cmshoppe/docs/tasks/T-684.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-684	明确自定义网关接口格式限制	5	T-680 T-681	TODO	2026-07-21

T-684 明确自定义网关接口格式限制

问题 / 背景

设置页的网关来源单选项仅显示“自定义网关”。普通用户可能误以为任意服务商网址和 API Key 都能接入，而当前实现只支持 OpenAI 格式的文本和图片编辑接口，配置不匹配时才在后续校验阶段失败，理解成本和排查成本较高。

“OpenAI 兼容”对非技术用户不够直观；需要在选择前明确“这是接口格式限制”，并告诉用户应向服务商确认什么。

方案

• 将设置页单选项“自定义网关”改为“自定义网关（仅支持 OpenAI 格式）”。内部配置值仍为 direct，不改变 ai.backend 字段、保存路径或网关选择逻辑。
• 在该单选项下新增一行低干扰的中文说明，仅当选中自定义网关时显示：只有服务商明确说明“支持 OpenAI 格式接口”时才选择此项。
• 为该单选项添加相同含义的 tooltip，方便窄窗口、键盘焦点和辅助说明场景读取。
• 说明仅表达当前既有能力边界：文本调用和 /v1/images/edits 图片编辑接口；不承诺支持任意 OpenAI 模型、服务商私有协议、聊天式图片返回或其它非兼容接口。
• 保持默认网关单选项位置、同一行布局、选择/保存/放弃未保存更改的行为不变；说明显示不应改变配置 dirty 状态。

验收要点

• 自定义网关单选项完整显示“自定义网关（仅支持 OpenAI 格式）”，默认网关文字不变。
• 选中自定义网关时显示中文说明和 tooltip；切回默认网关时说明隐藏。
• 单选项仍处于原有同行位置，窄窗口不裁切文字，键盘/鼠标选择仍正常。
• ai.backend 仍只保存 cmhub 或 direct，已有配置可正常加载、保存和放弃未保存更改。
• 不改变自定义网关模型字段、默认模型、API Key、请求协议、图片生成或商品套图调用。

测试与文档

• 更新 tests/test_gui.py：验证单选项文字、tooltip、说明在默认/自定义来源之间的显隐和后台值不变。
• 更新 docs/routes.md 设置页网关来源说明。

验证

py -3.10 -m unittest tests.test_gui
py -3.10 -m unittest discover -s tests
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check

边界（不改什么）

• 不新增自定义协议适配、模型目录、服务商检测、连接测试请求或自动降级。
• 不改变 ai.backend、data/config/ai_models.json、cmhub 配置、模型名称管理或默认模型引用。
• 不重排其它设置组件，不改 AI 请求、Chrome/CDP、采集、更新蝦皮或商品套图逻辑。

关联

• T-677：生成网关来源选择器与自定义模型配置。
• T-680：设置页同行网关来源单选框。
• T-681：自定义网关模型名称管理。

执行记录

• 待实现。