编程智能体指南
仓库根目录下的 AGENTS.md 是面向 AI 编码助手的精简且始终加载的契约。本页提供对某些任务有用的详细信息，但不应占用每个会话的提示词预算。
无论模型大小或模型运行位置如何，这些规则均适用。精简提示配置可能会改变主动加载的上下文数量；但不会削弱安全性、隐私性、授权或贡献方面的要求。
如何使用本页面
从架构和贡献映射开始。其变更路径表会将每项任务指向当前的架构、基础、测试、安全和维护者文档。仅在需要查阅以下特定于代理的主题时才返回这里。
单一数据源示例
任何状态都不应同时存在于两个独立维护的位置。如果某项事实已存在于配置、架构、运行时状态或生成的定义中，应从该来源解析或派生，而不是将其复制到另一个字段中。
在添加结构体字段、通道或句柄字段、schema 字段或配置项之前，请先给出以下答案之一：
- “这是唯一事实来源，在此创建。“说明它代表什么。
- “权威来源是
<path>；这样会将其复制一份。“在使用时从该位置解析它。
不要将重复状态的清理推迟到后续步骤。仅用于重启的快照仍然是重复状态。
禁止的示例：
- 频道句柄，用于缓存已授权用户，而实时配置负责管理这些用户；
- 一个枚举和一个单独手动维护的变体列表；
- 一个配置快照，克隆运行时可从实时配置中读取的字段；
- 将提供商凭证复制到另一个运行时字段中。
允许的示例：
- 解析器通过闭包捕获
Arc<RwLock<Config>>； - 借用的
Config或类型化配置参数； - 不会在操作结束后保留的按需视图；
- 宏或生成器，从单个输入生成多个 surface。
架构与所有权
ZeroClaw 是一个 Rust 优先、trait 驱动的智能体运行时。主要扩展 trait 位于 crates/zeroclaw-api/src/：
model_provider.rs(ModelProvider)channel.rs(Channel)tool.rs（Tool）memory_traits.rs(Memory)observability_traits.rs(Observer)runtime_traits.rs(RuntimeAdapter)peripherals_traits.rs（Peripheral）
不要在此处维护另一个 crate 或仓库清单。使用 Crates 了解所有权和依赖方向，使用根目录 Cargo.toml 中的工作区成员了解当前成员关系，并使用架构图了解 provider、channel、tool、plugin、runtime 和 config 的变更路径。
稳定性与风险
稳定性级别定义和版本控制策略位于 FND-001。组件本地 AGENTS.md 文件和插件注册表清单是目标所有权模型。在每个组件都拥有各自文件之前，下表是当前分配的权威来源；请勿将其复制到另一个手动维护的汇总中。
当前稳定性分配
| 组件 | 层级 | 备注 |
|---|---|---|
zeroclaw-api | 实验性的 | 自 v1.0.0 起稳定（正式里程碑） |
zeroclaw-config | Beta | v0.8.0 版本已稳定 |
| zeroclaw-log | Beta | 统一日志输出、JSONL 持久化和广播钩子 |
zeroclaw-providers | Beta | |
zeroclaw-memory | Beta | |
zeroclaw-infra | Beta | |
zeroclaw-commands | 实验性的 | 内置命令目录与元数据 |
zeroclaw-tool-call-parser | Beta | v0.8.0 版本已稳定 |
zeroclaw-channels | 实验性的 | v1.0.0 版本的插件迁移 |
zeroclaw-tools | 实验性的 | v1.0.0 版本的插件迁移 |
zeroclaw-runtime | 实验性的 | 智能体运行时：智能体循环、安全性、cron、SOP、技能和可观测性 |
zeroclaw-gateway | 实验性的 | 在 v0.9.0 版本中拆分二进制文件 |
zerocode | 实验性的 | TUI 入门向导 |
zeroclaw-plugins | 实验性的 | WASM 插件系统及 v1.0.0 插件生态系统的基础架构 |
zeroclaw-hardware | 实验性的 | USB 发现、外设和串行支持 |
zeroclaw-macros | Beta | 与配置架构紧密耦合 |
zeroclaw-eval | 实验性的 | 具备 LLM 追踪固件确定性回放能力的智能体评估框架 |
zeroclaw-spawn | Beta | 归因传播的 tokio::spawn 包装器，基于 zeroclaw-log 构建 |
稳定组件遵循破坏性变更策略。测试版组件可能在 MINOR 版本中进行破坏性变更，并附带变更日志说明。实验性组件不提供任何稳定性保证。层级只会通过团队的审慎决策进行提升，绝不会降级。
变更风险路由基于影响，而非路径。请参阅维护者标签指南中的规范定义：risk:low涵盖不会对生产、兼容性、构建、发布或治理产生影响的文档、测试夹具和机械性元数据；risk:medium涵盖常规行为变更；risk:high涵盖具体的信任、凭据、兼容性、治理或发布权限边界。domain:security独立于risk:*，用于标识实际的安全边界。
包含 risk:high 或 domain:security 任一标签的 PR，在合并前需要经过深入审查，并获得两次独立的 Core Team 批准。应将不确定性向更高等级分类。验证和回滚证据应与实际影响范围相匹配，而不应只依据变更行数。有关 PR 流程，请参阅 如何贡献；有关验证分类体系，请参阅 测试。
技能发现
仓库专属的编码助手技能存放在 .claude/skills/ 目录中。请检查可用的 */SKILL.md 文件，并仅加载与所请求操作匹配的技能。请勿在本页面维护第二份技能目录；该目录即为当前清单，每个技能文件负责管理其自身的工作流。
受保护的操作文档
这些文件由技能或开发工具使用。除非同时更新其使用方和仓库指南，否则不要移动或删除这些文件。
| 文件 | 消费者 |
|---|---|
docs/book/src/contributing/pr-review-protocol.md | PR 审查技能 |
.claude/skills/changelog-generation/SKILL.md | 变更日志技能加载器和发布运行手册 |
docs/book/src/maintainers/reviewer-playbook.md | 问题分流技能 |
docs/book/src/maintainers/pr-workflow.md | 问题分类与维护者工作流程 |
docs/book/src/contributing/privacy.md | Issue 和 PR 隐私门控 |
docs/book/src/foundations/fnd-00*.md | 审查架构参考资料 |
本地化与隐私
面向用户的文本和纯英文日志规则仍保留在根目录的 AGENTS.md 中。Wiki 和内部开发者文档同样仅使用英文。完整规约请参阅 Privacy and PII discipline 和 Docs and translations。