AI 原生系列 · HARNESS ENGINEERING

万物皆插件，量具才是真功夫。

作者：Paul Jialiang Wu · agentic-portfolio-lovat.vercel.app · 2026-08-17

1. 四天，147,620 颗星，还有一个错误的头条

deepseek-ai/deepseek-harness (dsh）公开发布于2026-08-13，采用 MIT 协议。8 月 17 日我调用 GitHub API 时，数字是147,620 颗星、15,083 次 fork，最近一次推送就在当天早上。媒体把这事框定成一次竞争性动作——一个瞄准 Claude Cowork 的开放运行时，一家模型公司要抢占模型之上那一层。

这个框定大概率是对的，但对我没什么用。星标增速能告诉你的是传播速度，不是工程质量。所以我做了这个仓库自己在AGENTS.md里推荐的事——"We recommend using an agent to explore the codebase"（中译：我们建议用一个 agent 来探索这份代码库）——把 81 MB 的代码全克隆下来，开始找有什么规则值得我偷师。

我盯着那条规则，合上笔记本电脑愣了一分钟——因为它是一套机制，而我用文字宣称自己在践行同一种纪律，已经念叨了两个星期，却从没真正做出来过。

2. 我到底读了什么，怎么读的

四个研究窗口——这是我给任何打算付诸行动的事情定的范围：眼下大家在聊什么、什么东西在过去眼下这段时间里从演示走向了默认选项、什么东西撑了三十个月还依然是承重结构、什么东西活过了三十年。最后这个窗口不是摆设，它是唯一一个足够长、能把那些听起来不错、实则站不住脚的想法淘汰掉的窗口。三百年。最后这个窗口不是摆设，它是唯一一个足够长、能把那些听起来不错、实则站不住脚的想法淘汰掉的窗口。

只看一手材料，而且是数出来的，不是翻一遍就算数：

• 仓库本身：docs/architecture.md，根目录和各 package 的 AGENTS.md, docs/testing.md，那棵 .agents/notes/ 树，scripts/，每个类别各挑一份真实的 invariant.ts 来看；
• 《Agent Harness Engineering: A Survey》——一篇 37,794 字的综述，作者来自 CMU、UAB、Tulane、Yale、Northeastern、Stanford、Amazon、UChicago、Virginia Tech 和 Rutgers，把 170 多个开源项目归入一套七层分类法；
• 两个长窗口对应的航海与制造业史料，全部对照博物馆与标准文献核实过，不是凭记忆写的。

下文所有数字，要么是我自己跑出来的计数，要么是引用自具名来源的数据。凡是我核实不了的，我都会说明。

3. 唯一值得偷师的一条规则

出自 packages/AGENTS.md，原文如下：

每个包都拥有 ./invariant. 注册清单名称；检查事件/数据关系，或让空的安装器给出该包专属的 No runtime invariant: 理由。生成的伴生文件、未加说明的空声明、以及被忽略的报告者，一律判定失败 verify-package-invariants.

我在他们的代码树里实测到的数字：

一个真实的、附带说明的空声明，出自 packages/code-runtime/code-runtime/src/invariant.ts:

/**
 * No runtime invariant: this package exposes no independent event sequence or mutable
 * data relation beyond contracts enforced at its owning seam.
 */
const install: InvariantInstaller = () => {}

再读一遍这个比例：84% 的产出，是一份签了名的声明——声明「此处无需断言」。 同事看到这个数字，多半觉得是浪费。我看到的却是整个设计的精髓所在。这道闸门产出的不是 35 条断言，而是 184 句人类可以提出异议的话，用来取代 184 处任何人都无法质疑的沉默。

接下来这句话真正刺痛了我，因为它写的正是我写过的每一道漂移检测闸门：

Runtime invariants assert owned relationships. 检查权威事件流或可变数据，not service or method presence，而不是服务或方法是否存在、插件元数据或副作用、或固定的纯示例。若不存在可信的关系，一个附带说明的空声明才是正确的。

我的 harness 有一个漂移闸门（drift gate），文档记载的命令若不存在就会失败；它还有一个 doctor 检查，安装的 CLI 哈希值若与源码不一致也会失败。这两个都是「存在性检查」（presence check）。它们能抓到重命名，却会在一个从写下那天起就悄悄错了的模块上永远亮绿灯——而这恰恰是我一再交付出去的那种失败。六天前我交付了一个双语读卡器，945 个测试全部通过，结果我是靠listening to it才找出两个真实缺陷。存在性从来都不是问题所在。

4. 1785 年：宣称是廉价的，量具才是真功夫

在1785 年 7 月 8 日，在 Château de Vincennes 的庭院里，Honoré Blanc 做了一件比造出模块化零件更激进的事：他把火枪枪机拆开、把零件混在一起、再重新组装起来。他没有拿出一份设计图纸然后为它辩护，而是当着见证人的面把真实的零件打乱重装，让结果自己说话。

为了做到这一点，他造了63 件量具。不是 63 台机器——是 63 件用于检验的工具。Jean-Baptiste de Gribeauval 早已为炮弹正式确立了通止规（go/no-go gauge）的做法，它回答的问题比「尺寸对不对」更精细：它问的是一个零件是否落在某个公差带之内，然后只给出两个答案中的一个——合格，或者不合格。

接下来是让人清醒的一记反转。Springfield Armory 在 1810 年代接过了这个雄心，到 1825 年已有11 件主控量具——但直到1849才真正实现零件互换。从 Blanc 的示范到零件能在规模化生产中可靠互换，中间隔了六十四年。想法从来都不是瓶颈，仪器才是。

这正是让 dsh 对我变得清晰可读的原因。“一切皆插件”不过是 Springfield 在 1810 年代的雄心，换了一套类型系统重新说了一遍。有意思的是，他们在发布这句口号的同一天，就把219 件量具和 36 个检验工位一并交付了。而 Blanc 那场“拆开再混装”的示范，在他们的测试策略里也有一个直系后代："Registry contributions prove disposal through the HMR-safety test: dispose the fiber and observe removal."（中译：注册项的贡献需通过 HMR 安全测试来证明其可释放性：销毁该 fiber，并观察其确实被移除。） 你不能靠读代码来证明一个插件可以被卸载，你得把它卸载掉，亲眼看着它消失。

5. 1876 年：自己给自己画的限，不算限

第二个历史发现，才是真正把这篇文章从一次有趣的阅读，变成了一次对我自己工作的诊断。

19 世纪 70 年代，英国商船被故意超载后沉没，船主借此骗取保险金，船员则随船一起葬身海底——人称“棺材船”（coffin ships）。Samuel Plimsoll 先是促成了 1872 年的皇家委员会调查，随后又推动了《1876 年商船法》（Merchant Shipping Act 1876），该法案强制要求标注载重线：一个十二英寸的圆盘，中间横穿一条十八英寸的线，漆在船体两侧的舯部。这是一条硬性的、在码头上肉眼可见的、有法律强制力的限。

只是 1876 年的这部法案 把线该漆在船体哪个位置的决定权，留给了船东自己.

。贸易委员会（Board of Trade）在 1886 年公布了载重线表；到1890年，这个位置才被正式写进法律，1894 年又进一步敲定细节。所以时间线是这样的：从"you must declare a limit"（中译：你必须自己申报一条限） 到"you do not get to choose your own limit."（中译：你无权自己选定这条限。），中间隔了十四年。第一部法案让超载变得可见；第二部才真正让超载停下来。

手握这个历史案例，再回头看看我自己的那些量具。

• 我的智能体技能文件有一个字节预算，由一个测试来强制执行。这个数字是我自己定的，而这条测试自身的失败信息还写着：当「所需内容确实需要更多空间」时，上限可以调高。我确实调高过。自己给自己画的线。
• 我系统里的每一次交付都会生成一张成绩单，关键结果按 0–1 打分。证据分级会给分数封顶，一根「针」再按后果把它压得更低——这些都是真实的约束。但定目标的，始终是作者自己。我自己的项目日志里，这条线索悬了好几周，原话是我自己写的："the Mate still sets its own targets, and sets them low."（中译：那位「大副」依然在给自己定目标，而且定得很低。）我诊断出了问题，然后就撂在那儿了。
• dsh 也不例外：它的文档篇幅清单是九个手工挑选的整数（AGENTS.md：1950 词，docs/architecture.md：2400……），而且它自己的规则也允许调高上限。同一条 Plimsoll 线，还是船东自己画的。

这条可以推而广之的规则，居然要靠一部一百五十年前的航运法案才能说清楚：由受此门槛约束的一方来设定门槛，那只是一种披露，算不上一种管控。 两者都有价值，但只有一种能救船。分清自己手上拿的是哪一种，就是整场游戏的关键。

6. 2024–2026：文献指出的缺口在哪里

Agent Harness Engineering: A Survey 把 170 多个项目映射到了ETCLOVG——Execution（执行）、Tool interface（工具接口）、Context management（上下文管理）、Lifecycle/Orchestration（生命周期/编排）、Observability（可观测性）、Verification（验证）、Governance（治理）——它的整体结论，恰好指向我原本就站着的地方：

执行、工具接口、生命周期编排和验证，是可见覆盖最密集的部分……可观测性与治理在开源项目中的覆盖相对单薄，更多是通过商业平台、SDK 功能或工程博文体现出来——这说明运行时与基准测试基础设施成熟得更早，而运营层面的管控成熟得更晚。

这篇论文里有四个发现，改变了我原本打算做的事：

大多数智能体的失败，并不是模型的失败。 AgentFixer 部署在 IBM 的 CUGA 生产系统上，配有 15 个验证工具，问题检测率达到 64–88%，并发现38% of task failures trace to parsing errors（中译：38% 的任务失败可追溯到解析错误） ——作者将其描述为 "a failure mode fully addressable by deterministic checks."（中译：一种完全可以用确定性检查来解决的失败模式） 生产环境智能体系统中，超过三分之一的失败都是机械性的。这就是支持设置闸门的实证依据，比任何出于品味的论证都更有说服力。

人人都在看，一半的人在判断。 论文引用了 LangChain 2026 年的调查：89% of teams use observability, 52.4% run offline evaluations（中译：89% 的团队使用可观测性工具，52.4% 会运行离线评估）。作者称之为「可观测性—评估鸿沟」，并精准地点出了后果："teams can see what agents did without systematically judging whether the behavior was correct."（中译：团队能看到智能体做了什么，却没有系统地判断这些行为是否正确。）

最终分数是错的量具。 第 12.3 节写道："a failed rollout may originate from model reasoning, a misleading tool schema, sandbox misconfiguration, stale context, flaky tests, benchmark ambiguity, judge instability, or orchestration loops."（中译：一次失败的轨迹采样，可能源于模型推理本身，也可能是工具模式（tool schema）误导、沙箱配置错误、上下文过期、测试不稳定、基准测试含糊、评判者不稳定，或编排循环出了问题。） 论文给出的建议是轨迹原生评估（trace-native evaluation）——把轨迹本身当作首要对象，而不是最终那个分数——并且这被列为一个尚未解决的问题（open problem），而非已经成熟的实践。

多仓库编排是一个有名有姓的生态缺口。 这是「在层与层的边界处反复出现」的五个缺口之一，其余四个是成本归因、故障恢复、跨工具互操作性，以及人类—智能体交接。我自己的舰队工具在这个缺口里已经摸爬滚打了一个月，却一直不知道它还有个名字。

论文里还有一条原则，事后为我做过的一件最不讨喜的事——删掉自己写的提示词——提供了正当性：

「harness 即假设」原则（the harness-as-assumption principle）。 每一个 harness 组件，都编码着一条关于「模型自己做不到什么」的假设。随着模型能力提升，可观测性系统不仅要检测智能体何时失败，还必须检测 harness 组件何时已经变成了多余的负担（unnecessary overhead）.

7. 三个方向，以及真正做出来的东西

四个研究窗口最终都指向同一句话：断言一个真实存在的关系，用真实拼装出来的输出去验证它，并且不让作者自己给自己划及格线。 这句话可以拆成三个项目。第一个我这周已经做出来了。另外两个我只是写了规范（specification），并且要坦白说清楚：它们还没做出来——因为不这样做的后果，就是我六天前干过的事：把一段照着已发布 API 写出来、却从未真正跑过一次的功能直接发出去，结果装上不到十分钟，就发现自己的两条假设都是错的。

R&D 1 ——「不变量或说明」，逐模块、闸门强制执行 (已建成)

anyagent invariants [repo] [--fleet] [--gate --baseline …]。每个模块的头部必须携带以下两种声明之一：

Runtime invariant: concatenating a text's segments reproduces that text EXACTLY, so
segmentation can never drop or duplicate a character.
@invariant-test: test_invariant_segmentation_is_lossless

……或一条明确的No runtime invariant: <reason>。四种状态：asserted（指明一种关系并且一个确实存在的测试），declared（诚实的空声明，附带理由），absent（违规），broken（声称有某种关系，却未指明测试，或指明的测试并不存在）。

有三个设计决定值得辩护一下。诚实的空声明也算作已覆盖——如果不这样判，作者们就会为了通过闸门而编造空洞的断言，那比「这里什么也没有」更糟。闸门拒绝评判质量：一条不变量是不是一条好的不变量，这是评审要回答的问题；脚本若假装能裁决这个问题，只会在更高一层重新造出「存在性检查」那套把戏。没有基线时，它宁可失败也不放行，因为一个没有依据的绿灯，正是整件事要防的那个缺陷。

写这四条不变量立刻就见了效。既然声称我的语言分词器是无损的，那就得想办法把它打破——于是我在断言任何结论之前，先用两万条随机双语字符串对它做了模糊测试，并提交了一个种子固定、包含四千个用例的版本，这样一旦失败也能复现，而不是偶发性的抖动。结果它扛住了。但要不是这条声明逼着我去指定一个测试，我根本不会去跑那次模糊测试——不变量才是真正的推动力，测试本身反倒不是。

R&D 2 ——轨迹原生（trace-native）证据：组装后完整对话记录的快照 （已定规范，尚未建成）

dsh有一条规则，我无可反驳，却也还没实现：

模型可见 ⟺ 已记录：任何抵达模型请求的内容，都必须能从会话日志中还原；新增一项模型可见输入，就必须新增一条会话事件。

……由一条运行时 invariant 强制执行，配套一条测试策略："Package tests, e2e assertions, mock/test-only compositions, and PR rationale do not replace the assembled transcript."（中译：包测试、端到端断言、仅用于测试的模拟组合，以及 PR 中的说明理由，都不能替代那份组装好的完整记录。） 他们的覆盖率文档里还有一句话，我想把它刻在自己的规范里："Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped."（中译：行覆盖率是必要的，但永远不充分——它只能证明代码行被执行过，不能证明这个功能在交付形态下真的能用。） 还有一句，妙极了："An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on."（中译：一行未被覆盖的代码，往往是死代码，闸门正确地把它标记出来该删掉，而不是该给它硬凑一个测试。）

我需要这套东西的证据，来得又丢人又新鲜。945 个单元测试全绿；结果两个真实缺陷，是我把输出念给自己听才听出来的。一句被截断的话，把「多说一点」的提示词带进了简报正中间，结果整段话听起来还没讲完就像已经讲完了。一个本该是单数的关键结果，被念成了复数。这两个问题，纯函数的单元测试根本测不出来；可只要录一段音，问题就明摆着。Blanc 当年靠的不是检查图纸——他是把零件打乱重装。Springfield 的后继规则说的是：销毁那根 fiber，然后亲眼看着它被移除。我这条规则应该这样写：回放那份组装好的完整记录，然后做差异比对。

R&D 3 —— 外部锁定的阈值（已定规范，尚未建成）

Plimsoll 的修法思路。舰队里的每一个阈值都要被归类为自定，或者外部锁定，凡是自定的，无论在哪里报告，都要原样标注出来。我自己选的预算、我自己打分的目标、我自己定的覆盖率门槛——每一个都是一种「自我披露」，理应以「自我披露」的样子被印出来。1876 到 1890 年这段教训是：可见性是第一步，但还不够；诚实的过渡做法，是别再让一条自己画的线，被人误读成官方勘测的标记。

8. 它在我身上测出了什么：0.27%

我把这道闸门对准了这台机器上的 27 个仓库。首次运行，未经任何修正：

对比一下：dsh，在公开当天就做到了 219/219。

公布这个数字有两层意思。第一，这个结果站得住脚——那个按照“无证据即未度量”这条准则来给我所有交付物打分的工具，竟然从未声明过自己模块必须恒久成立的东西。没有机制的准则，不过是一种情绪。第二，它只能收紧、不能倒退：如果按绝对值来算，1,501 个沉默模块会让这道闸门永远亮红灯，而一个永远不变的信号，久而久之就没人再看了。一个新增的沉默模块，会让当周的运行直接失败。继承下来的沉默是一笔写明了数字的债，这正是「积压」和「氛围」之间的区别。这四条声明都是真实的关系，而不是简单的「存在性检查」：分词是无损的（经过模糊测试验证）；回放结果不丢失任何部分；每个话题在中英双语下都符合各自的篇幅预算；语音引擎选择留空时，必须附带理由——最后这一条，正是「不许静默兜底」的规则，终于从文档字符串里的一句承诺，变成了数据本身的一项属性。我欠这篇文章一个更正，是在发布它的过程中挣来的教训

发布这篇文章的时候，我自己的 CI 挂了两次，而这两次失败，恰好就是我刚花三千字说自己 fleet 所欠缺的那种模式。

第一次：推广文件必须带上一个 URL、一条 LinkedIn 帖子、一条评论，

以及

一条讨论串，否则构建失败。我发布时漏了讨论串。第二次更能说明问题——一篇文章必须有四种语言的译文，或者一份明确的、注明日期、会过期的延期声明，而这道闸门自己的报错信息写着："no translation AND no explicit deferral — the silent-gap state this gate exists to forbid."（中译：既没有译文，也没有明确的延期声明——这正是这道闸门存在的目的，就是要禁止这种悄无声息的空白状态。）这就是「要么声明、要么解释」。它已经在我的作品集仓库里默默运行了好几个星期。它甚至有一项我的新闸门都还没有的功能：延期声明超过 90 天就会失败。所以，0.27% 这个数字的老实版本，其实比表面这个数字要窄——这支 fleet 几乎没有任何按模块划分的运行时不变量，但它确实在仓库层面、至少有一处，早在我读到 DeepSeek 的任何东西之前，就已经具备了这种纪律。

直到我自己写的一道闸门，拒绝发布一篇讲闸门的文章，我才把这两件事联系到一起。这恰恰是从反方向印证了论点：这套机制其实早就握在我手里，我却看不见它，因为它从未在任何地方被明确命名

为一条通用规则。读别人的代码库，很多时候学到的不是什么新点子，而是有人替你给了一个名字——命名了一个你早已在某处使用、却从未加以推广的做法。被命名为一条通用规则之前。读别人的代码库，很多时候学到的不是新点子，而是有人把你早已在某处用着、却从未推广开的东西，给了它一个名字。

9. 我刻意没有照搬的东西

读一个令人印象深刻的代码库，最容易犯的错误就是模仿。有三件事我按兵不动，理由如下：

219 个 package。 那种颗粒度背后是一支团队，加上逐文件 100% 的覆盖率闸门。对一个「一人加若干 agent」的舰队来说，这只会带来繁文缛节，而不是清晰。要偷的是量具，不是组织架构图。

693 条 Agent Notes。 对一个公开才四天的仓库来说，这意味着背后有很长的私有历史，而不是一个可供效仿的目标。我真正要偷的是它的生命周期机制——是——一组封闭的状态集合，外加一条极好的规则：被归档的记录proposed/ → implemented/ → archived/，永久冻结，不得被当作当前行为的权威依据。「陈旧文档被当真理引用」是一种我一直存在、却从未命名过的失败模式。

「不要用比喻。」他们的行文规范禁止比喻，要求用精确的名词，而不是contract, boundary, shape 这类词。对于合约类文本，这条规则毫无疑问是对的，我也在那部分采纳了它。但我的系统会刻意把每一次交付都写成一个持续故事里的一章——面向的是那种不会去读更新日志的读者——评分与证据则原文照录地并排呈现，绝不掺进叙述里。两条规则各自在自己的领域里都是对的。真正的错误，是把其中任何一条套用到所有地方。

10. 这一发现如何被落地，而不只是被记下

本周已经上线，这样这个发现就不会退化成一个收藏夹里的书签：这道闸门现在是一条可执行命令；舰队的每周工作流会把它和六维审计放在同一条棘轮机制上运行，并把报告作为构建产物上传；基线已经提交；相关约定写进了升级手册的第 8 节，与实测的 0.27% 并列；另外新增了 22 个测试，覆盖这道闸门本身和那四条已声明的不变量，包括「闸门没有基线时必须拒绝通过」这种情况。

主动的那一半，针对的是新工作，而不是一个清理项目。一个新模块要在写下的那一刻就声明它的不变量或者不声明的理由，趁作者还记得什么是必须始终成立的。回头给已有的 1,501 个模块补声明并不是目标——那样做多半只会造出 1,501 句空话。真正的目标，是让这个数字只能往一个方向变化。

诚实的局限

• 四天算不上业绩记录。 dsh 尚处于开发者预览阶段，且明确写着："THERE WILL BE COMPATIBILITY-BREAKING CHANGES."（中译：将会有破坏兼容性的改动。）我在此报告的是它的各项纪律——这是我能读到、能数出来的部分，而不是它的持久性，那谁也说不准。
• 我跑的是他们闸门的判定逻辑，不是他们的闸门本身。 我的统计数字来自文件系统——packages、companion、已说明的空断言、闸门文件、笔记。我没有真正跑过他们的 CI。
• 我的 0.27% 取决于我对「模块」的定义。 我把范围限定在引擎源码根目录，排除测试、包标记、纯类型文件和第三方引入的代码树。第一次不加区分地全扫时，这个仓库返回的是 196 个模块，而不是 178 个。口径不同，分母就不同。
• 三项计划里有两项还没实现。 R&D 2 和 R&D 3 目前都只是规范，尚未实现。说成已经实现，正是我上周犯过的那个错误。
• 那份综述里的数字是他们的，不是我的。 89%/52.4% 的分野、38% 的解析错误发现，以及 64–88% 的检测区间，都是引用自那篇论文里点名的来源；我并未重新验证过其中任何一个。

临别送上一个数字。从 Blanc 的示范到火枪零件能大规模互换：64 年。从「你必须自报一条限度线」到「你不能自己选这条线画在哪」：14 年。这两段间隔，花的都是打造量具的时间，而不是构思点子的时间。如果你的 harness 是个没有量具的插件架构，那你正处在 1785 年——这没什么不好，前提是你得清楚现在是哪一年。

参考来源

1. deepseek-ai/deepseek-harness ——仓库，docs/architecture.md, AGENTS.md, packages/AGENTS.md, docs/testing.md, .agents/notes/README.md, scripts/。统计数据取自 2026-08-17 的一次浅克隆；元数据（147,620 星标 · 15,083 次 fork · 创建于 2026-08-13）取自当天的 GitHub API。
2. Cordis 与 A Programming Paradigm for Spatiotemporal Composability ——该插件框架 dsh 正是建立在其上。
3. Li, Xiao, Zhang, Liu 等，Agent Harness Engineering: A Survey（我读过并引用的版本；OpenReview 上也有一份，但那个链接需要浏览器验证，打不开 PDF）——ETCLOVG 分类法、170 多个项目的映射、可观测性与评估之间的差距、「harness 即假设」原则、第 12 节的开放问题。eONq7FdiHa
4. RUCAIBox/awesome-agent-harness ——该综述配套的项目索引。
5. Royal Museums Greenwich — Samuel Plimsoll and ship safety 以及 Lloyd's Register Foundation Heritage — What is the Plimsoll line? ——1876 年《商船法》、由船东自行选定标线位置、1886 年贸易委员会发布的载重线表、1890 年该位置被正式写入法律。
6. 230 Years of Interchangeable Parts 以及 go/no-go gauge ——Blanc 于 1785 年的演示与 63 件量具、Gribeauval 的公差带、Springfield 到 1825 年拥有的 11 件主量具，以及 1849 年实现的互换性。
7. Chatterbox, Qwen3-TTS ——本周作为自证据引用的、受许可证限制的语音相关工作。