深度拆解：AI 智能体 Harness 的构造（译）¶

Ch04.065 深度拆解：AI 智能体 Harness 的构造（译）¶

📊 Level ⭐⭐ | 19.1KB | entities/ai-agent-harness-construction-akshay.md

深度拆解：AI 智能体 Harness 的构造（译）¶

原文：Akshay Pachaar @x.com 编译：宝玉AI

核心命题¶

问题不在模型，而在模型外围的基础设施。 LangChain 仅通过改变包裹 LLM 的底层架构，让 TerminalBench 2.0 排名从第 30 名飙升至第 5——模型没变，参数没变。核心公式（Vivek Trivedy, LangChain）：

"如果你不是模型本身，那你就是 Harness。"

三个层次¶

层次	范围
提示词工程	精心设计模型接收到的指令
上下文工程	管理模型在什么时间点能看到什么内容
Harness 工程	涵盖上述两者 + 工具编排、状态持久化、错误恢复、验证循环、安全执行

12 个核心组件¶

1. 编排循环 (Orchestration Loop)¶

TAO 循环（Thought-Action-Observation）= ReAct 循环。Anthropic 称之为"笨循环"——所有智慧存在于模型，Harness 只负责管理回合切换。

2. 工具 (Tools)¶

Claude Code 六大类：文件操作、搜索、执行、网页访问、代码分析、子智能体创建。 OpenAI Agents SDK：@function_tool、托管工具（网页搜索/代码解释器/文件搜索）、MCP 服务器工具。

3. 记忆 (Memory)¶

Claude Code 三层架构： 1. 轻量级索引（每条约 150 字符，始终加载） 2. 按需调用的详细主题文件 3. 仅通过搜索访问的原始对话记录核心原则：智能体将记忆视为"提示"，行动前必须根据实际状态验证。

4. 上下文管理 (Context Management)¶

上下文腐烂：关键信息处于窗口中间时，模型表现下降 30%+（斯坦福"迷失在中间"现象）。策略：

压缩：总结对话历史，保留架构决策和未修复 Bug
观察掩码：隐藏旧工具输出，保留调用记录
即时检索：轻量级标识符 + 动态加载（grep/head 而非加载整个文件）
子智能体委托：仅返回 1000-2000 Token 浓缩摘要

5. 提示词构建 (Prompt Construction)¶

层级化：系统提示词 → 工具定义 → 记忆文件 → 对话历史 → 当前用户消息。 OpenAI Codex 优先级：服务器系统消息 > 工具定义 > 开发者指令 > 用户指令 > 对话历史。

6. 输出解析 (Output Parsing)¶

依赖原生 tool_calls 对象。有调用 → 执行继续；无调用 → 当前输出即最终答案。

7. 状态管理 (State Management)¶

LangGraph：图形节点中流动的类型化字典，关键步骤 Checkpointing
Claude Code：Git 提交作为存档点，进度文件作为结构化草稿纸
OpenAI：应用内存、SDK 会话、服务器端 API、响应 ID 链

8. 错误处理 (Error Handling)¶

LangGraph 四类： 1. 临时性：延迟重试 2. 模型可恢复：将错误返回模型自愈 3. 用户可修复：暂停等待人类干预 4. 意外错误：上报调试

9. 护栏与安全 (Guardrails and Safety)¶

OpenAI SDK 三层级：输入护栏 → 工具护栏 → 输出护栏。触发绊网（Tripwire）立即停止。 Anthropic：模型决定想做什么，Harness 决定允许做什么（权限执行与模型推理分离）。

10. 验证循环 (Verification Loops)¶

区分"玩具演示"和"生产级智能体"的关键。 Anthropic 三法：

基于规则的反馈（测试、代码检查）
视觉反馈（Playwright 截图）
LLM-as-judge（子智能体评估输出） Boris Cherny：让模型验证自己的工作，产出质量提升 2-3 倍。

11. 子智能体编排 (Subagent Orchestration)¶

Claude Code 三模式：

Fork：复制父级上下文
Teammate：通过文件邮箱通信的独立窗口
Worktree：独立的 Git 分支 OpenAI：Agent as Tool（专家处理子任务）、移交（Handoff，专家接管控制权）。

7 个关键架构决策¶

单智能体 vs. 多智能体
ReAct vs. 先规划后执行
上下文管理策略（总结 vs. 动态加载）
验证循环设计（硬性测试 vs. LLM 打分）
权限与安全架构（速度优先 vs. 安全优先）
工具范围管理（最小工具集原则）
Harness 的厚度（硬编码 vs. 模型发挥）

核心洞察¶

"脚手架"比喻：房子盖好后脚手架要拆除。随着模型能力提升，Harness 应逐渐变薄。 协同进化原则：Harness 设计得好 → 模型升级时不需要增加复杂度，性能自动提升。 Harness 即产品：同样模型不同 Harness，TerminalBench 排名可差 20 多位。Harness 是硬核工程能力：上下文稀缺资源管理、验证循环防错误累积、不产生幻觉的记忆系统。

深度分析¶

1. Harness 作为"操作系统"的类比深化¶

Beren Millidge 的类比将 LLM 比为"无内存、无硬盘、无 I/O 的 CPU"，而 Harness 作为操作系统，这一视角揭示了几个关键层面： 类比的深层含义：

上下文窗口 ↔ 内存：高速但容量有限，断电即失（会话结束）
外部存储 ↔ 硬盘：大容量慢速，持久化但需要显式检索
工具集成 ↔ 驱动程序：让 CPU 能操控硬件设备，扩展能力边界
Harness ↔ 操作系统：协调资源、管理进程、提供安全隔离这个类比的深层启示是：Harness 不只是"包装"，而是一种计算基础设施的重新定义。传统计算中，CPU 依赖操作系统来管理硬件资源；在 AI 计算中，模型依赖 Harness 来管理上下文、工具、状态。

2. "笨循环"哲学的深意¶

Anthropic 将 Harness 运行时描述为"笨循环"——所有智慧在模型，Harness 只负责管理回合切换。这包含几个重要含义： 为何"笨"是优势：

复杂度留在模型侧：Harness 的复杂度不随任务难度线性增长
模型能力可迁移：同样的 Harness 可以受益于模型升级
失败模式清晰：问题要么出在模型推理，要么出在 Harness 执行，边界明确 "笨"的代价：
Harness 必须完美执行每一个回合
上下文管理不当会导致模型"失智"
工具设计的质量直接影响模型表现

3. 上下文腐烂的量化证据¶

斯坦福"迷失在中间"（Lost in the Middle）现象是 Harness 工程中最关键的量化发现之一：

关键信息在窗口中间时，性能下降 30%+
即便支持百万级 Token，上下文增长仍导致指令遵循能力退化 工程启示：
不能依赖"大窗口"来解决上下文问题
必须主动管理上下文内容的位置和密度
轻量级标识符 + 即时检索是最有效的策略

4. 验证循环为何是生产级和应用级的分水岭¶

玩具演示只需要一次执行，生产级智能体需要循环验证：

执行 → 验证 → 修正 → 再执行

错误累积雪球效应：10 步骤过程，每步 99% 成功率 → 全流程仅 90.4% Anthropic 三法对比： | 方法 | 适用场景 | 成本 |
|------|----------|------|
| 基于规则 | 确定性输出（代码、测试） | 低 |
| 视觉反馈 | UI 相关（截图 diff） | 中 |
| LLM-as-judge | 开放式输出（文案、方案） | 高 |

5. 子智能体模式的设计哲学¶

Claude Code 的三种子智能体模式代表了对"上下文继承"的深刻理解： | 模式 | 上下文继承 | 适用场景 |
|------|------------|----------|
| Fork | 完全复制 | 并行探索，多方案评估 |
| Teammate | 通信隔离 | 独立专家，独立决策 |
| Worktree | 版本隔离 | 长期任务，分支实验 |
OpenAI 的 Agent as Tool vs. Handoff 模式则是另一种维度：

Agent as Tool：子任务工具化，结果返回主循环
Handoff：控制权完全转移，适合专家接管

6. 脚手架比喻的动态演化¶

"脚手架"比喻包含一个动态演化过程：

阶段1（模型弱）：需要厚重脚手架（大量硬编码逻辑）  
     ↓  
阶段2（模型强）：脚手架变薄（更多留给模型）  
     ↓  
阶段3（模型很强）：脚手架近乎消失  
     ↓  
阶段4（模型极强）：脚手架重新变厚——但这是新的脚手架

这个看似矛盾的第四阶段揭示了一个真相：即使模型极强，仍需要 Harness：

管理多智能体协作
提供长期状态持久化
执行安全审计和验证

7. Harness 设计的三元悖论¶

类比分布式系统的 CAP 定理，Harness 设计存在一个三元悖论：

          速度  
           /\  
          /  \  
         /    \  
        /  安  \  
       /  全  \  
      /________\  
   成本        功能

速度优先：快速执行，但可能跳过安全检查
安全优先：层层验证，但增加延迟
成本优先：最小化 API 调用，但牺牲功能丰富度实际系统往往在这三极之间做取舍，而非追求全面最优。

实践启示¶

1. 从"抱怨模型"转向"检查 Harness"¶

当你发现智能体表现不佳时，首先检查 Harness，而非换模型：检查清单：

上下文是否过大？是否需要压缩？
工具设计是否清晰、参数是否合理？
是否有验证循环？错误是否累积？
状态持久化是否可靠？中断恢复是否顺畅？

2. 从最小工具集开始，逐步扩展¶

最小工具集原则（Minimal Tool Surface）：

暴露当前步骤所需的最小工具集往往效果最佳实践方法： 1. 从 3-5 个核心工具开始 2. 监控工具使用率，移除从不使用的 3. 按需添加新工具，配合任务复杂度升级 4. 定期审视工具必要性，警惕工具膨胀

3. 上下文管理优先于模型选择¶

上下文管理的优先级高于模型选择： 投入排序： 1. 首先：设计好上下文压缩和检索策略 2. 其次：优化提示词结构和工具描述 3. 最后：考虑换用更强的模型理由：同样的模型，在良好上下文管理下表现远超粗放使用。

4. 建立验证循环是生产部署的第一步¶

生产级智能体必须包含验证机制：

快速原型（不计验证）→ 引入验证 → 迭代完善

验证策略选择：

代码任务：单元测试 + 语法检查（成本最低）
API 调用：响应 schema 验证
内容生成：LLM-as-judge（成本最高，但最灵活）

5. 状态管理要服务于可观测性¶

良好的状态管理不仅是"保存进度"，更是可观测性的基础： Checkpointing 的价值：

中断恢复：不怕中途失败
时间旅行调试：回溯任何状态
审计追踪：记录完整执行历史实践建议：
LangGraph：使用 store 组件
Claude Code：利用 Git 提交历史
OpenAI：维护响应 ID 链

6. 安全架构的纵深防御¶

OpenAI SDK 的三层护栏（输入→工具→输出）体现了纵深防御思想：

用户输入 → 智能体 → 工具调用 → 结果输出  
   ↑         ↑        ↑          ↑  
 输入护栏   工具护栏  工具护栏   输出护栏

每层护栏独立运行，任一层失败不影响其他层。

7. 单智能体优先，多智能体谨慎¶

先充分挖掘单智能体潜力，再考虑多智能体：多智能体的开销：

通信开销（信息损耗）
一致性维护成本
调试复杂度指数增长 何时引入多智能体：
任务需要完全独立的领域专家
需要并行探索多个方案
任务规模需要团队协作

8. 适配模型升级的 Harness 设计¶

遵循"协同进化原则"设计 Harness： 好设计：

Harness 不假设特定模型能力
工具定义通用，参数类型明确
上下文管理策略与模型无关 坏设计：
Harness 硬编码模型特有行为
提示词依赖特定模型的输出格式
上下文压缩策略针对特定模型调优

9. Harness 也是产品¶

认识到 Harness 即产品：

同样模型，不同 Harness → TerminalBench 排名差 20+ 位
Harness 是差异化竞争力的核心来源
模型可以被任何人调用，但好的 Harness 是专有技术投入在 Harness 工程上的时间，其回报可能远高于投入在模型选择或提示词调优上的时间。

与 harness-engineering 的关系¶

本文（Akshay Pachaar 版）与 harness-engineering（刘棕霆版）共同构成 Harness 知识体系：

刘棕霆版：Harness Engineering 作为第三代工程范式的宏观框架
本文：Akshay Pachaar 版对 12 个核心组件的深度拆解 + 7 个关键架构决策

来源¶

原文：https://x.com/akshay_pachaar/status/2041146899319971922
中文编译：宝玉AI

深度拆解：AI 智能体 Harness 的构造（译）¶

Ch04.065 深度拆解：AI 智能体 Harness 的构造（译）¶

深度拆解：AI 智能体 Harness 的构造（译）¶

核心命题¶

三个层次¶

12 个核心组件¶

1. 编排循环 (Orchestration Loop)¶

2. 工具 (Tools)¶

3. 记忆 (Memory)¶

4. 上下文管理 (Context Management)¶

5. 提示词构建 (Prompt Construction)¶

6. 输出解析 (Output Parsing)¶

7. 状态管理 (State Management)¶

8. 错误处理 (Error Handling)¶

9. 护栏与安全 (Guardrails and Safety)¶

10. 验证循环 (Verification Loops)¶

11. 子智能体编排 (Subagent Orchestration)¶

7 个关键架构决策¶

核心洞察¶

深度分析¶

1. Harness 作为"操作系统"的类比深化¶

2. "笨循环"哲学的深意¶

3. 上下文腐烂的量化证据¶

4. 验证循环为何是生产级和应用级的分水岭¶

5. 子智能体模式的设计哲学¶

6. 脚手架比喻的动态演化¶

7. Harness 设计的三元悖论¶

实践启示¶

1. 从"抱怨模型"转向"检查 Harness"¶

2. 从最小工具集开始，逐步扩展¶

3. 上下文管理优先于模型选择¶

4. 建立验证循环是生产部署的第一步¶

5. 状态管理要服务于可观测性¶

6. 安全架构的纵深防御¶

7. 单智能体优先，多智能体谨慎¶

8. 适配模型升级的 Harness 设计¶

9. Harness 也是产品¶

与 harness-engineering 的关系¶

来源¶

相关实体¶