各个AI公司都在玩的Harness 架构：Harness架构深度解析

Harness 架构深度解析为什么 AI 智能体的未来不是框架而是「运行壳」TL;DR · 三分钟看懂这篇文章•当 Claude Code、Cursor、Codex、Windsurf 四款产品独立演化出几乎相同的内部架构时一种叫做 Harness运行壳的新形态浮出水面。•Harness ≠ Framework。框架是设计师写给开发者的产物Harness 是工程师写给模型的产物。•一个完整的 Harness 由五大子系统构成迭代主循环、上下文管理器、工具注册表、权限层、子代理与技能。•Harness Engineering 正在替代 Prompt Engineering成为构建生产级 AI Agent 的主流工程哲学。•文末附 50 行可运行的最小 Harness 实现 一份开发者自测清单。当 Claude Code、Cursor、Codex、Windsurf 这四款产品在毫无沟通的前提下独立演化出几乎相同的内部架构时这件事就不可能再是巧合了。它指向了一个结论——在当前这个阶段解决真实任务的 AI 智能体正在收敛到同一种稳定形态。这种形态有一个新的名字Harness。一、Harness 不是 Framework过去两年里构建 AI 智能体的主流方式是「框架」——LangChain、AutoGen、CrewAI 等等。框架的逻辑是先把智能体所需的所有能力抽象成组件Agent、Tool、Memory、Planner、Executor……再让开发者像搭积木一样组装出自己的智能体。这是一种自上而下的设计哲学先有抽象再有应用。Harness 走的是完全相反的路径。Harness 是从真实的 Coding Agent 产品里长出来的架构。Claude Code、Cursor、Codex、Windsurf 这些产品从一开始就没有把「构建通用智能体框架」当作目标。它们只想解决一个非常具体的问题让大模型在真实的代码仓库里写出能跑的代码。在解决这个问题的过程中它们各自摸索出了一套近乎相同的内部架构。框架交付积木Harness 直接交付一个能运行的系统。框架要求开发者「先理解抽象再组装应用」Harness 默认架构是固定的组件已经连好开箱即用。这个区别看似细微实际后果巨大•框架的失败模式当智能体出错时你需要去翻文档搞清楚是哪个组件的抽象出了问题是不是应该换一种 Chain 的写法。错误是「设计问题」。•Harness 的失败模式架构固定所以失败一定来自某个具体子系统——上下文压缩出问题、工具调用拒绝、权限层误判。错误是「工程问题」可以被永久修复。这是一种范式转移。它意味着构建智能体的工作正在从「设计抽象」转向「工程实现」。二、Harness 的五大核心子系统一个完整的 Harness本质上是一个包裹在大模型之外的运行时系统。它负责管理 LLM 与真实世界之间交互的全部生命周期。剥开外壳里面永远是这五块2.1 迭代主循环Iteration Loop最内层是一个极其朴素的 while 循环。所有 Harness 不管包装得多复杂核心都是这几行代码while not done:response model(context)if response.tool_calls:results execute(response.tool_calls)context.append(results)else:done True这个循环的本质是模型生成 → 调用工具 → 把工具结果写回上下文 → 再次生成。听起来简单到不值得讨论但所有 Harness 都收敛到这个结构恰恰说明它已经被证明是当前阶段最稳定的智能体执行模型。早期那些精心设计的 Plan-and-Execute、Tree-of-Thoughts、Reflection 等复杂控制流在工程实践中绝大多数情况下都不如这个朴素的循环跑得稳。原因也很现实循环越简单错误就越容易定位模型一旦升级简单循环能立刻拿到收益而复杂控制流反而会因为模型变强而显得多余。踩坑案例 · Plan-and-Execute 的反噬某甲曾经在自研 Agent 里实现过 Plan-and-Execute 架构——先让模型拆 plan再 step-by-step 执行。底层模型从 GPT-4 Turbo 升级到 GPT-4o 之后原本「拆得很烂」的 plan 反而成了执行瓶颈新模型在 while 循环里能自己规划下一步旧的 plan 框架反而是绊脚石。最后把整个 plan 模块下线成功率反而升了 12%。2.2 上下文管理器Context Manager上下文窗口是大模型最稀缺的资源。一个长会话很容易把窗口塞满而且越往后模型对前文的注意力越差。上下文管理器解决三件事•压缩历史把旧的对话回合压缩成摘要节点腾出空间给当前任务。•提取记忆把对话中产生的关键事实项目结构、用户偏好、约束条件写入可重读的记忆文件例如 Claude Code 的 CLAUDE.md、各类智能体常用的 AGENTS.md。•按需注入每一轮只把这一步真正需要的上下文送进模型而不是把所有历史一股脑塞进去。Harness 的关键不在于它包含了多少能力而在于它每一步选择「不给模型看什么」的能力。注意力管理才是真正的护城河。踩坑案例 · 200K 上下文照样幻觉乙曾在一个 200K 上下文窗口的 Agent 上偷懒把全仓 grep 的结果约 80K tokens一股脑塞进上下文。结果模型开始幻觉文件路径——它「记得」有一个 src/utils/auth.ts但仓库里根本不存在那个文件。把搜索结果在送进模型之前做一次摘要TopK 截断路径幻觉率从 23% 降到 2%。上下文越大越要节制。2.3 工具注册表Tool Registry工具注册表声明了智能体能做什么。它本身是个相对静态的清单——bash 执行、文件读写、网页搜索、对接 MCP Server 等等。但真正决定一个 Harness 强弱的是工具接口设计的质量。Anthropic 在工程博客里反复强调一句话工具设计就是智能体的 UX。一个工具的命名是否清晰、参数是否正交、错误信息是否能让模型自我纠正会直接决定智能体的成功率。一个糟糕的工具接口可能让 GPT-5 也表现得像 GPT-3.5反过来一组打磨精良的工具能让中等模型表现出意料之外的能力。这也是为什么 MCPModel Context Protocol这两年迅速崛起它标准化了工具的注册与调用方式让 Harness 可以即插即用地接入外部能力而不必为每一个集成都重写一遍胶水代码。踩坑案例 · 结构化错误返回让自愈率翻倍丙有一个 run_sql 工具最初返回的错误是英文短句syntax error near FROM。Agent 自我修复成功率约 31%。把返回值改成结构化 JSON含 error_code / hint / suggested_fix 三字段并对常见错误预置可操作建议之后同一组测试任务的自我修复成功率升到 78%。「工具设计就是 Agent 的 UX」不是修辞是 KPI。2.4 权限层Permission Layer工具注册表回答「能做什么」权限层回答「被允许做什么」。这是两个完全不同的问题必须解耦。一个成熟的权限层至少有三档判断•allow低风险操作直接放行例如只读文件、查询接口。•ask中等风险操作弹出确认对话框等待用户批准。•deny高风险操作如 rm -rf、发送邮件、调用付费 API直接拦截强制走结构化确认流程。Anthropic 在 Claude Code 的设计中特别强调了一点不要用自然语言权限提示。也就是说不要靠系统提示词里写一句「请不要删除用户文件」来约束模型——这种约束对一个有 tool call 能力的智能体来说几乎等于零。权限必须由 Harness 外层的结构化代码强制执行而不是交给模型自律。踩坑案例 · 提示词权限被一行 bash 绕过丁早期用系统提示词写「不要使用 rm -rf」。结果模型在清理临时文件时把命令拆成了 rm 与 -rf /tmp/xxx 两段绕过了对字符串的 naive 匹配。从那以后所有破坏性命令都走结构化白名单 参数解析禁止在 prompt 层做安全约束。这是教训不是经验。2.5 子代理与技能系统Sub-agents Skills当一个任务过于复杂、需要的上下文过多时Harness 会派生子代理。子代理拥有独立的上下文窗口独立完成一个子任务最后只把结构化的结论回传给主代理。这种「上下文隔离」让主线程的注意力保持干净避免被搜索过程、试错过程的噪声污染。技能Skills则是另一个维度的扩展——它本质上是一组可以被模型按需读取的、写给模型自己看的说明书。一个技能就是一个 SKILL.md 文件告诉模型「这类任务应该怎么做」「这个工具应该怎么用」。技能让 Harness 能够在不重新训练模型的情况下持续扩展它的能力边界。子代理处理「广度问题」——任务太大分而治之技能处理「深度问题」——任务太专提供说明书。两者加起来构成了 Harness 的可扩展性基底。踩坑案例 · 5 个子代理并行做 impact analysis一个 80 步的重构任务主线程很容易在第 30 步左右就被搜索/试错噪声污染——它开始重复犯之前犯过的错误。我们派生 5 个子代理并行做 impact analysis每个子代理只回传约 100 字的结构化结论。主线程的上下文从拥挤的 120K 降到清爽的 18K错误重复率直接归零。三、四款产品的架构收敛Claude Code、Cursor、Codex、Windsurf 是四款分别由 Anthropic、Anysphere、OpenAI、Codeium 推出的产品。它们的团队没有共享过代码也没有共享过设计文档。但当我们把它们的内部架构拆开对比会发现惊人的一致Claude Code · Anthropic· 迭代循环单循环 tool call· 上下文管理CLAUDE.md 记忆 自动压缩· 工具与权限MCP 工具集 三级权限· 子代理与记忆Task 子代理 SkillsCursor · Anysphere· 迭代循环Composer / Agent 循环· 上下文管理Codebase 索引 Rules 文件· 工具与权限内置工具集 操作确认· 子代理与记忆Background Agent 规则Codex · OpenAI· 迭代循环持续 tool-calling 循环· 上下文管理仓库快照 会话压缩· 工具与权限Sandbox 工具 用户授权· 子代理与记忆并行任务 配置文件Windsurf · Codeium· 迭代循环Cascade 循环· 上下文管理代码库感知 Memories· 工具与权限工具调用 风险分级· 子代理与记忆Flows Rules这种收敛不是抄袭而是工程现实的必然结果。当你认真去构建一个能在真实代码库里干活的智能体时你会一个一个发现•上下文不够用——必须压缩•工具调用偶尔会做危险的事——必须有权限层•长任务会污染主线程——必须有子代理•模型不知道某个项目的约定——必须有记忆文件每一个子系统都不是设计出来的而是被生产环境的失败逼出来的。这是 Harness 区别于框架的最深刻特征框架是「设计师写给开发者」的产物Harness 是「工程师写给模型」的产物。前者优化人的理解成本后者优化模型的成功率。这也意味着未来出现的新一批 Coding Agent 产品几乎一定会继续在这五个子系统上做加法——而不是减法。Harness 的形态会被工具的多样性、模型的能力增强进一步丰富但不会被颠覆。四、Harness Engineering 是一种新的工程哲学围绕 Harness 的工程实践正在催生一门新的学科Harness Engineering运行壳工程。它的核心信条只有一句话把每一次智能体失败当作工程问题去永久修复而不是当作提示词问题去临时重试。这一句话杀死了过去两年「靠改提示词解决一切」的工作方式。当一个智能体在生产环境失败时提示词工程师的反应是「换个写法再试一次」Harness 工程师的反应是「这是哪个子系统的边界没设好我应该加一个工具、调一个权限规则、还是写一个新的技能」业内逐渐被反复引用的一种总结把 Harness Engineering 归纳为三个互锁的系统•上下文工程Context Engineering——精心策划「智能体在每一步应该知道什么」。•架构约束Architectural Constraints——用确定性的 linter、结构性测试、CI 检查来约束智能体的输出。•熵管理Entropy Management——定期跑维护型智能体扫描文档漂移、代码腐烂并提出修复建议。还有一个被反复传播的概念「Humans on the Loop」而非「Humans in the Loop」。人不应该被放进智能体的每一步中审查输出而是应该站在循环之上设计和维护这套系统本身。这是 Harness Engineering 与传统 MLOps 最大的区别。MLOps 关心模型的训练、部署、监控Harness Engineering 关心模型之外的全部工程——它默认模型本身是黑盒是可替换的零件。五、对开发者的三条启示启示一不要再造框架要造 Harness如果你今天还在设计一个「让用户组装智能体」的框架请重新审视一下你的目标用户。框架的用户是工程师但 Harness 的「用户」其实是大模型本身。模型不会读你的文档不会理解你的抽象层次——它只会按照你提供的工具、上下文、提示去尝试解决问题。设计 Harness本质上是在为一个不会反馈意见的「用户」做产品设计。启示二模型可替换Harness 不可替换把所有业务逻辑、工具集成、记忆机制都沉淀进 Harness。当下一代模型发布时你只需要换一行 model_id剩下的代码不动——这是 Harness 架构带给团队的最大杠杆。反过来如果你把太多逻辑写进了提示词那就意味着每次换模型都要重写提示词每次都从零调试。启示三工具设计就是 Agent 的 UXHarness 的成败有相当大一部分取决于工具接口的质量——命名要清晰参数要正交错误信息要能让模型自我纠正返回值要结构化。一个糟糕的工具集会让最强的模型也表现失常一组精心设计的工具能让中等模型展现出意外的能力。这是当下 AI 产品工程里最被低估、也回报最丰厚的工作。六、动手50 行 Python 跑通一个最小 Harness讲了这么多概念不如直接跑一遍。下面这段代码就是一个最小 Harness 的骨架——单循环、单工具、最简单的 deny 规则。把它放进你的 IDE配好 API_KEY跑import os, json, subprocessfrom anthropic import Anthropicclient Anthropic()MODEL claude-opus-4-7DENY [rm -rf, mkfs, dd if, :(){]TOOLS [{name: bash,description: Run a shell command and return stdout/stderr.,input_schema: {type: object,properties: {cmd: {type: string}},required: [cmd],},}]def execute(name, args):if name ! bash:return {error: funknown tool {name}}cmd args[cmd]if any(d in cmd for d in DENY):return {error: denied by policy, hint: use a safer command}r subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue, timeout20)return {stdout: r.stdout[-2000:], stderr: r.stderr[-2000:], code: r.returncode}def run(task):msgs [{role: user, content: task}]while True:r client.messages.create(modelMODEL, max_tokens4096, toolsTOOLS, messagesmsgs)msgs.append({role: assistant, content: r.content})if r.stop_reason ! tool_use:print(r.content[-1].text)returnresults []for block in r.content:if block.type tool_use:out execute(block.name, block.input)results.append({type: tool_result, tool_use_id: block.id,content: json.dumps(out)})msgs.append({role: user, content: results})if __name__ __main__:run(统计当前目录下有多少个 .py 文件并告诉我最大的那个。)这就是 Harness 的「骨架」。剩下 4 个子系统的实现都是在这 50 行之上加层•上下文管理在 msgs 增长到一定 token 数时调用 Claude 自己做 summarize 折叠。•权限层升级把 DENY 列表升级为 allow/ask/deny 三档配 .settings.json 用户可改。•子代理把 execute() 里加一个 spawn_agent 工具独立开 messages 序列。•技能在系统提示里加一个 list_skills() 工具模型按需读取本地 .md 文件。这就是一个工业级 Harness 从无到有的全部路径。剩下的工作量大但没有什么神秘的地方。七、Harness 工程师的一天如果你想知道这门「学科」具体长什么样可以看一眼一个 Harness 工程师真实的日常。这不是抽象的方法论——这是 8 小时里发生过的事情•早 9:30 扫一遍夜里跑过的 Agent 失败日志。三起 tool_call 拒绝一起 token 超限。•上午 把 token 超限那条改成 sub-agent 隔离方案不改提示词改架构。•中午 和团队对齐一个新的 deny 规则——禁止 Agent 在 main 分支上直接 commit。•下午 给 run_sql 工具补 hint 字段、写一个新 Skill 文件 database-migration.md。•晚 6:00 跑一遍金标 100 个任务的回归。成功率 84% → 91%。提交 PR。全天没改过一行 prompt。这就是 Harness Engineering 的工作方式。提示词是流量架构才是积累。结语Harness 的出现标志着 AI 智能体从「研究项目」迈进了「工程学科」。它不再是论文里那些花哨的架构图而是一套被真实生产环境反复打磨、独立收敛出来的工程范式。它承认了一件事——当前阶段的模型并不能靠自己解决所有问题模型需要一个为它精心搭建的运行环境才能稳定地把事情做成。框架时代结束了。Harness 时代刚刚开始。下一个值得认真讨论的问题不再是「我该用哪个 Agent 框架」而是你的 Harness 长什么样Harness 工程师自测清单如果以下五条你都答得上来你的 Harness 已经走出了 Demo 阶段。1.你的 Harness 有显式的上下文压缩策略吗是用 summary 节点还是直接截断2.你的权限层是用代码 enforce 的还是只是写在提示词里的「请不要」3.工具的错误返回是结构化 JSON还是裸字符串模型能自我修复吗4.当下一代模型发布时你能在 5 分钟内把底层模型替换掉吗5.上一次 Agent 失败发生时你修的是提示词、还是某个子系统的边界这些问题没有标准答案。但今天还在用对答案的人会决定明天 AI 智能体的形态。参考与延伸阅读•Arize AI《What is an Agent Harness?》•Firecrawl《What Is an Agent Harness? The Infrastructure That Makes AI Agents Actually Work》•Anthropic Engineering《Harness Design for Long-Running Application Development》•Anthropic Engineering《Writing Effective Tools for Agents》•Martin Fowler关于「Humans on the Loop」与上下文工程的系列博客本文完结如有帮助感谢转发、关注、点喜欢~