论文信息
- 标题: Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems
- 作者: Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, Zhiqiang Shen (VILA Lab, MBZUAI & UCL)
- arXiv: 2604.14228
- 原文链接: https://papers.cool/arxiv/2604.14228
- 代码: https://github.com/VILA-Lab/Dive-into-Claude-Code
- 分析版本: Claude Code v2.1.88
深入 Claude Code：当今与未来 AI Agent 系统的设计空间
摘要
本研究通过分析 Claude Code 的公开 TypeScript 源码，全面描述了其架构设计。并将它与开源 AI Agent 系统 OpenClaw 进行对比，展示了相同的重复性设计问题在不同部署上下文中如何产生不同的架构答案。
核心发现
研究识别出驱动架构的五大人类价值，通过十三条设计原则追溯到具体的实现选择。系统核心是一个简单的 while 循环（调用模型→运行工具→重复），但大部分代码围绕这个循环构建：七种模式的权限系统、五层上下文压缩管线、四种扩展机制、子代理委派机制和追加式会话存储。
1. 引言
AI 辅助软件开发已经从自动补全（GitHub Copilot）→ IDE 集成助手（Cursor）→ 完全自主的 Agent 系统（Claude Code）演进。
Anthropic 对 132 名工程师和研究员的内部调查显示：约 27% 的 Claude Code 辅助任务是在没有工具的情况下根本不会尝试的工作，说明该架构带来了质变性的新工作流，而不仅仅是加速现有流程。
论文三大贡献
- 设计空间分析：识别重复性设计问题，通过 7 组件高层结构和 5 层子系统架构分析 Claude Code 的回答
- 与 OpenClaw 的架构对比：在六个设计维度上比较，展示不同部署上下文下的不同答案
- 未来 Agent 系统的开放方向：识别六个开放设计方向
2. 设计哲学、设计原则与架构动机
五大核心价值
1. 人类决策权威（Human Decision Authority）
人类保留对系统行为的最终决策权。当 Anthropic 发现用户批准 93% 的权限提示时，他们没有加更多警告，而是重构了问题：定义边界（沙箱、自动模式分类器），让 Agent 在边界内自由工作。
2. 安全、隐私与保障（Safety, Security, and Privacy）
即使人类疏忽或犯错，系统也要保护人类及其代码、数据和基础设施。自动模式威胁模型针对四类风险：过度热情行为、诚实错误、提示注入、模型不对齐。
3. 可靠执行（Reliable Execution）
Agent 做人类真正想做的事，随时间保持一致，并支持在声明成功前验证工作。关键洞察：Agent 倾向于”自信地赞美工作”，即使质量平庸——这促使了生成与评估的分离。
4. 能力放大（Capability Amplification）
系统实质性地增加人类单位投入能完成的任务量。被其创建者描述为”Unix 工具而非传统产品”。
5. 上下文适应性（Contextual Adaptability）
系统适应用户的特定上下文，关系随时间改善。自动批准率从 <50 次会话时的约 20% 增长到 750 次会话时的 40% 以上。
十三条设计原则
| 原则 | 服务价值 | 设计问题 |
|---|---|---|
| 默认拒绝+人类升级 | 权威、安全 | 未识别操作应允许、阻止还是升级？ |
| 渐进信任谱 | 权威、适应性 | 固定权限级别，还是用户随时间遍历的谱？ |
| 纵深防御 | 安全、权威、可靠 | 单一安全边界，还是多层重叠？ |
| 外部化可编程策略 | 安全、权威、适应性 | 硬编码策略，还是带生命周期钩子的外部化配置？ |
| 上下文为稀缺资源+渐进管理 | 可靠、能力 | 约束资源是什么？单次截断还是分级管线？ |
| 仅追加持久状态 | 可靠、权威 | 可变状态、检查点快照还是仅追加日志？ |
| 最小脚手架+最大操作 Harness | 能力、可靠 | 投资脚手架推理，还是让模型自由推理的操作基础设施？ |
| 价值观优于规则 | 能力、权威 | 刚性决策过程，还是有确定性护栏的上下文判断？ |
| 可组合多机制扩展 | 能力、适应性 | 统一扩展 API 还是分层机制？ |
| 可逆性加权风险评估 | 能力、安全 | 相同监督所有操作，还是对可逆/只读操作更轻？ |
| 透明文件化配置与记忆 | 适应性、权威 | 不透明数据库还是用户可见的版本可控文件？ |
| 隔离子代理边界 | 可靠、安全、能力 | 共享上下文还是隔离操作？ |
| 优雅恢复与韧性 | 可靠、能力 | 硬失败还是静默恢复？ |
3. 架构概览
系统核心：简单 While 循环
while (true) {
// 组装上下文
// 调用 Claude 模型
// 接收响应（可能含 tool_use）
// 路由到权限系统
// 分发已批准操作到工具
// 收集结果
// 循环
}社区分析估计：只有约 1.6% 的代码库是 AI 决策逻辑，其余 98.4% 是操作基础设施。
七组件架构
- 用户：提交提示、批准权限、审查输出
- 接口：交互式 CLI、无头 CLI、Agent SDK、IDE/桌面/浏览器（所有接口汇入同一个循环）
- Agent 循环：模型调用→工具分发→结果收集
- 权限系统：拒绝优先规则评估 + 自动模式 ML 分类器
- 工具：最多 54 个内置工具（19 无条件 + 35 条件）+ MCP 工具
- 状态与持久化：JSONL 会话转录（仅追加）
- 执行环境：Shell 执行（可选沙箱）、文件系统、Web、MCP
五层子系统
| 层 | 组件 |
|---|---|
| Surface 层 | 交互式 CLI、无头 CLI、Agent SDK、IDE |
| Core 层 | Agent 循环、压缩管线 |
| Safety/Action 层 | 权限系统、Hook 管线、扩展、工具、沙箱、子代理 |
| State 层 | 上下文组装、运行时状态、会话持久化、CLAUDE.md |
| Backend 层 | 执行后端、外部资源 |
4. Turn 执行：Agent 查询循环
查询管线
每个 turn 的固定流程：
- 设置解析：解构不可变参数
- 可变状态初始化：单个 State 对象
- 上下文组装：从上次压缩边界获取消息
- Pre-model 上下文整形器：五个整形器顺序执行
- 模型调用：流式响应
- 工具使用分发：并发读、串行写
- 权限门：每个工具请求通过权限系统
- 工具执行和结果收集
- 停止条件：无工具使用 = turn 完成
五层上下文压缩管线
每次模型调用前顺序执行：
| 层 | 名称 | 功能 |
|---|---|---|
| 1 | Budget Reduction | 单条工具输出超限时截断 |
| 2 | Snip | 移除较旧的历史段 |
| 3 | Microcompact | 基于时间的细粒度压缩 |
| 4 | Context Collapse | 只读投影，不修改原始消息 |
| 5 | Auto-Compact | 模型生成的摘要（最后手段） |
恢复机制
- 输出 token 上限升级（最多 3 次恢复/turn）
- 响应式压缩（每 turn 最多触发 1 次）
- prompt-too-long 处理
- 流式回退
- 备用模型切换
5. 工具授权与控制边界
七种权限模式
| 模式 | 描述 |
|---|---|
| plan | 必须创建计划，用户批准后执行 |
| default | 标准交互，大多数操作需批准 |
| acceptEdits | 编辑和文件系统命令自动批准 |
| auto | ML 分类器评估未匹配规则的请求 |
| dontAsk | 不提示但拒绝规则仍执行 |
| bypassPermissions | 跳过大多数提示，安全关键检查仍适用 |
| bubble | 子代理权限升级的内部模式 |
授权管线
- 预过滤：全面拒绝的工具从模型视图中移除
- PreToolUse Hook：可拒绝/修改请求
- 规则评估：拒绝优先
- 权限处理器：协调器/群集工作器/推测分类器/交互式
- Shell 沙箱：独立的文件系统和网络隔离
自动模式分类器
使用 ML 模型评估工具安全性，产生允许/拒绝/请求人工批准。
关键发现：安全研究人员发现，超过 50 个子命令的命令会回退到单一通用批准提示，因为逐子命令解析会导致 UI 冻结——展示了纵深防御在层共享故障模式时可能退化。
6. 扩展性：MCP、插件、技能和 Hook
四种扩展机制
| 机制 | 作用 | 上下文成本 |
|---|---|---|
| MCP 服务器 | 外部工具集成 | 初始仅加载名称 |
| 插件 | npm 安装的组件包 | 按需加载和缓存 |
| 技能 | 目录化领域特定行为 | 引用时加载 |
| Hook | 工具执行生命周期拦截 | 不增加上下文内容 |
27 种 Hook 事件类型，其中 5 种与安全直接相关。
7. 上下文管理
CLAUDE.md 指令层级
四级指令层次结构：
- 托管设置（全局偏好）
- 项目级指令
- 目录特定指令
- 会话特定指令
懒加载机制：仅在引用时加载，最小化上下文开销。
8. 子代理委派与编排
核心设计
- 子代理作为独立实例运行，有自己的上下文和权限系统
- 使用 Sidechain 转录文件（防止子代理对话膨胀父上下文）
- 父代理仅接收摘要文本
权限隔离
- 子代理权限从父代理派生但可覆盖
- 无法访问父代理上下文（除明确共享的）
9. 会话持久化
仅追加 JSONL 存储
- 每行一条消息
- 高效追加和恢复
- 支持恢复（resume）、分叉（fork）、回溯（rewind）
10. 与 OpenClaw 的架构对比
| 维度 | Claude Code | OpenClaw |
|---|---|---|
| 部署上下文 | 专用编码 Agent | 多通道个人助手网关 |
| 安全架构 | 逐操作安全评估 + 纵深防御 | 周界级访问控制 |
| 执行模型 | 单一 CLI 循环 | 网关控制面内的嵌入运行时 |
| 上下文管理 | 上下文窗口压缩管线 | 会话限制 + 外部存储 |
| 扩展性 | 多种专门机制 | 统一扩展 API |
| 扩展表面 | 上下文窗口扩展 | 网关级能力注册 |
核心洞察：相同的重复性设计问题在不同部署上下文中产生不同的架构答案。
11. 六个未来开放方向
- 可观测性-评估差距：受控环境 vs 真实使用
- 跨会话持久性：长期状态和关系维护
- Harness 边界演化：模型改进时操作 Harness 如何适应
- 时间跨度扩展：长期任务和依赖处理
- 治理：负责任的 AI Agent 开发框架
- 评估视角：系统是否支持长期人类能力提升
评估性视角
研究揭示了一个开放问题：虽然 Claude Code 大幅放大了程序员的短期能力，但缺乏明确支持长期人类提升、更深入理解和持续代码库一致性的机制。
Anthropic 自己的研究记录了”监督悖论”——过度依赖 AI 有萎缩监督所需技能的风险。独立研究发现，AI 辅助条件下的开发者在理解测试中得分低 17%。
核心启示
- Agent ≠ 模型：只有 1.6% 的代码是 AI 决策逻辑，98.4% 是操作基础设施
- 简单循环 + 丰富环境 > 复杂编排：不做显式规划图，而是提供丰富的操作环境
- 拒绝优先 > 允许优先：安全默认值 + 渐进信任
- 上下文是瓶颈：五层压缩管线反映了对有限上下文窗口的深刻理解
- 部署上下文决定架构：同样的问题，不同的答案
论文: Liu, J., Zhao, X., Shang, X., & Shen, Z. (2026). Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems. arXiv:2604.14228.
arXiv: https://arxiv.org/abs/2604.14228 代码: https://github.com/VILA-Lab/Dive-into-Claude-Code