Claude Code 源码架构与模块功能详解

本文档基于本仓库 src/ 目录结构、README.md 说明及对关键入口与模块的代码阅读整理，用于按架构分模块梳理职责与数据流。仓库为公开快照，原始版权归 Anthropic；本文仅作结构与功能层面的技术分析。

---

一、项目定位与技术栈

1.1 产品定位

Claude Code 是面向终端的 AI 编程助手 CLI：在本地工作区中与 Claude 对话，完成读改文件、执行命令、检索代码库、调用外部工具（MCP / LSP）、多代理协作、会话恢复等软件工程任务。

1.2 技术栈摘要

类别	技术
运行时	Bun
语言	TypeScript（严格模式）
终端 UI	React + Ink
CLI 解析	Commander.js
校验	Zod v4
模型 API	Anthropic SDK
扩展协议	MCP SDK、LSP
特性开关 / 实验	GrowthBook（Statsig 等门控）
构建裁剪	bun:bundle 的 feature() 编译期消除

1.3 架构分层（逻辑视图）

text

┌─────────────────────────────────────────────────────────────┐
│  入口层 entrypoints / main.tsx — CLI 解析、快速路径、子进程   │
├─────────────────────────────────────────────────────────────┤
│  表现层 components / screens / ink / context — Ink UI 与状态  │
├─────────────────────────────────────────────────────────────┤
│  交互层 commands / keybindings / vim / voice — 用户指令与输入  │
├─────────────────────────────────────────────────────────────┤
│  编排层 query.ts / QueryEngine — 对话轮次、流式、工具循环       │
├─────────────────────────────────────────────────────────────┤
│  工具层 tools/* + services/tools — 工具注册、权限、并发执行   │
├─────────────────────────────────────────────────────────────┤
│  服务层 services/* — API、OAuth、MCP、压缩、遥测、插件等        │
├─────────────────────────────────────────────────────────────┤
│  基础设施 utils / types / schemas / migrations / bootstrap   │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
    bridge/remote/      coordinator/         memdir/skills/
    server/upstreamproxy  多代理模式           记忆与技能

---

二、顶层目录与职责总览

以下为 src/ 下一级目录（及少量根级核心文件）的职责摘要。

路径	职责
entrypoints/	多入口：cli.tsx（主 CLI）、mcp.ts（MCP 服务模式）、init.ts（初始化）、SDK 类型与沙箱类型
main.tsx	与 Commander 配合的总体启动；并行预取（MDM、钥匙串等）以优化冷启动
cli/	结构化 I/O、NDJSON、传输层（SSE/WebSocket/Hybrid）、远程 I/O、更新与各类 handler（auth、MCP、agents、plugins 等）
query.ts / query/	查询管线核心 ：消息规范化、流式响应、工具调用循环、压缩边界、与 QueryConfig 等配置快照
Tool.ts / tools.ts	工具类型定义与全量工具注册；按 feature / 环境条件加载可选工具
tools/	各 Tool 的独立实现（schema、权限、执行逻辑、prompt 片段）
commands/	以 / 为主的斜杠命令及子命令实现（数十个子目录）
components/	Ink 组件库（消息气泡、输入框、列表、弹层等）
screens/	全屏或大型界面（如 Doctor、REPL、Resume 等场景）
context/	React Context：通知、邮箱、语音、统计、遮罩、队列消息等 UI 级横切状态
hooks/	React Hooks：设置、IDE、剪贴板、权限、任务、语音、远程会话等；含 toolPermission/
services/	对外服务与客户域逻辑：API、OAuth、MCP、LSP、压缩、分析、插件、策略限制、语音 STT 等
bridge/	IDE / 远程桥：会话创建、JWT、轮询、REPL 桥、容量唤醒、与云端 API 协同
remote/	远程会话：WebSocket、RemoteSessionManager、权限桥、SDK 消息适配
server/	直连 / 会话服务相关（如 directConnectManager、类型定义）
coordinator/	协调器模式 （coordinatorMode.ts）：多代理场景下的工具白名单与用户上下文注入
tasks/	本地任务执行：LocalShellTask、LocalAgentTask、DreamTask 等与 UI/执行隔离相关的任务模型
state/	应用级状态存储（如 AppStateStore）
plugins/	内置与打包插件注册
skills/	技能加载、捆绑技能（bundled）、与 MCP 技能构建辅助
memdir/	持久记忆目录 ：MEMORY.md 入口、扫描、团队记忆路径、相关 prompt 拼装
keybindings/	快捷键解析、默认绑定、校验
vim/	Vim 模式：动作、操作符、文本对象、过渡状态
voice/	语音输入管线（与 services/voice*.ts 协同）
outputStyles/	输出样式加载
upstreamproxy/	CCR 容器内上游代理：token、CA 合并、CONNECT→WebSocket relay、环境变量注入
bootstrap/	启动期状态（会话 ID、附加目录缓存等）
migrations/	配置/数据迁移
schemas/	Zod 配置 schema
types/	消息、权限、日志、生成事件类型等
utils/	通用工具：消息、Git、权限、模型、token、附件、配置等
assistant/	助手侧历史等
buddy/	伴侣精灵 UI 与通知
ink/	Ink 渲染封装
native-ts/	原生相关 TS 工具
constants/	产品常量、prompt 片段、查询来源等
moreright/	内部/实验相关模块（视构建门控而定）

---

三、核心运行时路径（深入）

3.1 入口 entrypoints/cli.tsx 与 main.tsx

• 设计目标 ：非交互快速路径（如 --version）尽量少加载模块；其余路径再拉取启动分析、配置、完整 CLI。

• 典型分支：

  • --dump-system-prompt：渲染并输出系统 prompt（评估/调试，常由 feature('DUMP_SYSTEM_PROMPT') 门控）。

  • --claude-in-chrome-mcp / --chrome-native-host：Chrome 集成相关子进程入口。

  • --computer-use-mcp：CHICAGO_MCP 门控下的计算机使用 MCP。

  • --daemon-worker：DAEMON 门控下由 supervisor 拉起的 worker。

  • remote-control / rc / remote / sync / bridge：在 BRIDGE_MODE 下进入桥接服务形态。

• 环境适配 ：例如 CLAUDE_CODE_REMOTE 为真时为子进程设置更大 Node 堆上限，避免容器内 OOM。

3.2 查询引擎 query.ts、QueryEngine.ts 与 query/ 子模块

• 角色 ：连接「用户/模型消息」与「工具执行结果」的主循环：发起 API 请求、处理流式事件、在工具调用与文本回复之间迭代直至回合结束或中止。

• 文件分工：

  • QueryEngine.ts 承载流式解析、重试、thinking、token 与工具循环的主体实现。

  • query.ts 作为管线入口与大量协作模块的衔接层。

  • query/ 目录提供 config、deps、stopHooks、tokenBudget 等子模块。

• 协作模块：

  • 压缩 ：services/compact（自动压缩、buildPostCompactMessages）。

  • 附件与记忆 ：utils/attachments、相关 memory prefetch。

  • 工具 ：StreamingToolExecutor、runTools、工具结果预算。

  • 遥测 ：services/analytics 的 logEvent 等。

  • 消息工具函数 ：utils/messages（用户消息、中断、规范化等）。

• query/config.ts --- QueryConfig ：每次 query() 入口快照不可变配置 （如 sessionId），gates 来自 Statsig 缓存门控与环境变量，与 feature() 编译期门控刻意分离。

3.3 工具编排 services/tools/toolOrchestration.ts

• runTools ：将一轮中的多个 tool_use 块按是否可并发分区：

  • 可并发 （只读等）：在上限内并行执行，并合并对 ToolUseContext 的延迟修改。

  • 不可并发：串行执行，保证写操作顺序与副作用可预测。

• 与 hooks/useCanUseTool 的 CanUseToolFn 结合，实现每次调用前的权限决策。

3.4 工具注册 tools.ts 与 tools/*

• 静态核心工具：Bash、文件读写/编辑、Glob、Grep、Notebook、WebFetch/WebSearch、LSP、MCP 资源读写、Agent、Skill、Plan/Worktree、Task 系列、Todo、AskUserQuestion、Config 等。

• 条件加载：

  • SleepTool、Cron*、RemoteTriggerTool、MonitorTool 等与 PROACTIVE / KAIROS / AGENT_TRIGGERS 相关。

  • REPLTool、SuggestBackgroundPRTool 等 Ant 内部 （USER_TYPE === 'ant'）。

  • WorkflowTool 在 WORKFLOW_SCRIPTS 下初始化 bundled workflows。

  • coordinatorMode 在 COORDINATOR_MODE 下参与协调器工具策略。

• 设计模式 ：通过 require + feature() 避免循环依赖，并在发布构建中剔除未启用代码路径。

---

四、命令系统 commands/

用户通过 / 斜杠命令触发的功能均落在此树。可按主题归类如下：

4.1 会话与工作区

• session：会话相关 UI/逻辑

• resume / rewind：恢复与回溯

• share：会话分享

• add-dir：附加工作目录

• context / ctx_viz：上下文查看与可视化

• compact：手动压缩上下文

4.2 版本控制与评审

• commit / commit-push-pr：提交与推送 PR 流程

• diff：查看变更

• review / security-review / pr_comments：代码评审与 PR 评论

• branch / rename / tag：分支与标签类辅助

4.3 配置、模型与主题

• config / model / theme / output-style / color

• permissions：权限模式相关界面

• keybindings：快捷键配置

• rate-limit-options / reset-limits / mock-limits：限额与测试

4.4 认证与账户

• login / logout / oauth-refresh

4.5 MCP、插件、技能

• mcp：MCP 服务器管理

• plugin / reload-plugins：插件与子命令分页等

• skills：技能管理

4.6 记忆与任务

• memory：持久记忆 UI

• tasks：任务列表与管理

4.7 环境与健康

• doctor：环境诊断

• upgrade / version / release-notes

• install / onboarding / terminalSetup

• remote-env / remote-setup / bridge：远程与桥接相关命令

4.8 编辑器与模式

• vim：Vim 模式切换与说明

• voice：语音相关命令

• ide：IDE 集成辅助

4.9 遥测、调试与内部

• stats / usage / cost / extra-usage

• debug-tool-call / heapdump / perf-issue

• ant-trace / bughunter / good-claude 等内部或实验向命令

---

五、服务层 services/（深入）

子模块	功能要点
api/	Anthropic API 客户端、重试、错误类型、上传、与主循环对接的 fetch 封装等
oauth/	OAuth 2.0 登录流程与 token 生命周期
mcp/	MCP 连接、工具与资源枚举、与 MCPTool 协同
lsp/	语言服务器进程管理与 LSP 请求封装
compact/	对话压缩算法与自动压缩策略
analytics/	GrowthBook、Datadog、一方向事件日志、metadata、kill switch
plugins/	PluginInstallationManager、CLI 命令扩展、插件操作
policyLimits/	组织策略与用量上限
remoteManagedSettings/	云端统一下发的设置
teamMemorySync/	团队记忆同步与密钥守卫
extractMemories/	从对话中抽取记忆条目
toolUseSummary/	对 tool 结果生成摘要，减少上下文体积
tools/	StreamingToolExecutor、toolOrchestration、toolExecution 等执行管线
voice.ts / voiceStreamSTT.ts	语音开关、流式语音识别
preventSleep.ts / awaySummary.ts	防止休眠、离开摘要
claudeAiLimits*	AI 限额钩子与测试模拟

---

六、桥接与远程 bridge/、remote/、server/

6.1 bridge/

• 目标 ：让 IDE 扩展 （VS Code、JetBrains 等）与本地 CLI 双向通信：同步选区、发起会话、权限回调、REPL 桥接。

• 关键文件：

  • bridgeMain.ts：主循环、退避重连、会话生成与销毁，涵盖错误分类、容量唤醒等生产细节。

  • bridgeMessaging.ts / inboundMessages.ts：消息协议。

  • replBridge.ts / initReplBridge.ts：REPL 与桥的衔接。

  • jwtUtils.ts：令牌刷新调度。

6.2 remote/

• RemoteSessionManager、SessionsWebSocket：远程会话生命周期与实时通道。

• remotePermissionBridge：远程场景下的权限桥接。

• sdkMessageAdapter：SDK 消息形态适配。

6.3 server/

• directConnectManager、createDirectConnectSession：直连会话创建与管理（配合远程/桌面产品形态）。

---

七、协调器模式 coordinator/coordinatorMode.ts

• 开关 ：feature('COORDINATOR_MODE') 且环境变量 CLAUDE_CODE_COORDINATOR_MODE 为真时进入协调器模式。

• 职责：

  • 定义协调器场景下允许的工具集合 与禁止/内部工具边界。

  • matchSessionMode：恢复会话时若当前模式与存储不一致，自动同步环境变量并打 analytics 事件。

  • getCoordinatorUserContext：向系统/用户上下文注入协调器专用说明。

---

八、任务系统 tasks/

• LocalShellTask：在本地 shell 中执行命令，含 guard、kill 逻辑。

• LocalAgentTask：本地代理子任务 UI/状态。

• LocalMainSessionTask：主会话任务抽象。

• DreamTask ：与 services/autoDream 等相关的后台/自动任务形态。

• 与 tools 中的 Task 系列及 hooks/useTasksV2 等联动，形成「计划---执行---可查询」的任务闭环。

---

九、记忆系统 memdir/

• memdir.ts ：MEMORY.md 入口内容截断（行数与字节双上限）、与自动记忆路径、getMemoryFiles 等 prompt 构建共享逻辑。

• paths.ts / memoryScan.ts / findRelevantMemories.ts：记忆文件布局、扫描与检索。

• teamMemPaths.ts / teamMemPrompts.ts ：团队记忆（TEAMMEM feature）路径与 prompt 片段。

• memoryTypes.ts：frontmatter 与说明文档结构约定。

记忆内容经 context.ts / utils/claudemd 等进入系统 prompt，与 /memory 命令及自动抽取服务共同构成长期上下文。

---

十、技能系统 skills/

• loadSkillsDir.ts：从用户/项目目录加载技能定义。

• bundled/ ：内置技能实现（如 batch、debug、simplify、verify、scheduleRemoteAgents、claudeInChrome、keybindings 等），由 bundledSkills.ts / bundled/index.ts 聚合。

• mcpSkillBuilders.ts：从 MCP 能力构建技能相关结构。

• 执行路径上通过 SkillTool 与模型 tool_use 对接，使用户可扩展可复用工作流。

---

十一、插件系统 plugins/

• builtinPlugins.ts / bundled/：内置与打包插件入口。

• 与 services/plugins、commands/plugin、hooks/useManagePlugins 等配合：安装、更新、推荐、与 MCP/LSP 能力的交叉提示。

---

十二、表现层与交互

12.1 components/ 与 screens/

• Ink 组件：消息列表、输入、确认框、进度、主题色与布局。

• Screens：Doctor、全屏 REPL、Resume 等大界面，减少主界面复杂度。

12.2 context/

集中放置 跨组件 的 React Context：通知、邮箱、语音、统计、FPS、遮罩、prompt 覆盖、队列消息等。

12.3 hooks/

• 输入与导航 ：useTextInput、useVimInput、useArrowKeyHistory、useCommandQueue 等。

• IDE ：useIDEIntegration、useIdeSelection、useDiffInIDE 等。

• 权限 ：useCanUseTool 与 hooks/toolPermission/*。

• 业务 ：useRemoteSession、useDirectConnect、useVoice、useSwarmInitialization 等。

12.4 keybindings/、vim/、voice/

• 快捷键解析与默认绑定；Vim 动作状态机；语音采集与识别服务衔接。

12.5 buddy/

终端内「伴侣」形象与轻量互动（精灵图、通知 hook）。

---

十三、状态、配置与类型

• state/AppStateStore：MCP 入口等使用的默认应用状态。

• schemas/ + migrations/：配置演进与校验。

• types/：消息模型、权限、hooks、生成的事件 proto 类型等。

• bootstrap/state.ts：会话级全局片段（如 session id、CLAUDE.md 缓存）。

• utils/config.js：配置启用与合并。

---

十四、上游代理 upstreamproxy/

面向 CCR（容器化远程会话） 场景：

• 读取 /run/ccr/session_token，加固进程（如限制 dumpable），下载并合并上游 MITM CA，启动 CONNECT→WebSocket relay ，设置 HTTPS_PROXY / SSL_CERT_FILE。

• 失败开放：任何一步出错应记录警告并禁用代理，避免拖垮主功能。

---

十五、CLI 子系统 cli/

• 传输 ：transports/SSETransport、WebSocketTransport、HybridTransport、ccrClient、WorkerStateUploader、SerialBatchEventUploader 等------支撑远程 worker、状态上报与流式事件。

• 结构化 I/O ：structuredIO.ts、ndjsonSafeStringify.ts、print.ts------便于脚本化与机器可读输出。

• handlers ：auth、mcp、agents、plugins、autoMode、util 等子命令实现。

• update.ts / exit.ts / remoteIO.ts：更新检查、退出码约定、远程环境下的 I/O 适配。

---

十六、入口：MCP 服务器 entrypoints/mcp.ts

• 使用 @modelcontextprotocol/sdk 创建 stdio MCP Server （名称如 claude/tengu）。

• 暴露注册表中的工具，并与内置 MCP 命令（如 review）结合；包含权限检查、setCwd、文件状态 LRU 缓存等长驻进程注意事项。

---

十七、SDK 类型 entrypoints/sdk/*

• coreTypes、coreSchemas、controlSchemas：对外或内部 SDK 控制的类型与 schema，与 agent SDK 类型文件共同约束程序化驱动 CLI 时的消息格式。

---

十八、权限体系（横切）

• 工具级 ：utils/permissions、hooks/useCanUseTool、hooks/toolPermission/handlers/* --- 根据模式（default / plan / bypass / auto 等）决定提示、自动允许或拒绝。

• 文件系统 ：utils/permissions/filesystem 等与 .gitignore、沙箱路径、scratchpad 门控结合。

• 桥接/远程 ：bridge 与 remotePermissionBridge 将权限决策延伸到 IDE 或远程 UI。

---

十九、遥测与特性开关（横切）

• GrowthBook / Statsig ：门控功能与实验分组；部分 gate 在 QueryConfig 等处单次查询快照以避免行为抖动。

• Datadog / 第一方日志 ：services/analytics 下 sink 与 exporter；关闭时走 kill switch。

• bun:bundle feature()：编译期剔除大块代码（VOICE、DAEMON、BRIDGE、MONITOR_TOOL 等），减小发布体积与攻击面。

---

二十、核心大文件说明（维护者视角）

文件	典型职责
QueryEngine.ts	流式解析、重试、thinking、token、与工具循环的完整状态机（体量最大）
query.ts	查询管线入口及与压缩、附件、工具编排、遥测等的协作
Tool.ts	所有工具的共有类型、权限上下文、findToolByName 等
tools.ts	工具列表组装与条件导出
commands.ts	命令注册总表与条件加载
main.tsx	Commander 命令树与 Ink 根渲染启动

---

二十一、数据流小结（一次用户发送消息后）

1. 输入层 解析用户文本或粘贴、附件引用；斜杠命令可走 commands 快捷路径。

2. 上下文组装 ：context.ts、memdir、utils/messages、attachments 等拼出用户可见上下文与系统提示片段。

3. query() 调用 API，消费 SSE/流式 事件；若出现 tool_use ，经权限检查进入 runTools（并发或串行）。

4. 工具结果写回消息列表；必要时触发 compact 或 tool use summary；继续下一轮直到模型停止或用户取消。

5. UI 通过 Ink 组件与 Context/Hooks 刷新；IDE/远程通过 bridge/remote 同步状态。

---

二十二、阅读源码的建议顺序

1. entrypoints/cli.tsx → main.tsx → entrypoints/init.ts

2. query.ts 主循环 + services/tools/toolOrchestration.ts

3. tools.ts + 任选 tools/BashTool、tools/FileReadTool 作为模板

4. hooks/useCanUseTool.tsx + hooks/toolPermission/

5. commands/help 或 commands/init 了解命令注册方式

6. bridge/bridgeMain.ts（需耐心：含网络与会话全生命周期）