Harness 工程方案

一句话定义：Harness 是模型之外，负责组织上下文、维护状态、执行工具、控制权限、恢复故障和验证结果，把模型的一次次判断变成可执行、可恢复、可验证的任务过程的代码、配置和执行逻辑。

单靠模型做不到这些：

• 没有记忆。一次模型调用不知道上一轮做到哪，也不知道任务是否在别处推进过。
• 窗口有限。长任务里的全部事实装不进上下文。
• 意图不等于授权。模型说"我要删这个文件"，不代表当前用户允许删。
• 说完成不等于完成。模型可以声称测试通过了，却证明不了。

所以 Agent = Model + Harness：模型负责理解和决策，Harness 负责把决策变成可靠的结果。Harness 也不是"更长的 Prompt"——Prompt 只是它每一轮生成的输入之一。

• 编排层（橙色）持有任务语义：推进循环、构建每轮上下文、检查权限与预算、判断是否完成。它决定模型看到什么、能做什么、什么时候停。
• 运行层负责物理保障：任务在哪个实例上跑、中断后从哪恢复、事实存在哪、模型和工具从哪接入、动作在哪个隔离环境里执行。
• 控制层负责治理与演进：集中定义版本、策略和预算，回收验证结果与 Trace，决定一个新版本能不能上线。

两条原则贯穿三层：状态外置——任务事实只存在 State Store 里，不在模型上下文或进程内存里，所以任何实例都能接手；策略集中定义、就地执行——控制层下发规则，编排层和运行层在请求路径上直接判定，不让控制层成为每次调用的同步依赖。

用一个例子走一遍：「修一个 bug：登录接口在密码为空时返回 500」。任务进来后先建好任务记录（目标、验收标准、预算），然后进入循环。

① 构建上下文：这一轮模型该看见什么

Harness 每轮重新编译一份上下文，而不是把全部历史塞进去：先按身份和权限过滤，再按相关性排序，再按 Token 预算取舍。大块内容（比如两千行的测试日志）放进 Workspace，窗口里只留摘要和引用。

修 bug 的第一轮，模型看到的是：Issue 描述、仓库规则、登录模块的相关文件、当前计划（复现 → 定位 → 修复 → 回归），以及一个"依赖与接口修复"的 Skill 简介——只有名称和一句话，真正用到时才加载全文。每次调用都会留下一份 Manifest，记录模型到底看到了哪些材料，出错时先查"它有没有看见对的东西"。

② 模型决策：只给出下一步

模型读完上下文，给出一个意图："先运行登录模块的测试，复现问题。"它可以选择行动、委派、提问、等待或申请完成，但它只是提议，不直接动任何东西。

③ 权限检查：模型绕不过去的关口

中间件逐项检查：这个工具在当前阶段允许吗？参数是否落在工作区内？预算还剩多少？结果是三选一——放行、拒绝（并告诉模型原因和替代做法）、需要人确认。跑测试是只读的，直接放行；之后若模型想直接推送到主干，就会被拦下等审批。

护栏按"在哪里执行"分层：写在 Prompt 里的规则只是提示，模型可以绕过；真正的边界在中间件、网关、Sandbox、人工审批和控制面这些模型无法控制的地方。

④ 工具执行：在隔离环境里动手

放行之后，调用经过网关换取短期凭证，在 Sandbox 容器里执行：只能读写这个仓库的副本，没有生产环境凭证，网络出站受白名单限制。即使代码里藏了"顺手部署一下"的指令，Sandbox 的网络和凭证边界也让它做不到。

一次工具调用就是图里这六个环节。工具设计也有讲究："创建合并请求"和"发布生产"必须是两个工具，因为风险、可逆性和审批要求完全不同；不要让模型用通用 Shell 自己拼生产操作。

⑤ 记录状态：先落账，再进入下一轮

测试结果回来：失败用例 1 个，堆栈指向空密码时未做校验。Harness 把这一步写成事件（调了什么、结果是什么、花了多少），更新计划（"复现"打勾，"定位"进行中），关键节点写 Checkpoint。模型下一轮看到的进度来自这份状态，而不是从几百条聊天记录里猜。

⑥ 验证完成：证据齐了才算完

几圈之后，模型补上校验并新增一条回归测试，然后说"修好了"。这只是申请完成。Harness 运行验收：全部测试通过、新增测试覆盖空密码场景、代码改动只在授权目录内、独立评审没有阻断问题。缺一项就把缺口作为新的观察结果送回循环，继续修。

评审这一步适合交给子 Agent：它用独立的上下文只读代码差异和测试报告，不和执行者共享中间判断，更容易发现盲点。同样，定位阶段可以让一个只读的研究 Agent 并行翻代码。子 Agent 只拿到完成子任务所需的最少上下文和更窄的权限，结果回来后仍由主 Agent 校验和整合——任务完成的责任不随委派转移。

最终交付的不是一句"已完成"，而是一组证据：代码差异、测试报告、评审意见，以及一个等待负责人审批的合并请求。

中断了：从 Checkpoint 接着干

执行实例随时可能挂掉。因为事实都在 State Store 里，任何实例都能加载最近的 Checkpoint 续跑。关键是恢复前先查再做：比如"补丁已写入、测试结果还没回来"时中断，恢复后应先查那次测试的结果，而不是再改一遍文件。有副作用的操作都带幂等键，用来判断"上一次到底做没做过"。

预算花完了：明确结束，而不是悄悄截断

预算是多维的：步数、时长、Token 与费用、工具调用次数、高风险动作次数。快到上限时，Harness 让模型收敛范围、优先交付已完成的部分；真的耗尽时进入"失败"，保留进度和未完成清单，转给人处理。比步数上限更早的信号是"没进展"：反复调用同一工具、反复得到同一错误、计划长时间不变——检测到就先要求重新规划，再考虑缩小任务或转人工。

高风险动作：先预览，再审批，再执行，再核实

发布、删除、付款、对外发消息这类动作，走 Preview → Approve → Commit → Verify：

• Preview：给审批人看实际要提交的内容、目标对象和影响范围。
• Approve：批准绑定到具体身份、对象版本和范围；批准后重新校验，防止等待期间环境已经变了。等待审批的任务挂起，不占计算资源。
• Commit：带幂等键执行，超时也不会重复提交。
• Verify：查询真实系统状态确认生效；失败就修复、补偿或升级给人，而不是把"请求已发出"当作成功。

审批不是越多越好。处处要确认会让人机械点"同意"。优先用更窄的工具、参数约束和 Sandbox 把风险降下来，只在策略判断不了的地方请人确认。

版本化发布

一个 Agent Release 把影响行为的东西全部锁在一起：模型与路由、Harness 版本、Prompt 与 Skill、工具清单与权限、Sandbox 配置、评估集与上线阈值。线上任何一条 Trace 都能追溯到具体版本，出了问题能复现、能回滚。

release: bugfix-agent@2026.10.19-3
model: model-a@2026-09     harness: 1.8.2     skills: [repo-nav@3, test-fix@5]
tools: tools@19            sandbox: container  eval: { dataset: bugfix@12, gate: success>=0.82 }

评估门禁

改进从真实失败出发：把线上 Trace 按症状和根因聚类，再做最小、对准根因的修改——缺事实就改上下文，工具用错就改工具定义或权限，没进展就调循环或计划，误判完成就加强验收。不要看到一条失败就往 Prompt 里加一句话。回归集同时包含原失败用例、相邻的正常用例和安全对抗用例，看成功率，也看成本和安全事件。

灰度上线

过了离线门禁，新版本先接小流量，与旧版本对比成功率、成本和风险；达标才全量，不达标直接回滚到上一个版本。Agent 不在生产中修改自己：模型或反馈生成的任何补丁，都只是下一轮的候选变更。

几个关键权衡

• Workflow 还是 Agent：审批、入账这类确定性环节留给 Workflow，Agent 只处理路径无法穷举的部分。
• 单 Agent 还是多 Agent：默认单 Agent；只有上下文装不下、权限需要隔离或子任务能并行时才拆，拆了要付出通信和合并成本。
• 自建还是复用：编排层自己掌握，因为它决定任务效果和可回归性；Sandbox、模型接入这类执行基础可以用托管服务。
• 隔离强度与速度：默认容器；运行不可信代码或处理高敏数据时升级到微虚拟机。
• 脚手架随模型简化：每次换模型都重新评估，删掉已经不需要的补偿逻辑。