30 运行时综合与设计原则

本章目标

到了这一章，前面的研究已经基本把 Claude Code 拆成了一套完整运行时：

入口与启动
commands / tools
QueryEngine 与 query loop
UI / interaction
integrations / extensibility
state / config / permissions
skills
hooks / side-channels
memory
recovery
message/context assembly
tool system
streaming / SDK boundary
compact / effective history
tasks / background execution
subagents / isolation
以及第 27–29 章补上的总图、阅读路径与术语系统

所以这一章不再追一个局部问题，而是回答五个更总的问题：

如果只保留最关键的判断，Claude Code 的 runtime 本质上是什么？
前面这些章节最终能收束成怎样的统一模型？
Claude Code 最成熟、最值得学的设计点到底有哪些？
哪些地方是“功能多”，哪些地方是真正的“架构成熟”？
对做 agent runtime / harness 的人，这套研究最终留下哪些可迁移原则？

这章的重点不是回顾章节目录，而是做真正的架构综合。

一、先给出总体判断

如果把前面所有章节压缩成一句话，我会把 Claude Code 的总体运行时概括成：

一套围绕 QueryEngine / query loop 作为主状态骨架，同时由 Context Plane、Execution Plane、Governance Plane、Side-Channel Plane 和 Interaction Plane 共同支撑的长期协作型 agent runtime；它的成熟不主要在“功能数量”，而在于这些能力被分层组织、受控连接，并且被放进了可持续演化的边界结构里。

这句话里最关键的不是“Claude Code 很复杂”，而是：

它不是把复杂度堆在一个地方
而是把复杂度拆成多个 plane，再让它们在边界处接合

如果再进一步压缩成最核心的三点，可以说：

主循环是骨架，但不是全部
长期协作能力来自主路径之外的正式机制
治理、上下文与执行被明确分层，而不是混成一个大状态黑箱

这一点，构成了前面全部研究的总结论。

二、Claude Code 的 runtime 本质上是什么

从前面所有章节综合起来看，Claude Code 最稳妥的定位不是：

一个聊天界面
一个会跑 shell 的助手
一个 prompt 壳加几个工具
一个单轮 agent demo

而更像：

一个围绕长期协作、受控执行、上下文管理和治理控制组织起来的 agent runtime / harness

这个判断很重要，因为一旦你把 Claude Code 定位成 runtime，而不是某个交互产品，很多设计选择就会变得合理：

为什么有 QueryEngine 和 query loop 分层
为什么有 settings / trust / policy / permissions
为什么有 memory 但又不把 memory 等同于 summary
为什么有 compact boundary
为什么要有 hooks / side-channels
为什么要有 task system / subagents / worktree isolation
为什么要把 SDK-visible protocol 和内部 message model 分开

这些都不是“附加功能”，而是在支撑一个长期可工作的 agent 环境。

三、这套系统最终可以收束成什么统一模型

第 27 章已经给出了六个 plane 的总图。
到了本章，可以把它们真正收束成一个工作模型：

1. Interaction Plane

负责：

用户如何进入系统
系统怎样把运行态输出给用户与外部集成

2. Runtime Core

负责：

一次 turn 的主状态推进
assistant -> tool -> tool_result -> continue / stop

3. Execution Plane

负责：

系统实际能做什么
tools、tasks、background jobs、subagents

4. Context Plane

负责：

模型这一轮到底看到什么
system prompt、attachments、memory、compact、effective history

5. Governance Plane

负责：

谁能控制系统
哪些能力能开
哪些来源可信
哪些动作要 allow / deny / ask

6. Side-Channel Plane

负责：

在主路径之外并行预取、分析、收尾、提炼、写回

如果只看这个模型，就能发现一个很关键的事实：

Claude Code 的设计成熟度，不在某个单层里特别炫
而在这些层之间的连接方式很克制、很清楚

这才是它和很多 demo agent 最本质的差别。

四、什么叫“主循环是骨架，但不是全部”

这是前面最反复出现、也最需要在本章收束的判断。

1. QueryEngine / query loop 确实是中心骨架

如果没有 QueryEngine 与 query loop，Claude Code 的很多能力根本无处安放。
它们负责：

turn 入口
messages/state 推进
tool/result 接续
follow-up / stop
把很多周边能力挂在正确时机上

所以把它叫骨架是成立的。

2. 但成熟系统绝不能把所有东西都塞进骨架

Claude Code 没有这么做。
它没有把：

settings source merge
durable config
memory 持久化
compact 历史语义
side-channel extraction
SDK protocol 投影
tasks / scheduling
subagents

统统糊进同一个巨大循环文件里。

这意味着它承认一个非常重要的工程事实：

主状态机必须清楚
但主状态机不应承担全部系统责任

这是一个非常成熟的 runtime 判断。

五、Claude Code 最成熟的地方，不是“功能多”，而是“边界稳”

这也是整套研究最终最应该保留下来的结论。

很多系统表面上也有：

tools
memory
permissions
streaming
subagents

但真正拉开差距的，不是有没有这些词，而是它们之间的边界有没有被清楚处理。

Claude Code 当前最值得学的，是它相对稳定地区分了这些东西：

1. Config / Settings / Bootstrap State / AppState

不同生命周期，不混。

2. Tool / Skill / Hook / MCP / Command

不同执行语义，不混。

3. Memory / Compact / Summary

不同问题域，不混。

4. Internal Message History / Effective History / SDK Protocol Stream

不同消费对象，不混。

5. Main Path / Side-Channel

不同运行时职责，不混。

6. Task / Background Execution / Subagent

不同工作组织层，不混。

这些边界感，比任何单一“高级功能”都更值钱。

六、Claude Code 最值得借鉴的 12 条设计原则

下面我会把前面所有章节压缩成 12 条最值得带走的设计原则。

原则 1：主循环必须清楚，但不能承载全部复杂度

Claude Code 用 QueryEngine + query loop 维持了一个明确的主状态机，但没有试图让所有增强能力都变成 loop 内部步骤。

启发
做 agent runtime 时，主循环应是骨架，而不是万能容器。

原则 2：上下文是构造出来的，不是天然存在的

Claude Code 明显区分了：

原始消息历史
effective history
system/user context injection
attachments
memory prompt / relevant memory
API normalization

启发
模型上下文绝不能被简化成“聊天记录 + system prompt”。

原则 3：长期记忆、当前历史压缩、当前检索结果必须分层

durable memory、relevant memory、compact boundary、summary 在 Claude Code 里不是同一个概念。

启发
长期协作系统里，“记住什么”和“这轮带什么上下文”必须拆开。

原则 4：治理层必须是一等架构对象

Claude Code 的 settings、policy、trust、permissions 不像许多系统那样是事后补丁，而是正式控制面。

启发
安全、信任和权限不能作为“后面补点判断逻辑”，而应该是 plane 级设计。

原则 5：工具面要做成受控 contract，而不是任意函数暴露

tool system 的核心不是“能调用很多功能”，而是：

名称稳定
schema 清楚
权限可裁决
结果可回填

启发
工具系统首先是 contract design，其次才是执行实现。

原则 6：执行面与治理面要强连接，但不应互相吞掉

tools 能做什么是一回事，当前能不能执行是另一回事。
Claude Code 通过 permission pipeline 把二者接起来，但没有混成一层。

启发
执行 contract 与治理裁决要耦合，但职责要分开。

原则 7：主路径之外必须有正式的 side-channel 结构

prefetch、post-sampling hooks、stop hooks、memory extraction、skill improvement 这些机制说明：

不是所有重要逻辑都应放进主路径
但这些旁路也不能成为无组织外挂

启发
成熟 runtime 需要正式 side-channel plane，而不是临时回调拼盘。

原则 8：对外协议和内部运行态必须分开

Claude Code 明显区分了：

model-visible context
internal message history
SDK-visible stream protocol

启发
不要把内部对象模型直接导出成 public protocol。

原则 9：长会话不是靠“多塞历史”解决，而是靠边界化管理解决

compact boundary、effective history、recovery boundary 都说明：

长会话管理不是“总结一下旧消息”那么简单
关键在于给后续 query 一个明确可继续的现实

启发
会话压缩最好是 runtime boundary 机制，而不是单纯摘要功能。

原则 10：长期协作 agent 必须有任务基础设施

task objects、background execution、cron、output recovery 说明 Claude Code 不满足于单轮 query。

启发
真正可工作的 agent 应该能组织长期任务，而不仅是即时响应。

原则 11：子代理的核心价值是上下文隔离，而不只是并行

subagent、agent type、SendMessage、worktree isolation 都说明：

委托的重点不是“多一个 worker”
而是“把局部问题放进独立上下文处理”

启发
多代理系统最重要的常常不是速度，而是隔离。

原则 12：成熟 agent runtime 的关键，不是功能数量，而是语义层次稳定

Claude Code 让人真正觉得成熟的地方，不在于“什么都有”，而在于：

每种东西大致知道自己在哪一层
与其他层怎么连接
为什么不应该变成别的东西

启发
层次稳定，比功能列表更重要。

七、Claude Code 体现出的 8 个“架构成熟信号”

如果不谈具体实现细节，只看架构气质，我会认为 Claude Code 至少体现出 8 个成熟信号。

1. 主状态机清楚

有骨架，而且骨架可分析。

2. 输入面、执行面、输出面分开

context、execution、protocol 没被混成一坨。

3. 控制面不是附属品

governance 是正式 plane。

4. 旁路机制有正式位置

side-channel 被架构化，而不是临时化。

5. 会话压缩有显式边界

compact boundary 很关键。

6. 长期记忆与当前上下文不混

memory system 的分层比较成熟。

7. 长时工作流被纳入正式运行时

task / cron / background execution 说明它不只是单轮 assistant。

8. 多代理委托强调隔离与责任边界

subagent 不是泛滥 delegation，而是 controlled delegation。

这些信号组合起来，才让 Claude Code 像一个真正的 runtime。

八、哪些地方最容易被外部观察者低估

从外部看 Claude Code，很容易低估几个地方。

1. 低估 governance

很多人会盯着 tool、memory、subagent 看，但真正把系统做“产品化”的往往是 governance plane。

2. 低估 context assembly

如果只看界面聊天，很容易误以为“上下文就是对话历史”。
实际上上下文层是高度工程化的。

3. 低估 side-channel

prefetch、post-sampling、stop hooks 这些东西不显眼，但它们对系统成熟度贡献很大。

4. 低估 compact

很多人觉得 compact 是“小功能”，其实它关系到长会话 runtime 的现实定义。

5. 低估 task / subagent 基础设施

这些机制说明 Claude Code 的目标远超过“会聊天、会跑命令”。

九、对做 agent runtime / harness 的人，最该带走什么

如果你不是为了理解 Claude Code 本身，而是为了做自己的系统，那么最值得带走的不是具体文件名，而是下面这些更抽象的判断。

1. 先分 plane，再分模块

先问：

哪些是交互面
哪些是主推进面
哪些是执行面
哪些是上下文面
哪些是治理面
哪些是旁路面

比一开始就陷入模块实现更有价值。

2. 长期协作能力不能只靠 prompt engineering

需要正式结构去承载：

memory
compact
tasks
background execution
subagents
governance

3. 任何成熟 agent 最终都绕不开边界工程

真正难的不是“再加个功能”，而是：

这功能属于哪层
跟别的层怎样连接
它不该和什么混

Claude Code 这套研究里最可迁移的，就是这种边界工程意识。

4. 如果必须让系统复杂，就把复杂度分散到稳定平面上

Claude Code 并不简单，但它尽量避免让复杂度全部集中在一个巨型状态机里。

这比“做一个无所不包的大 loop”要成熟得多。

十、如果把整套研究最后压缩成一张心智图

可以把它压缩成下面这张文字心智图：

Claude Code = 长期协作型 agent runtime

核心骨架：
  QueryEngine + query loop

它之所以成熟，不在于只有骨架，
而在于骨架外面还有 5 个被明确分层的 plane：

  Interaction Plane
    - 用户入口
    - UI/CLI
    - SDK stream

  Execution Plane
    - tools
    - tasks
    - background execution
    - subagents

  Context Plane
    - system prompt assembly
    - attachments
    - memory
    - compact/effective history

  Governance Plane
    - settings/config
    - trust
    - permissions
    - policy/managed settings

  Side-Channel Plane
    - prefetch
    - post-sampling hooks
    - stop hooks
    - extraction/improvement

最重要的成熟信号：
  - 主路径清楚
  - 边界清楚
  - 长期协作机制正式化
  - 执行与治理分层
  - 输入面与输出面分层

如果读完整套书之后，脑子里能留下这张图，那这套研究就算成功了。

十一、这套研究最终最稳妥的结论是什么

如果必须把前面所有章节里最稳妥、最不容易过时的判断提炼出来，我会保留下面这些：

Claude Code 的核心不是单一 prompt，而是 runtime。
QueryEngine / query loop 是骨架，但成熟度来自骨架外的分层机制。
Claude Code 明确地区分了执行、上下文、治理、交互和旁路。
它对长期协作的理解，不是单靠 summary，而是 memory + compact + tasks + subagents 的组合。
工具系统真正重要的是 contract 与 governance，而不是“能跑多少命令”。
Side-channel plane 是其成熟度的重要来源。
SDK stream 与内部 runtime message model 被清楚分开。
它更像一个持续协作环境，而不是一次性问答器。

这些结论即使未来实现细节变化，也大概率仍然有参考价值。

十二、这套研究的边界

最后也需要明确这套研究的边界。

这套研究最擅长的是：

runtime 架构分析
边界划分
源码链路上的稳定判断
对 harness engineering 的工程启发

它不打算重点做的是：

使用教程
prompt 技巧汇总
功能 marketing 文案
对所有未公开实现做强猜测

也正因为这个边界，这套研究的价值才主要落在：

架构理解
工程借鉴
runtime 设计思维

而不是“如何快速成为 Claude Code 高手”。

Harness 视角

如果把整套研究最终放回 harness engineering 的语境，我会给出这个总判断：

Claude Code 最值得学的，不是某一项神奇能力，而是它如何把长期协作 agent 所需的主循环、上下文、执行、治理、旁路、异步和隔离这些复杂因素，组织成一套仍然能被分析、能被治理、能被扩展的 runtime 结构。

这正是很多 agent 系统最难做到的地方。

工程化启发

1. 架构成熟的核心指标是边界稳定

边界不稳，功能越多越乱。

2. 主循环应该尽量薄，但不能失去骨架地位

不是越大越好，也不是越弱越好。

3. 治理、上下文、输出协议都必须独立建模

它们不是主状态机里的小细节。

4. 长期协作型 agent 一定需要正式的非主路径机制

memory、compact、tasks、subagents、hooks，这些都不是“附加功能”，而是长期协作的前提。

5. 多代理和异步能力必须建立在清晰责任边界上

否则系统会很快失控。

本章小结

如果把这一章压缩成一句话，可以说：

Claude Code 的真正成熟，不在于它拥有多少功能，而在于它把长期协作 agent 所需的 QueryEngine/query 主骨架、上下文构造、执行能力、治理控制、side-channel 机制、异步任务与子代理隔离，组织成了一套边界相对清楚、职责相对稳定、能够持续演化的 runtime 结构；对做 agent runtime / harness 的人而言，这套结构比任何单一技巧都更值得借鉴。

从整套研究最终能稳妥保留下来的设计原则包括：

主循环必须清楚，但不能承载全部复杂度；
模型上下文是构造出来的，不是天然给定的；
长期记忆、当前历史压缩和即时检索结果必须分层；
工具系统首先是受控 contract，其次才是执行器；
治理层必须是一等架构对象；
side-channel 需要正式的架构位置；
对外协议与内部运行态必须分开；
长期协作 agent 需要 memory、compact、tasks、subagents 等正式基础设施；
成熟系统最终拼的不是功能数量，而是边界稳定性。

源码证据索引

src/QueryEngine.ts — session owner 与 runtime 核心骨架
src/query.ts — turn loop、transition、recovery、compact、hooks
src/utils/messages.ts — context assembly 与 message projection 代表路径
src/services/tools/toolOrchestration.ts — execution plane / orchestration 代表路径
src/memdir/memdir.ts — durable memory / long-horizon context 代表路径
src/utils/permissions/permissions.ts — governance / permission pipeline 代表路径
src/query/stopHooks.ts — side-channel / post-turn 收口代表路径
src/services/analytics/index.ts — observability / evaluation 基础设施代表