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

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

一、项目定位与技术栈

1.1 产品定位

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

1.2 技术栈摘要

1.3 架构分层（逻辑视图）

┌─────────────────────────────────────────────────────────────┐│  入口层 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/ 下一级目录（及少量根级核心文件）的职责摘要。

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

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/（深入）

六、桥接与远程 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:bundlefeature()：编译期剔除大块代码（VOICE、DAEMON、BRIDGE、MONITOR_TOOL 等），减小发布体积与攻击面。

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

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

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（需耐心：含网络与会话全生命周期）