goauto/AGENTS.md

Agent 开发规则

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

当前文档规则参考 DevHarness 提交 bfdf648962d11a8024f62768380d8571e1f45f68，但所有模板内容都必须按 GoAuto 事实改写。开始工作前阅读任务涉及目录中的 AGENTS.md。不同交付单元规则不同时，在 server/、web/ 或 android/ 下增加更具体的 AGENTS.md；目录越深的规则越具体，但不得削弱上级安全规则。

项目档案 按需阅读，不作为每次任务的固定前置。出现下列情况之一时必须读：需要环境、配置或凭据来源；需要确认目录边界；需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。只为查命令不必打开项目档案。涉及采集、采购或设备行为时另读 docs/03-business-rules-and-glossary.md 和当前工单。

常用命令

所有命令默认从仓库根目录执行。

用途	命令
查看工作区	git status --short --branch
检查模板结构	python dev_scripts/harness.py check --strict
导出核心 Wiki 镜像	python dev_scripts/harness.py sync
检查核心 Wiki 镜像	python dev_scripts/harness.py sync --check
导出并完整校验	python dev_scripts/harness.py sync --verify
创建任务归档	python dev_scripts/harness.py archive 123 "修复登录超时"
增量导出任务归档	python dev_scripts/harness.py export
全量导出任务归档	python dev_scripts/harness.py export --all
服务端/Web/Android 验证	.\scripts\verify.ps1 -Component all

1. 永久规则

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

2. 哪些改动需要工单

新功能、缺陷修复、重构，以及接口、数据库、权限、并发、状态机、安全或用户界面变化必须先有单元工单。

以下小改动可以直接提交，不要求工单和任务归档：

• 只改错别字、注释或文档措辞；
• 只做格式化、导入排序或不跨文件的内部变量改名；
• 补充类型标注或文档字符串且不改变行为；
• 删除已经确认无人使用的死代码；
• 只修改用户看到的界面显示文案，并且满足本文件「工单与设计证据双门禁」的全部豁免条件。

除严格符合界面显示文案豁免的修改外，只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。

Epic 和 MVP 只维护目标与子工单索引；单元任务是唯一正式实施单位。

3. 需求到实施

1. 先确认目标、非目标和当前事实，区分代码事实、用户确认规则和假设。
2. 工单必须记录原始需求摘要、前置依赖、是否可并行、子项目影响、方案、设计证据、验收、验证、风险和文档影响。
3. 实施前检查依赖；真实依赖未满足且不允许并行时保持待实施。
4. 只修改工单声明的交付单元和共享契约；新发现的相邻问题记录或另建工单，不混入当前任务。
5. 共享 API 以 docs/08-agent-api-contract.md 为唯一事实来源。
6. 数据库和接口变化必须同步更新架构、业务规则和 API 文档。
7. 每个动作结果必须与 taskId、deviceId 和任务内的 ruleSnapshot 关联。
8. Android Agent 必须使用任务租约和本地互斥锁保证串行。
9. 服务端必须以最终包名、Activity 和页面证据验证动作，不只相信 Portal 的 success 响应。
10. 执行与风险相称的测试，把实现、验证、未验证项和提交哈希回写工单。
11. 长期核心文档必须先修改 Wiki、读取确认，再运行 python dev_scripts/harness.py sync 导出本地镜像；任务归档默认只更新 Wiki，不自动导出本地。不得直接编辑镜像后反向覆盖 Wiki。

Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。

新项目 Wiki 初始化门禁

本项目 Wiki 已于 2026-08-17 初始化并启用 Wiki-first，本节适用于从本仓库派生新项目的场景。

• 从模板或本仓库创建新项目时，先创建 Gitea 远端仓库并启用工单和 Wiki，再配置 wiki-docs.json；不得把模板自带的本地 docs/ 当作新项目 Wiki 已初始化的证据。
• 优先使用项目已配置的 Gitea MCP 查询和写入 Wiki；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
• 先查询线上页面列表；Home 不存在时必须先创建 Home，在线回读正文并记录 revision，然后再逐页创建或更新其他核心映射页面。
• 每个核心页面写入后必须在线回读并取得 revision。页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码。
• 产品编码前必须运行 python dev_scripts/harness.py sync --verify；全部成功才表示线上 Wiki 和核心镜像初始化完成。

工单与设计证据双门禁

• 纯显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、安全、支付、金额、单位、程序标识符、布局和可访问性时才免原型，并执行最小界面检查。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。
• 现有界面的小范围样式或布局调整至少提供标注截图、低保真图或明确复用的现有规范。
• 新组件记录正常、空、加载、失败、禁用和权限边界；按需提供低保真图。
• 新页面、独立用户功能、重大交互或导航变化必须先制作 QuantUX 或其他可审阅原型；用户确认文字需求、原型和覆盖范围后才能编写生产代码。
• 完整原型形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照，保存到 prototypes/<工单号>/<版本>/index.html；版本目录内资源使用相对路径。可编辑设计源仍在 QuantUX，Git HTML 是版本化审核证据，Wiki 和工单只保存索引。
• 已确认的 HTML 快照不得原位覆盖；页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。提交审核前检查入口、主要交互和资源完整性，并删除凭据、账号、个人信息和生产数据。
• 设计工具无法生成可用 HTML 时，在工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不得只保留难以访问的线上链接后直接编码。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。
• 后端、接口、数据和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计。
• 原型记录链接或 Git 路径、App ID/版本、草稿或已确认状态、确认人、确认时间和覆盖范围。草稿不能作为正式实现依据。
• 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新设计证据并重新确认。

存量原型的偏离说明（#47 确认）：prototypes/ 下已有的 quantux-*.html 平铺快照建立于本规则之前，保持原样不迁移，历史版本可在 Git 历史中查阅。工单号/版本目录结构自 #47 起对新增原型生效。

自然语言快捷指令

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

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

需求记录与流转

• 创建单元工单时记录来源、提出时间和表达目的所需的少量关键原话或脱敏摘要；不复制完整聊天或 Agent 内部推理。
• 不得臆造用户原话；无法确认的表述记为假设并标注待确认。
• Gitea 工单全文不导出到仓库；docs/task/ 只是用户明确要求时导出的 Wiki 任务归档快照，可能不完整。
• 需求变化时先更新工单与设计证据并重新确认，再继续实施。

效率与范围控制

本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。

严格控制范围

• 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
• 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
• 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于「额外验证」。
• 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。

渐进执行和修复

• 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
• 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
• 采用「执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑」的闭环。
• 不在真实证据出现前堆叠与已知风险无关的预防性检查。
• 涉及凭据、权限、安全、数据、迁移、并发、删除、发布、创建订单或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。

复用已验证事实

• 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
• 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
• 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
• 真机验证结论只在同一设备、同一 App 版本和同一规则快照下复用。

明确停止条件

• 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
• 「最小验收条件」包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
• 未影响当前验收的相邻问题只提示或建单，不顺手处理。

4. 工单层级

• Epic 维护长期目标与子工单索引，MVP 维护一次可交付范围，单元任务是唯一实施单位。
• 单元任务通过后才做 MVP 集成验收；MVP 通过后才关闭 MVP；Epic 全部范围完成后才关闭 Epic。

5. Git 与验证

• 提交只包含当前工单相关文件，提交信息引用工单号。
• 优先运行项目档案记录的格式、单元、契约和集成测试。
• 涉及创建订单、权限、安全、并发、迁移和删除数据属于高风险，真机或正式实施前必须再次等待人工确认。

6. 完成、验收和归档

1. 逐项完成验收、测试和实现提交，并把最终方案、差异、结果、提交及遗留问题写回工单。
2. 工单保持「待验收」，用户没有明确验收通过前不得关闭。
3. 运行 python dev_scripts/harness.py archive <编号> "<短标题>" 创建 Wiki 任务归档，不登记或导出本地镜像。
4. 读取确认 Wiki，运行 python dev_scripts/harness.py sync --check 检查核心镜像，并把任务归档页面、revision 和提交哈希写回工单。
5. 用户验收通过后关闭单元工单，并同步更新 MVP 和 Epic。
6. 用户未明确要求时，不导出 docs/task/；任务归档默认只保存在 Wiki。

7. 文档影响

• 每个单元任务必须在工单中选择「无长期文档影响并说明原因」或列出需要更新的 Wiki 页面。
• 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。
• 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。
• 必需核心页面及结构以 python dev_scripts/harness.py check --strict 为准。