山东大学项目实训四

2301_79938092

321人浏览 · 2026-05-08 05:44:16

2301_79938092 · 2026-05-08 05:44:16 发布

深入理解 claw-code：用 Rust 重写claudecode源码

在这里插入图片描述

claw-code 是 Claude Code CLI 工具的 Rust 重写版本。

第一章：整体架构 —— Rust Workspace 的九块拼图

1.1 为什么选择多 Crate 结构？

打开 rust/Cargo.toml，你会看到：

[workspace]
members = ["crates/*"]
resolver = "2"

claw-code 不是单一的巨型二进制，而是由 九个相互协作的 Rust Crate 组成的 workspace：

Crate	核心职责	系统角色类比
`rusty-claude-cli`	CLI 入口、交互式输入读取、终端渲染输出	应用程序的"外壳和感官"
`runtime`	会话管理、对话循环、权限评估、钩子调度、MCP 编排、沙箱检测	“大脑和中枢神经系统”
`api`	多提供商 LLM API 的统一客户端（Anthropic、OpenAI、xAI、DashScope）	“通信层——对外联络部”
`tools`	具体工具实现：文件读写、代码搜索、PDF 提取	“手和脚——执行机构”
`plugins`	插件注册表、钩子聚合、测试隔离	“免疫系统和扩展接口”
`commands`	CLI 命令的定义和解析	“指令集手册”
`telemetry`	遥测数据采集、会话追踪、用量统计	“黑匣子和仪表盘”
`compat-harness`	跨 API 兼容性测试框架	“质检流水线”
`mock-anthropic-service`	模拟 Anthropic API 响应的测试服务	“模拟训练场”

三层好处：

编译时隔离。 Rust 的编译模型以 crate 为边界。将系统按职责拆分意味着修改 tools 模块不会触发 api 模块的重新编译，大幅缩短了迭代周期。在需要频繁实验和调试的项目中，编译时间的节省直接转化为开发体验的质变。

接口即契约。 每个 crate 通过精心筛选的 pub use 暴露公共 API，内部实现被完全隐藏。这迫使开发者持续思考"这个模块对外承诺什么"，而非"我怎么在其他模块里随意调用它的内部函数"。长期维护中，这避免了意大利面条式的跨模块耦合。

分层可测试性。 mock-anthropic-service 作为独立 crate 为其他模块提供测试基础设施；compat-harness 可以跨 crate 验证行为一致性。在生产级 AI 系统中，这种测试分层至关重要——你不可能每次回归都去调用真实的 LLM API。

1.2 项目级设计约束

[workspace.lints.rust]
unsafe_code = "forbid"

[workspace.lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }

unsafe_code = "forbid" 是一个强烈的设计声明。在一个需要执行用户命令、读写文件系统、管理第三方子进程的系统中，禁止 unsafe 意味着所有操作都必须经由 Rust 的安全抽象层。这牺牲了部分底层优化的可能性，但换来了一个至关重要的保证：用户数据和系统完整性不会因为内存安全问题而被意外破坏。 对于一款以"执行用户指令"为核心功能的工具而言，这个保证不是锦上添花，而是安全基线。

clippy pedantic 是 Clippy 中最严格的一档 lint 集合。即使代码逻辑正确，不符合最佳实践的地方也会产生警告。在一个 AI Agent 本身就是重要贡献者的项目中，pedantic lint 充当了自动化代码审查者的角色，确保来自不同来源的代码贡献——无论是人类还是 AI——都遵循统一的质量标准。

1.3 端到端数据流全景

一次典型的用户交互经历以下路径：

用户输入（终端）
    │
    ▼
┌──────────────────────────┐
│  rusty-claude-cli         │  ← 解析输入、管理 REPL 循环
│  (main.rs / input.rs)     │     渲染流式输出
└───────────┬──────────────┘
            │
            ▼
┌──────────────────────────┐
│  runtime::                 │
│  ConversationRuntime       │  ← 核心编排引擎
│  (conversation.rs)         │     持有 Session / ApiClient / ToolExecutor
└───────────┬──────────────┘
            │
   ┌────────┼────────┐
   ▼        ▼        ▼
┌──────┐ ┌──────┐ ┌──────────┐
│ api   │ │hooks │ │tools     │
│client │ │system│ │executor  │
└──┬───┘ └──┬───┘ └────┬─────┘
   │        │           │
   ▼        ▼           ▼
 LLM API  外部命令    文件系统
(Anthropic (权限拦截)  MCP 服务器
/OpenAI
/xAI)

关键洞察：ConversationRuntime 是整个系统的中心调度器，但它本身不执行任何 I/O。 它通过 trait 协议与 API 客户端、工具执行器、权限策略和钩子运行器交互，每个子系统都通过 trait 接口实现可替换性。这种依赖反转设计允许在测试中注入 mock 组件来验证对话逻辑，而无需真实的 LLM 连接。

第二章：API 层 —— 多提供商的统一抽象

2.1 问题的本质

claw-code 需要同时支持四种不同的 LLM 后端，每种都有自己的认证方式、请求格式和流式协议：

Anthropic（Claude 系列）：原生 Messages API，支持 extended thinking 和 prompt caching
OpenAI（GPT 系列）：Chat Completions API，不同的 tool calling 格式和 reasoning 模式
xAI（Grok 系列）：兼容 OpenAI 的 wire format，但端点不同
DashScope（阿里云 Qwen 系列）：同样使用 OpenAI 兼容格式，但指向阿里云端点并使用独立的 API key

如果为每个提供商写一套独立的调用代码，代码量会翻四倍，且任何消息格式的改动都需要在四个地方同步。更棘手的是，这些 API 的流式响应格式、错误码语义和 token 计数标准都不同。

2.2 解决方案：枚举 + 共享实现的组合

pub enum ProviderClient {
    Anthropic(AnthropicClient),
    Xai(OpenAiCompatClient),
    OpenAi(OpenAiCompatClient),
}

精妙之处在于：xAI 和 OpenAI 使用了相同的 OpenAiCompatClient 类型，差异仅由 OpenAiCompatConfig 驱动。 这体现了"发现共性、隔离差异"的设计哲学——与其为每个 OpenAI 兼容提供商复制代码，不如让配置描述差异。

提供商选择逻辑是一个清晰的决策树：

模型别名解析："opus" → "claude-opus-4-6"，"grok" → "grok-3"，且用户可以在配置中自定义别名
提供商检测：通过模型名称前缀判断 ProviderKind
特殊路由：qwen-* 模型虽然使用 OpenAI wire format，但必须路由到 DashScope 端点并使用 DASHSCOPE_API_KEY

这套路由逻辑全部由纯函数实现（detect_provider_kind、resolve_model_alias），零副作用，天然支持单元测试，且行为完全可预测。

2.3 Prompt Cache 的透明集成

Anthropic 的 Prompt Cache 能缓存系统提示词和长对话前缀，在后续请求中大幅削减输入 token 成本。但它是 Anthropic 专属功能。

claw-code 的处理很干净：ProviderClient::with_prompt_cache() 为 Anthropic 客户端注入缓存支持，对不支持的提供商（xAI、OpenAI）是一个 no-op。所有缓存状态和逻辑封装在 prompt_cache 模块中，通过 PromptCacheRecord 和 PromptCacheStats 提供统一的可观测性接口。

调用方完全不需要知道当前提供商是否支持缓存。 它只需调用 prompt_cache_stats()——有数据就记录，没有就跳过。系统的任何其他部分都不需要写 if anthropic { ... } else { ... } 的分支判断。

2.4 SSE 流式解析的健壮性

LLM 的流式响应通过 Server-Sent Events（SSE）格式返回。在生产环境中，SSE 流可能出现各种边界情况：消息被 TCP 分包拆散、多个事件在一个 chunk 中到达、空行格式不一致。

api 的 sse 模块提供了能处理这些边界情况的增量解析器。它区分"增量模式"（用于逐步获取 stream 内容片段）和"完整帧模式"（用于一次性解析完整事件）。这个区分避免了常见陷阱：用完整帧解析器处理流式数据时，数据在中途被截断会导致部分内容丢失。

2.5 提供商回退策略

ProviderFallbackConfig 定义了一个有序的模型回退链：当主提供商返回可重试错误（429、500、503 等）时，系统按顺序尝试备用模型。这个配置的存在说明设计者考虑了生产环境的现实——外部 API 不是 100% 可用的，优雅的回退策略比硬故障更友好。

第三章：Session —— 对话状态的持久化核心

3.1 挑战：AI 会话的数据模型远比"消息列表"复杂

一次 AI 编程会话包含的不只是消息文本：

消息有五种角色：System、User、Assistant、Tool Use、Tool Result
助手消息内部可能包含文本、思考过程、工具调用请求
会话可能被压缩以节约 token，需要追踪压缩历史
会话可能被 fork 以支持并行工作流
会话必须绑定到特定工作区，防止多实例状态污染
用户提示历史需要保留以便回溯

如果把这些状态散落在各处用 ad-hoc 方式管理，一致性很快就会崩溃。

3.2 Session 数据模型的字段设计哲学

Session {
    version: u32,              // 格式版本——支持向前兼容和迁移
    session_id: String,        // 全局唯一标识
    created_at_ms / updated_at_ms: u64, // 时间戳
    messages: Vec<ConversationMessage>,  // 完整消息历史
    compaction: Option<SessionCompaction>, // 压缩历史元数据
    fork: Option<SessionFork>,           // Fork 来源追踪
    workspace_root: Option<PathBuf>,      // 工作区绑定——防止多示例串扰
    prompt_history: Vec<SessionPromptEntry>, // 用户交互历史
    model: Option<String>,     // 记录的模型名称
    persistence: Option<SessionPersistence>, // 磁盘持久化路径
}

每个字段都有明确的"为什么"：

version：当会话格式演进时，version 号允许旧版代码安全地拒绝加载不兼容的会话，或触发显式迁移。这是向前兼容性的基本保障——没有它，格式升级就意味着数据丢失。
compaction：记录压缩次数、移除的消息数量、压缩后摘要。这些元数据对调试"模型丢失上下文"问题至关重要——你可以追溯到哪一轮压缩可能截断了关键信息。
fork：记录父会话 ID 和可选的 git 分支名。这使多分支并行开发成为可能——从主会话 fork 出一个子会话来尝试实验性重构，效果好就合并回来，不好就丢弃。
workspace_root：在 opencode serve 架构下，全局 session store 由多个实例共享。没有工作区绑定，并行 lanes 可能在不知不觉中写入错误的 CWD，导致"幽灵完成"问题。

3.3 ContentBlock 的精细类型建模

pub enum ContentBlock {
    Text { text: String },
    Thinking { thinking: String, signature: Option<String> },
    ToolUse { id: String, name: String, input: String },
    ToolResult { tool_use_id: String, tool_name: String, output: String, is_error: bool },
}

这个枚举精确反映了 Claude 模型的实际能力：

Thinking 块对应 Anthropic 的 extended thinking。signature 字段用于验证思考内容的完整性——防止中间人篡改。
ToolUse 中 id 与后续 ToolResult 的 tool_use_id 配对，形成完整的调用-响应闭环。
ToolResult 的 is_error 标志区分成功和失败——这对于后续的对话流控制（是否重试、是否上报）至关重要。

类型安全的内容建模比不透明的 JSON 字符串有两层好处：编译时保证结构正确，运行时可以高效遍历和过滤特定类型块。

3.4 Session ID 生成：无锁原子操作

static SESSION_ID_COUNTER: AtomicU64 = AtomicU64::new(0);

使用 AtomicU64 而非 Mutex<u64> 是有意选择——session ID 生成是高频操作，Mutex 的锁竞争在并发场景下会成为瓶颈。原子 CAS（Compare-And-Swap）操作的无等待特性消除了这个瓶颈，同时保证了 ID 的全局唯一性。

3.5 持久化：文件轮转与原子写入

Session 的持久化不是简单的"保存到文件"。为了保护进程崩溃时的数据完整性：

ROTATE_AFTER_BYTES = 256KB——单文件超限时轮转
MAX_ROTATED_FILES = 3——最多保留 3 个历史备份

每次保存使用"先写新文件、成功后删除旧轮转文件"的策略。这确保了在任何时间点，磁盘上至少有一个完整的会话文件可用。即使在写入过程中崩溃，最多丢失当前文件的未写入内容，而不会破坏已有的备份。

第四章：ConversationRuntime —— 对话循环的核心编排引擎

4.1 泛型参数化的职责分离

pub struct ConversationRuntime<C, T> {
    session: Session,
    api_client: C,         // 满足 ApiClient trait
    tool_executor: T,      // 满足 ToolExecutor trait
    permission_policy: PermissionPolicy,
    system_prompt: Vec<String>,
    max_iterations: usize,
    usage_tracker: UsageTracker,
    hook_runner: HookRunner,
    auto_compaction_input_tokens_threshold: u32,
    hook_abort_signal: HookAbortSignal,
    hook_progress_reporter: Option<Box<dyn HookProgressReporter>>,
    session_tracer: Option<SessionTracer>,
}

三个重要设计决策：

泛型参数而非 trait object。 C 和 T 是编译时泛型而非 Box<dyn Trait>。这意味着编译器为每个具体类型生成单态化代码，消除虚函数调用开销。对可能在紧凑循环中高频调用的组件，这种性能差异显著。而且泛型允许编译器的内联优化跨越 trait 边界。

依赖注入。 Runtime 不拥有创建 API 客户端和工具执行器的逻辑，而是通过构造函数接收已配置好的实例。好处是：调用方可以在注入前配置；测试和生产可以注入不同实现；不需要修改 runtime 代码来适配新场景。

横切关注点使用 Option + trait object。 Hook reporter、session tracer 等可选功能通过这个模式表示，遵循了组合优于继承的原则。每个横切关注点独立开发、独立测试、独立配置。

4.2 run_turn —— 一次完整轮转的六步流水线

run_turn 是系统最核心的执行路径：

第一步：会话健康检查（Compaction 后）

当会话经历过 compaction 后，上下文被摘要替换，模型需重新建立对对话状态的理解。如果此时工具执行器无响应（如 MCP 服务器断开），继续执行会导致级联失败。健康检查使用一次无害的 glob_search（匹配一个不存在的 pattern）来验证整个工具链是否畅通。

第二步：用户消息入列

用户输入被封装为 ConversationMessage 并追加到 session。这是链上的新的一环。

第三步：LLM 调用-工具执行的交替循环

while iterations < max_iterations:
    构造 ApiRequest（系统提示词 + 完整消息历史）
    调用 api_client.stream(request)
    从流式事件构建助手消息
    记录 token 消耗
    提取工具调用请求列表
    if 无工具调用: break
    for 每个工具调用:
        执行 PreToolUse Hook → 权限评估 → 执行工具 → PostToolUse Hook
        将工具结果消息追加到 session

关键约束：每次 LLM 调用都发送完整消息历史。 这是因为 LLM 本身是无状态的——它不记住之前的交互。这也说明了为什么 compaction 如此关键：消息历史越长，每次 API 调用的成本越高、延迟越高。

第四步：权限-钩子流水线

工具并非直接执行，而是经过精心排序的流水线：

PreToolUse Hook → （可能修改输入参数）
    ↓
权限策略评估 → （可能拒绝执行）
    ↓
工具执行 → （产生输出）
    ↓
PostToolUseHook / PostToolUseFailureHook → （可能修改输出或标记为错误）

排序原因：Hook 在权限之前运行，因为它可能需要修改输入参数；权限在工具执行之前，因为一旦工具执行，副作用已不可逆转。如果 Hook 返回 cancelled/denied/failed，直接跳到构造错误消息，跳过权限检查和工具执行。

第五步：自动压缩检查

每轮结束后，如果累积 input tokens 超过阈值（默认 100,000），自动触发 compaction，将早期消息摘要化。

第六步：TurnSummary 组装

返回一个完整总结：助手消息、工具结果、缓存事件、迭代次数、token 消耗——供调用方更新 UI、记录日志或触发后续行为。

4.3 压缩边界保护：一个看似微妙但至关重要的细节

compaction 模块中有一处特别精心的处理——维护 tool-use / tool-result 配对的完整性。

当压缩边界恰好切在一个 tool-result 消息上时，如果只保留了 tool-result 而丢弃了前面的 tool-use 消息，OpenAI 兼容的 API 会返回 400 错误。为此，压缩逻辑会向后（向更早的消息方向）调整边界，确保不会拆散配对。

这个细节体现了一个核心系统设计原则：在不同抽象层之间转换消息格式时，必须维持语义完整性。 Anthropic 和 OpenAI 的 API 在 tool calling 的具体格式上存在细粒度差异——前者通过 tool_use_id 显式配对，后者要求 tool 消息紧跟包含 tool_calls 的 assistant 消息。内部数据结构需要向更严格的一方看齐。

第五章：权限系统 —— 安全与自由的平衡艺术

5.1 同心圆权限模型

claw-code 定义了五个权限层级，不是扁平的"允许/禁止"二元系统，而是一个同心圆模型：

ReadOnly → WorkspaceWrite → DangerFullAccess → Prompt → Allow
  ↑ 最安全                                           ↑ 最宽松

ReadOnly：只读操作——读取文件、搜索代码。适合审查和理解代码的场景。
WorkspaceWrite：工作区内自由读写。默认模式，平衡了安全性和实用性。
DangerFullAccess：无限制访问，包括系统目录和任意命令。需用户明确选择。
Prompt：每次操作请求用户交互确认。
Allow：完全自动允许，零交互。

关键特性：权限可按工具粒度精细配置。 read_file 可以在 ReadOnly 模式下使用，write_file 需要 WorkspaceWrite，bash（执行任意系统命令）需要 DangerFullAccess。这种基于 map 的工具-权限注册解耦了"什么工具需要什么权限"和"如何检查权限"，添加新工具时无需修改权限检查逻辑。

5.2 六层权限决策树

PermissionPolicy {
    active_mode: PermissionMode,
    tool_requirements: BTreeMap<String, PermissionMode>,
    allow_rules: Vec<PermissionRule>,
    deny_rules: Vec<PermissionRule>,
    ask_rules: Vec<PermissionRule>,
}

权限评估是一个有严格优先级的顺序决策树：

Hook 返回的决定（最高优先级）——PreToolUse Hook 可以直接 Allow/Deny/Ask
Hook 取消/失败状态——Hook 被取消或失败 → 视为 Deny
静态 deny 规则——配置文件中的禁止清单
静态 allow 规则——配置文件中的允许清单
权限模式检查——当前模式是否满足工具的最低需求
交互式提示（最低优先级）——以上都未命中时，询问用户

这个顺序确保了三件事：

持久化安全策略通过配置文件实现（静态规则优先于交互式）
Hook 系统可以动态覆盖任何策略（最高优先级，适用于 CI/CD 自动化场景）
交互式提示仅在最必要时触发（减少不必要的打断）

5.3 PermissionContext：为什么需要运行时的上下文？

PermissionContext {
    override_decision: Option<PermissionOverride>,
    override_reason: Option<String>,
}

它的存在解决了一个关键问题：权限评估不仅取决于"谁在请求什么"，还取决于"当前发生了什么"。 例如，在 CI 流水线中，所有操作应自动允许；在代码审查模式下，写操作应被阻止。这些上下文信息不适合硬编码在 PermissionPolicy 中，而应由上层编排器或钩子动态注入。

第六章：Hook 系统 —— 可编程的安全拦截链

6.1 设计哲学：拦截器而非通知器

Hook 系统围绕三个生命周期事件构建：

PreToolUse → [工具执行] → PostToolUse / PostToolUseFailure

这不是简单的"通知"机制，而是一个拦截器链（Interceptor Chain）。每个 Hook 可以：

修改输入——在工具执行前调整参数
拒绝执行——阻止工具运行并返回自定义消息
修改输出——在工具执行后调整结果
标记失败——将成功的执行标记为失败
覆盖权限——返回 Allow/Deny/Ask 决定

6.2 外部进程模式：四个关键优势

claw-code 的 Hook 不是回调函数，而是外部命令行程序：

系统构造 JSON payload（事件类型、工具名、输入/输出）
通过 stdin 传递给 Hook 命令
读取 stdout 的 JSON 响应
根据 exit code 和输出解析 Hook 的决策

这种设计带来四个关键优势：

语言无关性。 Hook 可以用 Python、Bash、Node.js、Rust 或任何能读写 stdin/stdout 的语言编写。零门槛。

进程隔离。 Hook 崩溃不会影响主进程。HookAbortSignal（Arc<AtomicBool>）提供取消信号——用户按 Ctrl+C 时，Hook 检查信号并优雅退出。

安全边界。 Hook 在独立进程中运行，权限受限于启动用户。恶意 Hook 无法访问 claw-code 的内存空间或覆盖其内部状态。

独立部署。 Hook 可以独立于 claw-code 更新、测试和分发。一个团队可以维护自己的 Hook 集合而不触及主代码库。

6.3 Hook 驱动的权限覆盖

通过 PreToolUse Hook，外部程序可以在每次工具调用前根据自定义逻辑返回权限决定：

CI Hook 检测 CI=true 环境变量 → 自动 Allow 所有操作
安全 Hook 检查命令是否包含危险模式 → 自动 Deny
审计 Hook 记录所有调用到远程服务 → 但不改变权限决策

这种可编程安全策略比任何硬编码的规则系统更灵活，因为它允许每个团队根据自己的需求定制行为，无需修改 claw-code 源码。

第七章：MCP 集成 —— 可扩展的工具生态

7.1 MCP 协议的角色

Model Context Protocol (MCP) 是 Anthropic 提出的开放协议，用于标准化 LLM 应用与外部工具和数据源之间的通信。claw-code 的 MCP 支持是整个工具系统可扩展性的基石。

MCP 定义的核心交互：

服务器暴露工具列表（tools/list）和资源列表（resources/list）
客户端调用工具（tools/call）和读取资源（resources/read）
通信遵循 JSON-RPC 2.0 协议

7.2 五种传输方式：每种场景都有最适配的通道

enum McpServerConfig {
    Stdio(McpStdioServerConfig),           // 本地子进程，stdin/stdout
    Sse(McpRemoteServerConfig),            // HTTP SSE，支持服务端推送
    Http(McpRemoteServerConfig),           // HTTP 常规请求-响应
    Ws(McpWebSocketServerConfig),          // WebSocket 双向实时
    Sdk(McpSdkServerConfig),               // 进程内嵌入
    ManagedProxy(McpManagedProxyServerConfig), // 云代理中转
}

每种模式对应不同的部署场景：

Stdio：最基础模式，适合本地工具——简单、零网络配置、天然进程隔离
SSE/HTTP：用于远程 MCP 服务，SSE 适用于需服务端推送的长时间运行工具
WebSocket：用于需双向实时通信的场景，如工具执行期间的进度推送
SDK：进程内 MCP 功能，无需进程间通信
ManagedProxy：通过云端代理中转的远程连接，代理层可处理认证、加密和速率限制——最安全的远程模式

7.3 工具名称命名空间

多个 MCP 服务器暴露同名工具时会产生冲突。解决方案：带前缀的命名约定。

例如 github 服务器的 create_issue 工具 → mcp__github__create_issue。mcp__ 前缀是 LLM 可识别的命名空间标识符——模型看到前缀就知道这是 MCP 工具，可据此构造调用参数。

名称规范化处理（所有非字母数字字符替换为下划线）避免了特殊字符导致的解析歧义。

7.4 McpToolRegistry 与 McpServerManager 的读写分离

McpToolRegistry {                     // 状态视图
    inner: Arc<Mutex<HashMap<String, McpServerState>>>,
    manager: Arc<OnceLock<Arc<Mutex<McpServerManager>>>>, // 操作接口
}

两个组件的分工：

Registry 是"状态视图"——维护服务器列表、工具集合、连接状态，供高频查询
Manager 是"操作接口"——负责进程启停、JSON-RPC 请求发送、连接生命周期管理

这种读写分离使得 UI 层可以高频查询服务器状态（通过 Registry）而不影响实际的连接管理（通过 Manager）。Arc<Mutex<>> 嵌套保证线程安全；OnceLock 支持延迟初始化——Manager 在第一个服务器配置时才创建。

7.5 生命周期验证的全链可观测

McpLifecycleValidator 跟踪 MCP 连接的全生命周期状态转换：初始化 → 握手 → 工具发现 → 运行时。每个阶段记录成功/失败状态，服务器降级时生成结构化报告。

当出现"模型说它调用了某个工具但没得到结果"时，validator 能快速回答：是连接断了？认证过期了？还是工具执行超时了？

第八章：插件系统 —— 模块化扩展的生命周期

8.1 插件 = MCP 服务器组 + 共享生命周期

在 claw-code 中，一个插件被视为一组 MCP 服务器的逻辑集合，共享配置和生命周期：

enum PluginState {
    Unconfigured,     // 尚未配置
    Validated,        // 配置验证通过
    Starting,         // 正在启动
    Healthy,          // 全部正常
    Degraded {        // 部分失败但仍有可用服务器
        healthy_servers: Vec<String>,
        failed_servers: Vec<ServerHealth>,
    },
    Failed { reason: String },
    ShuttingDown,
    Stopped,
}

Degraded 状态是设计精髓。 它表示"部分失败了，但系统仍可运转"。在微服务架构中，这种优雅降级模式同样重要：不应因为一个非关键组件失败就让整个系统宕机。

8.2 降级时到底什么还能用？

fn degraded_mode(&self, discovery: &DiscoveryResult) -> Option<DegradedMode> {
    // 返回: available_tools 列表 + unavailable_tools 列表 + 降级原因
}

降级时，系统不是简单地抛一个"插件坏了"的异常。而是精确列出：

哪些工具仍可使用
哪些工具当前不可用
为什么降级（如"3 台服务器正常，2 台故障"）

这个信息有三个消费者：

LLM——系统提示词注入"以下工具不可用"的信息，防止模型尝试调用失效工具
用户——UI 显示警告徽章
运维——日志记录降级详情，方便事后诊断

8.3 PluginLifecycle 的聚合视图

PluginLifecycle 将所有插件的状态聚合为一个全局视图，回答"系统整体是否健康"。当多个插件各自处于不同状态时，lifecycle manager 给出综合判断，影响系统行为：核心插件全部 Healthy → 正常运行；核心插件部分 Degraded → 运行但显示警告；核心插件 Failed → 阻止高风险操作。

第九章：上下文压缩 —— 突破 LLM 上下文窗口瓶颈

9.1 问题不可回避

一个真实的 AI 编程会话可能有数百轮对话。每次工具调用产生大量输出——grep 结果几百行，文件内容数千行。如果不加控制：

Token 费用暴涨（每次 API 调用都携带完整历史）
延迟增加（更长的 prompt = 更长的处理时间）
模型性能下降（“大海捞针”——过长上下文中关键信息被稀释）
最终撞上上下文窗口硬上限

9.2 策略：保留尾部，摘要头部

压缩前: [msg1 ... msg95, msg96, msg97, msg98, msg99, msg100]
                                        ↑________________↑
                                       保留最近 4 条
压缩后: [压缩摘要消息, msg97, msg98, msg99, msg100]

核心逻辑：

估算会话 token 消耗（启发式方法）
当 compactable 消息的估算 tokens 超过阈值且消息数超保留数时触发
将早期消息压缩为结构化的系统消息
保留最后 N 条消息（默认 4 条）原封不动
生成特殊的继续指令告诉模型"从之前的对话继续——以下是摘要"

9.3 为什么不让 LLM 生成摘要？

如果 compaction 时额外调用 LLM 来生成高质量摘要，就违背了 compaction 的初衷——降低 token 消耗。claw-code 采用基于规则的摘要方法：提取用户消息、统计对话轮廓、生成结构化摘要。虽不如 LLM 摘要精细，但零额外成本和延迟。

9.4 OpenAI/Anthropic API 差异驱动的边界保护

前面提到的 tool-use/tool-result 配对保护机制的直接原因：Anthropic 用 tool_use_id 匹配（位置无关），OpenAI 要求 tool 消息紧跟包含 tool_calls 的 assistant 消息（位置相关）。想构建同时支持两种 API 的系统，内部数据结构必须向更严格的一方看齐。

9.5 Summary Compression：对摘要的二次压缩

summary_compression 模块对已生成的摘要文本施加三个维度约束：

max_chars: 1200——总字符数上限
max_lines: 24——行数上限
max_line_chars: 160——单行长度上限（超出截断）

假设是摘要中仍有冗余——重复行、过长行——通过规则可以进一步精简而不丢失关键信息。

第十章：Sandbox —— 环境感知的隔离策略

10.1 三层文件系统隔离

enum FilesystemIsolationMode {
    Off,             // 无限制
    WorkspaceOnly,   // 仅工作区（默认）
    AllowList,       // 白名单
}

沙箱的目标不是"创造一个绝对安全的执行环境"（那是 Docker/VM 的职责），而是理解当前环境的隔离程度，据此决定可以安全执行什么操作。 WorkspaceOnly 作为默认值平衡了实用性（99% 的操作在工作区内）和基本安全保障（防止意外触及系统文件）。

10.2 容器检测的多信号融合

detect_container_environment 不依赖单一信号，而是综合四种来源：

文件标记：/.dockerenv、/run/.containerenv 是否存在
环境变量：CONTAINER、DOCKER、PODMAN、KUBERNETES_SERVICE_HOST
cgroup 信息：/proc/1/cgroup 中是否包含 docker、containerd、kubepods、podman、libpod
组合判断：多种信号的逻辑组合，而非依赖单一标志

不同容器运行时留下的痕迹千差万别。有些设置 /.dockerenv，有些只修改 cgroup。多信号融合大幅提高了检测准确率。

10.3 检测结果的影响面

返回的 SandboxStatus 不是简单的布尔值，而是一个丰富的信息结构体。两个消费者：

系统提示词——告诉 LLM 它在什么环境中运行（“你在 Docker 容器中”），LLM 据此调整行为（如不推荐安装系统级包）
权限策略——容器中的某些操作可能因风险被容器隔离所限制而自动批准

第十一章：Worker 系统 —— 自主 Agent 的控制平面

11.1 设计目标

Worker 系统为自主 Agent 提供了完整的控制平面。一个 Worker = 一个独立运行的 AI Agent 实例，拥有自己的生命周期、状态机、信任关系和故障恢复策略。

11.2 七态状态机

enum WorkerStatus {
    Spawning,                 // 进程启动中
    TrustRequired,            // 等待用户确认信任
    ToolPermissionRequired,   // 等待高风险工具授权
    ReadyForPrompt,           // 就绪，等待任务
    Running,                  // 执行中
    Finished,                 // 正常完成
    Failed,                   // 执行失败
}

两个特别值得关注的状态：

TrustRequired：Agent 开始执行前必须经用户确认"信任此 Agent 在其工作区内操作"。这是一个安全门——防止恶意或错误配置的 Agent 在无人知晓的情况下运行。
ToolPermissionRequired：即使信任了 Agent，某些高风险工具（网络访问、系统命令）可能需要额外确认。这允许 Agent 部分启动（执行低风险操作），但在高风险操作前暂停。

11.3 故障分类与恢复映射

enum WorkerFailureKind {
    TrustGate,           // → 信任提示未解决
    ToolPermissionGate,  // → 工具权限未授予
    PromptDelivery,      // → 提示投递错误
    Protocol,            // → MCP 协议错误
    Provider,            // → LLM 提供商故障
    StartupNoEvidence,   // → 启动超时，无法确定根因
}

StartupNoEvidence 是一个诚实的分类。 当 Agent 启动超时时，与其猜测一个可能错误的原因然后提供误导性建议，不如坦诚地说"我不确定具体是什么问题"，同时收集所有可用的环境证据（StartupEvidenceBundle）供人工诊断。

11.4 启动无证据时的诊断黑匣子

StartupEvidenceBundle 记录超时时刻的所有可用信号：最后生命周期状态、prompt 是否已发送、是否被接受、trust/tool permission prompt 是否被检测到、传输层和 MCP 是否健康、已过时间。这些字段构成一个"黑匣子"，即使不能立即解决问题，也足以让支持团队快速定位根因。

第十二章：Recovery 系统 —— 故障自动修复的七种武器

12.1 七种已知故障场景

enum FailureScenario {
    TrustPromptUnresolved,    // 信任提示未解决
    PromptMisdelivery,        // 提示投递到错误目标
    StaleBranch,              // 分支过期
    CompileRedCrossCrate,     // 跨 crate 编译失败
    McpHandshakeFailure,      // MCP 握手失败
    PartialPluginStartup,     // 插件部分启动失败
    ProviderFailure,          // LLM 提供商不可用
}

每种场景都有对应的结构化恢复配方（RecoveryRecipe），包含恢复步骤列表、最大自动重试次数、和重试耗尽后的升级策略。

12.2 核心原则：自动恢复一次，然后升级

这个"一次"不是"每种故障类型只尝试一次"，而是"对每个故障实例重试最多一次"。若你有三个插件先后失败，每个都获得各自的恢复机会。

限制重试次数是为了防止无限重试循环。如果 MCP 握手连续失败 10 次，第 11 次也不太可能成功。与其浪费资源，不如升级给操作者。

12.3 恢复动作的类型

AcceptTrustPrompt       → 在 CI 环境中自动接受信任提示
RedirectPromptToAgent   → 重新将提示投递到正确的 Agent
RebaseBranch            → 变基到最新提交
CleanBuild              → 清理构建产物后重新编译
RetryMcpHandshake       → 超时后重试 MCP 连接
RestartPlugin { name }  → 重启指定插件
RestartWorker           → 重启整个 Worker
EscalateToHuman         → 升级给人类操作者

每种恢复动作都是幂等的或至少有"安全重试"保证。RebaseBranch 在已是最新时是 no-op；CleanBuild 只是清理缓存后重新构建。

第十三章：Policy Engine —— 声明式的行为规则引擎

13.1 为什么需要规则引擎？

当多个自主 Agent 并行运行时，需要一个中心化的规则系统来协调它们的行为，避免"Agent A 认为应该合并 PR，Agent B 认为应该关闭 PR"的冲突。

PolicyRule {
    name: String,
    condition: PolicyCondition,   // 触发条件
    action: PolicyAction,         // 触发动作
    priority: u32,                // 优先级（冲突时的仲裁依据）
}

13.2 条件的无限组合能力

enum PolicyCondition {
    And(Vec<PolicyCondition>),     // 所有子条件满足
    Or(Vec<PolicyCondition>),      // 任一子条件满足
    GreenAt { level },             // 质量门禁通过
    StaleBranch,                   // 分支过期
    StartupBlocked,                // 启动阻塞
    LaneCompleted,                 // Lane 完成
    ReviewPassed,                  // 代码审查通过
    TimedOut { duration },         // 超时
    ...
}

And 和 Or 组合子允许条件无限嵌套。如：

And([
    LaneCompleted,
    ReviewPassed,
    Or([GreenAt(3), TimedOut(1h)])
])

读作：“Lane 已完成且审查通过且（质量等级≥3 或等待超过 1 小时）”。

声明式条件比命令式 if-else 链更容易理解、测试和修改。

13.3 动作的可串联性

PolicyAction::Chain(Vec<PolicyAction>) 允许多个动作串联执行。"合并到 dev → 通知 Slack → 关闭 Lane"就是一个典型的三步 Chain。

声明式规则的核心价值：业务逻辑和调度逻辑完全解耦。 添加新自动化行为只需添加/修改一条规则，调度循环的代码不变。

第十四章：Lane Events —— 事件驱动的开发流水线

14.1 Lane 的概念

Lane 代表一个独立的开发任务流水线——可能是 feature 分支开发、bug 修复全流程、或自动化代码审查。每个 Lane 拥有自己的状态、事件流、质量等级和完整生命周期。

14.2 基于指纹的事件去重

compute_event_fingerprint(event) → 相同指纹 → 只保留第一个

在分布式系统中，一个 Lane 可能在短时间内产生多个语义相同的事件（如两次代码提交触发两次 “Lane Green”）。去重防止消费者对同一状态变化做出多次反应。

14.3 终态事件的覆盖去重

如果 Lane 先产生 Failed 然后产生 Reconciled，消费方只应关心最终的 Reconciled。dedupe_terminal_events 移除被后续终态覆盖的早期终态事件，保证消费者看到的是最终一致性视图而非中间状态序列。

第十五章：Task 系统 —— 子代理任务的结构化管理

15.1 TaskPacket：为 AI Agent 设计的结构化任务协议

TaskPacket {
    objective: String,              // 目标描述
    scope: TaskScope,                // 范围（Workspace/Module/SingleFile/Custom）
    scope_path: Option<String>,      // 范围的具体路径
    repo: String,                    // 仓库标识
    worktree: Option<String>,        // 工作树路径
    branch_policy: String,           // 分支策略
    acceptance_tests: Vec<String>,   // 验收标准（可执行命令）
    commit_policy: String,           // 提交策略
    reporting_contract: String,      // 报告格式约定
    escalation_policy: String,       // 升级策略
}

TaskPacket 定义的不仅是任务"做什么"，还包含"怎么做"和"如何判断做完了"：

acceptance_tests：可执行命令列表，全部通过 = 任务完成
commit_policy：“single verified commit” = squash 成一个提交
reporting_contract：定义报告的标准格式
escalation_policy：定义何时需要人类介入

这是为 AI Agent 设计的完整任务协议——给 Agent 足够的上下文来工作，同时给出明确的边界和期望。

15.2 验证与类型安全

validate_packet 确保必填字段非空，scope 和 scope_path 的一致性得到满足。ValidatedPacket 作为 newtype wrapper——一旦通过验证，所有下游代码都能信任数据的合法性，无需在每个使用点重复检查。

15.3 TaskRegistry 和 Team

Task 可组织为 Team——一组共享上下文的关联任务，拥有独立的生命周期（Created → Running → Completed → Deleted）。Registry 使用 Arc<Mutex<HashMap>> 模式——Arc 支持线程间共享，Mutex 保证并发安全，HashMap 提供 O(1) 查找。

第十六章：跨模块设计模式全景

通读整个代码库，以下模式反复出现，构成项目的"架构 DNA"：

16.1 类型状态（Typestate Pattern）

ValidatedPacket —— 将验证后状态编码进类型，编译器强制"使用前先验证"。不可能使用未经验证的数据。

16.2 编译时依赖注入

ConversationRuntime<C, T> —— 零运行时开销的 DI，所有依赖关系在编译时解析。比运行时 DI 框架更快、更可预测。

16.3 策略模式（Strategy Pattern）

PermissionPolicy 将权限评估策略从检查逻辑中分离；PolicyEngine 将行为规则从规则引擎中分离。策略可独立演化而不触及引擎代码。

16.4 观察者模式（Observer Pattern）

Hook 系统、Event 系统、Session Tracer——核心流程发布事件，外部系统订阅响应，核心路径不依赖观察者。

16.5 优雅降级（Graceful Degradation）

从 Plugin 的 Degraded 状态到 Sandbox 的 fallback——"部分失败不应导致全部死机"贯穿始终。

16.6 结构化 Error 类型

每个模块拥有专用 Error 类型（SessionError、ConfigError、RuntimeError、ToolError 等），实现 Display + Error。精确的错误匹配取代笼统的 unwrap()。

第十七章：从 claw-code 学到的 AI Agent 系统设计原则

原则一：将 LLM 视为特殊 I/O 设备

LLM 有延迟、可能失败、需要特定数据格式。像对待任何 I/O 设备一样，系统围绕它构建了缓冲（会话管理）、错误处理（RuntimeError）、超时控制（max_iterations）和健康监控（health probes）。

原则二：安全必须内建而非外挂

权限检查深度嵌入每次工具调用的执行路径——PreToolUse Hook → 权限评估 → 执行 → PostToolUse Hook。没有任何代码路径能绕过安全检查。

原则三：可观测性是第一公民

SessionTracer、McpLifecycleValidator、UsageTracker、Event 系统——可观测性被内置在每一层。这使得"为什么 Agent 做了 X"和"Agent 现在在做什么"总可以被回答。

原则四：优雅降级优于完美运行

插件降级、MCP 部分故障、容器检测回退——系统始终假设"事情会出问题"，并为每种故障模式准备降级路径。

原则五：声明式优于命令式

PolicyEngine 的规则、权限策略的 allow/deny/ask 列表、TaskPacket 的验收标准——声明式配置更容易审计（一目了然）、更容易版本控制（diff 友好）、更容易被 AI 理解和修改。

结语：claw-code 的本质——AI Agent 操作系统的参考实现

claw-code 不仅仅是一个 Claude Code 的 Rust 重写。它实现了一个完整的 AI Agent 操作系统级基础设施：

操作系统概念	claw-code 对应	实现模块
进程管理	MCP 服务器启停、监控、优雅关闭	`mcp_stdio`、`mcp_server`
安全模型	权限分级、沙箱检测、钩子拦截	`permissions`、`sandbox`、`hooks`
文件系统	会话持久化、轮转、原子写入	`session`
网络栈	多传输协议、OAuth 认证、代理路由	`api`、`mcp`、`oauth`
调度器	Task/Team 任务编排	`task_registry`、`team_cron_registry`
监控系统	全链路遥测和健康检查	`telemetry`、`plugin_lifecycle`
故障恢复	故障分类、自动重试、人工升级	`recovery_recipes`、`worker_boot`