# Agent 开发规则 本仓库采用 DevHarness 工作流：Gitea 工单是任务过程的事实来源，Gitea Wiki 是长期开发文档和任务归档的事实来源，Git 是代码与版本绑定资料的变更记录。`docs/` 默认保存核心 Wiki 的只读镜像，`docs/task/` 只保存人工按需导出的任务归档快照。人负责确认方案与验收，Agent 负责检查、实现、测试和留下证据。 开始工作前先阅读任务涉及目录中的 `AGENTS.md`。目录越深的规则越具体，但不得削弱上级安全规则。 [项目档案](docs/00-project-profile.md) 按需阅读，不作为每次任务的固定前置。出现下列情况之一时必须读：需要环境、配置或凭据来源；需要确认目录边界；需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。只为查命令不必打开项目档案。 ## 常用命令 所有命令默认从仓库根目录执行，与项目档案保持一致。 | 用途 | 命令 | |---|---| | 查看工作区 | `git status --short --branch` | | 检查模板结构 | `python dev_scripts/harness.py check --strict` | | 运行单元测试 | `python -m unittest discover -s tests -v` | | 导出核心 Wiki 镜像 | `python dev_scripts/harness.py sync` | | 检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --check` | | 创建任务归档 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | | 增量导出任务归档 | `python dev_scripts/harness.py export` | | 全量导出任务归档 | `python dev_scripts/harness.py export --all` | ## 1. 永久规则 - 不把密码、令牌、Cookie、私钥、个人数据或生产数据写入代码、日志、工单、Wiki 和文档。 - 不执行未经用户明确授权的发布、付款、删除数据、破坏性迁移或其他不可逆操作。 - 保留用户已有和任务无关的工作区改动，不擅自重置、覆盖或混入提交。 - 发现需求与安全规则、已确认方案或现有数据冲突时，先停止实施并说明影响。 - 测试结果必须真实；未执行或无法覆盖的验证必须明确记录。 项目专用红线写入本文件的“项目专用规则”或对应子目录的 `AGENTS.md`，不要散落在聊天记录中。 ## 2. 哪些改动需要工单 新功能、缺陷修复、重构以及任何用户可感知或改变程序行为的修改，必须先建立单元任务工单。 以下小改动可以直接提交，不要求工单和任务归档： - 只改错别字、注释或文档措辞； - 只做格式化、导入排序或不跨文件的内部变量改名； - 补充类型标注或文档字符串且不改变行为； - 删除已经确认无人使用的死代码。 - 只修改用户看到的界面显示文案，并且满足本文件“工单与设计证据双门禁”的全部豁免条件。 除严格符合界面显示文案豁免的修改外，只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。 ## 3. 需求到实施 1. 先复述目标，阅读相关代码、日志和文档，区分事实与假设。 2. 给出目标、非目标、方案、影响范围、风险、回退方式、验证方法和文档影响。 3. 方案没有得到用户明确确认前，只做只读诊断和方案整理，不实施正式代码。 4. 方案确认后，先建立单元任务工单，再修改代码。 5. 建立新工单不要求其他工单已经完成；开始实施前检查工单声明的前置工单。真实依赖未满足时保持“待实施”，允许并行时必须写明原因。 6. 开始实施前检查分支和工作区，明确哪些现有改动不属于本任务。 7. 严格按工单范围实现；新发现的问题先记录，不顺手混入当前任务。 8. 执行与风险相称的测试，把关键结果和未验证部分更新到工单。实施过程中出现计划外、当前无法解除的问题时才标记“阻塞”。 9. 长期核心文档必须先修改 Wiki、读取确认，再运行 `python dev_scripts/harness.py sync` 导出本地镜像；任务归档默认只更新 Wiki，不自动导出本地。不得直接编辑镜像后反向覆盖 Wiki。 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。 ### 新项目 Wiki 初始化门禁 - 从本模板创建新项目时，先创建 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 和核心镜像初始化完成。 ### 工单与设计证据双门禁 - 纯界面显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、法律/安全/支付/单位等高风险含义、国际化键、程序标识符、布局和可访问性，且没有任何不确定时，才免工单和原型；修改后执行最小界面检查。 - 新页面、独立用户功能、重大交互或导航变化，必须先用 Quant-UX 或其他合适工具制作可审阅原型；用户确认原型、文字需求和覆盖范围后，才能建立或放行实现工单并编写生产代码。 - 上述完整原型形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照，保存到 `prototypes/<工单号>/<版本>/index.html`；版本目录内资源使用相对路径。可编辑设计源仍在原设计工具，Git HTML 是版本化审核证据，Wiki 和工单只保存索引。 - 已确认的 HTML 快照不得原位覆盖；页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。提交审核前检查入口、主要交互和资源完整性，并删除凭据、账号、个人信息和生产数据。 - 现有界面的小范围样式或布局调整使用标注截图、低保真图或明确复用的现有规范；新组件记录状态、错误和边界。两者只要不符合纯文案豁免就必须建单。 - 后端、接口、数据处理和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计；恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。 - 需要设计证据的工单记录链接或路径、版本/revision 或日期、状态、确认人、确认时间和覆盖范围；没有 UI 原型时记录替代技术设计或原因。 - 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，必须更新原型或文字需求并重新确认后再继续正式编码。 - 草稿原型可以用于讨论；写入 Git/Wiki、多人协作或单独实施时建立设计任务。草稿和经明确授权的隔离技术验证都不得直接作为生产实现。 - 设计工具无法生成可用 HTML 时，在工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不得只保留难以访问的线上链接后直接编码。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。 ### 自然语言快捷指令 快捷指令只是本工作流的自然语言别名，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收： - `只分析`：只读检查并给出方案；不建单、不修改，停在等待确认。 - `建工单`：根据已确认方案创建单元任务工单；建单后停止，不修改代码。 - `执行工单 #N`：检查工单和依赖，实施、测试、提交、归档、推送并回写证据；停在“待验收”。 - `建工单并做`：依次建单和执行，`建工单，做`、`建工单,做` 含义相同；停在“待验收”。 - `继续工单 #N`：核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查。 - `检查工单 #N`：只读核对范围、验收、测试和证据并输出报告；不自动修复。 - `同步文档`：读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档；不修改 Wiki、不自动提交。 - `导出任务归档`：人工触发 `python dev_scripts/harness.py export`，只导出新增或 revision 已变化的任务归档；不删除本地文件、不自动提交。 - `导出全部任务归档`：人工触发 `python dev_scripts/harness.py export --all`，读取并导出全部线上任务归档；不删除本地文件、不自动提交。 - `#N 验收通过`：仅在用户明确验收后，更新 Wiki 归档、同步必要的核心文档、推送、同步父工单并关闭任务；不自动导出任务归档。 方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 `#N 验收通过` 外，快捷指令不得关闭待验收工单。任务归档导出必须由用户明确提出，其他指令不得隐式执行。Gitea 工单不导出全文，`docs/task/` 只是可能不完整的 Wiki 任务归档快照。详细语义见 [开发工作流](docs/01-workflow.md)。 ### 需求记录与流转 - 创建单元任务工单时，记录原始需求的来源、提出时间，以及能表达用户目的、场景和限制的少量关键原话或脱敏摘要；不得臆造用户原话。 - 工单中的目标、非目标、已确认方案、验收标准和文档影响构成确认后的正式任务需求。 - 影响范围、接口、数据、风险或验收的需求变化必须记录日期、内容、原因和用户确认；会改变已确认结果时先更新工单并等待再次确认。 - 不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据；包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。 - 长期有效的产品需求、业务规则和系统边界进入对应 Wiki 主题页并导出核心 `docs/`；完成结果进入 Wiki 任务归档，仅在用户明确要求时导出 `docs/task/`。Gitea 工单全文不导出到仓库。 详细记录边界见 [开发工作流](docs/01-workflow.md) 与 [业务规则和术语](docs/03-business-rules-and-glossary.md)。 ### 效率与范围控制 本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 #### 严格控制范围 - 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。 - 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。 - 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。 - 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。 #### 渐进执行和修复 - 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。 - 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。 - 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。 - 不在真实证据出现前堆叠与已知风险无关的预防性检查。 - 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。 #### 复用已验证事实 - 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。 - 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。 - 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。 - Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。 #### 明确停止条件 - 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。 - “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。 - 未影响当前验收的相邻问题只提示或建单，不顺手处理。 ## 4. 工单层级 - 单元任务是唯一正式实施单位，记录方案、范围、验收标准、过程和测试结果。 - Epic 和 MVP 只维护目标、风险、汇总及 `- [ ] #编号` / `- [x] #编号` 子工单索引，不复制单元任务全文。 - 新任务先建单元工单，再把编号同步到所属 MVP 和 Epic。 - 详细层级、状态和模板入口见 [开发工作流](docs/01-workflow.md) 与 [业务规则和术语](docs/03-business-rules-and-glossary.md)。 ## 5. 实施中的变化 - 范围、接口、数据结构、依赖、验收标准或风险变化时，先更新单元工单。 - 变化影响 MVP 或 Epic 时，同时更新父工单。 - 会改变用户已确认结果的变化，更新工单后必须再次等待用户确认。 - 阻塞、失败方案和新发现根因不能只留在聊天或代码注释中。 - Wiki 页面删除、重命名或事实源边界变化时，必须先更新工单并等待用户确认；同步工具不得自动传播删除或重命名。 - 工单状态应使用：待确认、待实施、进行中、阻塞、待验收、已完成。 ## 6. Git 与验证 - 提交只包含当前工单相关文件。 - 实现提交信息引用工单号，例如：`fix: 修复登录超时 (#123)`。 - 不为流程制造空提交。 - 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。 - 不能验证的真机、生产、迁移或并发行为必须写入工单和归档。 ## 7. 完成、验收和归档 1. 逐项完成验收、测试和实现提交，并把最终方案、差异、结果、提交及遗留问题写回工单。 2. 工单保持“待验收”，用户没有明确验收通过前不得关闭。 3. 运行 `python dev_scripts/harness.py archive <编号> "<短标题>"`，只创建 Wiki 任务归档，不登记或导出本地镜像。 4. 读取确认 Wiki，运行 `python dev_scripts/harness.py sync --check` 检查核心镜像，并把任务归档页面、revision 和提交哈希写回工单。只有用户明确提出时才增量或全量导出任务归档。 5. 用户验收通过后关闭单元工单，并同步更新 MVP 和 Epic。 MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才能关闭 MVP。Epic 的全部范围完成后才能关闭 Epic。 详细归档顺序和字段见 [开发工作流](docs/01-workflow.md)。 ## 8. 可维护性 - 优先使用直白、常见的实现；不要为了少写几行引入晦涩技巧。 - 类和函数保持单一职责，名称表达业务含义。 - 注释解释原因、边界和风险，不逐行翻译代码。 - 错误必须可定位，不静默吞掉失败。 - Wiki 文档先写结论和用途，再写步骤；示例命令应可直接复制，本地 `docs/` 由同步工具生成。 - 面向初级维护者说明从哪里开始读、怎样运行和怎样验证。 ### 修改风险 - 低风险修改可由初级程序员在 Agent 协助下处理；接口、配置、依赖、跨模块逻辑和数据结构由 Agent 实现并验证。 - 权限、安全、并发、迁移、支付、删除数据和不可逆操作属于高风险；高风险修改必须停止，由 Agent 分析并等待人工确认。 - 风险按影响范围判断，不按代码行数判断；示例见 [常见修改指南](docs/05-common-changes.md)。 ### 文档影响 - 每个单元任务必须在工单中选择“无长期文档影响并说明原因”或列出需要更新的 Wiki 页面。 - 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。 - 部署命令变化时，有常驻服务的项目更新自己的 `Deployment-and-Operations` 页面（由 [部署文档模板](docs/templates/deployment.md) 复制建立）；没有常驻服务的项目记录为无部署文档影响，不创建空的部署页。 - 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。 - 必需核心页面及结构以 `python dev_scripts/harness.py check --strict` 和 [新项目文档初始化](docs/07-new-project-documentation-setup.md) 为准；稳定文档与任务归档的分工见 [开发工作流](docs/01-workflow.md)。 ## 9. 引导提交例外 从本模板创建全新仓库时，Gitea 远端和工单尚不存在，允许一次不带工单号的初始引导提交。该提交只能包含仓库骨架、Harness 规则和远端配置准备，不能包含产品功能。 远端建立并推送后，这个例外立即失效。 ## 10. 项目专用规则 - 长期开发文档以 Gitea Wiki 为事实来源，`docs/` 默认保存显式映射生成的核心只读镜像；`docs/task/` 是人工按需快照，可能不完整或不是最新状态。 - 核心 Wiki 与镜像的固定顺序是：修改 Wiki → 读取确认 → 导出核心 `docs` → 校验差异 → 提交镜像。 - 任务归档默认只保存在 Wiki；`导出任务归档` 或 `导出全部任务归档` 必须由用户明确提出，且不得自动传播删除或重命名。 - 同步配置只允许写入 `docs/` 下的 Markdown；发现镜像有未提交修改时必须停止。 - Gitea 凭据只通过进程环境或 MCP 安全配置提供，不得写入仓库。 - `dev_scripts/` 只存放 DevHarness 自身工具；业务项目的通用脚本必须使用独立目录，不得混放。