T-529 default to cmhub gateway
This commit is contained in:
chengma
@@ -6,8 +6,9 @@
|
||||
>
|
||||
> **v2 修订（2026-07-04，吸收对接文档）**：修正生图重试策略（非幂等，读超时不重发，避免重复扣点）；超时按分辨率细化到 600s 上限；余额直接用响应 `points_balance`；错误处理改为按 `code` 优先分支 + 未知 code 当不可重试，补 `content_blocked`；确认 `resolution`=`512/1K/2K/4K`（大写）、`aspect_ratio` 默认 `1:1`。
|
||||
> **v3 修订（2026-07-04，工程评审修正）**：补充既有配置迁移策略（缺 `backend` 先按 `direct` 处理，避免未配置 cmhub 时破坏现有生成）；固定 cmhub Key 文件为 `config/cmhub.json`；新增 `CMHubError` 结构化错误要求；明确 `points_balance/points_cost/call_id` 通过回调事件传播而不是改变 `gen_title`/`gen_cover` 返回值；要求 cmhub 分支用可区分 connect/read timeout 的 HTTP 调用；把 `image_url` 下载安全校验纳入 T-526 验收；T-525 顺延，Phase 7 成为当前业务优先任务。
|
||||
> **v3.1 修订（2026-07-04，实现前澄清）**：① 全新配置默认 backend 统一为 `direct`（cmhub 显式 opt-in），且 `backend=cmhub` 但未配置时须抛清晰"去⑤配置"错误而非崩溃（见 §4.1）；② 明确"返回值不变"≠"回调不变"——计费元数据须给 `gen_title`/`gen_cover` **新增可选事件回调参数**承载，是向后兼容加参（见 §4.2）。两点已同步 T-526 验收。
|
||||
> **v3.2 修订（2026-07-04，同步对接文档新增）**：cmhub 新增第 4 个接口 `GET /api/v1/models`（别名自助发现，见 §4.6），⑤设置别名由手填改为**动态下拉**（按 `operation_type` 分生文/生图、过滤 `unpriced`、展示单价、`requires_image` 提示），关闭原待确认 #1；仅 Base URL 仍待部署方提供。已同步 T-526（加 `fetch_cmhub_models` helper）与 T-527（别名下拉）。
|
||||
> **v3.1 修订（2026-07-04，实现前澄清）**：当时为保护既有直连流程，要求全新配置默认 backend 为 `direct`（cmhub 显式 opt-in），且 `backend=cmhub` 但未配置时须抛清晰"去⑤配置"错误而非崩溃（见 §4.1）；② 明确"返回值不变"≠"回调不变"——计费元数据须给 `gen_title`/`gen_cover` **新增可选事件回调参数**承载，是向后兼容加参（见 §4.2）。默认策略已被 v3.3/T-529 覆盖为普通产品默认 cmhub。
|
||||
> **v3.2 修订（2026-07-04，同步对接文档新增）**：cmhub 新增第 4 个接口 `GET /api/v1/models`（别名自助发现，见 §4.6），⑤设置别名由手填改为**动态下拉**（按 `operation_type` 分生文/生图、过滤 `unpriced`、展示单价、`requires_image` 提示），关闭原待确认 #1；仅 Base URL 仍待部署方提供。
|
||||
> **v3.3 修订（2026-07-04，产品收口）**：普通用户后续默认使用 `cmhub` 网关；⑤设置页去掉「AI 后端」label 和 direct/cmhub 下拉，直接展示 cmhub 网关配置。`direct` 代码和 `config/ai_models.json` 保留为内部兼容/手工回滚路径，但普通 UI 不提供切换入口；保存设置固定写 `ai.backend=cmhub`，允许先保存不完整 cmhub 配置，②生成时再提示去⑤补齐 Base URL/API Key/别名。已同步 T-529。
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
@@ -39,7 +40,7 @@
|
||||
|
||||
- **接缝最小化**：保持 `gen_title(...)` / `gen_cover(...)` 的**返回值与现有调用兼容**（`gen_title`→标题字符串、`gen_cover`→已存 JPEG 路径），允许向后兼容新增可选事件回调参数承载计费元数据，只改内层实现。这样 `generate_batch` 编排、并发、重试、DB 写入、诊断日志、JPEG 落盘、`images/<batch_id>/<slug>/...` 路径、T-520 封面开关**全部复用、零改动**；GUI `run_logs` 记录和余额展示放到 T-528。
|
||||
- **不碰高风险层**：`editor.py`/`cdp.py`/`chrome.py`/`accounts.py`/`excel.py`/`db.py`/`workers.py`，以及 ①采集/③更新/④账号全流程**完全不动**。这是本改动最重要的安全边界。
|
||||
- **适配器而非硬替换**：内层抽 `backend`（`cmhub` / `direct`），由配置选择。为保护既有用户，旧 `config.json` 缺 `ai.backend` 时先按 `direct` 迁移；用户在⑤设置明确切到 `cmhub` 并填好 Base URL / Key / 别名后才走网关。老 `ai_models.json` 不作废、测试易写、可灰度。
|
||||
- **产品默认 cmhub，direct 保留兼容**：内层仍抽 `backend`（`cmhub` / `direct`），但普通产品默认走 `cmhub`，⑤设置页不再展示后端切换。老 `ai_models.json` 和 direct 分支不删除，作为内部兼容/手工回滚路径；普通用户只配置 cmhub Base URL / Key / 别名。
|
||||
|
||||
## 4. 方案
|
||||
|
||||
@@ -49,7 +50,7 @@
|
||||
|
||||
```jsonc
|
||||
"ai": {
|
||||
"backend": "direct", // "cmhub" | "direct"；全新配置默认 direct，cmhub 为显式 opt-in
|
||||
"backend": "cmhub", // 普通产品默认 cmhub；direct 仅内部兼容/手工回滚
|
||||
"cmhub": {
|
||||
"base_url": "https://<cmhub>", // 网关根地址，请求时拼 /api/v1/...
|
||||
"title_alias": "title-standard", // 生文能力别名
|
||||
@@ -64,10 +65,7 @@
|
||||
|
||||
- **cmhub API Key 不进 `config.json`**（避免与其它设置混放、避免误提交）。固定存到 `config/cmhub.json`，文件 schema 第一版为 `{ "api_key": "sk_cmhub_xxx" }`；新增 `CMHUB_CONFIG_PATH`、`load_cmhub_config()`、`save_cmhub_config()`、`get_cmhub_api_key(masked=False)` 等 helper；`config/cmhub.json` 必须加入 `.gitignore`。沿用现有"本地明文保存但 gitignore + UI 打码 + 日志脱敏"纪律（T-503）。
|
||||
- **`ai_models.json` 去留**：`direct` 模式继续用；`cmhub` 模式不读它。文件保留但标记 legacy。
|
||||
- **默认 backend 的两条路径要分清（避免首启破坏）**：`appconfig` 里两条路径都必须落到"不破坏开箱"这一条统一规则——`backend` 默认 `direct`：
|
||||
- **加载既有 `config.json`** 缺 `ai.backend` 时，补 `direct`（保护老用户，其 `ai_models.json` 仍有效）。
|
||||
- **`DEFAULT_CONFIG` / `default_config()` 造全新配置** 同样写 `direct`，不写 `cmhub`——否则全新安装 `base_url`/Key 为空时首次生成直接报错。`cmhub` 一律由用户在 ⑤ 设置显式切换并填好 Base URL / Key / 别名后才生效。
|
||||
- 兜底：即使 `backend=cmhub` 但 `base_url`/Key 缺失，也必须抛**清晰的"请去⑤配置 cmhub"错误**（`CMHubError`/`AIError`），不得崩溃或静默直连。
|
||||
- **默认 backend 与配置不完整处理（T-529 后）**：`DEFAULT_CONFIG` / `default_config()` 造全新配置时写 `backend=cmhub`；⑤设置页隐藏 direct/cmhub 下拉并固定保存 `backend=cmhub`。允许先保存不完整 cmhub 配置，便于用户先保存其它路径/安全设置；②生成真正调用时如果 `base_url`/Key/别名缺失，必须抛**清晰的"请去⑤配置 cmhub"错误**（`CMHubError`/`AIError`），不得崩溃或静默回退 direct。显式手工配置 `backend=direct` 仍作为内部回滚路径保留，但普通 UI 不提供入口。
|
||||
|
||||
### 4.2 `gen_title` 改造（cmhub 分支）
|
||||
|
||||
@@ -156,7 +154,7 @@ cmhub 返回结构化 `{error:{code}}`。映射层**按 `code` 优先分支**（
|
||||
- 生文：`titles` 多条取首条；空 `titles`/空串 → `AIError`。
|
||||
- 生图：`image_url` → mock 下载字节 → `_save_jpeg` 落盘校验分辨率/质量；覆盖 scheme、内网/回环字符串地址、域名解析到内网 IP 的拒绝路径。
|
||||
- 错误码矩阵：402/401/403/400 不重试且原因正确；502/429/连接超时按 attempts 重试；生图读超时不重发；未知 code 不重试。
|
||||
- 配置：`backend=cmhub` 走 cmhub 分支、`direct` 走旧分支；旧配置缺 `backend` 时保持 direct；缺 `base_url`/Key 时明确报错。
|
||||
- 配置：`backend=cmhub` 走 cmhub 分支、显式 `direct` 走旧分支；T-529 后缺 `backend` 的配置按 `DEFAULT_CONFIG` 补为 cmhub；缺 `base_url`/Key/别名时明确报错。
|
||||
- **GUI**：⑤ cmhub 面板读写、测试连接 worker、别名下拉；② 生成在 `insufficient_points` 时的提示路径。
|
||||
- **回归**：`direct` 模式现有 `test_ai.py` 用例保持绿。
|
||||
- 验证命令沿用 `python -m unittest discover -s tests`。
|
||||
@@ -182,6 +180,7 @@ cmhub 返回结构化 `{error:{code}}`。映射层**按 `code` 优先分支**（
|
||||
- **第一步**：`app/ai.py` + `app/appconfig.py` 接入 cmhub backend（mock 联调），保留 direct。
|
||||
- **第二步**：⑤设置 UI cmhub 面板 + 测试连接/查余额。
|
||||
- **第三步**：② 计费错误提示（`insufficient_points` 引导充值）+ 可选余额展示。
|
||||
- **第四步（T-529）**：产品默认 cmhub，⑤去掉 AI 后端选择，保存固定 `backend=cmhub`。
|
||||
- 文档随每步同步。
|
||||
|
||||
> 当前已在 `docs/06-tasks.md` 落成 T-526~T-528；下一步按 T-526 开始代码实现，仍遵守 `docs/05-coding-rules.md` 验证清单。
|
||||
|
||||
Reference in New Issue
Block a user