cmshoppe/docs/tasks/T-599.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-599	AI工场 BYOK OpenAI Provider 契约、白名单与套餐校验对齐	8	T-596	TODO	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 托管模型默认路径。

执行记录

（完成后记录契约来源、白名单结论和是否解除后续实现阻塞。）