Harness Engineering：让 AI Agent 不再散架的系统设计

模型不是 agent；动手前先写任务契约

模糊意图（「改进一下 onboarding」）拿来聊天够用，拿来自主执行不够。harness 应把请求转成一份任务契约，回答五个问题：必须产出什么结果、什么在范围内、什么绝对不能改、什么证据能证明完成、哪些动作需要人工审批。

这把 agent 的问题从「我下一步该做什么」换成了「哪个动作能让环境更接近契约里的结果」。没有契约，它优化的是看起来像在干活。

给地图不给手册；要工具网关不要工具堆；分开大脑、手和历史

把整个仓库和所有历史塞进上下文不是上下文工程，是上下文洪水。正确做法是先给小地图，需要时再下钻——上下文的膨胀应该由任务驱动，不是由「信息存在」驱动。目标是每 token 的信号量最大，不是上下文最大。

给 agent 二十个工具不会让它更能干，只会给它二十种犯错方式。工具网关负责隐藏无关工具、校验参数、限制路径、加超时、让重试幂等、返回证据而不只是「成功」。模型可以提议动作，网关决定这个动作是否有效到可以执行。

脆弱的 agent 把推理、工具调用、报错、陈旧观察全混进一条越来越长的记录里。更强的系统分三块：模型要的是正确的当前状态而非全部原始事件；沙箱要的是安全执行一个有边界的动作；会话日志要的是在上下文消失后保住发生过什么。对话历史不是记忆，它只是事件流——原始历史留给审计，编译出的持久状态留给执行。

完成需要证据；验证要攻击结果；模型提议、策略授权

agent 说「done」只是又一次模型输出。完成必须由环境中可观察的变化判定，而且要先跑最便宜的确定性检查——凡是编译器、schema、校验和、查询或测试能回答的，就别再问模型。模型处理歧义，代码处理管道。

执行者和验证者不该共享目标：执行者想做出最强方案，验证者要找出应该拒绝它的理由。让同一个 agent 在同一个上下文里「再检查一遍」，它往往会保留造成错误的那些假设。验证阶段需要明确的拒绝标准、全新上下文，以及「可以只拒绝、不负责修」的权力。

有些规则不该依赖模型记不记得——它们不是提示词建议，是策略，应该放在推理循环之外，后果越严重闸门越硬。自主不是没有约束，是在清晰强制的边界内自由行动。

按失败类型恢复；指令沉淀成基础设施；观察过程；留变更回执

「出错了再试一次」不是恢复，是重复。要先给失败分类再选动作，一次重试至少要改变一个相关条件，否则只是在花钱复现同一个失败。每个循环都要有预算：尝试次数、时间、花费、破坏范围、升级条件。

指令解释「本地现实」时有用，但本身是很弱的强制手段——规则反复重要，就往下沉一层。prompt 负责解释判断，harness 负责强制不变量。

干净的最终产物可能掩盖糟糕的过程：读了错误的数据、忽略了失败的命令、花了十倍预算、用错误的理由得到正确答案。要的不是监控，是局部修复——第 18 步失败时能从可信检查点重启，而不是重放整个任务。运行结束再编译一张变更回执：它不是模型说了什么的摘要，而是系统能证明什么的摘要。

最弱的团队修复失败的输出，最强的团队还修复允许这个失败发生的系统。改对一个答案只帮到一次运行，改对一个 harness 帮到之后每一次。

harness 也会腐化；按层建；在正确层级度量

为昨天的模型做的绕行方案，可能挡住今天的模型用更好的策略。把 harness 组件当生产代码，定期问：它防的是哪种失败？那种失败还多久发生一次？增加了多少复杂度？去掉它会怎样？最好的 harness 不是最大的那个，而是能可靠闭合「意图」与「证据」之间差距的最小系统。Build to delete。

度量也要在正确层级：token 数不是终极指标，尝试的任务数也不是，有用的单位是「被接受的工作」。否则会掉进一个幻觉——agent 看起来极其高产，同时制造出昂贵的复核工作。