深入 Claude Code：当今与未来 AI 智能体系统的设计空间

Jiacheng Liu¹，Xiaohan Zhao¹，Xinyi Shang¹,²，Zhiqiang Shen¹,†

¹VILA Lab，Mohamed bin Zayed University of Artificial Intelligence，²University College London
†通讯作者

Claude Code 是一种智能体式编码工具，能够代表用户运行 shell 命令、编辑文件并调用外部服务。本研究通过分析公开可获得的 TypeScript 源代码，描述其综合架构，并进一步将其与 OpenClaw 进行比较。OpenClaw 是一个独立的开源 AI 智能体系统，它从不同的部署语境出发，回答了许多相同的设计问题。我们的分析识别出五种驱动该架构的人类价值、理念与需求：人的决策权威、安全与安全性、可靠执行、能力放大，以及上下文适应性；并将它们通过十三项设计原则追踪到具体实现选择。系统的核心是一个简单的 while 循环：调用模型、运行工具，然后重复。然而，大部分代码并不在这个循环本身，而是在围绕该循环的系统中：一个包含七种模式和基于机器学习分类器的权限系统，一个用于上下文管理的五层压缩流水线，四种扩展机制（MCP、插件、技能和钩子），一个子智能体委派与编排机制，以及面向追加的会话存储。与 OpenClaw——一个多通道个人助理网关——的比较表明，当部署语境发生变化时，相同的反复出现的设计问题会产生不同的架构答案：从逐动作安全评估到边界级访问控制，从单一 CLI 循环到嵌入网关控制平面的运行时，从上下文窗口扩展到网关范围的能力注册。最后，我们基于近期的实证、架构与政策文献，识别出未来智能体系统的六个开放设计方向。

我们的 GitHub 地址为：https://github.com/VILA-Lab/Dive-into-Claude-Code。

通讯作者：Zhiqiang Shen（[email protected]）

a v2.1.88，链接。免责声明：本文所使用的全部材料均来自公开可获得的在线来源。我们没有使用任何私有、机密或未经授权的材料，也无意侵犯任何版权或知识产权。源代码的原始知识产权归 Anthropic 所有。

1 引言

AI 辅助软件开发已经从 GitHub Copilot（Chen et al., 2021）这样的自动补全式工具，发展到 Cursor（Cursor, 2026）这样的 IDE 集成助手，再发展到完全智能体式的系统：这类系统能够自主规划多步骤修改、执行 shell 命令、读写文件，并对自己的输出进行迭代。Claude Code（Anthropic, 2026a）是 Anthropic 发布的一种智能体式编码工具（Anthropic, 2026c）。其官方文档将其描述为一种“智能体循环”：它会为了完成目标而规划并执行动作，可以调用工具、评估结果，并持续运行直到任务完成¹。从“给出建议”到“自主行动”的转变，引入了基于补全的工具所不具备的架构需求。这些需求定义了一个设计空间，即每一个编码智能体都必须处理的一组反复出现的问题，涵盖安全、上下文管理、可扩展性、委派等主题。本研究通过对 Claude Code 的源码级分析，展示一个生产系统如何回答这些问题。

尽管 Claude Code 的采用率不断增长，Anthropic 发布的是面向用户的文档，而非详细的架构描述。本研究使用源代码分析来描述其架构设计决策。Anthropic 对 132 名工程师和研究人员进行的内部调查（Huang et al., 2025）报告称，约 27% 由 Claude Code 辅助完成的任务，是如果没有该工具就不会被尝试的工作。这表明该架构所启用的不只是加速既有工作流，而是定性上新的工作流。

¹ https://code.claude.com/docs/en/how-claude-code-works.

在本文中，我们首先识别出驱动该架构的五种人类价值/理念和十三项设计原则（第 2 节），然后将分析组织为三个部分：

  1. 设计空间分析。 我们识别反复出现的设计问题：推理应位于何处、迭代循环如何组织、应采用何种安全姿态、扩展表面如何划分、上下文如何管理、工作如何在子智能体之间委派，以及会话如何持久化。随后，我们通过 7 组件高层结构和 5 层子系统架构来分析 Claude Code 的答案，并将每个选择追踪到具体源码文件（第 3 节）。该分析旨在建立对系统机制的深入理解，从而为设计更好、更强大的智能体系统提供参考。

  2. 与 OpenClaw 的架构对比。 除了分析 Claude Code 本身，我们还将其设计哲学与开源智能体系统 OpenClaw（Steinberger and OpenClaw Contributors, 2026）进行比较。OpenClaw 是一个多通道个人助理网关。我们在六个设计维度上对二者进行比较，以展示相同的反复出现的问题如何在不同部署语境下产生不同答案（第 10 节），从而突出商业软件与开源软件之间的共同原则和关键差异。这一比较有助于揭示部署环境、产品目标、安全需求和用户假设如何以不同方式塑造架构选择。通过考察这些系统在何处趋同、何处分化，本研究旨在为未来更强大的智能体系统设计提供有用指导与实践洞见。

  3. 未来智能体系统的开放方向。 基于设计空间分析和与 OpenClaw 的对比，第 12 节识别出六个开放方向，涵盖可观测性-评估缺口、跨会话持久性、运行框架边界演进、视野扩展、治理以及评估性视角；每个方向都借鉴了实证、架构和政策文献。作为一种评估性视角使用时，我们的研究还揭示了一个开放问题：虽然 Claude Code 智能体系统显著放大了程序员和终端用户的短期能力，但它提供的机制有限，无法明确支持长期的人类改进、更深入的理解以及持续的代码库一致性。

核心智能体循环是一个带有状态管理的 while-true 循环。围绕该循环的安全、可扩展性、上下文管理、委派和持久化子系统构成了实现的大部分。源码级分析²使我们能够直接从系统本身识别设计选择、子系统边界和实现权衡，而不是仅仅从产品描述中推断它们。

贯穿示例。 为了使架构分析更具体，我们将在第 3 节到第 9 节中追踪任务“修复 auth.test.ts 中失败的测试”。这个例子说明了一个看似简单的用户请求如何激活多个架构层，包括工具调用、权限检查、上下文选择、迭代式修复、委派和会话持久化。

论文组织。 第 2 节识别驱动该架构的人类价值和设计原则。第 3 节介绍高层架构及其回答的设计问题。第 4 节到第 9 节分别分析一个主要子系统的设计选择。第 10 节将该分析与 OpenClaw 进行对比，第 11 节展开讨论，第 12 节调研未来智能体系统的开放问题。第 13 节和第 14 节分别覆盖相关工作和结论。附录 B 描述证据基础和方法论。

² 我们的分析主要基于源代码，并辅以 Anthropic 官方文档和部分社区分析；附录 B 详细说明证据基础和方法论。

2 设计哲学、设计原则与架构动机

生产级编码智能体由人构建、为人服务，其所嵌入的架构决策反映了创建者认为重要的东西。本节识别驱动 Claude Code 设计的人类价值，将这些价值追踪到反复出现的设计原则，并界定组织第 3 节到第 9 节分析的设计空间问题。

Anthropic 的安全智能体框架指出了一个核心张力：“智能体必须能够自主工作；它们的独立运行恰恰是其有价值之处。但人类应当保留对其目标实现方式的控制权”（Anthropic, 2025a）。Claude 的宪法不是通过刚性的决策程序来解决这一点，而是通过培养“能够在上下文中应用的良好判断和健全价值观”（Anthropic, 2026b）来解决。结合关于开发者实际如何使用该工具的实证发现（Huang et al., 2025; McCain et al., 2026），这些承诺指向了塑造该架构的五种人类价值。

2.1 五种价值与理念

人的决策权威。 人类保留对系统行为的最终决策权，这通过一个主体层级来组织：Anthropic、然后是操作者、然后是用户；该层级形式化地规定了谁对什么拥有权威（Anthropic, 2026b）。系统被设计成使人类能够进行知情控制：他们可以实时观察动作，批准或拒绝拟议操作，中断兼容的进行中操作，并在事后审计。当 Anthropic 发现用户会批准 93% 的权限提示（Hughes, 2026）时，其回应不是增加更多警告，而是重构问题：定义边界（沙箱、自动模式分类器），让智能体在这些边界内自由工作，而不是依赖逐动作审批，因为用户在习惯之后会停止认真审查这些审批（Dworken and Weller-Davies, 2025）。

安全、安全性与隐私。 系统保护人类、他们的代码、他们的数据和他们的基础设施免受伤害，即使人类注意力不足或犯错也应如此。这不同于人的决策权威：权威关乎人类选择的权力，而安全关乎系统即使在该权力失效时也有保护义务。Anthropic 的安全智能体框架将保障智能体交互安全和在长期交互中保护隐私分别识别为核心承诺（Anthropic, 2025a）。自动模式威胁模型（Hughes, 2026）明确针对四类风险：过度积极行为、诚实错误、提示注入和模型不对齐。

可靠执行。 智能体应当完成用户真正想要的事情，在时间上保持一致，并支持在宣告成功之前验证其工作。该价值既涵盖单轮正确性（它是否忠实理解了请求？），也涵盖长视野可靠性（它是否能在上下文窗口边界、会话恢复和多智能体委派中保持一致？）。Anthropic 的产品文档（Anthropic, 2026d）描述了智能体会重复执行直到任务完成的三阶段循环：收集上下文、采取行动、验证结果。智能体设计指南（Schluntz and Zhang, 2024）进一步强调，每一步来自环境的“真实依据”用于评估进展。运行框架设计指南（Rajasekaran, 2026）同样指出，即使质量平庸，“智能体也倾向于自信地称赞工作”，这促使生成与评估相分离。

能力放大。 系统实质性提高人类在单位努力和成本下能够完成的事情。第 1 节讨论的 Anthropic 内部调查（Huang et al., 2025）表明，该架构所启用的是定性上新的工作流，而不只是更快地完成既有工作：约 27% 的任务代表了如果没有该工具就不会被尝试的工作。其创建者将该系统描述为“一个 Unix 实用工具，而不是传统产品”，它由“有用、可理解、可扩展”的最小构建块组成（Cherny and Wu, 2025）。该架构投资于确定性基础设施（上下文管理、工具路由、恢复），而不是决策脚手架（显式规划器或状态图），其前提是：能力越来越强的模型，相比受到框架约束，更能从丰富的操作环境中受益。

上下文适应性。 系统适配用户的具体上下文，包括他们的项目、工具、约定和技能水平，并且这种关系会随时间改善。扩展架构（CLAUDE.md、技能、MCP、钩子、插件）在多个上下文成本层级上提供可配置性（第 6 节和第 7 节）。纵向数据（McCain et al., 2026）显示，人类-智能体关系会演化：自动批准率从少于 50 个会话时的约 20%，增加到 750 个会话时的 40% 以上。这一模式被描述为由“模型、用户和产品共同构建”的自主性，意味着系统被设计为面向信任轨迹，而不是固定的信任状态。MCP 捐赠给 Linux Foundation 的 Agentic AI Foundation（The Linux Foundation, 2025）反映了该价值的生态系统维度。

表 1 设计原则、其服务的价值，以及每项原则回答的设计空间问题

原则服务的价值设计问题章节
拒绝优先并升级给人类权威、安全未识别的动作应被允许、阻止，还是升级给人类？5, 8, 9
分级信任谱系权威、适应性是固定权限级别，还是用户会随时间穿越的谱系？5
通过分层机制实现纵深防御安全、权威、可靠性是单一安全边界，还是使用不同技术的多个重叠边界？3, 5
外部化的可编程策略安全、权威、适应性是硬编码策略，还是带生命周期钩子的外部化配置？5, 6
将上下文视为稀缺资源并渐进式管理可靠性、能力绑定资源约束是什么，以及如何管理它：单次截断，还是分级流水线？4, 6, 7, 8
仅追加的持久状态可靠性、权威可变状态、检查点快照，还是仅追加日志？4, 9
最小脚手架，最大操作运行框架能力、可靠性投资于脚手架侧推理，还是投资于让模型自由推理的操作基础设施？3, 4
价值胜于规则能力、权威是刚性的决策程序，还是由确定性护栏支持的上下文判断？3, 5, 7
可组合的多机制可扩展性能力、适应性是一个统一的扩展 API，还是位于不同上下文成本层级的分层机制？6
按可逆性加权的风险评估能力、安全所有动作都采用相同监督，还是对可逆和只读动作采用更轻监督？4, 5, 8
透明的基于文件的配置与记忆适应性、权威是不透明数据库、基于嵌入的检索，还是用户可见且可版本控制的文件？7
隔离的子智能体边界可靠性、安全、能力子智能体共享父级上下文和权限，还是在隔离中运行？8
优雅恢复与韧性可靠性、能力遇到错误时硬失败，还是静默恢复并将人类注意力保留给不可恢复的情况？4, 5

2.2 设计原则

这些价值通过十三项设计原则被操作化，每项原则都回答生产级编码智能体必须解决的一个反复出现的问题。表 1 总结了这些原则；后续章节（第 3 节到第 9 节）将把每项原则追踪到具体实现选择。

这些原则可以与三类主要替代设计家族进行对照。第一类是基于规则的编排：例如 LangGraph（LangChain, Inc., 2024）这样的框架将决策逻辑编码为带有类型化边的显式状态图，选择脚手架而非最小运行框架。第二类是容器隔离执行：SWE-Agent 和 OpenHands（Yang et al., 2024; Wang et al., 2024b）依赖 Docker 隔离，而不是分层策略执行。第三类是以版本控制作为安全机制：Aider（Gauthier, 2024）等工具使用 Git 回滚作为主要安全机制，而不是拒绝优先评估。Claude Code 的原则集具有独特性：它将最小决策脚手架与分层策略执行结合起来，将基于价值的判断与拒绝优先默认值结合起来，并将渐进式上下文管理与可组合扩展性结合起来。

2.3 从价值到架构

每一种价值都会通过其原则追踪到具体架构决策： Pasted image 20260525170148

图 1 Claude Code 的高层系统结构。 该系统分解为七个功能组件：用户、接口、智能体循环、权限系统、工具、状态与持久化，以及执行环境。所有入口表面都汇聚到同一个智能体循环。

  • 人的决策权威促成了拒绝优先评估、分级信任谱系、仅追加状态（可审计历史）、外部化的可编程策略，以及价值胜于规则（第 5 节到第 7 节和第 9 节）。

  • 安全、安全性与隐私促成了纵深防御、拒绝优先默认值、按可逆性加权的评估、外部化策略，以及隔离的子智能体边界（第 5 节和第 8 节）。

  • 可靠执行促成了将上下文视为稀缺资源、仅追加持久状态、优雅恢复、隔离的子智能体边界，以及纵深防御（第 4 节和第 7 节到第 9 节）。

  • 能力放大促成了最小脚手架、可组合扩展性、按可逆性加权的风险、上下文管理，以及优雅恢复（第 4 节到第 6 节）。

  • 上下文适应性促成了透明的基于文件的记忆、可组合扩展性、分级信任谱系，以及外部化的可编程策略（第 5 节到第 7 节）。

这些映射也揭示了该架构没有做什么：它没有把显式规划图强加到模型推理上，没有提供单一统一的扩展机制，也没有在恢复时还原所有会话级、与信任相关的状态。这些缺席与上述原则集是一致的。

2.4 一种评估性视角：长期能力保存

上述五种价值描述了该架构旨在服务什么。本文还将第六个关切——该架构是否保存长期人类能力——作为一种评估性视角。这个关切是真实存在的：Anthropic 自己对 132 名工程师和研究人员的研究（Huang et al., 2025）记录了一个“监督悖论”，即过度依赖 AI 可能使监督 AI 所需的技能萎缩；独立研究（Shen and Tamkin, 2026）发现，在 AI 辅助条件下，开发者在理解测试中的得分低 17%。然而，这一关切并未作为设计驱动因素明显体现在该架构或 Anthropic 所声明的设计价值中。因此，我们不将其视为与其他价值并列的共同价值，而是将其作为一个横切性关切：这是第 11 节中应用于全部五种价值的问题，即短期能力放大是否以长期的人类理解、代码库一致性和开发者培养通道为代价。

3 架构概览

构建一个生产级编码智能体需要回答几个反复出现的设计问题：推理应当位于何处，需要多少个执行引擎，应采用什么样的安全姿态，以及应将哪种资源视为绑定约束。Claude Code 的架构可以被理解为对这些问题的一组回答。在实现层面，该系统由七个组件组成，并通过一条主数据流连接起来：用户通过若干接口之一提交提示，该提示进入一个共享的智能体循环。智能体循环组装上下文，调用 Claude 模型，接收可能包含工具使用请求的响应，将这些请求路由到权限系统，并将获批准的动作分发给与执行环境交互的具体工具。在整个过程中，状态与持久化机制会记录对话转录、管理会话身份，并支持恢复、分叉和回退操作。

3.1 设计问题与贯穿示例

本描述围绕四个在生产级编码智能体中反复出现的设计问题组织，每个问题都支撑表 1 中识别出的一项或多项设计原则。这里会先介绍每个问题以及 Claude Code 的回答，再说明可能的替代方案，并在第 4 节到第 9 节中逐步演示。

推理位于何处？ 在 Claude Code 中，模型负责推理要做什么；运行框架负责执行动作。模型将 tool_use 块作为其响应的一部分发出，运行框架解析这些块、检查权限、将其分发给工具实现，并收集结果（query.ts）。模型从不直接访问文件系统、运行 shell 命令或发起网络请求。这种分离具有安全后果：由于推理和执行强制机制位于不同代码路径中，被攻陷或受到对抗性操纵的模型无法覆盖运行框架中实现的沙箱、权限检查或拒绝优先规则。模型通向外部世界的唯一接口是结构化的 tool_use 协议，而运行框架会在执行前对其进行验证。社区对提取源码的分析估计，Claude Code 代码库中只有约 1.6% 构成 AI 决策逻辑，其余 98.4% 是操作基础设施；这一比例说明核心智能体推理层非常薄。替代设计则在脚手架侧推理上投入更多：Devin 维护显式规划和任务跟踪结构，而 LangGraph（LangChain, Inc., 2024）通过开发者定义的状态图来路由控制流。

需要多少个执行引擎？ Claude Code 使用单一的 queryLoop() 函数，无论用户是通过交互式终端、无头 CLI 调用、Agent SDK，还是 IDE 集成进行交互，该函数都会执行（query.ts）。变化的只有渲染层和用户交互层。其他系统使用特定模式的引擎：例如，IDE 集成可能遵循不同于 CLI 工具的代码路径，以牺牲统一性换取针对特定表面的优化。

默认安全姿态是什么？ Claude Code 的默认安全姿态是拒绝优先并升级给人类：拒绝规则覆盖询问规则，询问规则覆盖允许规则，未识别的动作会升级给用户，而不是静默允许（permissions.ts）。多个独立安全层（权限规则、PreToolUse 钩子、启用时的自动模式分类器，以及可选 shell 沙箱）并行应用，因此其中任意一层都可以阻止某个动作（第 5 节）。这结合了表 1 中的“拒绝优先并升级给人类”和“通过分层机制实现纵深防御”两项原则。替代方法会将信任边界转移到其他地方：SWE-Agent 和 OpenHands（Yang et al., 2024; Wang et al., 2024b）依赖基于容器的隔离来约束任意执行，而 Aider（Gauthier, 2024）将基于 Git 的回滚作为其主要安全网。

绑定资源约束是什么？ 在 Claude Code 中，上下文窗口是绑定资源约束：较旧模型为 200K，Claude 4.6 系列为 1M。每次模型调用前，都会执行五种不同的上下文削减策略（query.ts），并且若干其他子系统决策（指令懒加载、延迟工具模式、子智能体仅返回摘要）也都是为了限制上下文消耗（第 7 节）。五层流水线之所以存在，是因为没有任何单一压缩策略能够处理全部类型的上下文压力。预算削减针对超过大小限制的单个工具输出。Snip 处理时间深度。Microcompact 响应缓存开销。Context collapse 管理非常长的历史。Auto-compact 作为最后手段执行语义压缩。每一层都在不同的成本-收益权衡点上运行，并且更早、更便宜的层会先于成本更高的层执行。替代架构则将其他资源视为主要瓶颈，例如计算预算（限制模型调用或工具调用次数）或工作记忆（维护显式草稿区，而不是依赖对话历史）。

贯穿示例。 为了使这些原则具体化，我们会在第 3 节到第 9 节中贯穿一个单一任务：“修复 auth.test.ts 中失败的测试。”在本节中，用户通过 Claude Code 的某个接口提交提示。后续章节会追踪该请求如何经过查询循环、权限门、工具池、上下文窗口、子智能体委派和会话持久化。 Pasted image 20260525170322 图 2 单次运行时回合流程。 用户提示进入上下文组装，模型被调用，工具请求经过权限门，工具结果反馈回循环，并由压缩机制管理上下文压力。

3.2 高层系统结构

七组件模型（图 1）直接映射到源码文件：

  1. 用户： 提交提示、批准权限、审查输出。
  2. 接口： 交互式 CLI、无头 CLI（claude -p）、Agent SDK，以及 IDE/Desktop/Browser。所有表面都会进入同一个循环。
  3. 智能体循环： 模型调用、工具分发和结果收集的迭代周期，在 query.ts 中实现为 queryLoop() 异步生成器。
  4. 权限系统： 拒绝优先规则评估（permissions.ts）、自动模式 ML 分类器，以及基于钩子的拦截（types/hooks.ts）。
  5. 工具： 最多 54 个内置工具，其中 19 个无条件包含，35 个根据功能标志和用户类型有条件包含。这些工具通过 assembleToolPool()（tools.ts）组装，并与 MCP 提供的工具合并。插件通过 MCP 服务器和技能/命令注册表间接贡献工具。
  6. 状态与持久化： 主要是仅追加的 JSONL 会话转录（sessionStorage.ts）、全局提示历史（history.ts），以及子智能体 sidechain 文件。
  7. 执行环境： 带可选沙箱的 shell 执行（shouldUseSandbox.ts）、文件系统操作、Web 获取、MCP 服务器连接，以及远程执行。

数据流遵循一条从左到右的主干：用户通过某个接口提交请求，请求进入智能体循环。循环向权限系统提出动作；获批准的动作到达工具，工具与执行环境交互，并将 tool_result 消息返回给循环。状态与持久化位于循环旁侧，负责记录转录并加载先前会话数据。

main.tsx 中的应用入口点 main() 初始化安全设置，包括 NoDefaultCurrentDirectoryInExePath，以防止 Windows PATH 劫持；随后注册用于优雅关闭的信号处理器，并分发到合适的执行模式。

3.3 分层子系统分解

五层分解（图 3）将七组件模型扩展为更细粒度的视图，并将每一层映射到具体源码目录。

图 3 扩展后的分层架构。 该图展示五个子系统层：表面层（Interactive CLI、Headless CLI、Agent SDK、IDE/Desktop/Browser、UI/renderer）、核心层（智能体循环、压缩流水线）、安全/动作层（权限系统，包括自动模式分类器、钩子流水线、可扩展性、内置工具、MCP 工具、shell 沙箱、子智能体生成）、状态层（上下文组装、运行时状态、会话持久化、CLAUDE.md + 记忆、sidechain 转录），以及后端层（执行后端、外部资源）。

表面层（入口点与渲染）。 src/entrypoints/ 目录包含启动路径，包括带有 coreTypes.ts、controlSchemas.ts 和 coreSchemas.ts 的 SDK 入口。src/screens/ 目录组合全屏布局，src/components/ 则通过 ink 框架提供终端 UI 构建块。交互式 CLI 启动一个终端 UI，带有实时流式输出、权限对话框和进度指示器。无头 CLI（claude -p）创建一个 QueryEngine 实例，用于单次处理。Agent SDK 通过异步生成器发出类型化事件。

核心层（智能体循环、压缩流水线）。 queryLoop() 异步生成器（query.ts）实现迭代式智能体循环，它消费来自状态层的组装上下文，并将工具请求分发给安全/动作层。每次模型调用前，五个顺序执行的塑形器组成一个压缩流水线（query.ts:365–453），用于管理上下文压力：预算削减、snip、microcompact、context collapse 和 auto-compact（第 4.3 节和第 7.3 节）。

安全/动作层（权限系统、钩子、可扩展性、工具、沙箱、子智能体）。 权限系统（permissions.ts）实现拒绝优先规则评估，最多包含七种权限模式，如果也计算内部专用的 bubble 和由功能标志控制的 auto（types/permissions.ts）；同时还集成了自动模式 ML 分类器（yoloClassifier.ts），该分类器对工具安全性进行两阶段快速过滤和思维链评估（第 5 节）。跨越 27 种事件类型的钩子流水线（coreTypes.ts；输出模式在 types/hooks.ts 中）可以阻止、重写或注释工具请求；其中 5 种与安全相关，其余 22 种服务于生命周期和编排目的（第 6 节）。扩展子系统允许插件和技能将工具与钩子注册到运行时中。通过 assembleToolPool()（tools.ts）进行的工具池组装，会合并内置工具和 MCP 提供的工具。获批准的 shell 命令会经过 shell 沙箱（shouldUseSandbox.ts），该沙箱独立于权限系统限制文件系统和网络访问。通过 AgentTool（AgentTool.tsx、runAgent.ts）生成子智能体时，也会经由与所有其他工具相同的 buildTool() 工厂进行分发，随后以隔离的上下文窗口重新进入 queryLoop()，并只向父级返回摘要（第 8 节）。

状态层（上下文组装、运行时状态、持久化、记忆、sidechains）。 上下文组装是一个带记忆化的状态加载器，而不是路由中心：getSystemContext()（context.ts）计算会话级系统上下文，包括 git 状态；getUserContext()（context.ts）加载 CLAUDE.md 层级和当前日期。二者都会被缓存以便复用：系统上下文会附加到系统提示中，而用户上下文会作为用户上下文消息加入。src/state/ 目录管理运行时应用状态。会话转录以基本仅追加的 JSONL 文件形式存储在项目特定路径中（sessionStorage.ts）。CLAUDE.md + 记忆子系统提供四层指令层级（claudemd.ts），从托管设置到目录特定文件，以及 Claude 在对话期间写入的自动记忆条目（第 7.2 节）。Sidechain 转录（sessionStorage.ts:247）将每个子智能体的对话存储在单独文件中，防止子智能体内容膨胀父级上下文（第 8.3 节）。全局提示历史维护在 history.jsonl 中（history.ts）。恢复和分叉操作从转录中重建会话状态（conversationRecovery.ts）。

后端层（执行后端、外部资源）。 带可选沙箱的 shell 命令执行（BashTool.tsx、PowerShellTool.tsx）、远程执行支持（src/remote/）、跨多种传输变体的 MCP 服务器连接，包括 stdio、SSE、HTTP、WebSocket、SDK 和 IDE 专用适配器（services/mcp/client.ts），以及 src/tools/ 中 42 个工具子目录实现了具体工具逻辑。

3.4 QueryEngine：一个澄清

QueryEngine.ts 中的类文档写道：“QueryEngine 拥有一次对话的查询生命周期和会话状态。它将核心逻辑从 ask() 中提取到一个独立类中，该类可由无头/SDK 路径使用，并在未来阶段由 REPL 使用。”该类是非交互式表面的对话包装器，而不是引擎本身。它的构造函数接受一个 QueryEngineConfig，其中包含初始消息、abort controller、文件状态缓存，以及其他每次对话的状态。其 submitMessage() 方法是一个异步生成器，用于编排单个回合。共享查询路径位于 query()（query.ts）中，后者包装了内部的 queryLoop()；QueryEngine 会委托给 query()。

这一点在架构上很重要：交互式 CLI 也会调用 query()，完全绕过 QueryEngine。共享代码路径是循环函数，而不是引擎类。

3.5 权限与安全层

默认安全原则通过七个独立层实现。请求必须通过所有适用层，任一单层都可以阻止它：

  1. 工具预过滤（tools.ts）： 被整体拒绝的工具会在任何调用之前从模型视野中移除，防止模型尝试调用它们。
  2. 拒绝优先规则评估（permissions.ts）： 拒绝规则总是优先于允许规则，即使允许规则更具体也是如此。
  3. 权限模式约束（types/permissions.ts）： 当前激活的模式决定了对于未匹配任何显式规则的请求，其基线处理方式。
  4. 自动模式分类器： 基于 ML 的分类器评估工具安全性，并可能拒绝规则系统本会允许的请求。
  5. Shell 沙箱（shouldUseSandbox.ts）： 已获批准的 shell 命令仍可能在沙箱中执行，从而限制文件系统和网络访问。
  6. 恢复时不还原权限（conversationRecovery.ts）： 会话级权限在恢复或分叉时不会被还原。
  7. 基于钩子的拦截（types/hooks.ts）： PreToolUse 钩子可以修改权限决策；PermissionRequest 钩子可以与用户对话框并行异步解析决策，或者在协调器模式中先于用户对话框解析。

这些层会在第 5 节详细描述。

3.6 作为瓶颈的上下文：超越压缩

除了五层压缩流水线（第 7 节详述）之外，若干其他子系统决策也反映了“上下文即瓶颈”这一约束：

  • CLAUDE.md 懒加载： 基础 CLAUDE.md 层级会在会话开始时加载，但额外的嵌套目录指令文件和条件规则只会在智能体读取这些目录中的文件时加载，从而防止未使用的指令消耗上下文。
  • 延迟工具模式： 当启用 ToolSearch 时，一些工具在初始上下文中只包含名称；完整模式会按需加载。
  • 子智能体仅返回摘要： 子智能体只向父级返回摘要文本，而不是完整对话历史（第 8 节）。
  • 按工具结果设置预算： 单个工具结果会被限制在可配置大小内，防止某个冗长输出消耗不成比例的上下文。

4 回合执行：智能体式查询循环

当用户提交“修复 auth.test.ts 中失败的测试”时，输入会进入一个响应式循环，这是编码智能体若干可能编排模式之一。本节考察 Claude Code 对简单 while 循环架构的选择，并端到端追踪该循环中的一个回合，说明表 1 中的三项设计原则：最小脚手架与最大操作运行框架、将上下文视为稀缺资源并进行渐进式管理，以及优雅恢复与韧性。

4.1 查询流水线

每个回合都遵循一个固定序列（图 2，query.ts）：

  1. 设置解析。 queryLoop() 函数解构不可变参数，包括系统提示、用户上下文、权限回调和模型配置。
  2. 可变状态初始化。 单个 State 对象存储跨迭代的全部可变状态，包括消息、工具上下文、压缩跟踪和恢复计数器。该循环的七个继续点（“continue sites”）都会通过一次整体对象赋值覆盖该对象，而不是逐个字段地进行变异。
  3. 上下文组装。 getMessagesAfterCompactBoundary() 函数从最后一个 compact 边界之后取回消息，确保压缩后的内容由其摘要表示，而不是由原始消息表示。
  4. 模型前上下文塑形器。 五个塑形器顺序执行（第 4.3 节）。
  5. 模型调用。 对 deps.callModel() 的 for await 循环会流式接收模型响应，并传入组装后的消息（前置用户上下文）、完整系统提示、thinking 配置、可用工具集、abort 信号、当前模型规格，以及其他选项，包括 fast-mode 设置、effort 值和 fallback 模型。
  6. 工具使用分发。 如果响应包含 tool_use 块，它们会流向工具编排层（第 4.2 节）。
  7. 权限门。 每个工具请求都会经过权限系统（第 5 节）。
  8. 工具执行与结果收集。 工具结果会作为 tool_result 消息加入对话，然后循环继续。
  9. 停止条件。 如果响应不包含 tool_use 块，即仅包含文本，则该回合完成。

queryLoop() 函数被定义为一个 AsyncGenerator，在执行过程中会产生 StreamEvent、RequestStartEvent、Message、TombstoneMessage 和 ToolUseSummaryMessage 事件。这种基于生成器的设计，使系统能够向 UI 层流式输出，同时在循环内部维持单一同步控制流。

Claude Code 的响应式循环遵循 ReAct 模式（Yao et al., 2022）：模型生成推理和工具调用，运行框架执行动作，结果反馈到下一次迭代。替代编排模式包括显式的基于图的路由（LangChain, Inc., 2024），其中控制流被定义为带类型化边的状态机；以及树搜索方法（Zhou et al., 2023），这类方法会在提交之前探索多个动作轨迹。Anthropic 自己的文档（Schluntz and Zhang, 2024）识别出五种可组合工作流模式：提示链、路由、并行化、编排器-工作者，以及评估器-优化器。Claude Code 主要在子智能体委派中使用编排器-工作者模式（第 8 节），同时保持核心循环为响应式。响应式设计用搜索完整性换取简单性和延迟：每个回合都会提交到一个动作序列，而不会回溯。

4.2 工具分发与流式执行

当模型响应包含 tool_use 块时，系统会在两个执行路径之间选择。主路径使用 StreamingToolExecutor，它会在工具从模型响应中流式出现时就开始执行，从而降低多工具响应的延迟。备用路径使用 toolOrchestration.ts 中的 runTools()，该函数会遍历由 partitionToolCalls() 生成的分区。两个路径都会将工具分类为可并发安全或排他。只读操作可以并行执行，而会修改状态的操作，如 shell 命令，则会被串行化。

StreamingToolExecutor（StreamingToolExecutor.ts）通过两种协调机制管理并发执行：

  • 兄弟 abort controller。 当任何 Bash 工具报错时触发，立即终止其他正在运行的子进程，而不是让它们运行到完成。
  • 进度可用信号。 当新输出准备好时，唤醒 getRemainingResults() 消费者。

结果会被缓冲，并按照工具接收顺序发出，因此即使工具并行运行，输出顺序仍保持一致。这一点很重要，因为模型期望工具结果与其工具使用请求保持相同顺序。这种“并发读、串行写”的执行模型，位于完全串行分发与更激进的推测方法之间。例如 PASTE（Sui et al., 2026）会在模型仍在生成时，推测性地预执行预测的未来工具调用，以通过推测隐藏工具延迟。

工具结果收集阶段会遍历来自流式执行器或同步 runTools() 生成器的更新。每次更新可能携带一个工具结果、一个附件，或一个进度事件。一个特殊检查会检测 hook_stopped_continuation 附件：如果某个 PostToolUse 钩子发出不应继续该回合的信号，shouldPreventContinuation 标志就会被设置。结果会通过 normalizeMessagesForAPI() 被规范化为 Anthropic API 格式，该函数会过滤并只保留用户类型消息。

4.3 模型前上下文塑形器

每次模型调用之前，五个上下文塑形器会在 query.ts 中顺序执行，每个都作用于 messagesForQuery 数组。这五个塑形器按顺序运行，较早步骤会先应用较轻量的削减，随后步骤再应用更宽泛的压缩。

预算削减。（applyToolResultBudget()）。对工具结果强制执行按消息大小限制，将过大的输出替换为内容引用。豁免工具，即 maxResultSizeChars 非有限值的工具，会保留完整输出。对于 agent 和 session 查询源，内容替换会被持久化，以便在恢复时重建。预算削减运行在 microcompact 之前，因为 microcompact 纯粹通过 tool_use_id 工作，从不检查内容；二者可以干净地组合。

Snip。（snipCompactIfNeeded()，由 HISTORY_SNIP 控制）。一种轻量级裁剪，会移除较旧的历史片段，并返回 {messages, tokensFreed, boundaryMessage}。snipTokensFreed 值会被传递给 auto-compact，因为主 token 计数器会从最近一条 assistant 消息上的 usage 字段推导上下文大小，而该消息在 snip 后仍然保留，并且其预 snip 的 input_tokens 仍然附着其上；因此，除非显式传入，否则 snip 节省的 token 对计数器不可见。

Microcompact。 细粒度压缩，总是运行基于时间的路径，并可选运行缓存感知路径（由 CACHED_MICROCOMPACT 控制）。当启用缓存路径时，边界消息会被延迟到 API 响应之后再生成，这样它们就可以使用实际的 cache_deleted_input_tokens，而不是估计值。返回 {messages, compactionInfo}，其中 compactionInfo 可能包含 pendingCacheEdits。

Context collapse。 由 CONTEXT_COLLAPSE 控制。它是对话历史上的读时投影。源码注释解释道：“不会 yield 任何内容；collapsed view 是 REPL 完整历史上的读时投影。摘要消息存在于 collapse store 中，而不是 REPL 数组中。这正是 collapse 能跨回合持久化的原因。”与其他塑形器不同，context collapse 不会变异 REPL 所存储的历史；它通过 applyCollapsesIfNeeded() 将 messagesForQuery 数组替换为投影视图，因此模型看到的是 collapse 版本，而完整历史仍可用于重建。

Auto-compact。 第五个塑形器，通过 compact.ts 中的 compactConversation() 触发完整的模型生成摘要。该函数执行 PreCompact 钩子，使用 getCompactPrompt() 创建摘要请求，并调用模型生成压缩摘要。结果会输入到 buildPostCompactMessages()（compact.ts）中。Auto-compact 只有在前四个塑形器全部运行之后，上下文仍超过压力阈值时才会触发。

4.4 恢复机制

查询循环为边缘情况实现了若干恢复机制：

  • 最大输出 token 升级： 当响应触及输出 token 上限时，系统可以使用升级后的限制重试，前提是 GrowthBook 标志允许，并且不存在已有 override 或环境变量上限。每个回合最多允许三次恢复尝试（MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3）。
  • 响应式压缩（由 REACTIVE_COMPACT 控制）： 当上下文接近容量上限时，响应式 compact 会总结刚好足够释放空间的内容。hasAttemptedReactiveCompact 标志确保每个回合最多触发一次。
  • 提示过长处理： 如果 API 返回 prompt_too_long 错误，循环会先尝试 context-collapse 溢出恢复和响应式压缩。只有在这些失败之后，才会以 reason: 'prompt_too_long' 终止。
  • 流式 fallback： onStreamingFallback 回调处理流式 API 问题，使循环能够使用不同策略重试。
  • Fallback 模型： fallbackModel 参数允许在主模型失败时切换到替代模型。

4.5 停止条件

多个条件可以终止循环：

  1. 无工具使用： 模型只生成文本内容，这是主要停止条件。
  2. 最大回合数： 达到可配置的 maxTurns 限制。
  3. 上下文溢出： API 返回 prompt_too_long。
  4. 钩子干预： 某个 PostToolUse 钩子设置 hook_stopped_continuation。
  5. 显式 abort： abortController 信号被触发。

回合流水线决定了工具请求如何被编排和恢复。下一节考察决定每个请求是否被允许执行的关口。

5 工具授权与控制边界

生产级编码智能体采用不同的安全架构：分层策略执行、操作系统级沙箱，或基于版本控制的回滚。Claude Code 将前两者结合起来，实现了表 1 中的四项设计原则：拒绝优先并升级给人类、分级信任谱系、通过分层机制实现纵深防御，以及按可逆性加权的风险评估。

当 Claude 决定执行某个工具时，例如通过 BashTool 运行 npm test 以复现 auth 测试失败，请求会进入图 4 所示的权限流水线。每一次工具调用都会经过权限系统，默认行为是拒绝或询问，而不是静默允许。这一默认值受到一个已记录的行为模式驱动：Anthropic 的自动模式分析（Hughes, 2026）发现，用户会批准约 93% 的权限提示，这表明如果把交互式确认作为唯一安全机制，批准疲劳会使其在行为上并不可靠。由于用户习惯性批准而不仔细审查，系统必须在不依赖人类警觉性的情况下维持安全。这推动了该架构对拒绝优先评估、整体拒绝预过滤，以及沙箱作为独立层的承诺；这些层无论用户是否专注，都会运行。 Pasted image 20260525170402 图 4 权限门概览与设计原则。

原则描述
渐进式信任智能体以最小自主性开始；用户通过批准工具调用来扩展其自主性，这些批准会成为永久规则。
拒绝优先，默认询问拒绝规则总是胜出，即使处于更宽松的模式下也是如此。如果没有规则匹配，权限门会询问用户，而不是静默运行或阻止。
可组合策略三种机制塑造策略：声明式规则、全局信任模式和可编程钩子；每种机制都可以独立配置。

5.1 权限模式与规则评估

类型定义中存在七种权限模式：其中 5 种外部模式位于 types/permissions.ts；auto 会有条件加入；bubble 位于类型联合中。

  1. plan： 模型必须创建计划；只有在用户批准后才会继续执行。
  2. default： 标准交互式使用。大多数操作需要用户批准。
  3. acceptEdits： 工作目录内的编辑以及某些文件系统 shell 命令会被自动批准，包括 mkdir、rmdir、touch、rm、mv、cp、sed；其他 shell 命令需要批准。
  4. auto： 基于 ML 的分类器会评估未通过快速路径检查的请求；由 TRANSCRIPT_CLASSIFIER 控制。
  5. dontAsk： 不提示用户，但拒绝规则仍会执行。
  6. bypassPermissions： 跳过大多数权限提示，但安全关键检查和不受绕过影响的规则仍然适用。
  7. bubble： 内部专用模式，用于子智能体将权限升级给父级终端。

五种外部可见模式（acceptEdits、bypassPermissions、default、dontAsk、plan）定义在 EXTERNAL_PERMISSION_MODES 数组中。auto 模式只有在 TRANSCRIPT_CLASSIFIER 功能标志激活时才会有条件包含。bubble 模式存在于类型联合中，但不在任何模式数组里；它在内部用于子智能体权限升级（第 8 节）。

权限规则按照拒绝优先顺序进行评估（permissions.ts）。toolMatchesRule() 函数会先检查拒绝规则：拒绝规则总是优先于允许规则，即使允许规则更具体也是如此。一个宽泛拒绝规则（“拒绝所有 shell 命令”）不能被一个狭窄允许规则（“允许 npm test”）覆盖。规则系统支持工具级匹配（按工具名）和内容级匹配（匹配特定工具输入模式，例如 Bash(prefix:npm)）。

这七种模式构成一个分级自主性谱系：从 plan（执行前用户批准全部计划），经过 default 和 acceptEdits，到 bypassPermissions（最少提示）。这一梯度反映了一个反复出现的设计张力：随着自主性增加，系统必须从交互式批准转向自动安全检查。其他智能体系统以不同方式解决这一张力。SWE-Agent 和 OpenHands（Yang et al., 2024; Wang et al., 2024b）使用 Docker 容器隔离，对智能体的整个执行环境进行沙箱化，而不是评估单个工具调用。Aider（Gauthier, 2024）依赖 Git 作为安全网，通过版本控制使所有修改可逆。Claude Code 的方法是在可选容器沙箱之上叠加多个策略执行机制，用简单性换取对单个动作的细粒度控制。

5.2 授权流水线

完整授权流水线会经过若干阶段：

预过滤。 在任何工具请求到达运行时评估之前，filterToolsByDenyRules()（tools.ts）会在工具池组装时，将被整体拒绝的工具从模型视野中剥离。文档说明：“使用与运行时权限检查相同的匹配器，因此像 mcp__server 这样的 MCP 服务器前缀规则，会在模型看到之前剥离该服务器中的所有工具。”这能防止模型尝试调用被禁止的工具，因此模型不会把调用浪费在这些工具上。

PreToolUse 钩子。 已注册钩子会作为权限流水线的一部分触发。PreToolUse 钩子可以返回 permissionDecision 来拒绝或询问，也可以返回 updatedInput 来修改工具输入参数（types/hooks.ts）。钩子给出的 allow 不会绕过后续基于规则的拒绝或安全检查。在交互式路径中，用户对话框会先排队，而钩子异步运行；协调器和类似后台智能体路径会在显示对话框之前等待自动化检查。

规则评估。 拒绝优先规则引擎评估请求。MCP 工具会按其完全限定名 mcp__server__tool 进行匹配，服务器级规则会匹配来自该服务器的全部工具。

权限处理器。 useCanUseTool.tsx 中的处理器会根据运行时上下文分支到四种路径之一：

  1. 协调器： 用于多智能体协调模式。在回退到用户交互之前，尝试自动解析，包括分类器、钩子和规则。
  2. Swarm worker： 处理多智能体 swarm 中的 worker agent，它们有自己的解析逻辑。
  3. 推测性分类器： 当 BASH_CLASSIFIER 启用且工具为 BashTool 时，推测性分类器会让一个预先启动的分类结果与超时竞争。如果分类器以高置信度返回，该工具会立即获批，而无需用户交互。
  4. 交互式： 备用路径。通过终端 UI 呈现标准用户批准对话框。

在协调器和某些后台路径中，系统会先尝试自动解析，再进行用户交互。在标准交互式路径中，对话框可能先出现，而钩子或分类器检查继续并行运行。当分类器或拒绝规则阻止某个动作时，系统会将拒绝视为路由信号，而不是硬停止：模型会收到拒绝原因，修正其方法，并在下一轮循环中尝试更安全的替代方案。PermissionDenied 钩子事件（第 6 节）使外部代码能够以编程方式观察并响应这些拒绝。这种面向恢复的设计意味着权限执行是在塑造智能体行为，而不仅仅是中止它。

5.3 自动模式分类器与钩子生命周期

启用时，自动模式分类器（yoloClassifier.ts）会参与权限决策。当 TRANSCRIPT_CLASSIFIER 启用时，分类器会加载三类提示资源：

  • 一个基础系统提示。
  • 一个外部权限模板。
  • 对于 Anthropic 内部用户，一个单独的内部模板。

分类器会根据对话转录和权限模板评估拟议工具调用，并产生 allow、deny 或请求人工批准的结果。isUsingExternalPermissions() 函数检查 USER_TYPE 和 forceExternalPermissions 配置标志，以选择合适模板。

在源码定义的 27 个钩子事件中（coreTypes.ts），有 5 个直接参与权限流程，每个都有一个经过 Zod 验证的特定输出模式（types/hooks.ts）：

  • PreToolUse： 可以返回 permissionDecision（deny 或 ask，但 allow 不会绕过后续检查）、permissionDecisionReason 和 updatedInput（修改参数）。
  • PostToolUse： 可以注入 additionalContext，并且对于 MCP 工具，可以返回 updatedMCPToolOutput，在结果进入上下文之前修改结果。
  • PostToolUseFailure： 可以为错误特定指导注入 additionalContext。
  • PermissionDenied： 可以在自动模式拒绝之后提供重试指导。
  • PermissionRequest： 可以返回 allow 或 deny 决策。在协调器和类似路径中，它可以先于用户对话框完成解析。在标准交互式路径中，它也可以与对话框并行运行。

对于非 MCP 工具，tool_result 会在 PostToolUse 钩子触发之前发出。对于 MCP 工具，结果会被延迟到 post 钩子运行之后再发出，从而使 updatedMCPToolOutput 生效。

5.4 Shell 沙箱

Shell 沙箱为 Bash 和 PowerShell 命令提供了一层额外保护（shouldUseSandbox.ts）。shouldUseSandbox() 函数会检查沙箱是否全局启用、本次调用是否选择退出，以及命令是否匹配任何排除模式。

启用时，沙箱会提供文件系统和网络隔离，这独立于应用层权限模型。一个命令可能已经通过权限批准，但仍然在沙箱中执行；也可能被权限拒绝，从而永远不会到达沙箱检查。两个系统运行在不同轴线上：授权与隔离。

分层安全架构依赖一个独立性假设：如果某一层失败，其他层会捕获违规。然而，若干层共享共同的性能约束。安全研究人员（Adversa.ai, 2026）记录到，当命令包含超过 50 个子命令时，系统会回退到一个通用批准提示，而不是运行逐子命令拒绝规则检查，因为逐子命令解析会导致 UI 卡顿。这个例子表明，当不同防御层共享失败模式时，纵深防御会退化；这是安全与性能之间的一种结构性张力，第 11.3 节会进一步分析。

权限流水线治理的是某个工具请求是否执行。下一节考察决定有哪些工具存在的机制：即组装模型动作表面的可扩展性架构。

6 可扩展性：MCP、插件、技能与钩子

编码智能体的一个反复出现的设计问题是：如何组织扩展表面？是采用一个统一机制、少数几个专门机制，还是采用一个具有不同上下文成本的分层栈？

这里的分析说明了表 1 中的两项设计原则：可组合的多机制可扩展性和外部化的可编程策略。回到贯穿示例：一旦 Claude 正在尝试修复 auth.test.ts，并且此前的 npm test 请求已经由权限系统进行调解（第 5 节），下一个问题就是：有哪些启用了扩展的动作表面可用于此次修复？

当 Claude Code 中的一个回合开始时，模型不仅会看到 BashTool 和 FileReadTool 这样的内置工具，还会看到来自 MCP 服务器的数据库查询工具、来自 .claude/skills/ 的自定义 lint 技能，以及由已安装插件贡献的工具。这些能力通过四种机制进入系统，并在智能体循环的不同位置扩展智能体：

  • MCP 服务器提供外部工具集成。
  • 插件打包并分发组件包。
  • 技能注入特定领域的指令。
  • 钩子拦截工具执行生命周期。

Anthropic 的文档（Anthropic, 2026d）给出了一个更宽泛的视图，其中还包括 CLAUDE.md（第 7 节）和子智能体（第 8 节），与这里分析的四种机制并列。本文将 CLAUDE.md 和子智能体放在各自章节中处理，因为它们运行于不同子系统：前者属于上下文构建，后者属于委派。然而，上下文成本排序在架构上很重要：它揭示了每个扩展点如何在表达能力与有限上下文窗口之间进行权衡。

6.1 四种扩展机制

这些机制在不同源码目录中实现（图 5），并服务于不同集成模式。

MCP 服务器。 Model Context Protocol 是主要的外部工具集成路径。MCP 服务器可从多个作用域配置：项目、用户、本地和企业；另外，插件服务器和 claude.ai 服务器会在运行时合并进来（services/mcp/config.ts）。MCP 客户端（services/mcp/client.ts）支持多种传输类型：stdio、SSE、HTTP、WebSocket、SDK，以及 IDE 专用变体（sse-ide、ws-ide）和内部 claudeai-proxy。每个连接的服务器都会以 MCPTool 对象形式贡献工具定义。专用内置工具 ListMcpResourcesTool 和 ReadMcpResourceTool 提供对 MCP 资源的访问。

插件。 插件具有双重角色：既是一种打包格式，也是一种分发机制。PluginManifestSchema（utils/plugins/schemas.ts）接受十种组件类型：命令、智能体、技能、钩子、MCP 服务器、LSP 服务器、输出风格、通道、设置和用户配置。插件加载器（utils/plugins/pluginLoader.ts）会验证 manifest，并将每个组件路由到对应注册表：命令和技能通过 SkillTool 元工具浮现；智能体出现在由 AgentTool 消费的定义中；钩子合并进钩子注册表；MCP 与 LSP 服务器合入它们的标准配置；输出风格修改响应格式。因此，一个插件包可以同时跨多个组件类型扩展 Claude Code，这使插件成为第三方扩展的主要分发载体。

技能。 每个技能由一个带 YAML frontmatter 的 SKILL.md 文件定义。parseSkillFrontmatterFields() 函数（loadSkillsDir.ts）解析 15 个以上字段，包括显示名称、描述、允许工具（授予该技能访问额外工具的权限）、参数提示、模型覆盖、执行上下文（fork 表示隔离执行）、关联智能体定义、effort 级别和 shell 配置。技能可以定义自己的钩子，这些钩子会在调用时动态注册。捆绑技能会在启动时以内存方式注册。被调用时，SkillTool 元工具会将技能指令注入上下文。

钩子。 源码定义了 27 种钩子事件，覆盖：

  • 工具授权：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied
  • 会话生命周期：SessionStart、SessionEnd、Setup、Stop、StopFailure
  • 用户交互：UserPromptSubmit、Elicitation、ElicitationResult
  • 子智能体协调：SubagentStart、SubagentStop、TeammateIdle、TaskCreated、TaskCompleted
  • 上下文管理：PreCompact、PostCompact、InstructionsLoaded、ConfigChange
  • 工作区事件：CwdChanged、FileChanged、WorktreeCreate、WorktreeRemove
  • 通知

这些事件定义于 coreTypes.ts 和 coreSchemas.ts。其中 15 个具有事件特定输出 schema，提供丰富字段，支持权限决策、上下文注入、输入修改、MCP 结果转换和重试控制（types/hooks.ts）。通过设置和插件配置的持久化钩子命令使用四种命令类型：shell 命令（type: command）、LLM 提示钩子（type: prompt）、HTTP 钩子（type: http），以及智能体验证器钩子（type: agent）（schemas/hooks.ts）。运行时还支持不可持久化的回调钩子（type: callback），由 SDK 和内部 instrumentation 使用（types/hooks.ts）。钩子来源包括启动时的 settings.json、插件和托管策略；技能钩子会在调用时动态注册（utils/hooks.ts）。五个工具授权事件已在第 5.3 节详细说明。

图 5 Claude Code 的扩展机制插入智能体循环的位置。 左侧伪代码是图 1 中 Agent Loop 模块的放大视图。每个智能体循环都有三个注入点：
a assemble() 控制模型看到什么；
b model() 控制模型可以触达什么；
c execute() 控制一个动作是否以及如何实际运行。

# Claude Code 智能体循环的一个回合while not stopped:    # a assemble -- 构建模型看到的内容    context = assemble(        system_prompt,      # 指令头        tool_schemas,       # 可调用工具签名        history,            # 先前回合消息        hook_additions,     # 由钩子推入的内容    )    # b model -- 选择下一个动作    action = model(context, tools)  # 扁平工具池    if action.is_text_only():        stopped = run_stop_hooks(action)  # 可能否决停止        continue    # c execute -- 对工具调用进行门控并运行    if not permitted(action):      # 权限        continue    action = run_pre_tool_hooks(action)   # 阻止/重写    result = execute(action)              # 工具在这里运行    result = run_post_tool_hooks(result)  # 修改/注释    history.append(action, result)

a assemble()：模型看到什么

元素作用
CLAUDE.md 文件加载进上下文；工作目录之上的文件在启动时加载，子目录文件按需加载。
技能描述宣传技能，使模型调用 SkillTool。
MCP 资源与提示MCP 服务器推送的非工具内容。
输出风格替换响应格式化系统块。
UserPromptSubmit 钩子在每个用户回合中注入上下文，或阻止该回合。
SessionStart 钩子在会话开始时进行一次性上下文注入。

b model()：模型可以触达什么

元素作用
内置工具随 CLI 发布的 Read / Edit / Bash / ……
MCP 工具来自任意 MCP 服务器的工具，位于同一个扁平工具池中。
SkillTool按名称启动技能的元工具。
AgentTool递归生成子智能体的元工具。

c execute()：一个动作是否以及如何运行

元素作用
权限规则针对每次调用的声明式 allow / deny / ask。
PreToolUse 钩子批准、阻止或重写工具调用。
PostToolUse 钩子在调用之后修改输出或注入上下文。
Stop 钩子在模型停止时强制循环继续。
SubagentStop 钩子同上，但用于通过 AgentTool 生成的子智能体。
Notification 钩子对用户通知产生外部副作用。

6.2 工具池组装

tools.ts 中的 assembleToolPool() 函数被文档描述为“组合内置工具与 MCP 工具的单一事实来源”。组装遵循五步流水线：

  1. 基础工具枚举。 getAllBaseTools()（tools.ts）返回最多 54 个工具组成的数组：其中 19 个总是包含，例如 BashTool、FileReadTool、AgentTool、SkillTool；另外 35 个根据功能标志、环境变量和用户类型有条件包含。Anthropic 内部用户会获得额外内部工具。Worktree 模式会启用 EnterWorktreeTool 和 ExitWorktreeTool。当 Bun 二进制中有嵌入式搜索工具可用时，专用的 GlobTool 和 GrepTool 会被省略。
  2. 模式过滤。 getTools()（tools.ts）应用特定模式过滤。在 CLAUDE_CODE_SIMPLE 模式下，只有 Bash、Read 和 Edit 可用；或者在 REPL 分支中使用 REPLTool，并在适用时加入协调器工具。每个工具的 isEnabled() 方法都会被调用，以进行运行时可用性检查。
  3. 拒绝规则预过滤。 filterToolsByDenyRules()（tools.ts）会在任何调用之前，将被整体拒绝的工具从模型视野中剥离。
  4. MCP 工具集成。 来自 appState.mcp.tools 的 MCP 工具会先经过拒绝规则过滤，然后与内置工具合并。
  5. 去重。 工具按名称去重，且内置工具优先于 MCP 工具。

REPL.tsx（通过 useMergedTools 钩子）和 AgentTool.tsx（在构建 worker 工具集时）都会调用该函数，从而确保所有执行路径上的组装一致性。在请求时，延迟工具可能会从模型上下文中隐藏，直到通过 ToolSearch 显式查询（tools.ts）。

基于智能体的扩展，即通过 .claude/agents/*.md 定义的自定义智能体以及插件贡献的智能体，将在第 8 节讨论，因为智能体与上述四种机制有根本差异：它们创建新的、隔离的上下文窗口，而不是扩展当前上下文窗口。

6.3 为什么是四种机制？

考虑到每增加一种扩展机制，都会增加开发者需要学习的表面积，一个自然的问题是：为什么 Claude Code 使用四种不同机制，而不是合并为一种或两种？答案在于这样一个观察：不同类型的可扩展性会给上下文窗口施加不同成本，而单一机制无法覆盖从零上下文生命周期钩子到 schema 很重的工具服务器这一完整范围，否则就会迫使扩展作者承担不必要的权衡。

如表 2 所总结，每种机制都用不同的部署复杂度换取不同类型的可扩展性。MCP 服务器提供运行时工具集成，即模型获得新的可调用工具，代价是服务器管理开销，以及工具 schema 消耗的上下文预算。技能塑造智能体如何思考，而不仅仅是它拥有哪些工具；其上下文成本很低，因为只有 frontmatter 描述，而不是完整内容，会保留在提示中。钩子提供横切式生命周期控制，例如阻止、重写或注释工具调用，默认没有上下文占用，不过钩子也可以选择注入额外上下文。插件则将其他三种机制的任意组合打包为可分发的软件包，充当打包与分发层，而不是一种独立的运行时原语。

表 2 每种扩展机制独有提供的能力。 上下文成本指该机制激活时会消耗多少有限上下文窗口。

机制独有能力上下文成本插入点
MCP 服务器外部服务集成（多传输）高（工具 schema）model(): 工具池
插件多组件打包 + 分发中（视情况而定）全部三个点
技能领域特定指令 + 元工具调用低（仅描述）assemble(): 上下文注入
钩子生命周期拦截 + 事件驱动自动化默认零execute(): 工具前/后

这种分级的上下文成本排序，即钩子为零、技能较低、插件中等、MCP 较高，意味着廉价扩展可以广泛扩展而不耗尽上下文窗口，而昂贵扩展则保留给确实需要新工具表面的场景。

一些智能体框架提供单一扩展机制，通常是仅工具 API，所有自定义都以额外可调用工具的形式进入。另一些系统使用两层，将工具与配置或指令注入分离。Claude Code 的四机制方法能够容纳更广泛的扩展模式，从零上下文事件处理器到完整外部服务集成，但它也增加了开发者在决定某个集成任务应使用哪种机制时所面对的学习曲线。

7 上下文构建与记忆

智能体如何管理其上下文窗口并持久化用户指令，是一个核心设计选择。不同系统会在基于文件的透明性、数据库支持的检索，以及不透明的已学习表示之间做出选择。这里的设计选择实现了表 1 中的两项原则：将上下文视为稀缺资源并渐进式管理，以及透明的基于文件的配置与记忆。

在贯穿示例进行到这里时，任务已经积累了状态：原始请求、npm test 权限结果、第 6 节中组装的工具池，以及到目前为止收集到的任何文件读取内容或命令输出。本节追问的是：在下一次模型调用之前，这些不断增长的状态如何被打包进 Claude Code 有限的上下文窗口中？

在调用模型之前，智能体循环会从工具池（第 6 节）、CLAUDE.md 文件、自动记忆和对话历史中组装一个上下文窗口。以下小节覆盖组装顺序、CLAUDE.md 层级，以及多步骤压缩流水线。

7.1 上下文窗口组装

上下文窗口（图 6）由以下来源组装而成，其中一些在初始组装时加入，另一些则在回合期间较晚注入：

  1. 系统提示，包含输出风格修改，以及任何 --append-system-prompt 标志内容。
  2. 环境信息，通过 getSystemContext()（context.ts）获得：包括 git 状态，远程模式下或禁用 git 指令时会跳过；以及面向内部构建的可选破坏缓存注入，由 BREAK_CACHE_COMMAND 控制。该信息每个会话记忆化一次。
  3. CLAUDE.md 层级，通过 getUserContext()（context.ts）获得：四层指令文件层级（第 7.2 节）。同样会被记忆化。
  4. 路径作用域规则：条件规则和目录匹配规则，会在智能体读取匹配目录中的文件时懒加载。
  5. 自动记忆：上下文相关的记忆条目会异步预取。
  6. 工具元数据：技能描述、MCP 工具名称，以及延迟工具定义，通过 ToolSearch 按需加载。
  7. 对话历史：向前携带，但会受到压缩影响。
  8. 工具结果：文件读取、命令输出、子智能体摘要。
  9. 压缩摘要：替换较旧历史片段。 Pasted image 20260525170436 图 6 上下文构建与记忆层级。 汇聚到上下文窗口中的来源包括：系统提示、输出风格、环境信息、CLAUDE.md 层级（从 managed 到目录特定）、自动记忆、路径作用域规则、MCP 工具名称、通过 ToolSearch 获得的延迟工具定义、对话历史、文件读取、命令输出、工具结果、子智能体摘要，以及压缩摘要。

图中还将上下文来源按加载时机和可变性分层：

层级内容加载/更新方式
系统层系统提示、环境信息、技能描述、MCP 工具名称、输出风格启动时加载，主要只读
项目配置CLAUDE.md 层级、路径作用域规则 .claude/rules/*启动时或懒加载，可热重载
记忆自动记忆、压缩摘要启动时加入；压缩摘要替换长历史
对话对话历史、子智能体摘要每轮持续累积
运行时已读文件、命令输出、工具结果执行期间加入
按需层延迟工具定义，完整 schema 只在需要时加载通过 ToolSearch 懒加载

query.ts 中的系统提示组装，会通过 asSystemPrompt(appendSystemContext(systemPrompt, systemContext))() 将系统上下文与基础提示结合起来。用户上下文（CLAUDE.md 和日期）则通过 prependUserContext() 前置到消息数组中。这种分离意味着 CLAUDE.md 内容在 API 请求中占据着与系统提示不同的结构位置，可能影响模型的注意力模式。

若干上下文来源会在主窗口构建完成之后较晚注入：相关记忆预取（query.ts）、MCP 指令增量（只有新增或变更的服务器指令）、智能体列表增量，以及后台智能体任务通知。因此，上下文窗口在组装时并不是静态的，而可能在回合期间继续增长。

7.2 CLAUDE.md 层级与自动记忆

一项设计原则塑造了记忆系统：已存储上下文应当能够被用户检查和编辑。CLAUDE.md 文件是纯文本 Markdown，而不是结构化配置或不透明数据库条目。这种透明性选择用表达能力换取可审计性：用户可以阅读、编辑、版本控制并删除智能体所看到的任何指令（MindStudio Team, 2026）。

替代记忆架构体现了这种权衡。检索增强方法使用基于嵌入的查找来呈现相关的先前上下文，以牺牲可检查性换取灵活性：用户无法轻易看到或编辑检索系统认为相关的内容。数据库支持的记忆提供结构化查询，但需要额外基础设施，并且对版本控制不透明。Claude Code 的基于文件的方法，使智能体看到的每条指令都可以直接阅读、编辑，并与代码库一起提交。该系统不使用嵌入或向量相似度索引进行记忆检索；相反，它使用基于 LLM 的记忆文件头扫描，按需选择最多五个相关文件，并以文件粒度而不是条目粒度呈现它们。基于嵌入的系统可以更有选择性地检索单个条目，代价是可检查性下降，以及需要维护索引的基础设施。

CLAUDE.md 文件遵循多层加载层级。源码头部（claudemd.ts）定义了四种记忆类型：

  1. 托管记忆，例如 Linux 上的 /etc/claude-code/CLAUDE.md：面向所有用户的操作系统级策略。
  2. 用户记忆，~/.claude/CLAUDE.md：私有全局指令。
  3. 项目记忆，项目根目录中的 CLAUDE.md、.claude/CLAUDE.md 和 .claude/rules/*.md：检入代码库的指令。
  4. 本地记忆，项目根目录中的 CLAUDE.local.md：被 git 忽略，用于私有的项目特定指令。

文件发现会从当前目录向上遍历到根目录，检查每个目录中的所有项目记忆文件和本地记忆文件。离当前目录越近的文件优先级越高，也就是加载得更晚。

文件以“优先级反向顺序”加载：加载得越晚的文件会获得更多模型注意力。对于从根目录到当前工作目录的路径，来自 .claude/rules/*.md 的无条件规则会在启动时急切加载。对于当前工作目录之下的嵌套目录，即使是无条件规则，也会在智能体读取匹配目录中的文件时懒加载。这意味着，随着代码库中新部分被探索，模型的指令集可能在对话期间演化。

CLAUDE.md 内容会作为用户上下文，也就是一条用户消息传递，而不是作为系统提示内容传递（context.ts）。这一架构选择具有重要含义：因为 CLAUDE.md 内容是作为对话上下文而非系统级指令传递的，模型对这些指令的遵循是概率性的，而不是有保证的。按拒绝优先顺序评估的权限规则（第 5 节）提供了确定性的执行层。这在指导与执行之间创造了一个有意的分离：CLAUDE.md 是概率性的指导，而权限规则是确定性的执行。该函数调用 setCachedClaudeMdContent() 来为自动模式分类器缓存已加载内容，以避免 CLAUDE.md 加载器与权限系统之间出现导入循环。

记忆文件支持 @include 指令，用于模块化指令集（claudemd.ts 中的 processMemoryFile()）。语法变体包括 @path、@./relative、@~/home 和 @/absolute。该指令只在叶子文本节点中生效，不会在代码块中生效。在实现中，包含文件会先被推入，被包含文件追加在其后；系统通过跟踪已处理路径来防止循环引用，并且会静默忽略不存在的文件。

7.3 压缩流水线

五层压缩流水线（第 4.3 节）通过渐进式压缩实现“上下文即瓶颈”原则（query.ts）。Claude Code 不是使用单一策略，而是按顺序应用五层压缩，每一层都更激进。其中三层由功能标志控制；预算削减总是激活，而 auto-compact 可由用户配置。

这种渐进式方法与更简单的替代方案形成对比：许多智能体框架使用单次截断，即丢弃最旧消息，或者使用单一摘要步骤。渐进式设计体现了一种懒降级原则：先应用破坏性最低的压缩，只有当更廉价策略不足时才升级。该方法的代价是复杂性。五个相互作用的压缩层，其中若干由功能标志控制，会产生用户难以完全预测的行为。Auto-compact 会在转录中产生可见摘要，microcompact 会发出边界标记，但 context collapse 运行时没有用户可见输出。更简单的单次方法会牺牲信息，但更容易推理。

  1. 预算削减（总是激活）：按工具结果设置大小限制。
  2. Snip（HISTORY_SNIP）：轻量级地裁剪较旧历史。
  3. Microcompact（CACHED_MICROCOMPACT）：细粒度、缓存感知压缩。
  4. Context collapse（CONTEXT_COLLAPSE）：对历史进行读时虚拟投影。
  5. Auto-compact（默认启用，可禁用）：完整的模型生成摘要。

buildPostCompactMessages() 函数（compact.ts）返回如下压缩输出结构：

[boundaryMarker, ...summaryMessages, ...messagesToKeep, ...attachments, ...hookResults]

边界标记会通过 annotateBoundaryWithPreservedSegment() 标注保留片段元数据，记录 headUuid、anchorUuid 和 tailUuid，以支持读时链修补。这种基本追加式设计意味着压缩永远不会修改或删除先前写入的转录行；它只会追加新的边界事件和摘要事件。

compactConversation() 压缩函数（compact.ts）包含若干设计选择。首先触发 pre-compact 钩子，允许钩子注入自定义指令。一个 GrowthBook 功能标志控制压缩路径是否复用主对话的提示缓存；一条代码注释记录了 2026 年 1 月的一次实验：“false path is 98% cache miss, costs ∼0.76% of fleet cache_creation”。压缩之后，附件构建器会从实时应用状态中重新声明运行时状态，包括计划、技能和异步智能体，因为压缩会丢弃先前的附件消息，但不会丢弃底层状态。

当系统将工作委派给子智能体时，上下文隔离会变得更加关键，因为每个子智能体都在自己的有限上下文窗口中运行。 Pasted image 20260525170527 图 7 子智能体隔离与委派架构。 Agent 工具会分发到内置子智能体（Explore、Plan、general-purpose）或自定义子智能体；每个子智能体都运行在隔离上下文中，并拥有重建后的权限上下文和独立工具集。Agent 工具沿三个轴进行分发：路由（teammate）、隔离（remote、worktree）和生命周期（async、sync）。

8 子智能体委派与编排

多智能体编排是编码智能体的一个关键设计维度，其选择范围包括父子层级、基于对话的同伴框架（Wu et al., 2024），以及图结构工作流引擎（LangChain, Inc., 2024）。Claude Code 的委派架构实现了表 1 中的隔离的子智能体边界原则，同时也包含拒绝优先并升级给人类的某些方面（权限覆盖）和按可逆性加权的风险评估的某些方面（子智能体工具限制）。

当 Claude 判断修复 auth 测试首先需要探索认证模块结构时，它可以将这一探索委派给子智能体。委派机制是 Agent 工具（AgentTool.tsx），其中 Task 被保留为旧版别名。模型使用结构化输入调用 Agent，该输入包括委派提示、可选的子智能体类型，以及隔离模式、权限覆盖和工作目录配置。

8.1 Agent 工具与委派标准

Agent 工具输入 schema（图 7）使用由功能标志控制的字段：当对应功能未启用时，可选参数会被省略。isolation 字段对内部用户提供 [’worktree’, ’remote’]，对外部用户提供 [’worktree’]，该选择在构建时决定。cwd 字段由一个功能标志控制。run_in_background 字段在后台任务被禁用，或 fork-subagent 模式启用时，会被省略。

Claude Code 最多提供六种内置子智能体类型，具体取决于功能标志和入口点：

  • Explore： 主要用于以读取/搜索为导向的调查，其拒绝列表中包含写入和编辑工具。
  • Plan： 创建结构化计划；执行仍通过标准权限模型进行。
  • General-purpose： 能力较广泛，在被明确请求时使用。需要注意的是，省略类型可能会路由到 fork-subagent 路径。
  • Claude Code Guide： 用于入门和文档辅助，并拥有自己的 permissionMode 覆盖。
  • Verification： 运行验证检查，例如测试套件和 lint。
  • Statusline-setup： 专门用于终端状态行配置。

除内置类型外，用户可以通过 .claude/agents/*.md 文件定义自定义子智能体，插件也可以通过 loadPluginAgents.ts 贡献智能体定义。每个文件的 Markdown 正文充当该智能体的系统提示，而 YAML frontmatter 指定配置字段，包括 description、tools（allowlist）、disallowedTools、model、effort、permissionMode、mcpServers、hooks、maxTurns、skills、记忆作用域、后台标志和隔离模式。JSON 格式的智能体定义支持相同字段，另加 prompt 作为显式字段（loadAgentsDir.ts）。这意味着，一个自定义智能体可以是一个完全配置好的隔离子系统，拥有自己的工具、模型、权限、钩子、记忆作用域和隔离模式。

AgentTool 与 SkillTool 一起位于基础工具池中，二者都是元工具，会分发到这些定义；但二者有根本差异：SkillTool 将指令注入当前上下文窗口，而 AgentTool 会生成一个新的、隔离的上下文窗口。其权衡在于，大多数子智能体调用都需要一个自包含提示，因为默认路径不会继承父级对话历史；fork-subagent 路径是例外。共享完整转录历史的基于对话的框架避免了这一成本，但会随着智能体数量增长而面临上下文爆炸风险。

8.2 隔离架构

子智能体隔离支持多种模式（AgentTool.tsx）：

  • Worktree： 创建临时 git worktree，使子智能体拥有自己的代码库副本，可以修改而不影响父级工作树。
  • Remote（内部专用）： 在远程 Claude Code Remote 环境中启动，并始终在后台运行。
  • In-process（默认）： 与父级共享文件系统，但在隔离的对话上下文中运行。

子智能体的权限覆盖逻辑（runAgent.ts）包含若干具体规则。当子智能体定义了 permissionMode 时，会应用该覆盖，除非父级已经处于 bypassPermissions、acceptEdits 或 auto 模式；这些模式总是优先，因为它们代表用户已经就安全/自主性权衡作出的显式决策。对于异步智能体，系统会通过一个级联规则决定是否避免提示：首先检查显式的 canShowPermissionPrompts，然后检查 bubble 模式（始终显示，因为它们会升级到父级终端），最后使用默认值（同步智能体显示提示，异步智能体不显示）。可以显示提示的后台智能体会设置 awaitAutomatedChecksBeforeDialog: true，确保分类器和钩子在打断用户之前先完成解析。

这些隔离模式位于设计空间中的不同位置。SWE-Agent 和 OpenHands（Yang et al., 2024; Wang et al., 2024b）使用的基于容器的隔离提供更强的资源边界，但需要容器基础设施。AutoGen（Wu et al., 2024）等基于对话的框架使用的仅上下文隔离共享文件系统，但分离对话历史。Claude Code 的基于 worktree 的隔离，则利用 Git 内置机制提供文件系统级分离，不需要外部依赖，而不是引入容器编排。

当 allowedTools 被显式传给 runAgent()（runAgent.ts）时，会应用一个两层权限作用域模型。来自 --allowedTools 的 SDK 级权限会被保留：“来自 SDK 使用者的、应适用于所有智能体的显式权限。”但会话级规则会被子智能体声明的 allowedTools 替换。当未提供 allowedTools 时，也就是常见的 AgentTool 路径，父级的会话级规则会被继承，而不会被替换。

8.3 Sidechain 转录

每个子智能体都会将自己的转录写入一个单独的 .jsonl 文件，并配套一个 .meta.json 元数据文件（sessionStorage.ts、runAgent.ts）。这种 sidechain 设计意味着子智能体历史会被保留下来，用于调试和审计，但不会膨胀父级会话文件。只有子智能体的最终响应文本和元数据会返回到父级对话上下文中；完整的子智能体历史永远不会进入父级上下文窗口，从而遵守“上下文即瓶颈”的原则。

runAgent() 函数接受 21 个参数，覆盖智能体定义、提示、权限、工具、模型设置、隔离和回调。

仅返回摘要的模型是一种有意的上下文节约选择：在智能体之间共享完整转录历史的基于对话的框架，随着智能体数量增长，会面临上下文爆炸风险。即使是隔离上下文中的并行，也会带来巨大成本。Claude Code 的 agent teams 在 plan 模式下会消耗约为标准会话 7 倍的 token（Anthropic, 2025b），这使得当子智能体也处于隔离上下文中时，仅返回摘要变得更加关键。

对于 agent teams 中的多实例协调，运行框架使用文件锁，而不是消息代理或分布式协调服务（Anthropic, 2025b）。任务通过基于锁文件的互斥机制从共享列表中领取，锁文件存储在可预测的文件系统路径中。这以吞吐量换取了两个属性：零依赖部署（不需要外部基础设施）和完全可调试性（任何智能体的状态都可以通过读取纯文本 JSON 文件来检查）。

9 会话持久化与恢复

编码智能体中的会话持久化涉及一种设计选择：是采用仅追加日志、结构化数据库、基于检查点的快照，还是无状态架构。每种方案在可审计性、查询能力和部署复杂度方面都有不同权衡。

Claude Code 的持久化设计实现了表 1 中的仅追加的持久状态原则。会话级权限只存在于内存中，不会被序列化到转录中，因此恢复会话时，会从 CLI 参数和磁盘设置中重建权限上下文；重建后的上下文无法识别的请求，会回退到拒绝优先的提示流程。

当 auth 测试任务推进到本节时，会话中已经包含了原始提示、工具调用及其结果、压缩边界，以及来自探索认证模块的子智能体摘要（第 8 节）。本节追问的是：这些产物中哪些会被持久记录？哪些可以在之后恢复？同时，系统又如何避免把旧会话中的权限授予继续带入新会话？

Claude Code 的持久化机制会在事件发生时，将对话，包括消息、工具结果和压缩边界，写入磁盘。

9.1 转录模型

Pasted image 20260525170559 会话转录以基本仅追加的 JSONL 文件形式，存储在项目特定路径下；显式清理重写是例外（图 8）。getTranscriptPath() 函数（sessionStorage.ts）将该路径计算为：

join(projectDir, `${getSessionId()}.jsonl`)

其中，projectDir 会先通过 getSessionProjectDir() 获取，该值由恢复或分支期间的 switchSession() 设置；若不存在，则回退到 getProjectDir(getOriginalCwd())()。

三个持久化通道相互独立地运行：

  1. 会话转录： 包含用户、assistant、附件和系统消息，以及压缩和其他元数据事件。它是项目作用域的，每个会话对应一个文件。
  2. 全局提示历史： 只存储用户提示，保存在 Claude 配置主目录下的 history.jsonl 中（history.ts）。makeHistoryReader() 生成器通过 readLinesReverse() 以逆序产出条目，支持上箭头和 ctrl+r 导航。
  3. 子智能体 sidechain： 每个子智能体都有单独的 .jsonl 和 .meta.json 文件（第 8.3 节）。

会话转录不仅存储简单消息，还存储若干其他事件，包括压缩标记、文件历史快照、归因快照，以及内容替换记录。仅追加 JSONL 格式是一种有意选择：它偏向可审计性和简单性，而不是查询能力。每个事件都是人类可读的、可版本控制的，并且可以在不依赖专门工具的情况下重建。基于数据库的替代方案可以对会话历史进行更丰富查询，但会引入部署依赖，并降低透明性。

图 8 会话持久化与上下文压缩。 该图将实时会话状态（上下文窗口、压缩）与持久存储（会话转录、history.jsonl、子智能体 sidechain、检查点）分离开来。恢复和分叉会还原消息，但不会还原会话级权限。

原则描述
对话寿命超过上下文一个会话的有效生命周期不能被模型上下文窗口限制。磁盘上的转录记录一切，因此压缩可以回收实时视图，而不必结束对话。
对话会超出单一路径一个会话不应被困在单条线性轨迹上。仅追加转录允许用户回退、恢复或分叉到新分支，而不会丢失先前工作。

会话身份系统将 sessionId 与 sessionProjectDir 配对，并在恢复或分支期间一起设置。转录路径必须使用消息写入时处于活动状态的同一个项目目录，以避免钩子在错误目录中查找。

9.2 恢复、分叉，以及不恢复权限

--resume 标志会通过重放转录来重建对话（conversationRecovery.ts）。Fork 会从现有会话创建一个新会话（commands/branch/branch.ts）。然而，恢复和分叉都不会还原会话级权限；用户必须在新会话中重新授予这些权限。这是一个刻意保守的安全设计选择：会话被视为彼此隔离的信任域。

如果恢复时自动还原此前授予的权限，会带来便利性收益，但也可能把已经过时的信任决策带入已经变化的上下文。该架构选择重新授予，而不是隐式持久化权限；它接受用户摩擦，作为维持安全不变量的代价：信任总是在当前会话中建立。

compact_boundary 标记被精心设计为能够与持久化机制协同工作。annotateBoundaryWithPreservedSegment() 函数（compact.ts）会在边界事件中记录 headUuid、anchorUuid 和 tailUuid。这些 UUID 使会话加载器能够在读取时修补消息链：被保留的消息在磁盘上保持其原始 parentUuid，加载器则使用边界元数据将它们正确连接起来。这种基本仅追加设计意味着，压缩永远不会修改或删除先前写入的转录行。

Claude Code 中的“检查点”是面向 --rewind-files 的文件历史检查点，存储在：

~/.claude/file-history/<sessionId>/

这些是用于回滚文件系统修改的文件级快照，而不是通用检查点存储。

前面几节已经记录了 Claude Code 对反复出现的设计问题的回答。下一节将把 Claude Code 的设计选择与一个架构上独立的 AI 智能体系统进行对比。

10 比较分析：Claude Code 与 OpenClaw

前面几节记录了 Claude Code 对一些反复出现的设计问题的回答：循环架构、安全、可扩展性、上下文管理、委派和持久化。为了校准这些发现，本节将 Claude Code 与 OpenClaw 进行比较。OpenClaw 是一个独立的开源 AI 智能体系统，它从一个根本不同的出发点回答了许多相同的设计问题。OpenClaw 是一个本地优先的 WebSocket 网关，连接大约二十多个消息表面，包括 WhatsApp、Telegram、Slack、Discord、Signal 等，到一个嵌入式智能体运行时，并在 macOS、iOS 和 Android 上提供配套应用（Steinberger and OpenClaw Contributors, 2026）。

Claude Code 是绑定到单一代码仓库会话的 CLI 编码运行框架，而 OpenClaw 是面向多通道个人助理的持久控制平面。二者占据了智能体设计空间中的不同区域。比较的价值在于展示：当部署语境发生变化时，相同的反复出现的问题如何产生不同的架构答案。

表 3 Claude Code 与 OpenClaw 在六个设计维度上的架构比较

每一行都捕捉一个反复出现的设计问题，以及两个系统给出的不同答案。

维度Claude CodeOpenClaw
系统范围CLI/IDE 编码运行框架，每个会话都是临时进程持久 WebSocket 网关守护进程，多通道控制平面
信任模型拒绝优先的逐动作规则评估，带钩子和可选 ML 分类器；7 种权限模式；分级信任谱系每个网关有一个受信任操作者；用于入站通道的 DM 配对码和允许列表；可选沙箱，作用域可配置为按智能体、按会话或共享，并支持多种后端
智能体运行时迭代式异步生成器 queryLoop() 作为系统中心Pi-agent runner 嵌入网关 RPC 分发；按会话队列串行化，并带有可选全局 lane
扩展架构4 种机制，具有分级上下文成本：MCP、插件、技能、钩子Manifest 优先的插件系统，包含 12 种能力类型和中央注册表；单独的技能层；通过 openclaw mcp 内置 MCP，包括服务器和出站客户端注册表
记忆与上下文CLAUDE.md 四层层级；五层压缩流水线；基于 LLM 的记忆扫描工作区 bootstrap 文件：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md，以及有条件的 BOOTSTRAP.md、HEARTBEAT.md 和 MEMORY.md；单独的记忆系统，包括 MEMORY.md、每日笔记、可选 DREAMS.md；带可插拔 provider 的自动压缩；可选混合搜索，即在配置 embedding provider 时使用向量 + 关键词；用于长期提升的实验性 dreaming
多智能体与路由任务委派型子智能体，例如 Explore、Plan、general-purpose；worktree 隔离；最终响应文本返回给父级两个独立问题：（a）多智能体路由，包含隔离智能体、不同工作区和基于绑定的通道分发；（b）子智能体委派，具有可配置嵌套深度，最大 5，默认 1，推荐 2，并支持线程绑定会话

10.1 六个比较维度

表 3 总结了六个维度上的比较。每个维度都对应一个两个系统都必须回答的设计问题。

系统范围与部署模型。 Claude Code 作为一个临时 CLI 进程运行，并绑定到单一代码仓库。每个会话随终端开始和结束。OpenClaw 则作为一个持久守护进程运行，默认端口为 18789，且仅绑定 loopback；它拥有全部消息表面连接，并通过类型化 WebSocket 协议协调客户端、工具和设备节点。系统范围上的差异是最根本的架构分歧：它决定了其他所有设计问题如何被框定。二者之间也存在组合关系：OpenClaw 可以通过 ACP（Agent Client Protocol）集成，将 Claude Code、OpenAI Codex 和 Gemini CLI 作为外部编码运行框架托管起来，这使两个系统可以堆叠，而不只是彼此替代。

信任模型与安全架构。 两个系统处理不同的威胁模型。Claude Code 假设有一个不受信任的模型运行在受信任开发者的机器中：拒绝优先权限系统（第 5 节）评估每次工具调用，ML 分类器提供自动化安全评估，七种权限模式形成分级自主性谱系。OpenClaw 假设每个网关实例有一个单一的受信任操作者。其安全架构从身份与访问控制开始，例如 DM 配对码、发送者允许列表、网关认证，而不是逐动作安全分类。工具策略使用每个智能体可配置的允许/拒绝列表，而不是集中式分类器。沙箱作为可选功能提供，支持多个后端，包括 Docker、SSH 或 OpenShell，并且作用域可配置为按智能体、按会话或共享；启用时，non-main 模式可以对所有 non-main 会话进行沙箱化，不过沙箱默认并不激活。OpenClaw 的安全文档明确指出，在共享网关上进行敌对多租户隔离并不是一个受支持的安全边界。这一区别反映了关于信任边界位置的设计选择：Claude Code 将信任边界放在模型与执行环境之间；OpenClaw 将其放在网关边界上。

智能体运行时与工具编排。 两个系统都实现了智能体循环，但这些循环在各自架构中的位置不同。在 Claude Code 中，queryLoop() 异步生成器（第 4 节）是系统中心：所有接口都进入它，并且它直接管理上下文组装、模型调用、工具分发和恢复。在 OpenClaw 中，智能体运行时，也就是嵌入式 Pi-agent core，位于更大的网关分发层内部。网关的 agent RPC 会验证参数、解析会话并立即返回；嵌入式 runner 随后执行智能体循环，同时通过网关协议回传生命周期事件和流式事件。运行会通过按会话队列和可选全局 lane 被串行化，从而防止多通道表面上的工具与会话竞争。两个系统都遵循 ReAct 模式（Yao et al., 2022），但 OpenClaw 的循环是控制平面中的一个组件，而不是控制平面本身。

扩展架构。 Claude Code 的四种扩展机制（MCP、插件、技能、钩子）按上下文成本组织（第 6 节）：钩子消耗零上下文，技能消耗低上下文，MCP 服务器消耗高上下文。四者都扩展单个智能体的上下文窗口和工具表面。OpenClaw 使用 manifest 优先的插件系统，具有四个架构层：发现、启用、运行时加载和表面消费；并包含 12 种能力类型，包括文本推理、语音、媒体理解、图像/音乐/视频生成、Web 搜索和消息通道。插件将能力注册到中央注册表；网关读取该注册表，以暴露工具、通道、provider 设置、钩子、HTTP 路由、CLI 命令和服务。OpenClaw 还有一个单独的技能层，技能来源包括工作区、项目级、个人、托管、捆绑和额外目录，其中工作区技能具有最高优先级；此外还有一个公共注册表 ClawHub，并通过内置 openclaw mcp 命令支持 MCP，包括服务器和出站客户端注册表。关键架构差异在于：Claude Code 的扩展修改的是一个智能体的动作表面，而 OpenClaw 的插件扩展的是跨所有智能体的网关能力表面。

记忆、上下文与知识管理。 两个系统都使用透明的基于文件的记忆，而不是不透明数据库。Claude Code 加载四层 CLAUDE.md 层级，并通过五层压缩流水线管理上下文压力（第 7 节）。记忆检索使用基于 LLM 的文件头扫描。OpenClaw 在会话开始时将工作区 bootstrap 文件注入系统提示：五个核心文件 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md，再加上有条件的 BOOTSTRAP.md、HEARTBEAT.md 和 MEMORY.md；大型文件会被截断。单独来看，记忆系统管理三类文件：用于长期持久事实的 MEMORY.md、带日期戳的每日笔记 memory/YYYY-MM-DD.md，以及可选的 DREAMS.md，用于 dreaming sweep 摘要。当配置了 embedding provider 时，记忆搜索使用混合检索，将向量相似度与关键词匹配结合起来。一个实验性 dreaming 系统会执行后台整合，对候选项进行评分，并只将合格条目从短期召回提升到长期记忆。压缩之前，OpenClaw 会自动提醒智能体将重要笔记保存到记忆文件中，以防止上下文丢失。两个系统都共享这样一种设计承诺：记忆应当对用户可见、可编辑。OpenClaw 更重视结构化的长期记忆提升，例如 dreaming、每日笔记和记忆搜索；Claude Code 则更重视渐进式上下文压缩，即带缓存感知的五层压缩。OpenClaw 也支持可插拔压缩 provider 和会话裁剪，但其压缩流水线不像 Claude Code 的五层系统那样分级。

多智能体架构与路由。 这一维度揭示了最鲜明的架构差异。Claude Code 的多智能体模型是任务委派：父级生成子智能体，包括 Explore、Plan、general-purpose 和自定义类型；这些子智能体在隔离上下文窗口中运行，拥有受限工具集，并只返回摘要结果（第 8 节）。Worktree 隔离提供文件系统级分离。OpenClaw 则区分两个不同问题。第一是多智能体路由：单个网关可以托管多个完全隔离的智能体，每个智能体都有自己的工作区、认证配置文件、会话存储和模型配置，并通过确定性绑定规则路由到特定通道或发送者。第二是子智能体委派：在单个智能体内部，可以生成后台运行，并拥有可配置嵌套深度，最大为 5，默认值为 1，推荐值为 2；在受支持通道上可以使用线程绑定会话，并按深度配置工具策略。OpenClaw 的项目愿景明确拒绝将智能体层级框架作为默认架构。这个区别很重要，因为 Claude Code 的子智能体是同一个用户编码会话中的从属 worker，而 OpenClaw 的多智能体路由创建的是真正独立的智能体实例，它们通过不同通道服务于不同用户或目的。

10.2 这种对比揭示了什么

该比较揭示了关于 AI 智能体系统设计空间的三点观察。

第一，第 3.1 节识别出的反复出现的设计问题，包括推理位于何处、采用什么安全姿态、如何管理上下文、如何构造可扩展性，并不只适用于编码智能体。OpenClaw 回答了其中每一个问题，但它的出发点是多通道个人助理，而不是绑定代码仓库的编码工具。问题是稳定的；答案则会随部署语境变化。

第二，两个系统在若干维度上作出了相反押注。Claude Code 投资于分级的逐动作安全评估；OpenClaw 投资于边界级身份与访问控制。Claude Code 将智能体循环视为架构中心；OpenClaw 将网关控制平面视为中心，并将智能体循环嵌入为其中一个组件。Claude Code 的扩展修改单一上下文窗口；OpenClaw 的插件扩展共享网关表面。这些反转并非任意选择：它们源自不同的信任模型和部署拓扑。

第三，两个系统之间的组合关系在架构上具有重要意义。OpenClaw 可以通过 ACP 将 Claude Code 作为外部编码运行框架托管起来，这意味着两个系统是可组合的，而不是互斥替代品。这表明 AI 智能体的设计空间并不是一个扁平分类法，而是一个分层空间，其中网关级系统和任务级运行框架可以组合。

11 讨论

前面几节的分析记录了 Claude Code 如何回答关于循环架构、安全姿态、可扩展性、上下文管理、委派和持久化的反复出现的设计问题。每一个答案都代表了在一个具有真实替代方案和可衡量权衡的设计空间中的某个位置。本节考察当这些答案被合在一起阅读时，它们揭示了什么：它们反映的设计哲学（第 11.1 节）、它们创造的价值张力（第 11.2 节）、它们包含的架构权衡（第 11.3 节）、它们生成的经验预测（第 11.4 节），以及在各个子系统中反复出现的横切性承诺（第 11.7 节）。第 2.1 节中的五价值框架将作为贯穿本节的组织视角。

11.1 设计哲学

第 2 节引入的价值与设计原则预示了一种架构：它投资于操作基础设施，而不是决策脚手架。实现层面证实了这一点：第 3 节到第 9 节所记录的架构，压倒性地由确定性基础设施构成，例如权限门、工具路由、上下文管理和恢复逻辑；而 LLM 则作为一个无状态补全端点被调用。估计只有 1.6% 的代码库构成决策逻辑，其余 98.4% 是操作运行框架。这个比例并非偶然。

第 2.2 节记录的设计原则支撑了这种方法：运行框架创造条件，使模型能够做出良好决策，而不是约束模型的选择。

表 4 价值之间的张力及其支持证据。 每一种张力都表明，这两种价值捕捉的是确实不同的关切。

价值组合张力证据
权威 × 安全批准疲劳 vs. 保护93% 的批准率削弱了人类警觉性（Hughes, 2026）；安全必须通过分类器和沙箱来补偿
安全 × 能力性能 vs. 纵深防御超过 50 个子命令时的 fallback 会因为解析开销而跳过逐子命令拒绝检查（Adversa.ai, 2026）；安全层共享性能约束
适应性 × 安全可扩展性 vs. 攻击面多个 CVE 利用了钩子和 MCP 服务器在信任建立前初始化的漏洞（Donenfeld and Vanunu, 2026）
能力 × 适应性主动性 vs. 干扰任务数量增加 12% 到 18%，但在高频率下用户偏好下降（Chen et al., 2025）
能力 × 可靠性速度 vs. 一致性有界上下文阻止对完整代码库的感知（第 7 节）；子智能体隔离限制跨智能体一致性（第 8 节）；相邻工具中观察到复杂性增加（He et al., 2025）

这种设计与智能体工程中的主导模式相反。在主导模式中，LangGraph 等框架通过带类型化边的显式图节点来路由模型输出，而 Devin 等系统则将多步骤规划器与重型操作基础设施配对。Claude Code 则是在丰富的操作运行框架内给予模型最大的决策自由。工程复杂性的存在不是为了约束模型决策，而是为了启用这些决策。这种分层架构中，模型负责推理，运行框架负责执行强制机制；这引出了一个问题：智能体式编码工具是否正在收敛到类似操作系统的抽象，其中核心循环充当内核，而其他所有东西构成操作系统。

随着前沿模型在编码任务上的实际能力趋同，这种设计具有额外意义：外围操作运行框架的质量成为主要差异化因素，从而验证了一种投资于基础设施而非决策脚手架的架构。对智能体构建者而言，含义是：相比在越来越强大的模型周围添加规划脚手架，投资于上下文管理、安全分层和恢复机制等确定性基础设施，可能带来更大的可靠性收益。

综合前面几节可以看到，生产级编码智能体面对的是一组反复出现的设计选择：推理相对于运行框架位于何处、迭代循环如何组织、默认采用什么安全姿态、扩展表面如何划分、上下文如何组装和压缩、子智能体如何委派和编排，以及会话如何跨边界持久化。Claude Code 对这些问题的回答形成了一个连贯的设计点：在丰富的操作运行框架内优先保留模型自主性。这一哲学假设，丰富的确定性基础设施能够充分支持不受约束的模型判断。以下小节将考察这一假设在何处受到检验。

11.2 价值张力

第 2.1 节识别出的五种价值会产生张力：追求一种价值会限制另一种价值（表 4）。这些张力不是设计失败，而是同时追求多种价值时产生的结构性结果。这里报告的是有最强支持证据的张力，而不是全部组合集合。

通过长期能力保存这一评估性视角（第 2.4 节），还会浮现两种额外张力。一项涉及 16 名有经验开发者、覆盖 246 个任务的随机对照试验（Becker et al., 2025）发现，AI 工具让开发者慢了 19%，尽管他们主观上感知到 20% 的提升。一项针对 807 个代码仓库采用 Cursor 的因果分析（He et al., 2025）发现，代码复杂度增加了 40.7%。一项包含 54 名参与者的 EEG 研究（Kosmyna et al., 2025）发现，LLM 用户表现出减弱的神经连接性，并且这种减弱在 AI 被移除后仍然持续。研究者还提出了用于衡量 AI 辅助编程中认知卸载的协议，其动机是担心学生借助 AI 生成应用，却不了解底层逻辑（Aiersilan, 2026）。这些发现，加上 2023 年到 2024 年间入门级技术岗位招聘下降 25%（Rak, 2025），表明能力放大与长期可持续性之间的张力，不仅限于个体生产力，也延伸到更广泛的开发者培养通道。这些证据支持该评估性视角，但并不专门针对 Claude Code 的架构；它适用于任何具有有界上下文和工具使用循环的智能体系统。

11.3 架构权衡

表 4 中的张力会在四个方面表现为具体架构权衡。上面关于评估性视角的段落中记录的长期可持续性关切，会在第 11.4 节的经验预测中再次出现。

安全 vs. 自主性。 权限模式构成了一个梯度：始终存在的五种模式，加上分类器功能标志激活时的 auto，以及内部 bubble 模式，共同形成从 plan（用户批准所有计划）到 default、acceptEdits、auto（ML 分类器）、dontAsk，再到 bypassPermissions（跳过大多数提示，但保留安全关键检查）的连续谱。该进程代表一种随着自主性增加而单调下降的安全梯度。恢复时不还原权限，反映了有意偏向安全的选择：安全状态不会跨会话边界隐式持久化。

安全-自主性梯度不仅由架构设计塑造，也由用户行为塑造。Anthropic 的自动模式分析（Hughes, 2026）发现，用户会批准约 93% 的权限提示，这表明批准疲劳使交互式确认在行为上并不可靠。纵向使用数据（McCain et al., 2026）显示，自动批准率从少于 50 个会话时的约 20%，增加到 750 个会话时的 40% 以上，同时会话时长也显著增加。这些模式说明，用户穿越这一梯度的方式并不一定是审慎选择模式，而可能是逐渐习惯化。沙箱使权限提示频率估计减少了 84%（Dworken and Weller-Davies, 2025），从而将问题重新框定为一个人因问题：对不可靠人类批准的架构回应，是减少人类必须作出的决策数量。

更根本地说，第 5 节描述的纵深防御架构依赖一个独立性假设：如果一个安全层失败，其他层会捕获违规。但 Claude Code 的安全层共享共同的性能和经济约束。自动模式分类器是一次独立的 LLM 调用，具有直接 token 成本。bashSecurity.ts 模块执行顺序的、基于 AST 的检查，存在解析延迟。拒绝优先规则评估作用于命令结构。当性能压力推动系统降低这些成本时，多个层可能同时退化。安全研究人员（Adversa.ai, 2026）记录到，包含超过 50 个子命令的命令会回退到单一通用批准提示，而不是运行逐子命令拒绝规则检查，因为逐子命令解析导致 UI 卡顿。这表明，当独立性假设被破坏时，纵深防御会失败。

这种张力是结构性的。任何使用模型本身进行安全评估的 LLM 智能体系统都会面对它。相关评估标准不应是某个单独层是否可以被绕过，而应是多少个独立层必须同时失败，以及它们是否共享失败模式。

对抗条件下的权限模型。 独立安全研究为权限架构提供了经验验证，具体而言，是揭示了图 4 没有捕捉到的一种时间顺序属性。两个经独立验证的漏洞具有共同根因：项目初始化期间执行的代码，包括钩子、MCP 服务器连接和设置文件解析，会在向用户显示交互式信任对话框之前运行³。这个信任建立前的执行窗口位于拒绝优先评估流水线（permissions.ts）之外，创造了一个结构上享有特权的阶段，在该阶段，第 5 节记录的安全保证尚未适用。

这一模式揭示出，权限流水线描绘的是安全检查的空间顺序，但没有捕捉时间维度：也就是在会话初始化过程中的哪个时刻，每一种机制开始生效。初始化顺序——先加载扩展，然后显示信任对话框，再执行权限强制——创造了一个窗口，在该窗口中，可扩展性架构（第 6 节）先于安全架构（第 5 节）完全介入而运行。这一发现通过加入安全维度，细化了可扩展性与简单性之间的张力：可扩展性不仅通过组合复杂性创造攻击面，还通过初始化顺序创造攻击面。

³ 两个信任建立前顺序漏洞是 CVE-2025-59536（CVSS 8.7）和 CVE-2026-21852（CVSS 5.3）（Donenfeld and Vanunu, 2026），由 Check Point Research 发现。CVE-2025-54794 和 CVE-2025-54795（Beber, 2025）分别利用了权限流水线其他位置的路径验证和命令解析缺陷。四个漏洞均在披露后数周内被修复。

上下文效率 vs. 透明性。 五层压缩流水线实现了有效的上下文管理，但压缩对用户来说大多是不可见的。当预算削减将较长工具输出替换为引用，当 context collapse 用摘要替换消息（源码将其描述为“REPL 完整历史上的读时投影”），或当 snip 裁剪较旧历史时，用户没有简单方式检查到底丢失了什么。Microcompact 的缓存感知行为进一步增加了不透明性，因为压缩决策会受到提示缓存影响，而这对用户不可见。

简单性 vs. 可扩展性。 四种扩展机制支持丰富定制，但会产生组合式交互。某个插件可能贡献一个会修改工具输入的 PreToolUse 钩子。自动模式分类器会读取缓存的 CLAUDE.md 内容。当新目录中的文件被读取时，路径作用域规则会懒加载，从而可能在对话中途改变分类器行为。权限处理器的四个分支会在多个点与钩子流水线交互。这些横切性关切会创造出难以从单个配置文件预测的涌现行为。

11.4 经验预测与早期信号

本文记录的架构属性会生成关于代码质量结果的可检验预测，而这些预测无法仅从源代码本身得出。有界上下文窗口（第 7 节）阻止智能体同时保持对完整代码库的感知：五层压缩流水线保留有用信息，但每一阶段都引入有损压缩。这使得从架构上可以预测：与在完整代码库可见性下产生的代码相比，智能体生成代码会表现出更高比例的模式重复和约定违反。子智能体隔离（第 8 节）会加剧这一效果：每个子智能体都在自己的上下文窗口中运行，并拥有独立组装的工具池，因此并行智能体可能彼此独立地重新实现代码库中已经存在的解决方案。第 11.1 节的设计哲学信任模型能够做出良好的局部决策，但当模型缺乏全局上下文时，良好的局部决策可能导致糟糕的全局结果。

关于架构上相似工具的已发表经验研究，提供了与这些预测一致的数据。一项针对 807 个代码仓库采用 Cursor 的因果分析（He et al., 2025）发现，代码复杂度出现统计显著增加，并且最初的速度峰值在第三个月消退至基线；复杂度上升与未来开发速度按比例下降相关，这表明收益会自我抵消⁴。一项针对 6,275 个代码仓库中 304,000 个 AI 编写提交的大规模审计（Liu et al., 2026）发现了可衡量的技术债，其中约四分之一由 AI 引入的问题会持续到最新版本，而安全相关问题的持续率要高得多。尽管这些研究针对的是相邻系统，但架构相似性，即有界上下文、工具使用循环和单次生成，表明这些发现与这里分析的设计相关。

Claude Code 的上下文管理流水线就是专门为了缓解这些影响而设计的：分级压缩保留最新和最相关的上下文；缓存感知压缩避免在压缩期间使提示缓存失效；读时投影保留完整历史以便重建，同时向模型呈现压缩视图；子智能体摘要隔离防止探索性噪声积累到父级上下文中。这些机制是否足以克服有界上下文的结构性限制，是一个可以直接衡量的经验问题，而本文的源码级分析无法解决它。

⁴ 复杂度 +40.7%（p < 0.001）；第一个月速度峰值 +281%，第三个月回到基线。

11.5 局限性

除了第 B.3 节中的方法论局限之外，还存在若干分析限制。带记忆化的上下文组装函数，即 getSystemContext() 和 getUserContext()，二者都在 context.ts 中使用 lodash memoize，意味着 git 状态和 CLAUDE.md 内容会被缓存，而不是每轮重新计算。对话期间发生的动态变化可能不会被立即反映，尽管压缩可以清除缓存，懒加载的路径作用域规则也提供了部分反制机制。

功能标志会造成构建时变异性。在 TRANSCRIPT_CLASSIFIER 为 false 的构建中，整个自动模式分类器会被消除。由功能标志控制的模块使用动态 require()，而不是静态 import，例如 query.ts 中的 context collapse，因为受 bun:bundle tree-shaking 约束，feature() 只在 if / 三元条件中有效。不同构建目标可能产生功能上不同的应用。

11.6 新兴方向

实现中的若干方面与更广泛的设计问题有关。更长的上下文窗口会降低压缩压力，并可能简化分级流水线。多模态工具，例如截图、图表和 UI 预览，会扩展工具表面，并创造新的上下文挑战。对权限性质进行形式化验证，例如证明拒绝规则总是优先、沙箱命令不能逃逸隔离，或恢复的会话不能继承过时权限，将提供更强的安全保证。

架构解耦。 本文分析的紧耦合本地架构只是一个已经在演化的谱系上的一个点。Anthropic 自己关于 Managed Agents 的工作（Martin et al., 2026）描述了对智能体组件（会话、运行框架、沙箱）进行虚拟化，使得“每个组件都成为一个对其他组件作出很少假设的接口，并且每个组件都可以独立失败或被替换”；这明确类比了操作系统如何将硬件虚拟化为进程和文件。Harness Design 一文（Rajasekaran, 2026）从另一个角度提出类似观点，指出“随着模型改进，有趣的运行框架组合空间并不会缩小”；相反，“它会移动”。因此，本文记录的架构应被理解为一个共同演化系统的快照，而不是固定最优解。

记忆作为一等子系统。 Hu et al.（2025）的记忆综述认为，智能体记忆正在成为一种独立的认知基底，而不仅仅是上下文窗口管理的副作用，并将自动化记忆管理、RL 驱动的记忆，以及可信记忆（隐私、可解释性和幻觉鲁棒性）识别为开放前沿。Claude Code 目前暴露了事实层（CLAUDE.md、自动记忆）和工作层（对话窗口）；经验层，也就是从过去会话中学习并自动整理出来的策略 playbook，是自然的下一步；上下文工程文献（Zhang et al., 2025a）也已经开始提供这种积累的机制。

可观测性与静默失败。 行业调查表明，已部署智能体的主导失败模式不是崩溃，而是静默错误。Bessemer 的 2026 年基础设施报告（Wade et al., 2026）估计，“78% 的 AI 失败是不可见的”；LangChain 的 1,340 名受访者智能体工程状态调查（LangChain, 2026）将质量而非成本识别为生产使用的最大障碍，并发现可观测性与离线评估之间存在巨大缺口：前者采用率接近 89%，后者为 52.4%。本文分析的架构让操作者能够看到工具调用、钩子和会话转录；但要弥合评估缺口，可能需要额外脚手架，例如生成器-评估器分离、sprint contracts，以及 Rajasekaran（2026）讨论的那类事后检查，而不只是模型改进。

治理。 随着智能体变得更加自主，更广泛的治理趋势将约束设计空间。International AI Safety Report（Bengio et al., 2026）警告说，“AI 智能体由于能够自主行动而带来更高风险，使人类更难在失败造成伤害前进行干预”；MIT AI Agent Index（Staufer et al., 2026）发现，被索引的智能体系统中，只有 13.3% 发布了智能体专属安全卡。新兴监管框架，尤其是将于 2026 年 8 月全面适用的 EU AI Act，以及围绕 AI 生成代码的版权判例演化，可能会对日志记录、透明性和人工监督施加外部约束，并塑造编码智能体架构的演化方式。

主动式架构。 由功能标志控制的 KAIROS 系统说明了该架构如何可能超越响应式工具使用。KAIROS 实现了一个带 tick 心跳的持久后台智能体：当没有待处理用户消息时，系统会注入周期性 <tick> 提示，由模型决定行动还是休眠。该设计直接回应了一个有文献记录的张力：主动式 AI 助手会使任务完成率提高 12% 到 18%，但在高频率下会降低用户偏好（Chen et al., 2025）。KAIROS 通过终端焦点感知来解决这一点：当用户离开时最大化自主行动，当用户在场时增加协作；同时通过 SleepTool 进行经济节流，因为每次唤醒都会消耗一次 API 调用，而提示缓存会在 5 分钟不活动后过期，使 sleep/wake 成为一个显式成本优化问题。这种将主动性同时绑定到用户在场状态和 token 经济性的方式，在生产级智能体系统中并不常见，尽管无法确认 KAIROS 是否在生产构建中处于激活状态。

11.7 反复出现的设计选择

将六个子系统分析合起来阅读，可以看到三个横跨独立组件的设计承诺。

分级分层优于单体机制。 安全、上下文管理和可扩展性都使用由独立机制组成的分级栈，而不是单一集成方案。权限架构将七个阶段分层组合起来：从工具预过滤，到拒绝优先规则、权限模式、自动模式分类器、shell 沙箱、恢复时不还原权限，以及钩子拦截。上下文管理将五个压缩阶段、懒加载 CLAUDE.md 文件、延迟工具 schema 和子智能体仅返回摘要叠加起来。可扩展性则将四种机制，即 MCP 服务器、插件、技能和钩子，按不同上下文成本进行分层（第 6 节）。在每一种情况下，该设计都用简单性和可调试性换取纵深防御，并接受不同层之间的交互可能产生难以从单个配置预测的涌现行为。

偏向可审计性而非查询能力的仅追加设计。 会话转录是仅追加 JSONL 文件，并通过读时链修补；权限不会跨会话边界恢复；上下文压缩通过对完整历史进行读时投影来完成，而不是进行破坏性编辑。这一承诺反复出现，是因为它保留了在不修改先前写入状态的情况下恢复、分叉和审计会话的能力。代价是，更丰富的结构化查询，例如“显示所有跨会话修改文件 X 的工具调用”，需要事后重建，而不是直接查找。

确定性运行框架内的模型判断。 在所有子系统中，该架构都信任模型在丰富确定性运行框架内的判断，而不是约束模型选择。估计 1.6% 的决策逻辑比例定量地捕捉了这一点：运行框架创造条件，包括工具路由、权限执行、上下文组装和恢复逻辑，使模型能够良好决策。层级权限会跨智能体边界保留安全不变量，assembleToolPool() 会将内置工具和 MCP 工具合并为一个统一接口，但模型仍保留充分自由，可以决定调用哪些工具以及按什么顺序调用。其权衡是：当有界上下文阻碍全局感知时，良好的局部决策可能产生糟糕的全局结果，正如第 11.4 节的经验预测所记录的那样。

12 未来方向

第 11 节将第 3 节到第 9 节所记录的架构理解为一个连贯的设计点，并揭示了该设计点所蕴含的张力、权衡和近期方向。本节进一步超越架构本身，记录六个开放问题。这些问题在第 11.6 节中已有部分命名，并且不断增长的外部文献已经使它们足够清晰，可以被具体表述出来。

这六个问题横跨本文的五价值框架（第 2.1 节）及其评估性视角（第 2.4 节）：对权威层级施加外部治理约束（第 12.5 节）；安全侧的可观测性–评估缺口（第 12.1 节）；可靠性侧的跨会话状态与关系持久化（第 12.2 节）；能力边界的四种扩展（第 12.3 节）；作为可靠执行中不同于跨会话连续性的一个独立维度的视野扩展（第 12.4 节）；以及将第 2.4 节的评估性视角重新表述为一个设计问题，而不是诊断问题（第 12.6 节）。

与第 11.6 节的表述一致，每个问题都以“是否 / 如何 / 哪些”的形式提出；当所引用来源命名了具体机制选择时，本文会列出这些机制，否则保持开放。

12.1 静默失败与可观测性–评估缺口

第 11.6 节报告的可观测性–评估采用缺口，究竟反映的是缺少工具层、缺少运行框架内部的评估接口，还是模型能力上限，相关来源并未给出结论。因此，如何暴露该段落中提到的静默错误失败模式，是运行框架的架构问题，而不是模型的能力问题。

近期实证研究从多个分辨率刻画了这一缺口。Cemri et al.（2025）归纳了十四种失败模式，覆盖系统设计问题、智能体间不对齐和任务验证；Pathak et al.（2025）构建了一个专门用于智能体轨迹异常检测的基准；Yao et al.（2024）通过 pass^k 指标揭示一致性缺口，该指标表示 k 次独立试验全部成功的概率；Kapoor et al.（2024）则认为，当前智能体基准缺少 holdout 和成本控制，限制了可观测性真正能够诊断的内容。

结合第 4 节和第 5 节分析的权限流水线与工具编排层，有两个架构问题仍然开放。第一，本文引用 Rajasekaran（2026）所说的脚手架，例如生成器–评估器分离、sprint contracts、事后检查，以及基于 Madaan et al.（2023）self-refine 模式的机制，究竟应属于运行框架内部，例如作为第 6 节记录的 27 个钩子事件之外的额外钩子事件，还是应作为一个独立评估层位于运行框架之外，相关来源并未给出结论。第二，第 6 节的现有钩子流水线是否能在当前上下文成本包络内承载这样的脚手架，也是一个进一步开放的问题。第 11.6 节指出，弥合这一缺口“很可能需要额外脚手架……而不仅仅是模型改进”，这将开放工作定位在运行框架层。

12.2 持久化：记忆与纵向同事关系

智能体状态以及人类–智能体工作关系是否应跨会话持久化，以及应以何种形式持久化，在本文当前架构中被分成两个不同层面处理。第 7 节记录了四层 CLAUDE.md 层级和自动记忆；第 9 节记录了基本仅追加的 JSONL 转录，其中显式清理重写是例外，并且恢复时不会还原会话级权限。介于这两层之间的内容，即既不是静态指令、也不是单个会话转录的持久状态，应如何设计，是一个开放架构问题。

第 11.6 节已经引用的 Hu et al.（2025）和 Zhang et al.（2025a）为一个持续累积层提供了动机。Packer et al.（2023）将 LLM 重新框定为具有分页记忆的操作系统；Chhikara et al.（2025）构建了一个能够跨重启存活的生产导向记忆存储，而 Xu et al.（2025）提出了一种研究型智能体记忆设计；Wang et al.（2024c）捕捉可复用的过程性轨迹；Shinn et al.（2023）通过跨尝试的语言强化积累自我反思轨迹；Zhang et al.（2025b）和 Huang et al.（2026）的综述则梳理了候选机制。

同样的持久化问题也在人类侧反复出现。第 11.6 节已经引用了纵向自主性证据（Huang et al., 2025; McCain et al., 2026）；Dell’Acqua et al.（2025）针对 776 名 Procter & Gamble 专业人员的现场实验，以及关于 Copilot 推广的纵向和组织研究（Stray et al., 2025）和 AI 团队协作轨迹研究（Xiao et al., 2025），都报告了随着协作累积，人类–AI 工作动态会发生变化。Wang et al.（2023）展示了一个具身智能体如何跨任务积累技能库；Mollick（2024）则将人类–AI 工作关系框定为共同智能。

一个单一底层基质是否能够同时承载用户的个人指令层级和共享组织上下文，同时保持第 7 节所记录的 CLAUDE.md 的基于文件的透明性，是一个开放架构问题。会话级权限如何与这样一个基质交互，同时又不重新引入第 9 节作为刻意安全选择所关闭的恢复还原问题，则是进一步开放的问题。

12.3 运行框架边界演化：智能体在何处、何时、对什么、与谁一起行动

第 11.6 节引用 Rajasekaran（2026）的观察：“随着模型改进，有趣的运行框架组合空间并不会缩小；它会移动。”这种移动究竟会最明显地出现在运行框架运行于何处、它何时行动、它作用于什么对象，还是它与谁协调，第 3 节到第 9 节的源码级分析无法解决。四个方向各自都有活跃研究文献，而本文只是顺带触及。

何处。 Martin et al.（2026）的 Managed Agents 设计将会话、运行框架和沙箱虚拟化为可独立替换的接口，扩展了 Packer et al.（2023）应用于上下文窗口管理、并由 Karpathy（2023）更广泛普及的虚拟记忆类比；Khattab et al.（2023）则将运行框架本身视为编译目标。

何时。 第 11.6 节已经将 KAIROS 作为一个由功能标志控制的例子引入，其动机来自 Chen et al.（2025）报告的 12%–18% 任务通过率提升，以及高频 Persistent Suggest 变体中显著的偏好惩罚，即 47% 对比 80%–90%。Liu et al.（2025）、Pu et al.（2025）和 Lee et al.（2025）将主动性设计空间扩展到编程和环境界面场景；Pasternak et al.（2025）和 Sun et al.（2025）提出用于强化这一方向的基准和训练范式，Deng et al.（2025）则综述了更广泛的图景。

什么。 视觉–语言–动作工作将运行框架扩展到文本工具返回之外：Brohan et al.（2024）和 Black et al.（2024）训练能够执行物理动作的 VLA 策略，Ahn et al.（2022）将计划锚定在机器人 affordances 中；Figure AI（2025）和 Bjorck et al.（2025）等工业系统则将类似思想推进到人形机器人控制中。这些系统面对表 1 中“按可逆性加权的风险评估”原则时，会遇到一种成本不对称性：该原则命名了这一问题，但没有量化非文本动作中的不对称成本。

与谁。 角色差异化多智能体系统（Hong et al., 2023; Li et al., 2023; Chen et al., 2023; Qian et al., 2024）会组合具有不同职责的智能体；多智能体辩论（Du et al., 2024; Liang et al., 2024）和图结构工作流（Zhuge et al., 2024）探索了不同于第 8 节父级/子智能体模式的替代方案；Guo et al.（2024）对这一空间进行了综述。

一个单一运行框架架构是否能够覆盖所有四种扩展，或者 Rajasekaran（2026）所说的“运行框架组合”是否会分裂为专门化技术栈，是一个开放设计问题。“何时”扩展直接延续了表 4 中能力与适应性之间的张力。“与谁”扩展部分映射到能力与可靠性之间的张力，但也提出了表 4 本身未覆盖的跨智能体一致性问题。“何处”和“什么”扩展则提出了本文当前子系统边界无法覆盖的进一步问题：当运行框架组件成为托管服务时，会附带哪些治理义务（第 12.5 节）；以及按可逆性加权的风险如何从文本效果扩展到物理效果。本文的单一子系统分析无法解决这些扩展如何跨轴组合，而不是只在某一个轴内部组合。

12.4 视野扩展：从会话到科学计划

第 2.1 节将可靠执行定义为同时涵盖“单轮正确性和长视野可靠性”。当自主工作超越单个会话时，第 3 节、第 4 节以及第 7 节到第 9 节所记录的架构，其主要单位是回合、会话和子智能体，它们如何继续支持长视野可靠性，是一个开放问题。

越来越多文献正在针对这一尺度展开。Lu et al.（2024）提出了一个端到端自主研究流水线，可以产出论文草稿；Beel et al.（2025）在 SIGIR Forum 中对该流水线进行了独立评估，刻画了当前“自主研究”能够交付什么，以及在哪些方面仍然不足。Gottweis et al.（2025）开发了一个跨天运行而非跨回合运行的多智能体假设生成系统，Novikov et al.（2025）则追求算法发现，其时间尺度此前需要人类专家花费数周。Kwa et al. 的 METR 研究测量了前沿智能体在固定可靠性下能够成功完成的任务时长，即 50% 时间视野，以及该视野如何随模型代际演化，为这一扩展问题提供了实证框架。

结合本文分析，长视野部署会检验第 7 节的上下文管理流水线、第 8 节的“仅返回最后 assistant 文本”策略，以及第 9 节的仅追加持久化，在多个会话组合成多会话计划时是否仍然足够。第 11.4 节已经将这一点框定为“源码级分析无法解决、但可以直接衡量的经验问题”。视野扩展将这一问题重新表述到以周为尺度的工作中：仅靠运行框架层是否能够弥合缺口、是否需要跨会话记忆基质（第 12.2 节），或者视野级工作是否需要超越会话、子智能体和记忆的协调原语，这些都不是本文以会话为作用域的分析能够解决的。

12.5 规模化治理与监督

新兴 AI 监管为实现第 2.1 节所记录的 Anthropic、操作者和用户权威层级的架构增加了外部约束。在这种外部约束下，编码智能体架构应暴露哪些日志记录、透明性和人工监督能力，仍然是一个开放设计问题。

European Commission 的 GPAI Code of Practice（European Commission, 2025a）和实施指南（European Commission, 2025b）详细说明了伴随 EU AI Act 于 2026 年 8 月全面适用而来的通用 AI 义务；第 11.6 节已经引用的 MIT AI Agent Index（Staufer et al., 2026）和 International AI Safety Report（Bengio et al., 2026）则为披露和监督侧约束提供了动机。Bartz v. Anthropic 裁决（bar, 2025）在训练数据来源方面增加了输入侧约束，即受版权保护作品的合法获取，这不同于围绕 AI 生成代码的新兴案例所处理的输出侧版权问题。OECD 关于 AI 治理框架的报告（OECD, 2025），以及 Nannini et al.（2026）对智能体提供者合规义务的早期分析，勾勒了面向监管者的接口可能是什么样子，但并未规定具体形式。

结合第 5 节分析的权限流水线，在这一约束下，当前架构有两个属性仍然开放。第一，本文记录的拒绝优先评估，可以通过会话转录（第 9 节）在内部审计，但尚不能以 GPAI Code of Practice（European Commission, 2025a）等新兴框架所设想的形式进行外部审计。第二，本文将“价值胜于规则”原则与确定性护栏相配对，但这种原则是否能够给出合规审查可能要求的显式规则表述，也是进一步开放的问题。这两个属性都位于运行框架内部，而不是模型内部；未来架构可能需要在这里暴露新接口。

12.6 重新审视评估性视角：长期人类能力

第 2.4 节将长期人类能力保存作为分析性视角引入，而不是作为与其他价值并列的共同设计价值；第 11.2 节和第 11.4 节则用外部证据扩展了这一视角，包括感知生产力与测量生产力之间的差距、理解力下降、复杂度累积、技术债持续存在、神经连接性持续变化，以及早期职业招聘下降。第 14 节进一步转向这样一个判断：“未来系统可以将这一可持续性缺口视为一等设计问题，而不是下游评估指标。”这种转向是否可能，以及一等处理需要什么架构机制，是本节记录的最后一个开放问题。

两个子问题将测量缺口与设计缺口区分开来。第一，支撑这一视角的实证主张，是否能够在会话粒度上被测量。现有引用横跨从会话到多月尺度的研究，包括 Becker et al.（2025）的 16 名开发者随机对照实验、Shen and Tamkin（2026）的理解测试比较、Kosmyna et al.（2025）的 EEG 研究、He et al.（2025）对 807 个代码库的因果分析、Liu et al.（2026）对 304,000 个提交的审计，以及 Rak（2025）的招聘序列；但第 3 节、第 4 节和第 7 节所记录的运行框架，并没有暴露用于理解力或约定漂移的逐会话信号。关于程序员交互模式的相关工作（Barke et al., 2023）和 AI 引发的代码安全回归研究（Perry et al., 2023）勾勒了会话粒度测量方式，Aiersilan（2026）则提出了用于会话级认知卸载探针的协议。

第二，一旦这些测量存在，架构是否能够响应该测量。也就是说，是否存在一种类似生成器–评估器分离（Rajasekaran, 2026）但应用于人类循环的机制、保持理解力的界面，或者尚未被命名的机制。这就是第 14 节提出的设计缺口问题。本文不对哪一类机制合适作出立场判断；并且，本文所记录的运行框架是否甚至是采取行动的正确位置，而不是 IDE、组织或人类成长循环，也不是架构分析能够裁定的问题。第 13 节综述的相关工作和第 14 节的可持续性转向，标记了本文在这一问题上停下的位置。

13 相关工作

13.1 编码智能体分类

AI 编码工具可以按照其支持的自主行动程度来组织（表 5）。GitHub Copilot（Chen et al., 2021）这样的行内补全工具，会在编辑器中建议代码片段，但不具备自主行动能力。包括 Cursor 和 Windsurf 在内的聊天集成产品，加入了对话式交互和多文件编辑，但仍然与 IDE 环境耦合。智能体式 CLI 工具，包括 Claude Code、OpenAI 的 Codex CLI 和 Aider（Gauthier, 2024），从命令行运行，并且可以在单个请求中自主执行 shell 命令、读写文件，并对输出进行迭代。像 Devin、SWE-Agent（Yang et al., 2024）和 OpenHands（Wang et al., 2024b）这样的完全自主系统，则旨在实现最少的人类监督，并且通常运行在沙箱化的云环境中。

表 5 按自主行动程度划分的 AI 编码工具类别

类别示例模式
行内补全Copilot, Tabnine编辑器插件
聊天集成Cursor, Windsurf, CodyIDE 耦合产品
智能体式 CLIClaude Code, Codex CLI, Aider工具使用循环
完全自主Devin, SWE-Agent, OpenHands沙箱 + 规划

Claude Code 与更高自主性的智能体共享一些特征，例如自动模式分类器、后台智能体执行和远程环境，但默认仍然保留交互式批准。SWE-Bench（Jimenez et al., 2023）和 HumanEval（Chen et al., 2021）等评估基准，推动了学术界对编码智能体的大部分关注。本文则从源代码出发，考察 Claude Code 的内部架构。

13.2 智能体架构模式

Claude Code 的核心循环遵循 ReAct 模式（Yao et al., 2022）：模型生成推理和工具调用，运行框架执行动作，结果反馈到下一次迭代。Toolformer（Schick et al., 2023）证明语言模型可以学习使用工具；Claude Code 使用最多 54 个内置工具和一个分层权限系统。更广泛的设计空间已经被若干综述梳理过。Weng（2023）提出了现在已成为标准的分解：规划、记忆和工具使用；Wang et al.（2024a）则整理了早期自主智能体工作。Xu（2026）将该领域围绕三个反复出现的权衡进行组织：自主性 vs. 可控性、延迟 vs. 准确性、能力 vs. 可靠性；这些权衡贯穿本文分析。Hu et al.（2024）则将智能体设计本身视为一个在组件、算法和评估函数上的搜索问题。本文刻画的是该空间中的一个具体位置。

AutoGen（Wu et al., 2024）、LangChain 和 CrewAI 等多智能体编排框架提供基于对话的智能体协调。Claude Code 的子智能体委派（第 8 节）包含权限覆盖优先级、两层权限作用域，以及每个子智能体独立的转录文件。LATS（Zhou et al., 2023）在树搜索框架中统一推理、行动和规划；Claude Code 的 plan 权限模式则实现了一种更简单的“先计划、后执行”方法。

实践者写作已经收敛到一组 Claude Code 架构所实例化的反复出现的模式。Anthropic 自己的“Building Effective Agents”（Schluntz and Zhang, 2024）区分了智能体和工作流，并主张使用简单可组合的模式，而不是沉重框架。Martin（2026）综合了生产系统中观察到的七种模式，包括让智能体拥有文件系统和 shell 访问作为通用动作层，以及按需发现动作，而不是一开始就加载每个工具 schema。Chase（2025）观察到，Claude Code 的规划工具“基本上是无操作”，其价值在于让智能体保持在正确轨道上，而不是执行任何外部计算。Wang（2025）认为，权威是学术框架最常遗漏的元素，并称信任是生产级智能体设计中“最被忽视的元素”；第 5 节的权限分析正试图弥补这一缺口。Huyen（2025）使复合错误问题变得具体：如果每一步准确率为 95%，那么一个 100 步任务的成功率只有 0.6%，这也解释了第 4 节和第 5 节中追踪的逐步验证模式为何重要。

上下文管理。 表 6 给出了 LLM 工具中上下文管理方法的设计空间分类。Claude Code 的五层压缩流水线会在升级之前，以不同粒度应用多种策略，并具有缓存感知压缩和读时虚拟视图语义。Zhang et al.（2025a）刻画了该设计所缓解的两种失败模式：摘要丢失领域细节，以及迭代式上下文重写导致的细节丢失；他们转而提出将上下文视为一种“不断演化的 playbook”，使策略随时间累积。Claude Code 的方法与这一框架一致，因为 CLAUDE.md 层级会累积结构化指令，而不是反复总结它们。Hu et al.（2025）区分了上下文工程和智能体记忆：上下文工程处理临时组装，而记忆覆盖持久事实知识和经验痕迹。Claude Code 的架构也以同样方式将二者分离：它将压缩流水线与基于文件的记忆层级配对。

表 6 基于 LLM 的工具中上下文管理方法的设计空间

方法机制粒度
简单截断丢弃最旧消息粗
滑动窗口固定大小的近期历史中
RAG检索相关片段细
单次摘要一次性压缩粗
分级压缩多层流水线非常细

安全与权限。 生产级编码智能体采用的安全架构会沿三个轴变化：批准模型（逐动作提示、分类器调解的自动化，或不提示但事后审查）、隔离边界（OS 级容器、文件系统沙箱、权限作用域工具池，或无隔离），以及恢复机制（版本控制回滚、会话级权限重置，或基于检查点的回退）。SWE-Agent 和 OpenHands（Yang et al., 2024; Wang et al., 2024b）主要依赖 Docker 容器隔离，提供约束全部智能体动作的环境级沙箱。Codex CLI 支持用于 shell 命令的沙箱模式和批准策略。Aider（Gauthier, 2024）将 Git 作为主要安全机制，通过版本控制使所有变更可逆。Claude Code 则组合了逐动作拒绝优先规则、用于自动批准的基于 ML 的分类器、可选 shell 沙箱，以及会话级权限不恢复机制；它叠加多个机制，而不是依赖单一隔离边界。

协议与可扩展性。 Claude Code 用作主要外部工具集成方式的 Model Context Protocol，已经成为一种事实标准，并拥有庞大的生态系统以及相应攻击面。Hou et al.（2025）整理了分布于 26 个主要目录中的数千个社区开发 MCP 服务器，并将 MCP 特定威胁组织为四类攻击者和十六种场景，包括工具投毒、rug pull，以及跨服务器遮蔽。第 5 节分析的权限和拒绝规则机制，以及第 6.2 节中的预过滤步骤，可以被理解为该综述所呼吁的缓解措施在运行时侧的体现。

软件架构。 分层架构模式（Garlan et al., 1993）为本文的五层分解提供了参考。基于角色的访问控制模型（Sandhu et al., 2002）为权限模式系统提供了理论基础。浏览器沙箱（Reis and Gribble, 2009）是一种类似的按进程隔离方法。多智能体系统理论（Wooldridge, 2009）有助于解释子智能体委派。

定位。 先前关于编码智能体的工作主要聚焦于基准（智能体完成任务的效果如何）、框架（如何组合智能体）和产品（用户能做什么）。本文贡献的是一个基于源码的生产级编码智能体设计空间分析，通过源码级分析和架构比较来揭示设计选择与权衡。它借鉴软件架构案例研究传统（Garlan et al., 1993），但将其应用于一个基于 LLM 的智能体：系统性地识别设计问题、映射替代方案，并将 Claude Code 的选择与 OpenClaw 进行对比。OpenClaw 是一个从不同部署语境出发运行的独立 AI 智能体系统。

14 结论

本文表明，生产级编码智能体可以被理解为对一组反复出现的设计问题的回答：推理相对于运行框架位于何处，执行、安全、可扩展性、上下文、委派和持久化如何组织，以及这些选择编码了哪些权衡。Claude Code 在这个空间中占据了一个清晰的设计点。它给予模型广泛的局部自主性，同时用一个密集的确定性运行框架围绕模型，该运行框架负责权限、工具路由、上下文压缩、可扩展性和会话恢复。通过第 2 节识别出的五种价值和十三项设计原则来看，这些选择是连贯的，而不是临时拼凑的：该系统始终优先考虑人的决策权威、安全、可靠执行、能力放大和上下文适应性。

与 OpenClaw 的比较进一步凸显了主要架构发现：相同的设计问题会在不同智能体系统中反复出现，但会产生不同答案。Claude Code 在 CLI 运行框架内投资于逐动作安全分类和分级上下文压缩；OpenClaw 则在多通道网关中投资于边界级访问控制和结构化长期记忆。两个系统甚至可以组合：OpenClaw 可以通过 ACP 将 Claude Code 托管为外部运行框架。对于智能体构建者而言，最关键的开放问题因此不是如何增加更多自主性，而是如何长期保存人类能力。正如第 2.4 节的评估性视角、第 11 节的分析，以及第 12 节调研的开放问题所记录的，该架构提供的机制有限，无法明确保存长期的人类理解、代码库一致性或开发者培养通道。未来系统可以将这一可持续性缺口视为一等设计问题，而不是下游评估指标。