yovinchen/openclaude

Fork 0

Files

YoVinchen a10efa3b4b chore: initialize recovered claude workspace

2026-04-02 15:29:01 +08:00

17 KiB

Raw Permalink Blame History

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

启动经过精心优化的多阶段引导：

快速路径（Fast Path）: --version 直接输出版本号，零模块加载
特殊模式检查: --dump-system-prompt, --claude-in-chrome-mcp, --chrome-native-host 等
主路径: 动态导入 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 权限规则

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/ 目录。

17 KiB Raw Permalink Blame History Unescape Escape