Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-006 title: 将运行时插件作为可选通道的目标 date: 2026-07-18 status: 提议 relates-to:

  • ADR-002
  • ADR-009
  • docs/book/src/foundations/fnd-001-intentional-architecture.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8850
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8691#issuecomment-5009706612
  • wit/v0/channel.wit
  • crates/zeroclaw-plugins/src/wasm_channel.rs

ADR-006：将运行时插件作为可选通道的目标

上下文

ZeroClaw 目前通过 Cargo 功能标志将许多消息传递集成编译到构建中。这样可以让未使用的频道代码排除在指定构建之外，但添加或更新可选集成仍需要重新构建应用程序。这也使特定供应商的依赖项和发布节奏与主二进制文件紧密耦合。

WIT 组件模型现已定义 channel-plugin world，宿主适配器为 WASM 组件实现共享的 Channel trait。服务发现与宿主侧适配器已存在，但运行中的守护进程尚不构造已发现的 channel 插件，也不为其提供每个厂商监听器所需的全部依赖。因此，运行时插件描述的是具有不完整操作路径的真实目标，而非当前的打包模型。

替代方案包括保留永久的编译/运行时混合模式、要求立即进行全渠道迁移，或将运行时插件作为默认目标，同时允许针对插件边界尚无法支持的功能设置明确的原生例外。

决策

我们将使运行时可安装插件成为可选通道的目标打包和执行模型。

当 WIT/WASI 主机边界能够提供其所需的网络、webhook 或轮询入口、配置、机密、媒体、交互和生命周期能力，且不削弱运行时安全模型时，应将可选通道从编译期功能迁移为运行时插件。

在过渡期间，原生实现只能作为明确的、基于能力的例外保留。例外必须指出缺失的宿主能力或运行约束、依赖它的原生代码路径，以及允许迁移的条件。厂商身份、现有功能标志或实现存在时间本身都不能成为永久例外的理由。

运行时负责插件发现、权限强制执行、配置分发、监听器监管、健康报告，以及适配共享的 Channel 契约。通道插件负责平台特定的协议行为和消息转换。由 Gateway 托管的入口可以路由通用 HTTP 流量，但它不应成为特定供应商通道逻辑的永久所有者。

Issue #8850 负责迁移排序、能力差距跟踪，以及退役已编译可选通道的边界界定。本 ADR 不选择哪个通道首先迁移，也不要求在其运行时替代方案具备同等运维支持之前移除可用的原生实现。

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

  • 已发现通道插件可由运行中的守护进程进行配置和注册；
  • 受支持的发行版无需自定义重新构建即可安装、配置和运行 channel 插件；
  • 入站侦听器或 webhook 流量可以在受监管的运行时所有权下访问该插件；
  • 至少有一个现有的可选编译通道已完成端到端迁移；以及
  • 例外情况和兼容性流程已为尚无法迁移的渠道提供了文档说明。

后果

积极后果：

  • 用户无需重新构建 ZeroClaw，即可添加和更新可选集成。
  • 供应商依赖项和发布节奏可以从主二进制文件中分离出来。
  • 通道实现共享一个受权限控制的运行时边界和一个调用方可见的 trait 契约。
  • 原生例外仍然便于审查，因为它们与明确的能力缺口相关联，而不会演变成一个未定义的永久性第二模型。

负面后果：

  • 宿主必须监管长期运行的侦听器，并在组件边界上维持通道健康状态、交互、媒体和配置行为。
  • 在 WIT/WASI 能力逐渐成熟的过程中，某些平台可能仍保持原生形态，因此迁移过程仍需支持两种打包路径。
  • 插件的分发、兼容性、签名和吊销成为运营渠道生命周期的组成部分。
  • 迁移需要功能对等的证据；仅编译一个 channel 组件不足以弃用其原生实现。

参考文献