专题 J：Agent Harness 解剖——模型之外，是什么让 Agent 真正可用

延展阅读 | 技术认知

---

这个专题讲什么

你用 Claude Code 写代码，给它一个需求，它读文件、写代码、跑测试、修 bug，一套操作行云流水。但模型本身只是一个"输入文本 → 输出文本"的黑箱——它怎么就能操作你的文件系统、执行 bash 命令、甚至自己 spawn 出一个子 Agent？

答案是一个概念：Agent Harness。

LangChain 的 Vivek Trivedy 在 2026 年 3 月写了一篇博客 The Anatomy of an Agent Harness，把 Agent 系统拆开，解释模型外面那层东西到底是什么。核心公式就一句话：

Agent = Model + Harness

模型承载智能，Harness 让智能变得有用。

作为 PM，你不需要写 harness 代码，但你定义的每一个工具边界、审批节点、失败兜底策略，都是在设计 harness。理解它的构成，你的产品决策会更准。

---

"只要你不是模型，你就是 Harness"

Trivedy 的定义很直接：If you're not the model, you're the harness.

裸的 LLM 不是 Agent。它接收数据（文本、图片、音频、视频），输出文本——仅此而已。要让这样一个东西变成能干活、能操作环境、能自我纠错的 Agent，必须在它外面包一层东西。这层东西包括：

• System Prompt：定义 Agent 的角色、边界、行为规范
• Tools / Skills / MCP 及其描述：给 Agent 装上手脚
• 内置基础设施：文件系统、沙箱、浏览器
• 编排逻辑：子 Agent 的 spawn、handoff、模型路由
• Hooks 和中间件：压缩上下文、继续执行、lint 检查等确定性钩子

你也可以用别的方式切分模型和 harness 的边界，但这个框架最清晰——它迫使你围绕模型智能来设计系统，而不是把模型当成万能钥匙。

---

为什么必须有 Harness

反过来想最简单：哪些我们希望 Agent 做到的事，模型自己根本做不了？

模型能接收数据，输出文本。它不能：

• 在不同交互之间保持持久状态
• 执行代码
• 获取实时信息
• 自己搭建环境、安装依赖

以上全部是 harness 层面的事。

就连最简单的聊天产品，也需要把模型包在一个 while 循环里——追踪历史消息、追加新用户输入。这叫 harness，只是太基础了你没注意到。

整篇文章的方法论就是一条：

从期望的 Agent 行为出发 → 反推需要什么样的 Harness 设计

---

文件系统——最基础的 Harness 原语

期望行为： Agent 需要持久存储来对接真实数据、卸载上下文装不下的信息、跨会话保持进度。

没有文件系统的时候，你怎么让模型处理文件？复制粘贴。把代码贴进对话框，模型吐出来，你再贴回去。人机对话勉强能用，自主 Agent 完全行不通——Agent 需要在没有人插手的情况下自己读、自己写、自己改。

而且这个世界已经在用文件系统做真实工作了，模型在海量 token 上训练过如何操作文件。最自然的方案就是让 harness 提供文件系统抽象和文件操作工具。

Trivedy 把文件系统称为"最基础的 harness 原语"，因为它解锁了三件事：

• Agent 有了工作区，能读数据、代码、文档
• 工作成果可以渐进式写入和卸载，不用全堆在上下文窗口里。中间产物可以持久化，状态跨会话延续
• 文件系统成了人类与 Agent 之间的天然协作界面。多 Agent 和人类通过共享文件协作——Agent Team 这类架构就靠这个

文件系统上加一层 Git，Agent 就能追踪进度、回滚错误、分支实验。这个原语在后面每个高级能力里都会反复出现。

---

Bash + 代码执行——通用工具替代一百个专用工具

期望行为： Agent 应该自主解决问题，不需要人类预先把每种可能的工具都写好。

主流的 Agent 执行模式是 ReAct 循环：模型推理 → 调用工具 → 观察结果 → 继续推理，包在 while 循环里。问题是，harness 只能执行你提前写了逻辑的工具。

如果预判 Agent 可能需要的每一个操作、提前写好工具，这是无底洞。

所以方案是：给 Agent 一个通用工具——bash。 Trivedy 说这是"朝给模型一台计算机、让它自己想办法迈出的一大步"。有了 bash，模型可以在运行时自己写代码创造工具，不用被锁在一组预配置的固定菜单里。

harness 仍然会搭载其他专用工具，但代码执行已经是自主解决问题的默认通用策略。

---

沙箱——安全、可扩展的执行环境

期望行为： Agent 需要配置好默认工具的环境，能安全行动、观察结果、持续推进。

模型有了存储、有了执行能力——但总得在某个地方运行。直接在本地跑 Agent 生成的代码太危险，一个本地环境也扛不住大量 Agent 并发。

沙箱提供隔离的执行环境。harness 连接到沙箱执行代码、检查文件、安装依赖。安全层面可以做命令白名单、网络隔离。沙箱还解锁了规模化——环境按需创建、并行铺开、任务完成销毁。

好的环境需要好的默认工具，这是 harness 的职责：

• 预装语言运行时和包管理器
• git 和测试 CLI
• 用于 web 交互和验证的浏览器

浏览器、日志、截图、测试框架让 Agent 能观察和分析自己的工作成果。于是就有了自验证循环：Agent 写代码 → 跑测试 → 看日志 → 修错误——全程不需要人。

模型不会自己配置执行环境。Agent 在哪里运行、有哪些工具、能访问什么、怎么验证工作——全部是 harness 层面的设计决策。

---

记忆与搜索——让 Agent 知道该知道的东西

期望行为： Agent 应该记住见过的东西，能访问训练截止日期之后的信息。

模型的知识只存在于两处：权重里，和当前上下文窗口里。不能直接编辑模型权重，所以"增加知识"的唯一途径是上下文注入。

记忆方面，文件系统再次扮演核心角色。harness 支持 AGENTS.md、CLAUDE.md 这类记忆文件——Agent 启动时自动注入。Agent 编辑这些文件后，后续会话加载更新版本。这构成了一种持续学习：Agent 在一个会话中学到的东西被持久化，下次自动注入。

训练截止日期意味着模型无法直接获取新信息，比如更新后的库版本。web 搜索和 MCP 工具（如 Context7）弥补这个缺口。Trivedy 认为 web 搜索和最新上下文查询是值得内置到 harness 里的原语。

---

对抗上下文腐烂

期望行为： Agent 的表现不应该随着工作推进而退化。

上下文腐烂（Context Rot）是一个现象：上下文窗口被填满，模型的推理能力和任务完成质量持续下降。Trivedy 把上下文称为"珍贵而稀缺的资源"，harness 必须有策略管理它。他的原话是：今天的 harness，很大程度上就是优质上下文工程的交付机制。

三种策略：

压缩（Compaction）。 对话接近上下文上限时怎么办？什么都不做，API 直接报错——不可接受。压缩的做法是智能卸载和总结已有上下文，结构化保留关键信息，给 Agent 腾出空间继续工作。

工具输出截断。 跑测试产出的几千行日志会噪音式占满上下文。超过阈值的输出只保留头尾 token，完整内容写入文件系统，模型需要时自己读。

Skills 与渐进式披露。 Agent 启动时在上下文里加载太多工具和 MCP 描述，性能还没开始干活就被拖垮了。Skills 的做法是按需动态加载，不在启动时全量注入。模型没得选，但 harness 可以通过这种模式保护它免受上下文腐烂的影响。

---

长周期自主执行——所有原语的组合

期望行为： Agent 能在长时间跨度上自主、正确地完成复杂工作。

自主软件创作是编程 Agent 的圣杯。但今天的模型有三个问题：过早停止、难以分解复杂问题、跨多个上下文窗口后失去连贯性。好的 harness 必须针对所有这三个失败模式做设计。

前面的原语在这里开始产生复合效应：

文件系统 + Git = 跨会话追踪。 Agent 在长任务中可能产出数百万 token。文件系统持久化记录工作成果，跨时间追踪。Git 让新 Agent 实例快速了解最新进度。多 Agent 协作时，文件系统充当共享账本。

Ralph Loop = 阻止提前退出。 一种 harness 模式：hook 拦截模型的退出尝试，在新上下文窗口重新注入原始 prompt，强迫 Agent 对照完成目标继续工作。能这么做是因为文件系统保存了状态——每次循环从干净上下文开始，从文件系统读取上一轮进度。

规划 + 自验证 = 方向不偏。 模型把目标分解成步骤，harness 通过 prompt 和"如何使用计划文件"的提示来支持。每完成一步，Agent 检查产出是否正确。harness 的 hook 可以跑预设测试套件，失败时把错误反馈给模型重试。验证让解决方案以测试为准，同时创造自我改进的反馈信号。

---

Harness 的未来

模型训练与 Harness 设计的耦合

Claude Code、Codex 这类产品是在模型和 harness 共同参与循环的环境下做 post-training 的。这让模型在 harness 设计者认为重要的地方——文件系统操作、bash 执行、规划、子 Agent 并行——越来越强。

反馈循环是：有用原语被发现 → 加入 harness → 训练下一代模型时使用 → 模型在特定 harness 下更强 → 发现新原语……

副作用是泛化能力下降。Trivedy 举了 Codex 5.3 的例子：prompt 指南里专门描述了 apply_patch 工具的编辑逻辑。改变这个工具逻辑，模型表现就变差。一个真正智能的模型，切换 patch 方法不该有困难——但带上 harness 做训练，模型会过拟合到特定 harness 模式。

但反过来，Trivedy 指出：这不意味着最好的 harness 就是模型训练时用的那个。 Terminal Bench 2.0 上，Opus 4.6 在 Claude Code 里的得分远低于它在其他 harness 里的表现。他的团队只改了 harness，就把自己的编程 Agent 从 Top 30 拉到 Top 5。

结论：针对特定任务优化 harness，能榨出巨大性能提升。 默认配置不一定是最好用的。

Harness 工程会消失吗

模型越来越强，今天在 harness 里的东西（规划、自验证、长周期连贯性）会被吸收进模型本身。那 harness 是不是越来越不重要？

Trivedy 的回答：prompt engineering 到今天仍然有价值，harness engineering 也是。 今天的 harness 在补模型能力的漏洞，但它也在做另一件事——围绕模型智能设计系统。配置得当的环境、正确的工具、持久状态、验证循环，让任何模型都更高效，和基础智能水平无关。

开放问题

• 上百个并行 Agent 同时操作同一个代码库，怎么不冲突？
• Agent 能不能分析自己的执行 trace，自动修复 harness 层面的失败？
• Harness 能不能在运行时根据任务动态装配工具和上下文，而不是启动前预配置？

---

※ PM 核心备忘：Harness 就是产品设计。

Agent 能访问什么工具 → 功能边界设计。 什么操作需要人审批 → 安全策略设计。 失败时怎么兜底 → 容错设计。 上下文怎么管理 → 体验设计。

Agent 产品的好坏，模型能力只占一半。另一半在你对 harness 的理解里。

本篇基于 LangChain 博客 The Anatomy of an Agent Harness（Vivek Trivedy, 2026.03.10）整理。