diff --git a/docs/README.md b/docs/README.md index 9e21409..c59e3cc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ - [界面与流程结构](routes.md):GUI 窗口、操作流程、按钮职责(无前端路由,用 GUI 流程替代)。 - [AI工场端到端验收](ai-studio-e2e-checklist.md):⑥ AI工场 cmhub 托管主线的自动化覆盖、人工只读验收和发布检查。 - [AI工场托管模型评测与默认档位策略](ai-studio-model-evaluation.md):OpenAI / GPT 托管能力经 cmhub 别名落地前的评测样本、档位策略、上线门槛与运营用法。 +- [AI工场 BYOK 启动门禁记录](byok-startup-gate.md):自定义模型 / BYOK 开工前的授权、设备凭证、Provider 白名单、task secret 和接口契约检查记录。 - [当前实现状态](current-state.md):当前代码现实、可运行命令、下一步可做任务。 - [常见问题排查](troubleshooting.md):本地配置、启动报错、敏感文件修复等排障记录。 - [产品与 UI 评估](ux-review.md):以 PM + UI 设计视角评估主流程模块 / 组件合理性,含优化方案与优先级清单。 diff --git a/docs/byok-startup-gate.md b/docs/byok-startup-gate.md new file mode 100644 index 0000000..dd5ce5d --- /dev/null +++ b/docs/byok-startup-gate.md @@ -0,0 +1,57 @@ +# AI工场 BYOK 启动门禁记录 + +> 任务来源:T-596 +> 核验日期:2026-07-11 +> 结论:**暂不具备开工条件,T-596 标记 BLOCKED;T-599~T-602 不得开工。** + +## 证据来源 + +- Obsidian:`ila/项目文档/蝦皮圈優化助手/卡密设备绑定与套餐授权方案.md` + - 状态:评审修订中,第五节为当前权威口径,关键商业决策仍待确认。 +- Obsidian:`ila/项目文档/cmhub/cmhub-软件授权与设备凭证实施方案.md` + - 状态:方案草案,待落入 cmhub 仓库 `docs/` 后拆任务实施。 +- 本仓任务:T-597、T-598 已完成;T-586~T-595 已完成 AI工场 cmhub 托管主线。 + +## 门禁检查表 + +| 条件 | 当前状态 | 证据 / 说明 | 结论 | +| --- | --- | --- | --- | +| cmhub V1A 授权与设备凭证已实现 | 未满足 | cmhub 实施方案仍写明“方案草案,待落入 cmhub 仓库 docs 后拆任务实施” | 阻塞 | +| 产品专属设备凭证鉴权可用 | 未满足 | 方案建议新增 `DeviceCredential`、`key_type=device_credential` 和产品专属接口,但未提供已上线接口 | 阻塞 | +| 产品专属生成接口已版本化 | 未满足 | 建议路径为 `/api/v1/products/cmshopee/generate/...`,当前未见可联调 API 文档 | 阻塞 | +| BYOK Provider 白名单已冻结 | 未满足 | 方案只定义“第一版 Provider 白名单,不允许任意 URL”,未列出具体 Provider、模型能力、参数和域名 | 阻塞 | +| BYOK task secret 契约已冻结 | 未满足 | 方案要求 KMS/Fernet 加密 task secret、secret_id、TTL、终态清理,但未提供字段、接口和错误码 | 阻塞 | +| BYOK submit/poll 状态机兼容 AI工场 job | 未满足 | 原则上必须复用异步任务,但缺少请求/响应样例、状态映射和幂等字段 | 阻塞 | +| 零点数使用记录契约可用 | 未满足 | 方案要求 `points_cost=0` 和独立使用记录,但未提供账本字段或接口返回 | 阻塞 | +| 错误码可供 GUI 分支 | 部分满足 | 文档列出建议错误码,但不是已实现、版本化接口契约 | 阻塞 | +| 测试凭证 / mock 环境可用 | 未满足 | 当前会话没有 cmhub BYOK 测试环境、测试 device credential 或 mock server 文档 | 阻塞 | + +## 决策 + +T-596 不进入编码实现,标记 `BLOCKED`。依赖 T-596 的任务必须暂停: + +- T-599:BYOK OpenAI Provider 契约、白名单与套餐校验对齐 +- T-600:BYOK Key 本地 DPAPI 存储与设置 UI +- T-601:BYOK 异步 submit/poll 接入 `image_studio_jobs` +- T-602:BYOK 安全日志、零点数账本与端到端回归验收 + +原因:如果现在先做客户端 UI、DPAPI 保存或 submit/poll 适配,必然会猜接口字段,且可能恢复“客户端 direct / 同步长等待 / 绕过套餐设备授权”的错误路径。 + +## 解除阻塞需要的交付物 + +cmhub 侧 owner 需要先交付以下内容: + +1. cmhub 仓库内正式 docs:授权、设备凭证、产品专属生成、BYOK Provider 白名单和 BYOK task secret。 +2. 已实现或 mock 可测的接口: + - `POST /api/v1/licenses/activate` + - `GET /api/v1/licenses/me` + - `POST /api/v1/products/cmshopee/generate/title` + - `POST /api/v1/products/cmshopee/generate/image/tasks` + - `GET /api/v1/products/cmshopee/generate/image/tasks/{task_id}` +3. 结构化错误码、HTTP 状态、中文外围提示映射。 +4. OpenAI Provider 第一版白名单:允许的模型档位、图片编辑/生成能力、参数白名单、超时、最大图片大小。 +5. BYOK task secret 字段:`secret_id` 生命周期、加密方式、TTL、终态删除、reaper 行为、worker 解密边界。 +6. 零点数使用记录字段:provider、model_alias、task_id/call_id、耗时、状态、`points_cost=0`、费用由服务商收取的展示口径。 +7. 测试环境或 mock server、测试 device credential、无套餐/设备不匹配/Key 无效/Provider 禁用/任务超时等样例。 + +解除阻塞后,再从 T-599 开始,仍必须一任务一提交。 diff --git a/docs/tasks/T-596.md b/docs/tasks/T-596.md index 01a5284..8a3d130 100644 --- a/docs/tasks/T-596.md +++ b/docs/tasks/T-596.md @@ -3,7 +3,7 @@ id: T-596 title: AI工场自定义模型(BYOK)总设计与启动门禁 phase: 8 deps: [T-598] -status: TODO +status: BLOCKED created: 2026-07-11 --- @@ -52,4 +52,10 @@ BYOK 不能再做成一个大任务直接编码。它涉及设备授权、套餐 ## 执行记录 -TODO:领取时先核验 T-595/T-598 与 cmhub V1.5 授权、BYOK 异步契约;未满足则标记 BLOCKED,不编码。 +2026-07-11 核验并阻塞: + +- 已确认 T-595、T-597、T-598 完成,AI工场 cmhub 托管主线与托管模型档位口径已具备。 +- 已读取 Obsidian《卡密设备绑定与套餐授权方案》和《cmhub-软件授权与设备凭证实施方案》;两份文档当前仍为评审修订/方案草案,cmhub V1A 授权、设备凭证、产品专属生成接口、BYOK Provider 白名单、task secret、零点数账本和 mock/测试环境都未交付到可实现契约。 +- 新增 `docs/byok-startup-gate.md`,记录门禁检查表、阻塞原因、依赖任务暂停范围和解除阻塞交付物。 +- 决策:T-596 标记 `BLOCKED`;T-599~T-602 依赖 T-596,不得开工,避免猜字段或恢复客户端 direct / 同步长等待错误路径。 +- 验证:`git diff --check -- docs/byok-startup-gate.md docs/README.md docs/tasks/T-596.md` 通过。