claudecode/crates/runtime

运行时模块 (runtime)

本模块是 Claw 的核心引擎，负责协调 AI 模型、工具执行、会话管理和权限控制之间的所有交互。

概览

runtime 模块是整个系统的“中枢神经”，其主要职责包括：

• 对话驱动：管理“用户-助手-工具”的循环迭代。
• 会话持久化：负责会话的加载、保存及历史记录的压缩 (Compaction)。
• MCP 客户端：实现模型上下文协议 (Model Context Protocol)，支持与外部 MCP 服务器通信。
• 安全沙箱与权限：实施基于策略的工具执行权限检查。
• 上下文构建：动态生成系统提示词 (System Prompt)，集成工作区上下文。
• 消耗统计：精确跟踪 Token 使用情况和 Token 缓存状态。

关键特性

• ConversationRuntime：核心驱动类，支持流式响应处理和多轮工具调用迭代。
• 权限引擎 (Permissions)：提供多种模式（ReadOnly, WorkspaceWrite, DangerFullAccess），并支持交互式权限确认。
• 会话压缩 (Compaction)：当对话历史过长影响性能或成本时，自动将旧消息总结为摘要，保持上下文精简。
• 钩子集成 (Hooks)：在工具执行的前后触发插件定义的钩子，支持干预工具输入或处理执行结果。
• 沙箱执行 (Sandbox)：为 Bash 等敏感工具提供受限的执行环境。

实现逻辑

核心子模块

• conversation.rs: 定义了核心的 ConversationRuntime 和 ApiClient/ToolExecutor 特性。
• mcp_stdio.rs / mcp_client.rs: 实现了完整的 MCP 规范，支持通过标准输入/输出与外部工具服务器交互。
• session.rs: 定义了消息模型 (ConversationMessage)、内容块 (ContentBlock) 和会话序列化逻辑。
• permissions.rs: 实现了权限审核逻辑和提示器接口。
• compact.rs: 包含了基于 LLM 的会话摘要生成和历史裁剪算法。
• config.rs: 负责加载和合并多层级的配置文件。

对话循环流程 (run_turn)

1. 将用户输入推入 Session。
2. 调用 ApiClient 发起流式请求。
3. 监听 AssistantEvent，解析文本内容和工具调用请求。
4. 工具权限审核：针对每个 ToolUse，根据 PermissionPolicy 决定是允许、拒绝还是询问用户。
5. 执行工具：若允许，则通过 ToolExecutor（或 MCP 客户端）执行工具，并运行相关的 Pre/Post Hooks。
6. 将工具结果反馈给 AI，进入下一轮迭代，直到 AI 给出最终回复。

使用示例 (内部)

use runtime::{ConversationRuntime, Session, PermissionPolicy, PermissionMode};

// 初始化运行时
let mut runtime = ConversationRuntime::new(
    Session::new(),
    api_client,
    tool_executor,
    PermissionPolicy::new(PermissionMode::WorkspaceWrite),
    system_prompt,
);

// 运行一轮对话
let summary = runtime.run_turn("帮我重构 src/lib.rs", Some(&mut cli_prompter))?;
println!("共迭代 {} 次，消耗 {} tokens", summary.iterations, summary.usage.total_tokens());