OpenInfoHub
Go back

Harness Engineering 学习笔记：从 Prompt 到长时运行 Agent 系统

最近关于 Agent 工程的话题里，一个反复出现的词就是 Harness。

如果只看单篇文章，很容易把它理解成“提示词包装”或者“某个 Agent 框架”。但把下面三个来源放在一起看，会发现 Harness 其实描述的是一整层系统设计：

这篇文章不做逐段翻译，而是把三篇内容整理成一份适合开发者复用的学习笔记。

目录

一句话理解 Harness

最值得记住的定义是：模型只提供智能，Harness 负责把这种智能变成可执行的工作能力。

也就是说，裸模型通常只能接收输入、输出文本；真正让它像 Agent 一样工作的，是模型外侧那一层工程系统。

从工程视角看，Harness 包含但不限于：

所以 Harness 不是一个单点功能，而是一组围绕模型构建的执行基础设施。

为什么模型本身不够

Viv 那篇线程最有价值的地方，是它从“模型做不到什么”反推 Harness 为什么必要。

如果没有 Harness，模型通常缺少以下能力：

因此，所谓 Harness Engineering，本质上就是把“我希望 Agent 具备的行为”翻译成系统级能力。

一个很实用的推导方式是：

想要什么行为，就为这个行为设计对应的环境、工具、约束和反馈回路。

例如：

Harness 的核心组件

综合三篇文章，几乎所有高质量 Harness 都离不开下面这几类组件。

1. 文件系统是基础中的基础

Viv 把文件系统看成最底层的 Harness Primitive，这个判断我很认同。

因为文件系统同时解决了几件事：

Anthropic 的多 Agent 设计里，Planner、Generator、Evaluator 之间的沟通也是通过文件完成的。OpenAI 更进一步，直接把代码仓库当成记录系统，把文档、计划、架构说明、设计原则、技术债和生成产物全部收进仓库里。

结论很明确：如果 Agent 没有稳定的文件系统和结构化仓库，它的长期表现上限会很低。

2. 通用执行能力比预制工具更重要

Viv 提到一个关键观点：与其为每个动作手工设计专用工具，不如给 Agent 一个足够通用的执行能力，比如 bash 加代码执行。

原因很简单：

这也是为什么现代编码 Agent 几乎都把终端视为默认能力，而不是附属功能。

3. 沙箱、浏览器和可观测性共同构成“可验证环境”

Anthropic 文章里最值得借鉴的部分，是它没有把评估器局限在读代码，而是给 Evaluator 提供了 Playwright MCP，让它像真实用户一样操作应用。

这背后反映的是一个重要原则：评估必须尽量接近真实运行环境。

所以好的 Harness 往往不只提供代码访问，还会提供：

OpenAI 的做法更系统。他们让 Codex 可以直接读取 UI、日志、指标和追踪，并在独立 worktree 里启动应用、观察运行信号、修复问题、重启并重新验证。这意味着 Agent 不只是“写完代码就结束”，而是进入了接近工程闭环的工作模式。

4. 记忆和搜索不是附加项，而是长期运行前提

模型的知识受限于训练和当前上下文，所以只靠参数记忆无法支撑持续迭代。

Harness 通常要补上的两类能力是：

Viv 提到了记忆文件标准和 Web Search；OpenAI 则把这件事工程化成”仓库即真相来源”。也就是说，凡是 Agent 需要持续理解的知识，最好都编码成它能访问、能搜索、能版本化的工件。

5. Ralph Loop：让 Agent 在长时任务里不提前退场

Ralph Loop 是一种被多篇文章反复提及的长时任务 Harness 模式。它的核心逻辑是：通过 Hook 拦截模型的退出尝试，在干净的上下文窗口里重新注入原始目标，强迫 Agent 继续工作直到完成。文件系统是让这个模式成立的基础——每次迭代以新鲜上下文启动，但读取上一次迭代留下的状态文件接续工作。这个模式直接对抗了模型在 Context Window 接近限制时的提前收尾倾向。

6. 上下文管理决定长时任务是否会崩

Anthropic 明确指出，长任务里最常见的两个问题是：

他们对 Sonnet 4.5 的经验是，单纯 compaction 不够，context reset 加结构化 handoff 更有效。后来随着 Opus 4.5/4.6 能力增强，一些原本必须的脚手架又可以删除。

这里能提炼出一个很实用的原则：

Harness 设计不是越复杂越好，而是要围绕当前模型的真实短板做最小必要补强。

Anthropic：用生成器和评估器把主观质量变得可优化

Anthropic 这篇文章最有启发的地方，是它把一个很难处理的问题拆开了：模型不擅长给自己的结果做严厉评价。

灵感来源：把 GAN 的思路用在 Agent 设计上

Prithvi Rajasekaran 在文章里明确说，这套 Generator + Evaluator 架构的灵感来源于生成对抗网络（GAN）：一个生成器负责产出，一个判别器负责批评，两者对抗迭代。把这个思路迁移到 Agent 系统里，就得到了”生成-评估”的反馈闭环。

前端设计场景的核心思路

作者先在前端设计问题上实验。他发现模型如果自我评估，通常会对自己过于宽容，于是改成：

更重要的是，它不是问一个模糊问题，比如”这个页面美吗”，而是把评价拆成四个可操作的评分标准：

这样做的意义在于：先把主观任务变成可评分任务，再用多轮反馈把结果推高。

每次生成运行 5 到 15 轮迭代，由于 Evaluator 需要真实导航页面，单次完整运行最长可达四小时。Generator 在每次评估后还被要求做一个策略决定：如果分数趋势良好则沿当前方向优化，如果方向整体不奏效则直接做风格转向。

一个让人印象深刻的案例：作者提示模型创建一个荷兰艺术博物馆网站。前九次迭代产出的是干净的深色主题落地页，视觉不错但在预期范围内。到了第十次迭代，模型彻底推翻之前方案，把网站重新构想成了一个空间体验：用 CSS 透视渲染的 3D 房间，带有棋盘格地板，画作悬挂在墙上，通过门道而非滚动来切换画廊空间。这种创意跃变是单次生成里从来没有出现过的。

扩展到全栈应用开发

在全栈场景里，Anthropic 把结构升级成三 Agent：

Generator 和 Evaluator 在每个 Sprint 开始前先协商出 Sprint Contract：Generator 提出要构建的内容和成功标准，Evaluator 评审并确认，两者对齐后才开始写代码。Agent 之间的通信通过文件进行——一个 Agent 写文件，另一个读后在同一文件里回应或写新文件。

一个具体的对比实验：同一个提示”创建一个 2D 复古游戏制作工具，包含关卡编辑器、精灵编辑器、实体行为和可玩测试模式”：

Harness时长花费结果
单 Agent20 分钟$9游戏核心玩法坏的，实体出现在屏幕上但无法响应输入
完整 Harness6 小时$200游戏可实际玩，Planner 把一句话扩展成 16 功能 10 Sprint 规格，含 AI 辅助精灵生成和带分享链接的游戏导出

Evaluator 在日志里留下了非常精确的 Bug 报告，例如：

关于模型升级如何驱动 Harness 简化：最初使用 Sonnet 4.5 时，Context Anxiety 问题突出，必须使用 Context Reset + Handoff 机制。升级到 Opus 4.5 后 Context Anxiety 基本消失，可以去掉 Context Reset 让 Agent 单次连续运行整个构建过程。升级到 Opus 4.6 后，Sprint 分解结构也可以去掉了——新模型能原生处理更长时间的连续工作，DAW（数字音频工作站）构建任务中 Generator 连续运行超过两小时，整个 Harness 耗时 3 小时 50 分钟，花费 $124.70。

我认为这篇文章给出的最大收获不是”三 Agent”这个表面结构，而是两条底层原则：

  1. 生成与评估分离
  2. 评估必须基于真实运行结果，而不是只看代码表面

这对构建任何高要求 Agent 都成立，不只是前端和全栈开发。

OpenAI：把整个代码仓库变成 Agent 可读、可执行、可维护的系统

OpenAI 文章提供的是另一种视角：当 Agent 生成代码的比例极高时，工程团队的重心会从“写代码”转移到“设计环境”。

他们重点优化的不是代码补全，而是环境可读性

文章里一个特别强的观点是：对 Agent 来说，看不到的知识就等于不存在。

这意味着：

所以 OpenAI 的做法是把尽可能多的上下文显式写入仓库：

这比单纯“给模型更长上下文”更关键，因为它让知识变成了可维护的工程对象。

他们把可观测性直接接给了 Agent

OpenAI 还做了一件很多团队还没认真投入的事情：让 Agent 直接读日志、指标和追踪。

这样一来，提示不再只是：

而可以变成：

这说明高水平 Harness 设计已经不只是“让模型会写”，而是“让模型能观察、判断、迭代和回归验证”。

他们对 AGENTS.md 的态度尤其值得抄作业

OpenAI 明确反对把 AGENTS.md 写成大而全手册，亲身实践后得出四条教训：

他们改成把 AGENTS.md 当目录入口（约 100 行），把细节分散到结构化文档中。仓库文档结构实例（OpenAI 在文章里直接展示了目录树）：

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   ├── index.md
│   └── core-beliefs.md
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
│   └── new-user-onboarding.md
├── references/
│   └── design-system-reference-llms.txt
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
└── RELIABILITY.md

执行计划是一等工件，带有进度和决策日志，提交进仓库版本控制。活跃计划、已完成计划和技术债务都集中存放，让 Agent 无需依赖外部上下文也能运行。

doc-gardening 模式：他们还运行着一个定期执行的”文档维护” Agent，专门扫描那些不再反映真实代码行为的过时文档，并发起修复 PR。把文档维护本身也交给 Agent 来做——这是我认为很多团队最值得立刻借鉴的一条实践。

模型与 Harness 的协同进化

Viv 在文章末尾提出了一个值得长期关注的洞见：模型训练和 Harness 设计正在形成一个耦合的反馈回路。

今天的 Agent 产品（如 Claude Code、Codex）都是在把模型和 Harness 同时纳入训练循环的情况下做后训练优化的，这帮助模型在文件系统操作、Bash 执行、规划、并行化 Subagent 等能力上持续改进。

但这种协同进化有一个有趣的副作用：改变工具逻辑会导致模型性能变差。 Codex 的 apply_patch 工具就是一个例子——理论上通用的模型在切换补丁方法时应该没有阻力，但在 Harness 循环中训练的模型会对特定工具实现过拟合。

这并不意味着最好的 Harness 就是模型被训练时用的那个。Terminal Bench 2.0 排行榜上，Claude Code 里的 Opus 4.6 得分远低于其他 Harness 里的 Opus 4.6——这证明针对你的任务优化 Harness，仍然有巨大提升空间，不应只依赖模型的默认配置。

随着模型能力提升，Harness 里今天存在的一些功能会逐渐被模型原生吸收——规划、自我验证、长时连贯性。但就像 Prompt Engineering 到今天仍然有价值一样，Harness Engineering 很可能也会持续有用：真正配置良好的环境、正确的工具、持久状态和验证回路，无论基础模型能力多强，都会让 Agent 变得更高效。

三篇内容放在一起后，我总结出的统一框架

如果把这三篇内容合在一起，可以得到一个非常完整的 Harness 心智模型。

1. Harness 的本质是“为模型设计工作系统”

它不是一个提示词模板，也不是某个单独 SDK，而是一层把模型智能变成稳定产出的系统设计。

2. 高质量 Agent 不只是会生成，还必须会验证

Anthropic 用 Evaluator 加 Playwright 证明了这点。OpenAI 则把验证扩展到日志、指标、追踪和代码仓库规则。

3. 文件系统和仓库结构决定长期能力上限

没有稳定工件、计划文件、知识地图和版本控制，长时任务最终都会退化为混乱对话。

4. 好的 Harness 会随着模型升级而删减或重构

Anthropic 在新模型上去掉了一些旧脚手架，说明 Harness 不是越多越好，而是要持续验证哪些部分仍然真正承重。

5. 人类的角色正在从“直接实现者”转向“环境设计者”

OpenAI 文章反复强调，人类的主要价值变成：

这很可能就是未来一段时间 AI 工程的真实重心。

一个适合个人开发者的最小 Harness 模板

如果你不是在做超大规模系统，而是想自己搭一个实用 Agent，我建议从下面这个最小版本开始。

第一步：先把工作空间搭对

第二步：把关键知识写进仓库

第三步：加上验证回路

第四步：只在必要时增加多 Agent

推荐的演进顺序是：

  1. 单 Agent + 工具 + 测试
  2. 单 Agent + 计划文件 + 记忆文件
  3. Generator + Evaluator
  4. 再考虑 Planner、子 Agent、复杂编排

不要一上来就堆多 Agent。模型能力不足和任务复杂度不足时，复杂 Harness 只会增加成本和调试难度。

我现在对 Harness Engineering 的理解

看完这三篇内容后，我对 Harness 的理解从“模型外的一层壳”变成了“围绕模型构造生产系统”。

真正决定 Agent 能力上限的，往往不是模型参数本身，而是下面这些问题有没有被工程化处理：

如果这些都没有，再强的模型也容易退化成“会说但不稳定”；如果这些设计得足够好，中等能力的模型也可能表现出远超裸用时的效果。

可直接复用的检查清单

准备设计自己的 Harness 时，我会先检查这 10 件事：

  1. 模型能否读写文件并长期保存中间结果？
  2. 模型能否运行代码、安装依赖并看到执行结果？
  3. 是否有独立于生成器的验证机制？
  4. Web 场景里是否能用浏览器自动化做真实交互测试？
  5. 计划、handoff 和约束是否落到了文件，而不是只停留在聊天里？
  6. AGENTS.md 是否足够短，并且只是导航入口？
  7. 仓库里是否存在结构化文档来承接长期知识？
  8. 是否能访问日志、指标、追踪等运行信号？
  9. 当前 Harness 的复杂度，是否真的对应当前模型的短板？
  10. 有没有机制持续删除已经不再承重的脚手架？

参考来源

如果后面继续写这个系列，我会进一步拆三块：

Share this post on:
Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email
Previous Post
AI 指数级增长时代的产品管理：来自 Anthropic Claude Code 负责人的一线经验
Next Post
把 AI 训成 S 级员工：高效训练 Skills 的 4 个真实翻车教训