Add project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-05 09:33:11 +08:00
parent 4b9d30f795
commit 9074aabe1c
9 changed files with 1987 additions and 0 deletions
@@ -0,0 +1,174 @@
+# 核心数据流分析
+
+## 主循环数据流
+
+```mermaid
+sequenceDiagram
+    participant User as 用户输入
+    participant Input as TextInput
+    participant QE as QueryEngine
+    participant API as Anthropic API
+    participant Tools as 工具系统
+    participant MCP as MCP 服务器
+    participant UI as Ink 渲染器
+
+    User->>Input: 输入指令
+    Input->>QE: 构建查询请求
+
+    QE->>QE: 附加系统提示 + 上下文
+    QE->>QE: 组装工具定义
+    QE->>API: 发送 API 请求
+
+    loop 流式响应
+        API-->>QE: SSE 事件流
+        QE-->>UI: 增量渲染
+    end
+
+    alt 工具调用
+        API-->>QE: tool_use 块
+        QE->>Tools: 执行工具
+        Tools->>MCP: MCP 调用（可选）
+        MCP-->>Tools: MCP 响应
+        Tools-->>QE: 工具结果
+        QE->>API: 继续对话（附带工具结果）
+    else 文本响应
+        API-->>QE: text 块
+        QE-->>UI: 渲染文本
+    end
+```
+
+## 工具调用详细流程
+
+```mermaid
+sequenceDiagram
+    participant API as Anthropic API
+    participant QE as QueryEngine
+    participant Perm as 权限系统
+    participant Tool as 工具实现
+    participant Hook as 用户 Hook
+    participant User as 用户
+
+    API->>QE: tool_use 事件
+    QE->>Perm: 检查权限
+
+    alt 自动允许
+        Perm-->>QE: 允许
+    else 需要确认
+        Perm->>User: 提示确认
+        User-->>Perm: 确认/拒绝
+        Perm-->>QE: 结果
+    end
+
+    alt 允许执行
+        QE->>Hook: 执行 PreToolUse Hook
+        Hook-->>QE: Hook 结果
+        alt Hook 阻止
+            QE->>API: 返回阻止原因
+        else Hook 允许
+            QE->>Tool: 执行工具
+            Tool-->>QE: 工具结果
+            QE->>Hook: 执行 PostToolUse Hook
+            QE->>API: 返回工具结果
+        end
+    else 拒绝执行
+        QE->>API: 返回拒绝原因
+    end
+```
+
+## MCP 通信流程
+
+```mermaid
+sequenceDiagram
+    participant CLI as Claude Code
+    participant Mgr as MCPConnectionManager
+    participant Transport as InProcessTransport
+    participant Server as MCP Server
+
+    CLI->>Mgr: 初始化连接
+    Mgr->>Server: 启动/连接 MCP 服务器
+    Server-->>Mgr: 返回工具列表
+
+    CLI->>Mgr: 调用 MCP 工具
+    Mgr->>Transport: 序列化请求
+    Transport->>Server: 发送请求
+    Server-->>Transport: 返回结果
+    Transport-->>Mgr: 反序列化结果
+    Mgr-->>CLI: 返回工具结果
+
+    Note over Mgr,Server: 支持 stdio, SSE, SDK 控制传输
+```
+
+## 代理集群工作流
+
+```mermaid
+sequenceDiagram
+    participant Lead as 主代理
+    participant Agent as AgentTool
+    participant Worker1 as Worker 1
+    participant Worker2 as Worker 2
+    participant Task as TaskList
+    participant Msg as SendMessage
+
+    Lead->>Agent: 启动子代理
+    Agent->>Task: 创建任务
+    Task-->>Worker1: 分配任务 1
+    Task-->>Worker2: 分配任务 2
+
+    par 并行执行
+        Worker1->>Task: 更新任务状态 (in_progress)
+        Worker1->>Task: 完成任务 (completed)
+    and
+        Worker2->>Task: 更新任务状态 (in_progress)
+        Worker2->>Msg: 发送消息给 Lead
+        Worker2->>Task: 完成任务 (completed)
+    end
+
+    Task-->>Lead: 所有任务完成
+    Lead->>Lead: 汇总结果
+```
+
+## 上下文压缩流程
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Compact as /compact 命令
+    participant Service as compact 服务
+    participant API as Anthropic API
+    participant State as AppState
+
+    User->>Compact: /compact
+    Compact->>Service: 请求压缩
+    Service->>State: 获取当前上下文
+    State-->>Service: 返回消息历史
+    Service->>API: 请求摘要
+    API-->>Service: 返回压缩摘要
+    Service->>State: 替换消息历史
+    State-->>Compact: 压缩完成
+    Compact-->>User: 显示压缩结果
+```
+
+## 文件编辑流程
+
+```mermaid
+sequenceDiagram
+    participant API as Anthropic API
+    participant Edit as FileEditTool
+    participant FS as 文件系统
+    participant History as FileHistory
+    participant Diff as Diff 渲染
+
+    API->>Edit: Edit(file_path, old_string, new_string)
+    Edit->>FS: 读取当前文件内容
+    FS-->>Edit: 返回文件内容
+
+    Edit->>Edit: 验证 old_string 唯一性
+    alt old_string 不唯一
+        Edit-->>API: 错误：字符串不唯一
+    else old_string 唯一
+        Edit->>History: 保存文件快照
+        Edit->>FS: 写入修改后内容
+        Edit->>Diff: 生成差异展示
+        Edit-->>API: 返回成功结果
+    end
+```