Add project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/README.md

@@ -0,0 +1,15 @@
+所有分析文档已完成并更新。最终结果：
+
+| 文档 | 行数 | 内容 |
+|------|------|------|
+| `architecture-overview.md` | 187 | 架构总览、目录结构、启动流程、设计模式 |
+| `tool-system.md` | 262 | 40+ 工具分类、类图、注册机制、权限模型、AgentTool 架构 |
+| `command-system.md` | 234 | 82 个命令分类、类型系统(local/local-jsx/prompt)、命令来源、注册机制 |
+| `services-and-infrastructure.md` | 292 | API/MCP/OAuth/LSP 服务、Bridge 桥接、代理协调器、插件/技能系统、查询引擎 |
+| `ui-components.md` | 310 | React+Ink 组件层次、设计系统、Vim 模式、快捷键系统、Buddy 精灵、Hooks |
+| `types-utils-state.md` | 363 | 类型系统、Bash 解析器、状态管理、内存系统、任务类型、Schema 验证 |
+| `data-flow.md` | 174 | 主循环、工具调用、MCP 通信、代理集群的时序图 |
+| `file-statistics.md` | 150 | 代码规模统计、技术栈依赖、模块依赖关系图 |
+| **总计** | **1,972** | |
+
+所有图表均使用 Mermaid 格式，共包含约 30+ 个 Mermaid 图表（架构图、类图、流程图、时序图）。

docs/architecture-overview.md

@@ -0,0 +1,187 @@
+# Claude Code 源码架构总览
+
+> 基于 2026-03-31 公开暴露的源码快照分析
+
+## 项目基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 语言 | TypeScript (strict) |
+| 运行时 | Bun |
+| 终端 UI | React + Ink |
+| CLI 框架 | Commander.js |
+| Schema 验证 | Zod v4 |
+| 代码搜索 | ripgrep |
+| 通信协议 | MCP SDK, LSP |
+| API | Anthropic SDK |
+| 遥测 | OpenTelemetry + gRPC |
+| 特性开关 | GrowthBook / Bun feature flags |
+| 认证 | OAuth 2.0, JWT, macOS Keychain |
+| 规模 | ~1,900 文件, 512,000+ 行代码 |
+
+## 整体架构
+
+```mermaid
+graph TB
+    subgraph 用户层
+        CLI[CLI 入口<br/>main.tsx]
+        IDE[IDE 扩展<br/>VS Code / JetBrains]
+        Desktop[桌面应用]
+        Mobile[移动应用]
+    end
+
+    subgraph 命令层
+        CMD[命令注册器<br/>commands.ts]
+        CMD_IMPL[命令实现<br/>commands/ ~82个]
+    end
+
+    subgraph 工具层
+        TOOL_REG[工具注册器<br/>tools.ts]
+        TOOL_IMPL[工具实现<br/>tools/ ~40个]
+        TOOL_TYPE[工具类型定义<br/>Tool.ts]
+    end
+
+    subgraph 核心引擎
+        QE[查询引擎<br/>QueryEngine.ts]
+        QS[查询管道<br/>query.ts]
+        CTX[上下文管理<br/>context.ts]
+    end
+
+    subgraph 服务层
+        API_SVC[API 服务<br/>services/api/]
+        MCP_SVC[MCP 服务<br/>services/mcp/]
+        AUTH_SVC[OAuth 认证<br/>services/oauth/]
+        LSP_SVC[LSP 服务<br/>services/lsp/]
+        ANALYTICS[分析/特性开关<br/>services/analytics/]
+    end
+
+    subgraph 基础设施
+        BRIDGE[IDE 桥接<br/>bridge/]
+        COORD[多代理协调<br/>coordinator/]
+        PLUGINS[插件系统<br/>plugins/]
+        SKILLS[技能系统<br/>skills/]
+        PERM[权限系统<br/>hooks/toolPermission/]
+    end
+
+    subgraph UI 层
+        COMP[UI 组件<br/>components/ ~140个]
+        SCREENS[全屏界面<br/>screens/]
+        VIM[Vim 模式<br/>vim/]
+        KB[快捷键<br/>keybindings/]
+    end
+
+    CLI --> CMD --> CMD_IMPL
+    CLI --> TOOL_REG --> TOOL_IMPL
+    IDE --> BRIDGE --> QE
+    QE --> QS --> API_SVC
+    TOOL_IMPL --> PERM
+    QE --> CTX
+    CMD_IMPL --> TOOL_IMPL
+    TOOL_IMPL --> MCP_SVC
+    TOOL_IMPL --> LSP_SVC
+    QE --> ANALYTICS
+    BRIDGE --> AUTH_SVC
+    CLI --> COMP --> SCREENS
+    COMP --> VIM
+    COMP --> KB
+    COORD --> TOOL_IMPL
+    PLUGINS --> TOOL_REG
+    SKILLS --> CMD
+```
+
+## 目录结构
+
+```
+src/
+├── main.tsx                 # 入口：Commander.js CLI + React/Ink 渲染
+├── commands.ts              # 命令注册器
+├── tools.ts                 # 工具注册器
+├── Tool.ts                  # 工具类型定义
+├── QueryEngine.ts           # LLM 查询引擎
+├── query.ts                 # 查询管道
+├── context.ts               # 系统/用户上下文收集
+├── cost-tracker.ts          # Token 成本追踪
+│
+├── commands/                # 命令实现 (~82 个命令, 189 个文件)
+├── tools/                   # 工具实现 (~40 个工具)
+├── components/              # Ink UI 组件 (~140 个)
+├── hooks/                   # React hooks (~70 个)
+├── services/                # 外部服务集成
+├── screens/                 # 全屏界面 (Doctor, REPL, Resume)
+├── types/                   # TypeScript 类型定义
+├── utils/                   # 工具函数
+│
+├── bridge/                  # IDE 和远程控制桥接 (30+ 文件)
+├── coordinator/             # 多代理协调器
+├── plugins/                 # 插件系统
+├── skills/                  # 技能系统
+├── keybindings/             # 快捷键配置
+├── vim/                     # Vim 模式
+├── voice/                   # 语音输入
+├── remote/                  # 远程会话
+├── server/                  # 服务模式
+├── memdir/                  # 持久化内存目录
+├── tasks/                   # 任务管理
+├── state/                   # 状态管理 (AppState)
+├── migrations/              # 配置迁移
+├── schemas/                 # 配置 Schema (Zod)
+├── entrypoints/             # 初始化逻辑
+├── ink/                     # Ink 渲染器包装
+├── buddy/                   # 伙伴精灵
+├── native-ts/               # 原生 TypeScript 工具
+├── outputStyles/            # 输出样式
+├── query/                   # 查询管道子模块
+├── assistant/               # 助手相关
+├── bootstrap/               # 引导逻辑
+├── cli/                     # CLI 相关
+├── constants/               # 常量定义
+├── context/                 # 上下文子模块
+├── moreright/               # 扩展权限
+└── upstreamproxy/           # 代理配置
+```
+
+## 启动流程
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Main as main.tsx
+    participant Commander as Commander.js
+    participant MDM as MDM 设置
+    participant Keychain as macOS Keychain
+    participant GB as GrowthBook
+    participant Ink as Ink 渲染器
+    participant REPL as REPL 主循环
+
+    User->>Main: claude [command]
+    Main->>MDM: 并行预取 MDM 设置
+    Main->>Keychain: 并行预取 Keychain
+    Main->>GB: 并行初始化 GrowthBook
+    Main->>Commander: 解析 CLI 参数
+    Commander->>Main: 路由到对应命令
+    Main->>Ink: 初始化 React/Ink 渲染
+    Ink->>REPL: 启动 REPL 主循环
+    REPL->>REPL: 进入查询-响应循环
+```
+
+## 核心设计模式
+
+### 1. 并行预取 (Parallel Prefetch)
+启动时并行预取 MDM 设置、Keychain 读取和 API 预连接，优化启动时间。
+
+### 2. 惰性加载 (Lazy Loading)
+重型模块（OpenTelemetry、gRPC、分析等）通过动态 `import()` 延迟加载。
+
+### 3. 特性开关 (Feature Flags)
+通过 Bun 的 `bun:bundle` 实现编译时死代码消除：
+```typescript
+const SleepTool = feature('PROACTIVE') || feature('KAIROS')
+  ? require('./tools/SleepTool/SleepTool.js').SleepTool
+  : null
+```
+
+### 4. 代理集群 (Agent Swarms)
+通过 `AgentTool` 生成子代理，`coordinator/` 处理多代理编排，`TeamCreateTool` 支持团队级并行工作。
+
+### 5. 工具搜索延迟发现
+`ToolSearchTool` 允许在工具数量超过阈值时延迟加载工具定义，减少 prompt token 开销。

docs/command-system.md

@@ -0,0 +1,234 @@
+# 命令系统分析
+
+## 架构概述
+
+命令系统通过 `/` 前缀提供用户交互功能，共约 82 个命令目录、189 个文件。
+
+```mermaid
+classDiagram
+    class Command {
+        +string name
+        +string description
+        +boolean hidden
+        +execute(args) void
+    }
+
+    class InteractiveCommand {
+        +React 组件渲染
+        +用户交互
+    }
+
+    class NonInteractiveCommand {
+        +纯逻辑执行
+        +无 UI
+    }
+
+    Command <|-- InteractiveCommand
+    Command <|-- NonInteractiveCommand
+    InteractiveCommand <|-- CommitCommand
+    InteractiveCommand <|-- DoctorCommand
+    InteractiveCommand <|-- ReviewCommand
+    NonInteractiveCommand <|-- ClearCommand
+    NonInteractiveCommand <|-- CostCommand
+    NonInteractiveCommand <|-- CompactCommand
+```
+
+## 命令类型系统
+
+所有命令统一使用三种基本类型：
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| `local` | 执行本地操作，返回文本结果 | 简单操作（/clear、/cost） |
+| `local-jsx` | 执行本地操作并渲染 React 组件 | 需要用户交互（/help、/theme） |
+| `prompt` | 扩展为提示文本，由模型执行 | 需要 AI 能力（/commit、/review） |
+
+## 命令来源
+
+```mermaid
+flowchart LR
+    A[命令来源] --> B[builtin<br/>内置命令]
+    A --> C[skills/<br/>技能目录]
+    A --> D[bundled<br/>打包技能]
+    A --> E[plugin<br/>插件命令]
+    A --> F[managed<br/>托管命令]
+    A --> G[mcp<br/>MCP 技能]
+
+    B --> H[commands.ts<br/>统一注册]
+    C --> H
+    D --> H
+    E --> H
+    F --> H
+    G --> H
+```
+
+## 命令注册机制
+
+命令在 `src/commands.ts` 中注册，使用 `memoize` 缓存，支持延迟加载（`load()` 按需加载实现）。使用 Fuse.js 实现模糊搜索，支持命令名称、描述和别名匹配。
+
+```mermaid
+flowchart TD
+    A[COMMANDS memoize] --> B[核心命令注册]
+    B --> C[loadSkillsDir<br/>用户技能]
+    B --> D[initBundledSkills<br/>打包技能]
+    B --> E[插件加载器<br/>插件命令]
+
+    F{可用性检查} --> G[meetsAvailabilityRequirement]
+    G --> H[isCommandEnabled<br/>功能标志/平台/环境]
+    G --> I[availability<br/>claude-ai/console]
+```
+
+## 命令分类
+
+### 交互管理类
+| 命令 | 功能 |
+|------|------|
+| `/compact` | 压缩对话上下文 |
+| `/clear` | 清除对话/缓存 |
+| `/rewind` | 回退对话状态 |
+| `/resume` | 恢复之前的会话 |
+| `/exit` | 退出程序 |
+| `/rename` | 重命名会话 |
+
+### 代码工作流类
+| 命令 | 功能 |
+|------|------|
+| `/commit` | 创建 Git 提交 |
+| `/review` | 代码审查 |
+| `/diff` | 查看变更 |
+| `/autofix-pr` | 自动修复 PR |
+| `/pr_comments` | 查看 PR 评论 |
+| `/bughunter` | Bug 搜索 |
+| `/plan` | 计划模式 |
+
+### 环境和配置类
+| 命令 | 功能 |
+|------|------|
+| `/config` | 设置管理 |
+| `/doctor` | 环境诊断 |
+| `/env` | 环境变量管理 |
+| `/permissions` | 权限管理 |
+| `/sandbox-toggle` | 沙盒开关 |
+| `/keybindings` | 快捷键配置 |
+| `/vim` | Vim 模式切换 |
+| `/theme` | 主题切换 |
+| `/color` | 颜色配置 |
+| `/output-style` | 输出样式 |
+| `/effort` | 思考力度设置 |
+| `/model` | 模型选择 |
+
+### 认证和账户类
+| 命令 | 功能 |
+|------|------|
+| `/login` | 登录 |
+| `/logout` | 登出 |
+| `/cost` | 使用成本查看 |
+| `/usage` | 使用量查看 |
+| `/extra-usage` | 额外用量 |
+| `/rate-limit-options` | 速率限制选项 |
+| `/reset-limits` | 重置限制 |
+| `/passes` | 使用通行证 |
+
+### 工具集成类
+| 命令 | 功能 |
+|------|------|
+| `/mcp` | MCP 服务器管理 |
+| `/skills` | 技能管理 |
+| `/plugin` | 插件管理 |
+| `/reload-plugins` | 重新加载插件 |
+| `/hooks` | 钩子管理 |
+| `/lsp` | LSP 管理 |
+
+### IDE 和远程类
+| 命令 | 功能 |
+|------|------|
+| `/bridge` | IDE 桥接模式 |
+| `/ide` | IDE 集成 |
+| `/desktop` | 桌面应用切换 |
+| `/mobile` | 移动应用切换 |
+| `/chrome` | Chrome 扩展集成 |
+| `/remote-env` | 远程环境 |
+| `/remote-setup` | 远程设置 |
+| `/teleport` | 传送（远程会话迁移） |
+
+### 信息查看类
+| 命令 | 功能 |
+|------|------|
+| `/help` | 帮助信息 |
+| `/context` | 上下文可视化 |
+| `/ctx_viz` | 上下文结构可视化 |
+| `/stats` | 统计信息 |
+| `/status` | 状态查看 |
+| `/cost` | 成本查看 |
+| `/memory` | 持久化内存管理 |
+| `/files` | 文件列表 |
+| `/session` | 会话管理 |
+| `/thinkback` | 回溯思考过程 |
+| `/thinkback-play` | 回放思考过程 |
+| `/summary` | 会话摘要 |
+| `/share` | 分享会话 |
+| `/export` | 导出会话 |
+| `/release-notes` | 更新日志 |
+| `/feedback` | 反馈 |
+
+### 开发调试类
+| 命令 | 功能 |
+|------|------|
+| `/debug-tool-call` | 调试工具调用 |
+| `/heapdump` | 堆转储 |
+| `/perf-issue` | 性能问题 |
+| `/break-cache` | 缓存清除 |
+| `/mock-limits` | 模拟限制 |
+| `/ant-trace` | 内部追踪 |
+| `/backfill-sessions` | 回填会话 |
+| `/debug` | 调试模式 |
+
+### 特殊功能类
+| 命令 | 功能 |
+|------|------|
+| `/voice` | 语音输入 |
+| `/add-dir` | 添加工作目录 |
+| `/branch` | 分支管理 |
+| `/tag` | 标签管理 |
+| `/copy` | 复制输出 |
+| `/onboarding` | 新手引导 |
+| `/upgrade` | 升级 |
+| `/fast` | 快速模式切换 |
+| `/btw` | 顺便提到 |
+| `/good-claude` | 正面反馈 |
+| `/stickers` | 贴纸 |
+| `/issue` | Issue 管理 |
+| `/install-github-app` | 安装 GitHub 应用 |
+| `/install-slack-app` | 安装 Slack 应用 |
+| `/advisor` | 顾问 |
+| `/agents` | 代理管理 |
+| `/passes` | 使用通行证 |
+| `/privacy-settings` | 隐私设置 |
+| `/terminalSetup` | 终端设置 |
+
+## 命令执行流程
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Input as TextInput
+    participant Parser as 命令解析器
+    participant Registry as commands.ts
+    participant Impl as 命令实现
+    participant UI as Ink 渲染
+
+    User->>Input: 输入 /commit
+    Input->>Parser: 识别 / 前缀
+    Parser->>Registry: 查找命令
+    Registry->>Impl: 命令路由
+    Impl->>UI: 渲染交互界面
+    UI->>User: 显示结果
+```
+
+## 特殊命令集
+
+| 集合 | 说明 |
+|------|------|
+| `REMOTE_SAFE_COMMANDS` | 远程模式下可安全执行的命令（不依赖本地文件系统） |
+| `BRIDGE_SAFE_COMMANDS` | 可通过远程控制桥接安全执行的命令 |
+| `immediate` 命令 | 不需要等待停止点，立即执行的命令（如 /status、/cost） |

docs/data-flow.md

@@ -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
+```

docs/file-statistics.md

@@ -0,0 +1,150 @@
+# 项目文件统计分析
+
+## 代码规模
+
+| 目录 | 文件数（估算） | 说明 |
+|------|---------------|------|
+| `commands/` | 189 | 命令实现，约 82 个命令目录 |
+| `components/` | 180+ | UI 组件 |
+| `hooks/` | 70+ | React Hooks |
+| `tools/` | 80+ | 工具实现，约 40 个工具 |
+| `services/` | 50+ | 服务层 |
+| `bridge/` | 30+ | IDE 桥接 |
+| `utils/` | 50+ | 工具函数 |
+| `types/` | 10+ | 类型定义 |
+| 其他 | 50+ | 状态、Schema、Vim 等 |
+| **总计** | **~1,900** | **512,000+ 行代码** |
+
+## 核心文件规模
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `main.tsx` | ~804K (含内联) | CLI 入口（可能包含内联数据） |
+| `QueryEngine.ts` | ~46K | 查询引擎 |
+| `query.ts` | ~68K | 查询管道 |
+| `commands.ts` | ~25K | 命令注册 |
+| `Tool.ts` | ~29K | 工具类型定义 |
+| `tools.ts` | ~17K | 工具注册 |
+| `interactiveHelpers.tsx` | ~57K | 交互辅助 |
+| `history.ts` | ~23K | 历史记录 |
+| `setup.ts` | ~20K | 初始化设置 |
+| `context.ts` | ~6K | 上下文管理 |
+
+## 技术栈依赖
+
+### 运行时和语言
+- **Bun** — JavaScript/TypeScript 运行时，提供 `bun:bundle` 编译时特性开关
+- **TypeScript (strict)** — 类型安全
+
+### 终端 UI
+- **React** — 组件化 UI 框架
+- **Ink** — React 终端渲染器
+
+### CLI 和工具
+- **Commander.js** — CLI 参数解析
+- **ripgrep** — 代码搜索（通过子进程调用）
+- **Zod v4** — Schema 验证
+
+### 协议和 API
+- **Anthropic SDK** — Claude API 客户端
+- **MCP SDK** — Model Context Protocol
+- **LSP** — Language Server Protocol
+
+### 遥测和分析
+- **OpenTelemetry** — 遥测数据收集
+- **gRPC** — 远程过程调用
+- **GrowthBook** — 特性开关和 A/B 测试
+
+### 认证和安全
+- **OAuth 2.0** — 用户认证
+- **JWT** — Token 认证
+- **macOS Keychain** — 凭据安全存储
+
+## 模块依赖关系
+
+```mermaid
+graph LR
+    subgraph 入口
+        MAIN[main.tsx]
+    end
+
+    subgraph 核心
+        QE[QueryEngine]
+        QUERY[query.ts]
+        CTX[context.ts]
+    end
+
+    subgraph 能力层
+        TOOLS[tools.ts]
+        CMDS[commands.ts]
+    end
+
+    subgraph 实现层
+        TOOL_IMPL[tools/]
+        CMD_IMPL[commands/]
+    end
+
+    subgraph 基础设施
+        SERVICES[services/]
+        BRIDGE[bridge/]
+        HOOKS[hooks/]
+    end
+
+    subgraph UI
+        COMPONENTS[components/]
+        SCREENS[screens/]
+    end
+
+    MAIN --> QE
+    MAIN --> CMDS
+    MAIN --> COMPONENTS
+
+    QE --> QUERY
+    QE --> CTX
+    QE --> TOOLS
+
+    TOOLS --> TOOL_IMPL
+    CMDS --> CMD_IMPL
+
+    TOOL_IMPL --> SERVICES
+    TOOL_IMPL --> HOOKS
+    TOOL_IMPL --> BRIDGE
+
+    COMPONENTS --> HOOKS
+
+    QE --> SERVICES
+```
+
+## 关键设计决策
+
+### 1. Bun 运行时
+选择 Bun 而非 Node.js，获得：
+- 更快的启动时间
+- 原生 TypeScript 支持
+- `bun:bundle` 编译时特性开关（死代码消除）
+- 内置的文件系统 API
+
+### 2. React + Ink 终端 UI
+使用 React 组件模型构建 Terminal UI，获得：
+- 声明式 UI 编程
+- 状态管理一致性
+- 丰富的组件复用
+
+### 3. 工具/命令分离
+- **工具 (Tools)** — Agent 可调用的能力，通过 API 对话使用
+- **命令 (Commands)** — 用户直接调用的交互功能，通过 `/` 前缀使用
+- 两者解耦，但命令可以调用工具
+
+### 4. MCP 协议
+通过 Model Context Protocol 支持外部工具扩展：
+- 标准化的工具注册和调用
+- 支持多种传输方式（stdio、SSE、SDK）
+- 动态工具发现
+
+### 5. 代理集群架构
+支持多代理并行工作：
+- `AgentTool` 生成子代理
+- `coordinator/` 编排多代理
+- `TeamCreateTool`/`TeamDeleteTool` 管理代理团队
+- `SendMessageTool` 代理间通信
+- Git Worktree 隔离

docs/services-and-infrastructure.md

@@ -0,0 +1,292 @@
+# 服务层与基础设施分析
+
+## 服务层架构
+
+```mermaid
+graph TB
+    subgraph API 服务
+        API_CLIENT[client.ts<br/>Anthropic API 客户端]
+        API_CLAUDE[claude.ts<br/>Claude API 封装]
+        API_BOOTSTRAP[bootstrap.ts<br/>引导逻辑]
+        API_FILES[filesApi.ts<br/>文件 API]
+        API_USAGE[usage.ts<br/>使用量查询]
+        API_SESSION[sessionIngress.ts<br/>会话入口]
+        API_ERRORS[errors.ts<br/>错误处理]
+        API_RETRY[withRetry.ts<br/>重试逻辑]
+        API_GROVE[grove.ts<br/>Grove 集成]
+    end
+
+    subgraph MCP 服务
+        MCP_MGR[MCPConnectionManager.tsx<br/>MCP 连接管理器]
+        MCP_AUTH[auth.ts<br/>MCP 认证]
+        MCP_CONFIG[config.ts<br/>MCP 配置]
+        MCP_TYPES[types.ts<br/>MCP 类型定义]
+        MCP_REGISTRY[officialRegistry.ts<br/>官方注册表]
+        MCP_VSCODE[vscodeSdkMcp.ts<br/>VSCode SDK MCP]
+        MCP_SDK[SdkControlTransport.ts<br/>SDK 控制传输]
+        MCP_NORMAL[normalization.ts<br/>MCP 规范化]
+    end
+
+    subgraph OAuth 认证
+        OAUTH_FLOW[OAuth 2.0 流程]
+        OAUTH_XAA[xaa.ts / xaaIdpLogin.ts<br/>XAA 认证]
+        OAUTH_PORT[oauthPort.ts<br/>OAuth 端口]
+    end
+
+    subgraph 分析服务
+        ANALYTICS_GROWTH[GrowthBook 特性开关]
+        ANALYTICS_TELEMETRY[OpenTelemetry 遥测]
+        ANALYTICS_TRACKING[diagnosticTracking.ts<br/>诊断追踪]
+    end
+
+    subgraph 其他服务
+        COMPACT[compact/<br/>上下文压缩]
+        POLICY[policyLimits/<br/>组织策略限制]
+        REMOTE_SETTINGS[remoteManagedSettings/<br/>远程托管设置]
+        EXTRACT_MEM[extractMemories/<br/>自动记忆提取]
+        TOKEN_EST[tokenEstimation.ts<br/>Token 估算]
+        TEAM_MEM[teamMemorySync/<br/>团队记忆同步]
+        SESSION_MEM[SessionMemory/<br/>会话记忆]
+        LSP[lsp/<br/>Language Server Protocol]
+        PLUGINS[plugins/<br/>插件加载器]
+        VOICE[voice.ts / voiceStreamSTT.ts<br/>语音输入/STT]
+    end
+```
+
+## Bridge 桥接系统
+
+Bridge 是 IDE 扩展与 Claude Code CLI 之间的双向通信层，支持 VS Code 和 JetBrains。
+
+```mermaid
+sequenceDiagram
+    participant IDE as IDE 扩展<br/>(VS Code / JetBrains)
+    participant BridgeMain as bridgeMain.ts
+    participant Messaging as bridgeMessaging.ts
+    participant ReplBridge as replBridge.ts
+    participant JWT as jwtUtils.ts
+    participant Session as sessionRunner.ts
+    participant CLI as Claude Code CLI
+
+    IDE->>BridgeMain: 建立连接
+    BridgeMain->>JWT: JWT 认证
+    JWT-->>BridgeMain: 认证通过
+    IDE->>Messaging: 发送消息
+    Messaging->>ReplBridge: 转发到 REPL
+    ReplBridge->>Session: 执行会话
+    Session->>CLI: 调用工具/命令
+    CLI-->>Session: 返回结果
+    Session-->>ReplBridge: 处理结果
+    ReplBridge-->>Messaging: 构建响应
+    Messaging-->>IDE: 返回结果
+```
+
+### Bridge 核心模块
+
+| 文件 | 功能 |
+|------|------|
+| `bridgeMain.ts` | Bridge 主循环 |
+| `bridgeMessaging.ts` | 消息协议定义 |
+| `bridgePermissionCallbacks.ts` | 权限回调处理 |
+| `bridgeConfig.ts` | Bridge 配置 |
+| `bridgeApi.ts` | Bridge API 接口 |
+| `bridgeDebug.ts` | Bridge 调试工具 |
+| `bridgeEnabled.ts` | Bridge 启用状态检测 |
+| `bridgeUI.ts` | Bridge UI 组件 |
+| `replBridge.ts` | REPL 会话桥接 |
+| `replBridgeHandle.ts` | REPL Bridge 句柄 |
+| `replBridgeTransport.ts` | REPL Bridge 传输层 |
+| `initReplBridge.ts` | REPL Bridge 初始化 |
+| `jwtUtils.ts` | JWT 认证工具 |
+| `sessionRunner.ts` | 会话执行管理 |
+| `createSession.ts` | 会话创建 |
+| `codeSessionApi.ts` | Code 会话 API |
+| `capacityWake.ts` | 容量唤醒 |
+| `remoteBridgeCore.ts` | 远程 Bridge 核心 |
+| `trustedDevice.ts` | 受信任设备 |
+| `workSecret.ts` | 工作密钥 |
+
+## 多代理协调器
+
+```mermaid
+flowchart TD
+    A[coordinatorMode.ts] --> B{协调器模式?}
+    B -->|是| C[分发任务给 Worker]
+    B -->|否| D[普通模式]
+
+    C --> E[Worker 1<br/>AgentTool]
+    C --> F[Worker 2<br/>AgentTool]
+    C --> G[Worker N<br/>AgentTool]
+
+    E --> H[SendMessage<br/>消息传递]
+    F --> H
+    G --> H
+    H --> I[Coordinator<br/>汇总结果]
+
+    C --> J[TaskCreate<br/>任务创建]
+    J --> K[TaskUpdate<br/>任务更新]
+    K --> L[TaskList<br/>任务列表]
+```
+
+## 插件系统
+
+```mermaid
+flowchart LR
+    A[builtinPlugins.ts<br/>内置插件] --> C[插件加载器]
+    B[bundled/<br/>捆绑插件] --> C
+    D[用户插件目录<br/>.claude/plugins/] --> C
+    C --> E[插件注册]
+    E --> F[工具扩展]
+    E --> G[命令扩展]
+    E --> H[Hook 扩展]
+```
+
+## 技能系统
+
+```mermaid
+flowchart LR
+    A[bundled/<br/>捆绑技能] --> C[技能加载器]
+    B[bundledSkills.ts<br/>技能注册] --> C
+    D[loadSkillsDir.ts<br/>用户技能目录] --> C
+    E[mcpSkillBuilders.ts<br/>MCP 技能构建] --> C
+    C --> F[SkillTool<br/>技能执行]
+```
+
+### 内置技能清单
+
+| 技能 | 功能 |
+|------|------|
+| update-config | 配置 settings.json 和 hooks |
+| simplify | 代码简化和质量审查 |
+| loop | 定时循环执行命令 |
+| claude-api | Claude API / Anthropic SDK 开发 |
+| commit | Git 提交 |
+| remember | 记忆管理 |
+
+### MCP 服务详细架构
+
+MCP (Model Context Protocol) 服务支持多种传输协议：
+
+```mermaid
+flowchart TD
+    A[MCPConnectionManager] --> B{传输协议}
+    B -->|stdio| C[子进程通信]
+    B -->|SSE| D[Server-Sent Events]
+    B -->|HTTP| E[HTTP 传输]
+    B -->|SDK| F[SdkControlTransport<br/>IDE SDK 控制]
+
+    A --> G[officialRegistry.ts<br/>官方 MCP 服务器注册表]
+    A --> H[vscodeSdkMcp.ts<br/>VS Code SDK 集成]
+    A --> I[normalization.ts<br/>工具名规范化]
+
+    A --> J[auth.ts<br/>认证]
+    J --> K[OAuth 认证]
+    J --> L[API Key 认证]
+    J --> M[XAA 认证<br/>xaa.ts / xaaIdpLogin.ts]
+```
+
+### OAuth 认证流程
+
+```mermaid
+sequenceDiagram
+    participant CLI as Claude Code
+    participant Browser as 浏览器
+    participant OAuth as OAuth 服务
+    participant Listener as 本地监听
+
+    CLI->>OAuth: 生成 PKCE 挑战
+    CLI->>Browser: 打开授权页面
+    Browser->>OAuth: 用户授权
+    OAuth-->>Browser: 授权码
+    Browser->>Listener: 回调携带授权码
+    Listener->>CLI: 传递授权码
+    CLI->>OAuth: 用授权码 + PKCE 换取令牌
+    OAuth-->>CLI: Access Token + Refresh Token
+    CLI->>CLI: 存储令牌（Keychain/文件）
+```
+
+### LSP 服务架构
+
+```mermaid
+flowchart TD
+    A[lsp/manager.ts<br/>LSP 管理器<br/>单例模式] --> B[LSPServerManager<br/>服务器管理]
+    B --> C[LSPServerInstance<br/>单个服务器实例]
+    B --> D[config.ts<br/>服务器配置]
+
+    C --> E[TypeScript Server]
+    C --> F[Python Server]
+    C --> G[Go Server]
+    C --> H[其他语言服务器]
+
+    A --> I[功能]
+    I --> J[代码诊断<br/>被动反馈]
+    I --> K[跳转定义<br/>hover 信息]
+    I --> L[代码补全]
+    I --> M[多项目并行连接]
+```
+
+## 查询引擎 (QueryEngine.ts)
+
+QueryEngine 是核心的 LLM API 调用引擎（约 46K 行），处理流式响应、工具调用循环、思考模式和 Token 计数。
+
+```mermaid
+flowchart TD
+    A[QueryEngine.ts<br/>~46K 行] --> B[query.ts<br/>查询管道<br/>~68K 行]
+    A --> C[流式响应处理]
+    A --> D[工具调用循环]
+    A --> E[思考模式管理]
+    A --> F[重试逻辑]
+    A --> G[Token 计数]
+
+    B --> H[query/ 子模块]
+    H --> I[查询管道子步骤]
+
+    D --> J{工具调用?}
+    J -->|是| K[执行工具]
+    K --> L[收集结果]
+    L --> M[继续对话循环]
+    J -->|否| N[生成最终响应]
+
+    C --> O[SSE 流解析]
+    C --> P[增量渲染]
+```
+
+## 权限系统
+
+```mermaid
+flowchart TD
+    A[hooks/toolPermission/<br/>权限系统] --> B[PermissionMode]
+    B --> C[default<br/>默认模式]
+    B --> D[plan<br/>计划模式]
+    B --> E[bypassPermissions<br/>绕过权限]
+    B --> F[auto<br/>自动模式]
+    B --> G[dontAsk<br/>不询问模式]
+
+    A --> H[工具调用拦截]
+    H --> I{权限检查}
+    I -->|允许规则| J[执行]
+    I -->|拒绝规则| K[拒绝]
+    I -->|无规则| L[询问用户]
+```
+
+## 特性开关体系
+
+通过 Bun 的 `bun:bundle` 实现编译时死代码消除：
+
+| 特性开关 | 控制功能 |
+|----------|----------|
+| `PROACTIVE` | 主动模式（SleepTool） |
+| `KAIROS` | KAIROS 功能集 |
+| `BRIDGE_MODE` | IDE Bridge 模式 |
+| `DAEMON` | 守护进程模式 |
+| `VOICE_MODE` | 语音模式 |
+| `AGENT_TRIGGERS` | 定时触发器（Cron） |
+| `AGENT_TRIGGERS_REMOTE` | 远程触发器 |
+| `MONITOR_TOOL` | 监控工具 |
+| `COORDINATOR_MODE` | 多代理协调模式 |
+| `CONTEXT_COLLAPSE` | 上下文折叠 |
+| `TERMINAL_PANEL` | 终端面板 |
+| `WEB_BROWSER_TOOL` | Web 浏览器工具 |
+| `WORKFLOW_SCRIPTS` | 工作流脚本 |
+| `HISTORY_SNIP` | 历史记录剪辑 |
+| `UDS_INBOX` | UDS 收件箱 |
+| `OVERFLOW_TEST_TOOL` | 溢出测试工具 |

docs/tool-system.md

@@ -0,0 +1,262 @@
+# 工具系统分析
+
+## 架构概述
+
+工具系统是 Claude Code 的核心能力层，定义了 Agent 可以执行的所有操作。每个工具是一个自包含模块，包含输入 Schema、权限模型和执行逻辑。
+
+```mermaid
+classDiagram
+    class Tool {
+        +string name
+        +string description
+        +ToolInputJSONSchema inputSchema
+        +isEnabled() boolean
+        +getDescription() string
+        +getPrompt() string
+        +execute(input, context) ToolResult
+        +validateInput(input) ValidationResult
+    }
+
+    class BashTool {
+        +name = "Bash"
+        +execute() 运行 Shell 命令
+        +沙盒支持
+        +安全验证
+    }
+
+    class FileReadTool {
+        +name = "Read"
+        +支持图片/PDF/Notebook
+        +行号范围读取
+    }
+
+    class FileWriteTool {
+        +name = "Write"
+        +完整文件写入
+        +读取前置检查
+    }
+
+    class FileEditTool {
+        +name = "Edit"
+        +字符串替换编辑
+        +replace_all 模式
+    }
+
+    class GlobTool {
+        +name = "Glob"
+        +文件模式匹配
+        +基于 ripgrep
+    }
+
+    class GrepTool {
+        +name = "Grep"
+        +内容正则搜索
+        +ripgrep 集成
+    }
+
+    class AgentTool {
+        +name = "Agent"
+        +子代理生成
+        +worktree 隔离
+        +代理类型选择
+    }
+
+    class MCPTool {
+        +MCP 服务器工具调用
+    }
+
+    class LSPTool {
+        +LSP 操作
+        +goToDefinition 等
+    }
+
+    class WebFetchTool {
+        +URL 内容获取
+    }
+
+    class WebSearchTool {
+        +Web 搜索
+    }
+
+    Tool <|-- BashTool
+    Tool <|-- FileReadTool
+    Tool <|-- FileWriteTool
+    Tool <|-- FileEditTool
+    Tool <|-- GlobTool
+    Tool <|-- GrepTool
+    Tool <|-- AgentTool
+    Tool <|-- MCPTool
+    Tool <|-- LSPTool
+    Tool <|-- WebFetchTool
+    Tool <|-- WebSearchTool
+```
+
+## 工具注册机制
+
+工具注册在 `src/tools.ts` 中，通过 `getAllBaseTools()` 函数集中管理：
+
+```mermaid
+flowchart TD
+    A[getAllBaseTools] --> B{环境判断}
+    B -->|默认| C[核心工具集]
+    B -->|USER_TYPE=ant| D[内部工具集]
+    B -->|feature flag| E[特性开关工具]
+
+    C --> F[AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool, NotebookEditTool, WebFetchTool, WebSearchTool, AskUserQuestionTool, SkillTool, BriefTool, TaskStopTool, TodoWriteTool, ExitPlanModeV2Tool, ListMcpResourcesTool, ReadMcpResourceTool]
+
+    D --> G[ConfigTool, TungstenTool, REPLTool, SuggestBackgroundPRTool]
+
+    E --> H[SleepTool PROACTIVE/KAIROS]
+    E --> I[CronCreateTool/CronDeleteTool/CronListTool AGENT_TRIGGERS]
+    E --> J[RemoteTriggerTool AGENT_TRIGGERS_REMOTE]
+    E --> K[EnterWorktreeTool/ExitWorktreeTool]
+    E --> L[TeamCreateTool/TeamDeleteTool]
+    E --> M[SendMessageTool]
+    E --> N[ToolSearchTool]
+    E --> O[WorkflowTool WORKFLOW_SCRIPTS]
+    E --> P[WebBrowserTool WEB_BROWSER_TOOL]
+    E --> Q[MonitorTool MONITOR_TOOL]
+    E --> R[PowerShellTool]
+```
+
+## 工具分类
+
+### 文件操作类
+| 工具 | 名称 | 功能 |
+|------|------|------|
+| FileReadTool | Read | 读取文件（支持图片、PDF、Jupyter Notebook） |
+| FileWriteTool | Write | 创建或覆盖文件 |
+| FileEditTool | Edit | 部分文件修改（字符串替换） |
+| GlobTool | Glob | 文件模式匹配搜索 |
+| GrepTool | Grep | 基于 ripgrep 的内容搜索 |
+| NotebookEditTool | NotebookEdit | Jupyter Notebook 编辑 |
+
+### 执行类
+| 工具 | 名称 | 功能 |
+|------|------|------|
+| BashTool | Bash | Shell 命令执行（含沙盒） |
+| PowerShellTool | PowerShell | Windows PowerShell 命令 |
+
+### 网络类
+| 工具 | 名称 | 功能 |
+|------|------|------|
+| WebFetchTool | WebFetch | 获取 URL 内容 |
+| WebSearchTool | WebSearch | Web 搜索 |
+
+### 代理和协调类
+| 工具 | 名称 | 功能 |
+|------|------|------|
+| AgentTool | Agent | 生成子代理（支持 worktree 隔离） |
+| SendMessageTool | SendMessage | 代理间消息传递 |
+| TeamCreateTool | TeamCreate | 创建代理团队 |
+| TeamDeleteTool | TeamDelete | 删除代理团队 |
+| TaskCreateTool | TaskCreate | 创建任务 |
+| TaskGetTool | TaskGet | 获取任务详情 |
+| TaskUpdateTool | TaskUpdate | 更新任务状态 |
+| TaskListTool | TaskList | 列出所有任务 |
+| TaskOutputTool | TaskOutput | 获取后台任务输出 |
+| TaskStopTool | TaskStop | 停止后台任务 |
+
+### 交互类
+| 工具 | 名称 | 功能 |
+|------|------|------|
+| AskUserQuestionTool | AskUserQuestion | 向用户提问获取输入 |
+| EnterPlanModeTool | EnterPlanMode | 进入计划模式 |
+| ExitPlanModeV2Tool | ExitPlanMode | 退出计划模式 |
+| EnterWorktreeTool | EnterWorktree | 进入 Git Worktree |
+| ExitWorktreeTool | ExitWorktree | 退出 Git Worktree |
+
+### 集成类
+| 工具 | 名称 | 功能 |
+|------|------|------|
+| MCPTool | (动态) | MCP 服务器工具调用 |
+| ListMcpResourcesTool | ListMcpResources | 列出 MCP 资源 |
+| ReadMcpResourceTool | ReadMcpResource | 读取 MCP 资源 |
+| LSPTool | LSP | Language Server Protocol 集成 |
+| SkillTool | Skill | 技能执行 |
+
+### 特殊类
+| 工具 | 名称 | 功能 |
+|------|------|------|
+| BriefTool | Brief | 附件处理和上传 |
+| ConfigTool | Config | 设置管理（仅内部） |
+| ToolSearchTool | ToolSearch | 延迟工具发现 |
+| TodoWriteTool | TodoWrite | 待办事项管理 |
+| SleepTool | Sleep | 主动模式等待 |
+| SyntheticOutputTool | SyntheticOutput | 结构化输出生成 |
+| ScheduleCronTool | CronCreate/CronDelete/CronList | 定时任务 |
+| RemoteTriggerTool | RemoteTrigger | 远程触发 |
+| REPLTool | REPL | REPL 模式（仅内部） |
+| WorkflowTool | Workflow | 工作流脚本执行 |
+| WebBrowserTool | WebBrowser | Web 浏览器自动化 |
+
+## 权限模型
+
+```mermaid
+flowchart TD
+    A[工具调用请求] --> B{权限检查}
+    B -->|auto 模式| C[自动允许]
+    B -->|default 模式| D{规则匹配}
+    B -->|plan 模式| E[只读操作允许]
+    B -->|bypassPermissions| C
+
+    D -->|允许规则| F[执行工具]
+    D -->|拒绝规则| G[拒绝执行]
+    D -->|无规则| H[提示用户]
+
+    H -->|用户允许| F
+    H -->|用户拒绝| G
+    H -->|用户允许本次| I[临时允许并执行]
+
+    G --> J[getDenyRuleForTool 过滤]
+    J --> K[从工具列表中移除]
+```
+
+## AgentTool 子代理架构
+
+```mermaid
+flowchart TD
+    A[AgentTool] --> B[子代理类型选择]
+    B --> C[general-purpose<br/>通用代理]
+    B --> D[Explore<br/>代码探索]
+    B --> E[Plan<br/>架构规划]
+    B --> F[claude-code-guide<br/>使用指南]
+
+    C --> G[可用工具: 全部]
+    D --> H[可用工具: 只读<br/>Glob, Grep, Read, Agent]
+    E --> I[可用工具: 只读<br/>同 Explore]
+
+    A --> J{隔离模式}
+    J -->|worktree| K[Git Worktree 隔离]
+    J -->|默认| L[同目录执行]
+
+    A --> M[代理能力]
+    M --> N[并行代理启动]
+    M --> O[后台运行]
+    M --> P[消息传递]
+    M --> Q[内存管理]
+```
+
+## BashTool 安全机制
+
+```mermaid
+flowchart TD
+    A[BashTool 命令执行] --> B{安全检查}
+    B --> C[路径验证<br/>pathValidation.ts]
+    B --> D[只读验证<br/>readOnlyValidation.ts]
+    B --> E[破坏性命令警告<br/>destructiveCommandWarning.ts]
+    B --> F[沙盒检查<br/>shouldUseSandbox.ts]
+    B --> G[sed 命令验证<br/>sedValidation.ts]
+
+    C --> H{在工作目录内?}
+    H -->|是| I[允许执行]
+    H -->|否| J[路径限制警告]
+
+    E --> K{破坏性命令?}
+    K -->|rm, git reset --hard| L[额外确认]
+    K -->|其他| I
+
+    F --> M{沙盒可用?}
+    M -->|是| N[沙盒执行]
+    M -->|否| I
+```

docs/types-utils-state.md

@@ -0,0 +1,363 @@
+# 类型系统、工具函数与状态管理分析
+
+## 类型系统
+
+### 类型定义目录结构
+
+```mermaid
+graph TB
+    subgraph types/
+        CMD[command.ts<br/>命令类型]
+        GEN[generated/<br/>生成类型]
+        HOOKS[hooks.ts<br/>Hook 类型]
+        IDS[ids.ts<br/>ID 类型]
+        LOGS[logs.ts<br/>日志类型]
+        PERM[permissions.ts<br/>权限类型]
+        PLUGIN[plugin.ts<br/>插件类型]
+        TEXT[textInputTypes.ts<br/>文本输入类型]
+    end
+
+    subgraph 核心类型定义
+        TOOL_TYPE[Tool.ts<br/>工具类型]
+        MSG[types/message.ts<br/>消息类型]
+        TOOL_TYPES[types/tools.ts<br/>工具进度类型]
+    end
+
+    subgraph Schema 验证
+        SCHEMAS[schemas/<br/>Zod Schema]
+    end
+```
+
+### 关键类型定义
+
+#### 权限类型 (`types/permissions.ts`)
+```typescript
+// 权限模式
+type PermissionMode =
+  | 'default'      // 默认：提示用户
+  | 'plan'         // 计划：只读操作
+  | 'bypassPermissions'  // 绕过所有权限
+  | 'auto'         // 自动允许
+  | 'dontAsk'      // 不询问
+
+// 权限结果
+type PermissionResult =
+  | { allowed: true }
+  | { allowed: false; reason: string }
+```
+
+#### 工具进度类型 (`types/tools.ts`)
+```typescript
+type ToolProgressData =
+  | BashProgress
+  | AgentToolProgress
+  | MCPProgress
+  | REPLToolProgress
+  | SkillToolProgress
+  | TaskOutputProgress
+  | WebSearchProgress
+```
+
+#### 消息类型 (`types/message.ts`)
+```typescript
+type Message =
+  | UserMessage
+  | AssistantMessage
+  | SystemMessage
+  | ProgressMessage
+  | AttachmentMessage
+  | SystemLocalCommandMessage
+```
+
+## 状态管理
+
+```mermaid
+flowchart TD
+    A[state/] --> B[AppState.tsx<br/>应用状态]
+    A --> C[AppStateStore.ts<br/>状态存储]
+    A --> D[store.ts<br/>Store 定义]
+    A --> E[onChangeAppState.ts<br/>状态变更监听]
+    A --> F[selectors.ts<br/>状态选择器]
+    A --> G[teammateViewHelpers.ts<br/>队友视图辅助]
+
+    B --> H[全局应用状态]
+    H --> I[当前会话]
+    H --> J[MCP 连接]
+    H --> K[工具列表]
+    H --> L[消息历史]
+    H --> M[设置状态]
+    H --> N[代理状态]
+    H --> O[权限上下文]
+```
+
+### AppState 核心状态
+
+```mermaid
+classDiagram
+    class AppState {
+        +Session currentSession
+        +MCPState mcp
+        +ToolsState tools
+        +MessagesState messages
+        +SettingsState settings
+        +AgentState agents
+        +PermissionContext permissions
+        +BridgeState bridge
+        +UIState ui
+    }
+
+    class Session {
+        +string id
+        +string model
+        +Message[] messages
+        +number totalCost
+        +number totalTokens
+    }
+
+    class MCPState {
+        +MCPServerConnection[] connections
+        +Tool[] tools
+    }
+
+    class AgentState {
+        +AgentInfo[] activeAgents
+        +TeamInfo[] teams
+        +TaskInfo[] tasks
+    }
+
+    AppState --> Session
+    AppState --> MCPState
+    AppState --> AgentState
+```
+
+## 工具函数 (utils/)
+
+```mermaid
+graph TB
+    subgraph 核心工具
+        PERM_UTILS[permissions/<br/>权限工具函数]
+        FILE_CACHE[fileStateCache.ts<br/>文件状态缓存]
+        ENV[envUtils.ts<br/>环境工具]
+        SYSTEM[systemPromptType.ts<br/>系统提示类型]
+    end
+
+    subgraph 文件操作
+        FILE_HISTORY[fileHistory.ts<br/>文件历史]
+        FILE_STATE[fileStateCache.ts<br/>文件状态缓存]
+    end
+
+    subgraph 代理工具
+        AGENT_SWARM[agentSwarmsEnabled.ts<br/>代理集群开关]
+        WORKTREE[worktreeModeEnabled.ts<br/>Worktree 模式开关]
+        TOOL_SEARCH[toolSearch.ts<br/>工具搜索]
+        TASKS[tasks.ts<br/>任务工具]
+    end
+
+    subgraph Shell 工具
+        SHELL[shell/<br/>Shell 相关工具]
+    end
+
+    subgraph 其他工具
+        THEME[theme.ts<br/>主题管理]
+        THINK[thinking.ts<br/>思考模式]
+        TOKEN[tokenEstimation<br/>Token 估算]
+        COMMIT[commitAttribution.ts<br/>提交归因]
+        TOOL_RESULT[toolResultStorage.ts<br/>工具结果存储]
+        DENIAL[denialTracking.ts<br/>拒绝追踪]
+        EMBEDDED[embeddedTools.ts<br/>内嵌工具]
+    end
+```
+
+## Schema 验证体系
+
+使用 Zod v4 进行配置验证。
+
+```mermaid
+flowchart TD
+    A[schemas/<br/>Zod Schema 定义] --> B[配置验证]
+    B --> C[settings.json<br/>设置文件]
+    B --> D[CLAUDE.md<br/>项目指令]
+    B --> E[plugins/<br/>插件配置]
+    B --> F[keybindings<br/>快捷键配置]
+```
+
+## 上下文管理
+
+```mermaid
+flowchart TD
+    A[context.ts] --> B[系统上下文收集]
+    A --> C[用户上下文收集]
+
+    B --> D[操作系统信息]
+    B --> E[Shell 环境]
+    B --> F[工作目录信息]
+    B --> G[Git 状态]
+
+    C --> H[CLAUDE.md 指令]
+    C --> I[项目文件结构]
+    C --> J[对话历史]
+    C --> K[工具结果]
+
+    subgraph context/ 子模块
+        L[notifications.ts<br/>通知]
+        M[其他上下文模块]
+    end
+```
+
+## 任务管理
+
+```mermaid
+flowchart TD
+    A[tasks.ts] --> B[Task.ts<br/>任务类型定义]
+    A --> C[tasks/<br/>任务实现]
+
+    D[TaskCreateTool] --> E[创建任务]
+    F[TaskUpdateTool] --> G[更新任务状态]
+    H[TaskGetTool] --> I[获取任务详情]
+    J[TaskListTool] --> K[列出所有任务]
+    L[TaskOutputTool] --> M[获取后台任务输出]
+    N[TaskStopTool] --> O[停止任务]
+
+    E --> P[状态: pending]
+    P --> Q[状态: in_progress]
+    Q --> R[状态: completed]
+    Q --> S[状态: deleted]
+
+    subgraph 任务依赖
+        T[addBlocks<br/>设置阻塞关系]
+        U[addBlockedBy<br/>设置被阻塞关系]
+    end
+```
+
+## 成本追踪
+
+```mermaid
+flowchart TD
+    A[cost-tracker.ts] --> B[Token 计数]
+    A --> C[成本估算]
+    A --> D[阈值监控]
+
+    B --> E[输入 Token]
+    B --> F[输出 Token]
+    B --> G[缓存读取 Token]
+    B --> H[缓存写入 Token]
+
+    D --> I[成本阈值提醒]
+    D --> J[用量限制检查]
+
+    K[costHook.ts] --> L[成本 Hook<br/>每次查询后更新]
+```
+
+## 历史记录管理
+
+```mermaid
+flowchart TD
+    A[history.ts] --> B[会话历史存储]
+    A --> C[消息历史]
+    A --> D[命令历史]
+
+    B --> E[会话恢复<br/>/resume]
+    C --> F[上下文压缩<br/>/compact]
+    D --> G[命令补全<br/>useArrowKeyHistory]
+```
+
+## 配置迁移
+
+```mermaid
+flowchart LR
+    A[migrations/] --> B[配置版本检测]
+    B --> C{版本匹配?}
+    C -->|需要迁移| D[执行迁移脚本]
+    C -->|已是最新| E[跳过]
+    D --> F[更新配置格式]
+```
+
+## Bash 解析器 (utils/bash/)
+
+Claude Code 实现了一个完整的 Bash 语法解析器，用于分析和理解 Shell 命令：
+
+```mermaid
+flowchart TD
+    A[utils/bash/<br/>Bash 解析系统] --> B[parser.ts<br/>语法解析器]
+    A --> C[ast.ts<br/>抽象语法树]
+    A --> D[commands.ts<br/>命令解析]
+    A --> E[shellQuoting.ts<br/>Shell 引用处理]
+
+    B --> F[管道链解析<br/>识别管道操作]
+    B --> G[重定向解析<br/>识别重定向操作]
+    B --> H[变量展开<br/>识别环境变量]
+    B --> I[子 Shell 解析<br/>识别嵌套命令]
+
+    subgraph 用途
+        J[BashTool 命令语义分析<br/>commandSemantics.ts]
+        K[破坏性命令检测<br/>destructiveCommandWarning.ts]
+        L[只读验证<br/>readOnlyValidation.ts]
+        L2[sed 命令验证<br/>sedValidation.ts]
+    end
+```
+
+## 内存目录系统 (memdir/)
+
+```mermaid
+flowchart TD
+    A[memdir/<br/>持久化内存目录] --> B[memdir.ts<br/>内存目录管理]
+    A --> C[memoryTypes.ts<br/>记忆类型定义]
+    A --> D[memoryScan.ts<br/>记忆扫描]
+    A --> E[paths.ts<br/>路径管理]
+
+    B --> F[自动记忆<br/>auto memory]
+    B --> G[团队记忆<br/>team memory]
+
+    subgraph 记忆存储结构
+        H[MEMORY.md<br/>索引文件<br/>~150字/行]
+        I[*.md<br/>记忆文件<br/>frontmatter 格式]
+    end
+
+    F --> H
+    G --> H
+    H --> I
+```
+
+## 任务类型体系
+
+```mermaid
+classDiagram
+    class TaskBase {
+        +string id
+        +string subject
+        +string description
+        +TaskStatus status
+    }
+
+    class LocalShellTask {
+        +后台 Shell 执行
+    }
+
+    class LocalAgentTask {
+        +本地代理任务
+    }
+
+    class RemoteAgentTask {
+        +远程代理任务
+    }
+
+    class DreamTask {
+        +AI 规划任务
+    }
+
+    class LocalWorkflowTask {
+        +工作流脚本任务
+    }
+
+    class MonitorMcpTask {
+        +MCP 监控任务
+    }
+
+    TaskBase <|-- LocalShellTask
+    TaskBase <|-- LocalAgentTask
+    TaskBase <|-- RemoteAgentTask
+    TaskBase <|-- DreamTask
+    TaskBase <|-- LocalWorkflowTask
+    TaskBase <|-- MonitorMcpTask
+```
+```

docs/ui-components.md

@@ -0,0 +1,310 @@
+# UI 组件与前端分析
+
+## UI 架构
+
+Claude Code 使用 React + Ink 构建 Terminal UI，组件层次分明。
+
+```mermaid
+graph TB
+    subgraph 入口层
+        Main[main.tsx<br/>CLI 入口]
+        Ink[ink.ts<br/>Ink 渲染器包装]
+        App[App.tsx<br/>根组件]
+    end
+
+    subgraph 全屏界面
+        Screens[screens/<br/>Doctor, REPL, Resume]
+    end
+
+    subgraph 布局组件
+        Fullscreen[FullscreenLayout.tsx]
+        StatusLine[StatusLine.tsx<br/>状态栏]
+        TextInput[TextInput.tsx<br/>文本输入]
+        VimInput[VimTextInput.tsx<br/>Vim 输入]
+    end
+
+    subgraph 消息组件
+        Messages[Messages.tsx<br/>消息列表]
+        MessageRow[MessageRow.tsx<br/>消息行]
+        Message[Message.tsx<br/>单条消息]
+        MessageResp[MessageResponse.tsx<br/>响应消息]
+        VirtualList[VirtualMessageList.tsx<br/>虚拟滚动列表]
+    end
+
+    subgraph 工具组件
+        ToolLoader[ToolUseLoader.tsx<br/>工具加载器]
+        FileEditDiff[FileEditToolDiff.tsx<br/>编辑差异]
+        BashProgress[BashModeProgress.tsx<br/>Bash 进度]
+        NotebookReject[NotebookEditToolUseRejectedMessage.tsx]
+    end
+
+    subgraph 对话框组件
+        TrustDialog[TrustDialog/<br/>信任对话框]
+        MCPDialog[MCPServerApprovalDialog.tsx<br/>MCP 审批]
+        ExportDialog[ExportDialog.tsx<br/>导出对话框]
+        AutoMode[AutoModeOptInDialog.tsx<br/>自动模式确认]
+        CostDialog[CostThresholdDialog.tsx<br/>成本阈值]
+        BridgeDialog[BridgeDialog.tsx<br/>桥接对话框]
+    end
+
+    subgraph 输入组件
+        PromptInput[PromptInput/<br/>提示输入]
+        BaseInput[BaseTextInput.tsx<br/>基础文本输入]
+        SearchBox[SearchBox.tsx<br/>搜索框]
+    end
+
+    Main --> Ink --> App
+    App --> Screens
+    App --> Fullscreen
+    App --> StatusLine
+    App --> TextInput
+    App --> Messages
+    Messages --> VirtualList --> MessageRow --> Message
+    App --> ToolLoader
+    App --> PromptInput
+```
+
+## 组件分类
+
+### 核心布局组件
+| 组件 | 文件 | 功能 |
+|------|------|------|
+| App | `App.tsx` | 应用根组件 |
+| FullscreenLayout | `FullscreenLayout.tsx` | 全屏布局 |
+| StatusLine | `StatusLine.tsx` | 底部状态栏 |
+| TextInput | `TextInput.tsx` | 主输入框 |
+| VimTextInput | `VimTextInput.tsx` | Vim 模式输入框 |
+| PromptInput | `PromptInput/` | 提示输入组件 |
+| VirtualMessageList | `VirtualMessageList.tsx` | 虚拟滚动消息列表 |
+
+### 消息展示组件
+| 组件 | 文件 | 功能 |
+|------|------|------|
+| Messages | `Messages.tsx` | 消息容器 |
+| MessageRow | `MessageRow.tsx` | 消息行 |
+| Message | `Message.tsx` | 单条消息 |
+| MessageResponse | `MessageResponse.tsx` | 响应消息 |
+| MessageModel | `MessageModel.tsx` | 模型信息 |
+| MessageTimestamp | `MessageTimestamp.tsx` | 时间戳 |
+| CompactSummary | `CompactSummary.tsx` | 压缩摘要 |
+| Markdown | `Markdown.tsx` | Markdown 渲染 |
+
+### 工具相关组件
+| 组件 | 文件 | 功能 |
+|------|------|------|
+| ToolUseLoader | `ToolUseLoader.tsx` | 工具使用加载动画 |
+| BashModeProgress | `BashModeProgress.tsx` | Bash 命令进度 |
+| FileEditToolDiff | `FileEditToolDiff.tsx` | 文件编辑差异展示 |
+| FileEditToolUpdatedMessage | `FileEditToolUpdatedMessage.tsx` | 编辑更新消息 |
+| StructuredDiff | `StructuredDiff.tsx` | 结构化差异展示 |
+| StructuredDiffList | `StructuredDiffList.tsx` | 差异列表 |
+
+### 对话框组件
+| 组件 | 功能 |
+|------|------|
+| TrustDialog/ | 信任确认对话框 |
+| MCPServerApprovalDialog | MCP 服务器审批 |
+| MCPServerMultiselectDialog | MCP 多选对话框 |
+| ExportDialog | 导出对话框 |
+| AutoModeOptInDialog | 自动模式选择 |
+| AutoUpdater(AutoUpdaterWrapper) | 自动更新 |
+| CostThresholdDialog | 成本阈值确认 |
+| BridgeDialog | IDE 桥接对话框 |
+| IdleReturnDialog | 空闲返回对话框 |
+| BypassPermissionsModeDialog | 权限绕过确认 |
+| WorktreeExitDialog | Worktree 退出对话框 |
+| GlobalSearchDialog | 全局搜索 |
+| HistorySearchDialog | 历史搜索 |
+| QuickOpenDialog | 快速打开 |
+
+### 导航和信息组件
+| 组件 | 功能 |
+|------|------|
+| Stats | `Stats.tsx` 统计信息 |
+| Spinner | `Spinner.tsx` 加载动画 |
+| EffortIndicator | `EffortIndicator.ts` 思考力度指示 |
+| ModelPicker | `ModelPicker.tsx` 模型选择器 |
+| ThemePicker | `ThemePicker.tsx` 主题选择器 |
+| LanguagePicker | `LanguagePicker.tsx` 语言选择器 |
+| OutputStylePicker | `OutputStylePicker.tsx` 输出样式选择器 |
+| ThinkingToggle | `ThinkingToggle.tsx` 思考模式切换 |
+| FastIcon | `FastIcon.tsx` 快速模式图标 |
+| ContextVisualization | `ContextVisualization.tsx` 上下文可视化 |
+
+### 团队和代理组件
+| 组件 | 功能 |
+|------|------|
+| CoordinatorAgentStatus | 协调器代理状态 |
+| AgentProgressLine | 代理进度行 |
+| TeammateViewHeader | 队友视图头部 |
+| TaskListV2 | 任务列表 V2 |
+| PrBadge | PR 徽章 |
+
+### IDE 集成组件
+| 组件 | 功能 |
+|------|------|
+| IdeStatusIndicator | IDE 状态指示器 |
+| IdeAutoConnectDialog | IDE 自动连接 |
+| IdeOnboardingDialog | IDE 新手引导 |
+| ShowInIDEPrompt | 在 IDE 中显示提示 |
+| FilePathLink | 文件路径链接 |
+| LogSelector | 日志选择器 |
+
+## Vim 模式
+
+```mermaid
+flowchart TD
+    A[vim/] --> B[motions.ts<br/>移动操作]
+    A --> C[operators.ts<br/>操作符]
+    A --> D[textObjects.ts<br/>文本对象]
+    A --> E[transitions.ts<br/>状态转换]
+    A --> F[types.ts<br/>类型定义]
+
+    G[VimTextInput.tsx] --> A
+    H[useVimInput.ts] --> A
+
+    I[vim 命令<br/>/commands/vim] --> J[切换 Vim 模式]
+```
+
+## 快捷键系统
+
+```mermaid
+flowchart TD
+    A[keybindings/] --> B[defaultBindings.ts<br/>默认绑定]
+    A --> C[parser.ts<br/>快捷键解析]
+    A --> D[resolver.ts<br/>快捷键解析器]
+    A --> E[match.ts<br/>快捷键匹配]
+    A --> F[schema.ts<br/>Schema 定义]
+    A --> G[template.ts<br/>模板]
+    A --> H[validate.ts<br/>验证]
+    A --> I[reservedShortcuts.ts<br/>保留快捷键]
+    A --> J[shortcutFormat.ts<br/>格式化]
+    A --> K[loadUserBindings.ts<br/>用户自定义]
+
+    L[KeybindingContext.tsx] --> M[快捷键上下文]
+    N[KeybindingProviderSetup.tsx] --> M
+    O[useKeybinding.ts] --> P[使用快捷键]
+    Q[useShortcutDisplay.ts] --> R[快捷键显示]
+```
+
+## React Hooks
+
+项目包含约 70 个自定义 React Hooks：
+
+### 核心 Hooks
+| Hook | 功能 |
+|------|------|
+| `useCanUseTool` | 工具权限检查 |
+| `useMergedTools` | 合并内置和 MCP 工具 |
+| `useMergedCommands` | 合并命令列表 |
+| `useMergedClients` | 合并客户端 |
+| `useMainLoopModel` | 主循环模型管理 |
+| `useGlobalKeybindings` | 全局快捷键 |
+| `useCommandKeybindings` | 命令快捷键 |
+| `useTextInput` | 文本输入管理 |
+
+### 状态 Hooks
+| Hook | 功能 |
+|------|------|
+| `useDynamicConfig` | 动态配置 |
+| `useSettings` | 设置管理 |
+| `useSettingsChange` | 设置变更监听 |
+| `useTasksV2` | 任务管理 V2 |
+| `useTaskListWatcher` | 任务列表监听 |
+| `useMemoryUsage` | 内存使用 |
+| `useScheduledTasks` | 定时任务 |
+
+### IDE 集成 Hooks
+| Hook | 功能 |
+|------|------|
+| `useIDEIntegration` | IDE 集成 |
+| `useIdeSelection` | IDE 选择 |
+| `useIdeAtMentioned` | IDE @ 提及 |
+| `useIdeConnectionStatus` | IDE 连接状态 |
+| `useIdeLogging` | IDE 日志 |
+
+### 会话 Hooks
+| Hook | 功能 |
+|------|------|
+| `useReplBridge` | REPL Bridge |
+| `useRemoteSession` | 远程会话 |
+| `useSSHSession` | SSH 会话 |
+| `useSessionBackgrounding` | 会话后台化 |
+| `useBackgroundTaskNavigation` | 后台任务导航 |
+
+### 代理 Hooks
+| Hook | 功能 |
+|------|------|
+| `useSwarmInitialization` | 集群初始化 |
+| `useSwarmPermissionPoller` | 集群权限轮询 |
+| `useTeammateViewAutoExit` | 队友视图自动退出 |
+
+### 其他 Hooks
+| Hook | 功能 |
+|------|------|
+| `useVoiceIntegration` / `useVoice` | 语音集成 |
+| `useClipboardImageHint` | 剪贴板图片提示 |
+| `usePasteHandler` | 粘贴处理 |
+| `useTypeahead` | 自动补全 |
+| `useHistorySearch` | 历史搜索 |
+| `useDiffData` | 差异数据 |
+| `useDiffInIDE` | IDE 差异显示 |
+| `useVirtualScroll` | 虚拟滚动 |
+| `useTerminalSize` | 终端尺寸 |
+| `useCommandQueue` | 命令队列 |
+
+## 设计系统 (design-system/)
+
+内置组件库提供一致的 UI 基础：
+
+| 组件 | 功能 |
+|------|------|
+| ThemedBox / ThemedText | 主题感知的容器/文本 |
+| Dialog | 对话框组件 |
+| Tabs | 标签页组件 |
+| Button | 按钮组件 |
+| ProgressBar | 进度条 |
+| FuzzyPicker | 模糊选择器 |
+| CheckboxInput | 复选框输入 |
+
+### 布局系统
+
+使用 **Yoga Layout**（Flexbox 引擎）进行终端布局计算，支持：
+- Flexbox 弹性布局
+- 响应式终端尺寸适配
+- 基于 `useTerminalSize` 的动态调整
+
+### 主题系统
+
+```mermaid
+flowchart TD
+    A[ThemeProvider] --> B[themeSetting<br/>用户设置]
+    A --> C[systemTheme<br/>系统检测]
+    A --> D[currentTheme<br/>实际渲染主题]
+
+    B --> E[light / dark / auto]
+    C --> F[终端主题监听<br/>自动检测变化]
+    D --> G[动态切换<br/>实时预览]
+```
+
+## Buddy 伙伴精灵 (buddy/)
+
+终端伙伴精灵系统，提供视觉陪伴和交互反馈：
+
+```mermaid
+flowchart TD
+    A[CompanionSprite<br/>主精灵组件] --> B[动画系统]
+    A --> C[对话气泡]
+    A --> D[交互功能]
+
+    B --> E[idle<br/>空闲动画]
+    B --> F[fidget<br/>活动动画]
+    B --> G[blink<br/>眨眼动画]
+    B --> H[15帧循环序列]
+
+    C --> I[提示信息气泡<br/>~10秒显示]
+    C --> J[淡出效果<br/>最后3秒渐暗]
+
+    D --> K[pet<br/>抚摸交互]
+    D --> L[burst<br/>Hearts 爆发动画<br/>~2.5秒]
+```