深入 Claude Code：当代与未来 AI Agent 系统的设计空间
Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems
通过分析 Claude Code 的 TypeScript 源码（v2.1.88），系统梳理其五层架构、七大组件、十三条设计原则。并与 OpenClaw（多通道网关）和 Hermes Agent（单进程多面助手）进行六维横向对比，揭示不同部署场景下同一设计问题的不同答案。最后提出六个未来 Agent 系统的开放方向。
论文概览
这篇来自 MBZUAI VILA Lab 的 53 页长文，做了一件罕见的事：它不讨论 Agent 的 benchmark 分数，也不提模型能力，而是把 Claude Code 的 TypeScript 源码（v2.1.88）逐文件拆解，从中提炼出一套设计空间分析框架，并用同一框架横向对比了 OpenClaw 和 Hermes Agent 两个独立开源 Agent 系统。
论文的核心论点很清晰：生产级编码 Agent 的架构不是随意拼凑的，而是对一组反复出现的设计问题的系统性回答。Claude Code 的回答只是设计空间中的一个点——理解这个点的位置，以及它为什么在这里，才是设计更好 Agent 系统的前提。
| 维度 | 内容 |
|---|---|
| 论文标题 | Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems |
| 作者 | Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, Zhiqiang Shen |
| 机构 | MBZUAI VILA Lab + University College London |
| 分析对象 | Claude Code v2.1.88 (TypeScript 源码) |
| 对比系统 | OpenClaw (多通道网关)、Hermes Agent (单进程多面助手) |
| 页数 | 53 页 |
| 代码仓库 | github.com/VILA-Lab/Dive-into-Claude-Code |
五大价值与十三条设计原则
论文从源码中逆向出了驱动 Claude Code 架构的五个底层价值观，它们不是抽象口号，而是可以追溯到具体实现选择的设计约束。
五大价值
| 价值 | 核心主张 | 典型实现 |
|---|---|---|
| 人类决策权威 | 人类保留最终决策权，但通过有界自主性而非逐动作审批实现 | deny-first 默认、渐进信任谱系、append-only 审计日志 |
| 安全/安全/隐私 | 即使人类疏忽，系统也有义务保护代码、数据和基础设施 | 纵深防御、Shell 沙箱、auto-mode ML 分类器 |
| 可靠执行 | Agent 做人类真正想做的事，跨上下文窗口和会话保持连贯 | 5 层压缩管线、优雅恢复、隔离子 Agent 边界 |
| 能力放大 | 投资运营基础设施而非决策脚手架，让模型自由推理 | ~1.6% 决策逻辑 + ~98.4% 运营基础设施 |
| 上下文适应性 | 通过透明、可版本控制的文件适应用户项目 | CLAUDE.md 四级层次、4 种扩展机制、渐进信任 |
一个关键数据驱动了整个安全架构的设计：用户批准了 93% 的权限提示。Anthropic 的内部调研发现，审批疲劳使交互确认在行为上不可靠。系统因此转向"在有界范围内自由行动"的设计——不是加更多警告，而是重构问题本身。
十三条设计原则
这五个价值被操作化为十三条设计原则，每条回答一个反复出现的设计问题：
| 原则 | 回答的设计问题 |
|---|---|
| Deny-first + 人类升级 | 未识别动作应被允许、阻止还是升级给人类？ |
| 渐进信任谱系 | 固定权限级别，还是用户随时间递进的谱系？ |
| 纵深防御 + 分层机制 | 单一安全边界，还是多技术叠加？ |
| 外部化可编程策略 | 硬编码策略，还是带生命周期 hook 的外部配置？ |
| 上下文即稀缺资源 | 单次截断还是渐进式管线？ |
| Append-only 持久状态 | 可变状态、快照检查点还是 append-only 日志？ |
| 最小脚手架 + 最大运营框架 | 投资推理侧脚手架还是运营基础设施？ |
| 价值观优于规则 | 刚性决策过程还是确定性护栏下的上下文判断？ |
| 可组合多机制扩展 | 统一扩展 API 还是不同上下文成本的分层机制？ |
| 可逆性加权风险评估 | 所有动作相同监管，还是可逆/只读动作更轻？ |
| 透明文件配置和记忆 | 不透明数据库/嵌入检索还是用户可版本控制的文件？ |
| 隔离子 Agent 边界 | 子 Agent 共享父上下文和权限还是隔离运行？ |
| 优雅恢复和弹性 | 错误即停还是静默恢复？ |
架构全景：五层分解
Claude Code 的核心是一个简单的 while-true 循环：调用模型 → 执行工具 → 收集结果 → 重复。但围绕这个循环的是一层又一层的运营基础设施。社区分析估计，只有约 1.6% 的代码是 AI 决策逻辑，剩余 98.4% 是运营基础设施。
七组件高层结构
系统的七个功能组件通过主数据流连接：
- 用户 — 提交提示、审批权限、审查输出
- 接口层 — 交互 CLI、Headless CLI (
claude -p)、Agent SDK、IDE/Desktop/Browser，所有入口汇聚到同一个循环 - Agent 循环 —
queryLoop()异步生成器，模型调用 → 工具分发 → 结果收集的迭代周期 - 权限系统 — deny-first 规则评估 + auto-mode ML 分类器 + hook 拦截
- 工具池 — 最多 54 个内置工具（19 个无条件 + 35 个条件性）+ MCP 工具，通过
assembleToolPool()合并 - 状态与持久化 — append-only JSONL 会话转录 + 全局提示历史 + 子 Agent sidechain 文件
- 执行环境 — Shell 执行（可选沙箱）+ 文件系统操作 + Web 抓取 + MCP 连接 + 远程执行
运行时流程
一次 turn 的执行遵循固定序列：
- 设置解析 —
queryLoop()解构不可变参数 - 可变状态初始化 — 单个 State 对象存储所有迭代间的可变状态
- 上下文组装 —
getMessagesAfterCompactBoundary()检索消息，应用压缩边界 - 模型调用 — Claude 模型生成可能包含
tool_use块的响应 - 工具分发 —
StreamingToolExecutor在工具流式到达时开始执行，读操作并行、写操作串行化 - 结果收集 — 按工具请求顺序缓冲并发射结果
- 压缩检查 — 5 层压缩管线按需触发
关键设计选择是推理与执行的分离：模型通过结构化 tool_use 协议与外部世界交互，harness 负责验证和执行。即使模型被对抗性操纵，也无法绕过 harness 中的沙箱、权限检查或 deny-first 规则。
权限管线：纵深防御
Claude Code 的安全架构不是单一边界，而是多层独立机制的纵深防御。每层使用不同技术，一层失效时其他层仍然有效。
七种权限模式
| 模式 | 行为 | 自主性 |
|---|---|---|
plan | 模型必须先创建计划，用户审批后执行 | 最低 |
default | 超出只读访问的动作需要用户批准 | 低 |
acceptEdits | 文件编辑自动批准，其他动作仍需确认 | 中 |
auto | ML 分类器自动评估大部分审批请求 | 中高 |
bypassPermissions | 跳过大部分提示，安全关键检查仍然保留 | 最高 |
bubble | 内部使用，用于子 Agent 权限升级 | 内部 |
这七个模式构成一个渐进信任谱系：从 plan（用户审批所有计划）到 bypassPermissions（最小提示）。纵向数据支持这一设计——auto-approve 率从最初 50 次会话的约 20% 增长到 750 次会话后的超过 40%，系统是为信任轨迹而非固定信任状态而设计的。
授权管线流程
工具请求通过以下阶段依次过滤：
- Pre-filtering —
filterToolsByDenyRules()在工具池组装时剥离被 blanket-deny 的工具，模型根本看不到它们 - PreToolUse Hook — 注册的 hook 可以 deny、ask 或修改工具输入参数
- Rule Evaluation — deny-first 顺序评估，deny 规则总是优先于 allow 规则，即使 allow 更具体
- Auto-Mode Classifier — ML 分类器评估工具调用，输出 allow/deny/ask
- Shell Sandbox — 独立于权限系统的文件系统和网络隔离
- Execution — 批准的动作被执行，结果返回循环
关键在于权限与沙箱操作在不同轴上：一个命令可以被权限批准但仍被沙箱限制，也可以被权限拒绝而永远到不了沙箱检查。两套系统独立运行，互为补充。
上下文管理：五层压缩管线
上下文窗口是 Claude Code 架构的绑定资源约束，系统围绕它构建了五层渐进式压缩管线：
| 层 | 机制 | 粒度 | 触发条件 |
|---|---|---|---|
| 1. Budget Reduction | 每个 tool_result 有大小上限 | 粗 | 始终活跃 |
| 2. Snip | 轻量修剪旧历史段 | 粗 | HISTORY_SNIP flag |
| 3. Microcompact | 细粒度缓存感知压缩 | 中 | CACHED_MICROCOMPACT flag |
| 4. Context Collapse | 读时虚拟投影，不修改存储的历史 | 细 | CONTEXT_COLLAPSE flag |
| 5. Auto-compact | 完整模型生成摘要 | 很细 | 默认启用，可关闭 |
设计原则是懒退化：先应用干扰最小的压缩，只有在更廉价的策略不够时才升级。Context Collapse 是最精妙的一层——它不修改 REPL 存储的历史，而是在查询时用投影视图替换 messagesForQuery 数组，模型看到折叠后的版本，但完整历史仍可用于重建。
四种扩展机制
Claude Code 使用四种扩展机制，按上下文成本递增排列：
| 机制 | 独特能力 | 上下文成本 | 插入点 |
|---|---|---|---|
| Hooks | 生命周期拦截 + 事件驱动自动化 | 零（默认） | execute(): pre/post tool |
| Skills | 领域特定指令 + meta-tool 调用 | 低（仅描述） | assemble(): 上下文注入 |
| Plugins | 多组件打包 + 分发 | 中（可变） | 三个插入点全部覆盖 |
| MCP Servers | 外部服务集成（多传输） | 高（工具 schemas） | model(): 工具池 |
论文解释了为什么用四种而不是一种统一机制：不同扩展对上下文窗口施加不同成本。从零成本的 lifecycle hooks 到 schema 密集的工具服务器，单一机制无法在不迫使扩展作者做出不必要权衡的情况下覆盖整个范围。
子 Agent 委派与编排
子 Agent 通过 AgentTool 派发，与所有其他工具走同一个 buildTool() 工厂。关键设计：
- 隔离上下文窗口 — 每个子 Agent 在独立的上下文中运行，不继承父对话历史
- 仅返回摘要 — 只有最终响应文本和元数据返回父上下文，完整历史永远不进入父窗口
- Sidechain 转录 — 每个子 Agent 的对话写入独立的
.jsonl+.meta.json文件，不膨胀父会话文件 - 权限重建 — 子 Agent 获得重建的权限上下文和独立工具集，而非直接继承
内置子 Agent 包括 Explore（只读搜索）、Plan（规划）、General-purpose（通用）、Verification（验证）等。用户也可通过 .claude/agents/*.md 定义自定义子 Agent，指定独立的工具、模型、权限、hooks 和隔离模式。
三方对比：Claude Code vs OpenClaw vs Hermes Agent
论文最有价值的部分之一是三个系统的六维横向对比。它们回答相同的设计问题，但给出了不同的答案：
系统范围与信任边界
| 维度 | Claude Code | OpenClaw | Hermes Agent |
|---|---|---|---|
| 部署形态 | CLI/IDE 编码工具，临时单会话进程 | 持久 WS 网关守护，多通道控制面 | 单 Python 进程，角色由入口点决定 |
| 信任边界 | 模型与执行环境之间 | 网关边界 | 每动作审批（类似 Claude Code）但跨多面渲染 |
三个系统的信任边界位置截然不同：Claude Code 在模型和执行环境之间放置 deny-first 管线；OpenClaw 在网关边界放置身份和访问控制（DM 配对码、发送者白名单）；Hermes 在每动作层面放置审批流程，但同一流程在 CLI、Telegram、Discord、QQBot、ACP 四种面上渲染。
Agent 运行时
三个系统都使用了某种循环结构，但实现差异显著：
- Claude Code: 异步生成器
queryLoop()，ReAct 模式，模型决定下一步动作 - OpenClaw: 嵌入式
pi-coding-agentSDK runner 在网关 RPC 分发内运行，每会话队列序列化 - Hermes: 同步
while循环在AIAgent.run_conversation中，默认 90 次迭代 + 迭代预算，工具耗尽时触发 stripped summary call
记忆与上下文
三者都选择了透明文件式记忆而非不透明数据库，但层次不同：
- Claude Code: CLAUDE.md 四级层次 + 5 层压缩管线 + LLM 扫描选择（不用嵌入向量）
- OpenClaw: AGENTS.md/SOUL.md/MEMORY.md + 日记 + 可选 DREAMS.md + 混合检索（vector + keyword）+ 梦境整合系统
- Hermes: SQLite WAL + FTS 跨会话搜索 + 父子会话链 + cron 调度器 + curator 循环
Hermes 的 SQLite 选择提供了开箱即用的跨会话搜索和并发读支持，而 Claude Code 的 JSONL 选择优先考虑可审计性和简单性。
子 Agent 与多 Agent 编排
| 维度 | Claude Code | OpenClaw | Hermes Agent |
|---|---|---|---|
| 委派模式 | AgentTool 隔离上下文，仅返回摘要 | 多 Agent 路由，独立实例服务不同通道 | Kanban 共享看板，多 Worker 协调 |
| 隔离方式 | 上下文隔离 + worktree + 可选容器 | 独立 Agent 实例 + 不同通道 | 持久记忆禁用 + stale-claim 回收 |
| 协调机制 | 父子层级 | 通道路由 | SQLite 工作队列 + 心跳 |
关键区别在于：Claude Code 的子 Agent 是一个用户编码会话内的从属工作者；OpenClaw 的多 Agent 路由创建的是服务不同用户或目的的独立实例；Hermes 结合了严格的每 turn 委派默认和独立的 Kanban 层，让多个 Agent 进程在持久共享看板上协调。
价值张力与架构权衡
论文不仅描述了架构选择，还揭示了这些选择之间的内在张力：
| 价值对 | 张力 | 证据 |
|---|---|---|
| 权威 × 安全 | 审批疲劳 vs 保护 | 93% 批准率削弱人类警觉；安全必须通过分类器和沙箱补偿 |
| 安全 × 能力 | 性能 vs 防御深度 | >50 子命令的 fallback 跳过逐子命令 deny 检查（解析开销） |
| 适应性 × 安全 | 扩展性 vs 攻击面 | 多个 CVE 利用 hooks 和 MCP 服务器的预信任初始化 |
| 能力 × 适应性 | 主动性 vs 干扰 | 12-18% 更多任务但高频时偏好下降 |
| 能力 × 可靠性 | 速度 vs 连贯性 | 有界上下文阻止全局感知；子 Agent 隔离限制跨 Agent 一致性 |
一个重要的安全发现是预信任初始化窗口：项目初始化期间执行的代码（hooks、MCP 服务器连接、设置文件解析）在交互式信任对话框呈现给用户之前运行。这个时间窗口落在 deny-first 评估管线之外，创建了一个安全保证尚未完全生效的结构性特权阶段。
六个未来方向
基于设计空间分析和三方对比，论文提出了六个开放方向：
1. 可观测性-评估鸿沟
行业调研显示 78% 的 AI 故障是"不可见的"。可观测性（近 89% 采用）与离线评估（52.4%）之间存在巨大鸿沟。关闭这个鸿沟可能需要额外的脚手架（generator-evaluator 分离、sprint contracts、post-hoc 检查），而非仅靠模型改进。
2. 跨会话持久化
当前架构有两层持久化：静态指令（CLAUDE.md）和单会话转录（JSONL）。两者之间缺少一层：既不是静态指令也不是单会话转录的持久状态。记忆文献正在将 Agent 记忆视为独立的认知基底而非上下文窗口管理的副作用。
3. Harness 边界演进
Agent 交互正在向四个方向扩展：何时（proactive/ambient）、何地（beyond terminal）、做什么（VLA/物理动作）、与谁（多 Agent 协作）。单一 harness 架构能否覆盖所有四个扩展，还是会碎片化为专用栈，是开放问题。
4. 长程扩展
从单会话到科学程序级别的长程任务。orchestration-as-code 是否会成为主导的长程原语？其 token 成本和减少的人类中途监督如何与可靠性增益权衡？
5. 治理与监督
新兴 AI 法规为架构添加了外部约束。EU GPAI Code of Practice、MIT AI Agent Index、International AI Safety Report 都在推动文档化、风险管理、透明度和监督的更明确期望。当前架构是否充分暴露了日志和人类监督的接口？
6. 长期开发者能力
这是论文最深刻的关切。Anthropic 自己的 132 人工程师调研记录了"监督悖论"：过度依赖 AI 可能导致监督它所需的技能萎缩。独立研究发现 AI 辅助条件下的开发者在理解测试中得分低 17%。当前架构没有任何机制显式支持长期人类改进和深度理解。
启示与思考
这篇论文对 Agent 系统设计者有几个直接启示。
Harness 比模型更重要。 持有模型不变、仅改变周围 harness 就能在长程任务上造成 18 分的差异。这意味着投资确定性基础设施（上下文管理、安全分层、恢复机制）可能比在模型周围添加规划脚手架带来更大的可靠性收益。
安全不能依赖人类警觉。 93% 的审批批准率意味着逐动作交互确认在行为上不可靠。Claude Code 的回应不是加更多警告，而是在有界范围内让 Agent 自由行动，同时用独立的纵深防御层（deny-first + 沙箱 + 分类器）维持安全。这对 AARM 框架的意图授权层设计有直接参考价值。
同一设计问题在不同部署场景下有不同答案。 Claude Code 的逐动作安全分类在 CLI 编码场景中合理，OpenClaw 的边界级访问控制在多通道网关场景中合理，Hermes 的多面审批渲染在单进程多面场景中合理。不存在唯一正确答案，关键是在设计时明确回答这些反复出现的问题。
透明文件式记忆是一个可复现的模式。 三个系统都选择了用户可检查、可版本控制的文件式记忆而非不透明数据库或嵌入索引。这反映了可审计性优先于查询能力的共同价值取向。
长期开发者能力是被忽视的设计维度。 当前所有 Agent 架构都在放大短期能力，但没有一个显式支持长期人类改进。这在 Agent 越来越自主时会成为核心矛盾——监督 Agent 所需的技能可能正是 Agent 代替最多的技能。
这篇论文的价值不在于提出新方法或新 benchmark，而在于为 Agent 架构设计提供了一套共同语言：五个价值、十三条原则、七个组件、五层分解、六个维度。有了这套语言，不同 Agent 系统之间的对比不再是印象式的，而是可以沿着具体的设计问题逐一定位差异和原因。