feat(ai): enforce direct image edit contract

docs/api.md

@@ -73,6 +73,8 @@ update_ai_model(name, **fields) -> None
 delete_ai_model(name) -> None                 # 至少各留一个 text+image；删到剩一禁用
 model_request_url(model) -> str              # url 为 /v1 或 /api/v1 base 时按 api_type 补 /chat/completions 或 /images/edits
 test_ai_model(name) -> dict                   # 「测试连接」：用 key/url/model 发最小请求 -> {ok, status?, error?}
+check_image_model_config(name) -> dict        # 图片模型本地校验，不发网络/计费请求 -> {ok, check_only, error?}
+is_image_edit_model(model) -> bool            # category=image 且 api_type=images_edits
 get_model(name) -> dict                        # 返回模型定义，含 api_key（调用方不得写日志）
 ```
 
@@ -330,7 +332,7 @@ fetch_cmhub_models(base_url, api_key, connect_timeout=10, read_timeout=30) -> li
 
 要点：
 
-- `backend=direct`：设置页「自定义网关」的客户端直连兼容路径；标题用 `default_text_model`、封面用 `default_image_model`（`appconfig.get_model` 取定义，含 url/key/api_type）。②在创建 worker 前按本轮生成内容校验所需模型；运行中使用冻结的内存模型快照，不重读 `ai_models.json`。它不支持图片理解或商品套图新建任务。
+- `backend=direct`：设置页「自定义网关」的客户端直连兼容路径；标题用 `default_text_model`，保留 `chat` / `auto`；封面用 `default_image_model`，只接受 `category=image` 且 `api_type=images_edits`（`appconfig.get_model` 取定义，含 url/key/api_type）。封面固定 `POST /v1/images/edits`，multipart 中按顺序重复 `image[]`，首项是主体图，固定 `n=1`，只读取 `data[].b64_json` 或 `data[].url`，仅允许 data URL/base64/HTTP(S) 下载结果。②在创建 worker 前按本轮生成内容校验所需模型；运行中使用冻结的内存模型快照，不重读 `ai_models.json`。历史 `chat` / `auto` 图片模型仍可保存和查看，但不可提交图片生成。它不支持图片理解或商品套图新建任务。
 - `backend=cmhub`：设置页「默认网关」及普通产品默认路径；标题调用 `POST /api/v1/generate/title`；②批量封面生成调用 `POST /api/v1/generate/image/tasks` + `GET /api/v1/generate/image/tasks/{task_id}`，模型字段使用 `ai.cmhub.title_alias/image_alias`，Key 来自 `data/config/cmhub.json`。商品套图中的「AI帮写」单独调用 `POST /api/v1/analyze/images`，只使用 `ai.cmhub.vision_alias`，不得回退或混用生文/生图别名；同一商品项目的原图在一条请求内联合理解，用户勾选状态不参与选图。`gen_cover()` 单独调用没有任务/DB 上下文，第一版保留旧同步 `POST /api/v1/generate/image` 兼容路径。
 - 标题提示词组装：`gen_title()` 的 direct 与 cmhub 路径共用标题 prompt 规则。若标题提示词包含 `{旧标题}`，生成前替换为该任务旧标题，不再自动追加旧标题块；若不包含 `{旧标题}`，保持旧行为自动追加“旧标题：...”块。两种情况都会追加“请只返回新标题，不要解释。”输出约束；其它 `{...}` 原样保留。
 - `fetch_cmhub_models()` 调 `GET /api/v1/models` 返回别名清单，供设置页动态下拉、商品套图 AI帮写和商品套图正式生成的付费前确认共用；Base URL 会先规整为网关根，HTTP 404 映射为 `not_found` 并提示检查 Base URL 或实例是否部署 `/api/v1/models`。GUI 只在进程内按规整网关地址和别名短期缓存公开模型元数据，不缓存 API Key，也不写入配置、SQLite、日志或导出。AI帮写仅在当前 `vision_alias` 命中 `operation_type=vision`、`requires_image=true`、`pricing_status=priced` 且有唯一无条件 `points_cost` 时显示预计扣点；正式套图同样只在当前 `image_alias` 命中唯一无条件的图片生图价格时显示单张和按最终 `specs` 计算的总价。其它情况只提示实际以网关返回为准，预估值不参与扣减或成功判定。
@@ -505,7 +507,7 @@ T-523 后 GUI 已从旧 `app/gui.py` 拆为 `app/gui/` 包：`__init__.py` 负
 设置当前要点（T-501）：
 
 - `SettingsTab` 使用居中内容区 + 适度左右留白布局，当前留白已从 T-506 初始实现缩短到约 40%；实现上使用最大内容宽度和自适应 margin，避免固定像素导致小屏挤压。各设置组默认响应式 3 列表单：短字段占 1 格，长字段（URL/API Key/路径）跨 2 格或 3 格，窄窗口降为 2 列/1 列。点击「保存设置」成功后，调用 `QMessageBox.information` 弹出“设置已保存”轻量提示框，同时保留状态栏提示。T-531 已完成：`save_app_settings()` 返回 bool，成功写 `data/config.json` + `data/config/cmhub.json` 后清 dirty，失败保留 dirty 并让调用方阻止离开。
-- `SettingsTab` 的生成网关配置：用 `gatewayDefaultButton` / `gatewayCustomButton` 分段选择器表达 `cmhub` / `direct` 来源，选择仅标记待保存，保存后才写 `ai.backend`。默认网关 Base URL 保存/刷新前规整为网关根，API Key 单独读写 `data/config/cmhub.json`，别名下拉来自 `fetch_cmhub_models()`；自定义网关复用 `data/config/ai_models.json` 的模型 CRUD 与文本/图片角色选择。两套配置并存，模型 CRUD 立即保存；`refresh_cmhub_models()` / `test_cmhub_connection()` 使用输入框实时值但不得自动保存。`settingsSaved` 通知主窗口刷新⑥能力状态；`is_dirty()` / `discard_unsaved_changes()` / `_suspend_dirty`（或等价机制）用于保存和放弃来源选择。
+- `SettingsTab` 的生成网关配置：用 `gatewayDefaultButton` / `gatewayCustomButton` 分段选择器表达 `cmhub` / `direct` 来源，选择仅标记待保存，保存后才写 `ai.backend`。默认网关 Base URL 保存/刷新前规整为网关根，API Key 单独读写 `data/config/cmhub.json`，别名下拉来自 `fetch_cmhub_models()`；自定义网关复用 `data/config/ai_models.json` 的模型 CRUD 与文本/图片角色选择。图片模型只展示「OpenAI 图片编辑接口」；历史不兼容配置保留并标示。图片模型的「检查图片配置」只做本地校验，不发送网络图片请求。两套配置并存，模型 CRUD 立即保存；`refresh_cmhub_models()` / `test_cmhub_connection()` 使用输入框实时值但不得自动保存。`settingsSaved` 通知主窗口刷新⑥能力状态；`is_dirty()` / `discard_unsaved_changes()` / `_suspend_dirty`（或等价机制）用于保存和放弃来源选择。
 - T-532 要求 `SettingsTab._on_cmhub_finished()` 从 worker payload 的 `balance` / user/account 字段提取 cmhub 账号身份，成功文案优先显示 `cmhub 账号「<账号名>」连接成功：...`；当前 `/balance` 结构兼容 `{ "user": "cmhub_user", "points_balance": 88, "account": { "username": "cmhub_user", "display_name": "主账号" } }`，显示名优先 `account.display_name`，再兜底 `account.username` / `user` / 顶层常见字段；账号字段缺失时保持 `cmhub 连接成功：...`。显示名必须脱敏处理邮箱，且不得把 API Key、token 或完整敏感响应写入 GUI、run log 或诊断日志。
 - `MainWindow` 已负责设置页离开守卫：切 Tab 与 `closeEvent` 发现 `SettingsTab.is_dirty()` 时弹保存/放弃/取消；保存成功后继续，保存失败或取消时回到设置。由于 `QTabWidget.currentChanged` 是切换后信号，需维护上一个 index，并用 `_reverting_tab_change` 或等价 guard 防止 `setCurrentIndex()` 递归。
 - 模型详情字段按 3 个组件一组排列：启用、类别、api_type、连接超时等短字段一格；服务商名、模型 ID 视宽度占一格或两格；网址、密钥跨整行或跨 2/3 列。

docs/cmhub-integration-design.md

@@ -15,6 +15,7 @@
 > **v3.6 修订（2026-07-08，T-564）**：cmhub 已新增异步生图任务接口，②批量生图改为 `POST /api/v1/generate/image/tasks` submit + `GET /api/v1/generate/image/tasks/{task_id}` poll；cmshopee 持久化 `tasks.image_task_id/image_task_key`，支持停止/超时/重启后续查，避免 900 秒同步长连接和读超时重复扣点。旧同步 `POST /api/v1/generate/image` 仅保留给单独 `gen_cover()` 兼容/回滚路径。
 > **v3.7 修订（2026-07-17，T-645）**：⑥「商品套图」的 AI帮写接入独立图片理解能力：使用 `vision_alias` 调 `POST /api/v1/analyze/images`，不复用标题接口或 `title_alias`。请求最多8张有序本地原图，单图不超过10MiB、总计不超过32MiB；读取等待120秒且读超时不自动重发，避免结果未确认时重复扣点。
 > **v3.8 修订（2026-07-20，T-677）**：T-529 的普通 UI 单来源收口有限放开为「默认网关 / 自定义网关」分段选择器，来源仅在保存设置后切换。自定义网关是客户端直连的过渡兼容路径，只覆盖②生文、生图；模型清单与默认网关配置并存。⑥商品套图和图片理解仍只允许默认网关新建请求，但此前已由默认网关接受、且同时带 `generation_source=cmhub`、`provider=cmhub` 与 `task_id` 的套图 job 可继续轮询、下载、保存，避免已扣点结果丢失。运行中的 worker 冻结来源、模型与密钥的内存快照，后续保存设置不影响本轮；密钥不写入 SQLite、日志或 UI。
+> **v3.9 修订（2026-07-20，T-678）**：自定义网关的图片生成固定采用 OpenAI 图片编辑契约：`POST /v1/images/edits`、multipart 有序重复 `image[]`、第一张为业务主体图、`n=1`，仅从 `data[].b64_json` 或 `data[].url` 读取结果。`category=image` 只有 `api_type=images_edits` 可发起生成；历史 `chat` / `auto` 图片模型保留可查看但在设置和生成预检中明确为不支持，绝不静默迁移。默认网关的 cmhub 请求、异步任务与宽松响应解析不受该收敛影响。⑤对图片模型只做本地配置检查，不发送可能计费的空图片请求；实际可用性通过②或后续⑥的正常生成确认验证。
 
 ## 1. 背景与目标
 

docs/routes.md

@@ -173,8 +173,8 @@
 - 设置页整体布局：内容区居中，左右留白已从 T-506 初始实现缩短到约 40%；实现上用最大内容宽度 + 自适应 margin，而不是写死窗口像素。所有设置组默认响应式 3 列表单：短字段占 1 格，URL/API Key/路径等长字段跨 2 格或 3 格；窄窗口自动降为 2 列/1 列。点击「保存设置」成功后，状态栏显示“设置已保存”，并弹出轻量提示框。T-531 已完成：保存成功会清除未保存标记；保存失败时保留未保存标记并阻止离开。
 - 生成网关（T-677）：用具备选中态的「默认网关 / 自定义网关」来源选择器替代历史「AI 后端」下拉。切换只改变待保存状态并立即切换面板，点击「保存设置」才写入 `ai.backend=cmhub/direct`；默认网关的 `data/config/cmhub.json` 与自定义模型的 `data/config/ai_models.json` 始终并存，模型新增、保存、删除仍立即写盘，不受来源待保存语义影响。
   - 默认网关面板展示 Base URL、API Key、生文/生图/图片理解别名、连接超时、批量生成前检查余额、刷新别名和测试连接/查余额；Base URL 输入框旁提示“只填网关根，如 https://host”，保存/刷新前规整掉 `/api`、`/api/v1` 或其它路径。测试连接成功优先显示 `账号「<账号名>」连接默认网关成功`，邮箱脱敏；没有账号信息时显示「默认网关连接成功」。Key 只本地明文保存、UI 打码显示，不进入日志或导出。
-  - 自定义网关复用既有模型列表、模型详情、默认文本模型、默认图像模型和模型连接测试；它仅兼容现有 direct 标题/封面请求，`chat/auto` 走聊天请求、`images_edits` 走图片编辑请求，不承诺自动探测或所有 OpenAI 兼容服务可用。说明行明确「图片理解与商品套图仅支持默认网关」。
-  - 允许保存不完整配置。②点击生成后、自定义 worker 创建前按本轮标题/封面选择校验所需模型的启用状态、类别、地址、模型 ID、API Key 和接口类型，失败提示去⑤补齐且不发请求、不改任务状态；自定义网关不显示默认网关余额，运行日志和状态栏说明“不计点数，费用由服务商收取”。
+  - 自定义网关复用既有模型列表、模型详情、默认文本模型与默认图像模型。文本模型保留 `chat` / `auto`；图片模型固定使用「OpenAI 图片编辑接口」（`images_edits`），②通过 `/v1/images/edits` 以有序重复 `image[]` 上传，第一张是商品主体图、每次只请求 `n=1` 输出。历史 `chat` / `auto` 图片模型不会被改写或隐藏，但会标示「图片接口不支持」，生成前会被拦截。图片响应只接受 `data[].b64_json` / `data[].url`，不适配聊天响应或服务商私有结构。说明行仍明确「图片理解与商品套图仅支持默认网关」。
+  - 图片模型按钮显示「检查图片配置」，只在本地检查接口类型、URL、模型 ID、密钥和超时，绝不对 `/images/edits` 发送无图片的测试请求；实际可用性必须以②或后续⑥的正常生成确认判断。允许保存不完整配置。②点击生成后、自定义 worker 创建前按本轮标题/封面选择校验所需模型的启用状态、类别、地址、模型 ID、API Key 和接口类型，失败提示去⑤补齐且不发请求、不改任务状态；自定义网关不显示默认网关余额，运行日志和状态栏说明“不计点数，费用由服务商收取”。
   - ⑥商品套图在自定义网关下禁用新建、重新生成和 AI帮写；但已有 `generation_source=cmhub`、`provider=cmhub` 且 `task_id` 非空的可恢复任务仍显示「继续查询已提交图片」，仅轮询、下载和保存，不新建 job 或重复扣点。若默认网关配置已不可用，提示恢复原默认网关配置。所有②/⑥ worker 开始时冻结来源、实际模型和密钥的仅内存快照，保存设置不会改变正在执行的一轮。
   - T-531 已完成：设置页任意可编辑控件变更都进入未保存状态，保存按钮旁显示“● 未保存更改”；切换到其它 Tab 或关闭窗口时弹出保存/放弃/取消。放弃会重新从本地配置文件回填控件，避免未保存的 URL/API Key 留在界面上；程序化回填、保存后重载和刷新别名填充下拉不会误触发未保存状态。
   - 自定义模型清单继续保存于 `data/config/ai_models.json`；在自定义网关面板中可维护并立即保存，切换回默认网关不会清除这些配置。

docs/tasks/T-678.md

@@ -3,7 +3,7 @@ id: T-678
 title: 自定义网关图片模型锁定 OpenAI 图片编辑接口并支持多图输入
 phase: 7
 deps: [T-677]
-status: TODO
+status: DONE
 created: 2026-07-20
 ---
 
@@ -88,4 +88,8 @@ git diff --check
 
 ## 执行记录
 
-（做完在这里写：改了什么文件、跑了什么验证命令及结果、官方接口契约核实来源与日期、遇到的阻塞和关键决策。）
+- 2026-07-20 完成：保留全局 `API_TYPES`，新增按图片类别的 OpenAI 图片编辑接口校验；存量 `chat` / `auto` 图片模型仍可载入、查看和保存，但设置页标示为不支持，②预检及 direct 生图会在发请求前用中文拦截。
+- direct 封面请求统一使用 `/v1/images/edits` multipart；`_image_edit_body()` 支持有序多图，重复 `image[]` 字段的第一张为主体图，并固定 `n=1`。响应解析收敛到 `data[].b64_json` / `data[].url`；cmhub 保持独立的宽松解析函数，默认网关行为未改变。
+- 图片模型按钮改为「检查图片配置」，worker 只调用本地字段、接口类型、URL 和超时检查，不发送空图片请求；文字模型继续走既有连接测试。
+- 文档同步：`docs/cmhub-integration-design.md`、`docs/routes.md`、`docs/api.md`。接口契约于 2026-07-20 参考 [OpenAI Images API 文档](https://platform.openai.com/docs/guides/image-generation)：图片编辑使用 multipart 图片输入，图片结果使用 base64 或 URL 表达；本项目固定采用 `image[]`、`n=1` 和标准 `data` 结果字段，不适配服务商私有响应。
+- 验证通过：`py -3.10 -m unittest tests.test_ai tests.test_appconfig tests.test_gui`（287 passed）；`py -3.10 -m unittest discover -s tests`（643 passed）；`py -3.10 -m ruff check app tests main.py`；`py -3.10 -m compileall app main.py`；`git diff --check`。本任务未改 CDP，未作线上蝦皮实跑。