Claude Code 源码级架构拆解
基于对 v2.1.88 源码的系统性架构分析论文《Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems》（2026-04-14）。
核心结论
Claude Code 的核心 agent 循环只是一个简单的 while 循环。真正复杂的是围绕这个循环的安全、权限、上下文管理、可扩展性和会话持久化系统。社区估算：整个代码库约 1.6% 是 AI 决策逻辑，剩下 98.4% 是确定性工程基础设施。
架构哲学
"最小脚手架，最大操作环境"。Claude Code 不替模型规划步骤（不像 LangGraph 等用状态图规定"先搜索、再编辑、再测试"），而是把投资放在确定性基础设施上（上下文管理、工具路由、错误恢复），让模型自由推理和决策。创始团队自称为 "Unix 工具而非传统产品"。
五个驱动价值观
- 人类决策权威：层级化委托人体系（Anthropic > 运营商 > 用户）明确谁有权决定什么
- 安全、隐私和保护：系统有义务在人类注意力松懈时仍然保护他们
- 可靠执行：跨上下文窗口、跨会话恢复、跨多 agent 委托保持一致
- 能力放大：每单位人力投入产出更多成果
- 情境适应性：系统适应用户的具体项目、工具、习惯，且随时间进化（纵向数据：自动批准率从 20% 上升到 40%+）
13 条设计原则
关键原则包括：默认拒绝并交由人类升级处理；渐进信任谱系（用户随时间逐步扩展 agent 自主权）；纵深防御（多层独立机制叠加，不靠单一安全边界）；最小脚手架、最大操作环境。
7 个功能组件与 5 层子系统
四种入口方式（全部汇入同一个 agent 循环，共享同一套安全和执行逻辑）：
- 交互式 CLI
- 无头 CLI（headless，适合自动化脚本）
- Agent SDK（供开发者嵌入自己的程序）
- IDE 集成（VS Code 等）
5 层子系统（从外到内）：
- 表面层（入口和渲染）
- 核心层（agent 循环和压缩管线）
- 安全/动作层（权限、hooks、工具、沙箱、子 agent）
- 状态层（上下文组装、会话持久化、CLAUDE.md 和记忆）
- 后端层（执行引擎和外部资源）
Agent 循环
核心是 query.ts 里的 queryLoop() 函数，一个异步生成器。每轮流程：解析设置 → 初始化可变状态 → 组装上下文 → 运行五个上下文整形器 → 调用模型 → 如果模型返回 tool_use 块就分发给工具执行 → 收集结果追加到对话 → 如果没有 tool_use 块就结束本轮。
"模型提议、外壳执行"分工：模型输出结构化声明"我想调用某某工具，参数是某某"，由 harness（执行外壳）决定是否批准、怎么执行、结果怎么返回。模型本身从不直接接触文件系统、shell 或网络。这是典型的 ReAct 模式（Reasoning + Acting）。
五层上下文压缩管线
上下文窗口是硬约束（Claude 4.6 约 100 万 token）。每次模型调用前按顺序跑五个"整形器"（context shaper）：
- Budget Reduction：对单条工具输出限制大小，超出用内容引用替换
- Snip：直接剪掉较旧的历史片段
- Microcompact：细粒度压缩，可选缓存感知路径
- Context Collapse：生成"投影视图"供模型使用，原始完整历史保留在磁盘
- Auto-compact：调用模型自身对整段对话生成语义摘要（仅前四层不够时启动，消耗一次模型调用成本）
权限系统
七种权限模式（从 plan 到 bypassPermissions），规则评估遵循 "deny 优先"原则：一条宽泛的 deny 规则不能被更具体的 allow 规则覆盖。
自动模式分类器：Anthropic 发现用户对 93% 的权限提示都点了批准，说明人工确认作为唯一安全机制在行为上不可靠。分类器加载三种提示资源，对照对话记录和权限模板评估每个工具调用，输出允许、拒绝或要求人工批准。当分类器或 deny 规则阻止操作，系统把拒绝原因反馈给模型，模型在下一轮尝试更安全的替代方案。
四种扩展机制
| 机制 | 上下文开销 | 用途 |
|---|---|---|
| MCP 服务器 | 最高 | 外部工具集成，schema 常驻上下文 |
| 插件（Plugin） | 中 | 打包分发格式，10 种组件类型 |
| 技能（Skill） | 低 | 领域专用指令，SKILL.md 定义，按需加载 |
| Hooks | 零 | 生命周期拦截器，27 种事件类型 |
单一扩展 API 无法覆盖从零上下文开销到高开销工具服务器的全部频谱，所以四种机制各有存在理由。
上下文窗口组装优先级
系统提示 → 环境信息（git 状态等，缓存一次） → CLAUDE.md 层级文件（从根目录到当前目录，后加载优先级更高） → 技能描述和 MCP 工具名 → 对话历史和工具结果 → 压缩摘要替换旧历史。
CLAUDE.md：四级层次（操作系统级 / 用户级 / 项目级 / 本地级）。关键选择是不用嵌入向量或数据库，牺牲检索灵活性换取可审计性。
子 agent 委托
隔离架构：子 agent 获得独立上下文窗口，与父 agent 完全隔离。完成后只把摘要文本返回，全部对话存在单独的"侧链记录"（sidechain transcript）文件里。子 agent 不继承父 agent 的已批准权限，敏感操作通过 bubble 模式把权限请求"冒泡"回父终端。
会话持久化
追加式 JSONL 格式：每次操作追加到 JSON Lines 文件，完整操作轨迹始终可审计。恢复会话时不恢复权限状态，防止权限在人不在场时被滥用。
与 OpenClaw 的对比
| 维度 | Claude Code | OpenClaw |
|---|---|---|
| 部署模型 | 单用户 CLI 工具 | 多用户网关服务 |
| 安全架构 | 逐操作 deny-first 评估 | 边界级访问控制（OAuth/API 密钥） |
| 运行时 | 单循环 | agent 运行时嵌入网关控制面 |
| 扩展架构 | 上下文窗口扩展 | 网关级能力注册 |
| 记忆 | 文件系统层级 | 数据库支持的知识管理 |
| 多 agent | 父子隔离委托 | 渠道路由和 agent 分发 |
论文结论：这些差异不是孰优孰劣，而是同一套设计问题在不同场景下必然产出不同架构。
四个核心架构权衡
- 安全 vs 自主性：权限模式从 default 移到 auto 再到 bypassPermissions，安全判断逐步移交给算法，人参与越少效率越高但兜底越弱
- 对抗条件下的权限模型：当 shell 命令包含超过 50 个子命令时，系统放弃逐个检查 deny 规则，退回到单一通用批准提示（性能压力同时影响多层防线）
- 上下文效率 vs 透明度：压缩管线丢弃信息，但模型和用户都看不到被丢弃了什么
- 简洁性 vs 可扩展性：四种扩展机制提供灵活性，但开发者需要判断每种场景该用哪种
人类能力退化担忧
Anthropic 内部调查记录了一个**"监督悖论"**：过度依赖 AI 有可能侵蚀用来监督 AI 所需的那些技能。独立研究发现 AI 辅助条件下的开发者在代码理解测试中得分低 17%。论文指出当前架构在放大短期产出方面投资充分，但在维护人类对代码库的深层理解、保持代码库长期一致性、以及维持开发者技能管线方面，缺乏显式机制。
六个未来方向
- 静默失败与可观测性缺口
- 跨会话持久化记忆（当前记忆系统是文件级的，缺乏结构化长期记忆）
- harness 边界演进（本地 vs 云端 vs 跨组织，实时 vs 后台 vs 定时）
- 任务周期尺度扩展（从单次会话到持续数周）
- 规模化治理与监督（成百上千个 agent 实例并行运行）
- 长期人类能力的保持