被迫“开源“的Claude Code 架构设计解析
近日被近开源的Claude Code 是 Anthropic 官方 CLI 工具，为开发者提供基于 LLM 的终端交互式编程助手。系统以 交互式 REPL（Read-Eval-Print Loop） 为核心交互模式，同时支持无头/SDK 调用、远程控制、多 Agent 协作等多种运行模式。
·
基于 claude-code-source-code v2.1.88 反编译源码分析
项目路径：
claude-code-source-code
1. 系统概述
Claude Code 是 Anthropic 官方 CLI 工具，为开发者提供基于 LLM 的终端交互式编程助手。系统以 交互式 REPL（Read-Eval-Print Loop） 为核心交互模式，同时支持无头/SDK 调用、远程控制、多 Agent 协作等多种运行模式。
1.1 运行环境
| 属性 | 值 |
|---|---|
| 语言 | TypeScript（ESM 模块） |
| 原始运行时 | Bun（生产；利用编译时特性） |
| 兼容运行时 | Node.js ≥ 18（研究构建版） |
| UI 框架 | React 18 + Ink 5.x（终端 TUI） |
| 打包工具 | esbuild（研究版）/ Bun compile（生产版） |
| 模块系统 | ESM（"type": "module"） |
1.2 运行模式
claude [args]
├── --version → 快速版本输出（零依赖加载）
├── --daemon-worker → Daemon Worker 模式
├── remote-control/rc → Bridge 远程控制模式
├── daemon → 守护进程模式
├── ps/logs/attach/kill → 后台任务管理模式
├── new/list/reply → Template Jobs 模式
├── environment-runner → 环境运行器模式
├── self-hosted-runner → 自托管运行器模式
└── (default) → 交互式 REPL 模式
2. 整体架构
2.1 分层架构图
┌──────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ Ink TUI (React) │ StatusLine │ PermissionRequest │
│ REPL.tsx │ VirtualMessageList │ PromptInput │
├──────────────────────────────────────────────────────────────┤
│ Application Layer │
│ main.tsx (CLI Init) │ commands.ts │ replLauncher.tsx │
│ processUserInput │ Skills │ Plugins │
├──────────────────────────────────────────────────────────────┤
│ Core Engine Layer │
│ query.ts (LLM Loop) │ QueryEngine.ts │ StreamingToolExecutor│
│ Tool.ts (Interface) │ AppState/Store │ context.ts │
├──────────────────────────────────────────────────────────────┤
│ Service Layer │
│ MCP Integration │ Compact Service │ Analytics │
│ OAuth/Auth │ LSP Service │ Task Manager │
│ Memory (memdir) │ Bridge │ GrowthBook │
├──────────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ Anthropic SDK (claude.ts) │ fs/promises │ ripgrep │
│ Commander.js │ Node.js IPC │ WebSocket │
└──────────────────────────────────────────────────────────────┘
2.2 核心模块关系图
┌─────────────┐
│ cli.tsx │ 启动入口（动态 import 零延迟）
└──────┬──────┘
│
┌──────▼──────┐
│ main.tsx │ 初始化（Auth/MCP/Tools/State）
└──────┬──────┘
│
┌────────────▼────────────┐
│ REPL.tsx (Ink) │ 终端 UI
└────────────┬────────────┘
│ 用户输入
┌────────────▼────────────┐
│ processUserInput() │ 输入路由
└──────┬──────────┬───────┘
│ │
┌────────▼──┐ ┌───▼────────────┐
│ Command │ │ QueryEngine │ LLM 会话管理
│ Handler │ └───┬────────────┘
└───────────┘ │
┌──────▼──────┐
│ query() │ LLM 调用循环（AsyncGen）
└──────┬──────┘
│
┌───────────────▼────────────────┐
│ StreamingToolExecutor │ 并发工具执行
└────────┬─────────┬─────────────┘
│ │
┌─────────▼──┐ ┌───▼──────────┐
│ BashTool │ │ FileEditTool │ ... (35+ 工具)
└────────────┘ └──────────────┘
3. 核心模块详述
3.1 启动入口链
文件: src/entrypoints/cli.tsx → src/main.tsx
启动时的关键设计决策：
cli.tsx所有 import 均为动态 import()，保证--version路径的启动延迟接近零main.tsx最早执行三个并行副作用：profileCheckpoint('main_tsx_entry')— 性能埋点startMdmRawRead()— 企业 MDM 配置预读startKeychainPrefetch()— 钥匙串令牌预加载
初始化序列（main.tsx → main() 函数）：
配置迁移 → enableConfigs → loadPolicyLimits → initSinks
→ Commander.js 参数解析（150+ 选项）
→ Auth 检查（OAuth / API Key / Bedrock / Vertex / Foundry）
→ GrowthBook 功能标志初始化
→ MCP 服务器加载（getMcpToolsCommandsAndResources）
→ 工具注册（getTools()）
→ AppState 创建（createStore）
→ launchRepl() → Ink TUI
3.2 LLM 查询引擎
文件: src/query.ts, src/QueryEngine.ts
系统的核心处理引擎，负责与 Anthropic API 的所有交互。
query() 函数（核心循环）
query(params: QueryParams) → AsyncGenerator
├─ buildSystemPrompt() 构建系统提示词
├─ claude.ts: API 流式调用 BetaMessageStreamParams
│ └─ 事件: text_delta / tool_use / message_stop
├─ StreamingToolExecutor 并发工具执行
│ ├─ isConcurrencySafe → 并行执行
│ └─ !isConcurrencySafe → 串行执行
├─ AutoCompact 触发检测 Token 阈值检查
├─ Stop Hooks 处理
└─ 有工具结果 → 继续下一轮循环
QueryEngine 类（SDK/无头模式）
为 SDK 调用者提供会话生命周期管理，支持：
maxTurns轮次限制maxBudgetUsd费用控制taskBudgetAPI 预算thinkingConfig思考模式
3.3 工具系统
文件: src/Tool.ts, src/tools/
工具是 Claude Code 的核心扩展机制，所有能力扩展均通过 Tool 接口实现。
工具接口核心属性
type Tool = {
name: string
call(args, context, canUseTool, ...): Promise<ToolResult> // 执行逻辑
inputSchema: ZodSchema // 入参验证
isConcurrencySafe(input): boolean // 并发安全标志
isEnabled(): boolean // 可用性检查
isReadOnly(input): boolean // 只读标志
shouldDefer?: boolean // 延迟加载（ToolSearch 发现）
alwaysLoad?: boolean // 始终注入系统提示
maxResultSize?: number // 超限存盘
}
工具分类
| 类别 | 工具 | 数量 |
|---|---|---|
| 文件操作 | FileRead, FileWrite, FileEdit, Glob, Grep | 5 |
| Shell | Bash | 1 |
| Web | WebFetch, WebSearch | 2 |
| Agent | Agent, SendMessage, TeamCreate, TeamDelete | 4 |
| 任务管理 | TaskCreate, TaskGet, TaskList, TaskUpdate, TaskStop, TaskOutput | 6 |
| 模式控制 | EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree | 4 |
| UI 交互 | AskUserQuestion | 1 |
| MCP | MCPTool, ListMcpResources, ReadMcpResource | 3 |
| 工具发现 | ToolSearch | 1 |
| 其他 | TodoWrite, Config, Notebook, Skill, LSP, ... | 10+ |
3.4 命令系统
文件: src/commands.ts, src/types/command.ts
斜杠命令（/command）系统，与工具系统并列，但直接在本地处理而非通过 LLM。
命令类型：
PromptCommand：展开为文本发送给模型的技能LocalCommand：本地执行返回文本结果LocalJSXCommand：本地执行渲染 Ink React 组件
命令来源：builtin | mcp | plugin | bundled | skills | commands_DEPRECATED
总计 70+ 内置命令，包括 clear/compact/config/context/cost/diff/doctor/help/ide/login/logout/mcp/memory/model/permissions/plan/review/session/skills/status/theme/vim 等。
3.5 状态管理
文件: src/state/AppStateStore.ts, src/state/store.ts
采用自研极简响应式状态容器，遵循不可变更新模式。
Store 接口
type Store<T> = {
getState(): T
setState(updater: (prev: T) => T): void
subscribe(listener: () => void): () => void
}
AppState 核心字段（分组）
| 分组 | 关键字段 |
|---|---|
| 配置 | settings: SettingsJson |
| 模型 | mainLoopModel, thinkingEnabled |
| 权限 | toolPermissionContext: ToolPermissionContext |
| MCP | mcp: {clients, tools, commands, resources} |
| 插件 | plugins: {enabled, disabled, commands, errors} |
| 任务 | tasks: {[taskId]: TaskState} |
| Todo | todos: {[agentId]: TodoList} |
| 文件 | fileHistory: FileHistoryState |
| Bridge | replBridge*（15 个字段） |
| 实验 | tungstenActiveSession, computerUseMcpState |
3.6 MCP 集成
文件: src/services/mcp/
模型上下文协议（MCP）是 Claude Code 的外部扩展体系。
Transport 协议支持：stdio | sse | sse-ide | http | ws | sdk
配置作用域：local | user | project | dynamic | enterprise | claudeai | managed
加载流程：
getMcpToolsCommandsAndResources()
├─ config.ts: 解析多作用域配置（去重、策略过滤）
├─ client.ts: 建立连接（@modelcontextprotocol/sdk）
├─ 获取 tools / resources / prompts
└─ 注册到 AppState.mcp
3.7 上下文压缩（Compact）服务
文件: src/services/compact/
解决 LLM 上下文窗口限制的核心机制。
| 类型 | 触发条件 | 实现 |
|---|---|---|
| AutoCompact | Token 接近阈值 | Fork 子 Agent 生成摘要 |
| MicroCompact | 单工具结果过大 | 替换单条结果 |
| SnipCompact | 历史片段截断 | 直接截断（HISTORY_SNIP 门控） |
| SessionMemoryCompact | 会话结束 | 长期记忆整合 |
autoCompact 流程：
calculateTokenWarningState() → 检测 token 比例
→ 触发阈值 → compact.ts
→ fork 子 Agent（单独 query()调用）
→ 生成"到目前为止的工作摘要"
→ 替换历史消息为摘要消息
→ 继续当前会话
3.8 Bridge 远程控制
文件: src/bridge/
允许 claude.ai 移动/Web 客户端远程控制本地 Claude Code 实例。
安全三重验证：
- OAuth Token 有效性
- GrowthBook Gate 开关（
allow_remote_control） - 企业策略限制（
allow_remote_controlpolicy）
通信流程：
bridgeMain() → registerWorker() → 轮询循环
→ listSessions() → 发现待处理会话
→ SessionRunner.spawn() → 本地 QueryEngine
→ 双向消息转发（inbound / outbound）
→ JWT Token 定期刷新（jwtUtils.ts）
3.9 任务系统
文件: src/tasks/, src/Task.ts
支持长时间运行的异步任务，输出持久化到磁盘。
任务类型：
| 类型 | 说明 | 状态 |
|---|---|---|
local_bash |
本地 Shell 命令任务 | 已发布 |
local_agent |
本地子 Agent 任务 | 已发布 |
remote_agent |
远程 CCR Agent 任务 | 已发布 |
in_process_teammate |
进程内团队成员 | 已发布 |
local_workflow |
本地工作流任务 | 门控 |
monitor_mcp |
MCP 监控任务 | 门控 |
dream |
后台记忆整合（KAIROS） | 门控 |
任务状态机：pending → running → completed / failed / killed
3.10 Analytics 分析服务
文件: src/services/analytics/
双管线架构：
logEvent()
├─ 1P（First-Party）→ api.anthropic.com/api/event_logging/batch
│ OpenTelemetry + Protobuf
│ 批量200事件 / 10秒刷新 / 磁盘持久化重试
│ 无法通过配置关闭
└─ 3P（Datadog）→ http-intake.logs.us5.datadoghq.com
仅64种预批准事件类型
可通过 killswitch 关闭（GrowthBook flag: tengu_frond_boric）
4. 关键技术栈
| 层次 | 技术 | 用途 |
|---|---|---|
| UI 框架 | React 18 + Ink 5.x | 终端 TUI 渲染 |
| LLM 接入 | @anthropic-ai/sdk | Anthropic API 调用 |
| MCP 协议 | @modelcontextprotocol/sdk | MCP 服务器连接 |
| CLI 解析 | @commander-js/extra-typings | 命令行参数 |
| Schema 验证 | zod/v4 | 工具入参验证 |
| 功能标志 | @growthbook/growthbook | A/B 测试 / 功能门控 |
| 工具搜索 | ripgrep（命令行调用） | 代码内容搜索 |
| 状态管理 | 自研 Store | 应用状态响应式更新 |
| 分析上报 | OpenTelemetry + Datadog | 双管线事件上报 |
| 工具函数 | lodash-es | memoize/mapValues/uniqBy 等 |
| 颜色输出 | chalk | 终端颜色 |
| 格式化 | strip-ansi / figures | ANSI 处理 |
5. 功能特性矩阵
5.1 已发布功能
| 功能 | 核心模块 |
|---|---|
| 交互式 REPL | REPL.tsx + query.ts |
| 70+ 斜杠命令 | commands.ts |
| 35+ 内置工具 | tools/ |
| MCP 服务器集成 | services/mcp/ |
| 多 Agent 协作 | AgentTool + tasks/ |
| 上下文自动压缩 | services/compact/ |
| Git Worktree 支持 | EnterWorktreeTool |
| Vim 模式 | vim/ |
| 技能（Skills）系统 | skills/ |
| 插件系统 | plugins/ |
| Remote Bridge | bridge/ |
| IDE 集成 | plugins/bundled/ |
| 权限管理 | utils/permissions/ |
5.2 门控中功能（Feature Flags）
| 代号 | 功能 | Flag 前缀 |
|---|---|---|
| KAIROS | 自主 Agent 模式（无人值守） | kairos_* |
| VOICE_MODE | 语音输入 | voice_* |
| WEB_BROWSER_TOOL（bagel） | 浏览器自动化 | bagel_* |
| COORDINATOR_MODE | 多 Agent 协调 | coord_* |
| BUDDY | 虚拟宠物伴侣 | buddy_* |
| AGENT_TRIGGERS | Cron 定时触发 | triggers_* |
| BG_SESSIONS | 后台会话 | bg_* |
| DAEMON | 守护进程 | daemon_* |
| HISTORY_SNIP | 历史片段截断 | snip_* |
6. 系统数据流
6.1 主交互流程（REPL 模式）
用户键盘输入
→ PromptInput（Ink组件）
→ REPL.tsx handleMessage()
→ processUserInput()
├─ 斜杠命令 → Command.call() → 本地处理
└─ 普通消息 → QueryEngine.submitMessage()
→ query() [AsyncGenerator]
→ buildSystemPrompt()
→ Anthropic API 流式调用
→ text_delta → 实时显示
→ tool_use → StreamingToolExecutor
→ canUseTool() 权限检查
→ PermissionRequest 对话框（如需用户确认）
→ Tool.call() → ToolResult
→ 检查 Token 预算 / AutoCompact
→ 有工具结果 → 下一轮 API 调用
→ stop → 最终 AssistantMessage
→ 更新 messages state
→ REPL 重渲染（React/Ink）
6.2 多 Agent 流程
主 Agent → AgentTool.call()
├─ 本地路径:
│ LocalAgentTask.spawn()
│ → 新 QueryEngine 实例
│ → 独立工具池（assembleToolPool）
│ → 独立 AbortController
│ → 输出写入磁盘（TaskOutput）
└─ 远程路径:
RemoteAgentTask
→ bridgeApi 创建远程会话
→ 轮询任务状态
7. 安全模型
7.1 权限模式
| 模式 | 行为 |
|---|---|
default |
每次可能破坏性操作前询问用户 |
acceptEdits |
自动接受文件编辑，询问执行 |
bypassPermissions |
跳过所有权限检查（危险，需 env 设置） |
plan |
只读模式，禁止写入/执行 |
7.2 工具权限检查
canUseTool(tool, input)
→ toolPermissionContext 查询
→ alwaysAllow 白名单检查
→ alwaysDeny 黑名单检查
→ isReadOnly(input) → 自动允许
→ 提示用户确认（PermissionRequest UI）
7.3 Analytics 数据安全
AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS— 强制标注非敏感数据AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED— PII 标记路由到特权列- 工具输入默认不上报，需
OTEL_LOG_TOOL_DETAILS=1显式开启
8. 目录结构与职责
claude-code-source-code/
├── src/ # 全部 TypeScript 源码
│ ├── entrypoints/ # 入口文件（cli.tsx）
│ ├── main.tsx # CLI 主初始化（最大单文件 ~789KB）
│ ├── query.ts # LLM 查询循环核心
│ ├── QueryEngine.ts # SDK 会话管理
│ ├── Tool.ts # 工具基础接口
│ ├── commands.ts # 命令系统
│ ├── tools.ts # 工具注册/组装
│ ├── context.ts # 系统提示上下文
│ ├── tools/ # 35+ 内置工具实现
│ ├── screens/ # Ink UI 主界面（REPL.tsx）
│ ├── components/ # 120+ React 组件
│ ├── state/ # 状态管理
│ ├── services/ # 服务层（MCP/Compact/Analytics/OAuth/LSP）
│ ├── tasks/ # 任务系统
│ ├── bridge/ # 远程控制
│ ├── skills/ # 技能系统
│ ├── plugins/ # 插件系统
│ ├── memdir/ # 内存/CLAUDE.md 管理
│ ├── migrations/ # 配置迁移
│ ├── constants/ # 系统提示词等常量
│ ├── bootstrap/ # 全局单例状态
│ ├── types/ # 类型定义
│ └── utils/ # 工具函数
├── docs/ # 分析文档（中英文）
├── scripts/ # 构建脚本
├── tools/ # 外部调试工具
├── utils/ # 原生 JS 工具（系统集成）
├── vendor/ # Native 扩展（C/C++/Rust）
├── stubs/ # Bun 专有 API 桩模块
└── types/ # 额外类型声明
欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。
更多推荐
10
0- 0
已为社区贡献2条内容
所有评论(0)