cmshoppe/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 05-coding-rules.md。

一句话定位

蝦皮圈優化助手（代号 cmshopee）是一个 Windows 本地桌面自动化工具（PySide6，5 Tab），让运营管理多个 Shopee 账号，并用 CDP 驱动 Chrome + AI 批量改商品标题、换商品封面。

5 Tab 流水线（工作流优先顺序）： ① 导入采集 → ② AI生成 → ③ 更新shopee → ④ 账号管理 → ⑤ 设置

目标闭环：④ 配账号并登录 → ① 导入 Excel（按“别名”列关联账号）、采集旧标题/旧封面并回写 → ② 用提示词 AI 生成新标题/新封面（不设逐条确认阶段）→ ③ 对已生成任务点击「开始更新」，弹窗确认后批量改标题+换封面并点「更新」提交 → 结果实时存 SQLite、批量回写原 Excel。

存储：应用设置 config.json + AI 模型清单 config/ai_models.json（含本地明文 AI Key，必须 gitignore）+ 业务数据 SQLite cmshopee.db + Excel 用 openpyxl + 图片存本地 images/。AI 服务商/模型由 config/ai_models.json 配置。

必读顺序

每次开始写代码前，按这个顺序建立上下文：

1. 01-vision.md：为什么做、为谁做、什么不做。
2. 02-requirements.md：V1 要什么、怎么算达成。
3. 03-tech-stack.md：既定技术选型（Python + 自研 CDP + PySide6）。
4. 04-architecture.md：模块职责、账号数据模型、第七节 CDP 已验证事实（重点）。
5. 05-coding-rules.md：写代码前必须遵守的规则。
6. 06-tasks.md：领取本轮唯一任务。
7. ../progress.md：历史执行记录、验证结果、阻塞点和关键决策。
8. current-state.md：当前代码现实、可运行命令、下一步任务。

如果仓库根目录有 AGENTS.md、CLAUDE.md，也必须先读，仓库级规则优先。

当前阶段

当前项目处于：V0 单账号流程已验证，正在实现 V1 多账号 + Excel + AI + 5 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：③ 批量确认后更新 Shopee 并回写结果。
6. Phase 5：设置、敏感信息提示与日志脱敏、收尾。

领取任务规则

从 06-tasks.md 领取任务时：

• 只领取第一个状态为 TODO 且依赖均为 DONE 的任务。
• 开始前把该任务状态改为 DOING。
• 本轮只完成这一个任务。
• 验收通过后把状态改为 DONE。
• 完成后把执行记录追加到 ../progress.md，覆盖更新 current-state.md。
• 做完即停，汇报验证结果，等待下一步指令。

如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步。 current-state.md 只能展示按本规则计算出的当前快照，不能把多个无依赖任务改成“任选”；若两者冲突，以 06-tasks.md 的顺序和状态为准。

版本边界

V0 已验证原型：

• 单账号已登录 Chrome，通过 CDP 打开商品页、改标题、换封面。
• 原型脚本默认不提交线上，UPDATE=1 才点击「更新」。
• 作为 app/editor.py 的已验证参照，不再代表当前完整产品范围。

V1 当前 coding 目标：

• 5 Tab 流水线：① 导入采集 → ② AI生成 → ③ 更新shopee → ④ 账号管理 → ⑤ 设置。
• GUI 固定为 PySide6；后台采集/生成/更新用 QObject worker + QThread + signal 回传进度。
• 多账号管理；账号以独立 user-data-dir 隔离。③ 更新默认串行，提供「检查本轮更新」按钮；⑤ 可开启按账号并行和设置每批最大更新条数。
• Excel 导入/回写 + SQLite 实时落库 + 本地图片目录。
• AI 生成标题/封面，不设逐条确认阶段。
• ③ 点击「开始更新」后弹窗确认当前筛选范围和任务数量；用户确认后才批量提交线上。

V1 不做：

• 自动登录 / 自动填账号密码。
• 绕过验证码、风控、限流。
• 规则模板等 V2 后续能力。
• 商品数据批量爬取。

事实来源

项目事实只信：

• 04-architecture.md 第七节：CDP 交互已验证结论（选择器、就绪判断、上传/拖拽方式）。
• 04-architecture.md 5.1/5.1b/5.2/5.3：config.json、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 启动参数”一条。

验证命令

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 未建），在回复里如实说明。