AGENTS.md

1. 项目级约束

以下约束适用于整个仓库；具体设计、实现和审查规则由任务语义命中的项目技能提供，不在本文件重复维护。

• 仓库中的 Python 脚本统一使用 python3 运行；系统自带的 python 是 Python 2。
• 使用仓库固定的 Rust 2024 夜间工具链和 rustfmt 配置作为格式化事实来源。
• 可复用的内核、组件、内存、虚拟化和可移植驱动软件包优先使用 #![no_std]；只有软件包边界确实需要时才增加 alloc、std 或受功能开关控制的支持。
• 软件包和模块边界应与 TGOSKits 分层一致：可复用逻辑放在 components/、drivers/、memory/ 或 virtualization/，操作系统适配代码放在使用它的 ArceOS、StarryOS、Axvisor 或平台层附近。
• 公共接口和共享代码中的注释使用英文；面向项目的文档、拉取请求、议题、审查回复和讨论使用中文说明技术逻辑，命令、路径、代码标识符和标准正式名称可以保留原文。
• 判断项目技能是否适用时以行为语义为准，不以文件路径、拉取请求标题或作者声明代替判断。上下文被压缩或无法确信仍完整记得适用技能时，继续前重新读取相应技能。

2. 项目工作流

以下规则约束验证、持续集成、拉取请求和项目协作流程。

2.1 本地验证

项目任务工具负责展开软件包选择、功能组合和目标矩阵，并统一汇总失败结果；本地验证应使用这些稳定入口。

• 按实际改动选择能覆盖受影响行为、功能组合和目标的验证，完成本节及适用技能要求的检查。检查通过后，仅在新增改动、失败或未解决风险需要时扩大或重复验证；纯文档或技能说明修改只检查差异、引用及适用的文档或技能校验，不运行 Rust 构建和测试。
• 修改 Rust 代码后使用项目适配的 cargo xtask clippy 检查受影响的软件包及功能组合。未提交的改动使用 cargo xtask clippy --package <软件包>；cargo xtask clippy --since <引用> 只选择相对引用已提交的差异，使用前须确认本次改动已提交且选中受影响软件包。只有改动范围确实涉及全工作区时才使用 cargo xtask clippy 或 cargo xtask clippy --all，不得用原生 cargo clippy 命令代替。
• 改动需要标准库测试证明行为时，使用 cargo xtask test --since <引用> 验证受影响的软件包，并确认本次改动已提交且相应软件包被选中。直接修改 scripts/test/std_crates.csv 白名单时，白名单路径本身不会被 --since 选中；按 update-std-tests 验证变更条目。该入口不支持按软件包选择，不得用原生 cargo test 命令代替。
• 不得通过增加 allow 属性来回避静态检查警告；除非用户明确要求，否则应修复根因。
• 编辑 Rust 代码后运行 cargo fmt。
• 测试设计、必要性、去重和 Rust 测试布局统一遵循 test-quality。以最少且充分的测试证明完整通用功能；新增配置、参数取值、平台实例或历史问题不自动要求新增测试。
• 修复错误时，优先复用已有通用功能测试，必要时增强其判定；只有缺少独立行为证明时才新增。先确认同一测试在错误实现上必然失败，再实现或恢复修复，最后验证通过。不得只依赖修复后的证明、概率性复现程序或放宽后的测试。
• 构建、测试或运行 ArceOS、StarryOS 和 Axvisor 时，使用 cargo xtask 命令族，不直接使用 cargo build、cargo test 或 cargo run。
• 只有项目任务工具没有相应入口且任务明确需要特殊配置时，才检查 xtask 实现并使用原生 Cargo 命令手工匹配参数；不得把任务工具内部调用的原生命令当作项目验证入口。
• 解决变基或合并冲突时，不得手工合并发生冲突的 Cargo.lock 内容。先解决其他冲突，再用 Cargo 重新生成 Cargo.lock 并验证生成的锁文件。

2.2 持续集成与审查

持续集成配置和拉取请求审查使用仓库定义的证据链，不以临时本地命令或宽松检查替代项目门禁。

• .github/workflows/ci.yml 中自托管持续集成矩阵项的 cache_key 必须保持为空字符串（cache_key: ""）。非空值会在自托管运行器上启用 rust-cache 步骤，可能删除 Rust 或 Cargo 状态并破坏后续任务。
• 单项拉取请求审查执行 review-single-pr，批量审查执行 review-open-prs。在作出审查结论前，必须完整执行相应技能规定的持续集成前置门禁、技能路由、证据清单和当前提交复核。
• 执行拉取请求审查时不得运行本地格式化、构建、静态检查、测试、QEMU 测试、元数据、打包或发布验证命令。唯一运行时例外是技能明确允许的直接变更 apps/** 可运行应用，而且相同应用与目标缺少等价持续集成运行。
• 审查流程中的 CI_DEFERRED 和 CI_SKIPPED 是前置门禁状态，不是审查结论，不得发布到拉取请求。

2.3 拉取请求

面向项目的提交应保持中性、可追溯，并让标题、正文、验证记录和分支实际内容一致。

• 拉取请求标题遵循约定式提交的 type(scope): content 格式。一个软件包明显占主导时，优先把该软件包名作为 scope；跨领域或基础设施改动可以使用 ci、repo 或 docs 等较宽范围。
• 提交拉取请求时，标题使用英文，正文使用中文。正文必须说明要解决的问题、实际改动以及每一步方案背后的逻辑。
• 提交拉取请求前，按本次改动选择受影响软件包的 cargo xtask clippy，以及覆盖受影响行为与目标的定向 QEMU 或板卡测试；没有对应运行时影响时不强制运行 QEMU 或板卡。无需在本地复跑完整持续集成流程、全工作区 Clippy 或无关的架构与用例矩阵。
• 实体板卡或自托管环境无法本地执行时，在拉取请求中说明受影响而未验证的目标及原因。只修改文档或技能且不影响构建或测试时，按 2.1 节检查差异和引用即可。开发过程中由 2.1 节及适用技能要求的格式化、标准库测试和确定性回归证明仍按改动需要执行，不因提交拉取请求额外扩大范围。
• 分支新增或修改提交后，更新拉取请求描述，使其与已提交改动保持同步。
• 除非用户明确要求，不得加入与代理相关的标签、签名、品牌或宣传性措辞，例如 codex、agent、AI。
• 修改体系结构启动逻辑、someboot 启动顺序、统一可扩展固件接口交接、对称多处理启动、动态平台契约、目标描述文件假设或推荐调试流程时，在同一改动中更新 arch-platform-porting 技能或其参考资料。

2.4 授权与完成条件

从当前请求和会话中已有约定确定任务范围与交付物。用户明确指令优先于项目技能指引，但不绕过上层规则、工具权限或平台限制；读取技能本身不增加任务权限。

• “帮我修改”“修复”等行动请求授权连续完成范围内的读取、实现、必要验证和结果说明；“修复并提 PR”还包括提交、推送和创建拉取请求。阶段切换不重复询问“是否继续”；只读分析请求在给出结论和证据后结束。
• 优先从上下文和可读取资料补足信息，普通实现选择自行判断并说明必要假设。只有无法推断且会改变正确性、范围或交付目标的信息，或尚未获授权的破坏性、不可逆及外部写入操作，才需要询问。先完成不依赖该答案的已授权准备工作，再针对具体缺口询问；未获授权的合并、部署、发布和删除不由修复或提 PR 请求自动授权。
• 技能导致询问、暂停或交付不完整时，给出实际读取的 SKILL.md 路径、相关原文和适用原因，区分明确要求与自己的解释。业务规则冲突无法判断时保留原条款，说明冲突和影响，只暂停依赖该决定的步骤。
• 只修改授权范围内的文件，保留用户已有改动；范围外问题列为建议。通用授权与验证规则由本文件维护，技能只补充领域条件，避免重复规定不同的确认流程。
• 完成意味着请求的交付物已实现、必要检查已通过、最终差异已核对，并说明改动、验证证据和剩余限制。必要检查失败或受阻时明确报告未完成项及原因，不把计划、局部通过或运行中的 CI 当作整体完成；用户只要求检查点时按该边界交付。