chore: initialize recovered claude workspace

docs/Claude_Code_Source_Analysis.md

@@ -0,0 +1,501 @@
+# Claude Code v2.1.88 源码分析报告
+
+> 分析日期：2026-03-31
+> 源码版本：anthropic-ai-claude-code-2.1.88
+> 总文件数：1,884 个源文件（.ts/.tsx）
+> 总代码行数：约 512,664 行
+
+---
+
+## 一、项目概览
+
+Claude Code 是 Anthropic 官方的 CLI 交互式编程助手。它基于 **Bun 运行时** 构建，使用 **React + Ink** 渲染终端 UI，通过 Anthropic API 与 Claude 模型交互，为用户提供代码编写、调试、文件操作等软件工程任务支持。
+
+### 技术栈
+
+| 类别 | 技术 |
+|------|------|
+| 运行时 | Bun |
+| 语言 | TypeScript / TSX |
+| CLI 框架 | Commander.js (`@commander-js/extra-typings`) |
+| 终端 UI | React + Ink（自定义 fork） |
+| AI SDK | `@anthropic-ai/sdk` (Beta Messages API) |
+| 协议 | MCP (Model Context Protocol) |
+| 构建 | Bun bundler（`bun:bundle` feature flags） |
+
+---
+
+## 二、整体架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  entrypoints/cli.tsx                 │  ← 入口
+├─────────────────────────────────────────────────────┤
+│                     main.tsx                         │  ← CLI 参数解析 + 初始化
+├─────────────────────────────────────────────────────┤
+│                  screens/REPL.tsx                    │  ← 主交互界面（React 组件）
+├──────────┬──────────┬───────────┬───────────────────┤
+│ query.ts │ tools.ts │commands.ts│  QueryEngine.ts   │  ← 核心调度层
+├──────────┴──────────┴───────────┴───────────────────┤
+│  services/api/claude.ts  │  services/mcp/client.ts  │  ← API 通信层
+├──────────────────────────┴──────────────────────────┤
+│         tools/  │  skills/  │  hooks/  │  tasks/     │  ← 功能实现层
+├─────────────────────────────────────────────────────┤
+│    utils/  │  state/  │  constants/  │  types/       │  ← 基础设施层
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 三、核心模块详解
+
+### 3.1 入口与启动流程
+
+**文件**: `src/entrypoints/cli.tsx`
+
+启动经过精心优化的多阶段引导：
+
+1. **快速路径（Fast Path）**: `--version` 直接输出版本号，零模块加载
+2. **特殊模式检查**: `--dump-system-prompt`, `--claude-in-chrome-mcp`, `--chrome-native-host` 等
+3. **主路径**: 动态导入 `main.tsx`，进入完整 CLI 初始化
+
+**文件**: `src/main.tsx`（4,683 行，最核心文件之一）
+
+主函数负责：
+- 并行预取：MDM 配置、Keychain 凭证、OAuth、GrowthBook 特性开关
+- Commander.js 命令行参数解析
+- 初始化分析（analytics）、策略限制（policy limits）、远程托管设置
+- 加载 MCP 服务器、工具列表、技能系统、插件系统
+- 启动 React/Ink 渲染 → `REPL` 组件
+
+### 3.2 REPL 主界面
+
+**文件**: `src/screens/REPL.tsx`（5,005 行）
+
+核心交互组件，包含：
+- 消息列表渲染（虚拟滚动）
+- 用户输入处理（含 Vim 模式）
+- 权限请求对话框
+- 成本追踪与显示
+- Agent/Teammate 管理
+- 会话持久化与恢复
+
+### 3.3 查询引擎（Query Loop）
+
+**文件**: `src/query.ts` — 单次对话轮次的核心循环
+**文件**: `src/QueryEngine.ts` — 高级查询引擎（SDK/非交互模式）
+
+对话流程：
+```
+用户输入 → System Prompt 构建 → API 调用(streaming) → 解析响应
+    ↓
+  tool_use → 权限检查 → 工具执行 → 结果返回 → 继续 API 调用
+    ↓
+  end_turn → 展示结果给用户
+```
+
+关键机制：
+- **Auto Compact**: 上下文接近限制时自动压缩对话历史
+- **Reactive Compact**: 更智能的上下文折叠（feature flag 控制）
+- **Token Budget**: 工具结果的 token 预算管理
+- **Fingerprint**: 消息去重与缓存优化
+
+### 3.4 API 通信层
+
+**文件**: `src/services/api/claude.ts`（3,419 行）
+
+- 使用 Anthropic SDK 的 **Beta Messages API**（支持 streaming）
+- 支持多 provider：Anthropic 直连、AWS Bedrock、GCP Vertex
+- 处理 Betas 特性（extended thinking、tool use 等）
+- 请求指纹计算（用于 prompt cache）
+- 重试与错误处理策略
+
+---
+
+## 四、工具系统（Tools）
+
+### 4.1 工具接口
+
+**文件**: `src/Tool.ts`
+
+核心类型 `ToolUseContext` 定义了工具执行的完整上下文，包括：
+- 可用工具列表、命令、MCP 客户端
+- `AbortController` 中断控制
+- `AppState` 读写
+- 文件状态缓存、权限上下文
+- Agent/子代理相关状态
+
+### 4.2 工具注册
+
+**文件**: `src/tools.ts`
+
+所有工具在此文件中集中注册。支持条件加载（通过 `bun:bundle` feature flags）：
+
+| 工具 | 功能 |
+|------|------|
+| **BashTool** | 执行 shell 命令 |
+| **FileReadTool** | 读取文件 |
+| **FileEditTool** | 编辑文件（精确替换） |
+| **FileWriteTool** | 写入文件 |
+| **GlobTool** | 文件模式匹配搜索 |
+| **GrepTool** | 内容正则搜索（基于 ripgrep） |
+| **WebFetchTool** | 抓取网页内容 |
+| **WebSearchTool** | 网页搜索 |
+| **AgentTool** | 启动子代理 |
+| **SendMessageTool** | 向子代理发送消息 |
+| **NotebookEditTool** | 编辑 Jupyter Notebook |
+| **AskUserQuestionTool** | 向用户提问 |
+| **EnterPlanModeTool** | 进入计划模式 |
+| **ExitPlanModeTool** | 退出计划模式 |
+| **EnterWorktreeTool** | 创建 Git Worktree |
+| **ExitWorktreeTool** | 退出 Git Worktree |
+| **TaskCreateTool** | 创建任务 |
+| **TaskUpdateTool** | 更新任务 |
+| **TaskGetTool** | 获取任务详情 |
+| **TaskListTool** | 列出任务 |
+| **TaskOutputTool** | 获取任务输出 |
+| **TaskStopTool** | 停止任务 |
+| **SkillTool** | 执行技能 |
+| **TodoWriteTool** | 写入待办事项 |
+| **LSPTool** | Language Server Protocol 交互 |
+| **MCPTool** | 调用 MCP 工具 |
+| **ToolSearchTool** | 搜索可用工具 |
+| **ConfigTool** | 配置管理 |
+| **BriefTool** | 简洁模式 |
+| **ScheduleCronTool** | 定时任务（CronCreate/Delete/List） |
+| **ListMcpResourcesTool** | 列出 MCP 资源 |
+| **ReadMcpResourceTool** | 读取 MCP 资源 |
+
+**内部/实验性工具**（feature flag 控制）：
+- `REPLTool` — 仅内部用户
+- `SleepTool` — 主动等待
+- `RemoteTriggerTool` — 远程触发
+- `MonitorTool` — 监控工具
+- `SendUserFileTool` — 发送文件给用户（KAIROS）
+- `PushNotificationTool` — 推送通知
+- `SubscribePRTool` — PR 订阅
+- `TeamCreateTool` / `TeamDeleteTool` — 团队/多代理管理
+- `TungstenTool` — 内部工具
+
+### 4.3 Bash 工具安全系统
+
+**文件**: `src/tools/BashTool/bashSecurity.ts`（2,592 行）
+**文件**: `src/tools/BashTool/bashPermissions.ts`（2,621 行）
+
+Bash 工具有最复杂的安全系统：
+- 命令白名单/黑名单
+- 破坏性命令检测（rm -rf, git push --force 等）
+- 沙箱模式
+- Bash AST 解析器（`bashParser.ts` 4,436 行）用于静态分析命令安全性
+
+---
+
+## 五、权限系统
+
+### 5.1 权限模式
+
+**文件**: `src/types/permissions.ts`
+
+三种权限模式：
+- **`default`**: 默认模式，危险操作需要用户确认
+- **`plan`**: 计划模式，只读操作
+- **`bypass`**: 跳过权限检查（需用户明确启用）
+
+### 5.2 权限规则
+
+```typescript
+type ToolPermissionContext = {
+  mode: PermissionMode
+  alwaysAllowRules: ToolPermissionRulesBySource  // 始终允许
+  alwaysDenyRules: ToolPermissionRulesBySource   // 始终拒绝
+  alwaysAskRules: ToolPermissionRulesBySource    // 始终询问
+  isBypassPermissionsModeAvailable: boolean
+}
+```
+
+权限规则可在多个层级配置：
+- 全局设置 (`~/.claude/settings.json`)
+- 项目设置 (`.claude/settings.json`)
+- 命令行参数
+- 运行时用户选择
+
+---
+
+## 六、任务系统（Tasks）
+
+**文件**: `src/Task.ts`
+
+支持的任务类型：
+
+| 类型 | 说明 |
+|------|------|
+| `local_bash` | 本地 Shell 后台命令 |
+| `local_agent` | 本地子代理 |
+| `remote_agent` | 远程代理 |
+| `in_process_teammate` | 进程内协作者（多代理） |
+| `local_workflow` | 本地工作流 |
+| `monitor_mcp` | MCP 监控 |
+| `dream` | Dream 任务（后台推理） |
+
+任务状态机：`pending → running → completed/failed/killed`
+
+---
+
+## 七、MCP 集成
+
+**文件**: `src/services/mcp/client.ts`（3,348 行）
+**文件**: `src/services/mcp/auth.ts`（2,465 行）
+
+MCP (Model Context Protocol) 深度集成：
+- 支持 stdio 和 SSE 传输
+- OAuth 2.0 认证流程
+- 工具、资源、提示的完整支持
+- 官方 MCP 服务器注册表（`officialRegistry.ts`）
+- 连接生命周期管理（`MCPConnectionManager.tsx`）
+- 通道权限控制（`channelPermissions.ts`）
+
+---
+
+## 八、技能系统（Skills）
+
+**文件**: `src/skills/`
+
+技能是更高级的命令抽象：
+- `bundled/` — 内置技能
+- `loadSkillsDir.ts` — 从目录加载自定义技能
+- `mcpSkillBuilders.ts` — 从 MCP 构建技能
+- 支持用户通过 `/skill-name` 快捷调用
+
+---
+
+## 九、UI 系统
+
+### 9.1 Ink 终端渲染
+
+**文件**: `src/ink/`（96 个文件）
+
+自定义的 Ink (React for CLI) 框架：
+- `layout/` — 布局引擎（基于 Yoga layout）
+- `components/` — 基础 UI 组件
+- `hooks/` — React hooks（终端尺寸、焦点、搜索等）
+- `termio/` — 终端 I/O 和 DEC 控制序列
+- `events/` — 事件系统
+
+### 9.2 主要组件
+
+**文件**: `src/components/`（389 个文件）
+
+关键组件包括：
+- `PromptInput/` — 用户输入框（支持多行、Vim 模式）
+- `VirtualMessageList` — 虚拟滚动消息列表
+- `Spinner` — 加载动画
+- `permissions/` — 权限请求 UI
+- `mcp/` — MCP 相关 UI
+- `MessageSelector` — 消息选择器
+- `CostThresholdDialog` — 成本阈值对话框
+
+---
+
+## 十、命令系统
+
+**文件**: `src/commands/`（207 个文件）
+
+Slash 命令系统（用户通过 `/command` 触发）：
+
+| 分类 | 命令示例 |
+|------|---------|
+| **Git** | `/commit`, `/branch`, `/diff`, `/pr_comments`, `/review` |
+| **会话** | `/resume`, `/session`, `/compact`, `/clear`, `/exit` |
+| **配置** | `/config`, `/model`, `/theme`, `/permissions`, `/vim` |
+| **工具** | `/mcp`, `/plugin`, `/skills`, `/hooks` |
+| **调试** | `/doctor`, `/debug-tool-call`, `/cost`, `/stats`, `/perf-issue` |
+| **AI 模式** | `/plan`, `/fast`, `/effort`, `/brief`, `/thinkback` |
+| **协作** | `/agents`, `/tasks`, `/teleport`, `/remote-setup` |
+| **其他** | `/memory`, `/export`, `/help`, `/feedback`, `/version` |
+
+---
+
+## 十一、服务层
+
+**文件**: `src/services/`（130 个文件）
+
+| 服务 | 说明 |
+|------|------|
+| `api/` | Anthropic API 通信（claude.ts, bootstrap.ts, filesApi.ts） |
+| `mcp/` | MCP 协议客户端和服务器管理 |
+| `oauth/` | OAuth 2.0 认证 |
+| `analytics/` | 分析追踪（GrowthBook 特性开关） |
+| `compact/` | 对话压缩（autoCompact, reactiveCompact） |
+| `policyLimits/` | 策略限制管理 |
+| `remoteManagedSettings/` | 远程托管设置 |
+| `plugins/` | 插件加载与管理 |
+| `SessionMemory/` | 会话记忆 |
+| `tips/` | 使用提示 |
+| `lsp/` | LSP 服务 |
+| `tools/` | 工具相关服务 |
+| `extractMemories/` | 自动记忆提取 |
+| `voice/` | 语音交互 |
+
+---
+
+## 十二、状态管理
+
+**文件**: `src/state/`
+
+- `AppState.tsx` — 全局应用状态类型定义
+- `AppStateStore.ts` — 状态存储实现
+- `store.ts` — 状态存储工厂
+- `selectors.ts` — 状态选择器
+- `onChangeAppState.ts` — 状态变更监听
+
+状态包含：消息列表、任务状态、权限上下文、MCP 连接、成本追踪等。
+
+---
+
+## 十三、辅助系统
+
+### 13.1 记忆系统
+**文件**: `src/memdir/`（8 个文件）
+管理 `MEMORY.md` 和持久化记忆目录，跨会话保持上下文。
+
+### 13.2 Vim 模式
+**文件**: `src/vim/`（5 个文件）
+终端输入框支持 Vim 键绑定。
+
+### 13.3 语音交互
+**文件**: `src/services/voice.ts`, `voiceStreamSTT.ts`
+语音输入支持（STT）。
+
+### 13.4 代理群集（Agent Swarms）
+**文件**: `src/utils/swarm/`
+支持多代理协作：leader/worker 权限同步、team 管理、沙箱权限请求。
+
+### 13.5 插件系统
+**文件**: `src/services/plugins/`, `src/utils/plugins/`
+- `pluginLoader.ts`（3,302 行）— 插件加载器
+- `marketplaceManager.ts`（2,643 行）— 插件市场管理
+- 支持内置插件和第三方插件
+
+---
+
+## 十四、Feature Flags 系统
+
+通过 `bun:bundle` 的 `feature()` 函数实现编译时特性开关：
+
+| Flag | 功能 |
+|------|------|
+| `ABLATION_BASELINE` | A/B 测试基线 |
+| `DUMP_SYSTEM_PROMPT` | 导出系统提示 |
+| `PROACTIVE` | 主动模式 |
+| `KAIROS` | Assistant 模式 |
+| `AGENT_TRIGGERS` | 定时任务 |
+| `AGENT_TRIGGERS_REMOTE` | 远程触发 |
+| `MONITOR_TOOL` | 监控工具 |
+| `COORDINATOR_MODE` | 协调器模式 |
+| `REACTIVE_COMPACT` | 响应式压缩 |
+| `CONTEXT_COLLAPSE` | 上下文折叠 |
+| `KAIROS_GITHUB_WEBHOOKS` | GitHub Webhook |
+| `KAIROS_PUSH_NOTIFICATION` | 推送通知 |
+
+外部构建通过 DCE（Dead Code Elimination）移除内部功能。
+
+---
+
+## 十五、关键文件索引
+
+| 文件 | 行数 | 功能 |
+|------|------|------|
+| `cli/print.ts` | 5,594 | 非交互式输出/打印模式 |
+| `utils/messages.ts` | 5,512 | 消息创建与处理 |
+| `utils/sessionStorage.ts` | 5,105 | 会话持久化存储 |
+| `utils/hooks.ts` | 5,022 | Hooks 系统实现 |
+| `screens/REPL.tsx` | 5,005 | 主 REPL 界面 |
+| `main.tsx` | 4,683 | 主入口/初始化 |
+| `utils/bash/bashParser.ts` | 4,436 | Bash 命令解析器 |
+| `utils/attachments.ts` | 3,997 | 附件处理 |
+| `services/api/claude.ts` | 3,419 | API 通信 |
+| `services/mcp/client.ts` | 3,348 | MCP 客户端 |
+| `utils/plugins/pluginLoader.ts` | 3,302 | 插件加载器 |
+| `commands/insights.ts` | 3,200 | 洞察命令 |
+| `bridge/bridgeMain.ts` | 2,999 | Bridge 主进程 |
+| `utils/bash/ast.ts` | 2,679 | Bash AST |
+| `tools/BashTool/bashPermissions.ts` | 2,621 | Bash 权限 |
+| `tools/BashTool/bashSecurity.ts` | 2,592 | Bash 安全 |
+
+---
+
+## 十六、架构亮点
+
+### 1. 启动性能优化
+- 多阶段懒加载：快速路径零导入，主路径并行预取
+- `startupProfiler.ts` 追踪每个启动阶段耗时
+- MDM、Keychain、OAuth 凭证并行预取
+
+### 2. 安全设计
+- Bash 命令 AST 级静态分析
+- 多层权限控制（白名单、黑名单、始终询问）
+- 沙箱模式隔离
+- 破坏性操作自动检测与拦截
+
+### 3. 多代理架构
+- 子代理（AgentTool）支持并发执行
+- 团队协作（TeamCreate/TeamDelete）
+- 进程内协作者（InProcessTeammate）
+- 远程代理（RemoteAgent）
+- Leader/Worker 权限同步
+
+### 4. 上下文管理
+- Auto Compact 自动压缩历史
+- Reactive Compact 智能压缩
+- Context Collapse 上下文折叠
+- Token Budget 精细控制
+- 文件状态缓存 LRU
+
+### 5. 可扩展性
+- 插件系统 + 插件市场
+- MCP 协议集成
+- 自定义技能
+- Hooks 系统
+- Feature Flags 编译时裁剪
+
+---
+
+## 十七、数据流图
+
+```
+User Input
+    │
+    ▼
+┌─────────────┐     ┌──────────────┐
+│ PromptInput │────▶│  REPL.tsx    │
+└─────────────┘     └──────┬───────┘
+                           │
+                    ┌──────▼───────┐
+                    │  query.ts    │ ◄── System Prompt (constants/prompts.ts)
+                    │  (主循环)     │ ◄── Memory (memdir/)
+                    └──────┬───────┘ ◄── CLAUDE.md
+                           │
+                    ┌──────▼───────┐
+                    │ claude.ts    │ ── Anthropic Beta Messages API (streaming)
+                    │ (API 调用)    │
+                    └──────┬───────┘
+                           │
+              ┌────────────┼────────────┐
+              ▼            ▼            ▼
+         text_delta   tool_use    end_turn
+              │            │            │
+              ▼            ▼            ▼
+         渲染文本     ┌─────────┐   返回结果
+                     │权限检查  │
+                     └────┬────┘
+                          │
+                     ┌────▼────┐
+                     │工具执行  │ → BashTool / FileReadTool / AgentTool / ...
+                     └────┬────┘
+                          │
+                     tool_result → 继续 API 调用（循环）
+```
+
+---
+
+*报告生成完毕。源代码已还原至 `package/source/src/` 目录。*