Claude Code 代码架构
这一页拆解 Claude Code 的代码架构：分层设计、各模块职责、关键组件如何协作。内容综合官方行为与社区逆向白皮书，重在帮你建立「一个生产级编程 Agent 是怎么搭起来的」整体认知。功能总览见 功能总览，运行机制见 核心机制。
提示：具体文件名/类名来自社区逆向分析，可能随版本变化；这里用它们来说明职责划分，不必当作官方 API。
一、分层架构全景
Claude Code 大致可分为这样几层（自上而下）：
┌─────────────────────────────────────────────┐
│ 入口层 (CLI) 启动、参数解析、运行时初始化 │
├─────────────────────────────────────────────┤
│ 交互层 (REPL) React/Ink 终端 UI，输入→消息 │
├─────────────────────────────────────────────┤
│ 编排层 (Orchestrator/QueryEngine) │
│ 回合生命周期、token 预算、 │
│ 上下文压缩触发、会话持久化 │
├─────────────────────────────────────────────┤
│ Agentic Loop 核心 组织上下文→调 API→解析工具 │
│ 调用→权限检查→执行→递归 │
├─────────────────────────────────────────────┤
│ 工具执行层 文件/命令/搜索/任务/子 Agent │
├─────────────────────────────────────────────┤
│ 通信层 流式 HTTP，多后端适配 │
│ (Anthropic/Bedrock/Vertex) │
└─────────────────────────────────────────────┘
↕ 横切：权限、Hooks、MCP、配置、遥测每一层职责单一、向下依赖，横切关注点（权限、Hooks、MCP、配置）贯穿各层。
二、各层职责详解
入口层（CLI）
负责进程启动：解析命令行参数（交互模式 / -p 管道模式 / 各种 flag）、初始化运行时、加载配置与项目记忆。终端 Agent 的「main 函数」。
交互层（REPL）
用 React + Ink（终端里的 React 渲染器）构建交互式 UI：捕获用户输入封装成 UserMessage、流式渲染模型输出（打字机效果）、展示工具调用与权限询问。把「终端」做成了一个响应式界面。
编排层（Orchestrator / QueryEngine）
整个会话的「指挥中枢」：
- 管理多轮对话的回合生命周期；
- 维护 token 预算（如 200K 窗口的动态计算），决定何时截断/压缩；
- 触发上下文压缩（compaction）；
- 会话持久化（把对话记成 JSONL transcript，支持恢复、成本追踪）。
Agentic Loop 核心
决策引擎，整个系统的心脏（详见 核心机制）：组织上下文 → 调模型 API → 解析模型返回的工具调用 → 权限检查 → 执行工具 → 把结果喂回 → 再调，循环至完成。支持并行工具执行、流式、错误恢复。
工具执行层
把模型的「意图」变成「真实操作」：
| 工具类 | 代表 | 要点 |
|---|---|---|
| 文件操作 | Read / Edit / Write | 去重缓存、精确替换、原子写 |
| 搜索导航 | Glob / Grep | 基于 ripgrep，快速代码检索 |
| 命令执行 | Bash | 只读检测、AST 解析、输出截断 |
| 任务管理 | TodoWrite / Task | 内存待办 + 文件系统子任务双轨 |
| 子 Agent | Task / AgentTool | 派生子 Agent，独立上下文 |
通信层
流式 HTTP 调用模型 API，封装多后端适配（Anthropic / Bedrock / Vertex 等），处理 SSE token 流、重试、鉴权。
三、横切关注点（贯穿各层）
- 权限系统：Allow/Ask/Deny 三级 + 多层规则优先级，插在「工具执行前」（见 核心机制 - 权限）。
- Hooks：在工具调用前后等生命周期点注入用户脚本，可拦截/校验。
- MCP：通过 MCP 协议 接入外部工具，内置 + 外部多种传输。
- 配置系统：用户级 / 项目级 / 企业级配置合并；项目记忆 CLAUDE.md。
- 遥测与特性开关：错误上报、A/B 实验、feature flags 控制功能灰度。
四、为什么这样设计？（架构动机）
| 设计 | 解决的问题 |
|---|---|
| 分层 + 单一职责 | 复杂 Agent 可维护、可测试、可替换组件 |
| 编排层独立于 Loop | token 预算/压缩/持久化和决策逻辑解耦 |
| 工具层抽象统一 | 新增工具只需注册，模型用同一套调用协议 |
| 多后端适配层 | 一套代码对接不同模型供应商 |
| 横切的权限/Hooks | 安全和工程约束不侵入业务逻辑 |
这套架构是「生产级编程 Agent 的参考实现」——它要解决的工程问题（长任务上下文、并行工具、权限安全、可扩展）在任何严肃的 Agent 系统里都会遇到。
高频追问
Q：Claude Code 为什么用 React/Ink 做终端 UI？ Ink 是「终端里的 React」，让复杂的交互式终端界面（流式输出、工具调用展示、权限询问、可滚动历史）能用组件化、声明式的方式构建和维护，比手写 ANSI 控制码可维护得多。
Q：编排层（QueryEngine）和 Agentic Loop 是一回事吗？ 不是。Loop 是「决策—执行」的核心循环（这一步调什么工具）；编排层在它之外，管会话级的事务：token 预算、何时触发上下文压缩、回合生命周期、把对话持久化成 transcript、成本追踪。一个管「单步决策」，一个管「整场会话」。
Q：工具是怎么接进来的？ 工具有统一的类型定义和注册机制；每个工具声明名称、参数 schema、执行逻辑、权限要求。模型通过 Function Calling 输出「调用哪个工具+参数」，框架查注册表、校验权限、执行、回传结果。新增工具只要按协议注册即可，模型不用改。
Q：这套架构对我自己做 Agent 有什么借鉴？ 关键经验：① 把「单步决策的 loop」和「会话级编排（预算/压缩/持久化）」分层；② 工具用统一注册+调用协议；③ 权限/Hooks 作为横切关注点插在执行前，不污染主逻辑；④ 通信层抽象多后端。这些是任何生产级 Agent 都要面对的工程问题。