Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-002 title: 第一方扩展面使用 trait 合约 date: 2026-07-04 status: accepted relates-to:

  • crates/zeroclaw-api/src/model_provider.rs
  • crates/zeroclaw-api/src/channel.rs
  • crates/zeroclaw-api/src/tool.rs
  • crates/zeroclaw-api/src/memory_traits.rs
  • crates/zeroclaw-api/src/observability_traits.rs
  • crates/zeroclaw-api/src/runtime_traits.rs
  • crates/zeroclaw-api/src/peripherals_traits.rs
  • docs/book/src/architecture/crates.md
  • docs/book/src/developing/tool-inventory.md

ADR-002：第一方扩展表面使用 trait 合约

这是在正式 ADR 流程之前作出的一个决策的追溯性记录。原始决策的确切日期在此记录中不可用；上方日期是该 ADR 被添加到架构文档中的日期。

此记录草拟自 FND-002 §6.3、当前的 zeroclaw-api trait 接口，以及 crate 与工具边界文档。它并非从旧版 ADR 文件中恢复。

上下文

ZeroClaw 需要许多扩展家族：模型提供方、消息通道、工具、记忆后端、可观测性接收端、运行时适配器和硬件外设。每个家族都有不同的 IO、错误、配置、安全和生命周期约束，但都必须仍然组合进同一个智能体运行时。

如果没有明确的契约，每个集成都会迫使运行时循环不断增加特殊分支。这会让新的集成一开始更快，但日后更难维护：provider 路由会泄漏到 channels，tool policy 会泄漏到 providers，channel authentication 会泄漏到 agent loop，而 memory 或 logging 行为会被复制到彼此无关的 crates 中。

该仓库已经使用 zeroclaw-api 作为公共契约层。架构文档将该 crate 描述为内核 ABI，并说明运行时依赖于 trait，而不是具体实现。

决策

第一方扩展系列在 zeroclaw-api 中使用显式的 Rust trait 契约，并通过该表面的现有工厂、注册表、组合或宿主提供的边界进行接线。

主要合约包括：

  • ModelProvider 用于 model-provider 客户端；
  • Channel 用于入站和出站消息传递表面；
  • Tool 用于 agent 可调用的能力；
  • Memory 和 MemoryStrategy 用于持久化和回忆；
  • Observer 用于运行时遥测；
  • RuntimeAdapter 用于主机运行时功能；
  • Peripheral 用于硬件和板级表面。

共享行为应归属于 trait、factory、registry、policy、config、logging 或更底层的 helper 边界，当多个实现都需要它时。单个集成不应为了让某个 provider、channel、tool 或 backend 工作，而去修改运行时循环，或添加并行状态。

此 ADR 涵盖第一方进程内扩展表面。它不替代用于进程外或独立分发能力的插件、WIT、MCP 或 skill-package 边界。

后果

积极后果：

  • 新的第一方集成可以根据现有契约进行审查，而不是作为定制的运行时更改。
  • 运行时代码可以专注于编排、策略、状态和生命周期，而不是特定于供应商的行为。
  • 测试可以针对工厂、注册表或宿主边界的连接方式、trait 行为以及边缘情况，而无需为每个集成都运行完整的端到端运行时。
  • 文档和评审指南可以在实现开始前命名具体的扩展面。

负面后果：

  • Trait 变更影响范围很广，需要谨慎迁移。
  • 过于狭窄的 trait 会迫使集成通过配置、日志或临时的辅助路径来传递行为。
  • 过于宽泛的 trait 可能会变成一个最低公分母 API，从而掩盖重要的能力差异。
  • 默认 trait 方法可能掩盖不受支持的行为，除非文档和测试明确说明这些默认值。

后续决定：

  • ADR-003 约束独立分发的 WASM 插件能力，而不仅仅是第一方 Rust 实现。
  • ADR-005 记录了后端中立的内存存储契约及 SQLite 默认实现。
  • ADR-006 和 ADR-007 仍预留给受实现门控的通道插件和网关提取决策。

参考文献

  • 架构：Crates
  • 内置工具清单
  • 插件协议
  • crates/zeroclaw-api/src/model_provider.rs
  • crates/zeroclaw-api/src/channel.rs
  • crates/zeroclaw-api/src/tool.rs
  • crates/zeroclaw-api/src/memory_traits.rs
  • crates/zeroclaw-api/src/observability_traits.rs
  • crates/zeroclaw-api/src/runtime_traits.rs
  • crates/zeroclaw-api/src/peripherals_traits.rs