cc源码深度分析

Claude Code 源码深度分析报告

项目来源: instructkr/claude-code性质: Claude Code CLI 源码镜像（npm source map 泄露，2026-03-31）规模: ~1,900 文件，512,000+ 行 TypeScript运行时: Bun · UI: React + Ink（终端）

一、整体架构总览

Claude Code 本质上是一个 AI 编程 Agent 运行时，运行在终端中。它通过模块化的工具注册系统，让 LLM（Claude）能够执行文件操作、Shell 命令、搜索、Web 访问、任务管理等操作，并支持多 Agent 协作、远程控制、插件扩展等高级功能。

二、技术栈一览

层级 技术选型 说明

运行时 Bun 高性能 JavaScript/TypeScript 运行时

UI 渲染 React + Ink Ink 是 React 的终端渲染器，实现富文本 CLI

状态管理 Zustand 轻量级 React 状态管理

类型校验 Zod 运行时 Schema 校验

CLI 框架 Commander.js 命令行参数解析

LLM 接口 Anthropic API 与 Claude 大模型通信

三、目录结构解析

Plain Text

src/

├── main.tsx                    # CLI 入口 (Commander.js)

├── commands.ts                  # 命令注册表 (~50 个斜杠命令)

├── tools.ts                    # 工具注册表 (~40 个工具)

├── Tool.ts                     # 工具基类定义 (792 行)

├── QueryEngine.ts              # LLM 查询引擎 (1,295 行)

├── context.ts                  # 上下文管理器 (189 行)

├── cost-tracker.ts             # Token 成本追踪

│

├── commands/                    # ~50 个斜杠命令实现

├── tools/                       # ~40 个工具实现

├── components/                  # ~140 个 Ink UI 组件

├── screens/                     # 全屏 UI (REPL/Doctor/Resume)

├── coordinator/                 # 多 Agent 协调器

├── plugins/                     # 插件系统

├── skills/                      # 技能系统

├── bridge/                      # IDE&远程控制桥接 (40+ 文件)

├── server/                      # 服务端模式

├── remote/                      # 远程会话管理

├── memdir/                      # 持久化记忆目录

├── tasks/                       # 任务系统

├── state/                       # Zustand 状态管理

├── services/                    # 外部服务集成

├── schemas/                     # Zod 配置校验

├── migrations/                   # 配置迁移

├── voice/                       # 语音输入

├── vim/                         # Vim 模式

└── native-ts/                   # 原生 TypeScript 工具

四、核心模块详解

4.1 入口与命令行系统 (main.tsx)

基于 Commander.js 构建 CLI 框架，定义所有顶级命令（/quit、/clone、/session 等），通过 commands.ts 路由到对应处理逻辑。

关键设计：

1 CLI 路径通过 Commander.js 映射到不同功能模块

1 支持交互式 REPL（Read-Eval-Print Loop）模式

1 setup.ts 处理首次运行的引导配置流程

4.2 工具系统（核心）— Tool.ts + tools.ts

这是 Claude Code 最核心的模块。每个工具都是自包含模块，遵循统一接口：

TypeScript

// Tool 接口 (Tool.ts, 792 行)

interface Tool {

  name: string                    // 工具名称

  description: string             // 描述（供 LLM 理解何时使用）

  inputSchema: Zod Schema         // 输入参数校验

  outputSchema?: Zod Schema       // 输出校验

  permissions: PermissionModel    // 权限模型

  execute(): Promise<Result>      // 执行逻辑

  render?(): ReactNode           // 可选的富文本渲染

}

工具分类（~40 个）：

类别 工具 说明

文件 FileReadTool, FileWriteTool, FileEditTool, GlobTool 完整文件操作，支持字符串替换编辑

Shell BashTool, PowerShellTool, REPLTool 执行系统命令、Shell、REPL

搜索 GrepTool, WebSearchTool, WebFetchTool, ToolSearchTool 代码搜索 + Web 搜索

Agent 协作 AgentTool, TeamCreateTool, SendMessageTool 子 Agent spawn、团队管理、消息传递

任务管理 TaskCreateTool, TaskUpdateTool, TaskListTool 任务创建/更新/列表

Git Worktree EnterWorktreeTool, ExitWorktreeTool 进入/退出 Git Worktree 隔离

计划模式 EnterPlanModeTool, ExitPlanModeTool 切换 Agent 进入规划模式

MCP MCPTool, ListMcpResourcesTool, ReadMcpResourceTool 调用 MCP 服务器工具

Skill SkillTool 执行外部 Skill

定时 ScheduleCronTool, SleepTool 定时触发、延时

4.3 权限模型

每个工具都有独立的 Permission Model，这是 Claude Code 安全架构的核心：

TypeScript

// 权限级别

permission: {

  mode: ‘read’ | ‘write’ | ‘dangerous’ | ‘bypassable’

  requiresApproval: boolean

  canSkipApproval: boolean  // Agent 可自跳过（需 trust 模式）

}

模式 说明

bypassable 可在 trust 模式跳过确认

dangerous 危险操作，始终需确认

read 只读操作

write 写入操作（有条件确认）

4.4 查询引擎 (QueryEngine.ts — 1,295 行)

QueryEngine 是 Claude Code 与 LLM 之间的桥梁，负责：

1 对话循环管理 — 维护 messages[]，处理多轮对话

1 工具调用往返 — 接收 LLM 的 tool_use，调度工具执行，结果注入上下文

1 上下文窗口管理 — 自动决定哪些历史消息保留

1 Token 追踪 — cost-tracker.ts 记录每个请求的消耗

1 截断策略 — 当 context 快满时，自动摘要/压缩旧消息

4.5 上下文系统 (context.ts — 189 行)

ContextManager 负责动态收集和压缩上下文，确保 LLM 每次请求都获得最相关的信息。

上下文来源：

1 systemPrompt：固定系统提示

1 projectContext：项目信息（语言、框架）

1 recentMessages：最近对话历史

1 taskContext：当前任务状态

1 fileContext：当前打开的文件内容

1 relevantMemories：从 memdir 检索的相关记忆

记忆系统 (memdir/)：

1 memdir.ts — 记忆目录管理

1 findRelevantMemories.ts — 语义检索相关记忆

1 memoryScan.ts — 扫描项目文件生成记忆

1 teamMemPaths.ts — 团队共享记忆路径

Claude Code 在 ~/.claude/ 目录下维护持久化记忆，能在多个会话间保持跨会话上下文。

4.6 任务系统 (tasks/)

Plain Text

tasks/

├── LocalMainSessionTask.ts       # 本地主会话任务

├── LocalAgentTask.ts             # 本地 Agent 子任务

├── LocalShellTask.ts             # 本地 Shell 任务

├── RemoteAgentTask.ts            # 远程 Agent 任务

├── InProcessTeammateTask.ts      # 同进程 Team 任务

└── DreamTask/                    # 自动化做梦（实验性）

设计模式：每个 Task 代表一个独立执行单元，类似于轻量级进程：

1 有自己的状态（pending / running / completed / failed）

1 有自己的输入/输出

1 可以被启动、停止、查询

4.7 多 Agent 协调系统 (coordinator/)

Claude Code 支持多 Agent 协作：

工具 功能

TeamCreateTool / TeamDeleteTool 创建/删除 Agent 团队

AgentTool 在团队中 spawn 新 Agent

SendMessageTool Agent 之间通过消息传递协调

teamMemPaths.ts 团队成员共享记忆

任务依赖管理：

1 任务可声明 blocked-by 依赖

1 前置任务完成后自动解除阻塞

4.8 技能系统 (skills/)

Plain Text

skills/

├── bundled/                     # 内置技能目录

├── bundledSkills.ts             # 技能注册表

├── loadSkillsDir.ts            # 从目录动态加载技能

└── mcpSkillBuilders.ts         # MCP Skill 构建器

Skill 是可被 LLM 调用的一组工具/提示词模板包：

1 每个 Skill 有自己的 instructions.md（技能描述）

1 可通过 SkillTool 调用

1 支持从 ~/.claude/skills/ 目录动态加载

4.9 插件系统 (plugins/)

TypeScript

// 插件架构 (plugin.ts)

interface Plugin {

  name: string

  tools?: Tool[]           // 注册新工具

  commands?: Command[]     // 注册新命令

  hooks?: LifecycleHooks   // 钩子到生命周期事件

}

插件可以：

1 注册新的 Tool

1 注册新的命令（/mycommand）

1 Hook 到生命周期事件

4.10 状态管理 (state/)

Plain Text

state/

├── store.ts                  # Zustand store 定义

├── AppState.tsx             # 应用状态类型

├── AppStateStore.ts          # 状态存储

├── onChangeAppState.ts       # 状态变更处理器

└── selectors.ts              # 状态选择器

设计选择：Claude Code 选择 Zustand（轻量级 React 状态管理库）而非 Redux：

1 更简单的 API

1 更好的 TypeScript 支持

1 更小的 bundle 体积

4.11 桥接与远程控制 (bridge/ — 40+ 文件)

这是 Claude Code 最复杂的子系统，负责多种连接模式：

三种运行模式：

模式 说明

Local REPL 直接在终端本地运行，CLI 独占

Direct Connect –connect 参数直连远程 Claude Code 实例

Remote Bridge 通过 WebSocket 连接到远程服务

通信机制：

1 WebSocket：SessionsWebSocket.ts 处理实时双向通信

1 轮询（Polling）：当 WebSocket 不可用时降级为 HTTP 轮询

1 JWT 认证：jwtUtils.ts + trustedDevice.ts 处理设备认证

4.12 服务端模式 (server/)

Plain Text

server/

├── createDirectConnectSession.ts  # 创建直连会话

├── directConnectManager.ts         # 直连管理器

└── types.ts                       # 类型定义

Claude Code 支持服务端运行模式：

1 –server 标志启动为守护进程

1 通过 createDirectConnectSession API 接受客户端连接

1 支持多客户端并发连接

4.13 MCP（Model Context Protocol）集成

MCP 是 Claude Code 的扩展性核心，允许接入任何 MCP 兼容服务器：

工具 功能

MCPTool 调用 MCP 服务器提供的工具

ListMcpResourcesTool 列出 MCP 资源

ReadMcpResourceTool 读取 MCP 资源

McpAuthTool MCP 认证

通过 MCP，Claude Code 可以接入 GitHub、Slack 及任何第三方 MCP 服务器。

4.14 UI 系统（Ink + React）

Claude Code 使用 Ink（React 的终端渲染器）在终端中呈现富文本 UI：

Plain Text

screens/

├── REPL.tsx                    # 主交互界面

├── Doctor.tsx                  # 环境诊断界面

└── ResumeConversation.tsx      # 会话恢复界面

components/  (~140 个组件)

└── (大量 Ink 组件用于渲染各种 UI 元素)

Ink vs 传统终端：

1 传统 CLI 输出是纯文本流

1 Ink 允许用 React 组件描述 UI

1 实时更新，自动处理终端 resize

1 支持颜色、布局、进度条等复杂元素

4.15 斜杠命令系统 (commands/)

~50 个斜杠命令，每个都是独立模块：

命令 功能

/doctor 环境诊断

/model 切换模型

/cost 查看 token 消耗

/config 配置管理

/mcp MCP 服务器管理

/diff 查看变更

/branch Git 分支管理

/memory 记忆管理

/compact 上下文压缩

/login / /logout 认证

五、安全架构

5.1 权限层级

权限模式 说明

bypassable 可在 trust 模式跳过确认

dangerous 危险操作，始终需确认

read 只读操作

write 写入操作（有条件确认）

5.2 信任设备机制

trustedDevice.ts 实现信任设备模型：

1 首次连接需要手动授权

1 授权后设备获得长期 credential

1 通过 JWT 机制验证

5.3 源码泄露事件启示

泄露路径 说明

npm 包 → .map 文件暴露 → R2 Storage 未授权访问 → TypeScript 源码

教训：

1 Source Map 安全：生产环境不应包含未混淆的 .map 文件

1 构建产物审计：发布前应清理所有调试信息

1 云存储权限：R2/CVS 等对象存储应遵循最小权限原则

1 供应链检测：需要自动化检测意外泄露

六、设计模式总结

模式 应用位置 描述

Tool Pattern Tool.ts 统一工具接口：名称+Schema+权限+执行

Registry Pattern tools.ts commands.ts 中心化注册表，按名称查找

Strategy Pattern 各 Tool 实现 不同工具有不同执行策略

Observer Pattern State (Zustand) 状态变更自动通知 UI

Factory Pattern Task 系统 不同 Task 子类由工厂创建

Plugin Pattern plugins/ 运行时加载扩展

Pipeline Pattern QueryEngine 请求→处理→LLM→工具→响应的管道

Memory Pattern memdir/ 持久化记忆，跨会话检索

七、关键设计原则

1 工具化抽象：所有能力（文件、网络、Git、终端）都抽象为统一 Tool 接口

1 安全第一：完善的权限模型 + 信任设备机制 + Zod Schema 校验

1 可扩展性：Plugin 系统 + Skill 系统 + MCP 协议，三层扩展机制

1 状态管理：Zustand + Ink React 组件，清晰的响应式状态流

1 远程优先：Bridge 系统支持多种远程模式，适应不同部署场景

1 多 Agent：内置团队协作能力，支持任务分解和 Agent 间通信

八、总结

Claude Code 是一个高度工程化的 AI 编程 Agent，其核心架构体现了现代 Agent 系统设计的最佳实践。

这个项目的源码泄露，为研究 AI Agent 的工程实现提供了宝贵的案例。

本报告基于公开泄露的源码快照分析，仅供教育与安全研究使用。报告生成时间：2026-03-31