Harness工程

Harness Engineering：让模型稳定干活的工程层

一、先说结论：什么是 Harness

"Harness" 这个词，英文原意是马具、鞍具。给马戴上缰绳、辔头，不是为了让马跑不动，而是为了让马按人的意志、朝人想要的方向、以可控的速度奔跑。

放到 AI 语境里，Harness 就是给大模型套上的那副"缰绳"。

一句话结论：Harness 是包裹在大模型外围的一整套工程化装置------它负责决定模型"能看到什么"、"能动手做什么"、"按什么顺序做事"、"以及如何记住事"，让模型从"一个会说话的引擎"变成"一台能稳定交付的机器"。

更直白地说：

• 模型是引擎：它负责"思考"和"生成"，本身很强大，但也很随性、很不可控。

• Harness 是车架、方向盘和刹车：它负责把引擎装进车架，接上转向，装好刹车，再挂上挡位，让这台车能上路、能转弯、能停下来、出了状况能靠边。

• Prompt 只是点火：踩一脚油门之前，先得把钥匙插进去------但一台车的可靠性，从来不由钥匙决定，而由整车的工程决定。

所以 Harness 工程，本质上是围绕大模型做的一层工程化的稳定装置。它关注的不是"怎么让模型更聪明"，而是"怎么让模型的聪明真正、稳定、安全地被用起来"。

二、Harness 和 Prompt / Context 的关系

要理解 Harness，先要分清三个经常被混为一谈的东西：Prompt、Context、Harness。

概念	是什么	类比
Prompt	你发给模型的一次性初始指令，表达"这次要做什么、按什么要求做"	台词
Context	模型在本次推理中看到的所有信息------历史对话、检索来的资料、工具描述、用户输入	舞台与道具
Harness	生成、组织、裁剪、注入、持久化上面这两者的那套机制和框架	导演与剧务

关键认知在这里：

Prompt 和 Context 都是"内容"，而 Harness 是"管理这些内容的机制"。

• Prompt 是一次性的、静态的。你写好一段指令，交给模型，它就按这段指令跑一次。调 Prompt 只能改善"这一次"的表现。

• Context 是模型当下的全部视野。它决定了模型"看得到什么"。信息进不了 Context，模型就等于没看见。

• Harness 决定的是：哪些信息该进入 Context、以什么结构组织、什么时候注入、Context 满了怎么裁剪、跨任务的信息怎么持久化保存。 同样一个 Prompt，放在不同的 Harness 里，效果天差地别。

用一个比喻收尾：

Prompt 是给演员的台词，Context 是舞台和道具，而 Harness 是导演加剧务------它决定演员"看哪些布景、按什么顺序出场、演砸了怎么办、下一场怎么接"。台词再漂亮，没有导演统筹，整台戏依然会乱。

所以不要用"写更好 Prompt"的思路去做 Harness。Prompt 解决的是"让模型说对一次"，Harness 解决的是"让模型每次都稳定、安全地干对"。

三、为什么现在大家越来越重视 Harness

过去两年，大家把大量精力花在"调 Prompt"上，但现在风向明显变了。越来越重视 Harness，背后是几个很实在的原因：

1. 模型能力见顶，但"用起来"的差距才刚开始拉开

同样的模型，有人能稳定交付生产级结果，有人三天两头翻车。差距不在模型本身，而在模型外围的那层装置。当模型能力都差不多的时候，谁能把它"包"得好，谁就赢。

2. 单点 Prompt 优化的天花板太低

调 Prompt 只能局部改善，而且不可复用、不可版本化。换一个任务、换一个数据源，Prompt 又要重写。真正的稳定性和可维护性，只能靠 Harness 来兜。

3. 从 Demo 到生产，是两码事

一个 Demo，靠一个好 Prompt 就能跑通。但生产系统要处理：输入千奇百怪、工具调用失败、模型偶尔抽风、并发冲突、成本控制、权限安全、合规审计。这些没有一个靠 Prompt 能解决，全是 Harness 的领域。

4. Agent 化趋势的必然要求

模型从"回答问题"进化到"完成任务"------自主地规划、调用工具、执行多步、直到产出结果。自主意味着更多的自由度，也意味着更大的风险。自由必须由 Harness 来约束：给工具、给流程、给边界、给刹车。

5. 成本与可控性

要控制 token 消耗、控制行为的确定性、保证每一步都可审计可回滚，必须有 Harness 这样的工程层。没有它，成本失控、行为不可控、出了问题无从查。

6. 工程化与团队协作

Prompt 是"手艺"，Harness 是"工程"。工程意味着可版本化、可测试、可复制、可多人协作。一个团队要严肃地使用 LLM，就必须把这层"手艺"沉淀成"工程"。

一句话：当大家发现"光靠模型和 Prompt 不够用"时，Harness 就成了必选项。

四、Harness 里面通常包含哪些层

Harness 不是一坨东西，而是可以拆成四层来看。每一层回答一个问题：

1. 模型能看什么？ → 信息边界层

2. 模型能干什么？ → 工具系统层

3. 模型怎么干活？ → 执行编排层

4. 模型记住什么？ → 状态与记忆层

信息边界层

这是 Harness 里最容易被忽视、却最影响安全和质量的一层，所以在目录里我把它标蓝了。

信息边界层回答的是：哪些信息允许进入模型的视野？

• 该看到的：任务相关的输入、检索到的知识、必要的上下文。

• 不该看到的：用户隐私、公司机密、无关数据、不该由这个 agent 接触的信息。

它对应的工作包括：

• 数据隔离：不同用户、不同项目的数据互不可见。

• 按需取用：不是把所有东西都塞进 Context，而是模型需要什么，再去检索什么（RAG、查询）。

• 上下文裁剪与最小化：只把当前任务真正需要的信息放进去，避免信息过载和泄漏。

• 权限控制：模型能访问的范围，由边界层划定。

信息边界没做好，轻则结果跑偏（模型被无关信息带偏），重则泄密（模型把不该说的说出去了）。这一层决定了 Harness 的底线。

工具系统层

工具系统层回答的是：模型除了说话，还能"动手"干什么？

模型本身只会生成文本，但它可以调用工具来真正做事：查数据库、调 API、读文件、写文件、发消息、跑代码、搜网页。

这一层对应的工作：

• 工具注册：有哪些工具可用。

• 工具描述与 Schema：把每个工具"长什么样、参数是什么、能干什么"描述清楚，让模型知道何时该用哪个。

• 参数校验：模型生成的是自然语言，转成结构化调用时要校验，防止参数错误、类型错误。

• 工具选择策略：什么情况下该用什么工具，必要时由 Harness 决定而非全交给模型。

• 错误处理：工具超时、报错、返回异常时怎么办------是重试、换工具、还是降级。

没有工具系统层，模型只是一个"话痨"；有了它，模型才真正开始"办事"。

执行编排层

执行编排层回答的是：模型按什么顺序、以什么节奏干活？

单个工具调用解决不了复杂任务。真实任务往往是多步骤的：先理解需求 → 检索资料 → 制定方案 → 分步执行 → 校验结果 → 修正 → 交付。

这一层对应的工作：

• 任务拆解：把一个大任务拆成可执行的子步骤。

• 流程编排：定义步骤之间的顺序、条件分支、循环（Plan-Execute 循环）。

• 工作流 / 状态机：把流程固化成确定性的状态转移，减少随机性。

• 路由：不同子任务分给不同的模型或不同的处理链路。

• 人工介入点：在关键节点停下来等人工确认。

编排层决定了 Harness 是"有章法的确定流程"，还是"听天由命的随机漫步"。

状态与记忆层

状态与记忆层回答的是：模型怎么把干过的事、知道的规矩跨轮记住？

模型本身是无状态的------每一次对话都像失忆。要让一个 agent 在长任务、多轮、多任务里保持连贯，必须有外部的状态与记忆系统。

这一层对应的工作：

• 短期状态：当前任务的上下文、中间结果、已执行的步骤。

• 长期记忆：跨任务、跨会话保存的偏好、知识、历史结论。

• 记忆存取与更新：什么时候写入、什么时候读取、什么时候更新、什么时候清理。

• 记忆的组织：向量库、数据库、结构化存储，以及记忆的摘要与压缩。

没有状态与记忆层，agent 每做一件事都从零开始；有了它，agent 才谈得上"越用越懂"。

---

小结一下这四层：

          ┌──────────────────────────┐
          │      信息边界层          │  模型能看什么（底线）
          ├──────────────────────────┤
          │      工具系统层          │  模型能干什么（能力）
          ├──────────────────────────┤
          │      执行编排层          │  模型怎么干活（流程）
          ├──────────────────────────┤
          │      状态与记忆层        │  模型记住什么（记忆）
          └──────────────────────────┘

五、如果再压缩一点，Harness 怎么总结

四层听起来复杂，但其实可以压缩成四个字：界、能、序、记。

• 界：信息边界------让模型看该看的，绝不看不该看的。

• 能：工具系统------给模型干活的双手。

• 序：执行编排------让模型按章法做事，不随机。

• 记：状态记忆------让模型记住事，不白干。

再压缩成一句话：

Harness 就是用工程手段，把模型的能力、信息和边界稳定地组织起来。

或者说得更生活一点：

Harness 是把一个"很有想法但不太靠谱的天才"，包装成一个"能力出众且纪律严明的员工"。

模型是那个天才，Harness 是那套管理制度------工位（信息边界）、工具（工具系统）、SOP（执行编排）、档案（状态记忆）。

六、怎么开始做 Harness

很多人的误区是"想一步到位搭一个完美的 Harness"。别这样。Harness 是搭出来的、跑出来的、演进出来的。下面是五步启动法，按顺序做：

先定义信息入口

动手之前，先想清楚：这个 agent 应该看到哪些信息？从哪来？

• 输入是什么（用户输入、上传文件、外部请求）？

• 需要检索哪些知识（知识库、数据库、内部系统）？

• 哪些信息绝对不能进（隐私、无关数据、越权数据）？

信息入口没定义清楚，后面全白搭------因为信息是模型的"伙食"，喂错了，干什么都偏。

再准备工具系统

想清楚这个 agent 需要"动手"做哪些事，然后配齐工具：

• 列出它真正需要的能力（查数据、写文件、调接口、发通知......）。

• 把每个工具描述清楚、Schema 定义规范。

• 想好工具失败的兜底策略。

工具宁少勿滥：只给它真正需要的工具，工具太多模型反而容易用错。

固定一条任务流程

挑一个最典型、最高频的任务，把它写成固定流程：

• 先做什么、再做什么、什么时候检索、什么时候调用工具、什么时候停下来。

• 把流程固化成确定性的步骤（工作流 / 状态机），不要指望模型每次自己即兴发挥。

固定一条流程，是 Harness 从"随机"走向"稳定"的关键一步。

加上边界与风险控制

这一步不能省：

• 信息边界：哪些数据能碰、哪些不能碰。

• 行为边界：模型能执行哪些动作、不能执行哪些动作。

• 风险控制：高风险操作（写入数据、发送消息、产生费用）必须设人工确认/审批点。

• 越界拦截：一旦模型试图越权，立即拦截并回退。

最后补验证和反馈

Harness 搭好不是结束，要能"自我验证、持续改进"：

• 验证用例：给典型场景写测试用例，每次改动跑一遍，防止回归。

• 反馈闭环：记录失败、分析失败、把教训沉淀回 Harness。

• 日志与可观测性：agent 每一步做了什么、调用了什么、为什么，全都要可回溯。

• 回滚机制：改坏了能退回上一个稳定版本。

七、Harness 的一个简单落地顺序

五步启动法讲的是"搭一个 Harness 的步骤"，落地顺序讲的是"从哪开始搭"。

核心原则：先横打通一个场景，再纵深化。别一上来就铺很多场景。

一个务实的落地顺序是：

选一个任务（高频、失败率高、价值大）
        │
        ▼
定义信息入口 ──► 挂工具 ──► 定流程 ──► 加边界 ──► 加验证反馈
        │                                              │
        └────────────── 跑通最小闭环 ◄────────────────┘
        │                                              │
        ▼                                              │
        验证是否稳定、安全、可回滚 ◄─────────────────────┘
        │
        ▼
     固化成一个可复用的模板
        │
        ▼
   复制到下一个任务（循环）

要点：

1. 先选对第一个任务：要选一个"高频、反复失败、干好了价值大"的任务，这样 Harness 的价值立刻能被看到。

2. 跑通最小闭环：第一个版本一定简陋，没关系，先让它稳定跑通一个完整任务。

3. 横向打通一个场景，再纵向加深：先把一个场景做深做透，做出模板，再复制到别的场景。

4. 每一步都可回滚：演进过程中，任何一步改坏了都能退回上一步。

落地顺序的本质是：从一个点开始，做透，做成模板，再扩散。 贪多求全只会让 Harness 变成一座无法维护的空中楼阁。

八、做 Harness 时容易踩的几个坑

以下是实战中反复出现、代价很高的坑，提前避开：

1. 把 Harness 当成"超大号 Prompt" 把信息全部塞进一段超长 Prompt，以为这就是 Harness。结果 Context 爆掉、成本飙升、模型被无关信息带偏。Harness 是机制，不是更长的 Prompt。

2. 只调 Prompt，不处理工具错误 模型调用工具，十次里有几次会参数写错、超时、返回异常。不处理这些，agent 就会卡死或瞎编。工具错误处理，是 Harness 的基本功。

3. 忽视信息边界 / 隐私 为了"让模型更聪明"，什么都往 Context 塞，结果隐私泄露、越权访问、审计不过。信息边界是底线，不是性能的代价。

4. 流程写得太死或太松 写太死，遇到一点变化就卡死；写太松，模型自由发挥，结果每次都不一样。好的 Harness 是"该确定的地方极度确定，该灵活的地方留出口"。

5. 记忆无限膨胀 / 污染 对话历史、中间结果无限累积，Context 越来越脏，模型被自己的旧记忆带偏。记忆要有生命周期，要会清理、会压缩、会遗忘。

6. 没有验证与回滚 改一行 Prompt、改一个工具，结果整个 Harness 崩了，还不知道是哪步改坏的。没有验证用例和回滚机制，Harness 就是雷区。

7. 追求一步到位 想一次搭出完美 Harness，结果迟迟上不了线。先跑通最小闭环，再逐步演进。

8. 工具给太多 把所有能力都挂上去，模型反而不知道该用哪个，频繁用错工具。工具宁少勿滥。

9. 只关注成功路径 一切测试都测"顺利的情况"，一旦输入畸形、工具失败、模型抽风，立刻崩。要专门测试失败路径------Harness 的价值恰恰体现在失败时。

10. 不做可观测性 agent 内部在做什么完全黑盒，出了问题无从查起。每一步都要有日志、有迹可循。

九、activity-demo 事例

用上面的框架，来看一个具体例子：activity-demo------一个承担"活动/运营类任务"的 agent。它用一个实际的最小 Harness 结构，把前面讲的原理落到了文件上。

AGENTS 入口文件

入口文件定义的是这个 agent 的"身份和启动配置"：

• 角色定义：activity-demo 是谁、负责什么（例如：负责某活动的方案起草、物料生成、执行跟进）。

• 初始说明：它接手任务时的初始指令，告诉它"你是什么、你该按什么标准干活"。

• 可用工具集：声明它能调用哪些工具（如：活动模板库、素材库、日历、消息通知）。

• 信息入口声明：它默认能访问哪些数据源，不能访问哪些。

入口文件的作用：让模型一"醒来"就知道自己是谁、能干什么、边界在哪。这是 Harness 的"开机自检"。

工作流文件

工作流文件定义的是这个 agent 的标准做事流程：

• 阶段一：接收任务，解析需求（信息入口 → 拉取活动基本信息）。

• 阶段二：检索与参考（从模板库、历史活动库检索相关资料）。

• 阶段三：制定方案 / 生成物料（调用工具生成）。

• 阶段四：校验（检查生成结果是否符合规范）。

• 阶段五：交付与跟进（输出结果、登记状态）。

工作流文件的作用：把"做一场活动"这种模糊任务，固化成确定的步骤，让模型每一步都知道该干什么，而不是即兴发挥。

边界规则文件

边界规则文件定义的是这个 agent 的信息边界和行为边界：

• 信息边界：只能访问已授权的活动数据、模板、素材；不得接触其他用户隐私、财务数据、未授权业务数据。

• 行为边界：可以读、可以生成、可以在授权范围内写；不得执行未授权的写入、删除、对外发送等动作。

• 越界处理：一旦模型试图越权，立即拦截并上报。

边界规则文件的作用：让 agent 在"能干很多事"的同时，明确"哪些事绝不能干"。这是 Harness 的安全护栏。

风险边界说明

风险边界说明，比边界规则更进一步，专门针对高风险动作：

• 列出本任务中"高风险"的操作（如：对外发送消息、写入生产数据、产生费用、修改他人内容）。

• 对每个高风险动作，规定必须人工确认/审批，模型不得擅自执行。

• 规定高风险操作前的停顿点（pause）和回退预案。

风险边界说明的作用 ：高价值任务往往伴随高风险动作。Harness 要做的不是禁止这些动作，而是让它们必须经过人工这一关。

一个很实用的演进原则：失效优先

最后一条不是文件，而是贯穿整个 Harness 演进的原则，目录里叫"失效"，这里展开就是 Failure-First / 失效优先：

• 先保证"最坏情况下能安全失败" ：与其追求成功路径的完美，不如先确保失败时系统不崩、不泄密、不造成损失。

• 每次只改一个变量：演进过程中一次只改一处，改坏了能立刻定位。

• 保持可回滚：任何时候都能退回上一个稳定版本。

• 把失败当反馈：每次失败都是 Harness 升级的输入，沉淀回规则和流程，而不是掩盖掉。

为什么这条原则很实用：因为 Harness 永远在演进，而演进最大的风险是"改崩了还不知道是哪改的"。失效优先，让你在安全网内大胆演进。

---

activity-demo 事例给我们的启示：

一个最小可用 Harness，其实只需要四个文件加一条原则------入口文件（身份）、工作流文件（流程）、边界规则文件（边界）、风险边界说明（高风险管控），加上"失效优先"的演进原则。麻雀虽小，五脏俱全，四层结构（信息边界、工具、编排、记忆）都在里面了。

十、还可以补充的两个视角

如果想让 Harness 更完整，还可以从下面两个视角再补一刀：

Garbage Collection：AI 产物的治理

模型会持续产生"产物"，而这些产物会不断累积、污染系统：

• 中间生成物：草稿、临时文件、失败的重试结果。

• 缓存与历史：对话记录、检索缓存、模型推理缓存。

• 被污染的上下文：旧记忆、过时知识、带偏的历史。

Harness 需要像操作系统的**垃圾回收（GC）**一样，对这些产物做治理：

• 清理：定期清理不再需要的中间产物和缓存。

• 压缩：把冗长的记忆压缩成摘要。

• 遗忘：主动丢弃过时、错误、低质量的记忆，防止模型被旧信息带偏。

• 防污染：确保进入 Context 的信息是新鲜的、可信的、干净的。

视角的意义：很多人只关心"怎么往模型里塞信息"，忽略了"怎么清走脏信息"。AI 产物的治理，是 Harness 长期稳定运行的关键，否则系统会越跑越脏、越跑越偏。

仍待解决的问题

Harness 工程方兴未艾，还有很多硬骨头没啃下来：

• 可观测性：agent 内部在想什么、为什么做这个决定，依然难以完全看清。黑盒问题未解。

• 可解释性：模型的行为很难向用户、审计方解释清楚。

• 成本控制：Agent 自主执行，token 消耗和调用成本难以精准预估和限制。

• 记忆的污染与遗忘：如何精准地记住该记住的、忘掉该忘的，仍是难题。

• 多 agent 协作：多个 agent 之间如何分工、通信、避免冲突，尚未成熟。

• 安全与对齐评估：如何系统地评估一个 agent 的安全性、是否符合预期，缺乏统一标准。

• 评测标准缺失：Harness 本身好不好，缺少可量化、可对比的评测方法。

视角的意义：看到这些未解决的问题，不是为了劝退，而是为了明白------Harness 工程是"正在进行时的工程"，谁先在这些问题上做出可用的解法，谁就占了先机。

十一、最后怎么总结这件事

把整篇文章收束成几句话：

1. Harness 是什么

Harness 是包裹在大模型外围的一层工程化装置，负责把模型的能力、信息和边界稳定地组织起来，让模型从"会说话的引擎"变成"能稳定交付的机器"。

2. 它解决什么问题

Prompt 解决"让模型说对一次"，Harness 解决"让模型每次都稳定、安全、可控地干对"。

3. 它由什么构成

四层：信息边界（界）、工具系统（能）、执行编排（序）、状态记忆（记）。核心是"界、能、序、记"。

4. 怎么开始做

从一个高频失败的场景起步：定义信息入口 → 挂工具 → 定流程 → 加边界 → 加验证反馈，跑通最小闭环，再固化模板、复制扩散。

5. 怎么把它做好

守住信息边界这条底线，处理失败路径，做可观测、可回滚，用"失效优先"的原则持续演进，并像垃圾回收一样治理 AI 产物。

最后一句

当模型能力越来越趋同，真正决定一个团队 LLM 落地成败的，不再是"谁的模型更强"，而是"谁把模型包得更好"。Harness 工程，就是把"模型的能力"真正变成"产品的可靠性"的那一层。 它没有想象中那么玄，四个文件加一条原则就能起步；它也没有想象中那么简单，信息边界、失败治理、可观测性，每一个都是需要长期打磨的硬功夫。尽早搭起自己的 Harness，你就在这场工程化的赛道上，先人一步。