Claude Code 中的 Harness：从受控工具循环到生产级 Agent 运行时#

1.1 三类证据#

社区仓库本身明确声明：它是独立教育性分析，不代表 Anthropic 官方设计，也不保证与 Claude Code 当前版本的真实内部实现完全一致。仓库前半部分主要基于一个历史源码快照，后续新能力则更多依赖黑盒实测和公开情报。²

因此，本文采用以下写法：

• “官方文档确认”：可以视为当前产品公开契约；
• “社区源码分析显示”：可以作为高价值工程参考，但不等同于官方承诺；
• “可推断”或“可能”：只作为架构解释，不写成确定事实。

1.2 为什么社区分析仍然有价值#

官方文档通常回答“用户如何使用”，而源码分析更适合回答：

• 为什么要把会话管理和 Agent Loop 分成两层？
• 工具为什么需要并发安全语义？
• 为什么旧工具输出要先裁剪，再做全局摘要？
• 为什么 Permission 不能只是一个确认弹窗？
• 为什么多 Agent 必须优先做上下文和文件系统隔离？
• 为什么错误恢复应该是状态转移，而不是统一重试？

这类问题决定了一个 Agent 能否从 Demo 演进为生产系统。

3.1 接入层#

Claude Code 当前提供终端、IDE、桌面端、Web、CI/CD 和 Agent SDK 等多种界面。官方文档强调，不同界面共享相同的底层 Agentic Loop，变化的主要是交互方式和代码实际运行的位置。³¹

接入层负责把用户请求转换为统一任务输入，并附加：

• 当前工作目录；
• Git 状态；
• 会话 ID；
• 权限模式；
• CLI 或 SDK 配置；
• 附件和文件引用；
• 最大轮数和成本限制；
• 中断信号。

3.2 会话生命周期层#

这一层负责：

• 接收和规范化用户输入；
• 管理多轮消息；
• 处理斜杠命令；
• 保存本地 Transcript；
• 恢复、继续或 Fork 会话；
• 跟踪 Token、成本和轮次；
• 将内部事件转换为终端或 SDK 输出。

官方文档确认 Claude Code 会把会话写入本地 JSONL，从而支持恢复、回退和 Fork。¹

社区源码分析进一步将这层对应到 QueryEngine：它更关注一次用户交互是否成功、消息如何持久化、花费多少预算以及最终结果如何组装。⁴

3.3 Agent Runtime 层#

这一层是真正的 Agent Loop：

1
准备上下文
2
→ 调用模型
3
→ 解析工具请求
4
→ 执行工具
5
→ 回注结果
6
→ 判断继续或结束

官方文档从产品层确认了这种循环；社区仓库则进一步分析出一个以 query() 为中心的手写异步生成器状态机。¹⁴

3.4 能力层#

能力并不只包括文件读写和 Bash，还包括：

• 内置工具；
• MCP 工具；
• Skills；
• Subagents；
• Agent Teams；
• Hooks；
• Web 和代码智能插件。

官方把这些能力区分为不同扩展机制：CLAUDE.md 提供常驻上下文，Skills 提供按需工作流，Subagents 提供隔离执行，MCP 连接外部系统，Hooks 提供确定性事件自动化。⁵

3.5 治理层#

Claude Code 可以直接在真实开发环境中产生副作用，因此必须有：

• 细粒度工具权限；
• Allow / Ask / Deny 规则；
• 不同 Permission Mode；
• 受保护路径；
• Hooks；
• Sandbox；
• 用户审批；
• 企业级 Managed Settings；
• 审计事件。

官方文档把 Permissions 与 Sandboxing 定义为互补安全层：前者控制允许做什么，后者从操作系统层限制 Bash 实际能访问什么。⁶⁷

4.1 QueryEngine 解决什么问题#

QueryEngine 关注的是“这一轮用户交互”：

• 输入是什么；
• 是否是本地命令；
• 系统提示词和记忆如何初始化；
• 消息是否持久化；
• 最大轮数和预算是否超限；
• 工具权限是否被拒绝；
• 最终输出是否有效；
• SDK 应返回哪些结构化元数据。

它类似于应用服务层或会话级 Runtime。

4.2 query() 解决什么问题#

query() 关注的是一次 Agent Loop 内部的执行：

• 上下文是否需要压缩；
• 当前应该调用哪个模型；
• 流式响应里是否出现工具调用；
• 工具是否已经执行完成；
• Tool Result 如何注入；
• 是否进入下一轮；
• 是否因为 Token、Hook、预算或错误进入恢复路径。

它类似于 Agent 状态机或执行内核。

4.3 为什么要分两层#

如果把所有逻辑都塞进一个循环，会形成以下耦合：

1
输入解析
2
+ 会话持久化
3
+ Prompt 构建
4
+ 模型重试
5
+ 工具调度
6
+ 权限等待
7
+ Token 统计
8
+ UI 输出
9
+ 最终结果提取

这会导致：

• 很难对循环本身做单元测试；
• 无法复用到 Headless 或 SDK；
• 会话恢复和单轮执行相互污染；
• 错误恢复路径难以表达；
• UI 状态和核心 Runtime 紧密耦合。

双层架构把“对话外壳”和“执行内核”分开，使 CLI、SDK 和其他界面都能复用同一个 Agent Runtime。

4.4 这与 LangGraph 有什么不同#

LangGraph 使用显式的：

1
State + Node + Edge + Reducer + Checkpoint

Claude Code 的社区分析则显示，它更接近手写的：

1
State + while/continue + Transition + Async Generator

二者都在解决同一个问题：如何把非确定性模型调用约束在一个可追踪的状态机中。

差别在于：

• LangGraph 把控制流外显为图；
• Claude Code 把控制流编码在专用 Runtime 中；
• LangGraph 更通用；
• Claude Code 更贴近 Coding Agent 的具体工作负载，因此可以做更激进的定制优化。

5.1 模型控制语义，Runtime 控制状态#

模型负责判断：

• 需要先读哪些文件；
• 应该搜索还是执行测试；
• 当前错误意味着什么；
• 下一步修改哪个位置；
• 是否已经完成任务。

Runtime 负责判断：

• 这个工具是否存在；
• 参数是否通过 Schema；
• 是否允许执行；
• 是否必须人工确认；
• 是否可以与其他工具并行；
• 是否超过最大轮数；
• 是否应该继续、恢复或终止。

这是“开放式推理”和“确定性执行”的核心分界。

5.2 错误应该被建模为状态转移#

社区仓库分析出多个 Continue Site：正常工具续轮、上下文恢复、输出 Token 扩容、续写恢复、Stop Hook 阻止终止、Token 预算续跑等。⁴

这反映出一个生产级设计原则：

不同失败具有不同语义，不能全部交给统一重试器。

例如：

统一 retry() 会掩盖这些差异，并可能制造死循环或重复副作用。

6.1 为什么不是普通 Promise#

Promise 适合“一次调用、一次结果”：

1
request → await → result

Agent 任务却需要持续产生：

• 首 Token；
• 工具调用开始；
• 工具执行进度；
• 权限请求；
• 压缩边界；
• API 错误；
• 子任务通知；
• 最终结果。

如果使用 Promise，开发者往往需要额外维护：

• EventEmitter；
• 回调；
• 队列；
• AbortController；
• 完成状态；
• 错误通道。

异步生成器可以自然表达：

1
yield：中间事件
2
return：最终状态
3
throw：不可恢复异常

6.2 流式不是 UI 特性，而是 Runtime 特性#

很多系统只在最后一层做 Token Streaming：

1
模型完整生成 → 后端逐字切片 → 前端显示

Claude Code 的思路更接近语义事件流：

1
模型事件
2
工具事件
3
权限事件
4
恢复事件
5
最终状态

这样，终端、IDE、SDK 和观测系统可以消费同一条执行流。

6.3 取消和 Backpressure#

异步生成器还天然有利于：

• 消费者处理速度控制；
• 用户中断；
• API Abort；
• 工具清理；
• 资源释放；
• 子任务取消。

对于长时间运行的 Agent，取消不是附加功能，而是 Runtime 的一等能力。

7.1 三类上下文#

7.2 缓存感知的内容排序#

Anthropic 的 Prompt Caching 以完整前缀为缓存对象，并按照：

1
tools → system → messages

形成层级。缓存命中要求被缓存前缀完全一致，工具顺序、System 内容或早期消息变化都可能导致缓存失效。¹⁰¹¹

这解释了为什么一个成熟 Harness 会：

• 把稳定内容放在前部；
• 避免在 System Prompt 中插入时间戳等高频变化字段；
• 保持工具排序稳定；
• 将动态信息放在后部；
• 对不常用工具使用延迟加载；
• 对会话历史使用增量缓存。

这不是简单的 Token 省钱，而是同时优化：

• 首 Token 延迟；
• 输入成本；
• 速率限制；
• 长会话吞吐。

7.3 CLAUDE.md 为什么不是硬配置#

官方当前文档说明，CLAUDE.md 会以用户消息形式进入上下文，而不是成为不可覆盖的系统配置。Claude 会尽力遵循，但不保证严格执行。¹²

因此：

1
CLAUDE.md = 行为上下文
2
不是权限系统
3
不是策略引擎
4
不是安全边界

真正需要强制执行的规则应该放在：

• Permission Deny；
• Hooks；
• Sandbox；
• CI；
• Policy Engine；
• 静态分析；
• 代码审查。

7.4 渐进式压缩#

官方确认 Claude Code 在上下文接近上限时，会优先清理旧工具输出，再在需要时对对话进行摘要；如果压缩后立即再次溢出，还会停止反复压缩，避免 Thrashing。¹

社区仓库进一步将其拆成更细的流水线：

1
Tool Result Budget
2
→ History Snip
3
→ Microcompact
4
→ Context Collapse
5
→ Autocompact

其中的核心思想是：

1. 先使用本地、低成本、可逆的压缩；
2. 再对局部结果做裁剪；
3. 再生成只读折叠视图；
4. 最后才调用模型做全局摘要。

这比“一满就总结全部历史”更稳健，因为全局摘要会：

• 增加一次模型延迟；
• 消耗 Token；
• 丢失细节；
• 可能改变早期指令语义；
• 造成摘要漂移。

7.5 Tool Search 与延迟加载#

官方 MCP 文档说明，Claude Code 默认支持 Tool Search：MCP 工具定义可以延迟加载，启动时只让模型看到工具名称，真正需要时再加载完整 Schema。¹³

Anthropic 的 Tool Use + Prompt Caching 文档进一步说明，延迟工具不会插入稳定的 System 前缀，而是在发现后以 tool_reference 追加到历史中，因此不会破坏已有前缀缓存。¹¹

这是一个非常重要的可扩展性设计：

1
能力数量可以很大
2
≠
3
每轮都把所有能力 Schema 塞给模型

8.1 一个生产级 Tool 应包含什么#

一个成熟工具接口至少应表达：

1
interface Tool<Input, Output> {
2
  name: string
3
  description: string
4
  inputSchema: Schema<Input>
5

6
  call(input: Input, context: ToolContext): Promise<Output>
7

8
  isReadOnly(input: Input): boolean
9
  isDestructive(input: Input): boolean
10
  isConcurrencySafe(input: Input): boolean
11

12
  validateInput(input: Input): ValidationResult
13
  checkPermissions(input: Input, context: ToolContext): PermissionResult
14

15
  maxResultSize: number
16
  interruptBehavior(): InterruptPolicy
17
}

这意味着 Tool 同时是：

1
能力描述
2
+ 参数协议
3
+ 执行函数
4
+ 风险声明
5
+ 并发声明
6
+ 权限入口
7
+ 中断语义
8
+ 结果格式

8.2 为什么安全属性必须贴近工具#

如果风险属性放在外部配置：

1
{
2
  "Edit": { "readOnly": false },
3
  "Grep": { "readOnly": true }
4
}

工具实现变化后，配置可能没有同步。

而如果工具自己实现：

1
isReadOnly(input)
2
isDestructive(input)
3
isConcurrencySafe(input)

安全语义与具体输入和实现绑定，能够处理：

• 同一个 Bash Tool 中既有只读命令，也有破坏性命令；
• 同一个文件工具对不同路径风险不同；
• 某些操作只在特定环境可并发；
• 某些参数组合必须升级审批。

8.3 Fail-Closed：默认走保守路径#

社区仓库分析的一个优秀设计是：

• 新工具默认不可并发；
• 默认不视为只读；
• 默认不能自动批准；
• 只有显式声明后才放宽。

这是一种 Fail-Closed 设计：

1
未知能力 → 保守处理
2
而不是
3
未知能力 → 默认放行

在 Agent 工具生态快速扩展时，这一点非常关键。

8.4 流式工具预执行#

社区源码分析指出，Claude Code 可能在模型流式输出期间，一旦某个完整 tool_use 块被解析出来，就立即把它送入执行队列，而不是等待整个模型响应结束。⁴

时间线从：

1
[模型完整生成][工具1][工具2][工具3]

变成：

1
[模型持续生成................]
2
       [工具1]
3
             [工具2]
4
                   [工具3]

工具延迟可以被隐藏在模型生成窗口中。

8.5 并发必须由工具语义决定#

正确的并发规则不是：

1
所有 Tool Call 都丢进线程池

而是：

1
Read / Grep / Glob
2
→ 通常可并行
3

4
Edit / Write / Bash / Deploy
5
→ 默认串行或独占
6

7
具有依赖关系的命令
8
→ 失败时取消兄弟任务

工程上可以将工具状态建模为：

1
queued → executing → completed → yielded

并保证：

• 并发安全工具可以共存；
• 非并发安全工具独占执行；
• 结果按原始 Tool Call 关联；
• 中断和错误可以传递；
• 最终回注顺序可控。

9.1 官方确认的安全主线#

官方文档确认了以下机制：

• 默认只读；
• 文件修改和 Shell 需要授权；
• Allow / Ask / Deny 规则；
• Deny 优先；
• 多种 Permission Mode；
• 受保护路径；
• Plan Mode；
• Auto Mode；
• Sandboxed Bash；
• 工作目录写入边界；
• 企业 Managed Settings；
• 用户可随时中断。⁶¹⁶¹⁷

9.2 Permissions 与 Sandbox 的分工#

官方明确说明二者互补：⁶⁷

1
Permission：
2
决定 Agent 是否被允许尝试某项动作
3

4
Sandbox：
5
即使动作已经执行，也限制进程实际能访问的文件和网络

例如：

1
Deny Rule 阻止 Bash 尝试读取 ~/.ssh
2
+
3
Sandbox 从 OS 层禁止进程访问 ~/.ssh

即使 Prompt Injection 绕过了模型的行为判断，操作系统边界仍然存在。

9.3 社区总结的七层纵深防御#

社区仓库把安全进一步归纳为：

1. 工作区信任；
2. 权限模式；
3. Allow / Deny / Ask 规则；
4. Bash 语法与静态风险分析；
5. 工具级输入和路径检查；
6. Sandbox 与 Worktree 隔离；
7. 用户确认。¹⁸

其中，AST 分析和具体静态检查数量属于社区源码分析结论，不应视为官方长期稳定接口；但“多种不同技术共同防守”的思想值得复用。

9.4 为什么 Prompt 不能成为安全边界#

Prompt 可以告诉模型：

1
不要执行危险命令
2
修改前先读取文件
3
高风险操作先询问

但 Prompt 可能因为以下原因失效：

• 模型理解错误；
• 上下文污染；
• Prompt Injection；
• 长对话压缩；
• 指令冲突；
• 工具描述不清；
• 新模型行为变化。

因此安全必须落在确定性层：

1
Prompt：降低危险请求发生概率
2
Schema：阻止畸形参数
3
Permission：决定是否授权
4
Hook：执行组织级策略
5
Sandbox：限制实际能力
6
HITL：对高风险动作最终裁决
7
Audit：记录发生了什么

9.5 Checkpoint 只覆盖可逆的本地变化#

官方说明 Claude Code 会在文件编辑前保存快照，支持本地回退；但数据库写入、部署、发送消息、Git Push 等远程副作用无法通过文件 Checkpoint 撤销。¹

因此高风险工具必须额外具备：

• 幂等键；
• Dry Run；
• 审批；
• 前置条件；
• 后置状态校验；
• 补偿动作；
• 审计日志。

10.1 Skill 与 Hook 的根本区别#

1
Skill：
2
把一套知识或流程交给模型使用
3
模型仍然决定如何执行
4

5
Hook：
6
当事件匹配时确定性触发
7
不依赖模型记得执行

例如：

1
“修改后最好运行 ESLint”
2
→ 写在 Skill 中，属于软指导
3

4
“每次 Edit 后必须运行 ESLint”
5
→ 使用 PostToolUse Hook，属于硬流程

10.2 Hook 是 Agent Runtime 的中间件#

可以把 Hook 看成：

1
Agent Middleware / Interceptor

它适合实现：

• 安全策略；
• 审计；
• 输入清洗；
• 组织级合规；
• 工具结果后处理；
• 生命周期通知；
• 自定义审批。

但 Hook 本身也可能执行代码，因此：

• 项目级 Hook 必须受工作区信任保护；
• Hook 超时不能拖死主流程；
• Hook 输出要经过 Schema 校验；
• Hook 失败要区分阻断错误和非阻断错误；
• Hook 也要被观测和审计。

11.1 State 与 Memory 不是一回事#

1
State：
2
当前任务正在发生什么
3

4
Memory：
5
未来会话可能复用什么

例如：

1
当前测试失败 3 个
2
→ State / Transcript
3

4
用户偏好所有 API 使用 Result 类型
5
→ CLAUDE.md 或 Memory
6

7
当前正在编辑 auth.ts
8
→ State
9

10
项目测试命令为 pnpm test
11
→ CLAUDE.md 或 Auto Memory

当前任务状态必须来自权威 Runtime，不能依赖模型“记住”。

11.2 MEMORY.md 是索引，不是数据库正文#

官方文档说明，Auto Memory 目录包含：

1
MEMORY.md
2
debugging.md
3
api-conventions.md
4
...

每次会话只加载 MEMORY.md 的前 200 行或 25KB，详细主题文件按需读取。¹²

这体现了两级结构：

1
常驻索引
2
→ 告诉模型有哪些记忆
3

4
主题文件
5
→ 真正需要时再加载

它本质上是在管理：

1
召回能力
2
与
3
上下文成本
4
之间的平衡

11.3 “只记不可推导信息”应作为设计原则，而非绝对事实#

社区仓库提出一个很有价值的原则：

尽量只保存不能从代码、Git 和文档重新推导的信息。²⁰

这个原则可以防止记忆漂移。例如：

1
“认证模块位于 src/auth”

代码重构后可能过期，重新搜索代码更可靠。

不过官方 Auto Memory 示例包含构建命令、架构笔记和调试经验，其中一部分理论上也能从项目中重新推导。因此，更准确的工程建议是：

1
权威事实优先实时读取；
2
只有在重新推导成本高、语义隐含或来自用户反馈时，才进入长期记忆。

11.4 记忆写入必须有 Policy#

企业 Agent 不应让模型随意写长期记忆。需要判断：

• 是否稳定；
• 是否有未来价值；
• 是否包含敏感信息；
• 是否能从权威源重新获取；
• 是否需要用户确认；
• 是否有时效；
• 是否与旧记忆冲突；
• 是否需要记录来源和时间。

推荐结构：

1
type: feedback
2
source: user_explicit
3
created_at: 2026-07-24
4
confidence: high
5
expires_at: null

12.1 Skill 适合解决什么#

当某段 CLAUDE.md 逐渐变成：

• 多步骤流程；
• 检查清单；
• 大型参考文档；
• 特定任务模板；
• 可重复执行的操作说明；

就应该移入 Skill。

因为：

1
CLAUDE.md：每轮都加载
2
Skill：只在需要时加载

12.2 Skill 的渐进披露#

官方文档说明，模型可调用 Skill 时，启动阶段通常只加载名称和描述，完整正文在 Skill 被使用时才进入上下文。²¹⁹

这是一种 Progressive Disclosure：

1
先暴露能力目录
2
→ 模型发现匹配能力
3
→ 再加载完整操作手册

它让系统能拥有大量技能，而不让每轮上下文爆炸。

12.3 Description 就是语义路由接口#

模型是否自动选择 Skill，主要依赖：

• 用户请求；
• 当前上下文；
• Skill 的名称和描述。

因此 Description 不是普通文案，而是能力路由的核心协议。

好的描述应包含：

1
什么时候使用
2
什么时候不要使用
3
输入需要什么
4
会产生什么结果
5
有何风险或限制

12.4 Skill 不是强制策略#

Skill 进入模型上下文后，仍属于模型可解释的软指令。

如果流程必须每次执行，应使用 Hook、Workflow 或代码状态机，而不是依赖 Skill。

13.1 MCP 解决的是能力互操作，不是自动安全#

MCP 提供：

• 工具发现；
• Schema；
• Resources；
• Prompts；
• Transport；
• OAuth；
• 动态能力更新。

但 MCP 工具仍必须进入 Claude Code 的：

1
Tool Search
2
→ Tool Registry
3
→ Permission
4
→ Hook
5
→ Execution
6
→ Result Processing

外部工具不能因为是 MCP 就绕过安全层。

13.2 MCP Tool Search 的架构价值#

当工具数量从 10 个增长到 1000 个时，直接加载所有 Schema 会带来：

• Context 爆炸；
• Prompt Cache 失效；
• 工具选择准确率下降；
• 首次请求延迟升高；
• 无关能力干扰。

官方 Tool Search 采用：

1
启动只加载名称
2
→ 需要时搜索
3
→ 按需加载完整工具定义

这使 Capability Registry 可以扩展，而不把复杂度全部转嫁给模型上下文。¹³

13.3 大结果必须外部化#

MCP、Shell、搜索和数据库查询都可能返回巨大结果。

成熟 Harness 应支持：

1
小结果 → 直接回注
2
中结果 → 截断 + 摘要
3
大结果 → 落盘 / 对象存储 + 返回引用

模型需要全文时再分块读取，而不是把 100K 字符一次塞入上下文。

14.1 为什么 Subagent 要独立上下文#

一个搜索型子任务可能产生：

• 数十个文件内容；
• 大量日志；
• 中间假设；
• 无关搜索结果。

如果全部进入主上下文，会造成：

• 主任务被噪声污染；
• Token 费用上升；
• 压缩提前触发；
• 关键指令被稀释；
• 后续推理注意力分散。

Subagent 用自己的上下文处理这些材料，只返回结论，相当于一种“语义 Map-Reduce”。

14.2 工具隔离比角色 Prompt 更重要#

只给角色名字：

1
你是安全专家

并不能构成真正隔离。

更重要的是：

1
Explore Agent
2
→ 只读工具
3
→ 快速模型
4
→ 独立上下文
5

6
Plan Agent
7
→ 只读工具
8
→ 强推理模型
9
→ 结构化计划
10

11
Implementation Agent
12
→ Edit / Bash
13
→ 更严格 Permission
14
→ Worktree 隔离

这体现最小权限原则。

14.3 文件系统隔离#

并行 Agent 如果共享同一工作区，可能同时修改同一文件。

可选策略：

• 文件所有权分区；
• 乐观锁；
• Patch 合并；
• Git Worktree；
• 独立容器；
• 最终 Integrator 统一合并。

官方文档把 Worktree 作为并行会话隔离方式；社区仓库也将 Worktree 视为多 Agent 避免代码冲突的重要手段。²³²⁴

14.4 从模型编排到确定性编排#

少量任务可以让模型动态决定：

1
派谁
2
何时派
3
如何汇总

但规模扩大后会遇到：

• 重复派发；
• 并发失控；
• 等待屏障不合理；
• 中间格式不稳定；
• 无法断点续跑；
• 成本不可预测。

社区仓库对 Dynamic Workflow 的黑盒分析提出一种值得关注的模式：由主模型生成确定性脚本，再由 Runtime 执行 agent()、pipeline()、parallel() 和 Schema 校验。²⁵

该结论属于黑盒逆向，不应视为官方稳定接口，但它揭示了一条普遍规律：

1
开放探索留给 Agent
2
大规模编排交给确定性 Runtime

推荐演进路径：

1
小任务：单 Agent
2
独立副任务：Subagent
3
多 Worker 并行：Coordinator / Team
4
大批量任务：Deterministic Workflow + Agent Workers

15.1 四种记录回答不同问题#

15.2 ID、树和聚合不能混为一谈#

社区仓库对观测系统的一个优秀总结是：

1
离散事件用 ID 关联
2
因果关系用 Span 树表达
3
聚合指标拒绝高基数 ID

这适用于任何 AgentOps 系统。

15.3 默认保护隐私#

官方 OTel 文档说明：

• 用户 Prompt 默认不记录；
• Tool 参数默认不记录；
• Tool 内容默认不记录；
• 原始 API Body 默认不记录；
• 开启详细日志时可能暴露敏感数据，需要额外脱敏和后端治理。²⁶

因此可观测性不是“记录越多越好”，而是：

1
可诊断性
2
×
3
隐私
4
×
5
成本
6
×
7
基数

之间的平衡。

16.1 全链路流式事件#

模型开始生成后立即输出，不等待完整响应。

16.2 工具流式预执行#

社区源码分析认为，完整工具块一旦解析完即可开始执行，将工具延迟覆盖在模型生成时间中。⁴

16.3 记忆与能力预取#

与模型调用并行：

• Memory 召回；
• Skill 发现；
• MCP 连接；
• 工具准备；
• UI 初始化。

16.4 Prompt Cache#

稳定的 Tool 和 System 前缀可以复用缓存，减少重复输入处理。官方 Prompt Caching 文档确认，缓存命中可以降低延迟、费用并改善速率限制利用率。¹⁰

16.5 延迟加载#

不常用的：

• MCP 工具；
• Skill 正文；
• 观测 Exporter；
• 子 Agent 上下文；
• 大型参考资料；

不进入冷启动关键路径。

16.6 速度的真正公式#

1
感知速度
2
≈
3
尽早反馈
4
+ 并行隐藏等待
5
+ 缓存稳定前缀
6
+ 减少无效上下文
7
+ 限制串行关键路径

17.1 恢复不能制造重复副作用#

如果模型调用后网络中断，不能简单重放所有工具。

副作用工具需要：

• Idempotency Key；
• Execution ID；
• 状态查询；
• Exactly-Once 的业务近似；
• 可补偿操作；
• Tool Result 持久化。

17.2 终止不是只看“模型不再调用工具”#

还应该检查：

• 任务目标是否达成；
• 测试是否通过；
• 必要工具是否执行；
• 是否有未处理错误；
• 是否等待人工；
• 是否达到预算；
• 是否重复循环；
• 是否出现上下文 Thrashing。

17.3 Verifier 优先使用确定性信号#

验证顺序建议：

1
测试 / 编译 / 数据库状态
2
>
3
静态规则 / Schema
4
>
5
专用判别器
6
>
7
通用 LLM 自我反思

只要存在可执行标准，就不应让模型仅凭文本判断“完成了”。

原则一：模型负责语义决策，代码负责硬约束#

1
模型决定下一步应该做什么；
2
Runtime 决定是否允许、如何执行、如何恢复。

原则二：所有副作用必须经过 Tool#

模型不能绕过能力接口直接操作真实世界。

原则三：上下文是编译产物#

每轮都要选择、排序、压缩、隔离和缓存，而不是机械拼接历史。

原则四：工具应携带风险与并发语义#

isReadOnly、isDestructive、isConcurrencySafe 应是一等属性。

原则五：默认保守#

未知工具、未知路径、未知副作用和未知权限应进入更严格流程。

原则六：错误是状态转移#

上下文超限、Token 截断、权限拒绝和工具失败不能走同一重试逻辑。

原则七：记忆不能替代权威数据源#

代码读代码，Git 读 Git，业务状态查业务系统。

原则八：多 Agent 优先做隔离#

独立上下文、最小工具、文件隔离、结构化结果比角色命名更重要。

原则九：规模越大，编排越应确定性化#

小范围探索可由模型控制，大规模 fan-out 应由 Workflow Runtime 管理。

原则十：观测系统必须与隐私和成本共同设计#

不是“全量记录一切”，而是按 Metrics、Events、Trace 和 Transcript 分层。

19.1 哪些层可以交给框架#

LangGraph、Temporal、Agent SDK 等框架可以帮助实现：

• 状态机；
• Checkpoint；
• 中断恢复；
• 节点执行；
• Streaming；
• 工具循环；
• 子图；
• Trace。

19.2 哪些问题框架不会替你解决#

框架无法自动决定：

• 哪些工具是危险的；
• 哪些字段允许并发写；
• 哪些结果是权威事实；
• 哪些动作必须人工审批；
• 业务完成条件是什么；
• 哪些记忆应该持久化；
• 什么错误可以安全重试；
• 多 Agent 是否真的比单 Agent 更好。

Harness 的核心仍然是业务和系统设计。

Anthropic / Claude 官方资料#

社区源码分析与黑盒研究#