Harness Engineering 核心模式¶
Ch05.042 Harness Engineering 核心模式¶
📊 Level ⭐⭐ | 11.6KB |
entities/harness-engineering-core-patterns.md
Harness Engineering 核心模式¶
[!summary] 核心洞察 Harness Engineering 的核心是通过工程化手段构建确定性，以承载模型不确定性。三个生产系统（Claude Code、Claude Managed Agents、Hermes）的共同模式：持久化指令分离、分层记忆、会话不可变事件流、执行环境隔离、凭证安全设计。
Claude Code 的八大模式¶
指令与上下文管理¶
| 模式 | 做法 | 代价 |
|---|---|---|
| 持久化指令文件 | 指令不随对话消失 | 需要随项目更新维护，否则误导 |
| 作用域上下文组装 | 按范围（组织/项目）拆分指令，动态加载 | 规则分散、可读性变差、可能冲突 |
| 分层记忆 | 常驻摘要→按需细节→仅搜索历史 | 实现复杂，需设计分层流动 |
| 做梦整理 | 后台定期去重/清理/重组记忆 | 消耗资源，可能误删 |
| 渐进式上下文压缩 | 新对话保留细节→旧对话总结→更早摘要 | 压缩有信息损失，可能导致"编造" |
工作流与编排¶
| 模式 | 说明 | 代价 |
|---|---|---|
| 探索-规划-行动循环 | 三步严格分离（只读→规划→执行） | 小任务显得"笨重" |
| 上下文隔离子智能体 | 不同阶段独立上下文和权限 | 需要协调信息传递 |
| 分支-合并并行 | 并行子任务分发到独立环境，合并结果 | 合并复杂、代码冲突 |
工具与权限¶
- 渐进式工具扩展： 开始只提供必要工具，复杂工具按需动态加载
- 命令风险分类： 按类型/参数/影响自动评估风险等级，自动执行/请求确认/拦截
- 单用途工具设计： 常用操作封装为专用工具，非通用 Shell 命令
自动化¶
- 确定性生命周期钩子： 在关键节点自动触发预设动作（格式化等），不依赖可能被遗忘的指令
Claude Managed Agents：三件套解耦架构¶
宠物与牲畜哲学¶
- Session（会话）是宠物： 精心培育、持久保存、不可丢失
- Harness + Sandbox 是牲畜： 随时创建、销毁、替换
三件套解耦¶
| 组件 | 角色 | 关键特性 |
|---|---|---|
| Claude（大脑） | 推理和决策 | LLM 核心 |
| Harness（双手） | 驱动运行循环 | 无状态，可随时替换 |
| Sandbox（工作台） | 隔离执行环境 | 可隔离、可重建、可扩展 |
Session 设计： 只追加事件流（emitEvent() / getEvents()），天然支持重放和状态恢复。
Harness 设计： 循环：取上下文→调用 Claude→记录响应→路由工具→记录结果→循环。无状态→可替换。
Sandbox 设计： 完全隔离（独立文件系统/进程/网络）。
核心安全：凭证永不进沙盒¶
保险库(vault) + 代理(proxy)架构：
- 第三方凭证存储在独立保险库，Harness/Sandbox 都无法直接访问
- 调用外部工具时，通过代理按需获取凭证执行
- 凭证始终不暴露给 Sandbox 代码
优势：最小权限原则、所有外部调用可审计、凭证可统一轮换。
多智能体协作模式¶
| 模式 | 架构 | 适用场景 |
|---|---|---|
| 多脑一手 | 多 Claude 共享 1 Sandbox | 多角度分析同一代码（安全+性能） |
| 一脑多手 | 1 Claude 控制多 Sandbox | 多环境同时执行 |
| 多脑多手 | 多 Claude 各有 Sandbox，共享 Session | 最复杂的多步骤任务 |
上下文工程三件套¶
- 上下文压缩： 将满时压缩早期对话为总结，原始数据保留在 Session
- 记忆工具： Claude 主动写入持久存储，后续主动检索
- 上下文裁剪： 发送前智能裁剪不相关内容
性能优化¶
大脑从沙盒解耦： 解耦前每次推理需等 Sandbox 启动；解耦后 Session 拉取事件后推理立即开始。首 Token 延迟降低 60-90%。
Hermes：五段式循环 + 五层记忆¶
五段式循环¶
规划 → 执行 → 观察 → 学习 → 适应
五层记忆架构¶
| 层级 | 定位 | 说明 |
|---|---|---|
| L1 短期记忆 | 便利贴 | 当前对话临时信息 |
| L2 技能手册 | 肌肉记忆 | 复杂任务后自动生成 SKILL.md，形成可复用流程 |
| L3 知识库 | 语义记忆 | 向量存储实现模糊检索 |
| L4 用户建模 | 对你的了解 | "辩证式"更新：不一次定终身，持续观察调整 |
| L5 工作日志 | 长期档案 | FTS5 全文检索 + LLM 摘要，跨会话搜索 |
三大系统的共性与差异¶
| 维度 | Claude Code | Claude Managed Agents | Hermes |
|---|---|---|---|
| 会话管理 | 持久化指令+渐进压缩 | 不可变事件流+重放 | 五层记忆+FTS5检索 |
| 隔离执行 | Sandbox（牲畜哲学） | Sandbox（牲畜哲学） | 本地+沙箱两种环境 |
| 安全设计 | 命令风险分类 | 凭证永不进沙盒 | 确定性钩子 |
| 记忆进化 | 做梦整理 | 记忆工具 | 五层自动演进 |
| 协作模式 | 子智能体隔离 | 多脑/多手组合 | 单智能体自进化 |
深度分析¶
1. 三件套解耦的本质是关注点分离¶
Claude Managed Agents 的 Session/Harness/Sandbox 三件套并非简单的模块拆分，而是一种系统级的关注点分离（Separation of Concerns）设计。Session 专司状态持久化（类比 K8s 的 PersistentVolume），Harness 专司推理循环（控制器），Sandbox 专司执行（计算资源）。这种分离的深层价值在于：每个组件都可以独立演进、独立故障、独立替换，而不影响整体系统的正确性。解耦后的首 Token 延迟降低 60-90%，这不是优化的结果，而是架构正确性带来的副产品。
2. 凭证永不进沙盒是结构性安全而非权限控制¶
传统安全思维是"给受限 Token"，而 Claude Managed Agents 的设计是"让 Token 物理上不可达"。 这不是程度上的差异，而是范式上的根本区别——前者是权限收窄（假设攻击者还能拿到东西），后者是架构性消除（攻击者根本拿不到）。当 Claude 被 prompt injection 攻击时，架构性安全仍然有效，因为 Token 不在 Claude 的可达范围内。
3. 做梦整理与做梦生产是一体两面¶
Claude Code 的"做梦整理"（后台去重/清理/重组记忆）与 Hermes 的五层记忆演进，都隐含一个共同洞察：记忆系统必须同时具备整理（遗忘）和积累（留存）两种机制。没有整理机制的系统会因熵增而崩溃（所有历史都等权重要 = 没有重要），没有积累机制的系统无法形成跨会话的连续性。有效的记忆设计不是增加层数，而是设计层与层之间的流动规则——哪些信息升级、哪些降级、哪些淘汰。
4. 宠物与牲畜的哲学映射到 Agent 生命周期管理¶
Session 是宠物（精心培育、不可丢失），Sandbox 是牲畜（随时替换）——这个隐喻揭示了一个深刻的工程哲学：不同组件应有不同的变更频率和恢复策略。Session 承载了任务的完整历史，是系统恢复的真相来源，必须严格保护；Sandbox 是执行计算的资源，应该设计为可任意替换的 cattle，而非需要人工修复的 pet。这一原则直接延伸到现代云原生架构的核心教条——无状态、可替换、弹性扩展。
5. 多脑多手模式暴露状态一致性难题¶
多脑多手（多 Claude 各自 Sandbox，共享 Session）是最复杂的多智能体协作模式，也是当前最容易出问题的模式。 当多个专业化的 Claude 实例并行工作时，它们对"任务完成"的判断可能不一致——Generator 认为代码写完了，Evaluator 认为测试没通过，Planner 认为需求理解有偏差。这种状态不一致如果不能被及时仲裁，整个系统的协作效率会急剧下降。现有解决方案（STATE.yaml、共享状态文件）都是临时工程，都缺乏像 Git 一样的版本控制和冲突合并机制。
实践启示¶
1. 设计 Harness 时先确定组件的生命周期策略¶
在设计任何 Harness 系统之前，首先要回答：每个组件是宠物还是牲畜？ Session 必须是宠物，需要持久化保护；Harness 应该是无状态的 cattle，可随时替换；Sandbox 是计算资源，应该设计为可快速创建和销毁的 cattle。这个分类决定了后续所有的架构决策——持久化策略、故障恢复机制、扩展策略。如果不确定某个组件的生命周期，后续设计就会在根本上摇摆。
2. 凭证管理必须走保险库+代理架构¶
在任何涉及外部 API 调用的 Agent 系统中，都不应该让 Agent（无论是 Harness 还是 Sandbox）直接持有第三方凭证。正确做法是：凭证存储在独立保险库中，Agent 通过代理按需获取，凭证对 Agent 代码物理不可达。这个架构性原则比任何权限收窄策略都更可靠——因为它不依赖于"攻击者拿不到"或"模型不会被注入"这些假设，而是从根本上消除了攻击面。
3. 质量门禁必须可程序化验证¶
"检查 CI 是否通过"这类自然语言描述在 Agent 执行中几乎无效——Agent 可能将仅有状态码 SUCCESS（测试数为 0）理解为通过。正确的设计是：将门禁条件拆解为可程序化验证的精确条件组合（如 status == SUCCESS && total_tests > 0 && passed == total）。如果一个约束无法被机器自动验证，在 Agent 执行中它就是无效约束。质量门禁的可验证性比门禁本身的严格性更重要——不可验证的严格门禁在实际运行中会产生更多歧义。
4. 多智能体协作用共享 Session 而非共享状态文件¶
当多个 Agent 需要协作时，避免使用共享状态文件（这会引入竞态条件和版本冲突）。正确的模式是通过 Session 的不可变事件流来协调——每个 Agent 追加自己的事件，通过事件的偏序关系来重建全局状态。这种模式的天然优势是：事件流天然支持重放，任意 Agent 崩溃后都可以从最后一个事件恢复，冲突由偏序关系自然解决。如果必须共享状态，应该像 Git 一样引入版本控制和冲突合并机制。
5. 渐进式工具扩展比全量工具暴露更安全¶
Agent 系统应该采用渐进式工具扩展策略——开始只提供必要工具，复杂工具按需动态加载。这个策略的价值不仅是降低选择成本，更重要的是缩小攻击面和减少误操作概率。每增加一个工具，都是在增加一个潜在的故障点和安全风险点。动态加载机制确保在任何时刻，Agent 只需要知道它当前需要的工具，而非整个工具生态的全貌。