docs(tasks): decouple suite ai writing gateway

docs/tasks/T-695.md

@@ -0,0 +1,73 @@
+---
+id: T-695
+title: 商品套图AI帮写与生图网关解耦
+phase: 7
+deps: [T-679b, T-694]
+status: TODO
+created: 2026-07-23
+---
+
+## 问题 / 背景
+
+商品套图当前把“生成套图使用的网关”和“AI帮写使用的图片理解服务”绑定在同一个 `ai.backend` 上。用户选择自定义网关生成套图后，即使 cmhub Base URL、API Key 和 `vision_alias` 都已配置，`_apply_running_state()` 仍会把“AI帮写”按钮禁用并提示仅支持默认网关。
+
+该限制同时存在于三层：
+
+- GUI `start_ai_write()` 通过 `_require_default_gateway()` 拒绝当前 `backend=direct`。
+- `ProductSuiteAiWriteWorker.execute()` 再次检查 backend 并拒绝执行。
+- `ai.analyze_product_images()` 作为专用 cmhub 图片理解函数，仍根据全局 backend 拒绝 direct 配置。
+
+这不是能力冲突：自定义网关只负责套图生图，AI帮写本来就固定调用 cmhub `vision_alias` 的图片理解接口。二者可以同时保留各自配置并独立运行，不应要求用户为了使用AI帮写临时切换生图网关。
+
+## 方案
+
+### 1. 拆分能力判定
+
+- “生成套图”继续按已保存的 `ai.backend` 选择默认 cmhub 异步生图或自定义 OpenAI 格式同步生图，现有模型校验、确认、计费文案和 job 来源不变。
+- “AI帮写”不再读取当前生图 backend 作为准入条件；始终使用 cmhub 图片理解能力，并独立检查：规范化 Base URL 非空、本地 cmhub API Key 非空、`vision_alias` 非空。
+- 配置完整只代表按钮可用，不在界面刷新时发网络请求；模型目录、预计扣点和服务可达性仍在用户点击后由现有后台 worker 检查。
+- 缺少任一配置时按钮禁用，tooltip 使用中文说明“请到⑤设置配置默认网关的地址、API Key 和图片理解模型”；点击入口和 worker 仍需重复执行配置预检，不能只依赖按钮状态。
+
+### 2. 三层代码解耦
+
+- `ProductSuiteTab._apply_running_state()` 的 AI帮写启用条件改为“cmhub 图片理解配置完整 + 未在AI帮写 + 未在套图生成”，不再要求 `_is_default_gateway()`。
+- `start_ai_write()` 移除 `_require_default_gateway()`，改为专用 cmhub 图片理解配置检查；订阅预检、原图筛选、确认弹窗、模型目录扣点查询、取消和结果保存保持不变。
+- `ProductSuiteAiWriteWorker` 保留 `freeze_runtime_config(... include_cmhub=True, include_direct_models=False)`，移除全局 backend 拒绝；worker 快照仍只包含本轮需要的 cmhub 配置，不读取或调用自定义生图模型。
+- `ai.analyze_product_images()` 移除对全局 backend 的判断，直接通过 `_cmhub_runtime(..., "vision")` 校验并调用 cmhub；Base URL、Key 或别名缺失时继续返回中文安全错误，不回退自定义网关。
+
+### 3. 状态与文案
+
+- 自定义网关启用且 cmhub 图片理解配置完整时，“生成套图”和“AI帮写”可同时正常启用；AI帮写 tooltip 不再显示“仅支持默认网关”。
+- 自定义网关配置不完整只影响生成套图，不影响已配置完整的AI帮写；cmhub 图片理解配置不完整只影响AI帮写，不影响自定义网关生图。
+- AI帮写确认框继续说明理解图片数量和 cmhub 预计扣点；实际扣点、余额、超时、日志脱敏和会员预检口径不变。
+- 所有用户文案继续使用中文，不展示 API Key、完整接口路径、图片本地路径或上游原始错误。
+
+### 4. 回归测试
+
+- `backend=direct` 且自定义图片模型与 cmhub 图片理解均配置完整：生成套图按钮和AI帮写按钮都启用；点击AI帮写仍创建 `ProductSuiteAiWriteWorker` 并调用 cmhub 图片理解，不读取 direct 图片模型。
+- `backend=direct` 且 cmhub Base URL、Key 或 `vision_alias` 任一缺失：生成套图按自定义配置保持可用，AI帮写禁用并显示对应中文引导。
+- `backend=cmhub` 的现有AI帮写、模型目录预计扣点、前8张原图顺序、取消、成功保存和错误脱敏回归保持通过。
+- 核心 `analyze_product_images()` 在全局 backend 为 direct 时仍只请求 cmhub vision；配置缺失时失败且不调用网络。
+
+## 验收要点
+
+- 用户选择“自定义网关”生成套图后，只要 cmhub 图片理解配置完整，“AI帮写”按钮保持可用。
+- 点击AI帮写后实际请求仍使用 cmhub Base URL、API Key 和 `vision_alias`，不会调用自定义生图网关。
+- 两套能力的配置错误互不连带禁用，运行中锁定、会员预检和取消行为不变。
+- 自动验证：
+  - `py -3.10 -m unittest tests.test_product_suite_gui tests.test_workers tests.test_ai`
+  - `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帮写调用自定义网关，不新增AI帮写网关下拉、模型字段或独立 API Key。
+- 不改变默认/自定义生图 job、异步轮询、同步直连、重试、历史或导出逻辑。
+- 不改配置 schema；继续复用现有 `ai.cmhub` 与 `data/config/cmhub.json`，不复制或迁移密钥。
+- 不改订阅服务端最终授权、图片数量与大小限制、提示词结构或原图排序。
+
+## 执行记录
+
+- 待实现。