上一篇 梳理了 Harness Engineering 的六种方案。这一篇讲我自己动手的过程。

起点：为什么我需要 Harness

我的日常工作涉及 ML 实验——跑训练、复现论文的 baseline、调参数。这些任务有一个共同特征：步骤多、耗时长、每一步都可能出错、环境配置复杂。理想情况下，我写好一份实验计划，agent 帮我在服务器上从零开始搭环境、安装依赖、跑训练、验证结果。

问题是，这件事在实际操作中一直做不到。用 Claude Code 或 Codex 跑一个小任务——修个 bug、写个脚本——体验很好。但一旦任务复杂度上去，agent 的表现就开始退化。

第一次尝试：OpenAI 的文档系统

读了 OpenAI 的那篇博客 [3] 之后，我首先照着做了一套文档管理体系。核心思路是他们提出的「AGENTS.md 是目录，docs/ 是内容」的 progressive disclosure 方案：写好架构文档、规范文档，agent 按需查阅。

效果怎么样呢？agent 确实能跑了，但大概到 1 小时左右就开始出问题。回过头看，原因很明确：OpenAI 的博客详细介绍了文档系统怎么组织，但对 agent 之间的编排逻辑（orchestration）讲得不多。他们提到了 agent-to-agent review、Ralph Wiggum Loop，但具体怎么让多个 agent 协调工作、怎么处理失败和重试，没有给出可直接复用的方案。

文档系统帮 agent 理解了「该做什么」和「代码库长什么样」，但没有回答「做完了怎么验证」和「验证失败了怎么办」。agent 跑着跑着就偏了，或者在某个环节卡住后不知道该怎么恢复。

第二次尝试：三 Agent 架构

然后我读了 Anthropic 的两篇博客 [1][2] 和 lidangzzz 的 goal-driven [5]。有两个观察让我改变了方向。

第一，Anthropic [1]、[2]、Karpathy [4]、lidangzzz [5] 都明确地把 generator 和 evaluator 分开，让做事的和判断好坏的互不干涉。这跟我在第一次尝试中遇到的问题直接相关：agent 自己实现、自己验证，很容易自己说服自己「这就行了」。

第二，Anthropic [2] 中关于「品味可以打分」的思路给了我启发。虽然我的场景是 ML 实验复现，评估标准比前端设计更客观，但「把验收标准写成 acceptance criteria，evaluator 独立验证」这个框架是通用的。

于是我从头搭了一套 harness。

架构设计

我设计了一个三 agent 系统，用 shell 脚本做编排，文件系统做通信总线。架构的核心哲学是：让 agent 像一个工程团队那样工作——有人规划、有人执行、有人验收——同时人类保留最终控制权。

三个 agent 各司其职：

Planner（规划者）：只在最开始运行一次。接收我写的一份粗略的实验计划草稿，把它细化为一份正式的 plan，拆成若干个 milestone，每个 milestone 有明确的 acceptance criteria。输出写到 artifacts/plan.md。

Generator（执行者）：在循环中反复运行。每次只处理当前 milestone，写代码、改配置、跑实验。只能操作实验仓库里的代码，不能修改 harness 自身的任何文件。

Evaluator（评估者）：Generator 完成后运行。从 plan 中读取当前 milestone 的 acceptance criteria，独立设计测试，然后验证 Generator 的产出。关键约束：Evaluator 看不到 Generator 的对话历史，只能看到文件和仓库状态。它的 prompt 里明确写着：「先从 acceptance criteria 出发设计测试应该检查什么，然后再去看 Generator 的代码。」

这三个 agent 通过文件交互：plan.md、feedback.md、status.md、tests/ 目录。不走对话，不共享 context。

双循环机制

编排逻辑是两层循环：

  • 外循环：依次推进 milestone 1 → 2 → … → N
  • 内循环：每个 milestone 内部，Generator 和 Evaluator 反复迭代，直到 Evaluator 判定 PASS 或者超过重试上限

Evaluator 每次运行后输出一个 verdict：PASS（推进到下一个 milestone）、FAIL（Generator 重试，附带反馈）、HUMAN_NEEDED（暂停，等待人工介入）。如果 verdict 解析失败，默认按 FAIL 处理——系统是 fail-closed 的。

成本控制

Agent 调用的 token 成本很贵。我做了几个设计来控制成本：

  • Progressive disclosure：给 agent 的 prompt 只注入当前 milestone 对应的 plan 片段（大约 25 行），引导它按需去读完整文件，避免一上来就塞满 context。
  • Feedback 覆盖写入：每轮 Evaluator 运行后，feedback.md 被整体覆盖，只保留最新一轮的反馈。历史反馈不累积在文件里，避免 context 膨胀。
  • 迭代上限：全局最多 15 次迭代，单个 milestone 最多重试 3 次。超限自动停止，不无限消耗。

人机协作

harness 跑着跑着可能遇到 agent 搞不定的问题。我设计了三种触发人工介入的机制：agent 主动请求（写一个 .human_needed 标记文件）、用户主动中断、以及某个 milestone 连续失败超过上限。

介入时，tmux 弹出一个交互菜单：可以打开一个带完整 context 的 Claude 交互 session，也可以直接开 shell 手动操作，还可以看 plan 和 feedback，选择继续、跳过、或者退出。

实际效果

第一个完整测试是用 verl 框架复现 RL 训练的 baseline。

结果：5 个 milestone，总共 10 次迭代，全部 PASS，零次人工干预。

  • M1：Docker 环境搭建 — 2 次迭代，PASS
  • M2：Flash Attention 替换为 FlashInfer — 2 次迭代，PASS
  • M3：Baseline RL 训练验证 — 2 次迭代，PASS
  • M4：联合训练验证 — 2 次迭代，PASS
  • M5：测试套件验证 — 2 次迭代，PASS

之后我又用这套 harness 复现了 TRL 框架的 DPO 算法训练。同样顺利跑完。

跟第一次尝试对比，从 1 小时到 10 小时的稳定运行。差距在哪？我觉得核心在于三件事：

  1. Generator 和 Evaluator 的隔离。Evaluator 独立设计测试、独立判断，Generator 没法「自己给自己打分」。这是从 Anthropic [2] 和 lidangzzz [5] 那里学到的最重要的一条。
  2. 显式的失败处理。verdict 机制让系统知道什么时候该重试、什么时候该停下来找人。不再是 agent 跑着跑着悄悄偏掉。
  3. 文件作为通信总线。三个 agent 不共享 context，只通过文件交互。每个 agent 启动时拿到的都是最新的、干净的文件状态。

踩过的坑

说几个我在搭建过程中遇到的具体问题。

权限隔离只靠 prompt，有风险。 我在 prompt 里写了「Evaluator 不可以修改代码」「Generator 不可以修改测试」，但这靠的是模型遵守指令，没有文件系统层面的强制执行。如果模型不听话，harness 没有硬性的拦截手段。理想方案是用 Claude Code 的 hooks 机制做真正的权限隔离，但目前还没实现。

bypassPermissions 是个无奈的选择。 agent 跑在服务器上的非交互模式下，没有人在旁边点「允许」。我只能开启 bypassPermissions，同时用 prompt 边界和沙箱环境变量来尽量约束。安全性上不够理想。

Evaluator 的独立性是最难保证的。 最初几个版本里，Evaluator 的测试设计会不自觉地「迁就」Generator 的实现——看了代码之后按照代码的逻辑来写测试，这样什么都能过。后来我在 prompt 里加了强约束：「先读 acceptance criteria 设计测试，然后再看代码」，效果好了很多，但仍然不是百分百可靠。

还缺什么

用了一段时间之后，我清楚地看到几个缺口。

放权还不够。 目前 harness 主要让 agent 做代码生成和环境搭建。但 ML 实验还有很多环节——写实验报告、做结果 evaluation、整理文档——这些我还是手动做的。如果把这些也交给 agent，验证难度会上升，可能需要更多外部验证手段，比如固定的 skill、hook、或者专门的检查脚本。

没有成本可观测性。 跑了 10 小时，用了多少 token，花了多少钱？现在完全没有追踪。这在试验阶段还行，规模化使用就必须解决。

没有 meta-harness。 现在给每个新任务搭一套 harness 还是比较繁琐的——写 plan 模板、定义 milestone、配置 acceptance criteria。简单的任务几个文件就够了，复杂的任务需要系统化地设计。我一直在想：能不能有一个「元工具」，根据任务的难度和可验证性自动决定 harness 该长什么样？这可能是一个有意思的工程方向，甚至是研究方向。

没有完整的文档系统。 我的 harness 参照 Anthropic [2] 的思路，适合一次性的小型项目（复现一个 baseline）。但如果要长期维护一个代码库，OpenAI [3] 那套 progressive disclosure 的知识管理体系才是正解。两者能不能组合起来？三 Agent 的编排逻辑 + 仓库级的文档系统——这是我下一步想探索的。

回顾

两次迭代教会我的最重要的一课：harness 的复杂度应该匹配任务的复杂度。

第一次尝试照搬 OpenAI 的文档系统，缺少 agent orchestration，1 小时就撑不住。第二次引入三 Agent 分工和 verdict 机制，10 小时顺利。但如果任务更简单——只是调一组超参数——lidangzzz 的一段 prompt 或者 Karpathy 的单文件循环可能就够了。

Harness Engineering 现在还处于很早期的阶段。每种方案都有明显的局限，没有一种能通吃所有场景。但趋势很明确：人的角色正在从「写代码」转向「设计让 agent 工作的环境」。这个转变刚开始，还有很大的空间可以探索。

参考文献