60行Python揭秘Claude Code Harness原理：AI编程工具性能差异的核心

什么是Harness？被忽视的AI编程核心

在AI编程领域，我们已经习惯了各种模糊的术语——agentic coding、vibe coding，而现在又多了一个需要理解的概念：Harness（框架/载具）。Theo（t3.gg）在最新的深度视频中明确指出，Harness是一个非常具体的技术概念，对你从AI工具中获得的代码质量有着决定性的影响。

Harness概念的兴起与AI编程工具从"代码补全"向"自主Agent"演进的浪潮直接相关。在GitHub Copilot于2021年发布、将LLM引入编程工作流的早期阶段，工具层的角色相对简单——主要负责将编辑器上下文传递给模型并回填补全建议。真正意义上的Harness概念在2023年前后随着Agent编程范式的成熟而浮现，其背后是模型能力的质变：当GPT-4、Claude 2等模型展现出可靠的指令遵循与结构化输出能力后，让模型"自主操作文件系统"才从理论可行变为工程实践。

值得注意的是，Harness在技术架构上的地位类似于传统软件工程中的运行时环境（Runtime Environment）。它不仅负责工具的注册与调度，还承担着上下文管理、安全沙箱（防止模型执行破坏性操作）、错误恢复（工具调用失败时的重试与降级策略）等核心职责。从分层架构角度看，Harness处于模型API层与用户界面层之间，是决定整个系统可靠性与可预测性的关键中间件——这也是为什么同一底层模型在不同Harness中能展现出如此迥异的实际表现。

最有说服力的数据来自Matt Mayer的独立基准测试：同一模型在不同Harness中的表现差异悬殊。以Opus为例，在Claude Code中的得分为77%，在Cursor中则飙升至93%。唯一的变量就是Harness。这个数字足以说明，Harness绝非可有可无的外壳，而是决定模型能力上限的关键因素。

Harness到底是什么？用最简单的话说：Harness是Agent运行所依赖的工具集合与运行环境。它是让AI能够真正"做事"的那一层底层基础设施。有意思的是，Cursor、Claude Code、Codex CLI、OpenCode都是Harness，而T3 Code和Codex App却不是——这个区别后文会详细展开。

LLM只会生成文本，工具调用如何改变一切

要理解Harness的价值，必须先认清一个本质：所有的LLM本质上都是高级的自动补全。你输入文本，它预测最可能出现的下一段字符，如此循环往复。模型本身无法编辑文件、操作数据库、连接外部服务或上网搜索——它唯一能做的就是生成文本。

那么这些模型是如何在本地编辑文件、执行命令的？答案是工具调用（Tool Calling）。工具调用是现代LLM能力扩展的核心机制，最早由OpenAI在2023年以"Function Calling"形式正式引入，随后Anthropic、Google等主流厂商相继跟进并形成事实标准。

值得注意的是，从OpenAI的Function Calling接口，到Anthropic的Tool Use API，再到Google的Function Declarations，这三大平台的接口设计在过去两年间经历了从各自为政到逐步趋同的演变——JSON Schema成为工具参数描述的通用格式，这一标准化进程极大地降低了跨平台Harness的开发成本，也是为什么一个Harness可以相对容易地同时接入多家模型提供商的底层原因。这一标准化背后还有一个鲜为人知的推动力：模型上下文协议（MCP，Model Context Protocol）的出现——Anthropic于2024年底提出的这一开放协议尝试在工具调用层面建立更高层级的互操作标准，将"工具定义、调用、响应"的完整生命周期纳入统一规范，使不同Harness能够共享同一套工具生态，而无需为每个模型提供商重复实现适配层。其底层原理是在模型训练阶段引入大量包含结构化工具调用的对话数据，让模型学会识别"何时应该使用工具"以及"如何格式化工具调用请求"。从实现层面看，工具调用本质上是模型输出的一种特殊token序列，Harness层负责拦截、解析并路由执行。

其机制相当巧妙：模型在系统提示中被提前告知有哪些可用工具，比如一个bash调用工具。当模型需要使用时，它会用特定语法包裹命令，例如 <bash_call>ls -a</bash_call>，然后停止响应。

这里发生了一件关键的事：当模型输出工具调用语法后，它就停止响应了。此时模型与你的对话被彻底切断，对话历史只存在于你的本地机器或服务器上，模型处于"暂停"状态。

接下来就是Harness登场的时刻。Harness接收工具调用后，用最基础的代码去执行它——根据你的设置，要么直接运行，要么先请求授权（比如执行格式化文件等破坏性操作时会弹出确认）。执行完毕后，Harness把工具输出追加到对话历史末尾，然后向同一模型重新发起请求，让它继续工作。

这一"模型生成工具调用→Harness执行→结果回填历史→再次请求模型"的循环，在AI工程领域被称为Agentic Loop（智能体循环）或ReAct Loop（Reasoning + Acting，推理与行动交替执行）。ReAct框架由普林斯顿大学在2022年正式提出，将推理步骤（Thought）与行动步骤（Action）交替执行的范式形式化，成为此后几乎所有Agent框架的理论基础。

这一框架的核心洞见在于：单纯的"链式思考（Chain-of-Thought）"推理只能在模型内部世界打转，而只有将推理与真实世界的行动（工具调用、环境交互）交织起来，模型才能完成真正的复杂任务。LangChain、LlamaIndex、AutoGen等主流Agent框架都是这一范式的工程实现，它们在ReAct的基础上进一步引入了记忆管理、多智能体协调、工具路由优化等机制，但其最底层的循环结构与你用60行Python手写的Harness在本质上并无二致。

理解这一循环还有一个重要的工程含义：每次工具调用都是一次完整的API请求，这意味着token消耗、延迟和成本都随工具调用次数线性增长。一个设计精良的Harness会在工具调用粒度上做出权衡——粒度过细会导致过多的API往返（round-trip），粒度过粗又会增加单次调用失败的风险。这正是为什么Cursor等商业工具会专门优化"批量工具调用（Parallel Tool Calling）"能力，允许模型在单次响应中声明多个并行工具调用，由Harness并发执行后统一回填结果，从而在不牺牲准确性的前提下显著降低延迟。负责所有工作的"大脑"在每次工具调用时都会被暂停并重启，这正是当前几乎所有AI编程工具的核心运行方式。

Context为王：为什么大上下文反而让模型变笨

Theo特别强调了一个反直觉的观点：如果信息不在对话历史里，模型就不知道它。这不适用于TypeScript语法这类通用知识，但对于你的私有代码库，模型一无所知，除非它通过工具调用主动探索，或者你通过CLAUDE.md、AGENTS.md这类文件预先把上下文"注入"到历史顶部。

当你在一个项目目录里打开Claude Code时，它对这个代码库一无所知。它会调用搜索工具查找匹配的文件，读取package.json作为起点，再读取相关源文件，把这些输出全部倾倒进上下文。而如果你预先提供了CLAUDE.md，模型可能连工具调用都省去了。

这里Theo驳斥了一个曾经流行的理论：过去认为代码库太大装不进上下文窗口就无法工作，为此还诞生了RepoMix这类工具，把整个代码库压缩成单个XML文件喂给模型。但这制造了最糟糕的"大海捞针"问题。

大上下文窗口导致性能下降的现象在学术界已有系统性研究。斯坦福大学2023年的论文《Lost in the Middle》首次定量描述了这一规律：当关键信息位于长上下文的中间部分时，模型的检索准确率显著低于信息位于头部或尾部的情况——这与人类记忆的"首因效应"和"近因效应"在结构上颇为相似。这一发现的深层原因指向了Transformer架构的注意力机制：在超长序列中，中间位置的token在多头注意力计算中往往获得相对较低的注意力权重，这是架构层面的固有偏差，并非简单调整提示就能完全克服的。

有趣的是，这一问题并非无解。近期的研究方向包括：位置编码优化（如RoPE、ALiBi等改进方案尝试让模型对不同位置的信息保持更均匀的注意力分配）；上下文压缩技术（如Anthropic的Prompt Caching机制，通过缓存重复出现的长前缀来降低重复计算成本，同时配合摘要压缩来精简历史对话）；以及稀疏注意力机制（让模型只对"重要"的token计算完整注意力，而对其余token采用近似计算）。这些技术路径都在试图从架构层面缓解"Lost in the Middle"效应，但截至目前，没有任何一种方案能在所有场景下完全消除这一偏差——这也是为什么精准的上下文管理依然是Harness设计中最关键的工程挑战之一。

正是基于这一认知，Retrieval Augmented Generation（RAG） 技术才作为系统性解决方案迅速崛起。RAG的核心思路是将知识库中的文本切分为小块（chunk），通过嵌入模型（Embedding Model）将每个块转化为高维向量并存入向量数据库（如Pinecone、Weaviate、Chroma等）。当用户提出问题时，系统先将问题向量化，然后在数据库中做近似最近邻（ANN）检索，只取语义相关度最高的若干片段注入上下文，而非暴力填充整个知识库。这一机制从根本上规避了"大海捞针"困境：进入模型上下文的始终是高度浓缩的相关信息，而非冗余的全量数据。对于私有代码库而言，现代Harness的RAG实现还需要额外处理代码的结构化语义——函数签名、类层次、模块依赖等结构信息比纯文本更能表达代码间的语义关联，这正是代码专用嵌入模型（如Voyage Code、CodeBERT）与通用文本嵌入模型的核心差异所在。

Theo用了一个绝妙的比喻：想象你的记忆每30秒就被重置一次。你被要求修复一个bug，你知道大脑马上要重置，于是发起搜索——搜索一开始大脑就被清空了，搜索完成后大脑重启，但只保留了历史记录……如此反复。把整个代码库塞进这样一个不断重置的大脑，既昂贵又不准确。

数据也证明了这一点：当Sonnet的上下文突破5万到10万token范围时，它在上下文窗口中查找重复词的准确率会暴跌近50%。大上下文会让模型变笨。因此，现代Harness的真正价值在于：为模型提供工具，让它自己精准构建所需上下文，而不是一股脑全部塞进去。

60行Python：亲手构建一个Harness

Theo引用了Mihail的文章《The Emperor Has No Clothes》，核心观点是：像Claude Code这样的工具并不复杂，其核心大约只需200行直白的Python代码。整个事件顺序是：你发送消息 → LLM决定使用工具并返回结构化调用 → 你的程序（Harness）在本地执行 → 结果回传给LLM → LLM基于新上下文继续。

核心只需三个工具：读取文件（让LLM看到代码）、列出文件（导航项目结构）、编辑文件（实际做出修改）。生产级Agent还会有grep、bash、网络搜索等，但最基础的版本并不需要。

代码结构相当简洁：加载环境变量、初始化Anthropic SDK客户端、解析绝对路径（让模型更容易写出有效命令）、实现三个工具函数。read_file返回文件内容的JSON；list_files遍历目录返回文件名和类型；edit_file用old_string和new_string做替换，若old_string为空则创建新文件。

关键在于让模型知道这些工具的存在。由于Python没有TypeScript那样的类型签名，需要通过注释详细描述每个工具的功能和参数。这些描述连同工具列表被拼装进系统提示——本质上是告诉模型："这是你可以调用的工具，需要时回复一行tool:工具名加JSON参数。"这段系统提示，构成了Harness绝大部分的核心逻辑。

系统提示是Harness与模型交互的核心接口，其设计质量直接决定模型行为的可预测性与稳定性。专业的系统提示工程（System Prompt Engineering）已逐步演化为一门独立的工程学科，涵盖角色设定、约束条件、工具描述格式、输出规范、边界条件处理等多个维度。这门学科的核心难点并不在于"写出漂亮的描述"，而在于跨模型的鲁棒性：同一套系统提示在GPT-4o、Claude 3.5 Sonnet、Gemini 2.5 Pro上的行为差异可能超过30%，原因在于不同模型在预训练和RLHF阶段接触的指令数据分布不同，导致它们对相同语义的自然语言描述有截然不同的"理解倾向"。

在实践层面，业界已形成了若干被验证有效的系统提示结构化范式。Anthropic内部将系统提示的结构化设计方法称为"Constitutional AI Prompting"，强调通过显式列举原则（Principles）来约束模型行为，而非依赖隐式的自然语言语气。OpenAI则在GPT-4o的技术报告中披露了其系统提示的分层结构设计——将全局约束（Global Constraints）、角色定义（Persona Definition）、工具说明（Tool Specifications）、输出格式（Output Format）分层嵌套，而不是平铺成一段连续文本。分层嵌套的优势在于：模型在解析时会对靠前的层级分配更高的注意力权重，这与注意力机制的位置偏差特性相契合——将最重要的约束条件放在首位，可以在统计意义上降低模型"忘记"关键规则的概率。

一个往往被忽视的系统提示设计细节是负向约束（Negative Constraints）的措辞方式。研究表明，"不要做X"与"始终做Y来替代X"对模型行为的影响存在显著差异：前者需要模型在生成过程中持续压制某种输出模式，而后者通过引导模型朝向正确路径来间接避免错误行为。在工具描述的语境下，这意味着与其写"不要直接输出文件内容，应调用read_file工具"，不如写"当需要查看文件时，调用read_file工具并传入路径参数"——后者的措辞更符合模型在RLHF阶段学到的"按步骤执行"行为模式。这正是为什么商业Harness需要针对每个支持的模型单独维护和迭代提示版本，这项工作看似繁琐，却是产品质量差异的关键所在。

剩下的是解析与循环：模型停止响应后，查找以tool:开头的行，解析出工具名和参数，从注册表取出对应函数执行，把结果作为消息追加到历史，然后在循环中重新调用模型。Theo在演示中甚至发现，只保留bash工具就足够了——模型会反复调用bash完成所有任务，代码可精简到75行，去掉环境变量处理部分甚至更少。

这揭示了一个惊人的事实：给AI操作电脑的能力，只需给它一个能传递bash命令的工具。这些模型在训练中见过大量包含工具调用的"假对话历史"，它们天生就懂得如何处理工具调用响应。

Cursor为何更强？系统提示的秘密与两个终极问题

既然Harness如此简单，为什么Cursor能让同一模型表现好那么多？Theo的答案是：因为他们测试得更多。工具的形态、系统提示措辞、工具描述细节，都会极大地影响最终结果。Cursor投入大量精力定制Harness，甚至有专人在新模型发布或拿到早期访问权时，反复微调系统提示与工具描述，直到模型能基本按预期工作。

更有趣的是，Theo演示了"对模型撒谎"这一现象。他把read_file工具的描述改成"已弃用，请改用bash工具"，Sonnet就乖乖改用了bash；他甚至让read工具无论读什么文件都返回"print hello world"，模型信以为真地报告代码只有一行。模型不知道工具实际做了什么，它只知道你告诉它的。你可以把某个工具叫bash却做别的事，可以伪造响应让两个模型互相对话而不自知。

这一现象揭示了AI安全领域的一个核心议题：工具调用的信任边界问题。模型对工具响应的无条件信任，使得恶意构造的Harness可以系统性地欺骗模型——这在安全研究领域被称为"工具污染攻击（Tool Poisoning Attack）"。2024年多篇安全研究论文记录了此类攻击向量：攻击者通过控制工具响应内容，可以诱导模型执行原本不会执行的操作，或泄露上下文中的敏感信息。这也是为什么开源Harness框架（如开源版Claude Code、OpenCode）的透明度在企业采购决策中越来越受到重视——用户可以审计Harness的每一行代码，确认工具行为与其描述完全一致，而不是依赖对商业产品的盲目信任。

不同模型对相同描述的反应也大相径庭。同样标记为"deprecated"，Gemini 2.5 Pro会激进地"什么都用bash"，而Claude则更为谨慎。这种差异背后是各家模型在**RLHF（基于人类反馈的强化学习）**训练阶段形成的不同"个性倾向"。

RLHF的完整流程包含三个关键阶段：首先是监督微调（SFT），用高质量的人工示范数据对预训练模型进行初始化；其次是奖励模型训练（Reward Modeling），通过让标注员对模型的多个输出进行两两比较来训练一个偏好预测器；最后是策略优化（Policy Optimization），通常采用PPO（Proximal Policy Optimization）算法，用奖励模型的打分信号持续调整主模型的输出分布。Gemini系列在谷歌内部大规模部署场景下，其标注员群体和评分标准被校准为更倾向于"高效执行"的指令服从性；而Anthropic的Constitutional AI框架在RLHF之上额外引入了AI自我批评（AI self-critique）循环，让模型在生成回答后主动对照一组原则进行自查和修正，这一机制在行为上表现为面对模糊指令时的保守倾向。

值得注意的是，RLHF并非只是让模型"更听话"——它本质上是通过人类偏好数据对模型的输出分布做持续的定向调整，不同公司选择的标注员群体、评分标准和奖励模型设计，都会在模型最终的"性格"上留下可测量的印记。近期的Direct Preference Optimization（DPO）技术尝试绕过独立的奖励模型，直接用偏好对数据对预训练模型进行微调，这一方法在计算效率上有显著优势，但其对模型"个性塑造"的精细度是否能匹敌完整RLHF流程，目前学界仍有争议。这意味着Cursor必须为每个支持的模型分别改写工具描述——而Anthropic可能自从这些代码写下后就没怎么改过，这正是差距所在。

至于T3 Code是什么？Theo坦言它不是Harness，因为它不提供任何工具，没有bash工具也没有read工具。当你在T3 Code里选择Claude模型时，它实际调用的是你机器上已安装的Claude Code Harness；选Codex则依赖Codex CLI。T3 Code只是Harness之上的一层精美UI。这也回应了"只是做了个包装"的质疑——构建Harness本身并不难，难的是围绕它打造出色的产品体验。

核心要点