别只信绿灯：DeepSeek Harness 的测试分层

DeepSeek 最近开源的 agent 框架 deepseek-harness（命令行工具叫 dsh）不只会写代码，还把一套相当较真的工程文档一起公开了。其中的测试策略文档讲的不是某个 API 的用法，而是这个仓库如何组织测试，以及靠哪些规则保证「测试全绿」这三个字有含金量。对正在维护自己 agent 项目的团队来说，这份思路值得对照自查。

DeepSeek Harness 的五层测试体系

测试分五层，各管一段

仓库把测试分成五层，每层对应一条命令。

第一层是单元测试，pnpm run test 跑 vitest，测试文件跟着被测代码走，放在各自的 tests 目录，仓库脚本的测试单独收在 scripts 下。每个注册表都要求配一条 HMR 安全测试：把贡献它的 fiber 释放掉，断言清理干净。第二层是覆盖率闸门，pnpm run test:coverage 是真正的门禁，要求 packages 下的源码逐文件 100% 行覆盖。文档对这条的解释很特别：没被覆盖的行，往往不是缺测试，而是闸门在提醒你这一段是死代码，该删掉。同时它也明说，行覆盖只是必要条件，只能证明这些行跑过，不能证明功能按预期工作。没有安装 pwsh 的机器上，执行器测试会自动跳过并在配置里豁免对应文件，让没有 PowerShell 的主机保持全绿；CI 的运行器装了 pwsh，仍然执行完整标准。

第三层是真实 API 的端到端测试，pnpm run test:e2e，拿着 key 打真实的 DeepSeek 模型，还有依赖各自密钥的外部服务冒烟，比如 EXA_API_KEY 和 PERPLEXITY_API_KEY。每个套件在没有 key 时自动跳过，保证无 key 的 CI 不被卡住。第四层是快照测试，无 key 也能跑，用预先录制并落盘的期望输出锁定外部行为：ACP 场景会启动真实的 automation-server 示例，重放一次会话，比对规范化后的 JSON-RPC 和重新写入的日志。模型转写内容变了，就用 record 命令重新录制；回放输入还有效，就用 refresh 更新期望值，每一处差异都要人工过目。第五层是浏览器快照，pnpm run test:web 用 Chromium 把网页界面的回放输出与快照目录逐项对比，这是 Linux 上 PR 的强制门禁。CI 里强制只读的 replay 模式，绝不反写期望输出，录制和刷新只允许在本地做。

带 key 的测试不配给

文档里最直白的一节标题就叫「在这里，推理很便宜」，态度是不要配给真实 API 测试。理由是：无 key 测试只能证明管道通了，只有带 key 的真实运行才能证明 agent 对着真模型确实能干活。要覆盖写文件的提示、多轮对话、工具调用和中途取消。价值最高的是冒烟测试：启动真实示例，发一条 prompt，然后检查世界的状态。这一类测试专门抓「单元测试全绿、产品其实是坏的」，是 mock 抓不住的问题，官方的事故复盘也印证了这一点。自跳过机制的意义是让没有密钥的 CI 和贡献者不受阻，它不是成本信号，只代表没带钥匙的人暂时进不了这扇门。

真实实现优先于 mock

mock 的使用被严格限定：只允许 mock 昂贵或者非确定的边界，比如 LLM 适配器、网络和时钟，边界下游一律用真实现。理由是一手搭的替身只能证明桥上能过字节，证明不了真正发货的工具行为符合断言。文档举的例子是桥接工具调用测试：用脚本化的 mock 模型，接上真实的 bash 工具和执行器，然后真跑一条 echo 命令。

验证世界，而不是验证自述

带 key 政策与外部验证原则

端到端断言的基本功是重新执行一次命令，或者从测试进程外部重读文件。只对 agent 自己的输出做关键词探针是危险的，因为一个会作弊的 agent 恰好能骗过这种检查。还要断言不该动的文件字节保持一致。资源管理上，e2e 测试自己创建 harness，在 afterEach 里释放，失败、重试、超时都不例外；共享的测试装置放进普通的 harness 文件，而不是再写一个 e2e 测试文件，因为在测试代码里 import 另一个 spec 会重复注册用例、重复消耗真实 API 调用。

测真实入口，而不是测理想入口

产品可见的插件必须有真实组合测试：经由 Loader 和应用进程启动真正的配置文件，只 mock 外部服务和不确定输入，断言模型可见的请求、日志、持久化状态或者用户可见的输出。文档还强调，护栏只有在真的拦下回归时才算护栏，验证做法很硬：先引入回归，看着测试变红，再还原。发布物层面同理，包的 bin 入口要用裸 node 跑构建出来的产物，因为开发期的 tsx 会掩盖竞争条件、模块解析失败被吞掉这一类问题，这些只有在构建后的文件里才暴露。