Harness 工程 全部章节

第1章 从模型能力到任务运行：认识harness工程

大模型出现之后，软件多了一种做法：不用为每个场景单独训练模型，把要求写清楚，它就能给出判断和结果。最早的智能体应用靠一段固定提示词——给模型一个人设，再给一组指令和例子，让它照着回答。

但模型只知道训练语料截止之前的事。昨天会上定了什么、你本地那个文件写了什么，它都不知道。为了解决这个问题，人们提出了名为 RAG（检索增强生成）的方法：先把相关资料找出来，和问题一起送进上下文，让回答有事实依据。

除此之外，当时更实际的问题是，能不能让模型对现实世界产生作用。模型只能生成文本，真要改动什么，还得由程序代它动手。沿着这个问题，人们探索出一种做法：由模型在推理中决定用哪个工具、生成调用参数，再由应用程序分发执行，把结果送回模型继续判断。模型负责选择和判断，程序负责动手，这条分工是 ReAct 一类方法的核心。

但一次调用做不完一件事。调哪个工具、结果对不对、失败了怎么办、谁允许它动这个文件、做到什么程度算完成，都要有程序来管。管这些的是模型外面的一层系统，本书讲的就是它。

1.1大模型落地中的工程关注扩展

提示词工程是这一阶段形成的第一套方法：怎样编写和组织指令、示例及输出要求，让模型更可能给出想要的结果。一个最小尝试是把“整理这份材料”改写成明确的目的、范围和输出格式，再看结果是否符合需要。2020年的GPT-3研究已经显示，任务及示例可以通过文本交互提供，执行时不再分别更新模型参数——尝试新任务可以先从输入开始，不必每次准备训练数据、训练专用模型。这条路便宜、直接，边界也清楚：能用的只是写进提示的东西。

提示和检索解决的都是“给模型什么材料”，没有解决“模型能做什么动作”。2022年，姚顺雨等人提出ReAct，将模型生成的推理轨迹与任务行动交错组织。推理帮助选择和调整行动，行动则从知识库或环境取得新观察，再供后续推理使用。重要变化在于，任务不必完全依靠最初那份输入：模型可以先提出需要取得什么，看到结果后，再判断下一步。这为智能体搭建提供了一种有影响的组织思想。

例如，面对材料中的一个待核实说法，模型可以先决定查询，再根据查询结果补充判断。这里需要的已不只是一个更好的提示。应用要识别查询请求，把它交给实际接口，接住返回信息，并组织下一次模型输入。ReAct呈现了这条推理、行动与观察的关系；实现它需要程序参与，后续产品也可以采用结构化工具调用等不同形式，不必照搬论文中的文本格式。

Claude Code、Codex等商业化产品，使这种交互进入了开发者熟悉的工作过程。系统可以读取项目，提出并实施修改，执行测试，再利用错误结果继续处理。用户提交的是工作要求，检查的则是代码变更和测试结果。模型生成能力仍然重要，项目环境、工具、运行记录和验证方式也直接影响工作能否完成。它们不是ReAct的简单产品化版本，而是让多步交互的工程需求变得具体、可见。

接入范围扩大后，应用还要连接项目之外的文档、数据库和业务服务。MCP（Model Context Protocol）为应用与服务之间的工具、资源等接入提供共同协议。一个客户端连接一个提供读取能力的服务，就可以取得资料并调用相应能力。协议使接入方式可以复用，应用则继续决定本次任务需要哪些能力、允许访问哪些对象，以及取得的信息怎样使用。第一章先认识这个连接作用，详细契约留到第5章。

每一次操作还会改变后续判断所需的信息。最初只有目标和说明，后来增加了文件内容、查询结果、错误输出、已作出的决定以及用户纠正。把它们全部不断追加，会遇到输入容量、成本和信息干扰；只保留一段简短提示，又可能丢失推进任务所需的依据。工程问题于是从“怎样写这段指令”，扩展到“这一刻应该向模型提供什么”。

上下文工程围绕每次模型调用取得、筛选、组织和维护所需信息。上下文是该次调用实际提供给模型的内容，提示是其中一部分，材料、工具信息和历史观察也可能进入其中。一个最小做法，是在读取结束后，将相关内容与当前目标一起提供给下一次判断；任务变长以后，再考虑按需取得、局部保留和历史压缩。Anthropic在2025年的公开论述中明确讨论了这一关注范围，强调信息组织随多步工作持续进行，而不止于启动时编写提示。

信息准备妥当，交互仍有另一面的工作。谁真正修改文件？写入已发生却没有回执时，系统知道什么？用户撤回许可后，旧提议能否执行？界面显示完成时，有哪些对象和检查支持这个结论？这些问题涉及输入，也涉及执行、状态、约束和交付，需要一起设计。

厂商的公开实践已经把这套系统作为明确的工程对象。Anthropic在2025年讨论长任务harness，除上下文压缩外，还关注环境初始化、增量推进、工作记录与验证；OpenAI在2026年的harness工程文章中，讨论如何为Codex建设可理解、可操作、可验证的开发环境。DeepSeek也推出了DeepSeek Harness，官方页面在本书核验时提供公开预览及开源入口。这些实践的场景和实现并不相同，却都将注意力放到模型周围的工作系统上。

沿着这段探索，可以看见工程关注的扩大：从表达任务，到取得观察，再到组织持续变化的信息和实际操作。提示、行动方法、上下文策略仍然各有用途。Harness工程讨论的，是怎样把它们接成模型能够与外界交互、推进任务并形成结果的运行系统。

1.2Harness的定义与运行结构

Harness是围绕模型建立的任务运行系统。 它组织输入与模型调用，将模型提出的操作交给程序或服务，接受执行结果，并依据当前事实和约束决定继续、等待还是停止。需要产生外部效果的任务，还由它关联动作记录、产物与验收，形成可以向用户交付的结果。

这里的智能体（agent）依据目标和观察选择行动，并利用反馈调整下一步。本书讨论由模型参与行动选择的智能体。最小形态可以很有限：模型选择读取哪份允许的材料，取得结果以后决定是否提交产物请求。它不是模型名称，也不是仅让模型反复输出“继续”；自主选择可以存在于一个受到严格限制的行动空间内。

这段过程需要落在程序中。收到要求以后，程序准备输入；模型返回答复或行动请求；程序检查并处理行动，再将结果用于下一次判断。一个程序就可以承担全部工作，不必先拆成多个服务。若任务只需一次文本生成，运行层可以很薄；若要修改真实对象，执行与验收也必须进入这条路径。

因此，harness不是某家框架的专有名称，也不意味着在现有应用外再加一层。同一个框架可能已经负责消息、工具和调度，业务程序再负责任务许可与产物检查。建设时要找的是各项责任的实际实现：输入由谁准备，操作由谁实施，事实保存在何处，最后由谁决定交付。名称能帮助定位这些问题，不能代替答案。

聊天界面只规定要求与结果怎样呈现，固定流程组织步骤及转移条件；由模型选择下一步时，就有了智能体的行动组织。它们都可能使用同一套运行能力。第一章不将这些形式排成升级阶段，后面也不会要求读者为了建设harness先采用复杂的流程或多个agent。先建立足够完成任务的主线，再从实际需要中增加能力。

1.3任务目标、授权范围与验收条件

运行系统要作出判断，先需要取得任务条件：期望的结果是什么，可以实施哪些操作，以及结果怎样核对。这三件事分别由目标、授权和验收表达。它们可以保存在同一个任务对象里，但在推进过程中的用途不同。

目标表达想要的结果。“从指定材料中创建一个摘录文件”是一个产物目标。授权规定本次任务可以对哪些对象采取哪些操作，例如读取指定材料，在指定目录新建文件，但不覆盖已有文件。验收条件规定凭什么认定结果符合要求，例如摘录文件的文字逐字来自指定材料，并且磁盘上的文件与获准内容一致。

目标给模型选择提供方向，授权约束执行，验收为交付提供依据。要求创建一份摘录文件，并没有许可搜索所有目录；允许新建文件，也没有使任意文件成为合格产物。写入之后，仍要核对其内容及来源。把这三项分开，不是为了多造三个模块，而是让每一步使用恰当的判断依据。

其中有一项授权容易被忽略：材料会不会离开本机。允许本地读取，并不自动包含将内容发送给外部模型服务的许可。工具能够读取哪些对象，以及本次模型输入能够包含哪些内容，都要与任务范围相符。第3章采用公开的固定练习材料，让这项条件可以明确落实，而不涉及读者个人资料。

任务条件来自可靠的入口，例如被认可的用户要求或既定策略。模型的提议和读取材料中的文字属于任务信息，不能自行改变许可。材料里出现“修改其他文件”，程序仍要按材料内容处理；若它确实应当成为新要求，需要通过任务入口重新提出。否则，任何被读入的文本都可能重新规定操作范围。

用户也可能在任务过程中修改目标、撤回授权或调整验收标准。程序应保存当前有效条件的版本，并将模型请求与发出时的版本关联。最小实现可以由一个协调者串行接受变化，再决定旧请求是否仍可使用。只把纠正追加到历史，让旧提议沿用原许可继续执行，没有落实这次改变。

验收的变更同样需要说明。修复源码时，让测试不再检查原来的错误，并不会自动证明修复成功；改变测试可能是一项获准的新要求，也可能只是普通文件修改。系统要区分二者，才能说明最终完成的是原任务，还是已经正式调整后的任务。

1.4行动请求、工具执行与外部事实

任务条件确定以后，模型可以在允许的能力中提出行动。工具是harness向模型提供的能力契约，包含可识别的操作、可解释的输入和有明确含义的结果。实际能力由程序或服务实施。最小读取工具可以只接收一个材料标识，取得绑定内容，再返回来源与字节。

工具描述让模型知道可以提出什么，工具实现决定操作怎样发生。收到“读取材料A”的请求，程序先识别名称和参数，再核对对象、许可及执行条件，最后调用对应实现。实际实施操作的组件称为执行器，它可以与harness处于同一进程，也可以是独立服务。一次请求能被JSON解析，只完成了输入解释，还没有完成授权和执行。

能力的实际范围会改变建设要求。只读取两个绑定对象的接口，不需要模型选择任意路径；执行命令的接口则允许被启动的程序继续访问文件、网络或其他服务。两者即使都只有几个参数，效果范围也相差很大。建设者需要沿着实现看清哪些能力开放了，不能仅按参数数量判断约束是否充分。

执行结果决定下一步能够依据什么。读取返回可以说明取得了哪些内容；创建返回可以关联新对象；服务返回“已受理”时，只说明请求进入了处理流程，完成状态还需继续观察。这些返回各自意味着什么，需要运行系统区分。否则，尚在后台处理的任务可能被当成已经完成，后面的动作就失去了可靠依据。

写文件、创建进程或更新远端对象，会改变外部环境，本书将这样的变化称为副作用。它没有褒贬含义，也不是异常的别称。很多任务本来就要留下持续变化，例如在真实目录中创建一个新文件。Harness要使获准的效果发生，并限制其他效果，而不是一概阻止写入，或把全部结果放在退出即丢弃的环境里。

如果执行返回丢失，已发生的效果不会随之消失。模型可以根据现有信息推测写入成功，但确认仍要依靠产物、动作记录或外部查询。即使模型服务保存了某种历史或内部状态，也不能由此推出应用已经掌握外界操作的事实。这里不要求把所有模型接口理解为无状态函数；需要明确的是，各项外部事实由谁观察、凭什么确认。

1.5运行状态、记录与模型上下文

多步任务会积累信息，保存什么取决于后面要怎样使用。程序需要判断能否继续，模型需要理解当前任务，建设者需要核对发生过什么。三种用途有重叠，但不能靠一份不断增长的聊天历史代替全部工作。

运行状态是程序对当前位置、当前条件及已知事实的明确表示。它可以包含目标与授权版本、正在处理的动作、已知结果和停止原因。请求尚未提交，可以在条件允许时开始；已经提交却结果不明，则可能需要先核对。状态将这些差别表达为程序能使用的判断对象，而不只是模型的一段进度描述。

原始记录保存可以追溯的输入、决定与观察。将请求、当时的任务条件、工具结果和产物身份关联起来，就形成了一组最小记录。状态告诉程序现在怎样判断，记录解释判断的依据；二者可以使用相同存储设施，也可以分布在不同位置，只要关联和保存范围明确。

模型上下文是本次调用实际提供给模型的信息。程序刚读取材料，并不说明模型已收到材料；内容进入请求以后，才成为这次判断的输入。最小上下文可以包括当前目标、操作规则、相关材料和上一步观察。程序保存的整份档案是候选信息来源，不必每次全部提交。

这种分工使材料可以移出模型输入。一个大工具结果可以保存在原始记录中，后续请求只提供当前相关的部分；需要细节时再定向取回。移出模型输入并不要求删除动作证据，摘要也不承担证据的全部用途。摘要里一句“摘录文件已创建”，可以帮助理解进展；确认写入仍需要对应记录和磁盘上的实际内容。

跨任务复用的信息则形成长期记忆，例如带来源和适用范围的用户偏好。它不是当前任务进度，也不是所有聊天文本归档后的另一个名字。没有复用需求可以不建设；需要保存时，要说明怎样纠正、过期或撤回。旧任务的临时许可也不能通过记忆成为新任务的长期授权。

“短期记忆”在不同系统中可能指近期上下文、任务状态或暂存记录。后续讨论具体方法时，本书会先指出对象，避免用一个名称混合这些用途。信息管理首先是使用关系的设计，然后才是存储或压缩算法的选择。

1.6从任务许可到运行时约束

工具执行要符合授权，模型也应得到与之相符的指令。提示帮助模型选择合适动作，授权检查判断提议是否获准，实际执行路径再兑现许可中的限制。例如只允许创建新文件时，执行器需要使用不能覆盖已有对象的创建方式，而不只是接受一个名为“新建”的函数调用。

运行时强制是在实际操作路径上限制行为，在声明的执行边界和信任假设内阻止不被允许的效果。固定工具可以只实现绑定对象的读取，额外参数无法把它变成任意读取。这个最小形态容易查阅和验证；若开放任意程序，约束则要覆盖程序实际能够使用的能力。

任意程序可能创建线程、子进程和进一步的后代，还可能通过已有文件描述符、进程间通信或远端服务转交工作。允许启动哪个命令，只规定入口；要限制其读写，还须了解约束落在哪条实际路径上。父进程退出后，后代或转交的工作可能仍在继续。选择执行方案时，这些对象决定边界是否覆盖任务需要的行为。

审计利用留存记录追溯请求、许可、执行与结果，帮助定位问题。恢复则在中断后核对事实，再决定是否及怎样继续。最小恢复策略可以是发现结果未知就暂停自动动作，人工检查目标对象并决定后续。恢复不是默认再发一次旧请求，也不必抹掉此前有效修改；若要撤销或补偿，它本身就是需要判断许可的新动作。

提示、授权、强制、审计与恢复可以由一个程序承担，却分别作用于选择、资格、实际行为、追溯和接续。审批可以取得许可，凭证可以提供访问身份，都有明确用途；它们不能代替执行处的限制，事后日志也不能代替事前阻止。弄清这些位置，才知道某项能力能补足什么，而不是把各种“安全措施”简单相加。

本书会讨论怎样选择、接入和验证执行能力，不按操作系统机制逐章编写开发手册。读者需要的底层原理，是那些会改变边界判断的部分。与此同时，用户要求留下的文件和修改仍应持续存在；执行约束要服务于真实任务，不能通过丢弃整个环境改变任务本身。

1.7写前记录、预算与停止策略

各项责任接在一起后，就得到任务的运行路径。程序取得任务条件，组织输入，保存请求，取得模型提议，执行获准动作，再依据观察判断继续或交付。下面的伪代码表达职责顺序，具体数据结构与实现分别在第2、3章展开。

取得目标、授权与验收条件，保存当前有效版本
在预算允许且任务可以推进时：
    根据当前事实组织输入，保存本次请求及必要关联，再调用模型
    保存并识别候选输出
    若模型请求行动：
        按当前有效约束检查请求
        若拒绝，记录原因并决定反馈或停止
        若获准：
            在产生副作用前持久记录动作身份、目标对象和提交意图
            若记录不能确认成功，停止，不启动该动作
            通过满足约束的执行接口提交动作
            保存观察结果；若结果或记录未知，停止自动推进并等待核对
    若模型提出最终答复：
        按约定证据验收，而不是直接将任务标为成功
        保存验收结果和明确的停止或继续决定
预算耗尽、取消或无法继续时，保存对应原因

写前记录值得在第一套实现中落实。文件创建与记录保存是两个可能分别失败的动作：若先写文件，进程可能在记账之前退出，文件存在却没有解释它来历的可靠起点。先持久保存动作身份、对象和意图，再实施写入，至少保留了后续核对的关联。记录失败时不开始动作，让系统不会主动越过这个起点。

记录先写并没有使两件事成为一个事务。有了意图，动作可能还未启动；没有结果记录，动作也可能已经完成。因此写前记录提供核对依据，而不独立提供重试资格。第一次搭建可以在未知时停止，等后面建设了对象核对、接管与去重条件，再增加自动恢复。

运行还需要控制投入。预算是一次运行允许消耗的资源上限，最小形式可以是模型请求次数和单次输出额度。循环会不断增加历史，工具也可能消耗时间或费用，所以输入大小、调用次数及工具资源需要各有约束。预算表达可实施的限制，不预测任务一定需要多少步骤；只在提示里要求少调用几次，仍将限制留给模型选择。

停止原因应与后续处理相符。验收通过可以交付，等待材料可以暂缓，权限拒绝需要说明范围，结果未知需要核对。预算耗尽而目标未达到，不能改写成完成。用户取消时还可能有外部工作在进行，停止等待也不会撤销已发生效果。清楚表达这些情况，是第一版运行系统可以做到、也值得先做的能力。

1.8结果验收与后续建设

任务结束时，交付的是对目标是否达到的结论、对应产物和未确认项。工具成功说明一次局部动作的结果，模型答复组织面向用户的说明；完整交付还要将它们与任务条件关联。

验收首先要对准实际对象及检查时的版本。某条路径现在有文件，不足以说明它就是此前创建的内容；文件修改以后，旧检查仍针对旧状态。本书所说的独立验收，是让判断依据独立于模型自述，而不是必然再调用一个agent。程序可以读取文件、核对引用、检查格式或运行既定测试。需要语义判断时，也应保存依据与未确认范围；等待人工验收同样是一种明确结果。

由这些观察，可以找到建设缺口。模型没有获得关键材料，先检查读取与上下文组织；获准请求没有实际效果，检查执行与返回契约；效果已经发生却被重复提交，检查记录与恢复条件。它们都可能表现为“任务失败”，但需要修改的部位不同。Harness的责任划分帮助建设者沿着事实定位，而不将所有问题都归到模型能力。

新增能力也应有这样的理由。稳定且重复的步骤可以固化为流程；有跨任务复用需要再建设长期记忆。多数短任务可以由同一个agent单线推进，共享必要消息，不必先加入规划器或委派体系。独立探索、隔开大量局部材料或异步取得结果可能适合委派，收益和协调代价仍要按任务判断。这里不否定多agent，而是保持系统规模与实际需要相符。

已有应用和框架能承担这些工作，就可以复用，核对时再确认实际启用的配置与保证。保存消息不自动保存外部动作事实，注册工具也不自动限制实际执行；检查应沿着具体实现展开。完成目标和遵守约束是两条评价线：越权完成不是合格结果，未越权但没有完成也不能报告成功。

比较策略时，还要保留任务、环境、模型和策略版本，使结果具有相同或明确可比的条件。一次成功可以说明这个样例发生了什么，更大范围的结论需要对应验证。小系统不是必须升级成大平台的过渡形态。只要任务范围明确、责任完整、结果可核对，它就是一种可长期工作的选择。

本章判据

以下判据用于核对理解和设计位置。找到责任的定义，不等于已经验证实现；后续实践会把这些位置落实为代码和运行记录。

  • ☐能说明提示构造、行动与观察、上下文组织怎样引出任务运行系统，产品与协议的作用不混成一条技术替代链。
  • ☐能定义harness和由模型参与行动选择的agent，指出最小运行结构；聊天界面、固定流程与多agent不是harness的必要形式。
  • ☐目标、授权、对外发送范围与验收条件明确，模型输出和外部材料不能自行变更任务许可。
  • ☐行动提议、执行受理、实际观察和任务验收分别解释，工具契约能对应到真实实现。
  • ☐运行状态、原始记录、模型上下文和长期记忆各有用途，缩短输入仍保留动作核对依据。
  • ☐提示、授权、运行时强制、审计与恢复有各自的作用位置，实际边界及信任假设可以说明。
  • ☐副作用前持久记录意图，记录或结果未知时停止自动推进，并保留核对起点。
  • ☐预算、等待、取消、拒绝和未知有明确含义，任意程序执行的边界考虑后代与转交工作。
  • ☐验收关联产物及版本，目标效果和执行约束分别评价，后续建设由可观察的责任缺口支持。

本章没有回答什么

本章解释了建设对象与责任关系，没有提供模型接口的字段结构、可运行代码、任意程序执行方案或跨重启恢复协议。产品节点说明实践关注的变化，不代表其能力已经由本书验证，也不替代本书各章的实现与验证条件。

第2章把模型与程序的交互落实为会话、消息和一次次接口请求；第3章再使用两个固定工具读取材料、创建真实的摘录文件。读者先得到一个小而完整的运行系统，再带着其中的记录和判断位置，深入状态、工具、上下文与执行建设。

背景资料

以下一手资料用于核对本章涉及的研究、产品及公开工程节点，访问日期为2026年11月1日。文章发布日期不是相关实践的唯一起点。