2026-08-03 12:13:39 +08:00
|
|
|
|
# AGENTS.md
|
|
|
|
|
|
|
|
|
|
|
|
> Codex / AI coding agent 的仓库级入口。进入本仓库后先读本文，再进入
|
|
|
|
|
|
> [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)。
|
|
|
|
|
|
|
|
|
|
|
|
## 项目定位
|
|
|
|
|
|
|
2026-08-03 16:27:05 +08:00
|
|
|
|
cmbuyer 是一个自动化采购系统：**采购服务**（网页端，`admin/`，Go）负责建单与人工决策，
|
|
|
|
|
|
**采购工具**（Windows 桌面端，`client/`，Python）驱动 Android 手机在拼多多完成找货和下单。
|
2026-08-03 12:13:39 +08:00
|
|
|
|
|
|
|
|
|
|
**系统只创建待付款订单，任何情况下都不自动付款。**
|
|
|
|
|
|
|
|
|
|
|
|
当前状态：仓库只有文档，尚未开始编码。阶段为 Phase 0。
|
|
|
|
|
|
|
|
|
|
|
|
## 必读顺序
|
|
|
|
|
|
|
|
|
|
|
|
1. 本文。
|
|
|
|
|
|
2. [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：入口流程与**四条特有纪律**。
|
|
|
|
|
|
3. [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：**第 1 节红线**。
|
|
|
|
|
|
4. [`docs/current-state.md`](docs/current-state.md)：当前代码现实与下一步任务。
|
|
|
|
|
|
5. 与当前任务相关的具体文档（按 [`docs/agent-context.json`](docs/agent-context.json) 路由）。
|
|
|
|
|
|
|
|
|
|
|
|
日常会话按 `agent-context.json` 的 `bootstrap.always_read` 与任务类型 `routes` 读取，
|
|
|
|
|
|
不机械重读全部文档。
|
|
|
|
|
|
|
|
|
|
|
|
## 四条不可协商的规则
|
|
|
|
|
|
|
|
|
|
|
|
### 1. 不碰钱
|
|
|
|
|
|
|
|
|
|
|
|
绝不编写点击支付、免密支付、先用后付或任何扣款控件的代码。
|
|
|
|
|
|
这条没有例外，也不接受「先做个开关默认关掉」。
|
|
|
|
|
|
|
|
|
|
|
|
系统**会**点击「提交订单」创建待付款订单，但必须满足四个前置条件（授权未消费且服务端
|
|
|
|
|
|
提交围栏已建立、闸门二通过、闸门三通过、控件唯一），且**只点一次**、点击后无论结果
|
|
|
|
|
|
都不重试。围栏申请失败或响应不明时不得点击；围栏建立后只能调和同一提交记录。
|
|
|
|
|
|
**第一趟试选的代码路径不得引用任何下单函数**，必须有测试证明不可达。
|
|
|
|
|
|
|
|
|
|
|
|
### 2. 安全边界只能收紧
|
|
|
|
|
|
|
|
|
|
|
|
[`docs/04-architecture.md`](docs/04-architecture.md) 第四节列出全部硬约束，含**三道价格
|
|
|
|
|
|
闸门**与**提交订单四条件**。**不得在任务中放宽任何一条**，包括为了让流程跑通而临时放宽。
|
|
|
|
|
|
确需变更时先改架构文档并说明理由。
|
|
|
|
|
|
|
|
|
|
|
|
价格**只在规格面板和订单确认页读**。别处读不到就转人工，不用其他位置的数字凑合。
|
|
|
|
|
|
|
|
|
|
|
|
### 3. 页面判据必须先真机取证
|
|
|
|
|
|
|
|
|
|
|
|
拼多多 App 会随版本改变页面结构。**不得从前序项目、旧文档或推理直接写判据。**
|
|
|
|
|
|
必须先真机 dump 取证，把截图路径、XML 路径和**拼多多 App 版本**写进任务文件。
|
|
|
|
|
|
|
|
|
|
|
|
### 4. 真机验收只能由人完成
|
|
|
|
|
|
|
|
|
|
|
|
`needs_device: true` 的任务，agent 不得自行标 `DONE`，保持 `DOING` 并写明等待事项。
|
|
|
|
|
|
|
|
|
|
|
|
## 前序项目的地位
|
|
|
|
|
|
|
|
|
|
|
|
`/mnt/d/chengma/cmroubao` 与 `/mnt/d/chengma/cmpdd` 是本项目的**设计依据，不是事实来源**。
|
|
|
|
|
|
|
|
|
|
|
|
- 可以参考它们的结构决策和护栏理由。
|
|
|
|
|
|
- **不得**把它们的页面判据、常量或结论当作已验证事实直接使用。
|
|
|
|
|
|
- 引用其中任何结论时，必须在本项目重新验证并记录证据。
|
|
|
|
|
|
|
|
|
|
|
|
搬运护栏时，**必须连同理由一起搬**。只搬代码不搬理由，后人会把它当碍事的逻辑删掉。
|
|
|
|
|
|
|
|
|
|
|
|
## 工作模式
|
|
|
|
|
|
|
|
|
|
|
|
- 默认**单任务、单责任 agent、单写入者**：一个任务只有一个负责人，同时只有一个 agent
|
|
|
|
|
|
修改该任务的 `write_paths`。
|
2026-08-03 16:27:05 +08:00
|
|
|
|
- 多 agent 并行只拆到写路径互不重叠的任务。`admin/` 采购服务与 `client/` 采购工具天然可并行。
|
2026-08-03 12:13:39 +08:00
|
|
|
|
- 复杂任务先规划再编码。方案、不可变约束、写路径和验收门禁必须写入任务文件，
|
|
|
|
|
|
不能只停留在对话里。
|
|
|
|
|
|
- 任务内委派不是默认流程。委派后仍保持唯一写入者，执行者必须继承任务文件中的不可变
|
|
|
|
|
|
约束与验证要求。
|
|
|
|
|
|
- 无论是否委派，任务所有者都对结果负责，独立审阅差异、重跑验证；
|
|
|
|
|
|
**不能把执行者或工具的自我报告当成完成证据**。
|
|
|
|
|
|
|
|
|
|
|
|
## 验证
|
|
|
|
|
|
|
|
|
|
|
|
按 [`docs/03-tech-stack.md`](docs/03-tech-stack.md) 第六节的验证矩阵判断层级：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-08-03 16:27:05 +08:00
|
|
|
|
# 采购服务（admin/）
|
2026-08-03 12:13:39 +08:00
|
|
|
|
go test ./...
|
|
|
|
|
|
go vet ./...
|
|
|
|
|
|
|
2026-08-03 16:27:05 +08:00
|
|
|
|
# 采购工具（client/）
|
2026-08-03 12:13:39 +08:00
|
|
|
|
python -m unittest discover -s tests -t .
|
|
|
|
|
|
python -m compileall -q src tests
|
|
|
|
|
|
|
|
|
|
|
|
# 上下文清单
|
|
|
|
|
|
python scripts/validate_agent_context.py
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**跨端契约改动必跑完整门禁**——两端会同时坏。
|
|
|
|
|
|
|
|
|
|
|
|
代码尚未初始化，上述命令在 T-001 / T-002 完成前不可运行；届时由对应任务替换为真实命令
|
|
|
|
|
|
并同步文档。
|
|
|
|
|
|
|
|
|
|
|
|
## 风格
|
|
|
|
|
|
|
|
|
|
|
|
- 文档与 UI 文案使用中文，标识符使用英文。
|
|
|
|
|
|
- 金额一律用十进制字符串，不用浮点数。
|
|
|
|
|
|
- 护栏必须连同**理由**一起注释。
|
|
|
|
|
|
- 内容面向执行，每条规则能落到「读取什么、修改什么、验证什么」。
|
