feat: 添加 Web 前端及服务端 SSE 流式支持，扩展多模型兼容

后端： - server: 实现完整的 HTTP 会话管理（CRUD）+ SSE 事件流推送，支持双通道架构（POST 发消息 + GET SSE 接收流式响应） - runtime: ContentBlock 新增 Thinking / RedactedThinking 变体，支持思考过程和已编辑思考的序列化/反序列化 - api: 注册 GLM 系列模型（glm-4/5 等）到模型注册表，扩展 XAI/OpenAI 兼容提供商的请求构建逻辑前端： - 基于 Ant Design X 构建完整聊天界面：Bubble.List 消息列表、 Sender 输入框、Conversations 会话管理、Think 思考过程折叠、 ThoughtChain 工具调用链展示 - XMarkdown 集成：代码高亮、Mermaid 图表、LaTeX 公式、自定义脚注、流式渲染（incomplete 占位符） - SSE Hook 对接服务端事件流，手动管理 AssistantBuffer 累积 delta - 深色/浅色主题切换，会话侧边栏（新建/切换/删除）
2026-04-10 16:29:27 +08:00
parent 0782159ecd
commit 4a04faf926
56 changed files with 8611 additions and 172 deletions
@@ -0,0 +1,60 @@
+# 运行时模块 (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());
+```
@@ -160,7 +160,9 @@ fn summarize_messages(messages: &[ConversationMessage]) -> String {
        .filter_map(|block| match block {
            ContentBlock::ToolUse { name, .. } => Some(name.as_str()),
            ContentBlock::ToolResult { tool_name, .. } => Some(tool_name.as_str()),
-            ContentBlock::Text { .. } => None,
+            ContentBlock::Text { .. }
+            | ContentBlock::Thinking { .. }
+            | ContentBlock::RedactedThinking { .. } => None,
        })
        .collect::<Vec<_>>();
    tool_names.sort_unstable();
@@ -275,6 +277,8 @@ fn summarize_block(block: &ContentBlock) -> String {
            "tool_result {tool_name}: {}{output}",
            if *is_error { "error " } else { "" }
        ),
+        ContentBlock::Thinking { thinking, .. } => format!("thinking: {thinking}"),
+        ContentBlock::RedactedThinking { .. } => "thinking: <redacted>".to_string(),
    };
    truncate_summary(&raw, 160)
 }
@@ -324,6 +328,8 @@ fn collect_key_files(messages: &[ConversationMessage]) -> Vec<String> {
        .flat_map(|message| message.blocks.iter())
        .map(|block| match block {
            ContentBlock::Text { text } => text.as_str(),
+            ContentBlock::Thinking { thinking, .. } => thinking.as_str(),
+            ContentBlock::RedactedThinking { .. } => "",
            ContentBlock::ToolUse { input, .. } => input.as_str(),
            ContentBlock::ToolResult { output, .. } => output.as_str(),
        })
@@ -348,7 +354,9 @@ fn first_text_block(message: &ConversationMessage) -> Option<&str> {
        ContentBlock::Text { text } if !text.trim().is_empty() => Some(text.as_str()),
        ContentBlock::ToolUse { .. }
        | ContentBlock::ToolResult { .. }
-        | ContentBlock::Text { .. } => None,
+        | ContentBlock::Text { .. }
+        | ContentBlock::Thinking { .. }
+        | ContentBlock::RedactedThinking { .. } => None,
    })
 }

@@ -394,6 +402,8 @@ fn estimate_message_tokens(message: &ConversationMessage) -> usize {
        .iter()
        .map(|block| match block {
            ContentBlock::Text { text } => text.len() / 4 + 1,
+            ContentBlock::Thinking { thinking, .. } => thinking.len() / 4 + 1,
+            ContentBlock::RedactedThinking { .. } => 1,
            ContentBlock::ToolUse { name, input, .. } => (name.len() + input.len()) / 4 + 1,
            ContentBlock::ToolResult {
                tool_name, output, ..
@@ -19,6 +19,7 @@ pub struct ApiRequest {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AssistantEvent {
    TextDelta(String),
+    ThinkingDelta(String),
    ToolUse {
        id: String,
        name: String,
@@ -122,6 +123,7 @@ where
        )
    }

+    #[allow(clippy::needless_pass_by_value)]
    #[must_use]
    pub fn new_with_features(
        session: Session,
@@ -299,6 +301,16 @@ fn build_assistant_message(
    for event in events {
        match event {
            AssistantEvent::TextDelta(delta) => text.push_str(&delta),
+            AssistantEvent::ThinkingDelta(delta) => {
+                if let Some(ContentBlock::Thinking { thinking, .. }) = blocks.last_mut() {
+                    thinking.push_str(&delta);
+                } else {
+                    blocks.push(ContentBlock::Thinking {
+                        thinking: delta,
+                        signature: None,
+                    });
+                }
+            }
            AssistantEvent::ToolUse { id, name, input } => {
                flush_text_block(&mut text, &mut blocks);
                blocks.push(ContentBlock::ToolUse { id, name, input });
@@ -74,7 +74,7 @@ impl HookRunner {

    #[must_use]
    pub fn run_pre_tool_use(&self, tool_name: &str, tool_input: &str) -> HookRunResult {
-        self.run_commands(
+        Self::run_commands(
            HookEvent::PreToolUse,
            self.config.pre_tool_use(),
            tool_name,
@@ -92,7 +92,7 @@ impl HookRunner {
        tool_output: &str,
        is_error: bool,
    ) -> HookRunResult {
-        self.run_commands(
+        Self::run_commands(
            HookEvent::PostToolUse,
            self.config.post_tool_use(),
            tool_name,
@@ -103,7 +103,6 @@ impl HookRunner {
    }

    fn run_commands(
-        &self,
        event: HookEvent,
        commands: &[String],
        tool_name: &str,
@@ -238,7 +237,7 @@ fn format_hook_warning(command: &str, code: i32, stdout: Option<&str>, stderr: &

 fn shell_command(command: &str) -> CommandWithStdin {
    #[cfg(windows)]
-    let mut command_builder = {
+    let command_builder = {
        let mut command_builder = Command::new("cmd");
        command_builder.arg("/C").arg(command);
        CommandWithStdin::new(command_builder)
@@ -1,7 +1,8 @@
 use std::collections::BTreeMap;
 use std::fmt::{Display, Formatter};
+use serde::{Deserialize, Serialize};

-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum JsonValue {
    Null,
    Bool(bool),
@@ -892,9 +892,12 @@ mod tests {
        ]
        .join("\n");
        fs::write(&script_path, script).expect("write script");
-        let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
-        permissions.set_mode(0o755);
-        fs::set_permissions(&script_path, permissions).expect("chmod");
+        #[cfg(unix)]
+        {
+            let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
+            permissions.set_mode(0o755);
+            fs::set_permissions(&script_path, permissions).expect("chmod");
+        }
        script_path
    }

@@ -1018,9 +1021,12 @@ mod tests {
        ]
        .join("\n");
        fs::write(&script_path, script).expect("write script");
-        let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
-        permissions.set_mode(0o755);
-        fs::set_permissions(&script_path, permissions).expect("chmod");
+        #[cfg(unix)]
+        {
+            let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
+            permissions.set_mode(0o755);
+            fs::set_permissions(&script_path, permissions).expect("chmod");
+        }
        script_path
    }

@@ -1122,9 +1128,12 @@ mod tests {
        ]
        .join("\n");
        fs::write(&script_path, script).expect("write script");
-        let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
-        permissions.set_mode(0o755);
-        fs::set_permissions(&script_path, permissions).expect("chmod");
+        #[cfg(unix)]
+        {
+            let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
+            permissions.set_mode(0o755);
+            fs::set_permissions(&script_path, permissions).expect("chmod");
+        }
        script_path
    }

@@ -20,6 +20,14 @@ pub enum MessageRole {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum ContentBlock {
+    Thinking {
+        thinking: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        signature: Option<String>,
+    },
+    RedactedThinking {
+        data: JsonValue,
+    },
    Text {
        text: String,
    },
@@ -261,6 +269,26 @@ impl ContentBlock {
                object.insert("type".to_string(), JsonValue::String("text".to_string()));
                object.insert("text".to_string(), JsonValue::String(text.clone()));
            }
+            Self::Thinking { thinking, signature } => {
+                object.insert("type".to_string(), JsonValue::String("thinking".to_string()));
+                object.insert(
+                    "thinking".to_string(),
+                    JsonValue::String(thinking.clone()),
+                );
+                if let Some(signature) = signature {
+                    object.insert(
+                        "signature".to_string(),
+                        JsonValue::String(signature.clone()),
+                    );
+                }
+            }
+            Self::RedactedThinking { data } => {
+                object.insert(
+                    "type".to_string(),
+                    JsonValue::String("redacted_thinking".to_string()),
+                );
+                object.insert("data".to_string(), data.clone());
+            }
            Self::ToolUse { id, name, input } => {
                object.insert(
                    "type".to_string(),
@@ -312,6 +340,13 @@ impl ContentBlock {
                name: required_string(object, "name")?,
                input: required_string(object, "input")?,
            }),
+            "thinking" => Ok(Self::Thinking {
+                thinking: required_string(object, "thinking")?,
+                signature: object.get("signature").and_then(JsonValue::as_str).map(ToOwned::to_owned),
+            }),
+            "redacted_thinking" => Ok(Self::RedactedThinking {
+                data: object.get("data").cloned().ok_or_else(|| SessionError::Format("missing data".to_string()))?,
+            }),
            "tool_result" => Ok(Self::ToolResult {
                tool_use_id: required_string(object, "tool_use_id")?,
                tool_name: required_string(object, "tool_name")?,