132 lines
8.1 KiB
Markdown
132 lines
8.1 KiB
Markdown
# AI 开发入口
|
||
|
||
> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
|
||
|
||
## 一句话定位
|
||
|
||
蝦皮圈優化助手（代号 cmshopee）是一个 Windows 本地桌面自动化工具（PySide6，当前正式界面显示 6 个工作流 Tab），让运营管理多个 Shopee 卖家账号，并用 CDP 驱动 Chrome + AI 批量改商品标题、换商品封面；⑥「商品套图」用于按账号与商品生成本地电商套图，不自动上传蝦皮。
|
||
|
||
主流水线（工作流优先顺序）：
|
||
**① 导入采集 → ② AI生成 → ③ 更新蝦皮 → ④ 账号管理 → ⑤ 设置 → ⑥ 商品套图**。①～③是 Excel 批量更新主流水线；⑥是独立的本地商品套图工作区，复用 cmhub 托管生图与既有 `image_studio_*` 数据，不自动上传蝦皮。
|
||
|
||
目标闭环：④ 配账号并登录 → ① 导入 Excel（按“别名”列关联账号）、采集旧标题/旧封面并回写 → ② 用提示词 AI 生成新标题/新封面（不设逐条确认阶段）→ ③ 对已生成任务点击「开始更新」，弹窗确认后批量改标题+换封面并点「更新」提交 → 结果实时存 SQLite、批量回写原 Excel。
|
||
|
||
存储：T-538 后统一放在本地 `data/` 下：应用设置 `data/config.json` + cmhub Key `data/config/cmhub.json` + direct AI 模型清单 `data/config/ai_models.json`（含本地明文 AI Key，必须 gitignore）+ 业务数据 SQLite `data/cmshopee.db` + Excel 用 openpyxl + 图片存本地 `data/images/`。普通产品默认由 `data/config.json` + `data/config/cmhub.json` 配置 cmhub 网关。
|
||
|
||
## 必读顺序
|
||
|
||
每次开始写代码前，按这个顺序建立上下文：
|
||
|
||
1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
|
||
2. [`02-requirements.md`](02-requirements.md)：V1 要什么、怎么算达成。
|
||
3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型（Python + 自研 CDP + PySide6）。
|
||
4. [`04-architecture.md`](04-architecture.md)：模块职责、账号数据模型、**第七节 CDP 已验证事实（重点）**。
|
||
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
|
||
6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
|
||
7. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。
|
||
8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
|
||
|
||
如果仓库根目录有 `AGENTS.md`、`CLAUDE.md`，也必须先读，仓库级规则优先。
|
||
|
||
## 当前阶段
|
||
|
||
当前项目处于：**V0 单账号流程已验证，V1 多账号 + Excel + AI 的 6 Tab GUI 工作台持续收口中；⑥商品套图已接入**。
|
||
|
||
优先路径：
|
||
|
||
1. Phase 0：先建立正式代码包 `app/` 与根入口 `main.py`，再把已验证流程模块化到 `app/editor.py`，建立 `config.json` 与 SQLite。
|
||
2. Phase 1：账号绑定 user-data-dir、Chrome 启动、登录保活、PySide6 主窗口骨架。
|
||
3. Phase 2：导入 Excel、采集旧标题/旧封面并回写。
|
||
4. Phase 3：AI 生成新标题/新封面。
|
||
5. Phase 4：③ 批量确认后更新蝦皮并回写结果。
|
||
6. Phase 5：设置、敏感信息提示与日志脱敏、收尾。
|
||
|
||
## 领取任务规则
|
||
|
||
从 [`tasks/`](tasks/)（一任务一文件 `docs/tasks/T-<编号>.md`，约定见 [`tasks/README.md`](tasks/README.md)）领取任务时；[`06-tasks.md`](06-tasks.md) 已冻结为 T-000~T-549 历史归档、不再新增：
|
||
|
||
- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务文件。
|
||
- 开始前把该任务文件 frontmatter 的 `status` 改为 `DOING`。
|
||
- 本轮只完成这一个任务。
|
||
- 验收通过后把 `status` 改为 `DONE`。
|
||
- **完成后把执行记录写进该任务文件的 `## 执行记录` 一节**；**不再逐任务追加 [`../progress.md`](../progress.md)（已冻结归档）、不再逐任务覆盖 [`current-state.md`](current-state.md)**（那两个是每任务共享写入点，多 agent 并发会抢/覆盖）。
|
||
- 做完即停，汇报验证结果，等待下一步指令。
|
||
|
||
如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步。
|
||
[`current-state.md`](current-state.md) 只能展示按本规则计算出的当前快照，不能把多个无依赖任务改成“任选”；若两者冲突，以 [`06-tasks.md`](06-tasks.md) 的顺序和状态为准。
|
||
|
||
## 版本边界
|
||
|
||
**V0 已验证原型**：
|
||
|
||
- 单账号已登录 Chrome，通过 CDP 打开商品页、改标题、换封面。
|
||
- 原型脚本默认不提交线上，`UPDATE=1` 才点击「更新」。
|
||
- 作为 `app/editor.py` 的已验证参照，不再代表当前完整产品范围。
|
||
|
||
**V1 当前 coding 目标**：
|
||
|
||
- 当前正式界面为 6 Tab 工作台：① 导入采集 → ② AI生成 → ③ 更新蝦皮 → ④ 账号管理 → ⑤ 设置 → ⑥ 商品套图。旧 `ImageStudioTab` 只保留内部兼容，主界面入口由 `ProductSuiteTab` 替代；⑥只生成和管理本地图片，不自动提交线上。
|
||
- GUI 固定为 PySide6；后台采集/生成/更新用 `QObject` worker + `QThread` + signal 回传进度。
|
||
- 多账号管理；账号以独立 user-data-dir 隔离。③ 更新默认串行，提供「检查本轮更新」按钮；⑤ 可开启按账号并行和设置每批最大更新条数。
|
||
- Excel 导入/回写 + SQLite 实时落库 + 本地图片目录。
|
||
- AI 生成标题/封面，不设逐条确认阶段。
|
||
- ③ 点击「开始更新」后弹窗确认当前筛选范围和任务数量；用户确认后才批量提交线上。
|
||
|
||
**V1 不做**：
|
||
|
||
- 自动登录 / 自动填账号密码。
|
||
- 绕过验证码、风控、限流。
|
||
- 规则模板等 V2 后续能力。
|
||
- 商品数据批量爬取。
|
||
|
||
## 事实来源
|
||
|
||
项目事实只信：
|
||
|
||
- [`04-architecture.md`](04-architecture.md) 第七节：CDP 交互已验证结论（选择器、就绪判断、上传/拖拽方式）。
|
||
- [`04-architecture.md`](04-architecture.md) 5.1/5.1b/5.2/5.3：`data/config.json`、`data/config/ai_models.json`、SQLite schema、Excel 模板。
|
||
- 真实页面探查结果（用 `prototypes/inspect_images.py` / `prototypes/cookies.py` 实地确认）。
|
||
- 已验证脚本 `cdp.py`（T-000 后迁入 `app/cdp.py`）、`prototypes/demo.py`、`prototypes/set_title.py`、`prototypes/set_cover.py` 中跑通的逻辑。
|
||
|
||
不要把以下当事实来源：
|
||
|
||
- 旧脚本里可能已失效的选择器（Shopee 页面会变）。
|
||
- 未经实测的猜测。
|
||
- 临时探查脚本（`/tmp` 下的一次性脚本）。
|
||
|
||
## 常见任务该看哪里
|
||
|
||
做 GUI：
|
||
|
||
- 先看 `02-requirements.md` 的对应验收标准。
|
||
- 再看 `routes.md` 的窗口职责与操作流程。
|
||
- 最后看 `04-architecture.md` 的模块边界（GUI 不写业务逻辑）。
|
||
|
||
做 CDP / 浏览器操作：
|
||
|
||
- 先看 `04-architecture.md` 第七节已验证事实。
|
||
- 再看 `api.md` 的 `cdp` / `editor` 模块合约。
|
||
- 复用 `app/cdp.py`（迁移前参考根目录 `cdp.py`），不重写一套。
|
||
|
||
做账号配置 / Chrome 启动：
|
||
|
||
- 先看 `04-architecture.md` 第五节数据模型与 `api.md` 的 `config` / `chrome` 合约。
|
||
- Chrome 启动参数严格按第七节“Chrome 启动参数”一条。
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
python -m compileall app main.py # 语法检查（T-000 后）
|
||
python -m unittest discover -s tests # 纯逻辑单元测试（T-006 完成且 tests/ 存在后）
|
||
python prototypes/demo.py # 单账号闭环验证（分步，不提交）
|
||
```
|
||
|
||
说明：
|
||
|
||
- T-006 前若 `tests/` 不存在，不运行 `unittest discover`，也不把该命令失败视为当前任务失败；在回复里说明测试基座待 T-006 建立。
|
||
- T-006 完成后，纯逻辑改动必须补/更新 `tests/` 下的 unittest，并运行 `python -m unittest discover -s tests`。
|
||
- 改 CDP / editor 逻辑后：在测试商品（ITEM_ID 51100639510）上跑 `prototypes/demo.py` 实测。
|
||
- 改账号配置后：验证 SQLite 账号读写与 user-data-dir 创建；改应用设置后验证 `config.json` 读写。
|
||
- 改 DB / Excel / prompts / appconfig 纯逻辑后：T-006 前做可行的手动/临时验证并记录；T-006 后补或更新 `tests/` 下的 unittest。
|
||
- 如果命令当前不可运行（如 GUI 未建），在回复里如实说明。
|