第2章 Harness工程化方法------像造汽车一样造Agent
本章你将学到：
- Harness工程的核心思想：规范即基准
- 四层标准架构是什么，为什么需要分层
- 工业级智能体开发五步法的完整流程
- 通用三层评测指标体系的设计逻辑
本章你将产出：一张自己能画出来的Harness五步法流程图，以及对"规范文档应该长什么样"的直观认知
2.1 什么是Harness工程？
在第1章结束的时候，你刚刚经历了一次"手工作坊式"开发的典型挫败：Prompt越改越长，规则越加越多，最后变成了一团不敢碰的乱麻。你可能会想------到底有没有一套系统的方法，能让我"驾驭"这个过程？
答案是：有。而且它不是什么新发明。它的思想源头，来自一个已经成熟了五十年的领域：软件工程。
2.1.1 一个类比：造汽车和修自行车
想象你在修一辆自行车。链条掉了，你用手挂回去；刹车松了，你拧两下螺丝。整个过程凭感觉，不需要图纸，不需要流程，一个人就能搞定。
现在想象你在造一辆汽车。你还能"凭感觉"吗？你需要设计图纸，需要流水线分工，需要每道工序的质检标准，需要出厂前的安全测试。不是因为汽车比自行车"更难修"，而是因为汽车的复杂度到了某个量级，手工作坊式的方法就会失效。
AI智能体的开发，恰好跨过了这个量级。一个Prompt调一调就能用的小玩具，和一套需要持续维护、需要团队协作、需要质量保障的业务系统，是两种完全不同的东西。
Harness工程，就是把软件工程的思想引入AI智能体开发领域的一套方法。它的名字来源于软件测试中的"Test Harness"（测试夹具）概念------一个用来系统地"固定、驱动、评测"被测试对象的框架。
在AI语境下，Harness工程的定义是：辅助开发、评测、迭代专用AI的工程框架。
注意这三个关键词：
- 辅助开发：不是替代你，而是给你一套流程和工具，让你知道每一步该做什么。
- 评测：评测不是"跑完看一眼"，而是自动化、可量化、可追溯的完整体系。
- 迭代：不是改完就完了，而是每次修改都有依据、有记录、有对比。
2.1.2 核心第一原理：规范即基准（Specification as Truth）
整个Harness工程体系建立在一条最重要的原则上。理解了这句话，你就理解了这个方法论的灵魂。
Specification as Truth------规范即基准。
什么意思？在传统开发中，你判断一个智能体"好不好"，依据是什么？是你随手试的几条测试结果？是你当时的感觉？是同事说"嗯，看起来还行"？
这些都不叫基准。基准必须是确定的、可重复的、不依赖于执行者个人判断的。
规范就是你的基准。在正式开始写一行Prompt之前，你要先定义清楚：
- 这个智能体要做什么？
- 输入是什么，格式是什么？
- 输出是什么，格式是什么？
- 什么情况下算"做对了"，什么情况下算"做错了"？
- 边界情况怎么处理？
这些问题的答案，共同构成了一份评测规范文档。而这份文档，就是后面一切工作的"宪法"。数据集按照它来标注，评测按照它来打分，迭代按照它来判断是否成功。
规范不是写出来给你自己看的------规范是用来让"另一个人"或者"另一个AI"能够独立判断你的智能体是不是正确的。
这就是"规范即基准"的含义。在第4章，你会亲手为"评论甄别智能体"写出这样一份规范。
2.1.3 Harness四层标准架构
理解了"规范即基准"，我们再来看架构。Harness工程把整个系统分成四层。
用刚才造汽车的类比，这四层分别是：
| 层次 | 名称 | 汽车类比 | 职责 |
|---|---|---|---|
| 第一层 | 决策层 | 驾驶员 | 定义目标和策略：智能体要完成什么任务，用什么标准判断好坏 |
| 第二层 | 驾驭层（Harness） | 底盘/刹车/转向系统 | 控制开发流程、调度评测链路、管理迭代循环 |
| 第三层 | 执行层 | 发动机 | AI模型本身的能力：理解、生成、推理 |
| 第四层 | 业务层 | 车身/内饰 | 面向用户的具体功能：输入界面、输出展示、业务逻辑 |
普通人学AI开发，注意力全在第三层（模型本身）和第四层（做出一个能用的东西）。但真正让一个系统从能用到可靠、从一次性到可持续的，是前两层。
这就像一个驾驶员（决策层）开着车，通过方向盘和刹车（驾驭层）控制着发动机的动力（执行层），最终让车身（业务层）抵达目的地。没有驾驶员，发动机再强也只是空转。没有底盘和刹车，再好的发动机你敢开吗？
本书的重点，就是教你怎么做"驾驶员"和"底盘"，而不是教你怎么造"发动机"。 发动机（模型能力）会随着技术进步不断升级，但驾驶技术（工程方法）是永久通用的。
2.1.4 规范文档标准模板
说了这么多"规范"，规范文档到底长什么样？
下面是一个标准模板。在第4章你会用AI帮你填充这个模板，但在那之前，你需要知道它包含哪些部分：
【智能体名称】
一句话描述这个智能体的职责。
【角色定义】
这个智能体扮演什么角色，具备什么能力，有什么限制。
【输入规范】
- 输入内容：描述输入是什么
- 输入格式：纯文本/JSON/其他
- 输入约束：长度限制、必填字段等
【输出规范】
- 输出内容：描述输出是什么
- 输出格式：JSON结构及每个字段的含义
- 输出示例：给一个正确输出的样例
【评测维度】
- 维度1：定义+权重
- 维度2：定义+权重
- ...
- 每个维度有明确的"通过"和"不通过"标准
【边界规则】
- 边界情况1：处理方式
- 边界情况2：处理方式
- ...
（例如：空输入怎么处理？超长输入怎么处理？输入类型错误怎么处理？）
【错误处理】
- 当无法完成任务时，输出什么？
- 当输入不符合规范时，返回什么？这个模板看起来有点长，但别担心。每一条都不是凭空想出来的，而是对应着你在第1章踩过的每一个坑。回顾一下：
- 没有"评测维度"，所以你只能凭感觉判断对错。
- 没有"边界规则"，所以边界案例一出现，Agent就翻车。
- 没有"错误处理"，所以遇到异常输入，Agent的输出格式直接崩溃。
规范就是把"你以为你懂的"，变成"白纸黑字写得清清楚楚的"。
2.1.5 直观对比：不规范 vs 规范
为了让你立刻感受到规范的价值，我们用"评论甄别智能体"做一个对比。
【不规范版规范文档】
判断用户评论是否有效。有效的就是内容具体、有参考价值的。无效的就是那种刷的好评或者乱骂的。
这句话看起来好像也说了点什么，但你拿着它能让另一个AI独立完成评测吗？
- "内容具体"怎么定义？多少字算具体？提到菜品名字算不算具体？
- "刷的好评"怎么识别？什么特征？
- "乱骂的"怎么判定？情绪化一定有罪吗？
全是模糊地带。拿着这样的"规范"，你只能人肉判断，AI帮不了你。
【规范版规范文档】（核心部分示例）
评测维度1：具体性（权重40%）
- 通过标准：评论至少包含1个以上与商品/服务直接相关的具体细节（如菜品名称、口味描述、价格、分量、环境细节等）。
- 不通过标准：全文只有笼统形容词堆砌（"好吃""不错""很好"），不包含任何可验证的具体信息。
- 示例通过："红烧肉软烂入味，肥瘦相间刚好"
- 示例不通过："味道好极了，强烈推荐"
评测维度2：相关性（权重30%）
- 通过标准：评论主体内容针对商品/服务本身。
- 不通过标准：评论主体内容为与商品无关的事项（如吐槽配送速度、天气、平台优惠、个人情绪发泄等）。
- 边界规则：如果评论同时包含相关和不相关内容，以主体占比判定。具体信息占比超过50%仍可判定为相关。
边界规则：空输入处理
- 输入为空字符串或仅包含空格/标点：直接返回 {"valid": false, "reason": "输入为空"}
看到区别了吗？规范版写出来的标准，是另一个人可以直接拿来做判断用的------不管是人还是AI。你说"具体细节包括菜品名称、口味描述、价格"，那么任何拿到这份规范的人，都能独立判断一条评论是否符合要求。
规范的好坏，有一个简单的检验标准：把它交给一个没参与过这个项目的人，他能不能独立完成评测任务？
这就是"规范即基准"的落地形态。在第4章，会用Claude Code帮你生成这样一份完整的规范文档。
2.2 工业级开发五步法
有了"规范即基准"这个思想基础，我们再来看具体怎么干。
Harness工程把整个智能体开发流程分成五个步骤。这五步是全书统一的开发流程，不管你用的是Claude Code还是Trae，不管你做的是单智能体还是多智能体系统，都是同一套流程。
Step1 规范定义
写出可落地的业务规范和评测规范。产出物就是2.1.4节介绍的那份规范文档。
- 输入：模糊的业务需求（"帮我判断评论好不好"）
- 输出：结构化的规范文档（含角色、输入输出、评测维度、边界规则）
Step2 数据构建
基于规范，构建标准化的测试数据集，并为每条数据标注黄金标准（Ground Truth，简称GT）。
- 输入：评测规范文档
- 输出：带GT标注的测试数据集（CSV或JSON格式）
"黄金标准"这个词很重要。它指的是经过人工确认的、不可争议的正确输出。对于评论甄别任务，GT就是"这条评论，经过人工判断，到底是有效还是无效"。GT是你的定海神针。后面所有自动化评测，都是在跟GT做比对。
Step3 智能体开发
基于规范和数据集，用Prompt驱动的方式开发专用的业务智能体。
- 输入：规范文档 + 部分测试数据（用于验证）
- 输出：业务智能体的Prompt + 轻量运行脚本
Step4 自动化评测
搭建评测智能体（裁判），对整个测试集进行批量跑批，生成评测报告。
- 输入：测试数据集（含GT） + 业务智能体
- 输出：评测报告（含准确率、召回率、错误分布）
Step5 迭代优化
基于评测报告的归因分析，修改业务智能体，然后回到Step4重新评测，形成闭环。
- 输入：评测报告
- 输出：优化后的业务智能体 + 版本记录
这五步的关键特征：每一步的输出，都是下一步的输入。 它们是咬合在一起的齿轮，不是五个独立的操作。
而且注意，这五步不是"做完一次就结束"的线性流程。Step5做完一轮，你会回到Step4重新评测，如果还没达到目标，可能还要回到Step3甚至Step2。它是一个循环，每一轮都让智能体变得更好一点。
2.3 通用三层评测指标体系
五步法中，Step4是"自动化评测"。但评测应该评哪些指标？这就引出了Harness工程的另一项基础设施：三层评测指标体系。
这个体系的设计逻辑是：从最基础的形式正确，到最核心的业务准确，再到特定场景的定制需求，层层递进。
L1 基础工程指标
这是最底层、最基本的要求。不管你做什么智能体，这层指标都是通用的。
- 格式合规率：输出是否严格遵守了要求的JSON格式？字段名对不对？类型对不对？
- 完整性：要求的字段是否全部输出？有没有缺失？
- 可解析性：输出的JSON能不能被程序正常解析，不会报错？
如果连格式都不对，那内容再精彩也没用------后面的自动化流程根本处理不了。L1是及格线，达不到就直接打回去。
L2 核心业务指标
这是"有没有把事做对"的指标，是整个评测体系的核心。
- 准确率（Accuracy）：所有判断中，判断正确的比例。
- 召回率（Recall）：在所有真正无效的评论中，被你找出了多少。
- 精确率（Precision）：你判断为无效的评论中，有多少确实是无效的。
- F1分数：精确率和召回率的调和平均值，综合反映性能。
对于评论甄别任务，这些指标的含义很直观：
- 准确率高 = 总体判断靠谱
- 召回率高 = 垃圾评论漏网少
- 精确率高 = 不太会冤枉好评论
L3 自定义场景指标
前两层是通用的。但每个具体项目，可能还有自己关心的特殊维度。比如评论甄别项目，你可能会关注：
- 具体性判定准确率：专门看"是否具体"这个维度的判断准确度。
- 情绪化误判率：多少真实有用的差评被"情绪化"这个标签误伤了。
- 边界覆盖测试通过率：专门挑边界案例（空输入、超长输入、纯表情等）来测。
L3是你根据自己的业务场景定义的，没有标准模板，但有设计思路：问自己，这个项目最怕什么错？然后就专门针对那个错误定义指标。
三层指标不是并列的，而是递进的。连L1都没过的系统，不要讨论L2。L2没做好，L3再花哨也没意义。这三层构成了一个完整的质量度量金字塔。
2.4 为什么这套方法能解决你的问题？
讲了这么多理论，我们回到你身上。
在第1章结束的时候，你面临的困境是：Prompt改一处坏十处，不敢动，测不全，说不清到底有没有进步。
| 你的痛点 | Harness工程怎么解决 |
|---|---|
| 改了Prompt不知道影响范围 | Step4自动化评测：改完一键跑全量测试集，所有影响立刻看到 |
| 发现错误只能凭感觉猜原因 | 错误归因分析：评测报告告诉你到底被哪类案例难住了 |
| 测试用例随手挑，覆盖不全 | Step2标准化数据集：设计时就考虑正负均衡和边界覆盖 |
| 这次开发的经验带不到下次 | 规范+数据集资产化：每次开发的规范、数据、脚本都归档，下次直接复用 |
| 换个人完全没法接手 | 规范即基准：任何人拿到规范和数据集，都能独立跑评测、做迭代 |
| 不知道"优化"是不是真优化 | Step5迭代闭环+版本管理：每次优化都有数据支撑，回归测试验证 |
一句话总结：手工作坊依赖的是"人的感觉"，工程化方法依赖的是"可复现的流程"。
感觉会波动，会遗忘，会在你状态不好的时候背叛你。流程不会。流程写下来了就在那里，谁执行都一样。
2.5 本章小结
- Harness工程 是把软件工程思想引入AI智能体开发的系统方法，核心原则是规范即基准。
- 四层架构：决策层（驾驶员）、驾驭层（方向盘/刹车）、执行层（发动机）、业务层（车身）。我们教的是前两层。
- 规范文档不是写给自己看的，是写给"另一个独立评测者"用的。一份好规范，能让没参与过项目的人独立完成评测。
- 五步法是整个开发流程的骨架：规范定义→数据构建→智能体开发→自动化评测→迭代优化。每一步的输出是下一步的输入。
- 三层指标体系从格式、业务、场景三个层面度量质量，层层递进。
本章的概念比较多，不要试图一次全部记住。在后续的实战章节中，每一个概念都会被具体操作一遍，那时候你会真正理解它们的意思。
从第3章开始，我们将进入动手环节------搭建环境，拿起Claude Code和Trae这两个工具，为第4章的正式开发做准备。
课后练习
- 用你自己的话，画一张Harness五步法的流程图。标注每一步的输入和输出。
- 回顾第1章你遇到的"改坏"经历。如果用五步法重做一遍，每一步你分别会做什么？写出你的想法。
- 根据2.1.4节的规范文档模板，尝试为"评论甄别智能体"写一个初版规范文档（不必完整，重点写出你觉得最重要的两个评测维度）。这个初版会在第4章被正式版本替代，但自己先写一次，能让你更清楚规范的价值。