id: ADR-001 title: Rust 是 ZeroClaw 的实现语言 date: 2026-07-04 status: accepted relates-to:
- docs/book/src/foundations/fnd-001-intentional-architecture.md
- docs/book/src/architecture/crates.md
- Cargo.toml
ADR-001：Rust 是 ZeroClaw 的实现语言
这是在正式 ADR 流程之前作出的一个决策的追溯性记录。原始决策的确切日期在此记录中不可用；上方日期是该 ADR 被添加到架构文档中的日期。
本记录依据 FND-002 §6.3 及当前仓库结构起草，并非从旧的 ADR 文件恢复而来。
上下文
ZeroClaw 是一个 local-first 的 agent 运行时，其主要发行版需要在用户未安装必需语言运行时的情况下也能运行。它与许多操作系统和网络边界集成，并对安全、内存、进程、日志和配置行为保持严格控制。
该项目在其他语言中也有相邻的 agent-system 实验。这些项目有助于探索，但运行时需要一种实现语言来编写随 ZeroClaw 发布的代码：providers、channels、tools、memory、config、gateway、hardware support，以及面向用户的 CLI。
Rust 符合塑造运行时的要求：
- 可预测的单一二进制分发；
- 在 IO 和安全边界处进行明确的所有权和错误处理；
- 异步网络和进程监督，而无需大型运行时依赖；
- 面向 channels、hardware、gateway 和可选 capabilities 的 feature-gated 构建；
- 用于 crates、测试、文档生成和发布工作流的一个 Cargo workspace。
决策
ZeroClaw 的运行时、一方 crate、CLI、网关、工具宿主、提供方集成、通道集成、内存后端、配置模式和硬件支持均作为 Rust 工作区成员实现。
在正确的边界处，边缘上可能存在非 Rust 代码：shell 脚本、发布和打包辅助工具、生成的 Web 资源、外部 CLI、MCP servers、skill scripts 和插件 guest。这些表面可以支持、打包、驱动或扩展 ZeroClaw，但除非新的已接受 ADR 取代本 ADR，否则它们不会成为核心运行时的实现基础。
后果
积极后果：
- 贡献者可以通过一个带类型的工作区来推理运行时行为，而不是通过多个语言运行时。
- 主要工作区的构建、lint、测试、文档生成、发布和功能门控都通过 Cargo 路由。
- 安全敏感代码受益于 Rust 的所有权模型和显式错误传播。
- 第一方集成共享 crate 边界、trait 契约和日志/配置约定。
负面后果：
- 只懂 TypeScript、Python、Go 或 shell 的贡献者，在更改核心行为之前必须先跨过 Rust 的学习曲线。
- Web、UI 和外部服务集成需要显式的边界设计，而不是自由地与运行时共享应用状态。
- 生成的文档、本地化目录和发布制品即使可见输出是 Markdown、Fluent、HTML 或打包元数据，也通常依赖 Rust 工具链。
- 相邻项目中的实验必须在成为 ZeroClaw 运行时行为之前，有意地移植到 Rust 中。
后续决定：
参考文献
- FND-001: Intentional architecture
- 架构：Crates
- 插件协议
AGENTS.mdCargo.toml