Harness 工程 全部章节

第6章 任务组织——规划、路由与 workflow

第5章把不同能力接到同一责任链。接下来不是增加更多调用,而是决定哪些步骤值得做、由谁决定顺序,以及何时等待。一个任务可以由模型连续判断,也可以采用固定过程,还可以只把一项独立工作委派出去。这些组织方式解决不同问题,不构成从简单到高级的必然序列。

本章默认保留同一 agent 的单线推进。前面的发现、用户纠正和工具结果留在共享主线中,后面的选择继续受当前状态与授权约束。只有独立上下文或异步工作确实有收益时,才讨论委派。不另建多 agent 体系,也不把组织过程的增加当作系统创新或能力提升的证据。

6.1目标、计划与组织空间

任务组织是决定工作如何分段、选择能力、安排顺序和接收结果的控制方法。它不是重新定义目标,也不是一张能够授权所有后续动作的计划。最小形态可以只有当前阶段、未满足条件、可用能力与下一步合法转移。

组织前先保持第3章的三个对象。目标回答要得到什么,授权回答允许什么效果、哪些材料可以发送,验收回答怎样判断结果成立。若目标只是按固定来源创建摘录文件,规划就不应悄悄增加联网调查、材料真实性判断或来源代表性证明。增加这些工作会改变任务条件,不能以“更完整”为由自行取得资格。

同样,工具可用不等于某阶段必须调用。两份固定材料已经进入本次有效请求,再次读取可能没有新增价值。创建已经发生而结果未知,计划中的“创建摘录文件”仍未勾选,也不能因此自动重新提交。组织层必须读取动作事实,而不是从计划表的空格推断允许执行。

最小实现可以在现有循环中加入阶段条件,不需要新框架。先列出必须取得的材料、需要模型判断的位置、可信程序检查的位置及停止条件,再决定是否值得保存显式计划。若这些条件已经由两个工具的契约清楚表达,额外计划对象可能只增加同步负担。

建设任务组织的价值在于减少遗漏与无效选择。能否少做重复读取、能否在缺失材料时停止、能否保留用户纠正,才是应核对的效果。流程节点数量、agent 数量和计划文本长度不能替代这些判断。

目标和授权划定的是空间,先走哪一步仍要安排。Plan 是针对当前目标提出的候选步骤及其依赖关系。它不是已发生动作的记录,不是执行许可,也不是一份保证环境按预期变化的承诺。最小计划可以包含一个待满足条件、一项候选动作和判断完成的方法。

计划应按结果条件表达,不只列工具名。“取得两份指定来源的可用内容”比“调用两次读取”更明确,因为读取可能拒绝、取得错误版本或没有进入后续请求。“得到绑定当前修订的文件”也比“写文件”更明确,因为写入回执之后还需要核对实际对象。

模型可以生成计划,程序也可以为固定任务提供基础步骤。两者都只是组织依据。计划中的动作要到执行前重新经过当前修订、能力契约与预算检查。用户撤回以后,旧计划仍可留作历史材料,但不能继续执行。来源文本提出“改用其他工具”,也不能直接修改授权或计划约束。

计划的完成标记需要证据。读取完成应引用来源对象与版本,创建完成应引用动作与产物,验收完成应引用具体检查。模型声称“第一步已完成”可以作为它的叙述保留,却不能更新由程序维护的完成字段。计划状态与动作状态要分别保存,才能识别提议尚未执行、执行未知或结果不符合要求。

环境变化可以使计划需要修订。修订时保留变化原因和已成立条件,不把全部过程重写成仿佛从一开始就正确。当前程序对目标变更直接停止旧运行,不实现原地重新规划;本章的计划修订属于组织扩展,而不是对 Coordinator 现有行为的改写说明。

6.2路由与阶段

Routing 是在当前条件下选择下一项能力、方法或处理路径。它不是业务动作本身,也不是把任务交给另一个模型的同义词。最小路由可以是一个明确条件:材料未取得,选择读取;材料已发送且未创建,允许选择原文;结果未知,进入核对或停止。

路由与计划分别回答不同问题。计划提出较长过程的候选安排,路由作出当前一步的选择。计划说后面需要创建,不代表当前路由已经允许创建。先前结果已经满足某项条件时,也不必按计划文字重复调用。

可以用确定条件路由,也可以让模型在获准候选中选择。确定条件适合程序可核对的缺口,例如来源集合不完整、schema 不适配或当前修订失效。模型选择适合需要内容判断的差异,例如在合法原文中选哪一段。不要要求模型判断程序已经知道的授权版本,也不要把内容选择硬编码成声称普遍有效的规则。

能力路由需要第5章的实际契约,方法路由需要适用范围与依赖。候选工具名听起来合适,却接受任意路径或具有更宽效果时,不能按名称替换。方法要求额外发送材料,也要核对原授权。候选不足时可以停止或请求澄清,不通过隐式外联补齐。

路由结果还需要记录选择依据。最小记录指出采用的条件、选中能力或方法版本,以及不能走其他路径的原因。记录用于解释本次决定,不保证模型选择语义上最优。路由先确定这一步采用什么,候选目录与按需加载策略,再依第7章规则决定哪些细节进入请求。

选定能力之后,还要规定这一段从哪里进入、到哪里结束。Stage 是同一任务中具有局部目标、输入范围和出口条件的一段工作。它不是必然的新 agent,也不是按时间切开的几条消息。最小阶段包含进入条件、当前需要解决的问题、允许能力与退出判据。

阶段比计划步骤更关注实际控制边界。计划可以写“选择摘录”,阶段要说明选择依据所需的材料已进入请求、允许输出什么,以及结果怎样交给创建检查。进入阶段前缺少必需材料,应返回取得材料的路径,而不是让模型凭印象补写。

退出阶段也不能只靠模型宣布。内容选择阶段的结果是一份满足原文与来源条件的候选,创建阶段的结果是明确的动作结果,验收阶段的结果是对当前对象的检查。若返回未知,则退出结果是未知,需要停止或转入获准核对,不是自动进入下一成功阶段。

同一 agent 可以通过明确的阶段说明继续使用主线消息。阶段变化改变的是当前判断重点和允许操作,不自动建立新的身份、凭证或独立调度权。一个局部模型请求只看选定材料,仍可由同一主线调度;输入不同不等于多了一个能够自主行动的参与者。

第3章的读取、创建与完成三个阶段已经存在过程条件,但没有通用阶段对象。新增阶段结构应复用这些检查,不在外围再写一套可能冲突的“已读”与“已验收”。阶段怎样保留或退出局部材料,由第7章展开;本章只确定输入和出口必须可核对。

6.3固定 workflow 的保障范围

Workflow 是把部分步骤、依赖与合法转移显式固定的控制过程。它不是固定生成结果,也不是数据库事务。最小 workflow 可以只有两个节点、一条满足条件后的转移,以及一个明确失败出口。节点内部仍可能调用模型、等待外部服务或得到未知结果。

稳定 workflow 表示同类条件采用同类控制规则,不表示环境每次返回相同内容。读取可能失联,模型可能选择不同原文,文件创建可能失败,验收也可能发现对象变化。固定顺序不能消除这些差异,只能规定差异出现后怎样处理。

适合固化的部分是已经有明确前置与出口条件的重复过程。摘录任务中,取得材料后才允许选择,选择满足原文条件后才允许创建,创建后要重新验收。这些约束可以固定。到底选哪段原文,不必为了 workflow 完整而固定成某个子串;那会改变模型在任务中的职责。

workflow 节点也不是一条伪造的助手工具调用。若模型提出实际调用,保留它的 tool_call_id 并返回匹配结果。若程序主动调用固定工具,则记录程序发起的动作及依据,不编造模型曾经提出请求。两种发起方式可以采用相同工具契约,但来源和消息接续要如实表达。

固定过程不具备自动回滚。一个后续节点失败,前面的创建效果仍可能存在。把批次或 workflow 称为稳定,不等于跨工具事务成立。需要原子性或补偿时,应取得相应执行契约并在第11章处理,不能在转移表上画一条“失败返回”就宣称恢复原状。

6.4子流程与主线连续性

固定子流程是主线调用的一段具有明确入口和出口的局部过程。它不是另一个必须独立运行的 agent,也不因封装成函数就脱离主线授权。最小边界包含输入对象及版本、允许效果、返回结果和失败分类。

入口要传入具体条件,而不是整份未经解释的聊天历史。例如摘录子流程需要当前修订、来源集合、采用的方法版本、创建限制与验收范围。主线负责确认这些对象有效,子流程在开始效果前仍要核对所需条件。复制入口参数不等于冻结了所有外部授权变化。

出口应返回证据与局限。成功结果关联创建动作、来源快照、产物版本和验收边界。拒绝指出哪个条件未满足。失败注明已知结果及可能的部分效果。未知列出最后确认的边界。主线不能把所有非成功都折成“重新调用子流程”。

合法往返由条件决定。缺少未取得的材料,可以返回读取阶段;候选原文不合法,可以在剩余预算内返回选择阶段;已经创建而写入结果未知,不能返回创建阶段重做。流程图上的回边只表达候选路径,执行前还要确认这次回去是否有资格。

子流程结束后,主线重新检查当前目标与授权,再判断返回结果能否满足当前条件。子流程在旧修订下正确结束,不等于能完成新要求。若期间出现用户纠正,不能仅靠子流程内部的成功标记覆盖它。

这些边界可以通过同步函数和结构化结果建立,不要求安装 workflow 引擎。第3章目前由 Harness.loop、Harness.tool 与验收方法共同完成过程,没有一个通用子流程调用接口。本章提出封装时应保留的责任,而不是要求为了章节概念把现有程序拆成许多节点。

子流程有边界,主线自身的连续性要单独说明。同一 agent 的主线推进,是在共同任务身份与控制责任下连续处理发现、纠正和结果。它不是每一步都重发所有材料,也不是永远禁止局部请求。最小形态是一条可追溯的主线、当前有效条件及合法接续的消息关系。

共享消息的主要价值是后一步知道前一步已经发现什么。来源内容进入主线后,模型可以依据它选择原文;工具拒绝给出具体条件,后续可以针对条件修正;用户纠正改变任务要求,后续不能回到旧说法。若每步新开一个互不关联的请求,只给最初目标,这些事实会不断丢失。

共享也不意味着把各种来源提升为相同权力。用户纠正与工具结果承担不同责任,方法说明与来源文本也不同。程序接收授权变化,模型使用材料作内容判断。来源中出现命令语句,不能变成主线的新授权。消息来源与内容类型仍按第2章区分。

第3章的 history 保留助手提议与配对工具结果,见 book/v2/harness.py 的 Harness.loop。同时,当前协调者对目标变更采用停止,不是把新目标写入历史后继续执行旧任务。共享消息可以支持更广的连续组织,但不能据此宣称现有 CLI 已能接受任意目标并原地继续。

组织层应保留当前决定、依据和未解决条件,不要求在每个阶段重述全部历史。怎样在窗口限制内组装这些材料、怎样保持局部常驻和退出,由第7至9章处理。这里的原则只是:减少输入不能丢掉影响当前合法行为的纠正与事实。

6.5委派与异步返回

委派是主线把一项有明确边界的工作交给另一个执行单元,并约定返回结果。它不是复制一段上下文就自动产生的新 agent,也不是分工越多越好。最小委派包含子目标、输入范围、允许能力、返回要求和主线接收结果的条件。

默认不委派。多数连续任务的后一步需要前一步的发现与纠正,同一主线共享消息更直接。只有子工作相对独立,且独立上下文能减少干扰,或等待重叠有明确收益时,才值得增加边界。适合的候选可以是获准材料中一段长文的定向核对。若采用异步委派,还需确认主线在它返回前有独立可做的工作,或确有其他不必阻塞的处理。

判断时区分四个轴。独立上下文指子工作使用自己的输入与交互历史,作用是减少主线材料干扰。它不表示并行执行,也不保证权限隔离。两个请求使用不同消息,可以依次执行,并且仍使用同一套宽权限工具。

并行指执行时间重叠。它不要求独立 agent,也不必异步返回。一个固定工具内部并发读取材料,主线等待全部结果,就是工具内部并行。并行有收益还需要任务独立、资源可承受且结果能够关联,不能仅因机器允许多个进程就采用。

异步指发起后不必立即等待完成,结果稍后由明确通道返回。它不证明执行必然重叠,也不赋予返回端主线调度权。安全隔离则指不同执行单元的实际权限和资源被强制分隔。不同系统提示、不同上下文或不同名字都不能代替隔离机制。

四个轴可以分别选择。独立上下文但同步返回,可能足以减少长材料干扰;工具内部并行,不必增加子 agent;需要安全隔离的代码执行,即使同一主线调用,也要由第10章机制落实。本书不把它们合并成一个“多 agent”开关。

四个轴里,异步返回改变的是事实到达的时间。messagebox 在这里指发送子任务、取得受理标识并稍后接收结果的一种接口形态。它不是统一 API,也不是现有随书循环已提供的接口。最小接口语义需要说明提交什么、用什么关联返回、怎样查询或接收,以及失败、取消与未知怎样表达。

子任务输入要有边界。明确子目标、获准材料及版本、允许输出、可用能力和返回证据。若只是阅读探索,不应同时给它创建主产物的权力。返回应保留来源位置、版本、观察结论、不确定性与未完成条件。只交一段流畅摘要,会使主线无法区分证据与推测。

关联标识把子任务连接到发起它的主线与修订。接收返回结果时核对这些绑定、结果完整性及允许发送范围。子工作基于旧材料完成,其观察可以作为关于旧材料的事实保存;是否适用于当前目标需要另判断。事实入账不自动授权主线或子工作继续行动。

消息接续也必须如实。若委派来自一项实际模型工具调用,返回结果应匹配该调用。若委派由程序组织层发起,结果作为注明来源的外部材料进入,不补造一条助手调用来取得配对形式。模型格式合法性不能通过虚构发生过的请求来满足。

取消或等待超时不能证明子工作停止。接口需要说明停止请求能影响什么、是否存在未结束工作,以及怎样确认它已经结束。没有可靠回执时保留未知,不能换一个子任务编号就重新做可能有副作用的工作。主线也不能在同一个资源上同时启动冲突动作而只靠返回顺序解决。

第3章没有 messagebox 或异步接收器,随书局部 phase 实践也没有新增它们。现有循环只处理当前同步请求,旧修订不能调度,没有并发 resume 接口。迟到结果怎样仅入账、多更新者谁有调度权、重启后怎样确认旧执行者,由第11章建立可靠规则。接入异步服务时,需按其真实契约明确消息关联、结果接收与停止条件,不能仅凭接口名称假定这些条件已经成立。

6.6本章判据

组织层应使合法过程更清楚,而不是增加未经验证的自主权。

  • ☐计划是否只提出候选步骤,完成标记是否由动作与结果证据支持,而不是只依据计划文本认定?
  • ☐路由是否依据当前缺口选择能力或方法,是否重新核对效果与依赖而不是按名字替换?
  • ☐阶段是否有具体入口、允许能力与出口,同一阶段是否没有重复维护冲突事实?
  • ☐workflow 是否固定合法转移而不承诺确定结果,程序动作是否没有伪造模型 tool call?
  • ☐子流程是否保留版本、证据和失败类别,回边是否不把未知效果变成自动重做?
  • ☐共享主线是否保留发现与用户纠正,同时不把来源材料提升为授权?
  • ☐委派是否有可说明的独立性或异步收益,独立上下文、并行、异步与安全隔离是否分别判断?
  • ☐子结果是否经主线核对,事实入账是否不自动获得行动权,取消与超时是否不冒充工作已结束?

本章没有回答什么

本章没有建设多 agent 团队、通用调度平台或并发恢复系统。它没有证明增加计划、流程或委派一定改善效果;比较需要第12章的任务证据。局部材料怎样进入和退出由第7至9章处理;实际权限隔离由第10章处理;自动重试、迟到结果、多更新者与跨重启接手由第11章处理。组织流程稳定,不表示外部环境确定,也不表示跨步骤事务成立。

实践落点

第3章已有同一主线消息、串行工具调度、材料已进入请求的前置检查、当前修订检查及独立验收,原 Harness 没有显式 phase。随书 book/v2/capability_lab.py 的 CapabilityHarness.tool 根据确定观察到的 read_sources 与文件创建结果,选择 read、create、finish 三个局部阶段;CapabilityHarness.load_phase 只更新受控的 system 槽位,MethodPackage.load 只提供该阶段依赖的方法资源。它不代替模型提出调用,也不伪造 assistant 或 tool 消息,创建与验收仍沿原 Harness 完成。

这项局部实现可以直接核对。test_17_true_mcp_harness_run_and_phase_disclosure 检查三次实际请求中的阶段说明、按需资源和配对读取结果;test_18_method_text_does_not_allow_same_batch_create 检查同一批次先读后创建仍被拒绝。运行入口为项目根目录下的 python3 -I -B book/v2/test_capability_lab.py,该套件本轮18项通过。阶段改变说明重点,不替代“创建请求必须已包含所需材料”这一条件,也不构成完整 planner、通用 workflow 引擎、异步委派或并发接收器。模型响应仍为脚本,不能据此报告真实模型效果或用量。