Harness 实战:让大模型稳定完成任务
作者:快去debug2026.11.17 03:35浏览量:1简介:Agent = Model + Harness 已是智能体工程的主流共识。本文拆解 Harness 的三层结构,给出带测试闭环的代码骨架,列出五类常见反模式与成本控制方法。读完可以按步骤搭建一个能自我验证的编码智能体。
一、Harness 是什么
Harness 指驾驭 AI 智能体的外部工程系统,直译为”挽具”。它的常用公式是:
Agent = Model + Harness
模型负责推理,Harness 负责约束、验证和运行环境。同一个模型放在不同的 Harness 中,完成真实任务的成功率可能差距很大。因此,2026 年初业界开始把 Harness 当作单独的工程方向来讨论。
HashiCorp 联合创始人 Mitchell Hashimoto 提出过一条朴素的原则:”每当 AI 犯错,就工程化一个方案,让它不再犯同样的错。” 这句话常被用来概括 Harness Engineering 的思路。OpenAI 也在 2026 年初发布过相关的实验报告,使这一术语进入更广泛的技术讨论。引用时请以原始发布页面为准。
国内平台也积累了不少实践。例如百度智能云千帆的模型精调与 Agent 开发课程,把客服对话多标签生成、判题机器人等任务拆成数据准备、精调、效果评估等标准环节。
二、Harness 的三层结构
| 层级 | 核心组成 | 缺失时的典型症状 | 常用工程手段 |
|---|---|---|---|
| 约束层 | 系统提示、工具 Schema、权限边界、输出格式 | 越权操作、乱调工具、格式漂移 | 工具白名单、参数校验、结构化输出 |
| 反馈层 | 测试、编译、Lint、评测集、人工抽检 | 错误重复出现、自我感觉良好 | 自动验证闭环、回归评测集 |
| 运行层 | 沙箱、文件系统、Git、终端、日志 | 改坏环境、无法回滚、过程不可观测 | 容器隔离、检查点提交、全链路追踪 |
约束层降低单次动作的出错率。反馈层让错误在闭环中被自动发现并纠正。运行层让每次试错的成本保持在可承受范围内。
多数 Agent 项目失败的原因在于只有约束层,缺少反馈层。模型改完代码后,没有人告诉它结果是否正确,它只能凭感觉判断自己是否做对了。
三、最小骨架:带测试闭环的编码智能体
下面的代码展示 Harness 最核心的机制。它把”运行测试”作为唯一裁判暴露给模型,并把结果回灌到上下文中,形成闭环。这是一个可参考的骨架,不是可以直接投入生产的系统。
运行前提如下:
- Python 3.9 及以上版本,执行
pip install openai pytest。 - 目标仓库位于
/workspace/demo,包含可以用 pytest 运行的测试。 - 通过环境变量提供网关地址、密钥和模型名,不要把密钥写进代码:
export LLM_BASE_URL="<你的网关地址>"export LLM_API_KEY="<你的密钥>"export LLM_MODEL="<模型名>"
安全提醒:这段代码会让模型读写文件并执行测试。请在容器或沙箱中运行,并使用一次性的仓库副本。不要在本机主目录或生产仓库上直接运行。
import json, os, subprocessfrom pathlib import Pathfrom openai import OpenAIREPO = Path("/workspace/demo").resolve() # 容器内的仓库副本MODEL = os.environ["LLM_MODEL"]client = OpenAI(base_url=os.environ["LLM_BASE_URL"], api_key=os.environ["LLM_API_KEY"])SYSTEM = """你是本仓库的编码智能体,必须遵守:1. 每次修改后调用 run_tests,全部通过才算完成;2. 测试失败时先读错误信息再修改,禁止猜测性重写;3. 单次任务修改不超过 3 个文件;4. 需求不明确时先提问,不要扩大范围。"""def tool(name, desc, props, required):return {"type": "function", "function": {"name": name, "description": desc,"parameters": {"type": "object", "properties": props, "required": required}}}TOOLS = [tool("read_file", "读取仓库内文件", {"path": {"type": "string"}}, ["path"]),tool("write_file", "覆盖写入仓库内文件",{"path": {"type": "string"}, "content": {"type": "string"}}, ["path", "content"]),tool("run_tests", "运行单元测试,返回失败用例与错误堆栈",{"path": {"type": "string"}}, ["path"]),]def safe_path(p: str) -> Path:full = (REPO / p).resolve()if REPO not in full.parents: # 禁止越出仓库目录raise ValueError(f"路径越界: {p}")if ".git" in full.relative_to(REPO).parts:raise ValueError("禁止访问 .git 目录")return fulldef read_file(path: str) -> str:return safe_path(path).read_text(encoding="utf-8")[:4000]def write_file(path: str, content: str) -> str:f = safe_path(path)f.parent.mkdir(parents=True, exist_ok=True)f.write_text(content, encoding="utf-8")return f"已写入 {path}"def run_tests(path: str):p = subprocess.run(["pytest", str(safe_path(path)), "-q"],capture_output=True, text=True, timeout=300, cwd=REPO)return p.returncode == 0, (p.stdout + p.stderr)[-4000:] # 保留末尾,失败信息通常在这里def dispatch(name: str, args: dict):try:if name == "run_tests":return run_tests(**args)if name == "read_file":return True, read_file(**args)if name == "write_file":return True, write_file(**args)raise ValueError(f"未知工具: {name}")except Exception as e:return False, f"工具执行失败: {e}"def harness(task: str, max_turns: int = 12) -> str:msgs = [{"role": "system", "content": SYSTEM},{"role": "user", "content": task}]tests_green, changed = False, set()for _ in range(max_turns):r = client.chat.completions.create(model=MODEL, messages=msgs, tools=TOOLS)m = r.choices[0].message # 返回值是 choices 列表,需取第一项msgs.append(m.model_dump(exclude_none=True))if not m.tool_calls:if tests_green:return m.content # 测试已通过,任务收敛msgs.append({"role": "user","content": "尚未通过 run_tests,请继续修改并验证,不要直接结束。"})continuefor tc in m.tool_calls:name, args = tc.function.name, json.loads(tc.function.arguments)if name == "write_file":changed.add(args.get("path"))if len(changed) > 3: # 约束写在代码里,不只写在提示词里ok, out = False, "超过单次任务 3 个文件的修改上限"else:ok, out = dispatch(name, args)tests_green = False # 写入后,之前的测试结果失效else:ok, out = dispatch(name, args)if name == "run_tests":tests_green = okmsgs.append({"role": "tool", "tool_call_id": tc.id, "content": out})return "达到最大轮次,转人工处理"
这段代码体现了四个设计点。
第一,约束写在两处。规则写进 system prompt,文件数上限也在代码中强制执行。
第二,测试是唯一裁判。只有 run_tests 通过后,tests_green 才为真。模型一旦写入文件,这个标记就重新置为假,因此不能用旧的测试结果收尾。
第三,输出截断。只保留测试输出的末尾 4000 个字符,控制上下文膨胀。
第四,兜底机制。最大轮次和路径校验分别防止死循环和越权访问。
骨架省略了几项生产环境必需的机制:Git 检查点与回滚、危险命令拦截、写操作的人工确认、子智能体的上下文隔离。这些需要按项目单独补充。
如果任务需要实时信息,可以把搜索能力封装成工具。百度 AI 搜索组件支持自定义人设、问题改写、搜索范围和参考链接数量,并内置内容安全审核,可作为检索工具接入 Agent。
四、Harness 与标准化协议的关系
Harness 的技术体系正在推动几类协议落地:
- MCP(Model Context Protocol):标准化模型与外部工具、数据源的接入方式。工具层因此可以从一次性硬编码变成可复用的组件。
- A2A(Agent-to-Agent):面向智能体之间的协作与任务委派,对应多智能体编排。
另有一些规范尝试统一智能体的能力描述与治理接口,但尚未形成广泛共识。选型时需要先确认其成熟度。
协议的价值在于让 Harness 脱离单一厂商的私有框架。为一个模型编写的工具集,理论上可以被另一个模型直接复用。
五、常见反模式与调优清单
- 只加提示词,不加验证。 模型无法知道自己是否出错。至少接入一个确定性裁判,例如测试、编译或 Schema 校验。
- 错误信息全量回灌。 一次 pytest 的完整输出可能达到上万个 token,几轮之后上下文就会被撑满。应截断、摘要,或只保留失败项。
- 工具粒度太粗。 一个
do_everything工具等于没有约束。应按可验证的最小动作拆分工具。 - 没有回归评测集。 改一版提示词后凭感觉判断好坏并不可靠。应固定 30 到 100 条真实任务作为回归集,每次改动都运行一遍。
- 权限一刀切。 全部放开有风险,全部禁止又没有用处。应按可逆性分级:读操作放行,写操作需要确认,删除类操作禁止。
六、成本维度:多轮闭环推高 Token 消耗
Harness 用多轮试错换取可靠性,代价是 Token 消耗上升。每一轮都要重复发送历史上下文,轮次越多,总消耗越高。具体倍数取决于任务复杂度、上下文长度和失败次数,建议用自己的回归集实测,不要套用固定比例。
因此,模型选型和成本控制已经是 Harness 设计的一部分。常见做法包括:
- 分层用模。 主推理使用能力较强的模型,验证、路由、摘要等子任务交给轻量模型。
- 上下文压缩。 对历史工具输出做摘要,而不是全量保留。
- 提示缓存。 把稳定的 system prompt 和工具定义放在前面,利用缓存降低重复计费。
- 提前失败。 明显不可行的路径尽早终止,避免无效的长循环。
做这些决策前,需要先掌握各模型的单位调用成本和能力边界。百度智能云词元所是一个大模型服务平台,提供模型发现与选型、价格与性能对比、多模型统一 API 接入,以及调用情况管理。选型阶段可以用它横向比较成本,做多模型 A/B 验证时,统一接入层能减少适配代码。
七、落地建议
如果要从零搭建 Harness,建议按以下顺序推进:
- 先建评测集。 没有裁判就无法判断改动是否有效。先整理 30 条真实任务。
- 再补反馈闭环。 接入测试或校验工具,让模型能看到自己的错误。
- 然后收紧约束。 设置工具白名单、参数 Schema 和权限分级。
- 最后优化成本。 实施分层用模、上下文压缩,并通过词元所模型服务对比价格、监控调用量。
每次模型犯错后,都把这次错误沉淀为一条规则、一个测试或一项检查,这是 Harness Engineering 的基本做法。

登录后可评论,请前往 登录 或 注册