一篇文章搞懂 Agent Harness:从概念、原理到我们该不该上

0. 先说清楚我们要解决什么

你大概有过这种感觉:大模型 API 调起来很爽,但一让它"干点实际的事"就露馅——

  • 你问它"帮我看看 218 上 Ollama 跑得动吗",它给你一段看起来对的命令,但它自己不会真的去跑;
  • 你让它"读一下这个日志文件再总结",它说"我没有访问你文件的能力";
  • 你让它"连错三步后换个思路再试",它答完一句就停了,不会自己纠错。

这中间的鸿沟,就是 harness 要填的。本文就讲三件事:harness 是什么、它内部怎么转、以及结合我们自己的系统,到底要不要上。读到最后你会发现,harness 没有魔法,它是一套可被拆解、可被评估的工程。


1. Harness 这个词到底什么意思

英文 harness 本义是马具——套在马身上、用来控制和牵引它的那套装备。软件圈借这个词,意思很朴素:把某个"引擎"套牢,给它接上控制和执行机构,让它能真正干活的那层封装。 注意重点是"套"和"控制"——harness 不是引擎本身,它围着引擎转。

在 LLM 时代,harness 主要出现在两个地方,先分清楚,后面才好聊:

  • Agent Harness(智能体运行时)。把"只会生成文本的大模型"变成"能读文件、跑命令、调接口、循环执行任务"的智能体的那层软件。核心公式:Agent = Model + Harness。Model 是大脑,Harness 是身体(手脚 + 循环控制 + 安全护栏)。代表:我们的 dsh、Claude Code、OpenHands、AutoGPT、LangChain Agent。
  • Eval Harness(评测框架)。把模型套住、用统一流程跑 benchmark 的框架,最出名的是 EleutherAI 的 lm-evaluation-harness(评测 Llama、Qwen 常用)。它不接工具、不跑循环,只负责"喂题 → 收答案 → 算分"。

两者本质相同:都是用一层协议把"裸模型"驱动起来。区别只是,Agent harness 驱动它去干活,Eval harness 驱动它去考试。顺带说一句:你平时看到"某公司发了一个 harness",十有八九是 agent harness;看到论文里"我们用 xx harness 评测",那是 eval harness。别被同一个词带偏。

本文聚焦 Agent Harness——因为它和我们"要不要上"最相关。


2. 为什么非得有这一层

裸 LLM API 只做一件事:输入文本 → 输出文本。它天生缺四样东西:

  1. 记忆:每次请求上下文清零,上一句说了啥它不记得。
  2. 手脚:不能读你电脑的文件、不能执行命令、不能调接口。
  3. 循环:答完就停,不会"发现不对再试试"。
  4. 护栏:你让它 rm -rf / 它就真往那个方向写,没有任何拦截。

Harness 就是来补这四块的。没有它,LLM 是"会聊天的计算器";有了它,它是"能自助完成任务的同事"。

一句话记住:模型负责"想",harness 负责"动手 + 循环 + 保护"。 这个分工是理解后面所有内容的总纲——凡是 harness 做的事,本质上都是替模型把"想"和"做"之间的裂缝补上,并且保证"做"是安全可控的。


3. 核心原理:Agent = Model + Harness

把 harness 拆开,它其实就围着模型包了六块:

  • 执行循环(ReAct):harness 的心脏。反复"让模型想 → 模型决定调工具 → harness 执行 → 把结果喂回 → 模型再想",直到模型说"我做完了"。
  • 工具/技能系统:注册一批能力(读文件、写文件、跑 shell、调 API)。模型通过 function calling 声明要用哪个,harness 才真去执行。
  • 上下文管理:把系统提示、历史、工具结果拼成发给模型的 prompt;窗口快满时压缩/摘要。
  • 记忆系统:短期(当前会话)+ 长期(跨会话落盘,如 dsh 的 sessions 目录)。
  • 沙箱与安全护栏:隔离执行环境,限制权限和网络。
  • 模型适配层:屏蔽 OpenAI / DeepSeek / Ollama 的协议差异,harness 只管调统一的 chat()。

3.1 最关键的:执行循环怎么转

这是 harness 的灵魂,也是它和"一次性问答"最大的区别。最小实现大约 30 行:

模型每轮输出要么是"最终答案",要么是"我要执行 X 工具 + 参数",harness 负责真正执行并回灌。这个"想—做—看—再想"的圈,就是 ReAct(Reasoning + Acting)。

一个容易忽略的点:循环是有代价的。 每一步都是一次模型调用,上下文在累积。一个看似简单的任务,agent 可能跑 10~30 轮,token 消耗是单次问答的几十倍。所以 harness 一定要设"最大步数"上限,否则模型可能陷入死循环烧钱。我们 dsh 里也有这类保护。

3.2 工具协议:为什么是 function calling 而不是裸命令

      模型不直接拼 rm -rf 这种字符串,而是输出结构化 JSON:

      harness 拿 schema 校验参数、过白名单、再执行。这一步是"模型只决策、harness 才动手"的安全命门——也是为什么 harness 必须存在:它把"模型说的话"和"系统真正执行的动作"之间加了一道闸。模型永远不会直接碰到 shell,它只能"申请"一个工具调用,准不准、怎么执行,全由 harness 说了算。

3.3 agent 循环不止一种:四种主流模式

      ReAct 只是最基础的一种。理解这四种模式,你才真正看懂不同 harness 的取舍:

模式

怎么转

优点

缺点

典型场景

ReAct

想一步、做一步、看一步,交替进行

简单、实时纠错

长任务上下文易爆、token 多

短任务、需即时反馈

Plan-and-Execute

先一次性规划全部步骤,再逐步执行

长任务更省 token、方向清晰

计划错了难中途大改

多步工程任务

Reflection(反思)

做完一轮,让模型自我批评,再改

质量高、能自我纠错

多一轮调用、更慢

写代码、写文档

Multi-Agent

拆成多个角色(规划/执行/审查)协作

复杂任务分工清晰

编排复杂、成本高

大型自动化

       我们 dsh 走的是 ReAct 路线(也是 Claude Code 的路线);如果你以后想做"自动排障",长链路任务可能更适合 Plan-and-Execute 或 Multi-Agent。选型不是越高级越好,而是看任务长度和容错要求。


4. 拿我们的 dsh 当活样本看

  DeepSeek Harness 就是一个标准 agent harness,第 3 节每一块它都有:

  • 执行循环:内部就是 3.1 那个 ReAct 圈。
  • 工具/技能:文件读写、shell 执行、子任务拆分(Cordis 插件架构)。
  • 模型适配:同时接了本地 Ollama(qwen2.5:7b)和 new-api 网关(DeepSeek 渠道)。
  • 沙箱/护栏:专用低权用户 dsh(无 sudo、无 docker 组)、systemd 硬化、只绑 127.0.0.1 + URL token、工作区圈定到 /var/lib/dsh/workspace。
  • 访问:只能本机 + token,要走 SSH 隧道 bash ~/bin/dsh-access.sh。

几个我们踩过的真实坑,正好帮你建立体感:

  • 7B 跑不动 agent(最重要的一个)。链路全通、模型真被调用,但 qwen2.5:7b 跟不上 harness 的 agent 系统提示——这里展开讲:harness 会在 system prompt 里塞一大段"你是 agent,可用工具有 X/Y/Z,按 ReAct 格式输出"的指令。7B 模型参数量小,既要理解任务、又要记住工具协议、还要规划步骤,顾不过来,于是问它"解释 SRv6",它回"请问您需要执行哪个功能",典型指令遵循失败。这告诉我们:harness 把模型推到"规划 + 多步 + 守协议"的硬仗里,对模型能力要求远高于 RAG 生成(RAG 只要"读懂资料、写通顺"就行)。小模型适合当 RAG 生成器,不适合当 agent 大脑。
  • token 每次启动随机变,只能从 journalctl 拿,没有固定启动参数——这是 dsh 的设计,不是 bug。
  • 在 root 家目录跑会 EACCES,因为 dsh 在 cwd 找 .env/.git——得先 cd /var/lib/dsh/workspace。

5. 怎么造一个最小 harness(去神秘化)

       真没那么玄。一个能"读文件 + 跑命令 + 循环"的最小 harness,核心就是第 3.1 节的循环 + 一个工具表 + 一个执行器:

       跑在沙箱里(容器 / 低权用户)就能用。这一步的意义不是让你去造轮子,而是让你明白:harness 没有魔法,它本质是"循环 + 工具调度 + 护栏"三件套。

       懂了这点,你再看 dsh / Claude Code,就不会被包装吓到。工业级 harness 只是在这三件套上做厚:更多工具、更稳的循环、更细的权限、更聪明的上下文压缩。


6. 工具生态:MCP 与工具标准化

         当你开始给 harness 加工具,马上会遇到一个问题:每个 harness 自己定义工具格式,工具不能互通。 你给 dsh 写一个"查设备状态"的工具,换到另一个框架就得重写。

         MCP(Model Context Protocol,Anthropic 提出) 就是来解决这个的:它把"工具提供方(server)"和"模型消费方(client/harness)"用一个标准协议连起来。就像 USB 接口——工具做成 MCP server,任何支持 MCP 的 harness 都能即插即用。今天主流 harness(Claude Code、很多开源 agent)都在拥抱 MCP。

对学习的你来说,记住两点就够了:

  1. 工具正在标准化,未来你不必为每个框架重写工具,写一次 MCP server 到处用。
  2. harness 的核心竞争力,越来越不是"能不能调工具",而是"调得稳不稳、安不安全、上下文管得好不好"——工具本身会商品化。

      我们 ops-copilot 的检索能力如果想被 harness 复用,未来最自然的形态就是封装成一个 MCP server,而不是硬塞进某个框架。


7. 上下文与记忆(harness 真正难的地方)

模型窗口有限(哪怕 128K 也会爆),而 agent 一轮轮往里塞工具结果,很快就满。harness 的"内功"一大半在这:

  • 短期记忆:当前会话的 messages。满了怎么办?三种常见策略:① 截断最早的(最简单但丢信息);② 摘要压缩(让模型把前面聊的总结成一段);③ 检索式——把历史存起来,用到时再拉相关片段(和我们的 RAG 思路一样)。
  • 长期记忆:跨会话保留。dsh 的 sessions 目录就是干这个——这次排查的经验,下次能接着用。
  • 记忆的分类(学术上常提):情节记忆("上次在 218 上 Ollama 跑通了")、语义记忆("SRv6 是 IPv6 分段路由")、程序记忆("排查网络先查接口状态再查路由")。好的 harness 会让模型把这些分门别类存,而不是全糊进聊天记录。

这也是为什么我们说"ops-copilot 用 RAG 就够了"——RAG 本质就是一种检索式长期记忆方案,而我们主场景恰好是"查资料",和 harness 的上下文管理是同一类需求的轻量版。


8. 失败模式与应对(harness 真正坑的地方)

学 harness 最该看的不是它多厉害,而是它怎么翻车。常见六种:

  1. 死循环 / 不终止:模型一直调工具不停。→ 必须设最大步数(max_steps)和停止条件。
  2. 工具调用幻觉:模型调了一个不存在的工具,或参数类型错。→ schema 校验 + 失败回灌让模型重试。
  3. 工具执行报错没恢复:命令失败,模型假装成功继续。→ 把报错原文喂回去,强制它面对。
  4. 上下文溢出:工具输出太大(比如 cat 一个 50MB 日志)。→ 截断 / 摘要 / 按需读取。
  5. 成本爆炸:多轮调用 token 滚雪球。→ 预算上限 + 步数上限。
  6. 安全事故:模型生成危险命令被执行。→ 沙箱 + 白名单 + 人工确认(见第 9 节)。

记住:harness 的稳定性,几乎全靠这些"兜底"堆出来。 一个没做兜底的最小 harness(第 5 节那个)只能玩具级用;工业级 harness 的代码量,大部分花在这些兜底和护栏上,而不是"循环"本身。


9. 安全护栏的几种做法(生死线)

harness 会执行模型生成的命令,所以安全不是可选项。从弱到强四种隔离级别:

级别

做法

安全性

适用

同进程

直接 exec,无隔离

几乎无

只玩具

低权用户

专用账号,无 sudo/docker

中

我们 dsh

容器

Docker 隔离文件系统/进程

高

通用部署

微虚拟机

Firecracker 等,硬件级隔离

极高

多租户/不可信

权限模型也有三档:全放开(危险)、白名单(只允许特定命令/目录,推荐)、每次确认(HITL,human-in-the-loop)(关键操作弹窗让人点)。网络层面要限制出网(agent 不需要随便访问公网)。最后,所有执行的命令必须留痕审计——真出事能回溯。

我们的 dsh 用了"低权用户 + systemd 硬化 + 只绑 127.0.0.1 + 工作区圈定",属于"中"档,对一个实验机够用;但文档里也写了残留风险(dsh 用户仍能读 world-readable 文件、能出网),跑不可信任务还得再套容器。


10. 怎么选 / 评测一个 harness(主流框架对比)

如果哪天真要上新 harness,怎么挑?先横向看一眼主流玩家:

框架

定位

开源

语言

适合

Claude Code

编码 agent

否(商用)

TS

个人/团队编码

DeepSeek dsh

编码 agent

是(MIT)

TS

我们已部署

OpenHands

编码/运维 agent

是

Py

通用自动化

LangChain / LangGraph

agent 框架(自己搭)

是

Py

高度定制

AutoGPT

早期自主 agent

是

Py

研究/思路参考

CrewAI

多 agent 协作

是

Py

多角色分工

选型看四件事:① 任务类型(编码选 dsh/Claude Code,通用选 OpenHands);② 能否自托管(我们要放内网,闭源的 Claude Code 直接出局);③ 安全模型(能不能降权/限网/白名单);④ 模型门槛(小模型带不动,得配强模型)。

评测一个 harness 好不好,别只看 demo,看这五个指标:任务成功率、平均步数(效率)、token/成本、安全事故数、上下文管理能力。我们之前"7B 驱动不了 dsh"就是一条失败的"模型门槛"评测结论。

posted @ 2026-11-16 10:27  FutureAI-Zeng  阅读(265)  评论(0)    收藏  举报