Claude Code 源码分析 – (1)架构分析

版本: v2.1.88源码规模: 1,906 文件 / 515,029 行 TypeScript提取来源: @anthropic-ai/claude-code npm 包中的 cli.js.map source map

整体架构图

模块详解

入口层 (Entrypoints)

src/entrypoints/cli.tsx — CLI 主入口

Claude Code 的命令行入口点。负责快速路径处理（–version 等即时响应标志），初始化启动性能分析器，并通过动态 import 延迟加载较重的模块，保证 CLI 响应速度。最终渲染 main.tsx。

src/entrypoints/mcp.ts — MCP 服务器入口

将 Claude Code 自身作为 MCP（Model Context Protocol）服务器运行，通过 stdio 对外暴露工具能力，供其他 MCP 客户端调用。支持 Claude Code 工具集被外部系统调用。

src/entrypoints/sdk/ — Agent SDK 入口

作为 Anthropic Agent SDK 的运行时入口，支持以编程方式调用 Claude Code 的能力，用于构建自定义 AI Agent 应用。

Bootstrap 层

src/setup.ts — 启动编排

应用启动时的顺序初始化器。依次执行：检测工作目录、查找项目根目录、初始化 session 内存、备份终端状态，并在正式进入交互循环前确保环境就绪。

src/main.tsx — 应用根组件

React (Ink) 应用的主组件。负责全局初始化（遥测系统、keychain 预取、MDM 设置读取），设置 Ink 渲染环境，然后根据上下文启动 REPL 或执行特定命令。

src/bootstrap/ — 全局状态初始化

维护整个应用生命周期内的全局瞬态状态，包括 session ID、项目根目录路径、性能/成本追踪器、事件日志器等。是各模块共享运行时状态的中枢。

src/migrations/ — 版本迁移

存放随版本迭代执行的数据迁移脚本，升级用户配置、权限标志、模型偏好等本地持久化数据，确保跨版本升级时用户数据不丢失。

UI 层 (Ink / React TUI)

Claude Code 使用 Ink 在终端中渲染 React 组件，实现完整的 TUI（Terminal User Interface）。

src/screens/ — 顶级页面

应用的高层视图容器，管理不同功能模式之间的切换：

REPL.tsx：主对话界面，用户与 Claude 交互的核心页面
Doctor.tsx：诊断工具页面，检查环境配置和连接状态

其他辅助屏幕（设置、帮助、欢迎引导等）

src/components/ — UI 组件库

终端 UI 的原子和复合组件集合：

MessageRow：单条消息的渲染（用户/助手/工具调用）
ProgressBar：任务进度显示
DiffViewer：代码差异可视化
PromptInput：用户输入框（含历史、补全、Vim 模式）
Markdown.tsx：Markdown 语法渲染到终端
PermissionDialog：工具执行权限确认弹框
ThemePicker：主题选择界面
FeedbackSurvey：用户反馈收集
design-system：基础设计系统组件
messages：消息系统相关组件

src/ink/ & src/ink.ts — Ink TUI 引擎

对 Ink 库的封装和扩展，提供终端布局（flex、z-index 等）、按键解析（含 Kitty 键盘协议）、屏幕管理和字素簇处理，使 React 布局系统能够完整运作在终端环境中。

src/outputStyles/ — 输出样式主题

管理终端文本和数据的视觉格式化样式，支持不同输出主题的加载和切换。

核心引擎层 (Core Engine)

src/QueryEngine.ts — 对话引擎（核心大脑）

整个系统最核心的模块。管理与 Claude API 的完整对话循环：

消息规范化与格式转换
Tool Call 的触发与结果回填
Token 预算监控
与上下文、状态、工具模块的协调

src/query.ts & src/query/ — 查询主循环

实现迭代式对话循环的具体逻辑：Claude 处理用户输入 → 生成 Tool Call → 执行工具 → 结果回传 → 继续思考。同时管理 Token 配额和上下文压缩边界。

src/context.ts & src/context/ — 上下文/系统提示管理

动态构建发送给 Claude 的系统提示词（System Prompt）。收集当前环境信息（git 状态、目录结构、已打开文件、项目配置等），让 Claude 具备足够的背景知识来回答问题和执行任务。

src/coordinator/ — 多 Agent 协调

实现”协调者模式”（Coordinator Pattern），管理多子 Agent 的复杂工作流或远程执行任务，通过环境变量和 session 持久化确保多步骤任务的状态一致性。

src/state/ — 全局 UI 状态

以 AppStateStore.ts 为中心的集中式状态管理，追踪：

当前运行的任务列表
用户 session 信息
UI 交互状态（当前选中、展开的面板等）
权限授权状态

工具层 (Toolbox)

Claude Code 的工具系统是其能力的核心。所有工具都在 src/tools/ 中定义，通过 src/tools.ts 注册。

工具

功能描述

BashTool

执行 Shell 命令，含危险模式检测、只读验证、沙箱权限

PowerShellTool

Windows PowerShell 命令执行，含语言模式验证

FileReadTool

读取文件内容，支持分页、偏移量

FileEditTool

精确字符串替换编辑文件（带 diff 预览）

FileWriteTool

创建/覆写文件

GlobTool

通过 glob 模式查找文件

GrepTool

基于 ripgrep 的内容搜索

AgentTool

启动专用子 Agent 处理复杂任务

WebFetchTool

抓取网页内容并 AI 处理

WebSearchTool

联网搜索

MCPTool

调用 MCP 服务器提供的外部工具

SkillTool

执行预定义技能（Skill）

NotebookEditTool

编辑 Jupyter Notebook 单元格

REPLTool

在持久化 REPL 环境中执行代码

TaskCreateTool / TaskGetTool / TaskListTool / TaskUpdateTool / TaskOutputTool / TaskStopTool

任务生命周期管理

AskUserQuestionTool

向用户提问并等待回答

EnterPlanModeTool / ExitPlanModeTool

进入/退出规划模式

EnterWorktreeTool / ExitWorktreeTool

Git Worktree 隔离环境管理

ScheduleCronTool

定时任务调度

SleepTool

延迟等待

LSPTool

通过语言服务器获取代码诊断

BriefTool

附件处理（含 Web Bridge 模式下的上传）

SendMessageTool

向运行中的 Agent 发送消息

TeamCreateTool / TeamDeleteTool

Agent 团队管理

src/Task.ts & src/tasks/ — 任务系统

定义长时运行操作的生命周期和类型（local_bash、remote_agent、local_workflow 等）。tasks.ts 作为注册表将任务类型映射到实现，支持任务状态追踪、并发控制和后台执行。

服务层 (Services)

src/services/api/ — Claude API 客户端

与 Anthropic Claude API 通信的底层 SDK 封装。处理请求签名、认证、重试逻辑、流式响应解析和错误处理。包含 metricsOptOut.ts 指标退出控制。

src/services/mcp/ — MCP 协议层

Model Context Protocol 的完整客户端和服务器实现：

支持多种传输层：WebSocket、stdio、InProcess
MCP 服务器注册表和连接管理
工具发现与调用代理
认证处理（McpAuthTool）
权限管理

src/services/lsp/ — 语言服务协议集成

集成 LSP（Language Server Protocol）提供代码智能：

管理各语言 LSP 服务器的生命周期
诊断注册表（错误、警告收集）
被动反馈机制，辅助 Agent 理解代码库

src/services/compact/ — 上下文压缩

防止对话历史超出 Token 限制的核心机制：

监控 Token 使用量，触发自动压缩
通过 fork 出的 Agent 任务对旧消息进行摘要
微压缩（micro-compaction）API
维护对话连续性的压缩提示词

src/services/analytics/ — 遥测与功能开关

基于 OpenTelemetry 的使用指标收集
GrowthBook 功能标志（Feature Flag）集成
上报到 api.anthropic.com/api/claude_code/metrics
隐私控制：DISABLE_TELEMETRY=1 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 可完全关闭

命令层 (Commands)

src/commands/ & src/commands.ts — 斜杠命令系统

处理用户输入的斜杠命令（/commit、/config、/help、/review 等）。每个命令独立实现，commands.ts 统一注册和分发。支持自定义命令和 Skill 命令。

src/skills/ — 技能系统

可复用的预定义行为包，通过 SkillTool 调用。包含内置技能（bundled/）和从目录动态加载技能（loadSkillsDir.ts），支持 MCP 技能构建（mcpSkillBuilders.ts）。

通信/远程层 (Bridge & Remote)

src/bridge/ — Web/Mobile 远程通信桥

实现本地 CLI 与 Claude.ai Web 端、移动端之间的双向通信：

replBridge.ts：REPL 桥接核心，同步本地终端状态到 Web
bridgeApi.ts：与 Bridge 后端 API 的通信
codeSessionApi.ts：Session 生命周期管理
trustedDevice.ts：设备信任认证
workSecret.ts：工作密钥安全管理
createSession.ts：新远程 Session 创建

src/remote/ — 远程 Session 管理

管理远程执行会话，支持 Claude Code 在服务器端无头运行并通过 WebSocket 与客户端通信。包含权限桥接，确保远程执行的安全性。

基础设施层

src/utils/ — 工具函数库

项目最大的目录，提供跨模块共用的基础能力：

子模块

功能

git.ts

Git 操作封装（状态、diff、提交等）

permissions/

权限判断（危险模式检测、文件系统访问控制）

telemetry/

遥测事件发送、BigQuery 指标导出

hooks/

Claude Code Hooks 执行（execHttpHook.ts 等）

shell/

Shell 命令验证（只读命令白名单）

teleport/

Teleport 远程访问集成

model/

模型名称解析、公开名称映射

settings/

用户配置读写（global/local settings）

auth.ts

OAuth 认证、订阅类型判断

config.ts

全局配置读写

sessionStorage.ts

Session 持久化存储

debug.ts

调试日志

errors.ts

错误类型和消息处理

fsOperations.ts

文件系统操作封装

terminal.ts

终端能力检测和控制

image.ts

图片处理（base64、resize）

undercover.ts

Anthropic 内部专用：公开仓库卧底模式

privacyLevel.ts

隐私级别控制（遥测开关）

commitAttribution.ts

Git 提交署名（Co-Authored-By）

src/schemas/ — 数据结构验证

使用 Zod 定义的 Schema 集合，验证配置文件、API 响应和 Plugin Hook 定义的结构完整性，保证类型安全。

src/types/ — 共享 TypeScript 类型

全项目共享的接口和类型定义，按领域组织（commands.ts、permissions.ts、plugin.ts、generated/ 自动生成类型等）。

src/plugins/ — 插件系统

提供扩展框架，支持内置插件和外部捆绑插件的注册与管理，允许在不修改核心代码的前提下扩展功能。

src/history.ts — 历史管理

持久化用户输入历史和大体积粘贴内容。通过哈希去重机制避免重复存储大块文本，将其外化引用，防止 prompt 膨胀。

src/memdir/ — 记忆目录

管理跨 session 持久化的”记忆”文件（MEMORY.md 等），使 Claude 能在不同对话中保留项目上下文。

src/context.ts / src/context/ — 上下文构建

动态生成系统提示词，整合当前工作目录、项目配置（CLAUDE.md）、git 状态、内存文件等信息，为每次 API 请求构建最佳上下文。

特色功能模块

src/vim/ — Vim 编辑模式

在终端输入框中实现完整的 Vim 模态编辑：

支持 Normal/Insert/Visual 等模式切换
实现常用 Motion（hjkl、w、b、$ 等）
实现 Operator（d、c、y 等）
支持文本对象（iw、i”、i( 等）

src/keybindings/ — 键盘快捷键系统

可定制的键绑定框架：

快捷键解析器（支持 Kitty 键盘协议）
React Context Provider 分发按键事件
默认绑定注册表和保留快捷键列表
支持用户自定义 keybindings.json

src/voice/ — 语音输入

语音模式入口，通过 vendor/audio-capture-src 调用原生麦克风 API，实现语音转文字（STT）输入功能（macOS/Linux/Windows 均支持）。

原生模块层 (Vendor)

使用 Node-API（NAPI）编写的原生 C++ 模块，通过 TypeScript 类型声明对上层屏蔽平台差异：

模块

功能

vendor/audio-capture-src

跨平台麦克风录音与音频播放，含 macOS TCC 权限查询

vendor/image-processor-src

图片处理与 macOS 剪贴板图片读取

vendor/modifiers-napi-src

修饰键状态检测（macOS 专用，用于快捷键判断）

vendor/url-handler-src

macOS URL Scheme 事件监听（OAuth 回调用）

数据流图

安全架构

Claude Code 内建了多层安全机制：

权限系统：所有危险操作（文件修改、命令执行）需通过 utils/permissions/ 的检查，可配置白名单/黑名单
危险模式检测：utils/permissions/dangerousPatterns.ts 维护危险命令模式列表，防止过度授权
只读验证：BashTool/PowerShellTool 内置只读命令验证，防止在只读模式下写入
沙箱支持：支持以受限权限运行的沙箱模式（sandboxTypes.ts）
隐私控制：多级遥测控制（privacyLevel.ts），支持完全禁用非必要网络流量
用户提示默认脱敏：遥测事件中用户输入默认，需显式开启 OTEL_LOG_USER_PROMPTS 才上报

技术栈总结

层次	技术选型
运行时	Bun（构建/打包），Node.js（运行）
UI 框架	React + Ink（终端 TUI）
语言	TypeScript
构建工具	Bun Bundle（含 `feature()` 条件编译）
HTTP 客户端	axios
Schema 验证	Zod v4
遥测	OpenTelemetry
原生模块	Node-API (NAPI) / C++
协议	MCP（Model Context Protocol）、LSP、OAuth 2.0、WebSocket

本文档基于 Claude Code v2.1.88 源码分析生成