init：初始化项目

2026-04-07 15:21:27 +08:00
commit 1b494b6029
366 changed files with 11461 additions and 0 deletions
@@ -0,0 +1,107 @@
+# PopiArt 项目关系
+
+这份文档用于说明 `popiartcli`、`popiartServer`、`PopiNewAPI` 三个项目之间的职责边界、调用链路和联调顺序。
+
+同一份文档会分别放在三个仓库中，目的不是重复维护，而是让开发者在任何一个仓库里开始工作时，都能先看到完整上下文，避免把职责放错层。
+
+## 三个项目分别做什么
+
+| 项目 | 角色 | 应该负责 | 不应该负责 |
+|---|---|---|---|
+| `popiartcli` | 面向 coding agent 和创作者的统一 CLI 入口 | 登录、发现 skill、调用 skill、查看 jobs、拉取 artifacts、本地配置 | 不直接持有上游 provider key，不直接做模型路由，不直接做供应商计费 |
+| `popiartServer` | PopiArt 产品后端 | 用户鉴权、项目权限、skill 注册表聚合、skill 执行、job 引用管理、artifact read-through、路由决策、计费归因 | 不把供应商细节暴露给 CLI，不把 skillhub 直接耦合到 CLI，不重复实现 `PopiNewAPI` 已有的模型网关能力 |
+| `PopiNewAPI` | 模型网关和通道管理层 | 管理上游渠道和 key、代理模型请求、记录原始用量、提供模型层能力 | 不承载 PopiArt 的 skill 业务语义，不负责 CLI 交互，不负责产品级项目上下文 |
+
+## 标准调用链路
+
+```text
+coding agent / creator
+        ->
+    popiartcli
+        ->
+   popiartServer
+        ->
+    PopiNewAPI
+        ->
+model providers
+```
+
+这条链路里，`popiartcli` 是入口层，`popiartServer` 是产品编排层，`PopiNewAPI` 是模型网关层。
+
+## skillhub 放在哪一层
+
+`skillhub` 是公开 skill 注册表，不是模型执行层。
+
+推荐关系是：
+
+```text
+GitHub skillhub / skillhub.popi.art
+              ->
+        popiartServer 同步或聚合
+              ->
+          /skills API
+              ->
+           popiartcli
+```
+
+这样做有三个好处：
+
+1. CLI 不需要直接依赖 GitHub 或站点结构。
+2. skill 搜索、过滤、版本兼容可以统一放在后端处理。
+3. 以后从 GitHub 仓库切到 `skillhub.popi.art` 时，不需要改 CLI。
+
+## 授权、路由、计费分别在哪一层
+
+- 用户登录和项目权限：`popiartServer`
+- CLI 本地 key 持久化：`popiartcli`
+- 模型路由选择：`popiartServer`
+- 上游 provider key 管理：`PopiNewAPI`
+- 原始模型调用计量：`PopiNewAPI`
+- 面向 skill / project / user 的计费归因：`popiartServer`
+- artifact 文件存储与 task 内容代理：优先复用 `PopiNewAPI`，`popiartServer` 只做 read-through
+
+一个重要原则是：
+
+**真实 provider key 不进入 `popiartcli`。**
+
+CLI 只拿产品层 key；后端再用自己的方式调用 `PopiNewAPI`。
+
+## 当前测试应该怎么分阶段
+
+### 第一阶段：只验证产品协议
+
+先验证：
+
+- `auth`
+- `skills`
+- `run`
+- `jobs`
+- `artifacts`
+
+这一阶段可以完全不接真实模型，也不需要真实 provider key。
+
+### 第二阶段：接一个真实模型
+
+先只打通一个最小 skill，例如：
+
+- `popiskill-image-text2image-basic-v1`
+
+并让 `popiartServer` 将它映射到一个明确的 `route_key` 和一个真实可用模型。
+
+这一阶段才需要在 `PopiNewAPI` 中放可用渠道和 key。
+
+### 第三阶段：扩展 skill 与路由
+
+在文生图跑通后，再逐步加入：
+
+- 图生图
+- 图生视频
+- 更多供应商和项目级路由覆盖
+
+## 什么时候改哪个仓库
+
+- 你在改命令体验、输出格式、配置逻辑：改 `popiartcli`
+- 你在改 skill 调度、项目权限、artifact 规则、计费归因：改 `popiartServer`
+- 你在改渠道、模型映射、供应商 key、原始模型代理：改 `PopiNewAPI`
+
+如果一个改动同时需要触达三层，先从边界文档开始，再改代码。