Skip to content

Agent 项目操作规则

1. 适用范围

本文件适用于本仓库中的所有 Agent、自动化助手和后续维护会话。任何人在读取、设计、修改、测试或交付本项目时，都必须先阅读本文件以及 specs/constitution.md。

本项目采用规格驱动开发（Specification-Driven Development，SDD）。规格不是参考建议，而是实现、测试和验收的约束来源。

2. 规则优先级

出现冲突时，按照以下顺序处理：

  1. 用户在当前会话中的明确指令。
  2. specs/constitution.md 中的项目宪法。
  3. specs/ 下经过确认的专题规格。
  4. specs/tasks.md 中的任务顺序和完成条件。
  5. 当前实现、历史代码及工具默认行为。

低优先级内容不得覆盖高优先级要求。若冲突无法消解，必须停止操作并向用户说明，不得自行猜测。

3. 操作前确认

  • 不得擅自修改任何文件。
  • 修改前必须用中文说明修改目的、涉及文件、修改内容和预期效果，并等待用户明确确认。
  • 用户对已说明且范围明确的模块回复“ok”“继续”“做”或同义明确指令时，视为对该模块后续写入、真实测试、任务证据和已约定 Git 提交的连续授权；必须直接执行，不得再次请求相同确认，也不得发送“准备开始”“继续执行”等无实际操作、无新信息的消息。
  • sandbox_mode = "read-only" 与 approval_policy = "on-request" 为用户已配置的执行环境约束；它们不构成对已确认模块的重复确认理由。除真正新增权限、破坏性操作、规格冲突或缺失关键依赖外，必须连续完成当前模块，禁止询问“是否继续”。
  • 执行任何命令前必须说明用途。测试、构建、运行、生成文件、安装依赖、下载产物等操作必须获得用户确认。
  • 若完成当前已批准模块所必需的编译器、格式化器、测试工具、库、系统接口或其他依赖缺失，必须立即停止在安装步骤之前，用中文说明缺失项、必要性、推荐安装方式和安装后的确认命令；由用户自行决定并执行安装。未经用户针对该项安装的明确授权，禁止擅自安装，也不得以未声明的降级方案、替代工具或跳过检查掩盖缺失。
  • 不确定需求、边界、标准语义或破坏性影响时，必须先询问用户。
  • 未经明确要求，不得执行任何 Git 操作。
  • 不得回滚、覆盖或清理用户已有修改。

3.1 工作区安全边界

  • 默认将所有读取、修改、生成、构建和测试严格限制在仓库根目录及其子目录内。
  • 禁止修改、移动、删除或覆盖仓库外的任何用户文件、应用数据和系统文件。
  • 禁止擅自修改宿主机软件安装、环境变量、Shell 配置、系统服务、网络设备、路由、网桥、防火墙、DNS 或内核参数。
  • 命令必须设置仓库根目录为工作目录；不得使用用户主目录、文件系统根目录或未解析的变量作为递归操作目标。
  • 任务确需访问仓库外资源、标准系统接口或外部服务时，必须先解析精确目标，用中文说明必要性、影响和恢复方式，并等待用户对该项操作明确确认。
  • GitHub 远端创建、联网下载、依赖安装、TAP/网桥配置等均属于仓库边界之外的独立操作，不能从普通文档或代码任务中推定授权。

4. 规格驱动流程

每项实现必须遵循以下顺序：

  1. 找到对应规格和任务编号。
  2. 检查前置任务是否完成。
  3. 明确标准依据、输入、输出、错误路径和验收条件。
  4. 向用户说明拟修改范围并等待确认。
  5. 使用补丁进行最小且完整的增量修改。
  6. 经用户确认后执行与风险相称的真实测试。
  7. 记录实际结果，满足完成定义后才能勾选任务。

发现规格遗漏或冲突时，先修正规格并取得确认，再修改实现。不得让代码事实反向掩盖规格缺陷。

4.1 规格审查与纠错

  • PRD、专题规格和任务清单是实现基线，但编写规格时可能尚未覆盖后续发现的标准细节、硬件约束、协议边界与可验证性问题；Agent 不得把“照原文实现”当作忽略已知规格缺陷的理由。
  • 开始模块设计以及发现实现困难、测试冲突或标准歧义时，必须重新核对适用的官方架构规范、协议规范和项目总体目标，判断问题来自实现、测试还是规格本身，不能默认其中任意一方必然正确。
  • 若规格存在事实错误、内部矛盾、关键遗漏、无法验证的验收条件，或与正式标准不一致，必须先向用户说明问题、依据、影响范围和拟修订内容，取得确认后使用补丁同步修订 PRD、专题规格、任务依赖及验收标准，再继续实现。
  • 规格修订必须提高准确性、完整性和可验证性，不得为了迁就现有代码、减少工作量或让测试通过而删除正确要求、缩小必要范围、降低标准或改写完成定义。
  • 若原规格符合正式标准且工程上可以实现，只是实现复杂、耗时或当前代码尚不具备基础能力，则不得将其宣称为“不合理”；应保留原要求，并按依赖关系补齐真实实现。
  • 不得默默偏离规格。任何经确认的规格变更都必须保留可审阅的文档差异，并同步说明它对架构、代码、测试、任务状态和最终验收的影响。

4.2 完整模块批次

  • 每个模块开工前，必须一次列明计划新增、修改和删除的全部文件，并说明每个文件的职责及预期结果；没有删除文件时也要明确说明。
  • 在规格和全局架构已经限定边界的前提下，应以职责完整、可独立验证的模块作为实现批次。允许一个补丁同时新增或修改多个相关文件，不得为了形式上的渐进过程把一个完整模块人为拆成大量零碎写入。
  • 批次范围必须覆盖该模块的生产实现、真实测试、构建接线和必要文档，不得只完成容易部分，把关键语义以占位接口留给未定义的以后。
  • 写入前应完整检查模块依赖、错误路径、边界和验收条件；Agent 的处理能力不能成为省略设计审查的理由，也不能成为扩大已批准范围的理由。
  • 一个模块只有在严格构建、对应功能测试、回归测试和适用的动态检查全部通过后，才可以创建该模块的 Git commit。一个完整模块原则上对应一个可独立审阅和回退的 commit。

5. 禁止走捷径与伪造

  • 禁止使用 Mock、Stub、空实现、固定返回值或硬编码输出冒充真实功能完成。
  • 禁止使用宿主机现成功能绕过应由模拟器实现的 CPU、MMU、外设或协议语义。
  • 禁止仅凭编译成功、单元测试或快速冒烟测试宣称系统目标达成。
  • 禁止伪造测试日志、网络结果、Linux 启动状态、覆盖率或任务完成状态。
  • 禁止创建多套相互竞争的译码、内存访问、异常处理或设备逻辑。
  • 禁止为了让实现通过而删除、跳过、弱化或篡改测试，包括降低断言强度、只运行有利子集、吞掉失败和改变正确的预期结果。若测试本身违反正式规范，必须先给出可核对的规范依据，再修正错误测试并补充不弱于原覆盖面的正确断言。
  • 禁止用 TODO、FIXME、空分支或“以后实现”逃避当前批次必须完成的语义。确因已确认的下游依赖必须保留待办时，必须同时写明对应任务编号、阻塞原因、完成条件和清除节点，并在到达该节点时主动完成和移除标记。
  • 如阶段性测试必须使用测试替身，必须由对应测试规格明确许可、清楚标注范围，并且不得代替最终真实链路验收。
  • 未执行的检查必须明确写为“未执行”，失败的检查必须如实报告。

6. 架构与实现纪律

  • 遵循 SOLID 原则，模块职责单一，依赖方向明确，接口围绕稳定抽象设计。
  • 遵循 DRY 原则。寄存器语义、地址转换、总线访问、陷阱入口和 Virtqueue 解析等核心规则只能有一个权威实现。
  • CPU 只能通过统一内存访问入口进行取指和数据访问；物理访问只能通过统一总线分发。
  • 设备不得绕过总线或受控的 DMA 内存接口直接操作模拟状态。
  • ISA、CSR、异常编码和设备寄存器常量必须集中定义，禁止散落魔法数字。
  • 优先保证语义正确、边界清晰和可维护性，不得以开发速度为理由降低规格覆盖。

7. 文件修改规则

  • 必须使用 apply_patch 进行增量修改，不得通过整文件重写规避差异审查。
  • 当单个文件超过 90% 的内容确实需要改变、逐块补丁已失去审阅价值时，可以在说明原因后通过 apply_patch 替换该文件内容；仍禁止使用 Shell 重定向、脚本写文件或其他方式绕过 patch 记录。
  • 一个已批准模块可以在同一个 patch 中修改多个相关文件；“使用 patch”不等于必须把同一模块拆成多轮不完整补丁。
  • 在依赖清晰、验收条件可共同验证且失败能够准确归因的前提下，应将多个紧密相关功能合并为一个完整批次，统一实施、构建、回归和提交；不得人为拆碎成频繁确认。不得将跨层且错误难以定位的无关功能混入同一批次。
  • 新增或修改范围应与已批准计划一致。
  • 不得顺手格式化、重命名或调整无关文件。
  • 发现工作区已有改动时必须保留；若与任务冲突，应停止并请用户决定。
  • 仓库内出现的项目文件和目录路径必须使用从仓库根目录开始的相对路径，例如 specs/tasks.md；禁止写入任何宿主机用户目录或工作区绝对路径。
  • 文档、配置、脚本、诊断信息和测试证据都不得依赖某台机器的绝对工作区位置。确需引用系统设备节点（例如 /dev/net/tun）时，必须明确标注其为宿主系统接口，而不是仓库文件路径。
  • 临时文件和工具输出也必须放在仓库内已批准且被忽略的相对目录；不得借用用户桌面、下载目录或系统临时目录保存项目产物，除非用户针对精确目标另行批准。

8. 中文注释规范

每个代码文件必须包含：

  • 文件开头的中文意图注释：说明职责、边界、主要依赖和明确不负责的内容。
  • 所有对外类型、接口、函数以及包含非平凡语义的私有函数都必须有中文注释：说明设计意图、参数、返回值、状态变化、失败路径、异常及并发约束。紧邻且语义完全一致的简单访问器可以使用一段分组注释，但不得让维护者依赖阅读实现来猜测关键行为。
  • 长函数、复杂条件、位域处理、特权规则、页表漫游、原子操作、描述符链等关键位置的中文注释。
  • 解释“为什么”的注释，而不是逐句复述代码。

注释完整性与代码正确性同等属于完成条件。禁止以时间、篇幅或代码“看起来直观”为理由省略文件意图、函数职责、长难逻辑和关键不变量注释。

注释必须与实现同步，禁止保留错误、模糊或过期说明。

9. 测试与验收纪律

  • 测试必须覆盖成功路径、边界条件、权限拒绝、非法输入和状态转换。
  • 指令、CSR、Sv39、VirtIO 等行为应对照对应正式规范验证。
  • 单元测试不能替代真实 OpenSBI、Linux、rootfs、VirtIO 和 TAP 的系统集成验证。
  • 最终网络验收必须由来宾 Linux 通过 eth0 获取地址，并在真实网络链路上完成域名解析和 ICMP 测试。
  • 环境限制导致无法执行验收时，只能报告受阻，不得降低验收标准或勾选任务。

10. 外部产物与 Git

  • OpenSBI、Linux 内核、rootfs、磁盘镜像和下载缓存均为外部或构建产物，不得提交到 Git。
  • 下载前必须确认来源、版本、许可证和校验值，并先获得用户许可。
  • .gitignore 的实际修改属于独立实施操作，必须另行说明并获得确认。
  • 用户要求 Git 操作时，每一步都要用中文说明。
  • Commit 信息必须使用中文，主题清晰，正文说明原因和关键变更，总计不超过 10 行。
  • 不得主动执行 add、commit、push、pull、merge、rebase、reset 或 checkout。

11. 完成状态

只有满足规格、实现完成、真实测试通过、文档同步且不存在已知阻断问题时，任务才可以从 - [ ] 更新为 - [x]。若仅完成部分工作，应拆分或记录证据，不得提前打勾。