207 lines
21 KiB
Markdown
207 lines
21 KiB
Markdown
# Agent 开发规则
|
||
|
||
本仓库采用精简的单人 DevHarness 工作流：Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的唯一事实来源；Gitea Wiki 只维护长期产品、架构、契约、业务规则、安全边界和运行说明；Git 保存源码、迁移、测试、版本绑定资料和 Wiki 的本地镜像。`docs/` 中显式映射的 Markdown 是 Wiki 只读镜像；既有 Wiki 任务归档和 `docs/task/` 仅作历史兼容，只有用户明确要求专项快照时才创建或导出。
|
||
|
||
当前文档规则参考 DevHarness 提交 `4bbacf4d7fb265984396bb5589c544105043fa0b`，但所有模板内容都必须按 GoAuto 事实改写。开始工作前阅读任务涉及目录中的 `AGENTS.md`。不同交付单元规则不同时，在 `server/`、`web/` 或 `android/` 下增加更具体的 `AGENTS.md`；目录越深的规则越具体，但不得削弱上级安全规则。
|
||
|
||
[项目档案](docs/00-project-profile.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 账号凭据、个人数据或生产数据写入代码、日志、工单和文档。例外：经用户于 2026-08-21 明确确认的 #62 内部 AI Provider API Key，可明文保存在专用 `ai_matching_setting` 数据表，并只返回给管理员用于下次查看和替换；它仍不得出现在代码、日志、工单、Wiki、任务快照、采购员接口或 Android 接口中。
|
||
- 不执行付款。当前项目不实现任何自动支付动作、入口或测试；后续如需实现，必须单独建单评估，并至少具备显式能力位、服务端开关、单笔金额上限与人工授权四项控制。支付、下单和订单相关文字允许作为只读识别信号出现在采集与采购规则中，用于判断页面形态；任何规则都不得把它们配置为点击目标。
|
||
- 当前采集 MVP 只实现 PDD 商品、规则、任务、Android 执行和任务详情。采购是独立的后续高风险 MVP，未通过对应原型和工单门禁前不能混入采集代码；采集规则可以描述订单确认面板的只读特征，这不构成采购代码混入采集。
|
||
- 不保存原始控件树和设备截图；只保存结构化任务日志、错误码、任务规则快照和采集结果。
|
||
- 一台设备同一时刻只执行一个任务；手机离线时当前采集任务失败，默认不重试、不自动换机。
|
||
- Android Agent 端：找不到控件、验证码、风控、人机验证或登录失效时明确失败，不使用 OCR/VLM。
|
||
- 服务端顺云宝（SYB）登录：允许调用配置的线上 OCR 服务识别登录验证码（见 #48）。验证码图片会离开本项目发送到该服务，更换服务地址前必须重新评估。此例外只适用于 SYB 登录，不扩大到 Agent 端或任何 PDD 相关流程。
|
||
- 规格匹配：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：先修改线上页面并读取 revision，再运行一次 `python dev_scripts/harness.py sync` 和一次 `sync --check`，提交本地镜像。无长期文档影响时在工单说明原因并完全跳过 Wiki 更新和同步；不得直接编辑镜像后反向覆盖 Wiki。
|
||
|
||
### 权威源与事实边界
|
||
|
||
- 文档或界面与实现冲突时，按以下顺序裁决：可执行代码与自动化测试 → 已批准的共享契约和决策 → 当前长期 Wiki → 旧设计稿 → 注释、UI 文案和历史示例。
|
||
- 「当前实现」只能描述指定提交上可复核的行为；「目标契约」表示尚待实施或验收的目标，不能用来宣称现有能力。
|
||
- 能力状态优先使用「未发现实现」「仅设计」「部分实现」「已实现某一端」等带限定的表述，不用模糊的是/否结论。
|
||
- 基线或差距审计必须记录代码 commit、核验日期、证据路径、审计范围和不在范围；证据不能证明的内容也要明确写出。
|
||
|
||
Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。
|
||
|
||
### Gitea 交互与工单最小读取
|
||
|
||
- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
|
||
- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
|
||
- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省上下文跳过范围、依赖、安全、验收或重要变化。
|
||
- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
|
||
- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明范围、方案、风险和验收变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
|
||
- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把「已读取全文」误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
|
||
- 正确性、安全规则和已确认范围优先于读取成本；读取边界存在不确定时补读必要证据。
|
||
|
||
### 新项目 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 或其他可审阅原型；用户确认文字需求、原型和覆盖范围后才能编写生产代码。
|
||
- 完整原型形成待审核版本后，默认直接通过 QuantUX 或其他设计工具的线上链接审核。工单必须记录可访问链接、App ID、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围；链接无法访问或无法区分版本时停止审核，等待用户确认等效方案。
|
||
- 只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线证据时，才导出到 `prototypes/<工单号>/<版本>/index.html`。版本目录内资源使用相对路径；导出后检查入口、主要交互、资源完整性和敏感信息，但不自动提交。
|
||
- 已确认的本地快照不得原位覆盖；页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。
|
||
- 设计工具无法生成用户明确要求的可用 HTML 时，在工单记录限制并停止该导出；只要线上原型可访问且版本明确，线上审核不因此阻塞。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制建立完整原型或导出 HTML。
|
||
- 后端、接口、数据和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计。
|
||
- 原型记录链接或 Git 路径、App ID/版本、草稿或已确认状态、确认人、确认时间和覆盖范围。草稿不能作为正式实现依据。
|
||
- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新设计证据并重新确认。
|
||
|
||
> **存量原型的偏离说明（#47 确认）**：`prototypes/` 下已有的 `quantux-*.html` 平铺快照建立于本规则之前，保持原样不迁移，历史版本可在 Git 历史中查阅。工单号/版本目录结构自 #47 起对新增原型生效。
|
||
|
||
### 自然语言快捷指令
|
||
|
||
快捷指令只是本工作流的别名，不能绕过方案确认、前置依赖、安全规则、工单范围、必要验证或人工验收：
|
||
|
||
- `只分析`：只读检查并给出方案；不建单、不修改。
|
||
- `建工单`：根据已确认方案创建单元工单；建单后停止。
|
||
- `执行工单 #N`：检查工单和依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照；停在待验收。
|
||
- `建工单并做`：依次建单和执行；停在待验收。
|
||
- `继续工单 #N`：优先核对当前状态、最新评论、Git 和必要 Wiki 证据，从首个未完成步骤继续；关键前提未变化时不重复分析仍有效内容。
|
||
- `检查工单 #N`：只读核对范围、验收、测试和证据；不自动修复。
|
||
- `同步文档`：读取 Wiki、导出核心 `docs/` 镜像并检查一致性；不修改 Wiki、不导出任务归档、不自动提交。
|
||
- `导出原型 #N`：人工触发导出指定工单已确认的原型版本，按工单和版本写入 `prototypes/`；不扩展范围、不自动提交。
|
||
- `导出全部原型`：人工触发导出当前项目明确范围内的全部已确认原型；不扩展范围、不自动提交。
|
||
- `导出任务归档`：人工触发 `python dev_scripts/harness.py export`，只导出新增或 revision 已变化的任务归档；`导出全部任务归档` 执行 `python dev_scripts/harness.py export --all`。
|
||
- `#N 验收通过`：仅在用户明确验收后记录验收结论、关闭工单并同步父工单；没有新的长期事实变化时不重复同步 Wiki。
|
||
|
||
### 需求记录与流转
|
||
|
||
- 创建单元工单时记录来源、提出时间和表达目的所需的少量关键原话或脱敏摘要；不复制完整聊天或 Agent 内部推理。
|
||
- 不得臆造用户原话；无法确认的表述记为假设并标注待确认。
|
||
- Gitea 工单全文不导出到仓库；标准任务不创建 Wiki 任务归档。既有任务归档和 `docs/task/` 只作历史兼容，用户明确要求专项快照时才使用 `archive` / `export`。
|
||
- 需求变化时先更新工单与设计证据并重新确认，再继续实施。
|
||
- 工单默认只在开始实施、集中回写待验收、验收关闭三个节点更新；只有根因、范围、主要方案、风险或阻塞发生重要变化时才追加过程记录。
|
||
|
||
### 效率与范围控制
|
||
|
||
本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、按文档影响触发的 Wiki 同步、Git 提交和人工验收要求。
|
||
|
||
#### 严格控制范围
|
||
|
||
- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
|
||
- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
|
||
- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于「额外验证」。
|
||
- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。
|
||
|
||
#### 渐进执行和修复
|
||
|
||
- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
|
||
- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
|
||
- 采用「执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑」的闭环。
|
||
- 不在真实证据出现前堆叠与已知风险无关的预防性检查。
|
||
- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布、创建订单或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。
|
||
|
||
#### 复用已验证事实
|
||
|
||
- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
|
||
- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
|
||
- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
|
||
- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。
|
||
- 真机验证结论只在同一设备、同一 App 版本和同一规则快照下复用。
|
||
|
||
#### 明确停止条件
|
||
|
||
- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
|
||
- 「最小验收条件」包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
|
||
- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
|
||
|
||
## 4. 工单层级
|
||
|
||
- Epic 维护长期目标与子工单索引，MVP 维护一次可交付范围，单元任务是唯一实施单位。
|
||
- 单元任务通过后才做 MVP 集成验收；MVP 通过后才关闭 MVP；Epic 全部范围完成后才关闭 Epic。
|
||
|
||
## 5. Git 与验证
|
||
|
||
- 提交只包含当前工单相关文件，提交信息引用工单号。
|
||
- 优先运行项目档案记录的格式、单元、契约和集成测试。
|
||
- Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不得仅为设置编码重复启动一层 PowerShell。
|
||
- 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。
|
||
- 不得默认使用 `-ExecutionPolicy Bypass`；只有可信 `.ps1` 确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。
|
||
- 涉及创建订单、权限、安全、并发、迁移和删除数据属于高风险，真机或正式实施前必须再次等待人工确认。
|
||
|
||
## 6. 完成与验收
|
||
|
||
1. 逐项完成验收、测试、实现提交和推送，并把最终方案、差异、结果、提交及遗留问题写回工单。
|
||
2. 工单保持「待验收」，用户没有明确验收通过前不得关闭。
|
||
3. 有长期文档影响时，在本次待验收前完成唯一一轮 Wiki 更新、在线回读、镜像同步与一致性检查，并把页面和 revision 写回工单；无影响时在工单说明原因并跳过。
|
||
4. 用户验收通过后只记录验收时间和结论，关闭单元工单并同步更新 MVP 和 Epic；没有新的长期事实变化时不重复 Wiki 同步。
|
||
5. 标准流程不创建 Wiki 任务归档，也不导出 `docs/task/`。`archive` / `export` 仅为历史兼容或用户明确要求的专项快照保留。
|
||
|
||
## 7. 文档影响
|
||
|
||
- 每个单元任务必须在工单中选择「无长期文档影响并说明原因」或列出需要更新的 Wiki 页面。
|
||
- 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。
|
||
- 部署命令或常驻服务运维方式变化时，更新项目自己的 `Deployment-and-Operations` 页面；可以从 `docs/templates/deployment.md` 复制章节结构，但必须按已验证的 GoAuto 环境改写，不得用模板占位值冒充事实。真实部署拓扑未确认时在工单记录限制，不创建虚假的部署说明。
|
||
- 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。
|
||
- Wiki 同步由长期事实变化触发，不由任务完成触发；同一任务的一轮 `sync` 加一轮 `sync --check` 即完成闭环。
|
||
- 必需核心页面及结构以 `python dev_scripts/harness.py check --strict` 为准。
|