From 9074aabe1c6de32327b61db42445a0fcdbbf9771 Mon Sep 17 00:00:00 2001 From: arno Date: Sun, 5 Apr 2026 09:33:11 +0800 Subject: [PATCH] Add project documentation Co-Authored-By: Claude Opus 4.6 --- docs/README.md | 15 ++ docs/architecture-overview.md | 187 ++++++++++++++ docs/command-system.md | 234 ++++++++++++++++++ docs/data-flow.md | 174 +++++++++++++ docs/file-statistics.md | 150 ++++++++++++ docs/services-and-infrastructure.md | 292 ++++++++++++++++++++++ docs/tool-system.md | 262 ++++++++++++++++++++ docs/types-utils-state.md | 363 ++++++++++++++++++++++++++++ docs/ui-components.md | 310 ++++++++++++++++++++++++ 9 files changed, 1987 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/architecture-overview.md create mode 100644 docs/command-system.md create mode 100644 docs/data-flow.md create mode 100644 docs/file-statistics.md create mode 100644 docs/services-and-infrastructure.md create mode 100644 docs/tool-system.md create mode 100644 docs/types-utils-state.md create mode 100644 docs/ui-components.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..a6eade8 --- /dev/null +++ b/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 图表（架构图、类图、流程图、时序图）。 \ No newline at end of file diff --git a/docs/architecture-overview.md b/docs/architecture-overview.md new file mode 100644 index 0000000..5a3f734 --- /dev/null +++ b/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 入口
main.tsx] + IDE[IDE 扩展
VS Code / JetBrains] + Desktop[桌面应用] + Mobile[移动应用] + end + + subgraph 命令层 + CMD[命令注册器
commands.ts] + CMD_IMPL[命令实现
commands/ ~82个] + end + + subgraph 工具层 + TOOL_REG[工具注册器
tools.ts] + TOOL_IMPL[工具实现
tools/ ~40个] + TOOL_TYPE[工具类型定义
Tool.ts] + end + + subgraph 核心引擎 + QE[查询引擎
QueryEngine.ts] + QS[查询管道
query.ts] + CTX[上下文管理
context.ts] + end + + subgraph 服务层 + API_SVC[API 服务
services/api/] + MCP_SVC[MCP 服务
services/mcp/] + AUTH_SVC[OAuth 认证
services/oauth/] + LSP_SVC[LSP 服务
services/lsp/] + ANALYTICS[分析/特性开关
services/analytics/] + end + + subgraph 基础设施 + BRIDGE[IDE 桥接
bridge/] + COORD[多代理协调
coordinator/] + PLUGINS[插件系统
plugins/] + SKILLS[技能系统
skills/] + PERM[权限系统
hooks/toolPermission/] + end + + subgraph UI 层 + COMP[UI 组件
components/ ~140个] + SCREENS[全屏界面
screens/] + VIM[Vim 模式
vim/] + KB[快捷键
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 开销。 diff --git a/docs/command-system.md b/docs/command-system.md new file mode 100644 index 0000000..48baae2 --- /dev/null +++ b/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
内置命令] + A --> C[skills/
技能目录] + A --> D[bundled
打包技能] + A --> E[plugin
插件命令] + A --> F[managed
托管命令] + A --> G[mcp
MCP 技能] + + B --> H[commands.ts
统一注册] + 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
用户技能] + B --> D[initBundledSkills
打包技能] + B --> E[插件加载器
插件命令] + + F{可用性检查} --> G[meetsAvailabilityRequirement] + G --> H[isCommandEnabled
功能标志/平台/环境] + G --> I[availability
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） | diff --git a/docs/data-flow.md b/docs/data-flow.md new file mode 100644 index 0000000..86f936c --- /dev/null +++ b/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 +``` diff --git a/docs/file-statistics.md b/docs/file-statistics.md new file mode 100644 index 0000000..ede4940 --- /dev/null +++ b/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 隔离 diff --git a/docs/services-and-infrastructure.md b/docs/services-and-infrastructure.md new file mode 100644 index 0000000..b302e95 --- /dev/null +++ b/docs/services-and-infrastructure.md @@ -0,0 +1,292 @@ +# 服务层与基础设施分析 + +## 服务层架构 + +```mermaid +graph TB + subgraph API 服务 + API_CLIENT[client.ts
Anthropic API 客户端] + API_CLAUDE[claude.ts
Claude API 封装] + API_BOOTSTRAP[bootstrap.ts
引导逻辑] + API_FILES[filesApi.ts
文件 API] + API_USAGE[usage.ts
使用量查询] + API_SESSION[sessionIngress.ts
会话入口] + API_ERRORS[errors.ts
错误处理] + API_RETRY[withRetry.ts
重试逻辑] + API_GROVE[grove.ts
Grove 集成] + end + + subgraph MCP 服务 + MCP_MGR[MCPConnectionManager.tsx
MCP 连接管理器] + MCP_AUTH[auth.ts
MCP 认证] + MCP_CONFIG[config.ts
MCP 配置] + MCP_TYPES[types.ts
MCP 类型定义] + MCP_REGISTRY[officialRegistry.ts
官方注册表] + MCP_VSCODE[vscodeSdkMcp.ts
VSCode SDK MCP] + MCP_SDK[SdkControlTransport.ts
SDK 控制传输] + MCP_NORMAL[normalization.ts
MCP 规范化] + end + + subgraph OAuth 认证 + OAUTH_FLOW[OAuth 2.0 流程] + OAUTH_XAA[xaa.ts / xaaIdpLogin.ts
XAA 认证] + OAUTH_PORT[oauthPort.ts
OAuth 端口] + end + + subgraph 分析服务 + ANALYTICS_GROWTH[GrowthBook 特性开关] + ANALYTICS_TELEMETRY[OpenTelemetry 遥测] + ANALYTICS_TRACKING[diagnosticTracking.ts
诊断追踪] + end + + subgraph 其他服务 + COMPACT[compact/
上下文压缩] + POLICY[policyLimits/
组织策略限制] + REMOTE_SETTINGS[remoteManagedSettings/
远程托管设置] + EXTRACT_MEM[extractMemories/
自动记忆提取] + TOKEN_EST[tokenEstimation.ts
Token 估算] + TEAM_MEM[teamMemorySync/
团队记忆同步] + SESSION_MEM[SessionMemory/
会话记忆] + LSP[lsp/
Language Server Protocol] + PLUGINS[plugins/
插件加载器] + VOICE[voice.ts / voiceStreamSTT.ts
语音输入/STT] + end +``` + +## Bridge 桥接系统 + +Bridge 是 IDE 扩展与 Claude Code CLI 之间的双向通信层，支持 VS Code 和 JetBrains。 + +```mermaid +sequenceDiagram + participant IDE as IDE 扩展
(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
AgentTool] + C --> F[Worker 2
AgentTool] + C --> G[Worker N
AgentTool] + + E --> H[SendMessage
消息传递] + F --> H + G --> H + H --> I[Coordinator
汇总结果] + + C --> J[TaskCreate
任务创建] + J --> K[TaskUpdate
任务更新] + K --> L[TaskList
任务列表] +``` + +## 插件系统 + +```mermaid +flowchart LR + A[builtinPlugins.ts
内置插件] --> C[插件加载器] + B[bundled/
捆绑插件] --> C + D[用户插件目录
.claude/plugins/] --> C + C --> E[插件注册] + E --> F[工具扩展] + E --> G[命令扩展] + E --> H[Hook 扩展] +``` + +## 技能系统 + +```mermaid +flowchart LR + A[bundled/
捆绑技能] --> C[技能加载器] + B[bundledSkills.ts
技能注册] --> C + D[loadSkillsDir.ts
用户技能目录] --> C + E[mcpSkillBuilders.ts
MCP 技能构建] --> C + C --> F[SkillTool
技能执行] +``` + +### 内置技能清单 + +| 技能 | 功能 | +|------|------| +| 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
IDE SDK 控制] + + A --> G[officialRegistry.ts
官方 MCP 服务器注册表] + A --> H[vscodeSdkMcp.ts
VS Code SDK 集成] + A --> I[normalization.ts
工具名规范化] + + A --> J[auth.ts
认证] + J --> K[OAuth 认证] + J --> L[API Key 认证] + J --> M[XAA 认证
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
LSP 管理器
单例模式] --> B[LSPServerManager
服务器管理] + B --> C[LSPServerInstance
单个服务器实例] + B --> D[config.ts
服务器配置] + + C --> E[TypeScript Server] + C --> F[Python Server] + C --> G[Go Server] + C --> H[其他语言服务器] + + A --> I[功能] + I --> J[代码诊断
被动反馈] + I --> K[跳转定义
hover 信息] + I --> L[代码补全] + I --> M[多项目并行连接] +``` + +## 查询引擎 (QueryEngine.ts) + +QueryEngine 是核心的 LLM API 调用引擎（约 46K 行），处理流式响应、工具调用循环、思考模式和 Token 计数。 + +```mermaid +flowchart TD + A[QueryEngine.ts
~46K 行] --> B[query.ts
查询管道
~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/
权限系统] --> B[PermissionMode] + B --> C[default
默认模式] + B --> D[plan
计划模式] + B --> E[bypassPermissions
绕过权限] + B --> F[auto
自动模式] + B --> G[dontAsk
不询问模式] + + 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` | 溢出测试工具 | diff --git a/docs/tool-system.md b/docs/tool-system.md new file mode 100644 index 0000000..eef1dda --- /dev/null +++ b/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
通用代理] + B --> D[Explore
代码探索] + B --> E[Plan
架构规划] + B --> F[claude-code-guide
使用指南] + + C --> G[可用工具: 全部] + D --> H[可用工具: 只读
Glob, Grep, Read, Agent] + E --> I[可用工具: 只读
同 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[路径验证
pathValidation.ts] + B --> D[只读验证
readOnlyValidation.ts] + B --> E[破坏性命令警告
destructiveCommandWarning.ts] + B --> F[沙盒检查
shouldUseSandbox.ts] + B --> G[sed 命令验证
sedValidation.ts] + + C --> H{在工作目录内?} + H -->|是| I[允许执行] + H -->|否| J[路径限制警告] + + E --> K{破坏性命令?} + K -->|rm, git reset --hard| L[额外确认] + K -->|其他| I + + F --> M{沙盒可用?} + M -->|是| N[沙盒执行] + M -->|否| I +``` diff --git a/docs/types-utils-state.md b/docs/types-utils-state.md new file mode 100644 index 0000000..561f05f --- /dev/null +++ b/docs/types-utils-state.md @@ -0,0 +1,363 @@ +# 类型系统、工具函数与状态管理分析 + +## 类型系统 + +### 类型定义目录结构 + +```mermaid +graph TB + subgraph types/ + CMD[command.ts
命令类型] + GEN[generated/
生成类型] + HOOKS[hooks.ts
Hook 类型] + IDS[ids.ts
ID 类型] + LOGS[logs.ts
日志类型] + PERM[permissions.ts
权限类型] + PLUGIN[plugin.ts
插件类型] + TEXT[textInputTypes.ts
文本输入类型] + end + + subgraph 核心类型定义 + TOOL_TYPE[Tool.ts
工具类型] + MSG[types/message.ts
消息类型] + TOOL_TYPES[types/tools.ts
工具进度类型] + end + + subgraph Schema 验证 + SCHEMAS[schemas/
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
应用状态] + A --> C[AppStateStore.ts
状态存储] + A --> D[store.ts
Store 定义] + A --> E[onChangeAppState.ts
状态变更监听] + A --> F[selectors.ts
状态选择器] + A --> G[teammateViewHelpers.ts
队友视图辅助] + + 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/
权限工具函数] + FILE_CACHE[fileStateCache.ts
文件状态缓存] + ENV[envUtils.ts
环境工具] + SYSTEM[systemPromptType.ts
系统提示类型] + end + + subgraph 文件操作 + FILE_HISTORY[fileHistory.ts
文件历史] + FILE_STATE[fileStateCache.ts
文件状态缓存] + end + + subgraph 代理工具 + AGENT_SWARM[agentSwarmsEnabled.ts
代理集群开关] + WORKTREE[worktreeModeEnabled.ts
Worktree 模式开关] + TOOL_SEARCH[toolSearch.ts
工具搜索] + TASKS[tasks.ts
任务工具] + end + + subgraph Shell 工具 + SHELL[shell/
Shell 相关工具] + end + + subgraph 其他工具 + THEME[theme.ts
主题管理] + THINK[thinking.ts
思考模式] + TOKEN[tokenEstimation
Token 估算] + COMMIT[commitAttribution.ts
提交归因] + TOOL_RESULT[toolResultStorage.ts
工具结果存储] + DENIAL[denialTracking.ts
拒绝追踪] + EMBEDDED[embeddedTools.ts
内嵌工具] + end +``` + +## Schema 验证体系 + +使用 Zod v4 进行配置验证。 + +```mermaid +flowchart TD + A[schemas/
Zod Schema 定义] --> B[配置验证] + B --> C[settings.json
设置文件] + B --> D[CLAUDE.md
项目指令] + B --> E[plugins/
插件配置] + B --> F[keybindings
快捷键配置] +``` + +## 上下文管理 + +```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
通知] + M[其他上下文模块] + end +``` + +## 任务管理 + +```mermaid +flowchart TD + A[tasks.ts] --> B[Task.ts
任务类型定义] + A --> C[tasks/
任务实现] + + 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
设置阻塞关系] + U[addBlockedBy
设置被阻塞关系] + 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
每次查询后更新] +``` + +## 历史记录管理 + +```mermaid +flowchart TD + A[history.ts] --> B[会话历史存储] + A --> C[消息历史] + A --> D[命令历史] + + B --> E[会话恢复
/resume] + C --> F[上下文压缩
/compact] + D --> G[命令补全
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/
Bash 解析系统] --> B[parser.ts
语法解析器] + A --> C[ast.ts
抽象语法树] + A --> D[commands.ts
命令解析] + A --> E[shellQuoting.ts
Shell 引用处理] + + B --> F[管道链解析
识别管道操作] + B --> G[重定向解析
识别重定向操作] + B --> H[变量展开
识别环境变量] + B --> I[子 Shell 解析
识别嵌套命令] + + subgraph 用途 + J[BashTool 命令语义分析
commandSemantics.ts] + K[破坏性命令检测
destructiveCommandWarning.ts] + L[只读验证
readOnlyValidation.ts] + L2[sed 命令验证
sedValidation.ts] + end +``` + +## 内存目录系统 (memdir/) + +```mermaid +flowchart TD + A[memdir/
持久化内存目录] --> B[memdir.ts
内存目录管理] + A --> C[memoryTypes.ts
记忆类型定义] + A --> D[memoryScan.ts
记忆扫描] + A --> E[paths.ts
路径管理] + + B --> F[自动记忆
auto memory] + B --> G[团队记忆
team memory] + + subgraph 记忆存储结构 + H[MEMORY.md
索引文件
~150字/行] + I[*.md
记忆文件
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 +``` +``` diff --git a/docs/ui-components.md b/docs/ui-components.md new file mode 100644 index 0000000..76e455b --- /dev/null +++ b/docs/ui-components.md @@ -0,0 +1,310 @@ +# UI 组件与前端分析 + +## UI 架构 + +Claude Code 使用 React + Ink 构建 Terminal UI，组件层次分明。 + +```mermaid +graph TB + subgraph 入口层 + Main[main.tsx
CLI 入口] + Ink[ink.ts
Ink 渲染器包装] + App[App.tsx
根组件] + end + + subgraph 全屏界面 + Screens[screens/
Doctor, REPL, Resume] + end + + subgraph 布局组件 + Fullscreen[FullscreenLayout.tsx] + StatusLine[StatusLine.tsx
状态栏] + TextInput[TextInput.tsx
文本输入] + VimInput[VimTextInput.tsx
Vim 输入] + end + + subgraph 消息组件 + Messages[Messages.tsx
消息列表] + MessageRow[MessageRow.tsx
消息行] + Message[Message.tsx
单条消息] + MessageResp[MessageResponse.tsx
响应消息] + VirtualList[VirtualMessageList.tsx
虚拟滚动列表] + end + + subgraph 工具组件 + ToolLoader[ToolUseLoader.tsx
工具加载器] + FileEditDiff[FileEditToolDiff.tsx
编辑差异] + BashProgress[BashModeProgress.tsx
Bash 进度] + NotebookReject[NotebookEditToolUseRejectedMessage.tsx] + end + + subgraph 对话框组件 + TrustDialog[TrustDialog/
信任对话框] + MCPDialog[MCPServerApprovalDialog.tsx
MCP 审批] + ExportDialog[ExportDialog.tsx
导出对话框] + AutoMode[AutoModeOptInDialog.tsx
自动模式确认] + CostDialog[CostThresholdDialog.tsx
成本阈值] + BridgeDialog[BridgeDialog.tsx
桥接对话框] + end + + subgraph 输入组件 + PromptInput[PromptInput/
提示输入] + BaseInput[BaseTextInput.tsx
基础文本输入] + SearchBox[SearchBox.tsx
搜索框] + 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
移动操作] + A --> C[operators.ts
操作符] + A --> D[textObjects.ts
文本对象] + A --> E[transitions.ts
状态转换] + A --> F[types.ts
类型定义] + + G[VimTextInput.tsx] --> A + H[useVimInput.ts] --> A + + I[vim 命令
/commands/vim] --> J[切换 Vim 模式] +``` + +## 快捷键系统 + +```mermaid +flowchart TD + A[keybindings/] --> B[defaultBindings.ts
默认绑定] + A --> C[parser.ts
快捷键解析] + A --> D[resolver.ts
快捷键解析器] + A --> E[match.ts
快捷键匹配] + A --> F[schema.ts
Schema 定义] + A --> G[template.ts
模板] + A --> H[validate.ts
验证] + A --> I[reservedShortcuts.ts
保留快捷键] + A --> J[shortcutFormat.ts
格式化] + A --> K[loadUserBindings.ts
用户自定义] + + 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
用户设置] + A --> C[systemTheme
系统检测] + A --> D[currentTheme
实际渲染主题] + + B --> E[light / dark / auto] + C --> F[终端主题监听
自动检测变化] + D --> G[动态切换
实时预览] +``` + +## Buddy 伙伴精灵 (buddy/) + +终端伙伴精灵系统，提供视觉陪伴和交互反馈： + +```mermaid +flowchart TD + A[CompanionSprite
主精灵组件] --> B[动画系统] + A --> C[对话气泡] + A --> D[交互功能] + + B --> E[idle
空闲动画] + B --> F[fidget
活动动画] + B --> G[blink
眨眼动画] + B --> H[15帧循环序列] + + C --> I[提示信息气泡
~10秒显示] + C --> J[淡出效果
最后3秒渐暗] + + D --> K[pet
抚摸交互] + D --> L[burst
Hearts 爆发动画
~2.5秒] +```