综合 Anthropic 和 OpenAI 三篇核心工程博客，系统梳理 Harness 的关键概念、设计原则与实践架构。
2025 年底到 2026 年初，Anthropic 和 OpenAI 几乎同时发布了关于"Harness"的重量级工程文章。两家公司不约而同地指向同一个结论：AI 智能体的可靠性瓶颈，越来越不是模型本身，而是模型周围的运行环境。
这个运行环境，就是 Harness。
围绕它形成的工程实践，被 OpenAI 命名为 Harness Engineering——一个正在快速成型的新工程学科。
本文梳理了三篇核心一手资料的关键信息，帮你建立对这个领域的完整认知。
"Harness"直译是"线束"或"挽具"。在 AI 智能体语境下，它指的是模型认知与外部现实之间的操作接口——包括执行沙箱、工具接口、知识层、可观测性、评估体系、安全策略等所有让智能体"落地可用"的基础设施。
一个好的 Harness 做五件事：
这个定义比"Agent 框架"更有用，因为它涵盖了完整的反馈闭环：编排、运行时、评分、可观测性、安全性。
这是最早系统讨论 Harness 设计的工程博客。它从一个具体任务出发——让 Claude 从零构建一个 claude.ai 的克隆应用——揭示了长时间运行智能体的核心困难。
智能体必须在离散的上下文窗口中工作，每次新会话对之前的工作毫无记忆。即使有上下文压缩（compaction）技术，Opus 4.5 在跨窗口场景下仍然无法从一条高层提示完成生产级应用。
两种典型失败模式：
模式一：一步到位症。 智能体试图一口气完成所有功能，上下文耗尽时留下半成品代码，下一个会话只能连蒙带猜。
模式二：过早宣布胜利。 在项目已有部分功能后，新会话的智能体环顾四周，觉得"看起来差不多了"，直接收工。
Anthropic 从人类工程师的交接实践中获得灵感，设计了两个角色：
初始化智能体（仅首次运行）：
init.sh 启动脚本claude-progress.txt 进度日志编码智能体（后续每次运行）：
关键设计决策：
passes 字段，提示词中加了强硬约束"The key insight here was finding a way for agents to quickly understand the state of work when starting with a fresh context window."
让智能体在全新上下文中快速了解工作状态——这是整个 Harness 设计的出发点。
这是第一篇文章的升级版，从两智能体进化为三智能体架构，引入了 GAN（生成对抗网络）的思想，重点突破了智能体的自我评估瓶颈。
Prithvi 发现了一个更深层的问题：智能体在评估自己的工作时，倾向于自信地给出好评——即使质量明显平庸。
"Agents tend to respond by confidently praising work—even when quality is obviously mediocre."
对于前端设计这类主观任务，这个问题尤为严重，因为没有类似测试用例的二元验证手段。
还有一个问题是"上下文焦虑"——模型在上下文窗口接近上限时会提前收尾，即使任务远未完成。Sonnet 4.5 上这种现象非常明显，仅靠上下文压缩无法解决，需要彻底的上下文重置。
规划智能体（Planner）
生成智能体（Generator）
评估智能体（Evaluator）
Sprint 合同是生成智能体和评估智能体在实现之前协商的明确协议，定义了"完成"的标准。这弥合了高层产品规范与可验证实现之间的断层。
在前端设计实验中，Prithvi 建立了四个评分标准：
有意加权设计质量和原创性（Claude 在工艺和功能性上已经默认表现不错），推动模型冒更大的美学风险。
最惊人的案例：为一家荷兰艺术博物馆设计网站时，前 9 轮迭代产出了一个干净的深色主题页面。第 10 轮，模型推翻了整个方案，重新设计为一个 3D 空间体验——用 CSS 透视渲染的方格地板，墙上自由悬挂的画作，门廊式的房间导航。这种创造性跃迁在单次生成中从未出现过。
复古游戏制作器（Opus 4.5）
| 方案 | 耗时 | 成本 |
|---|---|---|
| 单智能体 | 20 分钟 | $9 |
| 完整 Harness | 6 小时 | $200 |
单智能体版本界面看起来还行，但核心游戏机制全坏了——实体出现在屏幕上，但不响应任何输入。Harness 版本虽贵 20 倍，但能做出真正可玩的游戏。
数字音频工作站（Opus 4.6，简化版 Harness）
| 阶段 | 耗时 | 成本 |
|---|---|---|
| 规划 | 4.7 分钟 | $0.46 |
| 构建（Round 1） | 2 小时 7 分钟 | $71.08 |
| QA（Round 1） | 8.8 分钟 | $3.24 |
| 构建（Round 2） | 1 小时 2 分钟 | $36.89 |
| QA（Round 2） | 6.8 分钟 | $3.09 |
| 构建（Round 3） | 10.9 分钟 | $5.88 |
| QA（Round 3） | 9.6 分钟 | $4.06 |
| 总计 | 3 小时 50 分钟 | $124.70 |
"The space of interesting harness combinations doesn't shrink as models improve. Instead, it moves, and the interesting work for AI engineers is to keep finding the next novel combination."
模型越强，Harness 的可能性空间不会缩小——它只会移动。AI 工程师的工作就是不断找到下一个有价值的组合。
OpenAI 的这篇文章首次使用了"Harness Engineering"这个术语，并正式将其定义为一个独立的工程学科。与 Anthropic 侧重实验案例不同，OpenAI 更侧重工程方法论和最佳实践。
智能体的有效性来自仓库的可读性、结构化文档、工作树本地化的应用实例、以及智能体可见的日志和指标——约束应通过机制而非散文来执行。
仓库可读性是第一等 Harness 原语
AGENTS.md 充当导航图docs/ 目录才是真正的"系统记录簿"核心洞察：仓库的形状是运行时的一部分，而非仅仅是文档。 如果智能体无法在仓库中找到某个事实，那这个事实对智能体来说实际上不存在。
工作树本地化（Worktree-local）
智能体应该在独立的工作树中操作，配有本地化的应用实例用于验证。这确保了隔离性和可重现性。
可追踪性是必需的
OpenAI 定义了"trace grading"——对决策、工具调用和推理步骤的端到端 trace 进行结构化评分。从"只看输出"的评估转向"看过程"的评估。
至少应存储：
没有 trace，你只能知道智能体失败了。有了 trace，你通常能知道为什么。
综合三篇一手资料，以下原则已在实践中反复验证：
大多数智能体失败本质上是状态管理失败，只是伪装成了推理失败。每个有意义的步骤应该产出以下之一：无操作（no-op）、观察（observation）、提案（proposal）、外部副作用（external side effect）、终结结果（terminal result）。显式存储步骤类型。
即使两者由同一个模型完成，也要分开接口。规划的表示应该是可检视、可评分的，不需要重新解析自由文本。Anthropic 在三智能体架构中体现了这一点（规划器独立于生成器），OpenAI 在 Agents SDK 设计中也遵循这个原则。
可重放的 trace 让你能够：复现回归、公平对比不同的提示词和模型、调试工具和策略失败、衡量随时间的漂移。没有可重放能力的扩展，只是更昂贵的混乱。
Anthropic 明确指出：详细的工具描述、严格的 schema、示例、紧凑且高信号的响应——这些实质性地影响智能体行为。智能体往往失败不是因为推理能力不足，而是因为工具描述模糊、接口臃肿或工具数量太多。设计工具时应当：为机器使用而设计，使用语义稳定的标识符，保持输出紧凑且与决策相关，合并重叠的工具，为工具接口做版本管理。
OpenHands 推荐 Docker 沙箱，将进程沙箱视为不安全的。如果智能体能执行命令、修改文件、浏览网页或调用外部 API，你的 Harness 需要：隔离执行、有界凭证、确定性的环境搭建、干净的重置语义、可审计的权限。
这是所有文献共同强调的反模式：当同一个失败反复出现时，应该把修复编码为工具约束、linter、fixture、策略、评分器或文档映射——而不是在提示词中加又一段巨长的指令。 Prithvi 用评分标准取代了散文式的质量要求。Justin 用 JSON 功能清单取代了对模型行为的口头约束。OpenAI 提出用自定义 linter 和结构化测试取代自然语言规则。同一个方向，三种实现。
综合三篇资料，一个完整的 Harness 系统包含六个层次：
┌─────────────────────────────────────────┐
│ 任务入口（Task Intake） │
└───────────────────┬─────────────────────┘
│
┌───────────────────▼─────────────────────┐
│ 规划 / 编排（Orchestrator） │
└───┬───────────┬───────────┬─────────────┘
│ │ │
┌───▼───┐ ┌────▼────┐ ┌───▼────┐
│ 知识层 │ │执行运行时│ │ 状态存储│
└───────┘ └────┬────┘ └────────┘
│
┌─────▼─────┐
│ 工具层 │
└─────┬─────┘
│
┌──────────▼──────────┐
│ 可观测性 / Trace │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ 评估 / 回归 / CI │
└─────────────────────┘将工作归一化为类型化的任务规范。最小字段：task_id、goal、success_criteria、environment、allowed_tools、risk_level、budget、timeout、artifacts_expected。不要把用户的原始文本直接当作运行时的唯一事实来源。
这一层应该尽量薄。复杂的隐藏编排逻辑难以评估。优先选择显式的计划和显式的状态转换。
这是智能体实际行动的"世界"：容器/虚拟机、浏览器会话、挂载的仓库、种子数据库、临时凭证。要求：确定性的环境镜像、每次运行隔离、已知状态重置、资源限制、超时控制、事件捕获。
按领域组织，版本化接口，严格 schema。每个工具应定义：用途、允许的调用者、输入 schema、输出 schema、副作用、重试安全性、幂等性说明、脱敏规则。
渐进式披露：AGENTS.md 作为路由图，ARCHITECTURE.md 作为系统全景，docs/ 下的结构化文档，docs/generated/ 下的生成式参考，docs/exec-plans/active/ 下的活跃执行计划。如果一条规则很重要，用 linter 或测试来执行，而非一段段落。
为每次运行捕获结构化 trace。建立三类评估器：
| 类别 | 指标 |
|---|---|
| 主要指标 | 任务成功率 |
| pass^k（重复运行一致性） | |
| 每个成功任务的成本 | |
| 端到端延迟 | |
| 人工介入率 | |
| 策略违规率 | |
| 调试指标 | 工具选择错误率 |
| Schema 验证失败率 | |
| 重试次数 | |
| 从失败中恢复的比率 | |
| 每个成功任务的步骤数 | |
| 每次运行消耗的上下文字节数 | |
| 编码智能体专项 | 测试通过增量 |
| diff 大小 | |
| 涉及的文件数 | |
| 回退率 | |
| 合并后的二次修复率 |
当同一个失败反复出现时，在提示词里加更多指令。正确做法是把修复编码为工具约束、linter、fixture 或评分器。
只看最终输出对不对，忽略过程中的不安全重试、脆弱的工具使用、策略违规。应该尽早加入过程评估器和策略评估器。
如果重置不彻底，评估就变成噪声。固定镜像版本、种子数据，把 teardown 纳入 Harness 合约。
工具歧义制造选择错误。激进地合并。
如果架构决策、策略或任务流程存在于聊天记录或人脑里，智能体的表现就会看起来不稳定——因为环境本身就不稳定。
如果从零开始，按这个顺序构建：
先不要做： 多智能体路由、向量记忆、复杂的自我反思循环、大而全的工具目录、到处用 LLM 做评审。这些会在你建立稳定的测量基线之前引入成本和歧义。
如果你希望模型升级带来复利效应，先把 Harness 做好。
如果 Harness 是混乱的，模型升级只会更快地产出混乱。
这就是 Harness Engineering 的全部。
它不玄妙，但它决定了你的智能体是"演示能跑"还是"生产可用"。