95 lines
5.0 KiB
Markdown
95 lines
5.0 KiB
Markdown
|
# 编码规则
|
||
|
|
|
||
|
|
> 每次写代码前完整读取。需求决定“该不该做”，架构和 API 决定“如何接入”。
|
||
|
|
|
||
|
|
## 1. 黄金法则
|
||
|
|
|
||
|
|
1. 不臆造源码结构、拼多多页面、字段、接口或依赖。
|
||
|
|
2. 一次只完成当前任务，不夹带后续功能。
|
||
|
|
3. 高风险自动化先做可停止、可观察的最小探针。
|
||
|
|
4. 代码完成不等于任务完成；必须有可运行验证证据。
|
||
|
|
5. 安全规则不能只写在提示词或 UI 中，服务端和工作流都要强制执行。
|
||
|
|
|
||
|
|
## 2. 动手前
|
||
|
|
|
||
|
|
- 读取当前任务关联的需求、US、IX、架构、API 和页面路由。
|
||
|
|
- 使用 codebase-memory 图谱优先发现代码；非代码和字符串搜索可用 `rg`。
|
||
|
|
- 先核实上游 Roubao 的真实模块和测试，再决定修改位置。
|
||
|
|
- 检查任务 `write_paths` 与用户已有改动，不覆盖无关内容。
|
||
|
|
- 不确定的业务决策标为 blocker，不让实现自行发明。
|
||
|
|
|
||
|
|
## 3. 领域边界
|
||
|
|
|
||
|
|
- 原始任务输入是不可变事实；AI 派生字段单独保存。
|
||
|
|
- 任务状态只能由领域状态机转换，HTTP 路由和 UI 不直接写状态。
|
||
|
|
- Android 工作流只通过 task client、automation adapter 和 AI client 访问外部边界。
|
||
|
|
- 管理页面调用 usecase，不直接执行 SQL。
|
||
|
|
- 供应商 VLM SDK 类型停留在 infrastructure adapter。
|
||
|
|
- 拼多多 UI 文本、资源标识和版本差异集中维护，不散落在工作流。
|
||
|
|
|
||
|
|
## 4. Android 自动化规则
|
||
|
|
|
||
|
|
- 动作前确认目标 App 包名和预期页面，动作后确认状态确实变化。
|
||
|
|
- 优先使用资源 ID、可访问性语义和稳定文本；坐标只能作为被验证的局部降级。
|
||
|
|
- 每个步骤定义 timeout、有限 retry、成功条件和停止条件。
|
||
|
|
- 禁止无界循环、无限滑动、无限候选遍历和随机点击。
|
||
|
|
- 默认最多检查 5 个候选；扩大范围必须先改需求。
|
||
|
|
- 前台服务通知要展示任务编号和当前步骤，并提供安全停止入口。
|
||
|
|
- 验证码、风控、登录、支付、未知页面统一进入安全失败。
|
||
|
|
- MVP 不得实现最终提交订单或支付动作，包括“先写好但不调用”的隐藏代码。
|
||
|
|
|
||
|
|
## 5. AI 规则
|
||
|
|
|
||
|
|
- 输入明确区分原始事实、用户硬约束、页面观察和待推断字段。
|
||
|
|
- 输出只接受结构化 schema；解析失败不能回退到自由文本猜测。
|
||
|
|
- 数量、预算、允许平台和停止边界由确定性代码覆盖模型输出。
|
||
|
|
- 提示词、schema、模型名和阈值版本化并记录到 execution。
|
||
|
|
- 不向模型发送密码、token、支付信息或与候选判断无关的个人信息。
|
||
|
|
- 模型低置信度或前后结果冲突时转人工，不自动增加动作权限。
|
||
|
|
|
||
|
|
## 6. 后端与 API 规则
|
||
|
|
|
||
|
|
- 请求在边界完成类型、大小、媒体类型和业务规则校验。
|
||
|
|
- 领取任务必须使用事务；不得先 GET 再由客户端自行标记占用。
|
||
|
|
- 状态变化校验当前状态、设备归属、claim token、版本和租约。
|
||
|
|
- 创建、领取、完成和证据上传的重试路径必须幂等。
|
||
|
|
- 不向客户端返回 `password_hash`、`token_hash`、存储绝对路径或供应商密钥。
|
||
|
|
- 通用错误使用稳定 code 和可读 message；内部堆栈只进受控日志。
|
||
|
|
- 文件访问通过鉴权接口，防止路径遍历和猜测 URL。
|
||
|
|
|
||
|
|
## 7. 安全与隐私
|
||
|
|
|
||
|
|
- 密钥只来自环境变量或被忽略的本地配置。
|
||
|
|
- 日志默认脱敏，不记录 Authorization、Cookie、密码、设备令牌或完整地址。
|
||
|
|
- 上传文件限制媒体类型、大小和解码结果，随机化服务端文件名。
|
||
|
|
- 不绕过第三方平台限制、验证码、风控或系统权限。
|
||
|
|
- 不可逆动作必须由明确需求、服务端授权、App 确认和幂等保护共同允许。
|
||
|
|
- 发现需求与平台条款冲突时停止实现并记录 blocker。
|
||
|
|
|
||
|
|
## 8. 测试
|
||
|
|
|
||
|
|
每个任务按风险选择测试：
|
||
|
|
|
||
|
|
- 领域状态机、硬约束、错误码：单元测试。
|
||
|
|
- API 权限、事务、幂等、文件校验：集成测试。
|
||
|
|
- VLM adapter：固定 fixture/契约测试，不让普通测试依赖真实付费 API。
|
||
|
|
- Android workflow：用 fake automation/AI client 测状态和安全停止。
|
||
|
|
- 拼多多真实流程：指定版本测试机手工 smoke，保存脱敏截图和步骤证据。
|
||
|
|
- UI：覆盖默认、加载、空、错误、权限和中断状态。
|
||
|
|
|
||
|
|
不得用删除断言、放宽预算、安全停止或候选上限来让测试通过。
|
||
|
|
|
||
|
|
## 9. 完成定义
|
||
|
|
|
||
|
|
- [ ] 修改在任务 `write_paths` 内。
|
||
|
|
- [ ] 构建、相关测试和格式检查通过。
|
||
|
|
- [ ] 关联需求、US 和 IX 的验收通过。
|
||
|
|
- [ ] 安全停止路径至少验证一次。
|
||
|
|
- [ ] 没有真实密钥或敏感证据进入仓库。
|
||
|
|
- [ ] 接口、数据模型或命令变化已同步文档。
|
||
|
|
- [ ] 当前任务文件记录命令、结果、环境和未验证项。
|
||
|
|
- [ ] `current-state.md` 与真实目录、命令和 blocker 一致。
|
||
|
|
|
||
|
|
当前尚无真实命令。`T-001` 后必须在这里列出 Android 构建和测试命令；后端建立后
|
||
|
|
再列出后端命令。不能把 `docs/03-tech-stack.md` 中的计划命令当作已通过证据。
|