DeepSeek Harness (DSH) 採用全插件化架構。版本升級時，插件兼容性、存儲格式變更以及會話數據遷移是三個主要風險點。dsh-compat-guard 是一個 npm 包，旨在爲 DSH 提供一套兼容性治理方案，包括升級前置閘門、存儲格式指紋校驗、自動備份、會話遷移以及 Profile 級別的鎖文件管理。
核心能力¶
該插件主要解決以下四個場景：
-
升級前置檢查（閘門）
使用dsh-guard preflight進行檢查。它會回答三個問題：插件兼容性、存儲格式破壞性變更、自動備份。如果存儲格式發生破壞性變更，升級將被拒絕（exit 1）。這是爲了防止因存儲格式變更導致的數據丟失事故。 -
插件×DSH 兼容矩陣
通過機器生成的兼容性數據，替代人工撰寫的文章。註冊表託管在 Blue-Whale-Harness 倉庫中，包含插件的兼容狀態和存儲格式信息。 -
會話數據遷移
提供migrate命令。流程遵循安全優先原則：檢測（detectLegacy）-> 備份 -> 轉換 -> 驗證 -> 檢查點。支持將 SQLite 格式轉換爲 zstd JSONL 格式，並對未知格式僅做備份而不強制轉換。 -
Profile 級鎖文件與回滾
生成profiles/<name>/dsh.guard.lock.json。記錄插件版本、配置 Hash、存儲格式版本等信息。支持snapshot（快照）、verify（與鎖文件比對）和rollback（一鍵回滾）。
安裝¶
作爲獨立 CLI 工具安裝：
npm i -g dsh-compat-guard
（可選）安裝到 DSH profile 中以獲得引導期探針：
dsh plugin --profile <name> add dsh-compat-guard
使用¶
日常使用需要將 dsh 命令通過 dsh-guard 包裹，以便在執行插件操作前自動過閘門。
設置別名/函數：
# bash
alias dsh='dsh-guard dsh'
# pwsh
function dsh { dsh-guard dsh @args }
常用命令：
- 狀態檢查：查看當前版本、dist-tags、存儲指紋及鎖文件狀態。
dsh-guard status
- 升級前檢查：執行
preflight，自動備份並檢查插件兼容性與存儲格式。
dsh-guard preflight
- 創建快照與鎖文件：記錄當前 Profile 的完整狀態。
dsh-guard snapshot
- 驗證一致性：對比當前環境與鎖文件，檢測團隊漂移。
dsh-guard verify
- 回滾：恢復到之前的快照。
dsh-guard rollback
- 透傳模式：手動調用
dsh-guard dsh對特定子命令進行前置檢查。
dsh-guard dsh plugin add <plugin-name>
注意事項與邊界¶
- 閘門非強制性：由於 DSH launcher 的
dsh plugin沒有前置鉤子，閘門無法強制攔截。必須通過別名dsh='dsh-guard dsh'的方式在用戶端強制執行紀律。dsh-web-app內部的命令行解析機制也不支持插件樹內掛載第二個解析器。 - 註冊表來源：兼容矩陣數據託管在 Blue-Whale-Harness 的
compat/目錄，默認通過 CDN 獲取。離線時可能需要緩存。 - 格式指紋與未知數據：
lib/formats.json是種子數據。如果目標版本的存儲格式未在註冊表中登記，工具只會警告而不會靜默放行。 - 遷移與驗證：遷移 JSONL schema 必須對照目標版本確認；
verify命令的完整性校驗基於插件package.json的 sha256，而非 npm integrity。
結語¶
dsh-compat-guard 是一套針對 DSH 升級風險的防禦性工具集。通過前置閘門和 Profile 鎖文件，它爲智能體開發環境提供了數據安全的最後一道防線。更多細節可參考 GitHub 倉庫 或 插件目錄。
