docs: 初始化项目文档集与一致性补丁

建立 harness coding 文档体系并完成一致性修正:

- 文档集:AGENTS.md/CLAUDE.md 入口,docs/00-05 规范文档,
  api.md/routes.md/current-state.md,根目录 tasks.md/progress.md。
- 一致性补丁:TaskStatus 中英映射、支付模式收敛为全局 PaymentConfig、
  执行器级 RunnerState 暂停语义、progress 与 current-state 职责边界。
- 工程地基:新增 .gitignore,忽略运行产物/敏感数据与 .claude 本地设置。
- 合规留痕:02 需求新增平台规则与合规风险条目。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-06-24 16:15:46 +08:00
co-authored by Claude Opus 4.8
commit 541dfab967
15 changed files with 1487 additions and 0 deletions
+97
View File
@@ -0,0 +1,97 @@
# 编码规则(Coding Rules)
> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
> 与技术细节冲突时,以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准;与“该不该做”冲突时,以 [需求](02-requirements.md) 为准。
## 0. 黄金法则
1. **不臆造**:Excel 字段、页面选择器、接口、依赖,不确定就查证或询问。
2. **守范围**:只做当前任务要求的事,不顺手加 Web 后台、多设备、数据库等后续能力。
3. **照架构**:使用既定技术栈和模块边界,不擅自引入新框架。
4. **小步改**:一次只解决一个问题,不夹带无关重构。
5. **可验证**:改完必须能运行、能测试、对得上验收标准。
## 1. 动手前
- 按链路确认:`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
- 找到本任务对应的验收标准,写之前就知道“怎么算做对”。
- 先找现有函数、组件、工具和测试,复用优先。
- 涉及真机自动化时,先确认设备连接和当前 App 状态。
- 如果需求含糊,或改动会偏离原则 / 架构,先问。
## 2. 事实来源纪律
- Excel 表头以用户提供的真实样例或 `04-architecture.md` 当前约定为准。
- 拼多多页面状态以真机截图、UI XML 和实际运行日志为准。
- 不从旧截图、临时脚本、未确认样例里推断当前事实。
- 不虚构字段、按钮文本、订单号位置、状态码、配置项。
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md` 和相关任务。
## 3. 范围纪律
- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
- V2 / V3 功能只记录,不实现。
- 需求明确排除的非目标不得实现。
- 不为“将来可能用到”提前抽象。
- 不默认覆盖原始 Excel,除非用户明确要求。
## 4. 安全与合规纪律
- 绝不实现绕过验证码、风控、人脸、短信、安全校验或平台限制的逻辑。
- 绝不实现无配置、无二次校验、无金额上限的自动支付。
- 绝不记录支付密码、短信验证码、账号密码等敏感信息。
- 绝不调用、逆向或改造拼多多非公开接口。
- 自动支付必须显式开启,并在商品、SKU、数量、地址、金额校验通过后才能继续。
- 遇到安全校验时进入 `待人工`,由运营在真机上处理。
## 5. 架构纪律
- 技术栈以 `03-tech-stack.md` 为准。
- 新增依赖前先说明理由;未经确认不要引入重量级依赖。
- GUI、Excel、任务执行器、Android 控制模块职责必须分离。
- API/本地模块合约以 `api.md` 为准,界面结构以 `routes.md` 为准。
- 页面选择器集中在拼多多流程模块,不散落在 GUI 代码里。
## 6. 代码规范
- 标识符使用英文。
- UI 文案、注释、文档语言使用中文,除非引用库 API 或错误码。
- 错误必须处理,不吞错。
- 注释解释“为什么”,不复述“做了什么”。
- 日志要包含任务 ID 和当前步骤,但不能包含敏感信息。
- 遵守项目已有格式化工具,不手工制造风格分裂。
## 7. 测试与验证
完成前至少检查:
- [ ] 构建或语法检查通过。
- [ ] 相关测试通过。
- [ ] 对得上需求验收标准。
- [ ] 没有夹带无关改动。
- [ ] 涉及文档事实变化时,文档已同步。
- [ ] 涉及 Android 自动化时,说明是否已用真机验证。
- [ ] 回复里如实说明跑了什么命令、结果如何。
计划命令,初始化后必须改成真实命令:
```powershell
python -m pytest
python -m compileall src
python src/main.py
```
## 8. 绝不
- 绝不把密钥、token、密码、支付密码、短信验证码写进代码或文档样例。
- 绝不为了让测试通过而删除断言、降低验收标准。
- 绝不擅自删除用户已有文件或重置工作区。
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
- 绝不在自动化失败时盲目点击不确定区域继续下单。
## 9. 拿不准就问
问题要具体,说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。