主流智能体 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 缺少幂等接口,先验证业务唯一键与查重能力,再确定自动重试范围。
三阶段交付
- 只读原型。 接入一个模型和三个只读工具,用合成或脱敏案例生成证据与工单草稿,同时建立可重置的回放数据。
- 受控写入。 加入持久状态、审批、幂等与对账。测试越序、审批失效、响应丢失、重复请求、并发提交及进程重启。
- 实测后优化。 比较串行与并行,再按统一工具契约接入第二模型。角色分工有明确验收收益时,再评估多智能体。
对照实验如何判定收益
| 实验 | 固定条件 | 主要衡量 |
|---|---|---|
| 提示内 SOP vs. 外置状态机 | 同模型、同工具、同任务、同预算 | 业务终态正确且流程合规率,以及违规写入与恢复率 |
| 串行 vs. 并行取证 | 同模型、同工具、同状态机 | P95 延迟,以及正确率、重试与限流 |
| 主模型 vs. 第二模型 | 同 Harness、同工具契约、同回放样本 | 每个成功且合规任务的成本,以及合格率 |
| 重复运行 | 同任务独立重复并重置初始状态 | pass^k,即同任务运行 k 次均成功的概率,按任务平均 |
零未授权写入和零重复工单可作为测试环境的上线门槛。统计单位成功成本时,失败运行也计入总成本。该图和门槛为拟议方案,尚无实测结果。研究依据是 LLMCompiler 的依赖调度、有限状态控制 与 τ-bench 的终态和稳定性评测。
评论