Yingjie

主流智能体 Harness 架构

薛英杰 / 2026-11-22


Harness 是模型外层的执行系统,负责组装上下文、循环调用模型、执行工具、管理会话和检查权限。下图依据官方公开资料重绘,Claude Code 图着重于公开可观察的行为。优缺点是工程分析,性能和运行成本需要同任务实测。

1. OpenAI Codex

flowchart TD
    UI["IDE 或桌面客户端"] <-->|"请求、事件和审批"| APP["App Server · 双向 JSON-RPC"]
    APP <--> CORE["Codex Core · 模型与工具循环"]
    CORE <-->|"上下文和流式响应"| MODEL["Responses API"]
    CORE <-->|"调用与结果"| GATE["审批与工具策略"]
    GATE --> EXEC["受限环境中的 Shell 和文件操作"]
    GATE --> MCP["MCP 集成"]
    CORE <--> STATE["Thread 历史与事件"]
    STATE --> CTX["上下文组装与压缩"]
    CTX --> CORE

执行机制。 App Server 接收请求并管理 Thread。Core 循环调用模型和工具。一个 Thread 包含多个 Turn,一个 Turn 包含消息、工具调用、差异等 Item。客户端可消费 Item 的开始、增量与完成事件。待审批动作可暂停 Turn 直至收到应答。图采用公开的 App Server 集成路径,本地入口的连接方式可能不同。依据 App Server 设计 和 Codex 执行循环。

优点。 多端可复用同一运行时,并呈现实时进度、差异与审批请求。持久 Thread 支持重连和继续会话。
代价。 集成方要处理事件顺序、重连、审批应答和协议版本。业务写入是否真成功,仍需查询目标业务系统。

逐节点读图

图上节点或连线 它负责什么
IDE/桌面 ↔︎ App Server 客户端发起任务、显示流式进度、在需要时回答审批请求。双向 JSON-RPC 允许服务端主动要求输入,客户端无需为每次中间进度单独查询。
App Server ↔︎ Codex Core App Server 寻址并管理会话,把外部请求转成 Core 操作,再把运行时事件转成供界面消费的通知。Core 根据输入推进当前 Turn。
Core ↔︎ Responses API Core 组装指令、可见历史和工具定义。模型返回文本或工具调用。工具结果纳入下一次模型请求,模型据此调整后续动作。
Core ↔︎ 审批与工具策略 → Shell/文件、MCP 策略根据配置决定某次调用能否执行、是否需审批。允许后交给相应执行器。Shell 和文件操作涉及执行环境,MCP 连接器则有自己的工具权限和实际运行位置。返回值经工具通路回到 Core。
Core ↔︎ Thread 历史 → 上下文组装 → Core Thread 是可持续保存的会话容器。Turn 是用户发起的一轮工作。Item 是一条消息、工具执行或差异等有生命周期的条目。运行时从历史构造模型输入,在达到相应阈值时可压缩输入来继续执行。

运行示例。 用户在 IDE 里说“修复交付异常页面并运行测试”。客户端开始一个 Turn。Core 先让模型读取相关文件,返回结果后再提出修改。客户端可从 Item 事件分别显示读取、修改和测试进度。若某工具操作需要审批,服务端发起请求并暂停该轮工作。用户批准后操作继续,拒绝时 Core 接收相应结果,再决定能否用已授权手段完成任务。最终回复可依据测试退出状态和文件差异说明完成情况。

故障与恢复。 界面断开时,可重新读取 Thread 与已保存事件来重建时间线。流式文字代表当前输出进展,工具执行完成和业务结果需要各自的终态证据。例如,客户端看到“测试通过”的文字后,可进一步核对命令 Item 的结果。上下文压缩改变下一次模型可见的信息,重要的业务回执宜保留独立引用。依据 App Server 的会话原语和审批交互 与 上下文压缩和工具循环。

2. Anthropic Claude Code

flowchart TD
    UI["终端、IDE 或 SDK"] --> LOOP["Claude Code · 取上下文、行动、验证"]
    CTX["项目指令、Skills、会话历史"] --> LOOP
    LOOP <--> MODEL["Claude 模型"]
    LOOP --> POLICY["工具权限与生命周期 Hooks"]
    POLICY --> SHELL["Shell · 启用时受本地沙箱限制"]
    POLICY --> TOOLS["文件工具、MCP 和子智能体"]
    SHELL -->|"执行结果"| LOOP
    TOOLS -->|"工具结果或子任务摘要"| LOOP
    LOOP --> HISTORY["会话记录与上下文压缩"]
    HISTORY --> CTX

执行机制。 Claude Code 反复获取上下文、行动与核验。项目指令和 Skills 为模型提供项目知识与专项流程。PreToolUse 在适用的工具执行前触发,可参与限制执行。子智能体能在独立上下文承接子任务,再返回结果。官方说明,本地 Shell 沙箱覆盖 Shell 命令,文件工具、MCP 服务器和 Hooks 在该沙箱之外运行。依据 运行机制、Hooks 和 沙箱范围。

优点。 项目规范、专项流程、执行前校验与子任务分工各有对应扩展点。
代价。 权限、Hooks、连接器和沙箱的作用域需要联合测试。上下文压缩和子任务摘要可降低输入量,关键原始证据仍需单独保留。

逐节点读图

图上节点或连线 它负责什么
终端、IDE、SDK → Claude Code 将用户任务送进同一类执行循环。SDK 让业务程序接入 Claude Code 的工具、会话和审批机制。图中客户端到循环的箭头着重显示任务输入,应用也可以消费输出。
项目指令、Skills、会话历史 → 循环 项目指令提供约定。Skills 让特定工作需要时装入专项内容。会话历史给出已执行动作。文档中的流程提示会影响模型选择,强制限制由可执行权限或校验承担。
循环 ↔︎ Claude 模型 Harness 提供上下文和工具。模型根据先前观察选择下一步,可能在多轮中交替读文件、修改和验证。取上下文、行动与验证是行为阶段,顺序可随任务调整。
循环 → 工具权限与 Hooks → 执行 模型生成工具名和参数后,适用的 PreToolUse Hook 有机会检查或拦截,权限模式也参与决定。本地 Shell 沙箱启用时限制命令及子进程的文件和网络访问。文件工具、MCP 和 Hooks 各有自己的权限边界。
文件、Shell、MCP、子智能体 → 循环 普通工具回传文件内容、命令输出或外部服务结果。子智能体使用独立上下文承接工作,并将结果交还主会话。子任务若需供人复核,可以返回证据路径和可重跑命令。
循环 → 会话记录与压缩 → 上下文 会话记录支持恢复、回看和分叉。压缩处理模型输入容量。官方 Hooks 也提供压缩前事件,用于在适用时执行用户配置的逻辑。

运行示例。 同样修复交付异常页面。项目指令规定改动需有回归验证,相关 Skill 可以提供测试入口。主循环读取代码后生成编辑调用,其参数可接受执行前检查。若将日志梳理委派给子智能体,主会话根据返回的摘要和原始日志路径决定下一步。修改后以测试结果判断是否还需继续。

故障与恢复。 在执行被拦截时,工具拒绝是可观察结果,主循环可以改用权限范围内的动作或请用户处理。权限审批、执行沙箱、MCP 的服务账户属于不同控制面。针对已有配置,分别验证每个入口实际能读取和写入什么,尤其是 Hook 自己启动的程序及外部工具。依据 Claude Code 运行机制、Agent SDK、Hooks 与 沙箱范围。

3. DeepSeek Harness

flowchart TD
    UI["Desktop、Web、Headless 或 SDK"] --> PROFILE["Profile、Bundle 与配置补丁"]
    PROFILE --> PLUG["Cordis 插件树 · 服务与事件"]
    PLUG --> LOOP["AgentLoop 插件"]
    PLUG --> POLICY["工具与策略插件"]
    LOOP <--> MODEL["模型适配器"]
    LOOP --> POLICY
    POLICY --> TOOLS["工具注册表和执行管线"]
    TOOLS -->|"执行结果"| LOOP
    LOOP -->|"追加已提交事件"| LOG["SessionEvent 日志"]
    LOG -->|"投影模型上下文"| LOOP
    LOG -->|"会话视图"| UI

执行机制。 DeepSeek 官方开源 Harness 用 Cordis 组合服务和类型化事件。Profile 选择 Bundle,配置补丁可以增补或覆盖插件。模型适配器、提示拼装、工具注册表、循环和会话日志均有插件扩展点。调用依次经过执行前、执行中、执行后管线。会话事件用于投影模型消息和恢复会话。瞬时流式增量与持久日志有不同生命周期,进程在提交前中断时,未提交的增量可能丢失。依据 官方主页 和 源码架构文档。

优点。 组件替换面广,适合试验模型、工具管线和执行环境。持久事件有助于重放和追踪。
代价。 插件初始化、依赖、卸载和版本兼容需要工程测试。外部工具的副作用仍需业务对账。官方主页将产品描述为公开预览,测试应记录版本和启用的 Profile。

逐节点读图

图上节点或连线 它负责什么
入口 → Profile、Bundle、配置补丁 图的上半部分描述启动时的组装。Profile 选定运行形态及各层 Bundle,Bundle 提供一组插件,配置补丁针对已有条目调整或增补。Web 和不带界面的 Headless 可以使用不同组装结果。
配置 → Cordis 插件树 → 循环与策略 Cordis 让插件注册服务、发布类型化事件并管理生命周期。工具注册、模型适配、提示组装和会话等模块通过服务接口组合。图中的两条箭头体现它们可以在启动时分别挂载。
AgentLoop ↔︎ 模型适配器 运行时从输入队列获取任务,选择会话指定的模型,拼装提示和当步可用的工具定义。对已组装请求发起流式调用。一个 Step 包括一次模型请求及其触发的工具调用,一个 Turn 可以包含多个 Step。
AgentLoop → 工具与策略插件 → 注册表和管线 → AgentLoop 循环提交调用,工具管线提供执行前、执行中及执行后扩展点。作用域决定该代理能发现哪些工具,策略处理执行条件。结果作为事件记录,并可在后续 Step 反馈给模型。
循环 → 日志 → 模型上下文/会话视图 SessionEvent 追加已提交事实。投影是按规则将日志转换成一种视图,模型消息和界面会话可以从同一份事实生成不同视图。面向界面的即时文字增量还可通过实时流提供。

运行示例。 开发团队把模型适配器、文件工具、日志存储与规则插件装进一个 Profile。用户请求修复交付异常页面时,AgentLoop 先读取已提交会话信息,组装本步工具列表,然后调用模型。模型提出文件读取与测试操作,工具管线执行并记录结果。下一 Step 从日志投影出当前上下文,继续做修改或产出回答。替换模型适配器时,保留同一套工具与测试数据,便于观察模型变化对执行结果的影响。

故障与恢复。 已提交事件可以支持恢复,实时增量在进程终止前若未写入持久日志,可能无法从日志恢复。若中断发生在外部工具已经写入、但 Harness 还没记录回执时,要按目标系统业务键对账。图只描述 Harness 内部记录和投影关系,外部系统的一致性仍由工具适配器和业务协议承担。依据 DeepSeek 官方架构的 Profiles、Turn Flow、Session Log。

4. OpenCode

flowchart TD
    UI["应用客户端"] <-->|"请求与事件流"| API["Server API 或进程内 SDK"]
    API <--> SESSION["会话与项目工作区"]
    SESSION --> AGENT["主 Agent 与子 Agent"]
    AGENT <--> MODEL["Provider 层 · 多家模型"]
    AGENT --> PERM["工具权限规则"]
    PERM --> TOOLS["内置工具、Shell 和 MCP"]
    TOOLS -->|"执行结果"| SESSION

执行机制。 OpenCode 提供服务器接口及进程内 SDK。会话关联项目位置,SDK 可接收运行事件。配置模型供应商、代理与工具权限后,OpenCode 负责执行循环。接入 DeepSeek 模型时,OpenCode 仍是该配置的 Harness。依据 SDK、API、供应商 和 权限。

优点。 契合多模型对照和应用内嵌,能够复用会话、工具和事件接口。
代价。 各模型的工具调用、流式响应和错误语义可能不同。官方文档说明 Shell 继承宿主用户的文件、进程与网络权限,部署时需要单独确认进程隔离。

逐节点读图

图上节点或连线 它负责什么
应用客户端 ↔︎ Server API 或 SDK 应用提交任务、管理会话并消费事件。网络客户端通过服务端接口交互,进程内 SDK 将 OpenCode 组装进宿主应用,通过内存 HTTP 路由调用,无需再开额外的网络监听。
API ↔︎ 会话与工作区 → Agent 会话定位到任务相关工作目录,关联此前交互。主 Agent 处理当前任务,子 Agent 可以有自己的工具权限配置。将外部工具和子 Agent 放进同一会话体验,需要区分实际执行身份。
Agent ↔︎ 多模型 Provider Provider 适配不同模型服务。模型接收上下文和工具定义,返回文本或调用请求。更换 Provider 会影响模型输出、计量和错误行为,业务流程与权限策略可继续由同一 OpenCode 宿主管理。
Agent → 工具权限 → 工具 访问规则决定允许、询问或拒绝。内置工具、Shell 和 MCP 各自执行受准入的动作。宿主进程隔离和工具层权限应分别部署与测试。
工具结果 → 会话 → 下一轮 文件内容、命令结果和错误进入会话,成为继续决策的反馈。用户界面从事件流获取进度。耗时和成功条件可由宿主进一步记录。

运行示例。 同一份交付异常页面进入 A/B 实验。为模型 A 和模型 B 分别创建会话,各用同一个工作区初始快照、同一个工具集和权限规则,给出同一条修复请求。记录每次工具调用、文件差异和测试结果,再用相同的断言判断两个任务是否完成。独立会话和初始工作区可避免前一次修改影响后一轮比较。

故障与恢复。 若某 Provider 返回不可解析的工具参数,将其作为调用失败记录,保留当前会话与工具权限。基准中可按错误类型区分供应商调用失败、权限拒绝和真实业务测试失败。使用 Shell 时同时检查进程实际权限,尤其是宿主挂载、网络访问和凭据暴露范围。依据 OpenCode SDK、API、Provider 接入 与 权限说明。

5. 架构取舍

对象 核心设计 有利场景 主要工程代价
Codex 双向 App Server,Thread / Turn / Item 多端实时交互、审批与重连 事件顺序、协议兼容、恢复逻辑
Claude Code 项目上下文、Hooks、子智能体 项目规范、执行前校验、子任务委派 配置组合、沙箱作用域及连接器权限
DeepSeek Harness Cordis 插件树、工具管线、追加式事件 可替换的运行时、研究原型和回放 依赖、生命周期、版本回归和副作用对账
OpenCode 多 Provider、服务器 API、嵌入式 SDK 多模型对照、自建界面 跨模型契约差异与宿主隔离

比较方法。 测 Harness 时尽量固定模型版本、工具权限、任务与预算。测整体产品时可使用各自原生配置,记录不同之处。架构图仅支持结构分析,无法据此给成功率、延迟或价格排名。

6. 面向垂直智能体的改进方案

选用供应商交付异常调查与工单提交作为落地示例。模型提出下一步,持久化流程检查能否推进,目标业务系统确认工单是否已写入。这个架构也适用于更换证据源和审批规则后的应急辅助流程。

flowchart TD
    API["工作台与事件流"] <--> FLOW["持久化业务状态机"]
    FLOW <-->|"候选动作与约束"| PLAN["单智能体计划与模型适配"]
    FLOW <-->|"版本、证据和回执引用"| LOG["状态库与审计日志"]
    FLOW -->|"允许的动作"| GATE["工具网关"]
    GATE --> READ["并行查订单、库存和物流"]
    READ -->|"证据、来源和时间"| FLOW
    FLOW <-->|"审批或驳回"| HUMAN["人工审批"]
    GATE -->|"校验审批与幂等键"| WRITE["ERP 工单适配器"]
    WRITE -->|"回执或待对账"| FLOW

逐节点读图

图上节点或连线 发出什么、接收什么
工作台 ↔︎ 业务状态机 工作台提交订单号,也接收“取证中、待审批、已确认”等结构化进度事件。状态机持有流程的转换规则。
状态机 ↔︎ 单智能体与模型适配 状态机提供当前阶段、可用证据和候选工具范围。模型返回拟调用动作、参数或草稿。状态机按当前状态、权限和数据完整性检查动作。
状态机 ↔︎ 状态库与审计日志 状态库保存当前版本、审批绑定和回执。审计日志保存状态变化与证据引用。模型上下文压缩或进程重启后,可从这些记录恢复。
状态机 → 工具网关 → 并行查询 → 状态机 网关检查接口权限和参数并执行查询。订单、库存和物流在共享前置条件满足后并行开始。每路返回来源、记录时间和结果。已成功的分支可复用,未成功的只读分支可按策略重试。
状态机 ↔︎ 人工审批 审批界面展示待审草稿及证据。批准或驳回以结构化结果返回,系统可校验审批所对应的案件、动作与草稿版本。
网关 → ERP 工单接口 → 状态机 写入前校验审批仍有效,并使用稳定幂等键。ERP 返回业务回执或待确认结果。超时进入待对账,查询目标系统后再更新案件状态。

一次完整运行。 用户选择 PO-1042。状态机创建案件并并行查询订单、库存与物流。示例中,订单已晚于承诺日期,库存不足,物流显示未发运。模型据此生成工单草稿,关联三条证据。人工批准该版本后,网关才调用 ERP。ERP 回传工单编号后,状态机落库并推送“已确认”。PO-1042 和查询结果均为演示数据。

分支场景 系统实际动作 用户看到的状态
物流查询超时,其他两路成功 保存订单和库存证据,仅重试物流查询。仍缺关键证据时停在取证阶段。 待补证
审批驳回或草稿内容改动 驳回回到修改环节。草稿更新后,原审批失效并等待新版本审批。 驳回待修改或待审批
ERP 写入后,返回途中超时 保持相同幂等键,通过案件业务键查原请求结果。查到对应工单时记录回执,无法确认时继续对账或转人工。 待对账或已确认
运行进程在等待审批时重启 重新加载案件、证据、草稿版本和审批记录,恢复等待或继续下一合法步骤。 原审批进度

图要表达的完成条件。 模型回复完成表示本轮推理结束。流程完成表示所有必须步骤已通过校验。只有业务回执可核验时,示例中的 ERP 工单才进入“已确认”。这三个时点分开记录,能解释界面显示、运行轨迹和业务数据库为何可能暂时出现不同状态。架构与异常行为是设计方案,需用后文的故障注入和回放验证。

优先级与验证

优先级 改进 设计与异常处理 验收测试
P0 业务状态外置 保存案件 ID、状态版本、证据引用、审批版本与业务回执。上下文压缩或进程重启后,从状态库恢复。 越序动作、过期审批和跨案件证据引用被拦截,合法的中断任务可恢复。
P0 审批绑定和幂等写入 审批绑定案件、动作及草稿版本。草稿改动需要重新审批。重复请求使用同一幂等键。超时进入待对账,查询原写入结果。 注入丢失回执、重复投递和并发写入,检查无未授权或重复工单。
P1 依赖调度 定义工具输入、输出、超时、错误与副作用。订单编号确认后并行取数。只重试失败的只读分支,关键证据缺失时进入待补证。 同模型同任务比较串行和并行的 P95 延迟、调用量和证据完整率。
P1 类型化事件 记录状态变化、工具结果引用、审批动作和业务回执。界面从事件流展示进度。 按运行编号复盘每次迁移,能核对审批与写入顺序。
P2 模型适配 先接一个主模型,再用工具契约测试接入第二模型。在安全的推理步骤边界切换,重新读取已提交证据。 配对比较单位成功任务成本、调用量及合格率。模型切换时权限保持一致。

主流程为受理 → 取证 → 核验 → 待审批 → 提交 → 已确认,另设待补证、审批驳回和待对账。已确认以业务回执或对账结果为准。如果 ERP 缺少幂等接口,先验证业务唯一键与查重能力,再确定自动重试范围。

三阶段交付

  1. 只读原型。 接入一个模型和三个只读工具,用合成或脱敏案例生成证据与工单草稿,同时建立可重置的回放数据。
  2. 受控写入。 加入持久状态、审批、幂等与对账。测试越序、审批失效、响应丢失、重复请求、并发提交及进程重启。
  3. 实测后优化。 比较串行与并行,再按统一工具契约接入第二模型。角色分工有明确验收收益时,再评估多智能体。

对照实验如何判定收益

实验 固定条件 主要衡量
提示内 SOP vs. 外置状态机 同模型、同工具、同任务、同预算 业务终态正确且流程合规率,以及违规写入与恢复率
串行 vs. 并行取证 同模型、同工具、同状态机 P95 延迟,以及正确率、重试与限流
主模型 vs. 第二模型 同 Harness、同工具契约、同回放样本 每个成功且合规任务的成本,以及合格率
重复运行 同任务独立重复并重置初始状态 pass^k,即同任务运行 k 次均成功的概率,按任务平均

零未授权写入和零重复工单可作为测试环境的上线门槛。统计单位成功成本时,失败运行也计入总成本。该图和门槛为拟议方案,尚无实测结果。研究依据是 LLMCompiler 的依赖调度、有限状态控制 与 τ-bench 的终态和稳定性评测。

评论