41 lines
2.2 KiB
Markdown
41 lines
2.2 KiB
Markdown
---
|
||
id: T-599
|
||
title: AI工场 BYOK OpenAI Provider 契约、白名单与套餐校验对齐
|
||
phase: 8
|
||
deps: [T-596]
|
||
status: TODO
|
||
created: 2026-07-11
|
||
---
|
||
|
||
## 问题 / 背景
|
||
|
||
BYOK 第一期开 OpenAI Provider 时，最大的风险不是 UI，而是绕过 cmhub 授权、把用户 Key 泄露到日志，或让客户端恢复任意 URL 直连。必须先和 cmhub 固化 Provider 白名单、设备授权、套餐校验、错误码和异步任务契约，再写客户端代码。
|
||
|
||
## 方案
|
||
|
||
- 核对 cmhub BYOK V1.5 API：device credential、product、provider、model_alias、task secret、submit/poll、download、错误码、零点数使用记录和幂等键。
|
||
- 第一阶段只允许 OpenAI Provider；允许的模型能力由服务端白名单提供，不允许客户端填写任意 URL 或任意模型名。
|
||
- 明确 OpenAI 模型档位：
|
||
- 文本/提示词辅助默认用 T-597 推荐的平衡档，允许高质量/省点档。
|
||
- 图像生成/编辑优先使用服务端白名单中的 GPT Image 2 等图像能力别名。
|
||
- 无有效套餐/设备授权时，服务端必须拒绝 submit；客户端只展示中文原因，不本地绕过。
|
||
- 明确 BYOK `points_cost=0` 的账本语义：不扣 cmhub 点数，但仍记录使用次数、provider、call_id/task_id 和“费用由模型服务商收取”。
|
||
|
||
## 验收要点
|
||
|
||
- 有版本化契约文档或接口样例，覆盖成功、无套餐、设备不匹配、Provider 禁用、模型不允许、Key 无效、内容被拒、上游失败、任务超时。
|
||
- 明确 Key 不出现在 request_payload、CallRecord 明文字段、队列日志、遥测、异常监控或导出文件。
|
||
- 明确 submit 之后的任务状态与 T-590/T-594 的 image_studio_jobs 生命周期兼容。
|
||
- 若 cmhub 契约缺失，任务转 `BLOCKED`，不进入 T-600/T-601。
|
||
- 本任务不写生产代码；可补文档和 mock 契约。验证至少运行 `git diff --check`。
|
||
|
||
## 边界（不改什么）
|
||
|
||
- 不实现 UI、不保存 Key、不发真实 OpenAI 请求。
|
||
- 不支持任意 Provider、任意 URL、客户端 direct 或同步长等待。
|
||
- 不改变 cmhub 托管模型默认路径。
|
||
|
||
## 执行记录
|
||
|
||
（完成后记录契约来源、白名单结论和是否解除后续实现阻塞。）
|