📐 Harness 工程 · 中文翻译

15 讨论

15.1 Anthropic 有效智能体系列作为实证验证

2024 年 12 月至 2025 年 9 月间,Anthropic 发布了四篇工程文章,就智能体设计给出规定性指导:Building Effective Agents [16]、Effective Context Engineering for AI Agents [19]、Writing Effective Tools for AI Agents [18],以及案例研究 How We Built Our Multi-Agent Research System [17]。 四篇文章共同浮现出一套连贯的设计哲学:手写循环优先于框架抽象,一小组高信号工具优先于包罗万象的 API,即时性结构检索优先于预索引 RAG,编排者-工作者模式优先于扁平单体,对智能体规划的透明呈现,以及把显式的上下文预算当作工程纪律。

11 个独立开发的系统(其中只有 Claude Code 来自 Anthropic)与这些处方逐条吻合:

  • •

    “非必要不使用框架” [16]:11 个系统中 0 个在智能体运行时使用 LangChain、LangGraph、AutoGen、CrewAI、ADK、LlamaIndex、Pydantic AI、Genkit 或 Semantic Kernel(观察 13.2)。

  • •

    “ACI 与 HCI 同等重要” [16](该概念源于此文;Aizawa 等人 [18] 以实用工具建议加以扩展)与“少数经过深思的工具” [18]:Aider 的 13 种多态编辑格式、Claude Code 的工具延迟加载、Codex 的自定义补丁格式、Hermes 的九策略编辑链、OpenCode 的按模型条件切换工具表面,都是重量级的 ACI 投入(观察 8.4)。

  • •

    “JIT 优于 RAG” [19]:11 个系统中 0 个对代码使用向量嵌入;全部使用 grep、tree-sitter、glob 与文件系统,外加自动发现的 Markdown 上下文文件(观察 13.2)。

  • •

    “可并行、跨上下文任务用编排者-工作者” [17]:出现在 Claude Code(递归组合)、Codex(带扇出的线程树)、Gemini CLI(注册表 + 会话协议)、Mistral Vibe(task 工具)、OpenHands(并行委派)、Hermes(编排者角色 + 集群)与 OpenCode(并发子会话)中(观察 11.10)。

  • •

    “子智能体派生前把计划存入外部记忆” [17]:Claude Code 的 CLAUDE.md、Gemini CLI 的计划文件与 MEMORY.md 项目索引、Codex 的 AGENTS.md 层级与其智能体自维护的记忆根。

  • •

    长程任务的“压缩 + 结构化笔记 + 子智能体” [19]:全部四个厂商原生系统——以及全部三个新成员——三者齐备。

  • •

    “多智能体系统比聊天多耗约 ∼\sim15×\times token” [17](对比的是单次聊天基线,而非单智能体管线):这正是 Claude Code 的提示词缓存共享分叉机制、Hermes 的共享缓存后台分叉与只回摘要、Gemini CLI 的思考剥离(记录响应时把扩展思考文本排除在持久化历史之外,使其永不重入缓存)的动机。没有这些优化,成本将不可承受。

这份指导中有一处张力应当点明。 Hadfield 等人 [17] 提醒,“多数编码任务中真正可并行的任务比研究少,而 LLM 智能体在实时协调与委派其他智能体方面还不擅长”。 尽管如此,本研究 11 个系统中的 7 个(算上 OpenClaw 的协议层变体则是 8 个)恰恰为编码工作流实现了协调者-工作者模式。 细看之下,观察到的模式大多用于广度优先的探索阶段(并行的代码库研究)而非并行实现——把分析单元从系统整体转移到单个工作流阶段后,这与 Hadfield 等人的告诫一致。

15.2 极简主义论证

Mini-SWE-Agent 用极简脚手架与单个 bash 工具取得有竞争力的自报基准成绩(SWE-Bench Verified 74%+),削弱了“丰富的工具生态必不可少”的假设。 这一发现呼应 CodeAct [3] 的论证:可执行代码涵盖离散的工具动作。 仅就基准评测而言,生产级系统中的大部分脚手架结果是开销。

反方论证是:基准只度量价值主张中狭窄的一截。 生产级系统(Claude Code、Codex、Gemini CLI、Mistral Vibe、OpenHands)在基准不奖励的东西上重金投入:

  • •

    安全:防止对用户代码库的破坏性动作。

  • •

    用户体验:流式响应、丰富的终端 UI、进度跟踪。

  • •

    可扩展性:支持自定义工具、MCP 服务器、插件。

  • •

    稳健性:处理边缘情况、卡死检测、错误恢复。

  • •

    成本管理:提示词缓存、上下文压缩、模型选择。

这些关切对 SWE-Bench 不可见,却对生产采用至关重要。

15.3 作为架构的安全

安全是语料库分布最散的维度。 Codex 采取纵深防御:操作系统级沙箱加策略即代码加审批工作流,安全从一开始就被当作首要工程关切而非事后追加。 Gemini CLI 在光谱上处于相近但更轻的位置:一个跨平台沙箱(复用操作系统二进制)加四种显式审批模式(PLAN/DEFAULT/AUTO_EDIT/YOLO)与分模式 TOML 策略。 Claude Code 的三层系统(Hook →\to 分类器 →\to 对话框)介于纯自动化与人工监督之间。 Mistral Vibe 的权限作用域层级(命令/文件/URL 模式加智能体档案门控)比 Aider 的二元确认更细粒度,但没有操作系统级强制。 OpenHands 的可插拔 SecurityAnalyzer 框架让基于规则与基于 LLM 的分析可以组合。

4 月版曾观察到语料库最大的两个系统(Codex,当时 62.1 万行;Gemini CLI,56.8 万行)恰好也是它的两个跨平台沙箱实现者,并把这种相关性读成结构性的。 扩大的语料库证伪了结构性解读,同时保留了成本论断:Hermes 与 OpenCode 体量相当,却零操作系统级隔离,把安全预算分别花在内容型威胁与权限粒度上(观察 10.2)。 仍然成立的是:凡构建了原生沙箱之处,它都是 Harness 中代码成本最高的组件之一——Codex 把 bubblewrap vendor 进自己的代码树,元 Harness 则在高一层把整张账单又付了一遍(第 14.4 节)。 Aider 与 Mini-SWE-Agent 的极简安全表面对其目标用例(用户可信的开发者工具)站得住脚,但限制了它们在企业或自动化部署场景的适用性。

15.4 模型-智能体协同设计论点

智能体脚手架与基础模型之间的耦合是双向的。

模型塑造智能体。

Codex 的按模型提示词——如今是服务端下发的目录数据,覆盖从 GPT-5.2 到 5.6 家族,带逐模型的工具模式与多智能体工具世代——明确表明脚手架设计必须随模型能力演化,而且供应商打算不经客户端发版就驱动这种演化。 Claude Code 的扩展思考集成(预算 token、思考块)利用了 Claude 专属的推理特性。 Gemini CLI 的 ModelRouterService 把模型选择本身当作运行时调度决策,把每个请求派给最便宜的够用 Gemini 变体——并在一个季度内消化了一整次模型代际切换(默认 2.5 →\to 3.x);同一思想在 Hybrid LLM [84]、RouteLLM [83] 与 FrugalGPT 级联 [82] 中被正式研究。 Mistral Vibe 的 reasoning_effort 映射与 ThinkChunk 解析利用了 Mistral 的推理枚举。 Aider 的模型感知编辑格式选择让编辑策略适配每个模型的输出模式;OpenCode 在其工具注册表中重新推导出同一思想(GPT 家族模型拿到补丁 DSL;其他拿字符串替换),还有它的九提示词模型家族矩阵。 OpenHands 出货模型专属的工具预设(default、gemini、gpt5、planning)——协同设计甚至抵达了一个多供应商系统的工具表面。

智能体塑造模型用法。

Claude Code 的工具延迟加载减少提示词 token,改变了模型的有效上下文窗口。 Claude Code 的提示词缓存边界拆分系统提示词以最大化缓存命中,把提示词结构既围绕逻辑组织、也围绕缓存经济学来设计;Gim 等人 [81] 为这一隐含假设的模块化注意力复用策略提供了系统层依据。 Gemini CLI 在响应记录时把扩展思考痕迹挡在持久化历史之外,使其永不泄漏进未来的缓存查找(并在认证切换时剥离思考签名)。 Mistral Vibe 的中间件管线让逐轮 token 预算策略与循环体正交组合。 OpenHands 的凝聚器选择性遗忘事件,塑造模型“记得什么”。

意涵。

四个厂商原生系统(Claude Code、Codex、Gemini CLI、Mistral Vibe)可以同时优化耦合的两侧,让提示词、工具与特性随模型更新齐步演进——Codex 最字面化,经其服务端下发的模型目录。 4 月版曾推断多供应商系统因此必须按最低公分母设计;扩大的语料库表明那个推断下得太重。 Hermes、Pi 与 OpenCode 证明:从多供应商基底出发,只要刻意且集中地支付逐供应商的条件代码成本(观察 7.1)——逐模型的怪癖元数据、供应商档案插件、转换矩阵——厂商原生优化菜单的全部条目都可触及。 多供应商系统无法复制的是更新循环:只有厂商能在模型发布当天在服务端重新调校脚手架行为。 Mistral Vibe 的“供应商优先 + 通用回退”设计与自研传输路线都仍是可行的中间路径,区别在于维护负担由谁背负。

15.5 脚手架-能力前沿(一个指导性直觉)

我们以一个指导性直觉而非正式假说收尾:在固定的任务分布与固定的模型下,脚手架复杂度与观察到的任务成功率似乎描出一条大致凹形的曲线。 一个智能体根本无法运作的地板之下(没有循环、没有工具、没有记忆、没有结果),一段早期陡峭增益区——加入一小组结构元素(bash 工具、读写工具、Markdown 上下文文件)即可快速提升成功率——以及一个边际收益递减的平台期:进一步的脚手架工作在运维关切(安全、UX、可扩展性)上兑现,而不在完成率上。 我们把这幅图景称为脚手架-能力前沿,把它当作待检验的假说,而非设计空间已被证明的性质。

文献中两个独立结果与这幅图景一致但不构成确认。 Mini-SWE-Agent 用刻意极简的脚手架在 SWE-Bench Verified 上报告约 ∼\sim74%+,这提示:对前沿模型上的 SWE-Bench 式任务而言,地板已经远低于多数生产级脚手架。 Lin 等人 [85] 报告他们的智能体 Harness 工程(AHE)系统——从与 Mini-SWE-Agent 相当的纯 bash 种子出发,用可观测性驱动的反馈自动演化 Harness——在 SWE-Bench Verified 上达到 71.9%。 其组件级消融发现结构性的 Harness 元素承载了改进(工具 +3.3+3.3 个百分点,中间件 +2.2+2.2 个百分点,长期记忆 +5.6+5.6 个百分点),而系统提示词本身倒退了性能(−2.3-2.3 个百分点);演化出的 Harness 还可跨四个模型家族迁移。 我们把这读作启发性证据:结构性的脚手架比散文级的提示词策略更可移植——与我们在架构(而非权重)层面讨论的模型-智能体协同设计一致。

一个可操作的定义至少需要:固定的任务分布 TT、固定的模型 MM、一个脚手架复杂度度量(行数、工具数量、结构特性数量,或某种加权组合),以及目标成功率 pp。 “针对 (T,M,p)(T,M,p) 的最小可用脚手架”将是脚手架复杂度值的下包络,其在 MM 上对 TT 的经验成功率超过 pp。 我们在这里不产出这样的测量。 那需要一项受控的跨系统运行研究,本文刻意回避(效度威胁见第 15 节)。 我们把脚手架-能力前沿标记为后续实证工作的一个问题,并指出相关的最小值几乎必然随以下因素变化:

  • •

    任务复杂度:多文件重构可能比单文件 bug 修复需要更精巧的工具支持。

  • •

    安全要求:企业部署要求的脚手架是基准不度量的。

  • •

    交互模式:长程交互会话受益于短基准运行不需要的记忆管理。

15.6 效度威胁

这种形态的研究有真实的局限,值得把它们说清楚。

本分析立足于源码阅读,而非运行时测量。我们不声称知道这些系统跑得多快;我们声称知道它们结构如何。文中报告基准数字之处,均来自系统自己的文档,而小数点后最后一位不是有趣的部分。

架构比较所依据的定性打分涉及判断抉择。我们尝试把每个分数锚定在具体的实现细节上,并欢迎任何阅读同样代码库而打分不同的人提出异议。我们刻意避免行号引用,并把所有代码规模数字标注到 2026 年 7 月的固定版本:语料库中的每个系统都在活跃开发,更精细的精度在读到论文时就会过时。所有版本都固定到精确的发布标签与 commit(表 3),2026 年 4 月快照被保留用于第 14.5 节的纵向比较,而且——那个季度直接教给我们的教训——我们如今区分清单式论断(标注日期)与结构式论断(预期耐久)。4 月版的三条观察在本版依据新证据得到实质修订;修订就地整合并在出现处标注。

在可复现性上,Claude Code 分析是最弱的一环。它依据的是 2026 年 3 月一份公开流传的源码快照而非官方发布,交付的二进制此后已演化甚多(我们跟踪其变更日志级别的演化,但不把变更日志的声明当作源码证据)。架构层面的论断仍应可对公开的 claude-agent-sdk 与交付二进制的行为加以检验,但我们承认与其他十个系统的不对称——后者的源码树从公开 Git 历史即可轻易重新导出。

框架缺席的发现(观察 13.2)很强,但在结构上保守。我们检查了依赖清单并在三种语言中做导入 grep——两轮,间隔三个月,覆盖包括元 Harness 在内的 12 棵代码树;我们没有追踪内部分叉、经动态 importlib/require 加载的插件或转译的分发产物。原则上,一家公司可以经我们未检查的代码路径在生产级 SWE 智能体内部使用 LangChain。我们会惊讶,但不至于震惊。

Anthropic 指导到观察的映射(观察 13.2)有启发性,但本身不构成因果。恰当的后续是对各厂商工程师的访谈研究;我们没有做。

我们还对每个系统独立比较,而没有把 11 个系统放到共享任务集上运行。一项正面对比的执行研究能把部分定性打分变成可测量的量。它也将付出比本文高一个数量级的成本,我们选择了可控的范围。