Claude Code 架构深度解构

核心论点：不是终端聊天，是 Agent 运行时

Claude Code 的核心创新不在于"在终端里聊天"，而在于它将 Agent 视为可调度、可隔离、可恢复、可观测的系统对象。它不是在 CLI 里嵌入 AI 功能，而是在 CLI 里构建了一个完整的 Agent 运行时。

四层架构全景

层级	职责	核心组件
用户交互层	REPL、命令、权限提示、任务面板、状态栏	REPL.tsx、cli.tsx
推理循环层	Prompt 组织、模型调用、上下文压缩、工具执行、停止钩子、预算控制	query.ts
执行系统层	工具、任务、子 Agent、团队 Agent、远程 Agent、Worktree 隔离、权限同步、状态持久化	AgentTool.tsx、runAgent.ts、toolOrchestration.ts
横切能力层	MCP、插件、技能、记忆、LSP、遥测、远程控制、沙箱、安全策略	跨层服务

数据流从上到下：

CLI 入口 → 快路径分发 → 主运行时组装
    ↓
主运行时 → 配置/认证/策略 → 命令/工具/MCP/Agent → REPL
    ↓
REPL 控制面 → 用户输入 → 消息队列 → 任务面板 → 流式渲染
    ↓
推理循环 → 构建 Prompt → 采样模型 → 运行工具 → 压缩/恢复
    ↓
执行基座 → 工具执行 → 任务框架 → 本地/远程/团队任务
    ↓
Agent 运行时 → Agent 定义 → AgentTool → runAgent → fork/worktree/swarm

入口设计：cli.tsx 双路径分发

入口点 cli.tsx 不是简单的转发器，它实现了两条截然不同的路径：

路径	内容	设计意图
轻路径	单次操作（--version、daemon workers、桥接、后台会话管理、模板命令）	无需完整运行时，快速响应
重路径	完整交互式 REPL 运行时	加载所有子系统

推理循环：query.ts 的 Agent Turn

query.ts 是核心推理引擎，实现了一个完整的 Agent Turn Loop，而非简单的请求-响应循环：

1. 收集消息
2. 组织 System Prompt / User Context / Tool Context
3. 调用模型
4. 处理流式输出
5. 提取 Tool Use
6. 执行工具
7. 将工具结果回注消息流
8. 必要时继续下一轮
9. 处理中断、压缩、预算、钩子、恢复

关键设计决策

决策	实现	解决问题
显式状态分离	不可变 params vs 可变循环状态	防止复杂 Turn 中压缩和异常恢复的状态管理灾难
原生"长 Turn"支持	"任务完成了吗？"而非"聊天记录"	auto-compact、micro-compact、token budget、stop hooks
工具执行在主循环中	工具是推理的内在部分	自然的预算控制、内容替换/压缩、进度消息

工具系统：受治理的执行面

工具系统遵循三大原则：

原则	描述
动态裁剪	工具基于 Feature Gate、用户类型、LSP 状态、Worktree 状态、Swarm 状态、插件/MCP 状态、权限模式动态构建——永远不是固定的
工具即 Prompt 工程	工具列表构成模型的"操作世界观"。Claude Code 精心管理哪些工具暴露、隐藏或受限
可观测与统计执行	工具执行路径处理遥测、权限决策、钩子、追踪、进度和错误分类

并发安全：toolOrchestration.ts

一个小但关键的组件，自动批处理工具调用：

• 只读工具 → 并行执行
• 写密集工具 → 串行执行

这将并发复杂性从模型卸载到运行时——模型不需要理解并发安全，运行时自动处理。

任务系统：Agent 作为一等公民

每个 Agent 表示为一个 Task，具有：

属性	用途
ID、类型、状态、描述	统一身份和生命周期
开始/结束时间	可观测性
outputFile	一等公民——支持恢复、通知、旁路记录；后台 Agent 无需持久前台 UI
<task-notification>	完成/失败/停止时生成的消息——主 Agent 无需阻塞即可收到更新

多 Agent 架构：三层隔离

AgentTool.tsx 是多 Agent 设计的核心门面，暴露统一接口并路由到不同后端：

AgentTool
  ├── Local agent（本地 Agent）
  ├── Teammate agent（团队 Agent）
  ├── Fork subagent（Fork 子 Agent）
  ├── Remote agent（远程 Agent）
  └── Worktree agent（Worktree Agent）

三层 Agent 形态

层	类型	隔离级别	适用场景
1	普通子 Agent	在本地 query loop 中运行	简单委派
2	进程内队友	同一 Node.js 进程，上下文隔离	性能/复杂度平衡
3	隔离 Agent	Worktree/远程	更强隔离，更长运行时间

Agent 定义即数据

Agent 是可加载、可组合、基于插件的配置对象，而非硬编码的角色。每个 Agent 定义包括：

• 行为边界
• 工具权限
• 记忆策略
• 隔离策略

上下文管理：压缩与记忆

三层 Agent 记忆

范围	描述	持久性
用户级	跨所有项目持久化	永久
项目级	项目内共享	项目生命周期
本地级	会话作用域	会话结束即清除

上下文压缩机制

• Auto-compact：长会话自动压缩历史，保留关键信息
• Micro-compact：精细化的增量压缩，针对特定上下文窗口
• Token Budget：防止上下文无限膨胀的预算控制
• Fork 子 Agent Prompt Cache：复用缓存的 Prompt 以优化成本

权限系统：主干而非补丁

权限系统被集成到核心执行流程中，而非作为安全补丁后加：

机制	实现	设计意图
ToolUseContext + ToolPermissionContext	管控每次工具调用	细粒度权限控制
Leader 审批模型	Worker 可发起操作，但最终决定权在 Leader UI	防止"权限提示疲劳"
集中决策	Agent 不能悄悄越权	可审计、可追溯

与 Cursor 3 / OpenClaw 技术对比

维度	Claude Code	Cursor 3	OpenClaw
架构核心	Agent 运行时（终端）	Agent 工作台（IDE）	Agent 框架（IDE 扩展）
Agent 隔离	三层（进程内/Worktree/远程）	Git Worktree 8 Agent 并行	Skills 隔离 + MCP 沙箱
模型层	Claude 系列（闭源）	Composer 2（自研 MoE）+ 第三方	模型无关（BYOK）
权限模型	Leader 审批集中制	Composer 审批流	Skills 白名单 + NemoClaw 护栏
工具扩展	MCP 原生 + 插件 + 技能	MCP 支持 + SDK	Skills + MCP + ClawHub
上下文管理	三层记忆 + Auto-compact	项目索引 + Codebase Retrieval	会话级 + RAG
开源程度	❌ 闭源（源码可读但非 OSI 许可）	❌ 闭源	✅ MIT 开源
部署模式	CLI 本地	IDE 本地 + Cloud Agent	本地 / 自托管 / 云端
典型用户	高级开发者、DevOps	全栈开发者	企业团队、隐私敏感

10 大创新点与 5 大局限

10 大创新点

#	创新	解决的问题
1	Agent as Task	统一生命周期管理
2	语义工具批处理	高效并发（读并行、写串行）
3	Fork 子 Agent Prompt Cache	成本优化
4	进程内队友隔离	性能/复杂度平衡
5	Leader 审批模型	集中化、非疲劳的权限控制
6	声明式 Agent 定义	工程级可组合角色
7	Agent 专属 MCP	基于角色的能力挂载
8	三层 Agent 记忆	实用的作用域持久化
9	一等隔离	Worktree/远程集成用于长时间任务
10	验证 Agent	反惰性设计（确保质量）

5 大局限

#	局限	影响
1	闭源生态	源码可读但非 OSI 许可，无法 fork/修改/自托管
2	模型绑定	仅支持 Claude 系列，无法使用 GPT/Gemini/DeepSeek
3	Windows 支持	基于 Unix 哲学设计，需要 POSIX 环境（WSL 是最佳选择）
4	学习曲线	配置文件驱动、多模式运行——对非终端用户不友好
5	企业级功能缺失	无 SSO、无审计日志、无合规护栏——企业需自行包装

创新点如何解决 5 大多 Agent 失败模式

失败模式	Claude Code 的解决方案
失控的 Agent	Task/Permission/UI 系统
并发混乱	工具分区 / Leader 审批
高成本	Prompt 缓存 / 智能路由
不可恢复的错误	持久化记录 / 元数据
用户困惑	统一 REPL / 通知系统