3.8 KiB
3.8 KiB
id, title, phase, deps, status, created
| id | title | phase | deps | status | created | ||
|---|---|---|---|---|---|---|---|
| T-684 | 明确自定义网关接口格式限制 | 5 |
|
DONE | 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：自定义网关模型名称管理。
执行记录
- 将自定义来源单选项和内部兼容下拉标签统一改为“自定义网关（仅支持 OpenAI 格式）”；配置值仍为
direct，保存成功状态仍使用简洁的“自定义网关”。 - 增加仅在
direct选中时可见的说明“只有服务商明确说明‘支持 OpenAI 格式接口’时才选择此项。”，同时为单选项增加中文 tooltip；说明显隐不接入 dirty 信号。 - 更新设置路由说明及 GUI 回归，覆盖单选项文字、tooltip、默认/自定义来源说明显隐和既有切换保存行为。
- 验证通过：
py -3.10 -m unittest tests.test_gui（213 项）、py -3.10 -m unittest discover -s tests（654 项）、py -3.10 -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check。