Harness工程：AI Agent从玩具到协作者

一、行业在卷两件事，真正的瓶颈在第三处

过去一年，围绕 AI Agent 的讨论大多集中在两条线上：一条盯着底层模型的能力上限，比参数、比评测分数；另一条钻研提示词写法，卷上下文组织、角色设定与推理链技巧。这两条线当然有价值，但当你真正把 Agent 搬进企业内部的工程环境——要接内部系统、要过权限管控、要交付可验收的产出——就会很快发现：决定成败的，往往不是提示词有多精妙，而是“把大模型纳入工程体系”这件事做得有多扎实。

二、Harness 是什么：一套面向大模型的控制面

先说清楚 Harness 不是什么：它不是某条提示词，不是某个具体工具，也不是多写几份操作文档。这些单独看都对，但都只是局部。

Harness 应被理解为一套控制面，负责把一个天然非确定性的执行核心（大模型），接入到一个要求确定性的工程交付体系里。它至少要回答五个问题：

1. 唯一真相源：Agent 从哪里获得权威、一致、不过期的信息？是架构文档、接口契约与代码仓库的受控组合，还是散落在聊天记录和口头共识里的碎片？
2. 执行边界：哪些操作允许执行，哪些必须禁止，哪些需要人工确认？工具调用如何分级（只读/可写）、如何设超时与配额？
3. 能力接入：企业内部的业务能力，如何以标准化、松耦合的方式暴露给 Agent，而不是为每个任务临时糊一层粘合代码？
4. 可观测与可调试：一次运行中，Agent 看到了什么上下文、做了什么决策、调了什么工具、拿到了什么返回，事后能否完整回放？
5. 可验证、可回归、可交接：产出如何被自动验收？改动之后如何确认既有能力没有退化？换一名工程师接手，理解成本是否可控？

这五个问题各自对应一根支柱，缺一根，整套体系就会从那个缺口漏风。

三、一次内部实践的复盘：工程摩擦清单

在一个内部研发效率项目中，我们没有从“先写一个能发请求的 Agent”起步，而是先读架构文档、收敛目标、迁移参考实现。即便如此，推进过程中摩擦依然密集出现，比较有代表性的四类：

• 上下文断裂：任务推进到中段，先前建立的约束与决策没有被稳定传递，Agent 开始“自由发挥”，产出偏离预期。
• 工具耦合：能力接口与提示词、执行流程互相纠缠，改一处、崩三处，谁都不敢动。
• 接口异常：内部接口偶发超时（504）与权限拒绝（403），而 Agent 侧缺乏统一的重试、降级与鉴权续期机制，一次裸奔失败就能中断整条任务链路。
• 测试即退：本地测试环境直接退出，且没有可复现的留痕，问题无从定位。

复盘下来有一个清晰的结论：这些坎能不能跨过去，与“换一个更聪明的模型”几乎没有关系；几乎每一个坎的跨越，都对应着我们在那个节点补上了一块 Harness——

• 应对上下文断裂：引入结构化任务状态，每一步都从唯一真相源重建上下文，而不是依赖对话历史的“记忆”；
• 应对工具耦合：把能力定义为显式契约，Agent 只依赖契约，不依赖实现；
• 应对接口异常：在执行层统一实现超时、重试、幂等与权限续期，让 Agent 对这些细节无感知；
• 应对测试即退：建立带全量留痕的运行沙箱与不变量断言，让失败可定位、可复现。

换句话说，项目每一次“突然变顺”，都不是因为换了模型或改了提示词，而是因为某个节点的 Harness 到位了。

四、两个互相咬合的判断

判断一：今天的大模型能力，已经足以参与真实的研发交付。但没有 Harness，它充其量是个高级玩具；有了 Harness，它才可能成为研发链路中的协作者。

判断二：程序员的核心价值正在迁移——从“亲手写出每一行代码”，转向“定义目标、卡住边界、掌控节奏、验收结果”。

需要强调的是，这两个判断不是并列关系，而是因果关系，且方向是单向的：正因为工程师必须学会放权、不能再把所有实现攥在自己手里，所以必须先把 Harness 建起来——没有约束与验证设施，放权等于失控；也正因为 Harness 建起来了，放权之后的交付才变得可预期、可审计，“从执行者走向控盘者”的身份迁移才真正可行。先有 Harness，后有身份迁移，顺序不能反。

五、与传统软件工程的分界线：确定性 vs 非确定性

很多同行第一次听说 Harness，反应都是：加测试、看日志、写规范、做代码评审——这不就是软件工程的良好实践吗？为什么要造新词？

如果仅是这样，确实没必要造新词。分界线在于：传统软件工程管理的是确定性，Harness Engineering 管理的是非确定性。

传统软件工程本质上是“为人类设计的防呆系统”：人有常识，但会手滑——敲错一个变量名、漏掉一个空指针判断。类型系统、单元测试、静态检查、代码评审，这些手段的共同前提是：程序行为可复现，同样的输入总会产生同样的输出——正因如此，“跑一次测试”才有意义。

大模型恰好击穿了这个前提。同一段输入，两次生成的输出可能不同；同一个任务，两次执行的路径可能不同。于是传统防呆手段开始大面积失灵：单元测试假设被测对象行为稳定，而 Agent 的输出天然漂移；代码评审针对人类的书写习惯，而 Agent 生成的代码往往风格工整、却在意图上悄悄跑偏；传统日志为排障而生，而你现在最需要的是“回放 Agent 当时到底看到了什么”。

维度	传统软件工程	Harness Engineering
管理对象	确定性程序行为	非确定性模型行为
防的是什么	人的手滑	系统的漂移
核心前提	输入相同则输出相同	输出天然不可复现
主要手段	测试、类型、评审、静态检查	不变量、能力契约、结果验收、留痕回放
质量边界	代码写得对不对	目标有没有达成

因此，Harness 必须引入在传统工程里不那么显性的手段：

• 不变量优先于路径：不规定 Agent 每一步怎么走，只规定任何一步都不允许突破什么（只读范围、禁改清单、资源上限）；
• 验收优先于过程控制：用可执行的验收标准（构建通过、测试通过、结构校验、指标阈值）替代对生成过程的逐步审批；
• 全量留痕与回放：上下文快照、计划步骤、工具调用与返回值完整落盘，供审计与调试；
• 回归基线：把“能力有没有退化”变成一条可持续运行的检查项，而不是靠某个人“感觉它最近变笨了”。

六、落地路径：四步搭起一套 Harness

第一步：收敛目标，建立唯一真相源。 先把“Agent 要做什么、做到什么程度算合格”写成可验收的条目；再把架构文档、接口契约、约束规则集中成一份权威输入。Agent 的每一次运行，都应从这份真相源出发，而不是从上一次对话的记忆出发。

第二步：把能力封装为显式契约。 每个能力都应带描述、输入输出结构、权限级别、超时与失败策略，示意如下：

{
  "capability": "query_deployment_status",
  "description": "查询指定服务在指定环境的部署状态，只读",
  "input_schema": { "service": "string", "env": "string" },
  "constraints": { "readonly": true, "timeout_ms": 3000 },
  "failure_policy": "retry_then_fallback"
}

要点在于：契约是唯一的耦合点。能力侧与 Agent 侧各自演进、互不感知，更换底层模型或重构内部接口都不会波及全局。

第三步：建立观测与调试回路。 为每次运行记录完整执行轨迹，支持单步重放（以下为示意代码，仅表达结构）：

def run_with_harness(task):
    ctx = load_truth_source(task.scope)            # 唯一真相源
    plan = agent.plan(ctx, boundaries=task.rules)   # 边界先行
    trace = Trace()
    for step in plan:
        trace.record(step)                          # 全量留痕
        assert invariants_hold(step, task.rules)    # 不变量校验
    verify(task.acceptance, trace)                  # 结果验收
    return trace.snapshot()                         # 供回归与审计

没有这个回路，对 Harness 的一切改进都是盲改；有了它，“为什么这次没做成”就从玄学变成可定位的工程问题。

第四步：固化回归与交接。 把每次任务的验收结果沉淀为回归基线；把契约、边界规则、验收标准文档化，确保任何一名工程师都能在可预期的时间内接手整套体系。

顺手给出一份自检清单，评估你的 Harness 成熟度：

• 每个任务是否都有可执行的验收标准，而不是靠人“看一眼觉得行”？
• Agent 的每次运行是否都能从唯一真相源完整重建？
• 能力接入是否全部走显式契约，不存在提示词与接口的私下耦合？
• 出了问题，是否能在十分钟内回放一次运行？
• 换一名工程师接手，是否能在半天内理解全部边界与验收规则？

五个问题里有三个答“否”，说明你还在用玩具的标准运行生产系统。

七、结语

Harness Engineering 不是给大模型“上纪律”，而是给研发体系补上“管理非确定性”这块缺失已久的拼图。这块拼图就位之后，两件事会同时发生：Agent 的产出从“演示时惊艳”变成“交付时可靠”；工程师的位置从“生产每一行代码”移到“定义目标、卡住边界、掌控节奏、验收结果”。模型能力还会继续涨，提示词技巧还会继续卷，但在企业内部，真正构成壁垒的，是那套把非确定性变得可管理的工程设施。谁先把它建扎实，谁就先把大模型从“偶尔惊艳的变量”变成“研发链路里确定性的组成部分”。