前言¶
寫 DeepSeek Harness（DSH）插件時，很多回歸問題不會在本地單元測試裏立刻暴露：工具 schema 是否過了真實註冊表、事件序列是否完整、異常注入是否會崩潰、併發重入是否穩定、掛載後是否留下非預期足跡。這些問題通常要放進 DSH 管線裏才能驗證。
dsh-windtunnel 就是爲這個場景準備的：它把“模型決策”換成劇本，但保留 DSH 真實管線，讓插件作者在零 API key、零網絡、確定性的環境裏跑契約迴歸。
這是什麼¶
dsh-windtunnel 是 DSH 插件，倉庫所有者爲 BotonJ，當前版本爲 0.1.0，許可證爲 MIT。
它的一句話定位是：給 DSH 插件作者的契約迴歸測試艙。
它主要解決三類問題：
- 插件契約是否穩定：加載、註冊、校驗、渲染、取消等契約問題。
- 行爲是否可斷言：工具調用、結果返回、會話事件序列是否符合預期。
- 迴歸是否可進 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：使用的 profiledisableRows：需要禁用的適配器行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
