夜雨聆风这两天又在研究Harness，迷糊了很久。我知道 Agent，知道 Workflow，知道 Model。但 harness 是什么？它和前三者是什么关系？为什么有的项目需要专门搭一套 harness，有的却不用？
带着这个困惑，我花了一个下午把它彻底捋清楚。这篇笔记记录了我从「完全不懂」到「终于能判断什么时候需要它」的完整思路，包括我问过的那些看起来很蠢、但很关键的问题。
我的起点：一个公式让我更困惑了
我看到一个说法：Agent = Model + Harness。
如果 agent 是更上位的概念，那 harness 应该只是 agent 的一部分？但我看到的 harness 仓库，看起来像一套完整的系统——有流程、有校验、有状态管理、有复盘档案。这和我理解的「agent 挂几个 skills」完全不同。
为了搞明白，我先从四个词的关系入手。
我试着用一个最生活化的场景串起这四个概念：一个厨师在餐厅做菜。
Model 是厨师的大脑。 存着菜谱知识、刀工技巧、火候判断。你让它做宫保鸡丁，它能告诉你鸡肉怎么切、花生怎么炸。但它只是大脑，没有手，没有厨房，做不了菜。
Agent 是厨师本人。 有手能切菜、有脚能拿食材、有眼睛能看火候。大脑只会「想」，厨师能「想」也能「做」。但注意，这个厨师现在站在一个空房间里，没有灶台、没有刀、没有冰箱。你让他做菜，他只能干瞪眼。
到这里我理解了 model 和 agent 的区别：agent = 大脑 + 手脚。但光有手脚还不够，还需要一个能让他稳定干活的环境。
Workflow 是菜谱上的步骤清单。 切鸡肉 → 炸花生 → 调酱汁 → 热油下锅 → 大火翻炒。这个清单规定了先做什么、后做什么。
但步骤清单不管质量。切出来的鸡肉大小不一怎么办？炸花生过了三十秒怎么办？workflow 只告诉你「做」，不告诉你「怎么算做对」。
Harness 是整个厨房的基础设施。 灶台和刀具让厨师有地方干活，冰箱让食材有序存放，计时器让炸花生三十秒必须关火，质检员让每道菜出锅前检查咸淡色泽，监控摄像头记录每一步方便出了问题回放，备用方案让鸡肉用完了自动通知采购而不是让厨师傻等。
到这里我突然明白了：
Model = 大脑（会思考）
Agent = 大脑 + 手脚（能思考 + 能行动）
Workflow = 步骤清单（规定了做事的顺序）
Harness = 整套厨房系统（让这件事能稳定、可重复、可质检地完成）
那个公式 Agent = Model + Harness 的意思，不是说 harness 只是 agent 的附属品，而是说：一个真正能稳定交付的 agent，必须有一套基础设施来支撑它的行动。Harness 是一个大框，包含 workflow（步骤顺序）、工具接口、状态管理、校验规则、错误处理、记忆系统。
这一层的理解让我松了口气：harness 不是另一个新物种，它是让 agent 从「能跑」变成能稳定跑的那套基础设施。
「质检员」和「风控把关人」：
听完上面的比喻，我以为自己懂了。但当我看到 harness 仓库里的文件结构时，又产生了新的困惑：
所以用仓库搭建一个这样的 harness，和我编写一个流水线、或者写一个 agent 挂上多个 skill 并且确认使用逻辑和顺序，有什么区别？
这个问题让我意识到，我混淆了「有步骤」和「有质检」。
Agent 挂 skills 是有手有脚，但自由发挥。你告诉它先解析、再分析、最后输出，它这次可能先调 skill A，下次可能先调 skill B。中间某个 skill 输出格式不对，它可能没发现，直接传给下一个。
Workflow 是有步骤，但没有质检。你写脚本明确 step1 → step2 → step3，顺序不会乱，但 step2 的输出不合格，会不会流到 step3？流水线本身不管，除非你每个步骤后手动加校验。
Harness 是「有步骤，且每一步都有质检，出了问题能定位」。不是等全部做完再检查，而是每个阶段做完就校验。有问题立刻暴露，避免「前面错了、后面全废」。有点像一个自带回查日志的智能系统。 Harness 不是「把工具和 workflow 拼在一起」，而是「给它们之间加上了确定性约束，让整个系统能自检、能续跑、能审计」。
二、Why Harness？
概念清楚了，但我还是不知道「为什么需要它」。直到我开始想象：如果没有 harness，批量任务会发生什么？
假设我要让 AI 批量处理一千份客户反馈，每份输出一份结构化的分析报告。
如果只用 Agent（挂几个 skills），第一天跑了十份看起来还行。但第二天我发现：
第三份报告的字段名有时候叫 customer_name，有时候叫 client_name。Agent 自己没觉得有问题，继续往下跑了。它不会告诉我「格式不一致」，因为它没有这个判断标准。
第七份返回了空内容，agent retry 了三次，第四次突然填充了一段完全不相关的文字。Agent 觉得「有结果了」，继续跑。它不知道这个结果其实是垃圾。
第十五份 API 超时停了。我不知道前面十四份哪些成功、哪些失败、成功的那些对不对。
一千份跑完，三十份格式不一致，二十份内容明显有问题，混在一起根本分不清。我只能人工抽查，或者祈祷下游系统别报错。
如果用 Workflow（脚本按顺序跑），顺序确实不会乱了。但新问题出现了：
第二十五份里，三个评分项是字符串 "5分"，另外两个是数字 5。脚本没检查，直接传给下游，下游系统解析报错。
第四十份跑到一半 API 挂了。脚本从头重跑，前面三十九份白跑了。
第八十份跑完，同事问你每份报告某个字段都有值吗。我愣住——脚本里没校验这个，只能人工抽查。
Harness 的做法是，在每一步之间加上「咬合」：
第一步的输出必须符合契约才能进入第二步。不符合？拦截，不往下传。
第二步跑完必须通过校验才能进入第三步。不通过？记录错误，人工介入或自动重试。
中途崩了？从断点恢复，前面已经完成的不用重跑。
三个月后有人问「当时为什么这样设计」？复盘档案里有记录。
到这里我终于感受到了 harness 的价值。它不是让 AI 变得更聪明，而是让整个过程变得可控。
三、Harness 工程长什么样
搞懂了概念关系，我还是想看看 harness 到底长什么样。我拆开那个仓库，发现它不是某种神秘的技术，而是非常具体的文件组织。
AI告诉我，一个 harness 再轻量，也必须有四层：
流程定义，至少要有一张步骤清单。
输出契约，至少要规定最终输出长什么样。
校验逻辑，至少要有「对不对」的判断规则。
状态管理，至少要能回答「跑到哪了」。
如果缺了第三层，就是普通 workflow。如果第三层靠 AI 自己判断，就是 agent 挂 skills。只有第三层是确定性脚本时，才是 harness。
但当我看到 harness 的「最小形态」需要四个层时，我又问了一个问题：
你写的那个最小形态，我感觉完全可以写成一个 skill 或者 prompt 类似的东西，有必要写成四个文件放成 harness 么？因此，什么场景/谁需要写 harness？
这个问题的答案让我理解了 harness 和 skill 的本质区别：生命周期不同。
Skill 的生命周期 = 一次调用。它做完了，返回值给你，它就「死了」。它不记得上一次调用发生了什么，也不知道下一次调用要做什么。
Prompt 的生命周期 = 一次对话上下文。你写再长的 prompt，它也只活在当前这次对话里。关掉窗口，一切归零。
Harness 的生命周期 = 整个任务 + 跨任务。它能记住这本书跑到哪一步了、上次跑一百本时踩过什么坑、契约规则升级后怎么校验旧数据。
所以不是「能不能写成一个 skill」，而是「skill 的寿命太短，撑不起一个长期运行的系统」。就像你可以把质检标准写在一张纸上（prompt/skill），但质检员、进度表、错误档案是另外一套管理体系。
四、隐藏在工具背后的Harness
搞懂了 harness 是什么，我又产生一个新问题：我平时在平台上配的 agent，是不是已经有 harness 了？（所以我才这么不了解harness）
答案是：是的。
平台本身就是一套别人写好的 harness。你选一个模型、写 system prompt、挂几个 skills、配置 workflow，这些动作是在平台提供的 harness 基础设施之上进行的。
平台已经帮你做了：工具调用编排、超时自动重试、对话历史管理、日志记录、安全护栏。所以大部分场景，你不需要自己写 harness。
那什么时候需要？
当平台自带的 harness 不够用时。具体有三种情况：
批量任务加断点续跑。 平台的 agent 通常按「单次对话」设计。处理一条数据没问题，但处理一万条，中间崩了怎么办？平台不会自动记录「第四千三百七十七条跑到第五步了」，你需要自己写状态管理和恢复逻辑。
输出格式要求极高加自定义校验。 平台有基本输出格式约束，但如果业务要求十个维度评分每个必须是整数档位、用户画像必须五段式且不同角色的校验规则还不同、引用字段必须命中原文且位置要校验——这些业务级校验，平台不可能预先知道。
跨系统对接加长期维护。 你的输出要喂给下游 API，JSON 格式偏差百分之零点一就抛异常；三个月后契约升级，需要能校验存量数据；团队换人了，新同事需要知道当初为什么这样设计——这时候需要 harness 的契约层和复盘层。
这一层解决了我最大的困惑：不是「要不要用 harness」，而是「平台的 harness 够不够我用」。
最后我给自己总结了一个判断标准。遇到新项目，问五个问题：
跑一次还是跑一千次？
输出给自己看还是给下游系统用？喂给 API 或数据库，需要 harness。
错了能忍还是错了要追责？会产生业务损失或安全隐患，必须 harness。
今天跑完三个月后还要维护吗？团队长期使用、可能换接手人，需要 harness。
崩了能重来还是崩了不能丢进度？必须续跑且不能丢已完成成果，需要 harness。
三个及以上回答「需要严格」，就上 harness。两个及以下，平台 agent 或简单 workflow 够用。
Harness 不是「高级玩法」，是「规模化加可交付加可维护」的门槛。
你的任务如果只是「玩玩看」，agent 就够了。但如果要「批量跑、给别人用、长期维护」，就需要 harness 那层质检员和风控管家。
我最喜欢的那个比喻：你可以把质检标准写在一张纸上（prompt 或 skill），但质检员、进度表、错误档案，是另外一套管理体系。
Harness 就是这套体系。
