很多工程师第一次接触编码 Agent 时会有个误解：以为本事全在模型里，换个更强的模型就万事大吉。但实际用下来会发现，同样的底座模型，套不同的工程框架，干活能力天差地别。这中间起决定作用的东西，就是 harness——直译"挽具/马具"，在编码 Agent 语境里指模型外面那层"编排脚手架"。这篇我们讲清楚 harness 到底是什么、由哪些部分组成、以及"要不要做成 Agent"该怎么判断。

模型只产出意图，harness 才让它落地

先把一个边界划清楚：大模型能做的，只是根据上下文输出文本。它不能真的读文件、跑命令、调接口。当你给它挂上工具，它在需要时会输出一个结构化的 tool_use——比如"我要调用 run_bash，参数是 pytest"。但这只是意图，不是执行。

真正把 pytest 跑起来、把退出码和报错收回来、再喂回给模型的，是 harness。所以可以下个定义：

Harness = 模型外面那套让它能真正干活的工程系统。 模型只产出 tool_use，harness 负责执行工具、回灌结果、并全程管控这个过程。

把模型比作大脑，harness 就是神经、四肢和约束它的安全带。少了它，再聪明的大脑也只是在空想。

Harness 的五个组成部分

一个完整的编码 harness，通常包含五块互相配合的东西：

1. Agent 循环（agentic loop）。 这是骨架：模型输出 tool_use → harness 执行 → 把 tool_result 回灌进对话 → 再次请求模型 → 如此往复，直到模型返回 stop_reason: end_turn。正是这个循环，让模型能基于"工具的真实反馈"一步步迭代，而不是一次性盲写一大段代码。

2. 工具（tools）。 模型的手脚：读写文件、执行命令、检索代码、调用 API。工具的设计质量直接决定 Agent 的上限——一个把完整报错回灌的工具，远胜过只回灌"失败了"三个字的工具。工具是模型唯一能影响真实世界的通道。

3. 上下文管理（context management）。 模型的上下文窗口有限，而真实代码库动辄上百万行。harness 必须决定喂什么进去：哪些文件、哪些历史、哪些检索结果，何时压缩或丢弃旧消息。喂得准，Agent 才不会在无关信息里迷路或爆窗。

4. 验证（verification）。 Agent 改完代码不能自说自话，得有客观的对错信号——跑测试、跑编译、跑 lint。这些验证结果回灌进循环，模型才能发现自己改错了并纠正。没有验证的 Agent 是危险的，因为它的"我搞定了"无从证伪。

5. 权限管控（permissions）。 哪些操作可以自动执行，哪些必须人工确认（删文件、推远程、改生产配置）。这层决定了把多大的自主权交给 Agent，是安全的最后一道闸。

这五块缺一不可。模型决定"想做什么"，harness 这五件套决定"能不能真做、做得对不对、出了事兜不兜得住"。

用伪代码看清它如何运转

把核心循环写出来，harness 的角色就一目了然：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
messages = [{"role": "user", "content": 任务}]

while True:
    resp = model.create(messages=messages, tools=TOOLS)  # 模型产出意图
    messages.append(assistant(resp.content))

    if resp.stop_reason != "tool_use":
        break  # end_turn，任务结束

    results = []
    for call in resp.tool_calls:
        if 需要审批(call):            # 权限管控
            等待人工确认(call)
        out = 执行工具(call)          # 工具 + 执行
        记录审计日志(call, out)
        results.append(tool_result(call.id, out))

    messages.append(user(results))    # 把结果回灌
    messages = 压缩上下文(messages)    # 上下文管理

模型在这段代码里只占一行（model.create），其余全是 harness 的活：执行、回灌、审批、记日志、管上下文。这恰好印证了那句话——能力的差距，往往不在模型，而在模型外面的工程。

要不要做成 Agent：先过四问

不是所有任务都该上 Agent。Agent 意味着更高的成本、更高的延迟和更难预测的行为。在投入前，建议拿四个问题逐一筛一遍：

  1. 复杂度：任务是不是多步骤、且难以提前完全规约清楚？如果步骤固定、能写死流程，那就别用 Agent，写个普通工作流更稳。
  2. 价值：这个任务值不值得为它付出更高的成本与延迟？低价值的简单任务，一次性调用足矣。
  3. 可行性：模型本身擅不擅长这类任务？模型做不好的事，套再好的 harness 也救不回来。
  4. 纠错成本：万一 Agent 出错，能不能被测试、审查、回滚兜住？兜不住的高风险场景（直接操作生产、不可逆操作），要么不用，要么把权限管控做到极严。

只要有任意一问的答案是"否"，就应该退回到更简单的方案——单次模型调用，或一条确定性的工作流。编码恰好是 Agent 的甜区：步骤多且难预先规约（复杂度 ✓）、能省大量人力（价值 ✓）、模型擅长（可行性 ✓）、有测试和版本控制兜底（纠错成本 ✓）。四问全过，才值得把它做成 Agent。

结尾

Harness 是把"会说话的大模型"变成"能干活的编码 Agent"的那层工程：模型负责思考，harness 负责让思考落地、可验证、可管控——理解了这一点，你优化 Agent 的着力点就会从"换更强的模型"，转向"把循环、工具、上下文、验证和权限这五件套打磨好"。