# 运行时模块 (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 给出最终回复。

## 使用示例 (内部)

```rust
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());
```