基于2026年3月泄露的51.2万行TypeScript源码（v2.1.88），Claude Code 不是简单的LLM包装器，而是一套分层Agent操作系统，核心是QueryEngine异步状态机+多Agent分工+流式工具执行+多层安全/上下文压缩。以下从源码结构、核心引擎、工具系统、Agent架构、记忆/上下文、安全与工程细节六个维度做完整拆解，重点深入QueryEngine异步状态机的工作原理，读懂它的核心逻辑。

一、源码目录与核心文件概览

1.1 整体目录结构（src/）

asrc/

├── main.tsx

CLI入口，React+Ink渲染终端UI，Commander.js解析命令

├── query/

核心查询引擎（QueryEngine，约4.6万行，系统大脑）

│   ├── QueryEngine.ts

主引擎：会话编排、流式循环、工具调度、重试、Token计数

│   ├── query.ts

回合级异步状态机（async generator，TAOR循环）

│   └── context.ts

上下文压缩、折叠、裁剪、摘要管道

├── tools/

工具系统（47+原生工具，工厂模式）

│   ├── Tool.ts

工具基类/接口（Zod校验、权限、并发安全）

│   ├── factory.ts

工具注册、延迟加载、ToolSearch动态发现

│   ├── BashTool.ts

Bash执行（沙箱、安全过滤）

│   ├── FileRead/Edit.ts

文件读写、diff、原子替换

│   ├── GitTool.ts

Git状态、diff、log、commit

│   └── WebSearch.ts

联网搜索、内容抓取

├── agents/

多Agent分工系统（Plan/Explore/Verify等）

│   ├── coordinator.ts

Agent调度器，任务拆解、子Agent分配、结果聚合

│   ├── PlanAgent.ts

只读规划：拆解任务、输出步骤、识别依赖

│   ├── ExploreAgent.ts

只读探索：Glob/Grep/FileRead，不写文件

│   └── VerifyAgent.ts

验证：编译、测试、lint、结果校验

├── services/

外部服务层

│   ├── api/claude.ts

Claude LLM API调用、SSE流式解析、Token计费

│   ├── ide-bridge.ts

VS Code/JetBrains双向通信（JWT认证、LSP）

│   └── memory.ts

全局/项目/本地三级记忆持久化

├── commands/

1.2 核心文件规模（关键）

QueryEngine.ts：

46,000 + 行 → 会话级编排、流式循环、工具调度、重试、上下文管理、Token 统计

Tool.ts：

29,000 + 行 → 工具抽象、权限模型、输入校验、并发安全规则

commands.ts：

25,000 + 行 → 斜杠命令注册、执行、参数解析

main.tsx：

CLI 入口、React+Ink 渲染、REPL 主循环

二、核心引擎：QueryEngine 异步状态机（系统大脑）

设计范式：异步生成器（async generator）+ TAOR 循环

核心是回合制异步状态机，基于async function*实现，每一轮是完整的Think-Act-Observe-Repeat (TAOR)循环，而非一次性调用 LLM。它不是简单的 “发请求→等回复”，而是一套永不停止、自我驱动、可中断、可恢复、可流式执行的异步状态循环系统。

极简代码模型（模拟源码核心逻辑）：5 个固定状态 + 1 个无限循环。

状态 1：IDLE（空闲）

等待用户输入。

状态 2：PREPARE（准备）

做三件事：

上下文压缩

自动折叠、裁剪、摘要历史，控制 token 不爆炸

动态组装 Prompt

把系统指令、记忆、工具、历史、代码全部拼成最优请求

Token 预算检查

超了就自动压缩，绝不触发模型长度限制

状态 3：THINK（思考）

调用 LLM，流式接收推理内容

实时输出思考过程

实时解析工具调用（tool_use）

不等待全部生成，边生成边调度

状态 4：ACT（执行）

这是状态机最强大的地方：

解析 LLM 想调用的工具

并发调度

：只读并行，写操作串行

流式执行文件读写、bash、搜索、git

执行过程实时 yield 进度给 UI

状态 5：OBSERVE（观察）

收集工具执行结果

错误处理：失败→重试→回滚→提示用户

把结果注入上下文，准备下一轮

回到 → REPEAT（循环）

状态机自动跳回THINK，开始下一轮推理。

三、工具系统：47 + 原生工具，工厂 + 权限 + 延迟加载

3.1 工具抽象接口（Tool.ts，核心）

所有工具继承统一基类，强制实现：

interfaceTool{

name:string;// 工具名（如file_edit）

description():string;// 短描述（注入LLM tool schema，Token敏感）

prompt():string;// 详细指令（走缓存，不计入每次Token）

inputSchema:ZodSchema;// Zod校验输入，防止注入

checkPermissions():boolean;// 权限检查（读写、高危操作）

isReadOnly():boolean;// 只读标记（Explore/Plan Agent专用）

isConcurrencySafe():boolean;// 并发安全标记（决定并行/串行）call(args:Input,context:Context):Promise

;// 执行入口}

3.2 三大设计亮点（Token 优化 + 安全 + 效率）

延迟加载 + ToolSearch 动态发现

权限沙箱（安全核心）

并发调度（toolOrchestration.ts）

四、多 Agent 架构：分工协作，而非单体模型

4.1 6 大核心 Agent

Plan Agent（只读）

：理解需求、探索代码库、拆解子任务树、输出执行步骤、识别关键文件 / 依赖 → 不写文件、不执行命令

Explore Agent（只读）

：Glob/Grep/FileRead、分析项目结构、提取接口 / 函数定义 → 纯探索、无写权限，避免污染上下文

Execute Agent（读写）

：调用 FileEdit/Bash/Git，执行代码编写、修改、构建、测试 → 唯一拥有写权限的核心 Agent

Verify Agent（只读）

：编译、lint、单元测试、diff 校验、结果验证 → 检查 Execute 输出是否符合预期、有无语法错误

Guide Agent

：交互引导、解释步骤、提示用户确认、处理异常

Coordinator（调度中枢）

：接收用户指令→分配给 Plan→Explore→Execute→Verify→聚合结果→决定是否进入下一轮 / 终止

4.2 协作流程（任务拆解→分工→聚合）

用户指令 → Coordinator → Plan Agent（生成任务树） → Explore Agent（探索代码库） → Execute Agent（执行工具） → Verify Agent（验证） → Coordinator（判断完成/继续） → 输出结果

核心价值：解耦规划 / 探索 / 执行 / 验证，避免单体模型 “既要又要” 导致的推理混乱、错误率高

五、记忆与上下文：三级持久化 + 动态压缩

5.1 三级记忆系统（Markdown 持久化，可编辑）

Global Memory（~/.claude/Claude.md）：

全局偏好、编程风格、常用命令、工具别名

Project Memory（项目根 / Claude.md）：

项目架构、技术栈、构建脚本、测试命令、团队规范

Local Memory（项目 / Claude.local.md）：

本地 IDE 配置、临时偏好、Git 用户名 → 不提交 Git

5.2 上下文压缩管道（context.ts，Token 生命线）

层级压缩：消息级（裁剪）→ 块级（折叠）→ 对话级（摘要）→ 项目级（记忆注入）

智能保留：优先保留代码 diff、函数定义、错误日志、关键工具结果；裁剪自然语言闲聊、重复说明

Token 预算：动态计算每轮 Prompt Token，接近上限时自动触发压缩，确保不触发 LLM 长度限制

六、安全、工程与隐藏机制（源码彩蛋）

6.1 安全体系（多层防护）

权限网关：工具权限与 Agent 绑定（Explore/Plan 只读，Execute 可写）

Bash 沙箱：命令白名单、路径限制、禁止高危系统调用、输出过滤

输入校验：所有工具输入走 Zod Schema，防止路径穿越、命令注入、SQL 注入

用户确认：文件覆盖、删除、批量修改、网络请求必须显式确认（Auto Mode 例外）

6.2 隐藏机制（源码泄露亮点）

autoDream（梦境引擎）：后台记忆整合，满足 “24 小时 + 5 会话 + 整合锁” 时触发，合并长期记忆、清理冗余、生成项目摘要 → 提升长期上下文一致性

KAIROS（持久在线模式）：后台常驻、主动监控 Git/PR/ 文件变化、推送通知、主动建议优化 → 无需用户触发，主动工作

IDE Bridge：VS Code/JetBrains 双向通信，支持代码高亮、跳转、实时 diff、LSP 集成 → 深度融入开发工作流

6.3 技术栈与工程细节

运行时：Bun（比 Node 更快、更小、内置 TS）

UI：React + Ink（终端组件化、流式渲染、状态管理）

打包：单文件 bundle，所有依赖内置，无外部依赖

日志：结构化日志、错误追踪、性能监控、Token 计费统计

写在最后：核心总结与设计哲学

不是 LLM 包装器，而是 Agent OS：以 QueryEngine 为中枢，工具、Agent、记忆、安全全栈解耦，LLM 仅做推理决策，不控制循环

Token 效率优先：延迟加载、动态压缩、描述 / 提示分离、缓存，把 Token 成本压到最低

安全与可控：权限隔离、用户确认、只读 Agent、沙箱，平衡自动化与风险

工程化极致：TypeScript 强类型、异步生成器、流式执行、并发调度、持久化记忆，支撑复杂长任务