2026-06-26 15:30:37 +08:00
|
|
|
|
# AGENTS.md
|
|
|
|
|
|
|
|
|
|
|
|
> Codex / 通用 AI coding agent 的仓库级入口。进入本仓库后，先读本文，再进入 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)。
|
|
|
|
|
|
|
|
|
|
|
|
## 项目定位
|
|
|
|
|
|
|
2026-07-07 09:52:51 +08:00
|
|
|
|
蝦皮圈優化助手（代号 cmshopee）是一个 **Windows 本地桌面自动化工具**：管理多个 Shopee 卖家账号，用 CDP 驱动 Chrome 自动改商品标题、换商品封面。当前单账号流程已验证，正在扩展多账号管理与 GUI。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
|
|
|
|
|
|
## 文档位置
|
|
|
|
|
|
|
|
|
|
|
|
- 项目文档集合在 [`docs/`](docs/)，导航见 [`docs/README.md`](docs/README.md)。
|
|
|
|
|
|
- 编程入口是 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)，它继续导航到愿景、需求、技术栈、架构、编码规则、任务看板。
|
|
|
|
|
|
- 执行历史流水在根目录 [`progress.md`](progress.md)；当前快照在 [`docs/current-state.md`](docs/current-state.md)。
|
|
|
|
|
|
|
|
|
|
|
|
## 必读顺序
|
|
|
|
|
|
|
|
|
|
|
|
每次开始工作前，按顺序读取：
|
|
|
|
|
|
|
|
|
|
|
|
1. 本文 `AGENTS.md`：仓库定位与规则。
|
|
|
|
|
|
2. [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：编程入口与流程。
|
2026-06-26 15:55:28 +08:00
|
|
|
|
3. [`docs/04-architecture.md`](docs/04-architecture.md)：尤其**第七节 CDP 已验证事实**。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
4. [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：硬性编码规则。
|
|
|
|
|
|
5. [`docs/06-tasks.md`](docs/06-tasks.md) + [`docs/current-state.md`](docs/current-state.md)：领取任务、了解现状。
|
|
|
|
|
|
6. 与当前任务相关的具体文档。
|
|
|
|
|
|
|
|
|
|
|
|
## 工作规则
|
|
|
|
|
|
|
2026-06-26 17:05:18 +08:00
|
|
|
|
- 正式代码统一放入 `app/` 包；迁移完成后复用 `app/cdp.py`，遵守架构第七节的选择器、就绪判断、上传/拖拽方式，不另起一套 CDP 交互。
|
2026-07-08 17:25:17 +08:00
|
|
|
|
- ①「导入采集」点击采集后可以为本轮匹配到的账号自动确保 Chrome 就绪：已打开则复用，未打开才启动；只检测登录态，不自动登录、不填密码、不绕过验证码。③「更新蝦皮」仍保持高风险边界：更新前只检测账号 Chrome/CDP/登录态，不自动启动缺失账号 Chrome。
|
2026-06-29 14:37:09 +08:00
|
|
|
|
- 只做当前任务范围内的事；T-504 已接入的多账号并行、dry-run、运行日志属于当前范围，其他 V2 / V3 功能只记录不实现。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- CDP 选择器 / 流程 / 配置 schema 变化，必须同步更新 `docs/04-architecture.md` 与相关任务。
|
2026-07-08 10:15:00 +08:00
|
|
|
|
- **新任务一任务一文件写进 `docs/tasks/T-<编号>.md`，不再手改 `docs/06-tasks.md`**（已冻结为 T-000~T-549 历史归档）；命名/frontmatter/领取规则见 `docs/tasks/README.md`。为避免多 agent 并发抢改同一文件、ID 撞号。
|
2026-07-08 10:19:55 +08:00
|
|
|
|
- 改完后**只更新对应任务文件**：把状态改 `DONE`、执行记录写进该任务文件的 `## 执行记录` 一节。**不再逐任务追加 `progress.md`、不再逐任务覆盖 `docs/current-state.md`**（这两个是每任务共享写入点，多 agent 并发会互相抢/覆盖）。`progress.md` 冻结为历史归档；`docs/current-state.md` 不再手动逐任务维护，当前状态以 `docs/tasks/` 各任务 frontmatter 为准，后续可由脚本汇总生成。
|
2026-07-09 16:49:42 +08:00
|
|
|
|
- **用户指令暗语**（用户输入以下触发词时按约定执行，默认全栈工程师视角、只提交本次相关文件）：
|
|
|
|
|
|
- `bug: <现象>` / `需求: <描述>` → 先查代码再给分析和方案，**只讨论不改代码**；
|
|
|
|
|
|
- `grill: <方案>` → 反方评审，逐点挑战该方案；
|
|
|
|
|
|
- `落task` → 把已讨论定案落成 `docs/tasks/T-<编号>.md`（按上述规则查号防撞），**只写文档不写代码，写完自动提交 git**；
|
2026-07-09 17:15:14 +08:00
|
|
|
|
- `审 T-<编号>` → **以 git 历史为准**（`git log -p docs/tasks/T-<编号>.md` 找出最近改动），先核代码事实，再审核该改动是否合理、给缺口；
|
2026-07-09 16:49:42 +08:00
|
|
|
|
- `补` → 把讨论新增的结论补进当前任务文件并提交 git；
|
2026-07-09 17:15:14 +08:00
|
|
|
|
- `做 T-<编号>` → 实现该任务 + 跑任务内验证命令；**验证全绿才提交**（执行记录写进任务文件、状态改 DONE、提交 git）；验证失败 → 报告结果、**不提交**、状态留 DOING 或标 BLOCKED 记原因；
|
|
|
|
|
|
- `记backlog: <一行>` → 追加进 `docs/06-tasks.md` 待办池并提交（只记一行，不建任务文件）。
|
|
|
|
|
|
- 上下文规则：`落task`/`补` 可带参数（如 `落task <主题>`、`补 T-<编号>`）；新会话或无对话上下文时**必须先问清指代对象，不得猜**。
|
|
|
|
|
|
- 本条目是这套暗语的**唯一权威源**；agent 记忆和模板库中的副本仅为指针/种子，以此处为准。
|
2026-07-11 10:18:50 +08:00
|
|
|
|
- **SVG 效果图统一存 `docs/ui/`**（不放 scratchpad/tmp）：新 tab 或界面改版的线框/效果图命名 `tabN-<名>.svg`，改版加后缀（如 `-T584`、`-v2`），画完随更新的文档一起提交 git；新增文件在 `docs/ui/README.md` 登记。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
|
|
|
|
|
|
## 安全红线
|
|
|
|
|
|
|
2026-06-26 16:27:33 +08:00
|
|
|
|
- 绝不把真实账号、密码、Cookie、token 写进代码、文档或日志；密码/API Key 可在本地配置或 DB 明文保存，但文件必须 gitignore，且不自动登录。
|
2026-06-26 16:37:58 +08:00
|
|
|
|
- `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/`（含配置、密钥、业务数据、登录态、图片）绝不提交版本库。
|
2026-06-27 11:29:48 +08:00
|
|
|
|
- `shopee待处理任务模板.xlsx` 是标准空模板，可提交；运营复制填写后的 Excel 属于业务数据，不提交版本库。
|
2026-06-26 15:55:28 +08:00
|
|
|
|
- 「更新」提交线上、删除满 9 张封面等不可逆动作，必须有显式确认；③ 点击「开始更新」后必须弹窗确认，用户确认后才批量更新当前筛选结果。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 不绕过 Shopee 的验证码、风控、限流或权限校验。
|
|
|
|
|
|
|
|
|
|
|
|
## 验证
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-06-26 17:05:18 +08:00
|
|
|
|
python -m compileall app main.py # 语法检查（T-000 后）
|
2026-06-26 16:37:58 +08:00
|
|
|
|
python -m unittest discover -s tests # 纯逻辑单元测试（T-006 完成且 tests/ 存在后）
|
2026-06-26 15:30:37 +08:00
|
|
|
|
python prototypes/demo.py # 单账号闭环（不提交）
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-06-26 16:37:58 +08:00
|
|
|
|
T-006 前若 `tests/` 不存在，不运行 `unittest discover`，只在回复中说明测试基座待建立；T-006 后纯逻辑改动必须跑该命令。
|
|
|
|
|
|
|
2026-06-26 15:30:37 +08:00
|
|
|
|
涉及 CDP 改动，在测试商品（ITEM_ID 51100639510）上实跑确认；如命令不可运行，在回复里如实说明。
|
|
|
|
|
|
|
|
|
|
|
|
## 风格
|
|
|
|
|
|
|
|
|
|
|
|
- 文档与 UI 文案用中文，标识符用英文。
|
2026-07-06 11:32:02 +08:00
|
|
|
|
- 所有用户可见文本必须使用中文：包括弹窗标题/正文/按钮、窗口标题、按钮、菜单、label、placeholder、tooltip、状态栏、空状态、确认框、运行日志、错误提示和成功提示等。URL、配置键、API 字段、模型别名、第三方/Shopee 原始错误可保留原文，但外围必须给中文解释；不得直接把英文技术报错裸露给用户。
|
2026-06-26 15:30:37 +08:00
|
|
|
|
- 内容面向 agent 执行：能落到“读什么、改什么、验证什么”。
|
