架构与贡献图
当某项变更不止是修正拼写错误，而你又不确定应参照哪些架构、基础、贡献者或维护者文档时，请查阅本页。
本页面仅作为导航索引，链接的文件仍为权威来源。
从这里开始
- 首先阅读仓库根目录中的
AGENTS.md。其中包含简明且始终加载的安全与贡献约定。 - 阅读如何贡献，了解 PR 机制、验证要求和评审流程。
- 请使用下表选择与变更相匹配的架构和基础文档。
- 当 AI 编码任务需要详细的权威示例、风险与稳定性策略、技能发现或受保护的操作文档时，请参阅编码代理指南。
- 如果该变更涉及子系统、配置、安全、工作流、治理或发布等边界，请在实施前查看 RFC 流程。
常见变更路径
| 更改 | 请先阅读 | 为什么 |
|---|---|---|
| 新的提供商 | 架构概览, Crates, 自定义提供者, 提供者配置 | 提供程序是位于 provider trait 后的边缘适配器，包含配置和工厂装配。 |
| 提供商配置选择、模型路由、会话覆盖、运行时模型切换、重试、回退或提供商归属 | 提供商路由生命周期、路由、提供商配置 | 将路由选择、尝试策略、配置文件构建以及请求与实际提供内容之间的归因保留在各自所属的层中。 |
| Provider 流解析、终止或回合级重放 | 提供商路由生命周期、流式传输、测试 | 将线级完成处理保留在适配器中，将整次调用的重放保留在运行时中。不可变事件输出一旦可见，绝不再进行重放。 |
| 新频道 | 架构概览, Crates, 通道运行时生命周期, 通道概览, crates/zeroclaw-channels/ 中的现有实现 | 通道是用户可见的信任边界；验证入站、出站、配对、授权、分发和回复生命周期行为。 |
| 通道分发、webhook 入口、回复意图、流式草稿、监听器生命周期，或通道重载行为 | 通道运行时生命周期, 请求生命周期, Gateway HTTP API, 插件协议, 测试 | Channel 生命周期变更需要单一的 dispatch 和 turn 路径，而不是一次性的 adapter 或 gateway 小型 orchestrators。 |
| 新增内置工具或工具策略 | 工具概览, 内置工具清单, 工具执行生命周期, ADR-004：工具共享状态所有权, 插件协议, 安全概览, 工具凭证 | 工具为代理执行操作。首先检查该能力是否属于 core，然后验证注册、审批、派发、审计、收据、本地化、归因以及共享状态所有权。 |
| 运行时、代理循环、状态、提供商令牌流式传输或工具循环行为 | 请求生命周期, 运行时状态与持久化, 工具执行生命周期, Crates, FND-001, 测试 | 运行时更改通常会影响多个用户路径，因此需要边界级测试。Provider token 流仍由 runtime 拥有；channel 草稿或输入指示器流则遵循 channel 生命周期行。Tool-loop 更改应注明它们是否影响审批、分发、回执、observer 事件、历史记录或取消。 |
| Cron、SOP、委派、子代理、目标模式、等待、取消或重启恢复行为 | 后台工作生命周期、委派与子代理、测试 | 后台执行并非单一的生命周期。请明确当前的所有者和状态展示界面，区分持久化记录与可在重启后恢复的工作，并在发生变更的边界处验证取消与恢复行为。 |
| 内存、会话历史、提示上下文、工具结果、文件/媒体载荷或上下文裁剪 | 内存和负载生命周期, 运行时状态与持久化, 历史管理, 运行时内部机制, 测试 | Payload 变更需要明确 owner、scope、durability、privacy 和 truncation 边界。 |
| 日志记录、可观测性、运行时跟踪持久化、日志分页、日志保留或架构迁移 | 日志架构、日志与可观测性、运行时状态与持久化、网关 HTTP API、安全概述、测试 | 同一个规范事件会分别独立提供给实时广播和持久化 JSONL；可选的类型化 Observer 投影仅在绑定时运行。验证投影字段、活动文件游标的生命周期、重写和保留行为、迁移兼容性，以及变更后目标位置的隐私性。 |
| 网关、Web API 或仪表板行为 | 网关 HTTP API、构建 Web 仪表板、请求生命周期、安全概述、审阅者操作手册 | Gateway 更改可能会影响 auth、公开暴露、生成的 API contracts、dashboard 消费者以及 review 风险。对于 webhook dispatch 或 reply 行为，请使用 channel lifecycle 行。 |
| 命令、终端、守护进程、浏览器、频道、提供程序、工具、后台任务或安装路径的用户可见行为或验证证据 | 用户边界证明、测试以及所修改范围的架构或功能文档 | 将每个行为声明与能够到达用户可观察到的边界的最小可信证据相匹配。仅针对自动化覆盖中已明确指出的缺口，才补充手动或特定于环境的证据。 |
| 配置模式、环境变量、默认值或重新加载行为 | 配置生命周期, 环境变量, 运行时状态与持久化, 提供方配置, FND-001, RFC 流程 | 配置更改会影响升级路径、重载行为、事实来源边界，并且可能需要迁移或 RFC 讨论。 |
| 生成的参考文档、mdBook 预处理器、文档片段或文档部署 | 生成文档流水线、本地构建文档 以及配置生命周期，在配置引用发生变更时。 | 命名规范来源、物化器、追踪或仅构建的输出、消费者以及漂移检查。 |
| Fluent/gettext 目录、区域设置注册表、翻译回退机制或目录发布版本锁定 | 本地化目录生命周期、文档与翻译、生成文档流水线 | 仓库中存在目录并不能证明运行时或站点构建过程会使用它。请验证加载器、物化器或固定引用路径。 |
| CI、发布、GitHub Actions 或允许的操作 | CI 与 Actions、FND-004、PR 工作流 | 当基础设施变更改变了可运行或可发布的代码范围时，其风险较高。 |
| 文档结构、贡献者指南或知识组织 | FND-002、文档与翻译、本页 | 文档变更应降低查找成本并保留决策追溯记录。 |
| 治理、标签、看板工作流或贡献流程 | FND-003、RFC 流程、标签、审阅者手册 | 流程变更会影响维护者和贡献者；请确保其稳定且明确。 |
| AI 辅助贡献、替代或审查文化 | FND-005、替代 PR、PR 评审协议 | 欢迎使用 AI 辅助工作，但人类发起者需对准确性、署名和评审回应负责。 |
| 生产代码健康度、错误处理或死代码清理 | FND-006、Testing、仓库根目录 AGENTS.md | 错误处理规范、无用代码和生产就绪性是评审的硬性门槛，而非风格偏好。 |
一屏掌握基础文档
| 基础 | 读取以下情况：当变更要求…… |
|---|---|
| FND-001：有意架构设计 | 这是否符合微内核/运行时方向？应该由哪一层来负责？ |
| FND-002：文档标准 | 知识应该存放在哪里？文档应如何保持易于查阅和持久可用？ |
| FND-003：治理 | 谁来决定？应由哪些标签、项目看板或 RFC 流程来承载该状态？ |
| FND-004：工程基础设施 | CI、发布自动化或 GitHub Actions 应如何运作？ |
| FND-005：贡献文化 | 贡献者、维护者以及借助 AI 协助完成的工作应如何沟通与审查？ |
| FND-006：实践中绝不妥协 | 生产代码、错误处理、无用代码和发布就绪性适用什么质量标准？ |
编码代理入口点
编码代理应使用与人类相同的公共文档，外加仓库本地的代理契约。
- 遵循仓库根目录的
AGENTS.md。检查.claude/skills/*/SKILL.md，并在适用时使用仓库中匹配的技能；技能文件具有权威性。 - 将基础文档视为决策依据。它们解释了为什么评审可能会要求拆分、提交 RFC、加强验证或更换负责人。
- 请勿在公开的 PR 内容、issue 评论和评审中暴露私有的工作流机制。公开文本应引用具体行为、源码路径、命令、验证证据、关联的 issue 以及用户可见的风险。
- 如果生成的或由技能编写的草稿与源代码、当前的
AGENTS.md或已批准的基础文档存在冲突，请先停止并进行协调，然后再发布或实施。
RFC 与 PR 检查点
此映射不会取代 RFC 流程或 PR 模板；它只是帮助你找到正确的文档。RFC 流程包含权威的“这是否符合 RFC 形态？“表格，因此请查阅该表格，而不要根据这里重新陈述的列表来猜测。在 RFC #6808 策略切片提升后，请遵循 FND-003、标签、PR 工作流和评审者手册。
- 如果某个变更含义模糊但又并非明显属于 RFC 范畴，请在实现之前咨询维护者或缩小该 PR 的范围。
- 在创建 PR 之前，请先回答 PR 模板（
.github/pull_request_template.md）中的提示。如果这些答案不够清晰，请先撰写设计说明或 RFC。