cmshoppe/docs/tasks/T-684.md

---
id: T-684
title: 明确自定义网关接口格式限制
phase: 5
deps: [T-680, T-681]
status: DONE
created: 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` 设置页网关来源说明。

## 验证

```bash
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`。