跳到主要内容

新手看懂 Agent Harness

· 阅读需 4 分钟
ZhiQing Lin
ZhiQing Lin
CEO | Fuzhou Beisi Network Technology Co., Ltd.

上周我让一个 coding agent 接了一个很小的活：修一个接口偶发报错。

我没给它太复杂的需求，就是一句话：“改这个点，别碰别的文件。”

结果它先改了 api.ts，又改了 routes.ts，再把 README 也重写一遍，最后还没跑通测试。

我当时就明白了，这不是模型不行，而是它没有“能持续正确做事的围栏”。

为什么叫 harness​

很多人会先问：这名字怎么起的，为什么不叫框架？

harness 的重点不是“更强模型”，而是让模型的动作能被系统托住。

模型是会推理的，但推理和落地是两回事。它能说“该改这里”，却不知道该不该改、改了该验证什么、出错后怎么收回。

所以我们给它一层“夹紧器”： 任务边界、工具边界、权限边界、执行流程、日志和回滚。
这层夹紧器，就是 harness。

为什么它能解决业务闭环​

真实业务不是问答，而是循环。

一个完整闭环通常是：计划 → 执行 → 验证 → 修正 → 留痕。
只要缺了任何一步，自动化就会出问题。

有 harness 之后，agent 的链路是这样的：

  • 拿规则：先读 AGENTS.md 里的边界。
  • 下动作：只用白名单里的工具。
  • 看结果：测试不通过会回到前一步重试，而不是盲改。
  • 留痕：每次改了什么、为什么改、是否通过，都写到 trace 里。

没有闭环，agent 很容易像“很快做完一半事的人”；有闭环，它更像“能持续交付的人”。

设计要点（v0.1 下先做到这 8 点）​

  1. 目标边界：先声明本次只解决哪个问题，不要一上来就全量优化，否则方向漂移。
  2. 文件边界：只允许改你项目里安全的路径，关键配置和凭据目录禁止写。
  3. 工具边界：把工具分成 allow/deny，防止无意义或危险调用。
  4. 上下文边界：定期压缩历史，只把有价值信息留住，避免上下文老化导致偏题。
  5. 验证边界：改代码一定绑定至少一条检查，失败时必须修复再继续。
  6. 失败边界：同一失败连续 N 次触发人工介入，不要无限重试烧 token。
  7. 状态边界：任务计划、当前步骤、剩余风险写入持久文件，下一轮能接上。
  8. 可观测边界：每一步都要有日志：谁调用了哪个工具、用了多少时间、结果是什么。

Skill / Harness / Runtime / Framework 到底怎么分​

我给它一条很实用的判断线：

skill 是“能力包”，harness 是“治理系统”；runtime 是“执行场景”，framework 是“构建方式”。

  • Skill：某类任务怎么做，像“写周报”、“按模板改文案”。
  • Harness：谁能做、何时做、做完怎么验、坏了谁接盘。
  • Runtime：代码在哪跑，是本地、容器还是沙箱。
  • Framework：你用的开发框架，比如 LangChain、Agents SDK 这类 glue。

一句话：同一模型，换了 harness，体验可能完全变。反过来，没 harness 再强的模型也很容易翻车。

一个可抄的 v0.1 示例​

先从 .agent 目录起步，越简单越好。
你可以直接把它放到项目里试跑（再根据业务删减）：

AGENTS.md

- 只处理一个任务，任务不满足会先暂停。
- 只允许读写 src/**、tests/**、docs/**。
- 每次改动后先跑一次测试。
- 连续 2 次同类失败后暂停并告警。
- 提交前输出：改了哪些文件、测试结果、剩余风险。

.agent/harness.yaml

name: v0.1-agent-harness
scope:
  allowed_paths:
    - "src/**"
    - "tests/**"
    - "docs/**"
  deny_paths:
    - ".env"
    - "infra/**"
turn_policy:
  max_turns: 60
  max_files_changed: 4
tools:
  allow:
    - read_file
    - write_file
    - run_tests
    - git_diff
  deny:
    - delete_file
    - network_request
quality_gates:
  - command: "npm test --silent"
    on_fail: rollback
  - command: "git diff --check"
    on_fail: stop
observability:
  trace: "logs/agent-trace.jsonl"

这份配置并不复杂，但你已经把最核心的事做了：
定义边界、定义动作、定义验收、定义失败处理。

什么时候该拆复杂度，什么时候该收口​

不要一上来就建一个“全功能总控台”。
先跑 1-2 个真实任务，确认哪一步最常翻车，再补对应规则。

如果你发现模型本身经常卡在某个推理点，不用先加复杂系统，先加一条更明确规则。
如果 80% 任务都稳定了，再考虑引入多步规划、子任务 Agent、外部评测。

现实版结尾​

我现在的经验很实在：先把闭环做稳，再去追求更大的模型。
模型会进步，但工程习惯的提升不容易自己出现。你搭好 harness，才是真正把“会回答”变成“能交付”的开始。