Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-011 title: 已配置的代理在同一守护进程下具有明确的运行时边界 date: 2026-07-19 status: 已接受 relates-to:

  • https://github.com/zeroclaw-labs/zeroclaw/issues/5890
  • https://github.com/zeroclaw-labs/zeroclaw/pull/6398
  • ADR-005
  • ADR-010
  • docs/book/src/agents/overview.md
  • docs/book/src/agents/internals.md
  • docs/book/src/channels/peer-groups.md

ADR-011：已配置的 Agent 在单一守护进程下具有明确的运行时边界

这是对 v0.8.0-beta-1 中通过 #6398 发布的多智能体架构的追溯记录。上方日期是添加此 ADR 的日期，而不是原始实现日期。

已接受的 RFC #5890 提出了更宽泛的多代理用户体验和配置模型。本记录捕获了已发布的五项持久边界：命名标识、单一监督守护进程、显式通道关系、代理范围的内存，以及按代理划分的运行时策略和工作区范围。它并未批准该 RFC 中尚未发布的仅别名加入要求、memory_namespaces 模式、包分类法、集群形态，或延期的仪表板和可观测性契约。

上下文

ZeroClaw 最初将配置和运行时行为集中于一个隐式代理。多代理操作需要能够共存的身份标识，且不会意外共享工作区、内存、权限或通道可达性。

V3 实现将隐式单例替换为以别名为键的已配置代理。每个代理都会解析自身的运行时输入和作用域边界，而一个守护进程负责协调已启用的集合。显式授权会在预期协作的地方连接代理。

决策

代理身份与监督

每个 [agents.<alias>] 条目定义一个可寻址的 Agent 身份。alias 在 CLI、channel、daemon 及其他运行时入口点选择已配置的 Agent。单 Agent 安装使用同一模型，只需一个配置条目；不存在独立的特权单例架构。

每个代理都有自己的工作区边界和身份来源。身份文件会针对该代理进行解析，而不是从整个安装范围共用的单一人格中解析。

一个 zeroclaw daemon 进程负责监管已启用的已配置代理及其通道绑定。这并不意味着每个代理都拥有一个始终运行的进程或循环。它意味着守护进程操作会启动并协调已配置的代理集合，而不需要每个身份对应一个守护进程。

明确沟通

持久不变的规则是：经授权的通道关系是显式的。当前实现使用每个代理的通道绑定和对等组。共同驻留在同一个守护进程中并不会使代理成为通道对等方。

跨代理通道消息传递目前要求相关通道上存在共享的对等组关系。对等组是相互路由和入站接受的边界；不在该关系中的代理，即使配置在同一安装实例中，也不会因此变得可达。

为了兼容性，当没有已配置的代理声明任何通道绑定时，运行时会确定性地分配通道归属。该回退机制可保留旧版安装；它并不会将隐式共享确立为多代理契约。

委托及其他跨代理能力可能会施加额外的门控。本 ADR 不将对等组成员资格作为每项能力的通用授权机制。

工作区与运行时策略范围

每个已启用的智能体都会解析出一个风险配置和一个工作区边界。默认的文件系统边界是智能体自身的工作区。目标智能体上的访问条目会显式授予该智能体访问指定的同级工作区的权限。

仅限工作区的隔离环境可由解析后的风险配置禁用，包括完全自主模式，也可由 agent 的 unrestricted-filesystem 设置禁用。其余禁止路径策略和主机权限仍然适用。

共享提供程序、渠道适配器、捆绑包或其他被引用的配置，不会合并代理的工作区或已解析的运行时策略范围。它可能会有意共享被引用的资源或凭据：机密信息仍按整个安装范围共享，而不是按代理划分。

内存隔离

已配置的代理身份是内存契约所使用的作用域。后端通过存储的代理元数据或代理所拥有的存储边界和作用域适配器来强制执行该作用域。

跨代理调用是附加的且显式的。它需要兼容的同后端访问；运行时不会静默桥接不同种类的后端。

ADR-005 负责存储、归因、召回允许列表、后端兼容性以及破坏性操作约束。ADR-010 单独在会话历史、整理后的记忆和增强之间分配权威。

模式演进边界

上述命名身份和显式边界模型才是长期有效的决策。只要这些边界保持不变，具体的配置引用、捆绑包别名和文件系统字段都可以演进，而不会取代本 ADR。

后果

积极后果：

  • 单代理和多代理安装共享同一运行时模型。
  • 操作员可以针对每个命名代理，分析工作区、记忆、运行时策略和通道可达性。
  • 共享关系通过配置显式呈现，而不是根据进程共驻留来推断。
  • 可以按需添加跨代理协作，而不会削弱默认的作用域边界。

负面后果：

  • 每个可识别 agent 的入口点都必须正确携带或解析 agent 别名。
  • 配置验证必须在运行时使用前拒绝悬空别名和不兼容的跨代理授权。
  • 共享的全安装范围后端和适配器需要代理归属和过滤，而不是依赖单独的进程来界定作用域。
  • 机密信息仍然是整个安装范围内共享的，因此按代理划分的工作区和运行时策略作用域并不意味着凭据按代理隔离。

后续决定：

  • 新的跨代理能力必须定义自身的授权和归因边界，而不是假定对等组或守护进程成员身份就足够。
  • 更改默认工作区、风险配置或内存范围的弱化操作需要明确的架构和安全决策。

参考文献