Harness 与 Agent 参考架构

一句话：Agent 不是“模型 + 一段很长的提示词”，而是模型外面那层把判断组织成可执行、可恢复、可验证任务的 Harness；架构的第一件事不是选框架，而是划清模型、Harness、Runtime、沙箱和平台各自担什么责。

为什么需要

Demo 里的 Agent 只要“能跑一次”就够了。进入生产后，问题会变成另一组：任务跑到一半进程被杀，能不能续；两个任务同时改同一个仓库，会不会互相覆盖；模型调用的到底是哪个版本，出了问题能不能复现；换一个模型或运行时，任务逻辑要不要重写；出了事故，责任落在模型、编排、运行环境还是业务验收。

这些问题的共同点是：能力被做出来了，但责任没有落位。没有责任边界，团队只能在每次故障后临时打补丁；而补丁越多，系统越难解释。Harness 和参考架构解决的正是这件事：先把“谁决定下一步、谁保存事实、谁限制影响范围、谁对结果签字”分开，再谈用哪个框架。

核心机制

五个层次：先分清谁负责什么

层	负责	不负责	常见混淆
Model	理解与推理，产出下一步意图	持久状态、权限、执行	把模型当工作流引擎
Harness	组装上下文、驱动循环、调工具、做验证与恢复	提供算力与隔离	把 Harness 等同于框架或系统提示词
Runtime	让任务持续运行：调度、状态、工作区、恢复	决定业务上“做什么”	把容器当 Runtime
Sandbox / Environment	限定行动的影响范围：文件、网络、凭证	判断任务是否成功	把沙箱当安全兜底的全部
Agent Platform	规模化交付：身份、版本、配额、审计、观测	替业务定义正确性	平台建得越早越好

边界是逻辑边界，不一定对应独立产品。一个人可以同时实现 Harness 和 Runtime，但架构上仍要能回答：这次故障该归到哪一层。否则所有问题都会被归因成“模型不行”。

五层不能合并成两层的根本原因，是四类故障的修法互不相同：模型答错要换模型或改 Prompt，Harness 漏验证要补检查器，Runtime 恢复不完整要改状态机与检查点，沙箱权限过宽要收紧环境配置。层数不是抽象洁癖，而是归因词汇表——说不清故障在哪层，就开不出正确的修复工单。

横向再切三个视图：组件图回答“有没有漏能力”，平台图回答“谁运行、谁负责”，生命周期图回答“怎么从一次演示变成可运营系统”。能力落到五个责任域（业务与应用、构建与编排、生产运行、治理与控制、调优），平台职责分成执行面、数据资源面、控制面。安全不是某一层的一个组件，而是横切这五层的约束；三个视图不能互相推导，否则会把“部署失败”和“能力缺失”混为一谈。

Harness 与 Payload：哪些改动不该走发版

实际需求：业务规则（话术、工具说明、评测用例、某个 Skill 的步骤）一周改三次，而 Harness 的管道、权限、状态机一年改不了几次。如果两者同生命周期，每次改提示词都要走代码评审、打包、发布、回滚，响应速度被基础设施拖住。

归 Harness（代码与发布）	归 Payload（配置与热加载）
循环结构、状态机、节点编排	System Prompt、Skill 正文
工具注册、权限校验、审批流	工具描述、参数说明、few-shot 示例
持久化、恢复、运行时	评测集、评分规则
沙箱、凭证注入	租户级话术、术语表

Payload 要可版本化、可按环境与租户寻址、可灰度、可回滚；Harness 只负责“什么时候把哪份 Payload 装进上下文、装之前检查什么权限”。这样业务规则变更不必等代码发版。

但热更新不等于免评测。Payload 仍要进版本库、挂评估基线、走灰度和回滚；换一个 Skill 文件也不等于换整个 Agent——工具、权限、状态和运行时都没变，只是模型看到的内容变了。把 Payload 当“不用测试的配置”，是这类架构最常见的翻车方式。

切分线画在哪、为什么热更新不能免评测：切分线是契约，不是文件类型。判断标准只有一条——这次变更是否需要管道代码配合生效。需要（新增工具要注册鉴权、状态机要加迁移）归 Harness；不需要（改文案、改示例、改评分权重）归 Payload。而"发布成本下降一个数量级"的另一面是故障发现成本同步上升：走发版的变更有评审、CI、预发环境兜着，热加载的变更直接进运行时——省掉的每道关卡都要用评测和灰度补回来，否则只是把事故从发布日挪到任意一个改文案的下午。

“无特权内核”不是“没有内核”

常见误读：插件化 Harness 说“无特权内核”，听起来像把内核也拆掉。准确含义是没有哪个业务组件比其他插件高一级——摘要、检索、审批、某个垂直 Skill 都通过同一套注册与调用协议接入，不能靠改内核代码获得特殊路径。内核仍然存在，只是只保留与业务无关的机制：依赖注入、组件生命周期、事件总线、配置加载、错误传播。

扩展粒度也随之变化：固定 hook 位（LangGraph、Spring AI 这类图运行时）要求你“在给定位置插逻辑”；插件化运行时允许你“换掉整个组件”。前者边界清晰、可预测，后者灵活但要求组件契约稳定。二者是扩展点粒度不同，不是先进与落后。

八个构建对象，收敛成三个能力域

新项目先填一张检查表，而不是先选框架：

对象	要回答的问题	落到哪
Agent Contract	为谁工作、目标、允许与禁止	业务 + 控制
Execution	循环、状态机、预算、终止	执行与编排
Context & State	每轮看到什么、事实存在哪	上下文与状态
Capability	Tool / MCP / Skill / Subagent	行动与反馈
Environment	在哪运行、能碰什么	运行与沙箱
Control	以谁的身份、哪些动作要审批	治理
Interaction	人怎么看进度、怎么干预	产品 + 运行
Quality	怎么证明完成	评测与验收

这八项收敛成三个能力域：执行与编排、上下文与状态、行动与反馈。它们正好对应本专栏的 01–06 篇；如果一张检查表填不满，先补责任，不要先加 Agent 数量。

Agent Release：最小可复现单元

一次 Agent 发布不能只版本化 Prompt。至少要绑定六类要素：

六类要素缺一类，复现就会断：只换模型不换评估基线，无法判断是模型变强还是任务变简单；只版本化 Prompt 不版本化工具权限，同一份 Prompt 在不同环境里行为不同。调优产生的新版本必须回流到构建、重新过门禁，而不是让 Agent 在生产里改自己。

四类构建入口与部署位置

• 高代码框架：自己实现 Harness，代码级控制循环、上下文、权限与验证；适合深度定制、数据与执行环境自控。
• 产品化 Harness：复用现成的工作区、规划与工具执行；适合嵌入现有应用，但可定制边界由产品决定。
• 托管 Agent：把约定范围内的 Harness 与运行资源托管出去；适合异步、批量、快速生产化，但数据边界与验收责任仍在企业。
• 云平台构建：从创建起就进入统一的身份、版本、配额与治理体系；适合规模化，但迁移成本最高。

四类不是成熟度阶梯，也不互斥。选择时只问三件事：通用行为谁来写、运行谁来承载、企业还要补哪些责任。Managed 不等于把责任也托管出去。

Harness 本身放哪，则是另一个取舍：

形态	典型场景	好处	代价
客户端 Harness	IDE、桌面工具、单机 Agent	低延迟、能碰本地文件与凭证、离线可用	版本分散、权限与审计难统一
云端 Harness	多租户 SaaS、企业统一平台	统一身份/配额/审计、集中升级	延迟、数据出域、本地能力要桥接

多租户企业通常倾向云端统一治理；单机或 IDE 产品通常把 Harness 放客户端，云端只做模型网关与评测。混合形态（云端编排 + 本地执行器）也常见，代价是两侧契约必须版本化。没有单向唯一答案。

实战场景

案例：把容器当架构——3 小时定不出这一层归谁

现象：一次“Agent 恢复后行为不一致”的事故，复盘会开了 3 小时（经验值，需校准）定不出责任层：有人说模型不稳定，有人说 Pod 被驱逐，有人说业务 Prompt 有问题。工单派给业务组改 Prompt，回滚无效；真实缺陷在 Runtime 层的检查点没有保存工具状态。事故本身 40 分钟，归因空转 3 小时，方向改错又白跑两天。

排查过程：用的不是“我们有哪些容器”，而是五层表的“负责 / 不负责”两列做逐层排除。四类故障的修法互不相同，所以每层都要同时给出判据和它对应的修法族：

层	判据（这一层能不能解释现象）	现场证据	结论与修法族
Model	同一上下文重放是否仍产出错误的下一步	固定输入重放 3 次行为一致	排除；否则才是换模型或改 Prompt
Harness	恢复时组装给模型的上下文是否完整	恢复后缺工具状态段	现象在此层暴露；补检查器与验证
Runtime	检查点持久化了哪些字段	waiting、paused 要求保存完整上下文，落库只有中间结果与计划	定位在此层；改状态机与检查点
Sandbox	文件、网络、凭证范围是否变化	环境镜像与凭证策略未变	排除；否则收紧环境配置
Platform	版本与实例调度记录	确有 Pod 驱逐，但驱逐只决定何时恢复，不决定恢复成什么	诱因，非根因

对症做法：事故单强制填写故障层与修法族两列，二者都取自五层与四类故障的对应关系。

incident_ticket:
  required: [fault_layer, fix_family, evidence_ref]     # 层与修法族必须成对出现
  forbidden_values: ["环境问题", "模型不行"]              # 空泛归因直接退回重填
  cross_check: 平台层的调度事件可以解释发生时机，不能解释恢复内容；两者分列填写

复盘要点：层数不是抽象洁癖，是归因词汇表——说不清故障在哪层，就开不出正确的修复工单。这次真正的成本不是 40 分钟故障，是“所有问题都被归因成模型不行”之后那两天的无效修复。一个人同时实现 Harness 和 Runtime 完全合法，但恢复字段清单仍要分层写，否则恢复语义没人负责。

案例：热加载改了话术、例行升级换了档位——两周静默退化

现象：运营把租户话术 Skill 走热加载上线，当天生效、未走发版；同一晚平台把某档位的推理服务做了例行升级。两周内任务成功率从 0.86 跌到 0.79（经验值，需校准），期间没有任何发布事件、没有触发任何告警，周报把它写成“模型质量波动”。

排查过程：先按切分线判两个变更归谁，判据只有一条——这次变更是否需要管道代码配合生效。话术 Skill 不需要：工具、权限、状态、运行时都没变，只是模型看到的内容变了，归 Payload，热加载合规。推理档位需要：它改的是 Release 六元组里的模型与参数，路由与配额要跟着动，属发版范畴，却以基础设施例行升级的名义绕过了门禁。变更归类完成后，再查归因为什么会断——六元组绑定字段缺两项：模型只记服务名不记档位与版本，评估基线沿用上一版没更新；这正是“只换模型不换评估基线，无法判断是模型变强还是任务变简单”的镜像形态，退化同样被基线缺失掩盖。用固定 Harness、固定话术、只切档位跑同一黄金集，成功率差与线上一致，定位在模型与参数这一项。

对症做法：把“省掉的每道关卡都要用评测和灰度补回来”落成热加载入口的硬约束，两类变更各补各的。

payload_hot_update:            # 合规热加载：免发版，不免门禁
  gates: [in_version_repo, eval_baseline_attached, canary_then_full, rollback_ref_ready]
  block_if: eval_baseline_missing
  canary: {tenants: 2, min_hours: 24, metrics: [任务成功率, 追问率, 高风险动作确认率]}  # 阈值经验值，需校准
infra_change:                  # 触及六元组任一项，一律按 Release 变更处理
  release_tuple: [模型与参数, harness编排, prompt策略, 工具与权限, 运行环境, 评估基线]
  admission: 重过门禁，不通过回到构建；调优产生的新版本必须回流
  silent_upgrade: forbidden    # 任何改变模型行为的组件换版都算一次发布

复盘要点：发布成本下降一个数量级的另一面是故障发现成本同步上升。这次两周静默退化说明热加载真正该省的是评审与打包，评测和灰度一道都不能省；没有版本库与基线的热更新只是把故障从发布时挪到运行时，这里挪成了任意一次基础设施升级。

案例：同一条权限策略两处实现——事故里没人认领审批

现象：平台组、算法组和两个业务组共管一个仓库，Harness、Runtime 与沙箱配置混在同一层目录里。一次“高风险动作在审批前被执行”的事故，值班 2 小时（经验值，需校准）内找不到该找谁：审批判断这段逻辑归谁没有答案。实际缺陷是 Harness 的审批流读到一份沙箱层自己实现的宽松“权限”配置——同一个概念两处实现，取值不一致。

排查过程：这类问题不能用组件图回答（它只回答有没有漏能力），也不能从平台图直接推导（它回答谁运行、谁负责），三个视图不能互相推导，否则会把部署失败和能力缺失混为一谈。要核对的是责任而不是文件位置：

要回答的问题	正文的责任归属	现场状态
谁决定下一步能不能执行	Harness：工具注册、权限校验、审批流	两处实现，取值不一致
谁限制影响范围	Sandbox：文件、网络、凭证	自行复制了一份权限判定，越界
谁对结果签字	Quality 与评估基线	空缺，无人签字
谁保存事实	Runtime：状态与工作区	审批未决时的任务状态未定义，应落 waiting

判据一条：同一条策略在两个层里都能改对，就是职责混写；此时任何求快的补丁只会加深不一致。

对症做法：按负责与不负责两列写契约，权限判定只保留一处实现，并给审批未决一个确定状态（沿用 05 篇的 10 态口径，不自造状态）。

ownership:
  harness: {owns: [loop, tool_registry, permission_check, approval_flow, verification]}
  sandbox: {owns: [fs_scope, network_egress, credentials],
            must_not: [判断任务是否成功, 自行实现权限判定]}
  runtime: {owns: [schedule, state, workspace, recovery]}
  single_source: 权限判定只允许一处实现，其余层调用取结论，禁止复制逻辑
approval_pending: running -> waiting     # 确认到达才 running -> running，拒绝则转 cancelled

复盘要点：边界是逻辑边界，不一定对应独立产品，所以一人兼写 Harness 与 Runtime 合法；不合法的是同一职责两处实现、以及审批未决没有落状态。层归属是契约，不是文件类型或目录位置——该找哪个团队的判据来自契约写在哪个层，正文那句“先定边界，再选框架”同样适用于定人。

最小上手

新项目先用一页纸填完下面九项，再决定用什么框架：

1. Contract：为谁工作；目标；明确不做的事；失败时谁能叫停
2. Loop：Prepare → Model → Act → Observe → Verify；终止条件与预算
3. State：哪些事实必须落库；哪些只是本轮上下文
4. Capability：需要哪些 Tool / MCP / Skill；每个的权限与超时
5. Environment：容器还是 worktree；能否出网；凭证从哪来
6. Control：哪些动作必须审批；审批未决时任务是什么状态
7. Interaction：人从哪里看进度、暂停、改目标
8. Quality：完成由哪些证据判定；谁签字
9. Release：模型 / Harness / Prompt / 工具 / 环境 / 评估基线六元组

跑通判据不是“Demo 成功”，而是：杀掉进程后能从权威状态恢复；同一 Release 重跑能得到可比较的结果；高风险动作在审批前不会执行；完成后能拿出环境证据，而不是模型说“已完成”。

生产动作

• 先定边界，再选框架：架构评审时要求画出五层责任与三个平面；任何一层缺失，都要写明由谁临时承担。
• Payload 与 Harness 分开管理：Payload 进版本库、进评测、走灰度；Harness 发布只改管道与权限。两者混在一起，回滚会互相牵连。
• 编排与 Runtime 解耦：任务逻辑不依赖某个运行实例；状态外置，执行实例可替换。
• 权限与验证是运行前提：最小权限、短期凭证、沙箱、审批、审计在首发前到位，不要等上线后补。
• Release 六元组进版本库：每次发布记录模型、Prompt、工具权限、环境镜像、评估基线；没有基线不允许上线。
• 观测前置：Trace 至少覆盖入口、模型调用、工具调用、状态变更、人工卡点与验收证据；先能解释，再谈优化。

边界

• Harness 不是更长的系统提示词：提示词只影响模型看到什么；Harness 还包括状态机、工具注册、权限检查、错误恢复与完成验证。
• 框架不是架构：选 LangGraph 还是自研，只决定 Harness 的一部分怎么实现，不决定责任边界。
• 热更新有成本：Payload 能热加载，但灰度、回滚、评测基线一个都不能省；没有版本库的“热更新”只是把故障从发布时挪到运行时。
• Managed 不是免责：运行托管出去，数据边界、任务目标、审批与验收仍在企业。
• 平台不要过早建：一个团队、两三个 Agent 时，先用手工约定和现成工具；等到多团队、多 Agent 出现身份、配额、审计重复建设，再上平台。
• 常见误区：把 Workflow、Agent、Hybrid 当成应用形态，其实它们是路径控制方式；把沙箱当安全全部，忽略凭证与出网；把“能演示”当成“可运营”。

讲清楚

Agent 的核心不是模型，而是模型外面的 Harness：它决定下一轮给模型什么、允许它做什么、任务怎么推进、失败怎么恢复、完成由谁证明。架构上先分五层——模型、Harness、Runtime、沙箱、平台——再分三个平面：执行面跑循环，数据面存事实，控制面管身份与策略。Prompt、Skill、工具描述和评测集是 Payload，可以热更新，但仍要版本、基线和灰度；Harness 只留管道、权限、状态与恢复。所谓无特权内核，是没有业务组件高于其他插件，不是没有内核。Harness 放客户端还是云端，取决于治理半径和本地能力谁优先。发布时把模型、Harness、Prompt、工具权限、运行环境、评估基线绑成一个 Agent Release，调优必须回流重过门禁。框架只是载体，托管也不转移责任。

适用：2026 年 Agentic Application 架构设计 | 初稿 2026-10