深度解读：从源码架构透视 Claude Code 的 Agentic CLI 范式

背景

在 AI 辅助开发的浪潮中，Anthropic 推出的 Claude Code 代表了从传统命令行工具向智能化代理（Agent）演进的重要一步。近期，GitHub 上出现了一个针对 Claude Code 泄露源码进行分析的项目（Claude Code from Source），该项目由 Anthropic 工程师 Alejandro Balderas 与 AI 合著，其封面设计充满了对开源文化与 AI 协作的隐喻。

传统的命令行界面（CLI）本质上是确定性的函数调用，如 grep 或 curl，执行即结束，缺乏上下文感知与自主决策能力。而 Agentic CLI 的出现改变了这一格局。它不再是一串固定的指令，而是围绕大语言模型（LLM）运转的循环系统。模型能够根据自然语言描述，自主决定调用哪些工具、以何种顺序执行，并通过反馈闭环直到任务完成。

Claude Code 正是这一理念的工程化实现。作为一个基于 TypeScript 的单体应用，它将终端转化为一个由 Claude 驱动的全功能开发环境。本文基于对 Claude Code 源码架构的分析，深入解读其底层的六种核心心智模型与抽象机制，揭示其如何构建出一个既灵活又可控的 AI 编程代理。

核心内容

Claude Code 的架构建立在六个核心抽象之上：Query Loop（查询循环）、Tool System（工具系统）、Tasks（任务）、State（状态）、Memory（记忆）和 Hooks（钩子）。其余数百个工具函数、终端渲染器及 Vim 模拟器等组件，均服务于这六大抽象。以下重点解析前四个核心抽象。

1. Query Loop：系统的统一异步生成器

Query Loop 位于 query.ts 文件中，约 1700 行代码，是整个系统的核心引擎。它是一个异步生成器（Async Generator），负责处理所有类型的交互入口，包括 REPL、SDK 调用、子代理（sub-agent）以及无头模式（--print）。

运行机制

无论输入来源如何，所有请求最终都汇入同一个 query() 方法。其核心逻辑是一个持续运行的循环：

1. 调用模型。
2. 接收流式响应。
3. 收集工具调用指令。
4. 执行工具。
5. 将工具执行结果追加回上下文。
6. 进入下一轮循环。

这种设计类似于快递分拣中的自动化集装箱，机械臂（Agent）实时处理包裹（Event），一边执行一边输出。

事件流与渲染

模型产生的原始事件（Event）无法直接展示给用户，需要经过 Agent 层的渲染与包装。以 claude -p 的输出为例，事件流包含以下关键节点：

• system/init：会话初始化，包含工作目录、Session ID、可用工具列表及模型信息。
• system/status：状态更新，如 requesting 表示开始请求模型。
• stream_event：流式事件，包括 message_start（开始）、content_block_delta（文本块增量，即实时打字效果）和 message_delta（消息结束）。
• assistant：SDK 整理后的助手消息对象。
• result：最终结果，包含 stop_reason（停止原因）。

异步生成器的三大优势

采用 async generator 而非普通回调或同步阻塞，带来了显著的工程优势：

1. 输出节奏可控：通过 for await 逐段消费事件，避免了因终端渲染速度慢导致的消息积压。
2. 即时中断响应：当用户按下 Ctrl+C 或外部取消请求时，生成器能立即停止产出事件，并沿执行链路进行清理，防止后台任务“僵尸化”。
3. 明确的停止语义：最终输出的 result 消息中携带 stop_reason，清晰区分是用户取消、工具失败还是系统异常，便于上层逻辑做出正确决策。

2. Tool System：流式调度与权限控制

工具系统是 Agent 在计算机世界中执行操作的能力边界，源码分布在 Tool.ts、tools.ts 及 services/tools/ 中。每个工具都实现了涵盖身份、模式、执行、权限和渲染的丰富接口。

工具执行器与并发策略

工具执行器负责实际运行 Read、Write、Bash、Grep 等操作。系统根据工具的特性区分串行与并发执行：

• 并发安全：如读取文件，可并行执行以提升效率。
• 状态敏感：如写入文件或修改系统状态的命令，必须串行执行以避免冲突。

流式调度器（Streaming Scheduler）

这是工具系统的高级优化机制。它允许在模型尚未完整输出完指令前，提前启动某些工具。例如，当模型刚刚输出 Read 调用时，若该操作被判定为并发安全，调度器即可立即启动文件读取。此时模型仍在生成后续指令，但读取操作已在后台完成，从而显著降低延迟。

3. Tasks：子代理与递归能力

Tasks 抽象位于 Task.ts 及相关目录，主要用于承载后台执行单元和子代理（sub-agent）。

子代理的生命周期

每个 sub-agent 拥有独立的状态机：pending（等待） -> running（运行） -> completed | failed | killed（完成/失败/被杀）。

递归代理架构

当 Claude Code 需要执行复杂任务时，会 fork 出一个 sub-agent。

• 父代理与子代理：fork 出 sub-agent 的称为父 Agent。sub-agent 虽然复用同一套 query loop 逻辑，但拥有独立的上下文、工具集合和权限模式。
• 递归能力：这种设计赋予了系统递归代理的能力，即一个 Agent 可以委派给另一个 Agent，后者还可继续向下委派。

安全红线：Bubble 模式

递归代理带来了失控风险。为防止子代理执行危险操作，系统引入了 bubble 模式。当 sub-agent 遇到敏感动作时，不能自行批准，必须“冒泡”上报给父 Agent 或用户进行决策。这是多 Agent 系统中至关重要的安全机制。

4. State：双层状态管理

Claude Code 的状态管理分为两层，分别服务于系统逻辑与用户界面。

第一层：会话级状态（STATE）

这是一个可变单例对象，保存约 80 个会话级基础字段。当用户打开一个新的终端窗口时，即创建一个新的 Session。该状态包括：

• 当前工作目录（cwd）
• 当前使用的模型
• Session ID
• 成本追踪与 Token 用量
• 当前权限模式

启动时初始化，运行中直接修改，系统模块按需读取。

第二层：UI 界面状态

由 React 框架下的状态管理库 Zustand 驱动，负责同步用户界面的变化。包括：

• 新消息的到来
• 输入模式的切换
• 等待用户批准工具调用的状态
• 进度条更新
• 模型正在输出的状态

通过 Zustand 的 create 和 set 方法，UI 状态能够高效地响应底层逻辑的变化，确保前端展示的实时性与一致性。

关键要点

• Agentic CLI 范式：Claude Code 并非传统 CLI 的简单封装，而是基于大语言模型的反馈闭环系统，具备自主决策、工具调用和上下文记忆能力。
• 统一入口设计：所有交互模式（REPL、SDK、子代理等）均汇入统一的 query() 异步生成器，实现了逻辑收敛与资源复用。
• 异步生成器的工程价值：相比传统回调，async generator 提供了更好的背压控制、即时中断响应机制以及明确的终止语义（stop_reason）。
• 流式工具调度：通过 流式调度器，系统能在模型输出未完成时提前执行并发安全的工具（如读取文件），显著优化交互延迟。
• **递归代理