feat: add cmhub AI backend

2026-07-04 15:13:15 +08:00
parent c8a5e9ada8
commit 1efb095767
11 changed files with 1061 additions and 43 deletions
@@ -27,7 +27,7 @@ GUI（PySide6 QTabWidget，5 Tab）
  └── ai         文本生成（提示词+旧标题→新标题）/ 图像生成（提示词+旧封面→新封面）
  |
  v
-Google Chrome（每账号独立 --user-data-dir + --remote-debugging-port） + AI 服务（外部）
+Google Chrome（每账号独立 --user-data-dir + --remote-debugging-port） + AI 服务（direct 外部模型或 cmhub 网关）
  |
  v
 Shopee 卖家中心页面 / 本地图片目录
@@ -38,7 +38,7 @@ Shopee 卖家中心页面 / 本地图片目录
 - GUI 入口：根目录 `main.py` 调用 `app/gui/` 包（PySide6 + `QMainWindow` + `QTabWidget`，5 Tab）；包入口 `app/gui/__init__.py` 提供 `main()` 并兼容 `from app import gui` / `from app.gui import MainWindow`；也支持 `python -m app`。
 - 核心模块统一放在正式代码包 `app/`：`appconfig.py`、`db.py`、`excel.py`、`config.py`、`accounts.py`、`chrome.py`、`editor.py`、`workers.py`、`ai.py`、`prompts.py`；CDP 底座迁入 `app/cdp.py`（当前根目录 `cdp.py` 为已验证来源）。
 - 已验证脚本（重构进模块）：`prototypes/demo.py`、`prototypes/set_title.py`、`prototypes/set_cover.py`、`prototypes/get_title.py`、`prototypes/cookies.py`、`prototypes/inspect_images.py`、`prototypes/grab.py`。
- 外部依赖：本机 Google Chrome；Shopee；AI 服务（文本+图像，服务商/模型由 `config/ai_models.json` 配置）；`openpyxl`。
+- 外部依赖：本机 Google Chrome；Shopee；AI 服务（文本+图像；direct 模式由 `config/ai_models.json` 配置，cmhub 模式由 `config.json` 的 `ai.cmhub` + `config/cmhub.json` 配置）；`openpyxl`。

 ## 二、流水线（核心）

@@ -71,12 +71,13 @@ imported  →  collected  →  generated  →  applied
 - `chrome`：拼接启动命令、启动、探测端口、（可选）生成快捷方式。
 - `cdp`：连接调试端口、找/开 tab、执行 JS、拖拽、注入文件。
 - `editor`：登录检测、**采集**（读旧标题、下载旧封面）、改标题、换封面、点更新。
- `ai`：`gen_title(prompt, old_title)`、`gen_cover(prompt, old_cover_path)`（外部 AI；模型清单配置；通用 HTTP）。
+- `ai`：`gen_title(prompt, old_title)`、`gen_cover(prompt, old_cover_path)`（外部 AI；支持 `direct` 模型清单和 `cmhub` 网关 backend；返回值保持标题字符串/本地 JPEG 路径）。

 **存储（同一事实只存一处）**

 - 应用配置（模型选择、生成参数、目录、Chrome 路径）→ `config.json`。
- AI 模型清单（url/模型/密钥/类型/连接超时）→ `config/ai_models.json`（API Key 本地明文保存，必须 gitignore，UI 打码显示）。
+- AI 模型清单（direct 模式 url/模型/密钥/类型/连接超时）→ `config/ai_models.json`（API Key 本地明文保存，必须 gitignore，UI 打码显示）。
+- cmhub 网关 Key → `config/cmhub.json`，schema `{ "api_key": "..." }`；`config.json` 只保存 Base URL、别名和超时，不保存 Key。
 - 业务数据（账号、任务、各阶段结果）→ SQLite `cmshopee.db`。
 - 图片（采集的旧封面、AI 生成的新封面）→ 本地图片目录（路径记在 DB）。
 - 提示词 → 标题提示词存单文件 `title_prompt.txt`；封面提示词存多模板 `prompts/cover/<名称>.txt`。
@@ -103,6 +104,14 @@ imported  →  collected  →  generated  →  applied
    "default_text_model": "GPT-5.5 文本",
    "default_image_model": "Nano Banana 2",
    "generate_cover": false,
+    "backend": "direct",
+    "cmhub": {
+      "base_url": "",
+      "title_alias": "",
+      "image_alias": "",
+      "connect_timeout": 10,
+      "check_balance_before_batch": false
+    },
    "title_concurrency": 4,
    "image_concurrency": 4,
    "retry": 2,
@@ -125,12 +134,14 @@ imported  →  collected  →  generated  →  applied

 `ai` 段只放**选择 + 全局生成参数**：

- `default_text_model` / `default_image_model`：引用 `ai_models.json` 里的模型名（标题用文本模型、封面用图像模型）。
+- `backend`：`direct` / `cmhub`。全新配置和旧配置缺字段时均为 `direct`，避免未配置 cmhub 时破坏既有直连生成；只有用户在⑤显式切换并配置完整后才走 cmhub。
+- `cmhub`：cmhub 网关配置，`base_url` 为网关根地址，`title_alias` / `image_alias` 为 `GET /api/v1/models` 发现的能力别名，`connect_timeout` 为连接超时；API Key 不在此处保存。
+- `default_text_model` / `default_image_model`：direct 模式下引用 `ai_models.json` 里的模型名（标题用文本模型、封面用图像模型）；cmhub 模式不读取这些模型定义。
 - `generate_cover`：②「开始生成」时是否调用图片模型生成新封面；默认 `false`，避免用户无意产生图片生成成本。该字段只控制 AI 生成阶段，不等同于 ③ 的 `allow_cover_update`。
 - `resolution`：当前分辨率，下拉 `512 / 1k / 2k / 4k`。
 - `resolution_timeouts`：分辨率 → **等待大模型返回超时(秒)** 的映射；用户选分辨率即自动套用，不单独填。
- 模型本身的定义（url/key/类型/连接超时…）在 `config/ai_models.json`，见 5.1b。
- 密钥不在 `config.json`：每个模型的 `api_key` 存于 `config/ai_models.json`，本地明文保存、保存/变更时弹窗提示、UI 打码、gitignore、不入日志/导出。
+- direct 模式模型本身的定义（url/key/类型/连接超时…）在 `config/ai_models.json`，见 5.1b。
+- 密钥不在 `config.json`：direct 模式每个模型的 `api_key` 存于 `config/ai_models.json`；cmhub 模式 API Key 存于 `config/cmhub.json`。两者均本地明文保存、保存/变更时弹窗提示、UI 打码、gitignore、不入日志/导出。

 `shopee_update` 段放**真实更新前的安全开关**：

@@ -147,7 +158,7 @@ imported  →  collected  →  generated  →  applied

 ### 5.1b AI 模型清单 `config/ai_models.json`

-模型定义清单（"有哪些模型"），与 `config.json` 的 `ai` 段（"选了哪个 + 全局参数"）职责分开。
+模型定义清单（"有哪些模型"），与 `config.json` 的 `ai` 段（"选了哪个 + 全局参数"）职责分开。该文件只用于 `backend=direct`；`backend=cmhub` 时生文/生图使用 cmhub 别名，不读取此文件。

 ```json
 {
@@ -177,6 +188,16 @@ imported  →  collected  →  generated  →  applied
 - `name` 唯一；`api_key` 本地明文保存、保存/变更时弹窗提示、打码显示。
 - 日志/状态/导出不得含密码或 API Key；结构化对象统一先过 `appconfig.sanitize_for_log()`，自由文本只允许在掌握明文值时用 `appconfig.redact_secrets()` 替换。

+### 5.1c cmhub Key `config/cmhub.json`
+
+```json
+{ "api_key": "sk_cmhub_xxx" }
+```
+
+- 文件必须 gitignore，不提交；UI 展示打码。
+- `appconfig.load_cmhub_config()` 缺文件时返回空 Key，不自动启用 cmhub。
+- `backend=cmhub` 但 Base URL、API Key 或别名缺失时，`app/ai.py` 抛 `CMHubError(code="cmhub_not_configured")`，提示去⑤设置配置，不静默回退 direct。
+
 ### 5.2 SQLite `cmshopee.db`

 ```sql
@@ -374,8 +395,8 @@ images/<batch_id>/<slug>/<task_id>_<item_id>_new.<ext>    # AI 生成的新封

 单个「开始生成」按钮，标题必生成，封面按本轮成本开关可选生成：

-1. **并发生成标题**：线程池大小 = `title_concurrency`，用 `default_text_model` 调 `gen_title(标题提示词, old_title)` → new_title。
-2. **若②勾选「生成封面图片（成本较高）」**：接着并发生成图片，线程池大小 = `image_concurrency`，用 `default_image_model` 调 `gen_cover(封面提示词, old_cover_path, resolution, jpg_quality)` → 新图存 `images/<batch_id>/<slug>/<task_id>_<item_id>_new.jpg`。
+1. **并发生成标题**：线程池大小 = `title_concurrency`，调 `gen_title(标题提示词, old_title)` → new_title。`backend=direct` 时使用 `default_text_model`；`backend=cmhub` 时调用 `POST /api/v1/generate/title` 并使用 `title_alias`。
+2. **若②勾选「生成封面图片（成本较高）」**：接着并发生成图片，线程池大小 = `image_concurrency`，调 `gen_cover(封面提示词, old_cover_path, resolution, jpg_quality)` → 新图存 `images/<batch_id>/<slug>/<task_id>_<item_id>_new.jpg`。`backend=direct` 时使用 `default_image_model`；`backend=cmhub` 时调用 `POST /api/v1/generate/image`，拿 `image_url` 后立即安全下载并转本地 JPEG。
   - 连接超时取该模型 `connect_timeout_seconds`；**返回超时取 `resolution_timeouts[resolution]`**（512→180/1k→240/2k→360/4k→600）。
 3. **若未勾选生成封面**：标题成功后立即写 `new_title`，`new_cover_path=NULL`，不渲染封面提示词、不调用 `gen_cover()`、不创建本地新封面文件。

@@ -462,7 +483,8 @@ cmshopee/
 ├── main.py                    # GUI 启动入口：from app.gui import main
 ├── shopee待处理任务模板.xlsx   # 标准空 Excel 模板，可提交；业务填写后的副本不提交
 ├── config.json               # 应用配置（模型选择/生成参数/路径，gitignore）
-├── config/ai_models.json     # AI 模型清单（含密钥，必须 gitignore）
+├── config/ai_models.json     # direct AI 模型清单（含密钥，必须 gitignore）
+├── config/cmhub.json         # cmhub API Key（含密钥，必须 gitignore）
 ├── cmshopee.db               # SQLite（账号/任务/结果，gitignore）
 ├── chrome_user_data_dir/     # 各账号 Chrome 配置（含登录态，gitignore）
 ├── images/                   # 旧封面/新封面本地图片（gitignore）
@@ -472,7 +494,7 @@ cmshopee/
                              # 逻辑待并入 app/editor.py 后清理；见 prototypes/README.md
 ```

-> `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` 含密钥/凭证/业务数据，必须 gitignore。`shopee待处理任务模板.xlsx` 是标准空模板，可以提交；运营填写后的 Excel 副本属于业务数据，不提交。
+> `config.json`、`config/ai_models.json`、`config/cmhub.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` 含配置/密钥/凭证/业务数据，必须 gitignore。`shopee待处理任务模板.xlsx` 是标准空模板，可以提交；运营填写后的 Excel 副本属于业务数据，不提交。

 ## 十、架构纪律