id: ADR-012 title: 实时配置应用采用按代际限定范围的发布和结果 date: 2026-07-19 status: proposed relates-to:

• https://github.com/zeroclaw-labs/zeroclaw/issues/7897
• docs/book/src/architecture/config-lifecycle.md
• crates/zeroclaw-config/src/schema.rs
• crates/zeroclaw-gateway/src/api_config.rs
• crates/zeroclaw-channels/src/orchestrator/mod.rs

ADR-012：实时配置应用使用代际范围的发布与结果

上下文

ZeroClaw 可以通过 CLI、RPC、TUI、Quickstart 和网关界面保存配置。保存成功并不意味着每个长期运行的子系统都已采用新值。网关可见状态可能立即发生变化，而守护进程拥有的通道、会话、提供程序及其他组件将继续使用其先前的运行时状态，直到 /admin/reload 重建子系统图为止。

已接受的 RFC #7897 针对有界改进：选定的安全策略和通道变更可在无需完整守护进程重载的情况下生效，同时运维人员可针对每个子系统实际处理的代次收到特定目标的结果。已接受的架构要求一份规范的已发布配置、特定代次的结果、范围受限的安全覆盖层，以及仅使用经过验证的通道过渡模式。

此记录定义了该目标及其实现门槛。它并不声称实时应用已经存在。在这些门槛发布之前，配置生命周期 中描述的当前已保存与已应用行为以及 /admin/reload 回退机制仍然为准。

决策

发布一个规范的配置生成

该进程有一个规范化的已发布配置修订版本。进程内的写入者与读取者分别进行序列化处理。写入者会克隆当前修订版本，应用并验证其变更，在序列化写入事务中持久化生成的配置，然后才会原子性地发布下一代版本。编辑 config.toml 的独立进程之间的协调不在本决策范围之内。

面向读取方的配置锁不会在异步磁盘 I/O 期间一直持有。发布不会创建第二个长期存在的配置缓存，也不会保留先前的配置快照用于常规回滚。

Apply 事件标识已发布的代次和已更改的路径。它们不携带另一个完整配置副本或先前的配置值。每个目标都会读取当前规范修订版本，并且仅在其代次与事件匹配时才应用它。被取代的事件会被跳过，无法覆盖较新代次的结果。

记录实际应用的生成结果

每个 apply 目标都会记录其自身特定于世代的结果：

• AppliedLive 表示目标在无需重新加载守护进程的情况下采用了所标识的生成版本。
• QueuedForReload 表示更改已保存，但该目标需要执行 /admin/reload；结果中包含具体原因。
• Rejected 表示目标拒绝对该生成版本执行实时应用；结果包含具体原因。

较旧世代的目标完成状态无法覆盖较新世代的状态。配置状态报告呈现目标结果，而非从变更路径前缀推断出单一的全局应用状态。

保持已获批准的安全覆盖层范围较窄

已批准的安全实时应用边界仅涵盖 allowed_commands 和 forbidden_paths。当这些字段发生变化时，它会保留现有的 SecurityPolicy 及其速率限制跟踪器，而不是重新构建策略。

执行会接收一个适用于相应代次的类型化覆盖层。该覆盖层会显式传播到派生任务和 JoinSet 工作项中；任务本地状态可以作为便利手段，但不是唯一的安全判定依据。缺少执行作用域或代次不匹配时，会以故障关闭方式失败，而不是回退到过时策略。

更大范围的风险配置重新分配及其他安全策略变更仍需排队等待重新加载，除非后续架构决策证明存在安全的在线边界。

将频道更改限制为经过验证的过渡模式

获准的通道实时应用边界仅支持具有已验证 InPlace 或 Handover 边界的变更。原位变更由运行中的适配器在使用时解析。移交会在解除现有通道实例之前构造并验证替换项。

无法证明任一边界的更改将保持 QueuedForReload 状态并附带具体原因。此决策不添加通用的停止-启动回滚机制，因为这需要保留先前的配置状态，或接受交接契约本应避免的中断。

将完整重新加载保留为后备方案

/admin/reload 仍是针对已验证实时应用边界之外每项配置变更的受支持回退方案。此决定不会改变重载身份验证、授权或 standalone-gateway 行为。

验收关卡

此 ADR 在满足以下所有条件之前仍处于提议状态：

• 规范配置发布和按生成代限定作用域的已应用状态账本随附提供，不会启用新的 live-apply 行为；
• 每个目标结果都会记录其处理的生成版本，过期的完成结果无法覆盖更新的状态；
• allowed_commands 和 forbidden_paths 使用类型化且显式传播的执行覆盖层，该覆盖层保留现有的速率限制跟踪器，并在作用域缺失或生成不匹配时默认拒绝；
• 经过验证的通道就地更新和交接路径会在替换项就绪前保留现有服务，而不受支持的更改会报告具体的重新加载原因；并且
• 配置 API 和 Operator 文档会按目标报告已生效、已排队和已拒绝的结果及具体原因，并保留 /admin/reload 作为回退方案。

在启用安全和渠道消费者之前，必须发布规范发布和结果台账，且不得引入新的线上行为。安全线上应用先于渠道线上应用。

后果

积极后果：

• 配置状态可以区分已保存的内容与各个子系统实际应用的内容。
• 并发进程内写入不能从过时的起始修订版本静默发布。
• 来自较早应用尝试的缓慢完成操作无法使较新的生成版本显示为已应用。
• 已批准的安全和通道消费者具有范围明确且可测试的安全边界。
• 对于不受支持的更改，仍保留清晰且熟悉的完整重新加载路径。

负面后果：

• 除了面向读取方的配置句柄之外，Publication 还需要写入方序列化和代际跟踪。
• 每个 live-apply 目标必须拥有一个结果处理程序和感知生成的测试。
• 执行范围的安全状态必须通过异步任务边界显式传播。
• 许多配置路径仍需要重新加载；实时应用是经过验证的行为白名单，而非普遍的承诺。

参考文献

• RFC #7897：无需完整重新加载守护进程即可应用安全策略和通道配置更新
• 配置生命周期
• crates/zeroclaw-config/src/schema.rs
• crates/zeroclaw-gateway/src/api_config.rs
• crates/zeroclaw-channels/src/orchestrator/mod.rs