前言¶
DeepSeek Harness（DSH）支持通過插件擴展功能，社區維護了一個公共插件列表。在向該列表提交插件之前，需要符合一套具體的規範。手動檢查 dsh.bundle 配置、cordis.patch.yml 掛載關係以及 peerDependencies 的版本範圍容易出錯，尤其是在處理 DeepSeek Harness 的預發佈版本時。
dsh-plugin-preflight 是一個專門用於解決這些問題的工具。它的作用是在提交或發佈插件前，自動驗證其結構是否符合規範，並檢測常見的兼容性問題。
這是什麼¶
dsh-plugin-preflight 是一個零依賴的 DSH 插件，用於對 DeepSeek Harness 插件進行預檢。
- 維護者：AphyTOT
- 許可協議：MIT
- 核心定位：開發者診斷工具，用於在插件提交前進行自動化校驗。
核心功能¶
該工具主要驗證以下五個方面的內容：
- dsh.bundle 清單驗證
檢查dsh.bundle配置是否存在且正確。如果只聲明瞭dsh.client而沒有dsh.bundle，這是導致插件提交被拒絕的最常見原因。 - cordis.patch.yml 掛載檢查
驗證dsh.bundle.patch指向的文件是否存在，以及補丁層是否正確掛載（檢查行名、ID 是否匹配）。 - 客戶端包形狀校驗
檢查dsh.client導出是否正確，確保客戶端模塊系統能夠加載該包。 - Peer Dependencies 兼容性
檢測peerDependencies中的預發佈版本兼容性問題。DeepSeek Harness 會發布預發佈版本（如0.1.5-rc.2），普通的版本範圍可能會靜默排除這些版本，導致運行時ERESOLVE錯誤。 - 清單完整性
檢查package.json是否存在 BOM、營銷語言、缺少倉庫 URL，以及 CLI 可執行文件是否包含在files[]中。
安裝與啓用¶
將此插件添加到當前 DSH 配置文件中：
dsh plugin --profile web add dsh-plugin-preflight
安裝後，它會在 DSH 環境中註冊一個只讀的、面向模型的工具。你可以直接在 DSH 會話中調用它：
plugin_preflight(dir)
典型用法¶
安裝後，可以通過命令行工具在任意目錄下運行預檢。
檢查當前目錄：
npx dsh-plugin-preflight
檢查指定路徑的倉庫：
npx dsh-plugin-preflight path/to/repo
在 CI 環境中使用（遇到警告即報錯）：
npx dsh-plugin-preflight --strict
適用場景與注意¶
適用場景
* 在向 awesome-dsh-plugin 提交插件前進行自檢。
* 在發佈插件到 npm 前確保清單和依賴配置正確。
注意點
- 運行環境：開發環境僅在 Windows 下經過測試。
- npm 發佈：該插件尚未發佈到 npm，直接通過 npm 安裝的路徑未經驗證。
- 本地路徑安裝：使用本地路徑安裝時，系統會創建一個 junction（Windows 下類似軟鏈接），實際是 pnpm link 的行爲。由於 Node 解析 ESM 導入時通過真實路徑向上查找
node_modules，這可能導致無法正確找到宿主包。本插件通過延遲加載宿主包來規避這個問題，確保即使運行時環境不可達，插件也能作爲 CLI 工具運行而不導致 DSH 進程崩潰。 - 預發佈版本驗證範圍：關於
peer/prerelease-tuple的驗證目前僅基於 fixtures（測試數據），尚未在大量真實發布的插件上全面測試。
結語¶
dsh-plugin-preflight 能夠覆蓋插件提交規範中的大部分機器可驗證規則。通過在本地或 CI 中運行它，可以避免因清單配置錯誤或版本範圍陷阱導致的提交被拒或運行時錯誤。
