goauto/AGENTS.md

Agent 开发规则

本仓库采用 DevHarness 工作流：Gitea 工单记录任务过程，Gitea Wiki 是长期开发文档和任务归档的事实来源，Git 保存源码、版本绑定资料和 Wiki 的本地镜像。docs/ 中显式映射的 Markdown 是 Wiki 只读镜像；docs/task/ 只保存用户明确要求导出的任务归档快照。

当前文档规则参考 DevHarness 提交 b1f500128d6eb100985792d4a715db8b6b5ae203，但所有模板内容都必须按 GoAuto 事实改写。开始工作前阅读 docs/00-project-profile.md、docs/03-business-rules-and-glossary.md 和当前工单。不同交付单元规则不同时，在 server/、web/ 或 android/ 下增加更具体的 AGENTS.md。

永久规则

• 不把密码、Token、Cookie、私钥、PDD 账号凭据、个人数据或生产数据写入代码、日志、工单和文档。
• 不执行付款；任何自动支付实现、入口或测试都禁止进入本项目。
• 当前采集 MVP 只实现 PDD 商品、规则、任务、Android 执行和任务详情。采购是独立的后续高风险 MVP，未通过对应原型和工单门禁前不能混入采集代码。
• 不保存原始控件树和设备截图；只保存结构化任务日志、错误码、任务规则快照和采集结果。
• 一台设备同一时刻只执行一个任务；手机离线时当前采集任务失败，默认不重试、不自动换机。
• 找不到控件、验证码、风控、人机验证或登录失效时明确失败，不使用 OCR/VLM，不猜测规格，不点击相近候选。
• SKU 数据不完整仍须提交并允许在任务详情查看，状态记为 completed_partial。
• 规则创建即生效；删除后不能创建新任务，但已有任务继续使用自身规则快照。
• 同一 PDD 商品不能同时存在多个 pending 或 running 采集任务。
• 重置采集任务保留 URL、goods_id、规则和设备快照，事务清空旧结果后重新进入 pending。
• 保留与当前工单无关的工作区改动，不重置、不覆盖、不顺手修改。
• 测试结果必须真实；未执行或无法覆盖的真机、多设备、云环境和高风险行为必须明确记录。

工单门禁

• 新功能、缺陷修复、重构，以及接口、数据库、权限、并发、状态机、安全或用户界面变化必须先有单元工单。
• 只改错别字、注释、文档措辞或不改变含义的纯显示文案时可以免工单；有任何行为、布局、状态或安全含义不确定时不得使用豁免。
• Epic 和 MVP 只维护目标与子工单索引；单元任务是唯一实施单位。
• 工单必须记录原始需求摘要、前置依赖、是否可并行、子项目影响、方案、设计证据、验收、验证、风险和文档影响。
• 实施前检查依赖；真实依赖未满足且不允许并行时保持待实施。
• 用户未明确验收前，工单保持待验收，不关闭。

工单与设计证据双门禁

• 纯显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、安全、支付、金额、单位、程序标识符、布局和可访问性时才免原型，并执行最小界面检查。
• 现有界面的小范围样式或布局调整至少提供标注截图、低保真图或明确复用的现有规范。
• 新组件记录正常、空、加载、失败、禁用和权限边界；按需提供低保真图。
• 新页面、独立用户功能、重大交互或导航变化必须先制作 QuantUX 或其他可审阅原型；用户确认文字需求、原型和覆盖范围后才能编写生产代码。
• 后端、接口、数据和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计。
• 原型记录链接或 Git 路径、App ID/版本、草稿或已确认状态、确认人、确认时间和覆盖范围。草稿不能作为正式实现依据。
• 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新设计证据并重新确认。

需求记录与实施

1. 先确认目标、非目标和当前事实，区分代码事实、用户确认规则和假设。
2. 创建单元工单时记录来源、提出时间和表达目的所需的少量关键原话或脱敏摘要；不复制完整聊天或 Agent 内部推理。
3. 只修改工单声明的交付单元和共享契约；新发现的相邻问题记录或另建工单，不混入当前任务。
4. 共享 API 以 docs/08-agent-api-contract.md 为唯一事实来源。
5. 数据库和接口变化必须同步更新架构、业务规则和 API 文档。
6. 每个动作结果必须与 taskId、deviceId 和任务内的 ruleSnapshot 关联。
7. Android Agent 必须使用任务租约和本地互斥锁保证串行。
8. 服务端必须以最终包名、Activity 和页面证据验证动作，不只相信 Portal 的 success 响应。
9. 执行与风险相称的测试，把实现、验证、未验证项和提交哈希回写工单。

自然语言快捷指令

快捷指令只是本工作流的别名，不能绕过方案确认、前置依赖、安全规则、工单范围、必要验证或人工验收：

• 只分析：只读检查并给出方案；不建单、不修改。
• 建工单：根据已确认方案创建单元工单；建单后停止。
• 执行工单 #N：检查工单和依赖，实施、测试、提交并回写证据；停在待验收。
• 建工单并做：依次建单和执行；停在待验收。
• 继续工单 #N：从首个未完成步骤继续，不重复仍然有效的检查。
• 检查工单 #N：只读核对范围、验收、测试和证据；不自动修复。
• 同步文档：读取 Wiki、导出核心 docs/ 镜像并检查一致性；不修改 Wiki、不导出任务归档、不自动提交。
• 导出任务归档：仅在用户明确提出时增量导出 Wiki 任务归档；导出全部任务归档 才执行全量导出。
• #N 验收通过：仅在用户明确验收后更新任务归档、同步必要镜像、关闭工单并同步父工单。

效率与停止条件

• 优先执行能产生真实反馈的最小命令，采用“执行 → 首个真实错误 → 最小修复 → 继续”的闭环。
• 同一任务和同一环境中已经验证的事实不重复检查；环境、配置、代码或关键前提变化后才重新验证。
• 不主动增加与验收无关的文档、脚本、框架、重构或扩展性设计。
• 涉及凭据、权限、安全、迁移、并发、删除、发布、创建订单或其他不可逆动作时，先完成相应门禁，不通过试错获取风险反馈。
• 完成工单范围、必要测试、文档影响和证据回写后立即停止；未影响当前验收的相邻问题只提示或另建单。
• 长期文档固定顺序为：修改 Wiki → 读取确认 → 导出核心 docs/ → 检查一致性 → 提交镜像。不得直接编辑镜像后反向覆盖 Wiki。

Git 与验收

• 提交只包含当前工单内容，提交信息引用工单号。
• 优先运行项目档案记录的格式、单元、契约和集成测试。
• 涉及创建订单、权限、安全、并发、迁移和删除数据属于高风险，真机或正式实施前必须再次等待人工确认。
• 完成后将实现、验证、遗留问题和提交哈希回写工单，等待用户验收。
• 用户未明确要求时，不导出 docs/task/；任务归档默认只保存在 Wiki。