From 3cd71b5285730dd20f4c4dccf4002c1ea0e2cb71 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Tue, 21 Jul 2026 09:47:30 +0800
Subject: [PATCH] docs(tasks): add custom gateway format notice task

---
 docs/tasks/T-684.md | 63 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/tasks/T-684.md

diff --git a/docs/tasks/T-684.md b/docs/tasks/T-684.md
new file mode 100644
index 0000000..7db8524
--- /dev/null
+++ b/docs/tasks/T-684.md
@@ -0,0 +1,63 @@
+---
+id: T-684
+title: 明确自定义网关接口格式限制
+phase: 5
+deps: [T-680, T-681]
+status: TODO
+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：自定义网关模型名称管理。
+
+## 执行记录
+
+- 待实现。