乐于分享
好东西不私藏

Claude Code 源码深度解析

Claude Code 源码深度解析

基于 2026-03-31 npm source map 泄露的 Anthropic Claude Code TypeScript 源码,面向二次开发者的完整技术参考文档。

1 项目概述

Claude Code 是 Anthropic 开发的命令行 AI 编程助手,运行于终端中,能够执行 Shell 命令、读写文件、搜索代码库,并协调多 Agent 工作流。它是一个完整的Agentic AI 系统,而非简单的聊天界面。

能力维度
描述
核心模块
文件操作
读取、写入、编辑,支持 Jupyter Notebook
FileReadTool / FileWriteTool / FileEditTool
Shell 执行
安全的 Bash/PowerShell 执行,带权限控制
BashTool + permissions/
代码搜索
ripgrep 内容搜索 + Glob 文件匹配
GrepTool / GlobTool
Web 能力
URL 抓取 + 网络搜索
WebFetchTool / WebSearchTool
多 Agent
子 Agent 生成、团队协作、跨进程通信
AgentTool / TeamCreateTool
IDE 集成
VS Code / JetBrains 双向桥接
bridge/
MCP 协议
Model Context Protocol 服务器集成
services/mcp/
持久记忆
会话内存、跨会话记忆、团队共享记忆
memdir/ + sessionStorage.ts

2 技术栈全景

包名
版本/备注
用途
bun
最新版
运行时,原生 TypeScript 支持,替代 Node.js
@anthropic-ai/sdk
官方
Claude API 客户端,支持流式调用
@modelcontextprotocol/sdk
官方
MCP 协议实现(stdio/SSE/WS)
react

 + ink
19 + 自定义
终端 UI 框架,React 组件渲染到 TTY
react/compiler-runtime
编译器
React 编译器运行时,自动 memoization
@commander-js/extra-typings
带类型
CLI 参数解析,带完整类型推导
zod/v4
v4
运行时类型校验,Tool 输入 schema 定义
bun:bundle
Bun 内置
构建时 feature flag 注入,死代码消除
lodash-es
ES 模块版
工具函数(memoize, mapValues, uniqBy 等)
GrowthBook
SDK
服务端 A/B 测试与 Feature Flags
OpenTelemetry
+ gRPC
性能追踪与可观测性

3 目录结构详解

src/├── main.tsx                    # ① CLI 入口,Commander.js 解析,React/Ink 初始化├── commands.ts                 # ② 所有 slash 命令注册表(含 DCE 条件导入)├── tools.ts                    # ③ 所有 Tool 注册表(含 feature-flag 条件导入)├── Tool.ts                     # ④ Tool 接口定义、ToolUseContext、权限类型├── QueryEngine.ts              # ⑤ 查询引擎(对话生命周期管理)├── query.ts                    # ⑥ 核心 LLM 调用循环(tool-call loop)├── context.ts                  # ⑦ 系统/用户上下文收集├── cost-tracker.ts             # ⑧ Token 成本追踪├── entrypoints/│   ├── cli.tsx                 # CLI bootstrap(版本快速路径)│   ├── init.ts                 # 初始化(telemetry、设置加载)│   ├── mcp.ts                  # MCP 服务器入口│   └── agentSdkTypes.ts        # SDK 模式类型定义├── commands/                   # ~50 个斜杠命令实现│   ├── commit.ts               # /commit│   ├── review.ts               # /review│   ├── compact/                # /compact(上下文压缩)│   ├── config/                 # /config(设置管理)│   ├── doctor/                 # /doctor(环境诊断)│   ├── mcp/                    # /mcp(MCP 服务器管理)│   ├── plugin/                 # /plugin(插件管理)│   └── memory/                 # /memory(持久记忆)├── tools/                      # ~40 个 Agent 工具│   ├── BashTool/               # Shell 命令执行│   ├── FileReadTool/           # 文件读取(含图片/PDF)│   ├── FileWriteTool/          # 文件写入│   ├── FileEditTool/           # 字符串替换编辑│   ├── GlobTool/               # 文件模式匹配│   ├── GrepTool/               # ripgrep 内容搜索│   ├── WebFetchTool/           # URL 获取│   ├── WebSearchTool/          # 网络搜索│   ├── AgentTool/              # 子 Agent 生成│   ├── SkillTool/              # Skill 执行│   ├── MCPTool/                # MCP 工具封装│   ├── TeamCreateTool/         # 多 Agent 团队创建│   ├── SendMessageTool/        # Agent 间消息传递│   └── TodoWriteTool/          # Todo 列表管理├── components/                 # ~140 个 Ink UI 组件├── hooks/                      # ~100 个 React Hooks├── services/                   # 外部服务集成(api/mcp/oauth/lsp)├── state/                      # 应用状态管理(AppStateStore)├── bridge/                     # IDE <-> CLI 双向桥接├── utils/                      # ~330 个工具模块├── ink/                        # 自定义 Ink 终端渲染器├── keybindings/                # 键绑定系统├── vim/                        # Vim 模式实现├── memdir/                     # 持久记忆目录扫描├── migrations/                 # 配置版本迁移├── plugins/                    # 内置插件├── skills/                     # Skill 系统├── coordinator/                # 多 Agent 协调(feature-gated)├── remote/                     # 远程会话管理└── tasks/                      # 任务状态管理

4 系统整体架构

5 启动流程

关键优化:startMdmRawRead()和startKeychainPrefetch()在所有import语句执行之前以副作用方式触发,利用 Bun 的并发 I/O,将 macOS 冷启动从约 300ms 降低至约 150ms。

阶段
关键操作
耗时估计
优化手段
Phase 0

 副作用
startMdmRawRead

 + startKeychainPrefetch
0ms(异步触发)
fire-and-forget
Phase 1

 模块加载
~135 个顶层 import 求值
~100ms
与 Phase 0 并行
Phase 2

 并行初始化
GrowthBook + Bootstrap API + Policy
~50ms
Promise.all 并行
Phase 3

 命令/工具注册
getCommands + getTools + MCP 连接
~20ms
懒加载循环依赖
Phase 4

 UI 启动
launchRepl / print mode
~10ms
React/Ink 渲染

6 查询引擎(QueryEngine)

QueryEngine是整个系统的大脑,管理一次完整对话的生命周期(src/QueryEngine.ts,约 1300 行)。每个实例对应一个会话,submitMessage()每次调用启动一个新的 Turn。

6.1 类结构

6.2 Tool-Call 主循环

6.3 系统提示构建优先级

来源
CLI 参数 / 配置
优先级
行为
Override
内部 loop mode
最高
完全替换所有 prompt
Coordinator
COORDINATOR_MODE

 flag
多 Agent 协调专用 prompt
Agent 定义
.claude/agents/*.md 中高
替换或追加默认 prompt
Custom
--system-prompt
替换默认 prompt
Default
内置 Claude Code prompt
普通
标准行为
Append
--append-system-prompt 追加
始终追加到末尾
CLAUDE.md
项目/用户目录文件
注入
作为 attachment 注入上下文

7 工具系统(Tool System)

每个工具是一个自包含的模块,实现统一的Tool接口,包含 Zod schema、权限控制、执行逻辑和 UI 组件。

7.1 Tool 接口核心方法

7.2 内置工具清单

7.3 工具并发执行模型

8 命令系统(Command System)

8.1 命令注册机制

8.2 内置命令分类

分类
命令
描述
代码操作 /commit
智能生成 Git commit
/review
代码 Review 分析
/diff
查看待提交变更
/compact
压缩对话上下文以节省 Token
配置管理 /config
交互式设置管理
/doctor
环境诊断检查
/mcp
MCP 服务器配置
/model
切换使用的 Claude 模型
记忆状态 /memory
持久记忆管理
/tasks
后台任务列表
/context
可视化 Token 使用
扩展 /plugin
插件安装/管理/浏览市场
/skills
Skill 文件管理
/hooks
Hook 配置查看
集成 /ide
IDE 连接状态
/bridge
启用 IDE 桥接模式
/desktop
切换到桌面应用

9 权限系统(Permission System)

Claude Code 实现了一套精细的多层权限系统,在每次工具调用前进行安全检查,防止意外的破坏性操作。

9.1 权限决策流程

9.2 权限模式状态机

9.3 Bash 命令安全分析

危险模式
示例
风险等级
处理方式
递归删除根目录
rm -rf / 极高
强制交互确认,显示警告
管道执行远程脚本
curl | bash 极高
强制交互确认
覆盖系统文件
> /etc/passwd
检测输出重定向目标路径
修改文件权限
chmod 777
提示警告,需用户确认
git push(修改远程)
git push origin main
标准权限检查流程
只读操作
ls

catgrep
自动允许,不中断用户

实现位置:src/utils/permissions/bashClassifier.ts— 基于命令语义分析(非简单字符串匹配),通过src/utils/bash/parser.ts解析 Shell AST 后判断危险模式。

10 插件系统(Plugin System)

10.1 插件目录结构

~/.config/claude/plugins/my-plugin/├── plugin.json              # 插件元数据(可选)├── commands/                # 自定义斜杠命令(Markdown 格式)│   ├── build.md             # /build 命令│   ├── deploy.md            # /deploy 命令│   └── test.md              # /test 命令├── agents/                  # 自定义 AI Agents│   └── code-reviewer.md     # Agent 系统提示定义├── hooks/                   # Hook 配置│   └── hooks.json           # PreToolUse/PostToolUse/SessionStart├── output-styles/           # 自定义输出样式│   └── compact.md└── skills/                  # 可复用 Skill 定义    └── refactor.md

10.2 插件加载时序

10.3 Hook 事件类型

Hook 类型
触发时机
可用环境变量
PreToolUse
Tool 执行前(权限检查后)
$CLAUDE_TOOL_NAME

$CLAUDE_TOOL_INPUT_*
PostToolUse
Tool 执行完成后
同上 + $CLAUDE_TOOL_OUTPUT
PreCompact
上下文压缩前
$CLAUDE_SESSION_ID
PostCompact
上下文压缩后
同上
SessionStart
会话启动时
$CLAUDE_SESSION_ID

$CLAUDE_CWD
SessionStop
会话结束时
同上

11 MCP 集成

11.1 传输类型对比

类型
适用场景
配置字段
推荐
stdio
本地子进程,最常用,零网络延迟
command

 + args + env
✅ 推荐
sse
远程 HTTP SSE 流,支持服务端推送
url

 + headers
远程服务
http
远程 HTTP 请求-响应
url

 + headers
简单 REST
ws
WebSocket 双向通信
url
低延迟场景
sdk
SDK 内嵌模式(程序化注入)
代码注入
SDK 使用

11.2 MCP 工具集成流程

11.3 配置示例

{  "mcpServers": {    "filesystem": {      "type""stdio",      "command""npx",      "args": ["-y""@modelcontextprotocol/server-filesystem""/path/to/dir"]    },    "github": {      "type""sse",      "url""https://api.githubcopilot.com/mcp/",      "headers": {        "Authorization""Bearer ${GITHUB_TOKEN}"      }    },    "my-server": {      "type""stdio",      "command""node",      "args": ["/path/to/my-mcp-server.js"],      "env": { "API_KEY""${MY_API_KEY}" }    }  }}

12 Bridge 系统(IDE 集成)

13 状态管理

Claude Code 使用自制的 Zustand-like 不可变状态管理,核心是AppState类型(被DeepImmutable包裹)。

投机执行(Speculation):SpeculationState实现了一种预取优化——当用户正在输入时,系统会用当前上下文预先执行下一次查询,将结果暂存在文件覆盖层(overlay)中,用户提交后直接使用预计算结果,减少等待时间。

14 Terminal UI(React + Ink)

Claude Code 使用 React 组件模型渲染终端界面,Ink 作为 React 的自定义渲染器将 JSX 渲染为 TTY 输出。

自定义渲染特性
实现文件
说明
终端尺寸检测
ink/terminal.ts
响应式布局适配
超链接支持
ink/supports-hyperlinks.ts
终端 OSC 8 超链接转义序列
BiDi 文本
ink/bidi.ts
阿拉伯语等 RTL 语言支持
文本选择/复制
ink/selection.ts
鼠标选择支持
ANSI 处理
ink/Ansi.tsx
ANSI 转义码正确渲染
虚拟滚动
hooks/useVirtualScroll.ts
大量消息时只渲染可见区域
搜索高亮
ink/searchHighlight.ts
历史搜索高亮
Tab 停止
ink/tabstops.ts
终端 Tab 键焦点管理

15 会话存储与持久化

文件/目录
用途
格式
transcript.jsonl
对话记录(追加写,不修改历史)
JSONL,每行一条消息
file_history/
每次 Turn 开始时的文件状态快照
SHA 哈希索引
config.json
全局设置(模型、权限规则、MCP 等)
JSON
.claude/CLAUDE.md
项目级系统提示(自动注入)
Markdown
~/.claude/CLAUDE.md
用户级全局系统提示
Markdown
~/.config/claude/plugins/
已安装插件目录
目录结构

16 Feature Flags 与死代码消除

Anthropic 利用 Bun 的bun:bundle实现构建时 Feature Flag 注入。当 flag 为false时,整个代码分支在打包时被完全移除,外部发布版本不包含任何内部专属功能的代码或字符串。

Flag
功能描述
外部版本
KAIROS
助手模式(always-on AI 助手)
❌ 移除
PROACTIVE
主动模式
❌ 移除
VOICE_MODE
语音输入
❌ 移除
BRIDGE_MODE
IDE 桥接
✅ 保留
COORDINATOR_MODE
多 Agent 协调器
❌ 移除
AGENT_TRIGGERS
定时/远程 Agent 触发器
❌ 移除
AGENT_TRIGGERS_REMOTE
远程触发 Agent
❌ 移除
MONITOR_TOOL
监控工具
❌ 移除
TRANSCRIPT_CLASSIFIER
命令自动分类(Auto Mode 核心)
✅ 保留
HISTORY_SNIP
历史记录截断
✅ 保留
REACTIVE_COMPACT
响应式上下文压缩
✅ 保留
ENABLE_AGENT_SWARMS
Agent 团队功能
✅ 保留
ANT_ONLY
内部员工专属功能
❌ 移除
CONTEXT_COLLAPSE
上下文折叠压缩
✅ 保留
DAEMON
守护进程模式
❌ 移除
ABLATION_BASELINE
实验对照组
❌ 移除
DUMP_SYSTEM_PROMPT
导出系统提示(调试用)
❌ 移除

17 二次开发指南

前提:这是源码研究版本,无 package.json/build 脚本。二次开发建议基于官方 npm 包的插件系统或通过 MCP 协议扩展,无需修改源码。

17.1 添加新 Tool(修改源码方式)

📄 MyCustomTool.ts 完整示例

// src/tools/MyCustomTool/MyCustomTool.tsimport { z } from 'zod/v4'import type { ToolToolUseContextToolResult } from '../../Tool.js'const InputSchema = z.object({  target: z.string().describe('操作目标路径或标识符'),  options: z.object({    verbose: z.boolean().default(false).describe('是否输出详细信息'),    dryRun: z.boolean().default(false).describe('是否只模拟执行'),  }).optional(),})export const MyCustomToolTool<typeof InputSchemastring> = {  name'MyCustom',  searchHint'custom operation for specific domain task',  inputSchemaInputSchema,  maxResultSizeChars10_000,  async call(args, contextToolUseContext, canUseTool, parentMsg, onProgress) {    const { target, options } = args    onProgress?.({ toolUseID'...'data: { type'progress'percent50 } })    const result = await doSomething(target, context.abortController.signal)    return { data: result }  },  async description(input) { return `执行: ${input.target}` },  isEnabled()             { return true },  isReadOnly()           { return false },  isConcurrencySafe()   { return true },  isDestructive()       { return false },}

17.2 通过插件系统扩展(推荐,无需修改源码)

📄 命令插件示例(commands/analyze.md)

---description: Deep code analysis with metricsallowedTools:  - Bash  - Read  - Glob  - Grep---You are a code analysis expert. Analyze the codebase for:1. Code complexity metrics2. Dependency structure3. Test coverage gaps4. Performance bottlenecksTarget: $ARGUMENTSProvide actionable recommendations with file:line references.

📄 Hook 插件示例(hooks/hooks.json)

{  "PostToolUse": [    {      "matcher""Write",      "hooks": [{        "type""command",        "command""prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"      }]    },    {      "matcher""Edit",      "hooks": [{        "type""command",        "command""eslint --fix \"$CLAUDE_TOOL_INPUT_PATH\" 2>/dev/null || true"      }]    }  ],  "SessionStart": [{    "hooks": [{ "type""command""command""git status --short" }]  }]}

17.3 关键扩展点总览

17.4 重要配置文件路径

路径
用途
修改方式
~/.config/claude/config.json
全局设置(模型、权限、MCP 等)
/config

 命令或直接编辑
~/.config/claude/CLAUDE.md
用户级全局系统提示
直接编辑
.claude/CLAUDE.md

(项目根)
项目级系统提示,自动注入
直接编辑
.claude/settings.json
项目级权限规则
直接编辑
~/.cache/claude/sessions/
会话持久化目录
只读(自动管理)
~/.config/claude/plugins/
插件安装目录
/plugin

 命令或手动放置
~/.config/claude/skills/
用户级 Skill 定义目录
手动放置 .md 文件