ARTICLE · 1235471
源码级拆解:11大生产级Agent Harness横向对比
Agent = Model + Harness，这是目前业界的普遍观点，模型提供智能，Harness 把智能变成真正可执行、可管理、可扩展的工作。
《Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents》从源码入手，分析了 Claude Code、Codex CLI、Gemini CLI、Mistral Vibe、OpenHands、Aider、Mini-SWE-Agent、Hermes、Pi、OpenCode 和 OpenClaw 共 11 个生产级编程Harness，以及统一管理多种 Agent Harness 的元 Harness Omnigent 。它关心的核心问题是：一个能持续行动的编程智能体Harness，由哪些部分组成？这些部分为什么会被设计成今天的样子？这个领域正在如何发展？
“Harness”这个词很容易被用乱，它不是大模型，不是模型权重，是除模型之外的全部运行时环境，把只会输出文本的大模型，变成能读写文件、执行命令、和真实代码仓库打交道的自动化助手。论文专门厘清 4 个极易混淆的概念：
第一，Harness ≠ Scaffold。
Scaffold 更像结构代码（循环、注册表、工具接口）；Harness 是最终交付给用户运行的完整运行时。例如 Mini-SWE-Agent 只有百行 Python 骨架，是 Scaffold；Claude Code 是带 UI、权限、插件生态的完整 Harness 产品。
第二，Harness ≠ Agent 开发框架。
LangChain、AutoGen、CrewAI 这类框架，是开发者导入用来写 Agent 的代码库；Harness 是一个可以直接在里面干活的运行程序。2025 年这条界线很清楚，2026 年后却在两边互相靠拢，这正是论文后半段“平台转向”的主题。
此外，论文调研的全部 11 个生产级 Harness，没有一个在核心运行逻辑导入 LangChain、LangGraph、AutoGen 这类通用 Agent 框架，全部手写异步循环。
第三，Harness ≠ 评测Harness。
SWE-bench 的评测Harness是包裹 Agent 用来跑测试任务的外壳；而我们说的 Agent Harness，是包裹大模型，让 Agent 去干活，二者方向完全相反。
第四，Harness ≠ Orchestrator。
编排器在多个 Harness 之上协调它们，自己不一定实现编辑循环。论文分析的 Omnigent 就是这样一个“元 Harness”：它把 Claude Code、Codex、OpenCode、Hermes、Pi、Cursor 等当成可互换组件，自己不做编辑循环。
论文提出，无论是最小 100 行的研究基线，还是百万行级的商业 CLI，都绕不开这 7 大模块，只是有的极简实现，有的功能拉满。
在模型推理和动作执行之间来回切换，主要如何反复推理、行动、接收反馈，何时继续或停止。所有编程 Agent 本质都是改良版ReAct 循环：思考→调用工具→观察结果，往复循环。论文划分出 3 种主流范式：
- 迭代动作-观察（绝大多数系统）：一轮思考，一批工具调用，拿到输出再继续。
极简版：Mini-SWE-Agent 就是一个简单 while True。 - 高级变体：OpenHands 采用事件溯源，每一步操作保存事件日志，可以回滚、分叉会话；Claude Code 做工具批处理，只读工具可以并行跑，修改文件工具强制串行避免冲突。
- 反思增强循环（代表 Aider）：执行修改之后，自动跑 lint、单元测试，如果报错，自动把错误返回大模型让它自我修正，相当于内置自我调试循环。
- 协调者-作者模式：主 Agent 生成多个子 Agent 分头干活，再汇总结果。Claude Code、Codex 原生支持，把任务拆成调研、实现、验证多个子角色。
新兴概念Loop Engineering（循环工程）不只写内部思考-执行循环，还要在外层增加校验循环，不用人干预，让 Agent 自己检查自己的输出，不合格就重新做。
负责组装请求，适配模型接口、缓存和推理能力。不同 Harness 对接模型分好几条路线：
- 厂商深度绑定：Claude Code 只对接 Anthropic，Codex 深度绑定 OpenAI。可以用上思考预算、专属缓存机制等专属特性，但切换别的模型很难。
- 厂商优先 + 通用兜底：Mistral Vibe 优先深度使用自家模型，同时兼容其他厂商 API。
- 基于通用封装库（LiteLLM）：OpenHands、Aider，可以对接上百种模型，但高级专属特性会丢失一部分。
- 手写多模型适配（Hermes、Pi、OpenCode）：不依赖第三方封装，自己手写各家 API 适配代码，把各家的缓存、思考模式全部兼容。这是 2026 年新崛起路线，要付出大量适配成本，但同时拿到全部高级能力。
提示词工程也发生了巨大变化，早期全部靠写一大段自然语言提示词约束模型行为。现在越来越多把规则移出提示词，放到配置、钩子、策略文件里。比如，禁止随便 git 提交、不要过度重构代码，早期写在 prompt 文本里；现在改成配置开关，不再靠说服大模型遵守。
几乎所有系统的系统提示词，都没有写 “遇到有害请求要拒绝” 的文字。安全拒绝完全交给底层大模型本身，Harness 不去重复做对齐工作。
定义智能体能做什么，操作如何校验与执行，是 Agent 真正改变代码的途径。
工具很多时，不全部塞进提示词占用 token。只放少量核心工具；其他工具只保留目录，需要的时候 Agent 主动搜索加载，Claude Code 首创了延迟加载工具（Deferred Tool Loading），现在已经广泛普及。
文件编辑是编程 Agent 最重要工具，流派分化很明显：
- 精确字符串匹配：传入旧文本，精确替换，要求文件里只能找到一处匹配。适合能力强的前沿大模型（Claude Code、Mistral Vibe 后期转向该方案）。缺点是代码稍微改动一点，匹配就失败。
- 模糊匹配链：多层容错，允许缩进、空白字符差异。OpenCode、Hermes，专门适配开源模型。
- 补丁 DSL：自定义补丁语法，类似 diff，Codex 采用。
- LLM 辅助修复：匹配失败之后，调用模型自动修复匹配片段（Gemini CLI）。
在工具执行沙箱方面，Codex 投入巨大，在 Linux/macOS/Windows 三平台实现操作系统级沙箱隔离；但也有 Hermes、OpenCode 这种百万行级大型 Agent，不内置操作系统沙箱，把隔离交给外部容器，内部靠语法解析 + 权限策略做防护。沙箱是可选工程投入，不是体量必然产物。
管理上下文窗口，跨轮次、跨会话保存知识。
长会话跑久了对话越来越长，超出模型上下文窗口，是编程 Agent 的头号痛点。主流方案是阈值触发 LLM 压缩，当 token 快满时，调用大模型把历史对话总结，保留最近原始消息，旧内容换成摘要。十一个系统里面有七个采用这套模式，但实现细节千差万别。
跨会话长期记忆出现 4 种治理模式：
- Agent 自主维护记忆（Codex）：后台子 Agent 自动从会话抽取知识点，存入本地文件，不需要人审批。
- 人工审核闸门（Gemini CLI）：Agent 生成记忆草稿，放到收件箱，必须人确认之后才生效。
- 模型直接编辑限定大小 Markdown 文件（Hermes、Claude Code），文件大小强制封顶，保护提示词缓存。
- 文件约定（AGENTS.md/ CLAUDE.md）：项目目录下放特殊 md 文件，Agent 自动读取，保存项目规则。
论文有非常重要的观测：没有任何一个编程 Harness，用向量数据库 RAG 读取源代码！大家不用 Embedding 检索代码库，全部用 ripgrep、glob、tree-sitter 做确定性搜索。因为代码变化极快，向量索引很容易过时；代码的路径、语法结构，传统命令行搜索效果反而更好。向量检索仅少量系统用于聊天历史记忆，绝不用于源代码检索。
决定什么能跑、什么要问、什么禁止，以及如何隔离执行。目前安全方案主要分两条路线：
- 操作系统沙箱路线：进程隔离、文件系统读写限制、网络阻断。Codex 做的最完整，Gemini CLI 紧随其后。
- 策略即代码路线：不靠 OS 隔离，解析 shell 命令、文件路径，通过规则判断允许 / 拒绝。Hermes、OpenCode 代表。哪怕开启 “全部允许（YOLO）” 模式，依然保留一套高危命令黑名单，防止毁灭性操作。
很多系统设计多档位模式：只读计划模式、默认询问模式、自动编辑模式、完全放任 YOLO 模式。在计划模式 Agent 只能读代码，输出修改方案，不会改动任何文件，等待用户批准。
生成并协调子智能体，连接其他智能体。
论文总结 6 种多 Agent 模式：从完全单 Agent，到顺序委派、并行子会话、分层线程树、递归组合、注册表协议调用。
- Claude Code 支持递归组合，子 Agent 完整复制父 Agent 上下文缓存，节省大量 token 开销。
- Gemini CLI 独有的 A2A 协议，可以跨机器调用别的 Agent。
- 有意思：绝大多数系统内部自己的子 Agent，都不用外部标准协议，直接进程内调用；但是对外给 IDE、给元驾驭层调用的时候，统一使用 ACP 协议（Agent Client Protocol）。
ACP 本来是为 IDE 对接 Agent 设计的协议，现在进化成通用标准，OpenHands 甚至可以把 Claude Code、Codex 当成可插拔后端，切换底层 Agent，上层业务代码不变。
让用户和生态添加能力：配置、hooks、skills、plugins、MCP。目前主要有两大扩展标准：
- Skills（技能，SKILL.md）：9/11 系统支持。一个文件夹放 SKILL.md，写好工作流程、规则、脚本。是文件为基础的能力包。支持延迟加载，只在项目匹配条件才激活，还有技能市场、安全扫描、信任分级，甚至可以让 Agent 自己写新技能。
- MCP（Model Context Protocol）：8/11 系统支持。进程间协议，用来对接外部程序、数据库。
在其选取的 11 个系统中，9 个具有 Skills 机制，8 个支持 MCP。Pi 明确拒绝 MCP，只靠技能 + 命令行工具做扩展。不过多数情况下，二者可以互补：MCP 对接外部程序，Skills 封装工作流业务逻辑。
除了上述7个子系统外，还有两个贯穿多个子系统的基础部分：一是用户和程序访问它的接口，例如终端、IDE、SDK 或 HTTP 服务；二是保存会话、恢复任务和创建分支的会话存储。
拆分的价值在于，它让我们能够具体讨论“智能体哪里出了问题”。
一个系统频繁忘记约束，可能是上下文管理的问题；不断改错文件，可能是编辑工具契约的问题；明明没有验证却宣布完成，可能是停止条件的问题。把所有问题都归结为“模型不够聪明”，会错过许多能够通过工程手段修复的环节。
当一个编程智能体只有终端输入框和几个工具时，它很像一款开发工具。
当它进一步拥有 SDK、服务接口、插件市场、技能仓库、企业策略、持久会话和多种客户端时，它开始承载其他人的工作方式和扩展能力。
这就是论文的中心论点：Harness 正从工具演变为平台。
对比 2026 年 4 月版本和 7 月版本源码，短短三个月，整个行业发生明显变化：
- 从独立探索，走向互相模仿：不再是各自闭门造车。Codex 照搬 Claude Code 的钩子事件命名；OpenHands 读取 Claude Code 插件格式；很多代码注释直接写 “借鉴 OpenCode 的匹配算法”。优秀设计扩散速度极快。
- 策略从提示词里搬去配置：不再靠大模型读懂文字规则。把行为约束迁移到配置、钩子、策略文件。模型越来越强，很多旧提示词禁令直接删掉。
- Harness 本身变成 SDK 库。过去 Harness 只是终端 CLI 工具；现在厂商把 Harness 内核打包成可导入 SDK。你可以在自己代码里直接 import Claude-Agent-SDK、openai-codex SDK。
- 框架和 Harness 正在融合：过去 LangChain 这类框架和 Harness 完全割裂。现在 LangChain 自己开发 Deep Agents，直接做成一套完整 Harness；另一边 Harness 输出 SDK，充当新一代 Agent 开发库。于是出现论文提出的论断：Harness 取代传统 Agent 框架。
之前大家争论的是“开发 Agent 选 LangChain 还是 AutoGen？” 现在新问题变成了“我该基于哪个 Harness SDK 二次开发？”
论文还以 Omnigent 为例，讨论了平台之上的元编排层。它把Claude Code、Codex、Cursor、OpenCode、Hermes、Pi、Goose、Qwen、Kimi、Kiro、Copilot、Antigravity 等不同厂商的 Harness 接到统一接口下，在上层管理任务分发、策略、会话和跨系统协作，而把具体的代码读取与编辑循环留给底层系统。
这种结构使一个任务能够由不同 Harness 分别承担实现、检查或评审。
不过，统一接口不会自动抹平差异。各系统的权限机制、会话结构和特殊功能仍然不同，适配层必须承认这些差异。沙箱、预算和策略执行也可能在多个层级重复建设。
因此，“平台化”是作者对架构与生态变化的解释，并非已经通过实验验证的最终行业格局。它的说服力主要来自一组共同出现的现象：扩展接口趋同、能力包开始分发、会话数据变得重要，以及完整执行系统被当成可组合组件使用。
论文最后把分析压缩成 18 条设计建议，每条都锚定一个观察和一个实现系统。
- 起步先用简单线性 while 循环，不要一上来搞复杂架构，只有需要多种独立策略时，再引入中间件管道。Mini-SWE-Agent 百行循环已经拿到不错评测成绩。
- 如果你做多模型产品，不要完全依赖 LiteLLM，要预算成本做各厂商的适配层，才能拿到缓存、高级推理能力。
- 工具不要一开始就堆一大堆。起步只实现 bash、读文件、写文件、搜索替换；遇到真实故障再新增工具。工具超过 15 个，一定要做延迟加载。
- 文件编辑：强模型用精确字符串匹配；开源弱模型采用多层模糊匹配。尽量避免行号定位匹配，模型很容易搞错行号。
- 自动发现 AGENTS.md/CLAUDE.md 这类层级上下文文件，兼容多家格式。
- 实现上下文阈值压缩，压缩后保留一部分原始对话，不要全部摘要。
- 不要为代码库做向量 RAG。优先用 ripgrep、glob、tree-sitter 确定性检索。
- 面向开发者自用工具：提供 Plan/Default/YOLO 三级权限模式。面向企业：必须操作系统沙箱 + 策略即代码。
- 安全规则写成配置/策略文件，不要写死在业务代码；就算全开放任模式，也要保留高危命令底线黑名单。
- 优先做单 Agent；只有明确需要大规模并行调研场景，再上多子 Agent。
- 实现 ACP 服务端，让你的 Agent 可以被 IDE、元驾驭层调用；内部子 Agent 优先进程内调用。
- 扩展优先使用 Skills 技能包；对接外部软件再用 MCP。第三方技能包要做信任扫描。
- 不要把 LangChain/LangGraph/AutoGen 作为运行时核心。工业生产 Harness 全部手写原生循环。
- 不要把每个 API 都简单包装成工具，要合并、抽象高层工具。
- 不用过度做 “卡死循环检测”，但是一定要加上步数、时长、连续错误的基础上限。
论文很坦率地列了局限：分析基于源码阅读，不是运行时测量；Claude Code 的分析依赖 2026 年 3 月流传的源码快照，可复现性是最弱环节；Anthropic 指南到观察的映射是提示性的，不能单独建立因果；没有让 11 个系统在同一任务集上跑，那会贵一个数量级。
但这些局限不影响论文的核心判断：编程 Harness 在 2026 年上半年完成了平台转向。你认为未来一年，Harness 会整合成少数主导平台、碎片化成可互操作运行时，还是被上层商品化呢？
论文地址：https://arxiv.org/abs/2609.00006
【261023】
