---
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 托管模型默认路径。

## 执行记录

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