前言¶

写 DeepSeek Harness（DSH）插件时，很多回归问题不会在本地单元测试里立刻暴露：工具 schema 是否过了真实注册表、事件序列是否完整、异常注入是否会崩溃、并发重入是否稳定、挂载后是否留下非预期足迹。这些问题通常要放进 DSH 管线里才能验证。

dsh-windtunnel 就是为这个场景准备的：它把“模型决策”换成剧本，但保留 DSH 真实管线，让插件作者在零 API key、零网络、确定性的环境里跑契约回归。

这是什么¶

dsh-windtunnel 是 DSH 插件，仓库所有者为 BotonJ，当前版本为 0.1.0，许可证为 MIT。

它的一句话定位是：给 DSH 插件作者的契约回归测试舱。

它主要解决三类问题：

1. 插件契约是否稳定：加载、注册、校验、渲染、取消等契约问题。
2. 行为是否可断言：工具调用、结果返回、会话事件序列是否符合预期。
3. 回归是否可进 CI：不依赖真实模型、不依赖网络、结果确定。

它的核心方式是“剧本适配器驱动真实管线”：插件看到的调用可以来自剧本，但插件所进入的 DSH 管线是真实运行的。这样可以在不消耗真实 API key 的情况下，测试插件在管线中的契约与行为。

它能做什么¶

下面介绍已核实的测试能力。

分层测试¶

dsh-windtunnel 提供四层测试：

• L0 加载
• L1 契约
• L2 行为
• L3 注入

具体检查点¶

根据已核实功能，它支持以下检查：

• 非 ctx 足迹快照差分
• 会话事件序列断言
• 并发重入测试
• 负向用例 expectFail 支持
• 隔离子进程执行与崩溃隔离
• CLI 与 bundle 两种使用方式

边界声明¶

这里需要明确它的边界：

dsh-windtunnel 是契约回归网，不是效用测试床。

它验证的是“当工具以给定参数被调用时，管线是否产出预期事件流和结果”，不证明真实模型会主动、正确地调用工具。

安装与启用¶

安装到指定 profile：

dsh plugin --profile <name> add github:BotonJ/dsh-windtunnel

安装后有两种使用方式。

CLI 方式¶

CLI 方式更适合 CI。它直接运行用例，并输出报告：

node bin/windtunnel.mjs cases --timeout 90000 --md report.md

退出码含义：

• 0：全部通过
• 1：存在失败

bundle 方式¶

bundle 方式用于在 DSH 对话内触发。插件装进 profile 后，对 DSH 说：

帮我跑一下插件风洞

模型会调用 windtunnel_run 工具执行测试。

典型用法¶

写一个用例¶

用例文件放在 cases/ 下，例如：

cases/xxx.case.mjs

用例对象需要包含以下字段：

name
profile
disableRows
tools
sutPatch
script
expect

其中：

• name：用例名
• profile：使用的 profile
• disableRows：需要禁用的适配器行
• tools：本次测试关注的工具
• sutPatch：被测插件补丁配置
• script：剧本输入
• expect：预期断言

路径解析上，用例里涉及路径时一律以 import.meta.url 相对解析，不要硬编码绝对路径。

使用负向用例¶

如果某个用例的预期是“违约应该被捕获”，可以加上：

expectFail: true

此时结果语义会反转：

• 红色结果表示正确捕获了契约违约或断言失败，用例通过。
• 绿色结果反而意味着风洞没有检测到预期失败，用例失败。

适合用负向用例检查这类问题：声明了超时却忽略取消信号、对畸形输入处理不完整、渲染结果不完整、事件序列缺失等。

执行模型¶

dsh-windtunnel 的执行模型强调隔离：

• 被测插件在隔离子进程中运行。
• 风洞宿主负责编排与断言。
• 被测插件崩溃时，子进程退出，风洞仍可收集结果并输出报告。
• 子进程内禁用真实网络适配器，配置上通过 overlay disabled: true 禁止出网。

这意味着测试环境更接近“物理上无法出网”的隔离状态，适合做确定性回归。

适用场景¶

它适合以下使用者：

• 写 DSH 插件的作者
• 需要维护插件契约的开发者
• 想把插件回归测试放进 CI 的团队
• 想检查事件序列、工具契约、注入失败、并发重入的插件维护者

注意事项¶

使用前需要注意权限和安全边界。

权限¶

被测插件会在子进程中以全权限执行。

因此，在把未审源码放进风洞前，应先完成静态安检，再进入风洞测试。已核实的要求是：先过 sentinel 静态安检，再进风洞。

安装前检查¶

安装前应检查：

• 源码
• 许可证
• 依赖关系
• 插件入口文件
• 用例中引用的被测插件路径

已知局限¶

dsh-windtunnel 有以下已知局限：

• 效用缺口：不证明真实模型会主动、正确地调用工具。
• 双行重挂载是代理测法。
• 足迹快照是 best-effort。
• rc 期 DSH 违约变更可能先打到风洞自身。

开发与自测¶

本地开发时可以使用以下命令：

node --test test/engine.test.mjs

运行狗食用例：

node bin/windtunnel.mjs cases

运行用例需要本机已经安装 DSH CLI。

结尾¶

dsh-windtunnel 的价值在于把 DSH 插件的契约问题变成可重复、可断言、可进 CI 的检查。它不替代真实模型效用测试，而是给插件作者一张明确的回归网：哪些契约坏了，哪些事件缺了，哪些注入会崩，哪些负向用例本该失败，都能在本地跑出来。

GitHub 仓库：

• https://github.com/BotonJ/dsh-windtunnel