docs: 记录AI模型category启动报错排查

- 新增 troubleshooting 文档，说明 category 缺失导致启动失败的原因 - 补充安全修复步骤，避免泄露或提交 config/ai_models.json 中的 API Key - 更新文档导航、技术栈、当前状态和进度记录
2026-06-29 10:37:27 +08:00
parent 0e0ed193b6
commit 3a79e34eab
5 changed files with 105 additions and 0 deletions
@@ -34,6 +34,7 @@
 - **多账号隔离用独立 user-data-dir，不用 Chrome profile**：profile 共享同一 user-data-dir/进程/调试端口，无法每账号独立 CDP 与并行；独立 user-data-dir 才契合自动化。详见 [架构 3.0](04-architecture.md)。
 - **快捷方式生成用 PowerShell（无额外依赖）**：用 `WScript.Shell.CreateShortcut` 生成 `.lnk`，不引入 `pywin32` 等依赖。
 - **AI 服务商不写死在代码里**：T-301 已采用 `config/ai_models.json` 的通用 HTTP 接入，当前支持 OpenAI-compatible chat JSON 与 images_edits multipart；具体服务商/模型/Key 由⑤设置维护。
+- **AI 模型 category 是硬约束**：`config/ai_models.json` 每个模型必须有 `category=text` 或 `category=image`；启动时报 “AI 模型 category 必须是 text 或 image” 时，按 [常见问题排查](troubleshooting.md) 修复本地配置，不删除或提交含 Key 的配置文件。
 - **敏感信息不加密但强提示与脱敏**：密码与 AI Key 只在本机 SQLite / `config/ai_models.json` 明文保存；保存/变更时弹窗提示，UI 打码，日志/导出必须脱敏，相关本地文件必须 gitignore。
 - **AI 产出无逐条审核**：生成的新标题/新封面经 ③ 批量确认后提交线上；无常驻提交开关，本地留档 + 回写 Excel 供追溯。
 - **T-504 更新执行增强**：③ 支持 dry-run 预览、运行日志和按账号并行；默认 dry-run 关闭、并行关闭，不引入新依赖。
@@ -21,6 +21,7 @@ cmshopee 是一个给**电商运营**使用的 Windows PySide6 桌面自动化
 - [模块 / CLI 合约](api.md)：本地模块接口、Chrome 启动参数、账号配置 schema。
 - [界面与流程结构](routes.md)：GUI 窗口、操作流程、按钮职责（无前端路由，用 GUI 流程替代）。
 - [当前实现状态](current-state.md)：当前代码现实、可运行命令、下一步可做任务。
+- [常见问题排查](troubleshooting.md)：本地配置、启动报错、敏感文件修复等排障记录。

 ## 任务 / 进度 / 当前状态

@@ -31,6 +31,7 @@
 | `app/cdp.py` | 已有 | CDP 底座：连接/找 tab/开 tab/关闭 target/执行 JS/拖拽；`CDP.close()` 只断开 WebSocket，`close_tab()` 才关闭浏览器页面 |
 | `prototypes/` | 已有 | 已验证原型/探查脚本（demo/set_title/set_cover/get_title/cookies/inspect_images/grab/1.py），保留作人工回归与探查参考；见 `prototypes/README.md` |
 | `chrome-remote-debug-lan.md` | 已有 | WSL→Windows CDP 转发排查记录 |
+| `docs/troubleshooting.md` | 已有 | 常见问题排查；已记录 `config/ai_models.json` 缺失 `category` 导致 GUI 启动报 “AI 模型 category 必须是 text 或 image” 的原因、修复和验证步骤 |
 | `app/__init__.py` / `app/__main__.py` / `main.py` | 已有 | 正式包与启动入口；`python main.py` / `python -m app` 可运行占位入口 |
 | `app/gui.py` | 已有 | T-104/T-105/T-106/T-202/T-202b/T-203/T-204/T-204b/T-205/T-302/T-302p/T-303/T-401/T-402/T-403/T-501/T-501b/T-501c/T-503/T-504 产出：PySide6 `QMainWindow` + 五 Tab；顶部 Tab 栏防误点样式；① 导入采集导入按钮、导入汇总栏、`QTableView` 任务列表、未匹配筛选与略过标记、采集旧标题旧封面 worker、采集前账号就绪预检与④引导、采集完成自动回写与手动重试；② AI生成左右布局、提示词管理、筛选栏、任务列表、开始生成/停止/进度、双击新旧封面预览与 `GenerateWorker`；③ 更新shopee筛选栏、任务列表、Shopee 更新安全拦截、开始更新确认弹窗、`ApplyWorker` 串行/dry-run/按账号并行、账号与端口预检、运行日志、逐条 `set_applied`、自动回写结果到 Excel、结束汇总弹窗与手动回写重试；④ 账号管理表格、账号弹窗、密码本地明文保存提示、启动登录、检测登录、快捷方式；⑤ 设置 AI 模型下拉、新增/删除、详情编辑、密钥打码与本地明文保存提示、测试连接 worker、默认角色下拉、生成参数、路径端口配置、Shopee 更新安全与执行模式设置 |
 | `app/workers.py` | 已有 | T-104b 产出：`BaseWorker` + 通用 signals + 取消标记 + `run_worker()` QThread 包装 |
@@ -68,6 +69,7 @@
 - ① 采集依赖对应账号 Chrome 已用专属 user-data-dir 和 CDP 端口启动并登录；T-205 已在采集前拦截未配置账号、Chrome 未启动、未登录，并引导去④账号管理，但不会无提示批量启动所有账号 Chrome。
 - T-501/T-501b/T-501c 已完成 `config/ai_models.json` 模型清单 UI，以及 `config.json` 里的标题/图片默认模型角色、并发、重试、分辨率、jpg 质量、路径/端口设置和 Shopee 更新安全开关。
 - T-301/T-303 已完成通用 HTTP AI 接口、批量生成编排和 GUI 接入 mock 单测；真实 AI 生成还需要在 `config/ai_models.json` 填入可用 url/model/api_key 后做一次成本可控的小样本实测。
+- 本地 `config/ai_models.json` 若由旧版本或手工维护，可能缺少 `category`；启动报 “AI 模型 category 必须是 text 或 image” 时，按 [`troubleshooting.md`](troubleshooting.md) 只补 `category` / `enabled` 等非密钥字段，保留 API Key，且不要提交该文件。
 - T-403/T-501c 已完成③更新结果回写、结束汇总与真实更新安全开关；真实 Shopee 更新冒烟仍未执行，下一步 T-404 只允许在测试商品范围内做单条验收，默认先只测标题更新，封面更新作为可选子项。
 - T-502 满 9 张封面删除流程已完成代码路径、mock 单测和真实 9 图商品不提交流程实测；删除第一张前必须已有本地旧封面备份（`old_cover_path` 存在且文件存在），缺失备份时拒绝删除线上图片。本轮实测只操作编辑页并关闭测试 tab，未点击「更新」保存线上。

@@ -0,0 +1,94 @@
+# 常见问题排查
+
+> 本文只记录可复用的本地排障步骤。涉及 `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` 时，默认它们是本机敏感或业务数据，必须保持 gitignore，不把真实密码、API Key、Cookie、token 写入文档、日志或提交。
+
+## 启动时报 “AI 模型 category 必须是 text 或 image”
+
+### 现象
+
+运行 `python main.py` / `python -m app` 启动 GUI 时，弹出或输出：
+
+```text
+AI 模型 category 必须是 text 或 image
+```
+
+### 原因
+
+`config/ai_models.json` 是本地 AI 模型清单，里面每个模型都必须有合法的 `category`：
+
+- `text`：标题生成模型，会出现在“标题大模型”下拉。
+- `image`：封面生成模型，会出现在“图片大模型”下拉。
+
+早期或手工维护过的 `config/ai_models.json` 可能缺少 `category`，或者填了中文、空值、旧字段，导致 `appconfig.load_ai_models_config()` 严格校验失败，GUI 启动被阻断。
+
+### 不要这样做
+
+- 不要删除 `config/ai_models.json` 来“重置”，否则会丢失本地明文 API Key 和模型配置。
+- 不要把 `config/ai_models.json` 提交到 git。
+- 不要把完整文件内容贴到聊天、文档或日志里；该文件含本地明文 API Key。
+
+### 推荐修复
+
+先只查看非敏感字段，确认哪些模型缺少 `category`：
+
+```powershell
+python -c "import json; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); [print({'index': i+1, 'name': m.get('name'), 'category': m.get('category'), 'api_type': m.get('api_type'), 'enabled': m.get('enabled'), 'has_api_key': bool(m.get('api_key'))}) for i,m in enumerate(data.get('models', []))]"
+```
+
+然后手工编辑 `config/ai_models.json`，只补这些字段：
+
+```json
+{
+  "name": "示例文本模型",
+  "category": "text",
+  "enabled": true
+}
+```
+
+```json
+{
+  "name": "示例图片模型",
+  "category": "image",
+  "enabled": true
+}
+```
+
+如果要用脚本批量修复，只按模型名或 `api_type` 推断 `category`，并保留原有 `url`、`model`、`api_key`、`extra_body` 等字段。示例：
+
+```powershell
+python -c "import json; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); mapping={'你的文本模型名':'text','你的图片模型名':'image'}; changed=False
+for m in data.get('models', []):
+    name=m.get('name')
+    if not m.get('category') and name in mapping:
+        m['category']=mapping[name]; changed=True
+    if m.get('enabled') is None:
+        m['enabled']=True; changed=True
+open(p,'w',encoding='utf-8').write(json.dumps(data,ensure_ascii=False,indent=2)+'\n')
+print('updated' if changed else 'unchanged')"
+```
+
+### 验证
+
+验证时只输出模型名、类别、是否启用、是否存在 Key，不输出 Key 本身：
+
+```powershell
+python -c "import os,sys; sys.path.insert(0, os.getcwd()); from app import appconfig; print([(m['name'], m['category'], m['enabled'], m['api_key_set']) for m in appconfig.list_ai_models()])"
+```
+
+确认 `config/ai_models.json` 仍被忽略：
+
+```powershell
+git status --short --ignored config/ai_models.json
+```
+
+正常输出应包含：
+
+```text
+!! config/ai_models.json
+```
+
+最后重新启动：
+
+```powershell
+python main.py
+```