docs: add cmhub AI gateway integration design and sync docs
- 新增 docs/cmhub-integration-design.md（v3.2）：对接 cmhub 生文/生图/余额/别名发现接口的设计、迁移策略、错误与重试、待确认项 - docs/06-tasks.md：新增 Phase 7（T-526~T-528）AI 网关对接任务，补充别名动态下拉与 fetch_cmhub_models helper；相关文档索引与工程/打包任务同步 - 同步 README/03-tech-stack/current-state/packaging/troubleshooting/ux-review 文档 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chengma
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
6d4f60fcdb
commit
c8a5e9ada8
+13
-12
@@ -27,16 +27,16 @@
|
||||
|
||||
| 路径 | 状态 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `docs/` | 已有 | 本 harness coding 文档集合 |
|
||||
| `docs/` | 已有 | 本 harness coding 文档集合 |
|
||||
| `docs/packaging.md` | 已有 | T-524 产出：PyInstaller 打包命令、发布目录排除本地数据规则、首次运行数据位置和用户手动覆盖更新步骤 |
|
||||
| `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` 可运行占位入口 |
|
||||
| `requirements.txt` | 已有 | T-521 产出：锁定运行时直接依赖 PySide6 6.5.3、openpyxl 3.1.3、requests 2.31.0、websocket-client 1.6.1、Pillow 9.5.0；换机/CI 使用 `python -m pip install -r requirements.txt` |
|
||||
| `requirements.txt` | 已有 | T-521 产出：锁定运行时直接依赖 PySide6 6.5.3、openpyxl 3.1.3、requests 2.31.0、websocket-client 1.6.1、Pillow 9.5.0；换机/CI 使用 `python -m pip install -r requirements.txt` |
|
||||
| `requirements-build.txt` | 已有 | T-524 产出：打包环境依赖，先安装运行依赖再安装 PyInstaller 5.13.2；不作为运行时依赖文件 |
|
||||
| `.github/workflows/tests.yml` | 已有 | T-522 产出：push / pull_request 自动在 `windows-latest` + Python 3.11 安装 `requirements.txt`，设置 `QT_QPA_PLATFORM=offscreen`，运行 `python -m compileall app main.py` 与 `python -m unittest discover -s tests` |
|
||||
| `.github/workflows/tests.yml` | 已有 | T-522 产出：push / pull_request 自动在 `windows-latest` + Python 3.11 安装 `requirements.txt`，设置 `QT_QPA_PLATFORM=offscreen`，运行 `python -m compileall app main.py` 与 `python -m unittest discover -s tests` |
|
||||
| `cmshopee.spec` / `scripts/build_exe.ps1` | 已有 | T-524 产出：PyInstaller onedir 构建配置与发布目录校验脚本；`cmshopee.spec` 不声明本地数据 `datas`，脚本检查 `dist\\cmshopee` 不含配置、DB、图片、日志、Chrome 登录态或提示词 |
|
||||
| `app/gui/` | 已有 | T-523 产出：由旧 `app/gui.py` 拆分的 PySide6 GUI 包，包入口 `__init__.py` 继续兼容 `from app import gui` / `from app.gui import MainWindow`；`main_window.py` 放 MainWindow，`models.py` 放 3 个 TableModel，`widgets.py` 放色板/空状态/批次总览/helper，`workers.py` 放具体 GUI workers，`tabs/` 放 ①~⑤ Tab； T-104/T-105/T-106/T-202/T-202b/T-203/T-204/T-204b/T-205/T-206/T-207/T-302/T-302p/T-303/T-303b/T-401/T-402/T-403/T-404a/T-501/T-501b/T-501c/T-503/T-504/T-506/T-507/T-508/T-509/T-510/T-505/T-511/T-512/T-513/T-514/T-515/T-516/T-517/T-518/T-519/T-520 产出：PySide6 `QMainWindow` + 五 Tab；顶部 Tab 栏防误点样式；统一语义色板、①②③状态列前景色、③开始更新 warning 样式、①导入校验数字标红、④登录状态点、③Tab warning 小圆点、删除按钮 danger 样式、①②③首次空状态引导卡片和批次阶段进度总览；① 导入采集导入按钮、导入汇总栏、批次/店铺/商品ID/状态筛选、删除批次软删除按钮、`QTableView` 任务列表、未匹配筛选与略过标记、采集旧标题旧封面 worker（旧封面路径按批次/店铺/任务细分）、采集前账号就绪预检与④引导、采集完成自动回写与手动重试、采集运行日志视图；② AI生成左右布局、提示词管理、批次/店铺/商品ID/状态筛选栏、任务列表、新标题列本地编辑、开始生成/停止/标题与图片双进度条、双击新旧封面预览、用户可读自动滚动AI生成运行日志、重置生成结果与 `GenerateWorker`；③ 更新shopee批次/店铺/商品ID/状态筛选栏、任务列表、开始更新主按钮、重置更新状态右键菜单、Shopee 更新安全拦截与「前往设置」跳转、「检查本轮更新」按钮、开始更新确认弹窗、`ApplyWorker` 检查/分批串行/按账号并行、账号与端口预检、运行日志、逐条 `set_applied`、自动回写结果到 Excel、结束汇总弹窗与手动回写重试；④ 账号管理表格、账号弹窗、密码本地明文保存提示、启动登录、检测登录、快捷方式；⑤ 设置 AI 模型下拉、新增/删除、详情编辑、密钥打码与本地明文保存提示、测试连接 worker、默认角色下拉、生成参数、路径端口配置、三列 Shopee 更新安全与执行模式设置，高频安全/执行模式分区前置、基础设施分区后置，`test_item_id`/`dry_run` 兼容字段无用户入口且普通更新不再阻断正式更新；②封面模板「另存为/重命名/删除」低频操作已收敛进「模板操作」菜单；②AI生成底部已增加标题/图片双进度条，运行日志已改为用户可读、自动滚动、脱敏的长任务日志，且②本轮「生成封面图片（成本较高）」开关默认关闭并持久化到 `ai.generate_cover`，关闭时只生成标题并进入可更新状态 |
|
||||
| `app/workers.py` | 已有 | T-104b 产出：`BaseWorker` + 通用 signals + 取消标记 + `run_worker()` QThread 包装 |
|
||||
@@ -69,7 +69,7 @@
|
||||
任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史记录见 [`../progress.md`](../progress.md)。
|
||||
|
||||
- 已完成：T-000（正式代码包结构）、T-001（`app/editor.py` 模块化）、T-002（`app/appconfig.py` + `config.json`）、T-003（SQLite 建表）、T-004（本地数据 gitignore）、T-005（AI 模型清单后端）、T-006（单元测试基座）、T-101（账号 slug/user-data-dir）、T-102（Chrome 启动器）、T-103（登录保活与检测）、T-103b（登录检测补充识别 Shopee accounts 登录页）、T-104（PySide6 五 Tab 主窗口骨架）、T-104b（PySide6 worker 基座）、T-105（Tab④ 账号管理）、T-106（账号快捷方式）、T-201（Excel 导入：解析多文件输入列入库）、T-202（Tab① 任务列表 + 导入按钮 + 别名匹配标记）、T-202b（Tab① 导入汇总栏）、T-203（采集旧标题+旧封面）、T-204（回写旧字段到原 Excel）、T-204b（采集完成自动回写旧字段）、T-205（首次未配账号 / Chrome 未启动 / 未登录引导保护）、T-205b（采集后关闭自动新建商品页 tab）、T-206（Tab① 删除指定批次软删除）、T-301（AI 生成接口）、T-302（Tab② 左右布局与任务列表）、T-302p（提示词管理）、T-303（Tab② 开始生成 + 停止 + 进度）、T-303b（②/③ 商品ID筛选）、T-401（Tab③ 更新列表筛选 + 开始更新确认弹窗）、T-402（Tab③ 确认后串行更新）、T-403（Tab③ 结果回写与结束汇总）、T-501（Tab⑤ AI 模型管理 UI）、T-501b（Tab⑤ 角色与生成参数）、T-501c（Tab⑤ Shopee 更新安全开关）、T-502（换封面删第一张再上传）、T-503（敏感信息本地明文保存提示与日志脱敏）、T-504（多账号并行 / dry-run / 运行日志）、T-207（①采集诊断日志）、② AI生成图片失败诊断日志补丁、T-404a（②/③ 选中记录重置）、T-404（真实 Shopee 单条更新冒烟验收）、T-506（正式使用批量更新体验）、T-507（正式批量更新：移除普通流程测试商品 ID 限制）、T-508（③ 更新shopee生产化操作区）、T-509（② 新标题人工微调）、T-510（③ 检查本轮更新文案统一）、T-505（全流程诊断日志扩展）、T-511（语义色板 + ①②③任务状态列上色）、T-512（③高风险按钮上色 + ①导入校验数字标红）、T-513（登录点 / ③Tab危险标识 / 破坏性按钮上色）、T-514（①②③ 首次空状态引导卡片）、T-515（批次阶段进度总览）、T-516（①筛选对齐②③）、T-517（⑤设置分区 + 清理兼容字段）、T-518（②左栏提示词区组件密度优化）、T-519（②AI生成长任务进度条 + 用户可读滚动日志）、T-520（②AI生成封面可选生成开关）、T-521（依赖清单：锁版本 requirements）、T-522（CI：自动跑语法 + 单元 / GUI 测试）、T-523（拆分 `app/gui.py` 为 `app/gui/` 包）、T-523a（②/③ 新一轮运行前清空界面日志显示）、T-404b（商品详情页加载失败 toast 自动捕获）、T-524（PyInstaller 打包为免安装 exe）。
|
||||
- 下一个可领取任务：T-525（引入 ruff lint + format + 可选 pre-commit）。
|
||||
- 下一个可领取任务：T-526（`app/ai.py` + `appconfig` 接入 cmhub backend）；T-525 ruff 顺延到 cmhub 对接后。
|
||||
|
||||
## 当前已知限制
|
||||
|
||||
@@ -88,14 +88,15 @@
|
||||
- T-516 已完成：①导入采集补齐店铺、商品ID、状态筛选，筛选栏与②③对齐；当前筛选结果用于①表格显示和「采集旧标题/旧封面」作用范围，导入汇总栏、批次进度总览和未匹配数量仍按当前批次全量任务统计；未匹配按钮继续在当前筛选结果内筛出未匹配任务。
|
||||
- T-517 已完成：⑤设置页将「Shopee 更新安全 / 执行模式」前置为独立分区，将「基础设施（路径与端口）」后置；`test_item_id`、`dry_run` 不再有用户可操作控件，保存设置仍保留 `test_item_id` 兼容字段并固定 `dry_run=false`，③「检查本轮更新」语义不变。
|
||||
- T-518 已完成：②AI生成左栏保留模板选择、编辑内容、新建/保存等高频入口，把封面模板「另存为 / 重命名 / 删除」收敛进②本页「模板操作」菜单；动作仍调用原有保存/重命名/删除方法，删除二次确认、错误处理和 prompts 文件结构不变，不涉及 AI/Shopee/CDP。
|
||||
- T-519 已完成：②AI生成底部增加标题/图片两条独立进度条，现有「AI生成运行日志」改为用户可读、自动滚动、脱敏的长任务日志；日志显示本轮开始、标题/图片开始与成功、商品ID/店铺、调用失败重试、失败、停止请求和完成汇总，不显示 API Key、密码、Cookie、token、完整请求体、base64 图片或超长 prompt，不改变 AI/DB/Excel/Shopee/CDP 核心流程。
|
||||
- T-519 已完成：②AI生成底部增加标题/图片两条独立进度条，现有「AI生成运行日志」改为用户可读、自动滚动、脱敏的长任务日志；日志显示本轮开始、标题/图片开始与成功、商品ID/店铺、调用失败重试、失败、停止请求和完成汇总，不显示 API Key、密码、Cookie、token、完整请求体、base64 图片或超长 prompt，不改变 AI/DB/Excel/Shopee/CDP 核心流程。
|
||||
- T-520 已完成：②AI生成页增加「生成封面图片（成本较高）」开关，默认关闭以避免无意产生图片模型成本；关闭时标题生成成功即可写库进入 generated，`new_cover_path=NULL`，③只更新标题且不受「允许更新封面」阻断；开启时保持标题后图片两段生成流程。未改 DB schema、AI HTTP 协议、Excel、Shopee/CDP 更新流程。
|
||||
- T-521 已完成：根目录新增 `requirements.txt` 并锁定当前运行依赖版本；`docs/03-tech-stack.md` 和 `docs/README.md` 已改为 `python -m pip install -r requirements.txt` 安装；未新增运行时依赖、未改业务代码。
|
||||
- T-522 已完成：新增 `.github/workflows/tests.yml`，在 push / pull_request 上用 Windows + Python 3.11 安装 `requirements.txt`，设置 `QT_QPA_PLATFORM=offscreen`，自动运行语法检查和全量单元/GUI 测试；CI 不连接真实 Shopee 或真实 AI。
|
||||
- T-523 已完成：旧 `app/gui.py` 已拆为 `app/gui/` 包，公开导入路径保持兼容；本轮为纯结构重构，未改 Shopee/CDP、AI、DB、Excel 行为。
|
||||
- T-523a 已完成：②点击「开始生成」、③点击「检查本轮更新」或「开始更新」时，先清空对应界面的旧日志显示并写入本轮开始摘要；运行中只追加本轮日志。历史 `run_logs/run_log_events` 和本地 `logs/` 不删除、不自动混入当前运行界面。
|
||||
- T-404b 已完成：`open_product()` 在导航商品详情页前后安装 toast 捕获，等待详情页关键元素超时时会读取最近 `.eds-toasts`/toast/message 节点及页面缓存，把明确商品失效/商品不存在/无权限类 toast 上浮为 `商品失效：<原始toast>`；如果失败发生在 `open_product()` 内部，本轮自动新建的失败 tab 会关闭，复用用户已有 tab 不关闭；①列表“阶段”列只在这类明确失效错误时显示“商品失效”，底层仍保持 `stage=imported/status=failed`，其他打开失败仍显示“失败”。
|
||||
- T-524 已完成：新增 PyInstaller onedir 打包配置、构建脚本和发布目录校验；打包版启动时工作目录切到 `cmshopee.exe` 所在目录，首次运行在 exe 同级生成/使用本地配置、DB、图片、日志、登录态和提示词；发布包不内置这些本地数据，用户后续更新采用关闭程序后覆盖程序文件、保留本地数据的方式。
|
||||
- T-404b 已完成：`open_product()` 在导航商品详情页前后安装 toast 捕获，等待详情页关键元素超时时会读取最近 `.eds-toasts`/toast/message 节点及页面缓存，把明确商品失效/商品不存在/无权限类 toast 上浮为 `商品失效：<原始toast>`；如果失败发生在 `open_product()` 内部，本轮自动新建的失败 tab 会关闭，复用用户已有 tab 不关闭；①列表“阶段”列只在这类明确失效错误时显示“商品失效”，底层仍保持 `stage=imported/status=failed`，其他打开失败仍显示“失败”。
|
||||
- T-524 已完成：新增 PyInstaller onedir 打包配置、构建脚本和发布目录校验；打包版启动时工作目录切到 `cmshopee.exe` 所在目录，首次运行在 exe 同级生成/使用本地配置、DB、图片、日志、登录态和提示词；发布包不内置这些本地数据，用户后续更新采用关闭程序后覆盖程序文件、保留本地数据的方式。
|
||||
- Phase 7 cmhub 网关对接已补设计与任务定义：T-526 先接 `app/ai.py`/`appconfig` backend，T-527 做⑤设置面板，T-528 做②计费错误提示与余额展示；T-525 ruff 因业务优先级顺延。
|
||||
|
||||
- T-301/T-303 已完成通用 HTTP AI 接口、批量生成编排和 GUI 接入 mock 单测；真实 AI 生成还需要在 `config/ai_models.json` 填入可用 url/model/api_key 后做一次成本可控的小样本实测；URL 可填完整 endpoint 或 OpenAI-compatible base URL。
|
||||
- 本地 `config/ai_models.json` 若由旧版本或手工维护，可能缺少 `category`；启动报 “AI 模型 category 必须是 text 或 image” 时，按 [`troubleshooting.md`](troubleshooting.md) 只补 `category` / `enabled` 等非密钥字段，保留 API Key，且不要提交该文件。
|
||||
@@ -107,10 +108,10 @@
|
||||
|
||||
```bash
|
||||
# 安装锁定依赖（T-521 后）
|
||||
python -m pip install -r requirements.txt
|
||||
|
||||
# 安装打包依赖并构建免安装 exe（T-524 后）
|
||||
python -m pip install -r requirements-build.txt
|
||||
python -m pip install -r requirements.txt
|
||||
|
||||
# 安装打包依赖并构建免安装 exe（T-524 后）
|
||||
python -m pip install -r requirements-build.txt
|
||||
powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
|
||||
|
||||
# 语法检查（T-000 后；本机优先用 py -3）
|
||||
@@ -178,4 +179,4 @@ set UPDATE=1 && python prototypes/demo.py
|
||||
|
||||
- 新建 `config/chrome/editor/gui/workers` 或改 CDP 选择器后，更新本文与 `04-architecture.md`。
|
||||
- 任务状态变化同步 [`06-tasks.md`](06-tasks.md)；执行记录追加 [`../progress.md`](../progress.md)。
|
||||
- 本文只保留当前快照，不保留完整历史。
|
||||
- 本文只保留当前快照，不保留完整历史。
|
||||
|
||||
Reference in New Issue
Block a user