goauto/AGENTS.md

Agent 开发规则

本仓库采用 DevHarness 工作流：Gitea 工单记录任务过程，Git 保存源码与版本绑定文档。当前长期文档事实来源是仓库 docs/；接入 Gitea Wiki 同步后再切换为 Wiki 主源，切换必须单独建单。

开始工作前阅读 docs/00-project-profile.md、docs/03-business-rules-and-glossary.md 和当前工单。不同交付单元规则不同时，在 server/、web/ 或 android/ 下增加更具体的 AGENTS.md。

永久规则

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

工单门禁

• 新功能、缺陷、接口、数据库、权限、并发、状态机和 UI 变化必须先有单元工单。
• Epic 和 MVP 只维护目标与子工单索引；单元任务是唯一实施单位。
• 工单必须记录原始需求摘要、前置依赖、是否可并行、子项目影响、方案、验收、验证、风险和文档影响。
• 实施前检查依赖；真实依赖未满足时保持待实施。
• 用户未明确验收前，工单保持待验收，不关闭。

实施规则

1. 先确认目标、非目标和当前事实。
2. 只修改工单声明的交付单元和共享契约。
3. 共享 API 以 docs/08-agent-api-contract.md 为唯一事实来源。
4. 数据库和接口变化必须同步更新架构、业务规则和 API 文档。
5. 每个动作结果必须与 taskId、deviceId 和任务内的 ruleSnapshot 关联。
6. Android Agent 必须使用任务租约和本地互斥锁保证串行。
7. 服务端必须以最终包名、Activity 和页面证据验证动作，不只相信 Portal 的 success 响应。
8. 测试结果必须真实；未验证的真机、多设备和云环境行为写入工单。

Git 与验收

• 提交只包含当前工单内容，提交信息引用工单号。
• 优先运行项目档案记录的格式、单元、契约和集成测试。
• 涉及自动提交订单、权限、安全、并发、迁移和删除数据属于高风险，必须再次等待人工确认。
• 完成后将实现、验证、遗留问题和提交哈希回写工单，等待用户验收。