作者：@rohit4verse
你的AI代理用不好，问题可能不在于模型选择错误。
真正的原因在于：你没有为它构建正确的运作环境。
业界已经出现了令人震惊的效率对比：有些团队仅凭三名工程师，就通过AI代理交付了百万行代码；而另一些团队，却连AI代理流水线中一次稳定的代码重构都难以完成。这种差距的根源，并非来自GPT-5与Claude Opus等模型的能力差异，也不是提示词技巧或temperature参数设置所能解释的。
关键在于一个被行业长期低估的概念：Harness（驾驭框架）。
本文将深入剖析这一概念的技术与观念内核。整个行业已养成了一个坏习惯：对这个词的使用过于随意和表面化。Harness并非系统提示词，不是API调用的简单封装，也不是评估框架或带记忆的聊天机器人。
Harness是语言模型赖以运作的完整设计环境。它包括了模型可调用的工具、接收信息的格式、历史记录的压缩与管理方式、在错误级联发生前进行捕获的“护栏”，以及让代理能将工作移交给“未来的自己”而不失连贯性的脚手架。
当你审视Anthropic为使Claude Code真正奏效而构建的体系、OpenAI通过Codex以“零手写代码”交付百万行代码的实践，以及普林斯顿NLP组在里程碑论文《SWE-agent》中提出的“Agent-计算机接口（ACI）”时，一个相同的模式从每个深耕此领域的团队中浮现出来：模型本身几乎无关紧要，Harness才是一切。
这是一份关于为何“环境设计”将成为2025至2026年应用AI工程核心洞察的详细技术分析。它涵盖了相关研究、真实案例、驱动设计的失败模式，以及无论你构建编程代理、研究代理还是长期运行的自主软件工程师时都会反复出现的通用模式。
理解之后，你将不仅明白Harness是什么，更会懂得为何正确构建一个Harness，已成为当今行业中极具价值的工程技能。
第一部分：被忽视的核心问题——为何原始能力不够用
接口即“心智”
2024年中，AI基准测试领域出现一个奇特现象：同一前沿模型在完全相同的编程任务上，因任务呈现方式和可用工具的不同，结果天差地别。模型未变，底层智能未变，变的只是接口。
这并不令人意外。合适的工具能极大提升工程师效率，这一道理对AI同样适用。语言模型本质是在上下文窗口中对token进行精密模式匹配的引擎。它们在某一时刻“知道”的一切，由上下文窗口中的内容决定；它们产出的一切，以该上下文的结构为条件。输入的格式不是装饰，它就是代理的认知架构。接口即“心智”。
普林斯顿NLP组2024年的SWE-agent论文引入了“Agent-计算机接口（ACI）”概念，并证明：一个精心设计的ACI，相比同一模型通过标准Linux shell交互，能在基准测试上带来64%的相对性能提升。相同的模型、任务和计算预算，唯一的变量是接口设计。
这个数字意味着有效工具与无效工具之间的本质差距，完全源于环境设计，而非模型改进。
上下文窗口不是内存插槽
一个常见的错误认知，是将上下文窗口视为简单的内存。实际上，它更接近于代理在特定会话中的“工作意识”。每个token都有计算成本，每条无关信息都在争夺注意力。模型缺乏人类选择性忽略噪音的机制——噪音在场，就会影响推理。
这带来具体后果：当代理在循环中对大型代码库运行grep并返回上万行结果时，你并非在提供更多有用信息，而是在用无关数据淹没其工作记忆，这将降低后续每一步骤的质量。SWE-agent的研究者详细记录了这种“反复横跳”的失败模式：代理发出返回海量结果的grep命令，然后迷失，再发出更多grep，最终被噪音淹没。
问题的核心不在于模型智能，而在于接口没有机制保护代理免于“自我淹没”。
第二部分：SWE-Agent论文与ACI的诞生
Agent-计算机接口（ACI）详解
ACI被定义为语言模型代理与计算机环境之间的抽象层。正如人机接口（HCI）研究如何设计契合人类认知的界面，ACI研究如何设计契合语言模型认知的界面。
SWE-agent的ACI包含四个针对语言模型失败模式洞察而设计的主要组件：
1. 搜索与导航： 用专用工具（如find_file, search_file）取代标准grep/find。关键创新是输出管理：结果上限为50条。若超出，工具会提示代理“结果过多，请精炼搜索”。这通过强制函数打断了“越搜越广”的噪音循环，推动代理行为更审慎、更具针对性。
2. 文件查看器： 最具认知架构洞察的体现。测试发现，每次显示100行是“甜点”。更少行数（如30行）会导致代理失去上下文；更多行数（或显示完整文件）则易致其迷失。查看器是有状态的，保持文件位置，并为每一行添加明确的行号。这看似小事，却将“数行数”的认知任务从代理工作记忆中移除，释放了真正用于问题求解的容量。
3. 带Linting的文件编辑器： 核心是带护栏的即时反馈。edit命令接受行范围和新内容作为单次操作。每次编辑后，工具自动运行linter并报告。若引入语法错误，编辑会被拒绝，代理会收到包含原始代码和失败编辑的清晰错误消息。这封闭了导致级联失败的反馈回路，让语法错误在引入瞬间即被捕获、本地化修复。
4. 上下文管理： 解决长会话中过时上下文堆积的问题。系统将较早的观察记录（最后五轮之前）压缩为单行摘要。这使活跃上下文聚焦于近期相关信息，同时保留整体轨迹的压缩记录，防止代理被陈旧历史淹没。
基准测试结果及其意义
在真实的SWE-bench数据集（Python代码库GitHub Issue）测试中：使用GPT-4配合标准bash shell，系统解决了3.97%的问题；使用GPT-4配合专门构建的ACI，解决率跃升至12.47%。这正是64%的相对提升，完全源自接口设计。
消融研究证实，linter集成、带上限的搜索、带行号的有状态查看器是关键杠杆组件。性能差异与模型智能无关，而与认知负荷管理有关。ACI减少了模型追踪状态所需的心智负担，为真正重要的工作腾出了空间。
第三部分：Anthropic的Harness工程——破解长期运行代理难题
上下文窗口边界是核心挑战
大多数真实软件项目过大，无法装入单个上下文窗口。即便有20万token的窗口，也无法将完整项目同时装入。人类工程师依靠外部记忆和长期积累的理解，而开启新会话的代理则一无所有。
朴素的“压缩”方案不够。Anthropic内部实验显示，即使有压缩，像Opus 4.5这样的前沿编程模型在跨多个上下文窗口运行时，仍难以仅凭高层提示构建生产级Web应用。失败模式主要有二：
- 试图一次性完成太多： 代理尝试实现整个应用，但每个功能都未完成或测试，便在耗尽上下文后留下“半成品烂摊子”。
- 过早宣告胜利： 项目后期，代理看到已有进展便推断“工作已完成”，实际上应用只完成了一半。
共同根源是：代理缺乏能在上下文窗口边界存活、为后续会话提供方向的、持久且结构化的项目状态理解。
双代理架构：初始化代理与编程代理
Anthropic的解决方案是已成为行业模板的两部分架构：
1. 初始化代理： 特化的初始会话，唯一目的是搭建后续所有编程代理将运作的环境。它不编写功能，只创建使跨会话开发成为可能的脚手架。产出三个关键输出：
- init.sh脚本： 可靠启动开发环境，为每次会话节省摸索配置的token开销。
- 功能列表文件： 包含超过200条具体端到端功能描述（如“用户可新建对话并看到AI回复”），每个功能初始标记为“未通过”。这是项目的基准事实，防止代理从代码片段错误推断完成度。
- 进度文件与初始Git提交： 人类可读的日志，结合Git历史，让后续代理快速定向，无需耗费上下文预算做“考古”。
2. 编程代理： 初始化后的每次会话，使用不同的提示词：一次只处理一个功能，结束时更新进度文件和Git历史，将环境留在干净状态。增量推进，记录状态，干净交接。
功能列表作为认知锚点
Anthropic有意将功能列表存储为JSON而非Markdown。原因是行为层面的：模型对JSON文件不当修改或覆写的概率低于Markdown。JSON的刚性结构抵制随意编辑，促使代理谨慎更新这个“基准事实”。
测试：无人愿谈的失败模式
一个常见失败模式是：代理在没有端到端验证的情况下将功能标记为完成。 单元测试通过，但以用户方式通过浏览器测试时，功能实际不可用。解决方案是赋予代理访问浏览器自动化工具（如Puppeteer MCP服务器）的能力，使其能真正导航应用、点击按钮、验证端到端功能。这印证了一个通用原则：代理工作质量受限于其反馈回路的质量。
第四部分：OpenAI的Harness工程——“零行手写代码”实验
一场约束实验
2025年8月，OpenAI Codex团队以唯一约束创建了一个Git代码库：无人工编写代码。 五个月后，该库包含约一百万行代码（涵盖应用、测试、CI配置、文档等），提交了约1500个PR。三名工程师的小团队推动了大部分工作，平均每人每天提交3.5个PR。
核心结论与SWE-agent一致：瓶颈从来不在模型能力，而始终在于环境设计。
工程工作的重新定义
当主要工作不再是编写代码，工程师在做什么？答案是：设计环境、明确意图、构建反馈回路。 工程师的思维从“如何修复这个缺陷？”转变为“环境中缺少什么能力，导致这个缺陷反复出现？”。你不再调试代码，而是调试产生代码的系统。
代码库知识作为系统记录
最重要的架构决策之一是：将代码库本身作为代理所需了解的一切的唯一真实来源。 任何代理在运行时无法在上下文中访问的内容，对它而言就不存在。
早期尝试“一个大AGENTS.md文件”的方案失败了，原因有四：1）挤占稀缺的上下文资源；2）过多指导等于无指导；3）迅速过时腐化；4）难以验证和更新。
解决方案是结构化的docs/目录配合简短的AGENTS.md（约100行）作为“地图”。这实现了渐进式披露：代理从小而稳定的入口点出发，被引导至更深层信息，而非一开始就被淹没。
应用可读性：让系统对代理“可见”
随着代码生成吞吐量增加，验证成为瓶颈。解决方案是让应用对Codex直接可读：
- 支持按git worktree启动，使代理能为每个变更驱动独立的应用程序实例。
- 集成Chrome DevTools Protocol，使代理能操作DOM、截图、导航，复现缺陷。
- 构建完整的本地可观测性技术栈，通过LogQL、PromQL等向代理暴露日志、指标和追踪。
每个代理任务在完全隔离的、拥有独立可观测性数据的应用版本上运行。这意味着代理能使用与人类工程师相同的工具调试类生产环境问题。
在不微观管理的情况下执行架构
在完全由代理生成的代码库中，维护架构一致性是一大挑战。解决方案是机械化地执行不变量，而非依赖人工审查。应用围绕刚性架构模型构建，由自定义linter和结构测试执行约束（如依赖方向、边界）。
核心洞察是执行边界，同时允许边界内的充分自由。Linter专门编写，错误消息包含可注入代理上下文的修复指令，形成闭环反馈。
吞吐量改变合并哲学
当代理吞吐量远超人类注意力时，传统工程规范变得适得其反。OpenAI团队做出有意决定：以最小阻塞合并门控运作。PR保持短生命周期，测试偶发性失败通过重新运行处理。核心权衡是：在高吞吐量环境中，纠错是廉价的，等待是昂贵的。
第五部分：反复出现的设计模式
纵观所有成功系统，若干设计模式反复出现，这是大规模可靠部署代理时涌现的工程解决方案：
模式一：渐进式披露 – 不一次性提供所有信息。提供最小必要信息，并指引获取更多信息的路径。（如SWE-agent的搜索上限、OpenAI的docs/结构）
模式二：Git Worktree隔离 – 一个代理，一个worktree。为并行或顺序任务提供文件系统级隔离，变更在隔离中验证后再合并。
模式三：规格优先，代码库作为系统记录 – 任何代理需要知道的信息都必须编码在代码库中。如果代理无法读取，它就不存在。
模式四：机械化架构执行 – 将架构约束编码为自动运行的检查（linter、结构测试），取代无法扩展到代理吞吐量的人工审查。
模式五：闭合的反馈回路 – 将反馈收紧到极致：编辑时lint、运行时可观测、UI缺陷通过浏览器自动化发现。尽早捕获错误，防止级联失败。
结论：Harness才是一切
变革性技术的长期价值，往往不在于其原始能力，而在于使之变得可靠、可控、可扩展的基础设施层。Web的价值在于搜索引擎和浏览器，移动端的价值在于应用商店和开发者工具。
AI代理正在遵循同样的规律。能力已然存在。真正的差异化优势和持久价值，在于谁能为这些能力构建卓越的运作环境——Harness。
模型是推理引擎，Harness是决定推理引擎究竟能完成什么的上下文、约束、反馈回路、记忆、工具和脚手架。 将Harness做对，不是提示词工程问题，而是系统工程问题。这已成为当前应用AI领域最重要的工程前沿。