cmshoppe/docs/troubleshooting.md

常见问题排查

本文只记录可复用的本地排障步骤。涉及 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 时，弹出或输出：

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：

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，只补这些字段：

{
  "name": "示例文本模型",
  "category": "text",
  "enabled": true
}

{
  "name": "示例图片模型",
  "category": "image",
  "enabled": true
}

如果要用脚本批量修复，只按模型名或 api_type 推断 category，并保留原有 url、model、api_key、extra_body 等字段。示例：

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 本身：

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 仍被忽略：

git status --short --ignored config/ai_models.json

正常输出应包含：

!! config/ai_models.json

最后重新启动：

python main.py

⑤ 设置里测试连接提示 “HTTP 404”

现象

在⑤设置里填写文本大模型信息后，点击「测试连接」，结果显示：

HTTP 404

原因

HTTP 404 表示服务端已响应，但当前请求 URL 路径不存在。旧代码会把「网址」字段原样作为 POST 地址；如果只填 OpenAI-compatible base URL，例如：

https://api.vectorengine.ai/v1

程序会直接 POST 到 /v1，部分服务商会返回 404。当前代码已兼容 base URL：

• api_type=chat 或 auto：/v1、/api/v1 会自动补成 /chat/completions。
• api_type=images_edits：/v1、/api/v1 会自动补成 /images/edits。
• 已经填写完整 endpoint（如 /v1/chat/completions）时保持不变。

推荐修复

更新到包含该修复的代码后，保留当前配置即可；也可以手工把「网址」改成完整 endpoint：

https://api.vectorengine.ai/v1/chat/completions

如果仍然 404，优先检查服务商文档要求的 endpoint 路径和 api_type，不要把 config/ai_models.json 或 API Key 贴到日志、文档或聊天里。

非敏感检查

只输出非密钥字段确认 URL 形态：

python -c "import json; from urllib.parse import urlsplit,urlunsplit; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); [print({'name':m.get('name'),'category':m.get('category'),'api_type':m.get('api_type'),'url_without_query':urlunsplit((urlsplit(m.get('url','')).scheme,urlsplit(m.get('url','')).netloc,urlsplit(m.get('url','')).path,'','')),'has_api_key':bool(m.get('api_key'))}) for m in data.get('models', [])]"

AI生成：标题成功但图片生成失败，且看不到原因

当前代码会为 ② AI生成写两层日志：

• 页面右下「AI生成运行日志」显示最近一次 run_type=generate 的逐条事件，例如 phase=cover step=cover_request result=failed detail=...。
• 本地 logs/cmshopee.log 保存脱敏后的 traceback、任务 id、alias、item_id、phase 和 step，用于判断卡在模型配置、封面请求、图片解析、保存文件还是写库。

排查顺序：先看 ② 页面运行日志里的 phase / step / detail；如果只看到简短错误，再查看本地 logs/cmshopee.log。不要把 config/ai_models.json 或 API Key 发到聊天、文档或提交里。