魔神公寓
94.55M · 2026-04-07
很多开发者在使用 Claude Code 时，会觉得它和 ChatGPT、Copilot 用起来"感觉不一样"——响应更快、操作更稳、很少卡死或胡说。这背后不是模型能力的差距，而是工程化深度的差距。
最近深入分析了 Claude Code 的底层架构（参考 Anthropic 官方 PPT 及架构图），我把核心发现整理成这篇文章。如果你正在构建 AI Agent、大模型工具链，或者只是想理解"一个生产级 AI 系统到底长什么样"，这篇文章值得细读。
核心结论：AI Agent 的竞争力不仅在模型能力上，更在工程化的深度上。
先来看一张对比表，它清晰地说明了 Claude Code 和 ChatGPT/Copilot 之间的本质差异：
| 维度 | Legacy Tools (ChatGPT / Copilot) | Claude Code | | --- | --- | --- | | 交互模式 | 对话与补全 | 自主 Agent 循环 | | 工具能力 | 无 / 极有限 | 47+ 内置工具，支持 MCP 扩展 | | 上下文管理 | 简单截断 | 5 层上下文压缩管道 | | 代码修改 | 输出代码片段 | 带有 AST 校验的直接文件系统编辑 | | 权限控制 | 无 | 3 层纵深防御 + LLM 分类器 | | 任务调度 | 单线程 | 多子 Agent 并发编排 |
这不是功能堆砌的差距，而是系统设计哲学的差距。Claude Code 从根本上把自己定义为一个端到端完整的 Agent 运行时系统，而不是一个"聊天框 + 代码高亮"。
Claude Code 的整体架构分为三层：
关键洞察：Claude Code 并非简单封装大模型 API，而是一个端到端的完整 Agent 运行时系统。大模型只是"大脑"，下面两层的工程化基础设施才是让它能真正干活的关键。
Claude Code 的主循环是一个基于 TypeScript Async Generator 实现的异步状态机，这是整个系统最核心的设计决策。
// Claude Code 主循环的简化示意
async function* agentLoop(state: AgentState): AsyncGenerator<AgentEvent> {
while (true) {
try {
// 发起模型推理请求
const response = await callModel(state.context);
// yield 中间事件：UI 渲染、SDK 流式输出
yield { type: 'model_response', data: response };
if (response.stopReason === 'tool_use') {
// 执行工具调用
const toolResult = await executeTools(response.toolUses);
yield { type: 'tool_result', data: toolResult };
// 更新状态，继续循环
state = updateState(state, toolResult);
continue;
}
// 达到终止条件，退出循环
return { status: 'completed', finalResponse: response };
} catch (error) {
// 内部错误恢复，防止循环崩溃
if (isRecoverable(error)) {
yield { type: 'error_recovery', data: error };
continue;
}
throw error;
}
}
}
这个设计带来三个关键架构优势：
消费端（UI 层）可以自主控制事件处理速率。当终端渲染来不及时，生成器会自然暂停，不会因为数据堆积导致内存爆炸。
yield 对应中间事件（流式输出、工具执行进度），return Terminal 对应最终状态。彻底分离了过程与结果，让 UI 层和 SDK 消费层的逻辑极度简洁。
用户按下 Ctrl+C 时，调用 generator 的 .return() 方法，可以直接终止所有嵌套的子 Generator，无需额外的取消信号传播机制。
终态分为四种：completed（正常完成）、aborted（用户取消）、max_turns（超出轮次限制）、prompt_too_long（上下文超限）。
传统 AI 工具的执行模式是串行的：等模型完整生成所有工具调用描述 → 依次执行工具 1、工具 2、工具 3。
Claude Code 用 StreamingToolExecutor（抢跑并发）彻底改变了这一模式：
三个核心机制：
Claude Code 内置 47+ 工具，覆盖文件读写、代码搜索、终端执行、网络请求、Git 操作等。工具调度的核心哲学是 Fail-Closed：
每个工具请求都经过一个 Dynamic Evaluation Node：
• 输入 ls -la → 评估为"并发安全" → 允许并行执行
• 输入 rm -rf → 评估为"独占风险" → 强制串行 / 阻断
两条核心工程哲学：
Must-Read-First Guard（强制先读后写）：模型在调用 Edit 工具修改文件之前，必须先调用 Read 工具证明"已经读过这个文件"。否则拒绝编辑操作。这从根本上防止了模型"盲改代码"。
陈旧写入检测（Stale Write Detection）：基于文件时间戳，拒绝对已被外部程序修改过的文件进行并发覆写，防止竞争条件导致数据损坏。
上下文管理是所有 AI Agent 的核心难题。Claude Code 没有简单截断，而是设计了一套分层递进的压缩漏斗：
设计原则：轻量操作优先，重量操作兜底。每一层都在尽量保留上下文价值的前提下减少 Token 消耗。只有前面几层都无法解决问题时，才触发代价高昂的 Auto Compact。
实践启示：在构建自己的 AI Agent 时，不要只在超限时才处理上下文，而是要在每一层请求前主动做预防性压缩。
当 API 返回 prompt-too-long 错误时，普通系统的处理方式是直接抛给用户。Claude Code 的处理链路完全不同：
这套机制实现了真正意义上的"自治（Autonomy）"：系统通过拦截底层错误并自主修复，在绝大多数情况下让用户感知不到任何异常。只有在系统真正无法恢复的情况下，才将错误暴露给用户。
Claude Code 能执行真实的文件系统操作，这意味着安全设计至关重要。它采用了三层同心圆防御：
核心工程哲学：通过静态规则过滤 80% 的请求，让 LLM 分类器只处理模棱两可的边界情况。这样既保证了安全性，又最大化了流畅度——不会动不动就弹出"你确定吗？"的确认弹窗。
每次 API 调用的成本，很大程度上取决于 Prompt 缓存命中率。Claude Code 将 Prompt Payload 分为两层：
锁存器防抖机制：状态变量一旦开启（如 FastMode = true），则永久锁定，不再切换。这防止了 Header 频繁切换导致整个高价值静态 Prompt 缓存失效。
工程价值：在长会话中，静态区的缓存命中可以将 API 成本降低 60-80%。
Claude Code 的状态管理用了一个反直觉的极简设计：34 行自定义状态管理器，核心是 useSyncExternalStore + DeepImmutable<T>。
// 34 行状态管理器的核心思路
// 无中间件，无时间旅行，只有极简的编译期不可变约束
type DeepImmutable<T> = {
readonly [K in keyof T]: T[K] extends object ? DeepImmutable<T[K]> : T[K];
};
const store = createExternalStore<DeepImmutable<AgentState>>(initialState);
长期记忆则完全外部化为文件系统：
~/.claude/
projects/
[hash]/
memory/
MEMORY.md ← 常驻上下文，25KB 限制
设计哲学：RAM 只保留当前会话状态，长期记忆外部化为 Markdown 文件。释放 RAM 的同时，利用标准 RAG 技能动态召回历史话题。这种设计让系统重启后能无缝续接上下文，且不依赖任何数据库。
Claude Code 有三种能力扩展模式，形成完整的 Coordinator-Worker 架构：
触碰特定文件类型时，自动挂载对应的 .md 技能文件。比如打开 .tsx 文件时，自动加载 React 最佳实践指令集。这本质上是上下文感知的动态 System Prompt 注入。
子 Agent 在临时创建的独立 Git Worktree 中执行危险操作，不污染主工作区。如果出错，直接丢弃 Worktree；如果成功，才合并回主干。
主 Agent 仅保留路由能力，将具体任务下发给挂载了特定工具集的 Worker 子 Agent。例如：
• 代码重构任务 → 派发给挂载了文件编辑工具的 Worker
• 网络调研任务 → 派发给挂载了搜索工具的 Worker
所有插件与核心能力同源共享，Agent 本身可以像调用工具一样生成子 Agent。
这是 Claude Code 中最具创意的设计之一——借鉴人类睡眠记忆整理机制：
工程价值：利用后台闲置算力提炼长期价值，保持主循环极致轻量。用户主动工作时不消耗任何资源；用户休息时，系统悄悄整理记忆，为下次交互做好准备。
综合以上分析，这是一份可以直接参考的 Agent 架构技术选型清单：
| 核心系统组件 | Claude 架构模式 | 推荐技术栈 | | --- | --- | --- | | 主循环设计 | Async Generator 状态机 | Bun（原生 TS，极致冷启动） | | 终端渲染 | 解耦中间事件流 | React-Ink（CLI 组件化） | | 工具调度 | 流式并发 + 默认 Fail-Closed | Zod（严格输入校验） | | 权限与安全 | AST 级拆解 + 轻量分类器兜底 | Tree-sitter（语法树解析） | | 文件读写 | 并发提取 + 搜索替换（非行号） | Ripgrep（子进程提速） |
// 坏实践：一次性读取整个文件
const content = fs.readFileSync(filePath, 'utf-8');
// 好实践：先搜索定位，再局部读取
const matches = await grep(pattern, filePath);
const content = await readLines(filePath, matches[0].line - 5, matches[0].line + 20);
在底层封装好行数限制（最多 2000 行），超出部分强制截断或要求分页读取。
// 坏实践：错误直接抛给用户
process.on('uncaughtException', (err) => console.error(err));
// 好实践：捕获错误，构造为下一轮的反馈上下文
try {
await executeTool(toolName, params);
} catch (error) {
// 将错误信息作为 Tool Result 返回给模型，让模型自我纠错
return {
success: false,
output: `工具执行失败。错误详情：${error.message}n建议：请检查参数格式或文件路径是否正确。`
};
}
将"大模型对话历史"和"本地工具执行状态"分离存储。前者是 AI 的记忆，后者是系统的状态机。混在一起会让"撤销操作"和"状态恢复"变得极度复杂。
import { z } from 'zod';
// 永远不要信任模型输出的参数格式
const EditToolParams = z.object({
filePath: z.string().min(1),
oldString: z.string().min(1),
newString: z.string(),
replaceAll: z.boolean().default(false),
});
// 解析失败 → 将 ZodError 作为反馈返回给模型
const params = EditToolParams.safeParse(rawParams);
if (!params.success) {
return { success: false, output: `参数格式错误：${params.error.message}` };
}
Claude Code 的工程化底座揭示了一个重要事实：顶级 AI Agent 产品的护城河，在于工程化基础设施的深度，而不只是模型本身的能力。
六个核心设计值得每个 AI 工程师深思：
从提示词工程到系统级工程，这是 AI 应用开发的必经之路。
2026.04.06 18:00沪 · 汇金路宝龙广场
声明：本文由 AI 辅助完成
[1] Claude Code 源码泄露？我把这个最强 AI Coding Agent 的架构扒干净了: www.bestblogs.dev/article/97b…
