前言¶
DeepSeek Harness（DSH）的核心理念是“一切皆插件”。隨着本地安裝的插件數量增加，開發者面臨的問題逐漸從“如何使用”轉向“如何管理”。如何確認一個插件是否與其聲明的能力一致？不同插件之間是否存在衝突？升級 DSH 版本後，現有插件是否還能正常工作？DSH Harbor 針對已安裝在機器上的插件，提供了一份基於證據的只讀賬本。它通過能力清單、聲明與檢測對比、運行時歸屬、衝突檢測、版本漂移追蹤以及升級預檢等功能，幫助開發者在不破壞現有環境的前提下進行治理。
核心能力¶
DSH Harbor 對插件進行證據優先的治理，主要包含以下能力：
- 能力清單：掃描 DSH 配置文件中的所有第三方插件，報告固定的 13 種能力詞彙。源代碼發現結果攜帶
file:line證據，確保來源可追溯。 - 聲明 vs 檢測：將插件在
package.json中的能力聲明與實際檢測情況進行比對，暴露缺失或未知的能力 ID，並在聲明格式錯誤時關閉報告，防止單一壞包影響整體結果。 - 運行時歸屬：在 DSH 主機運行時，枚舉工具、提供者、路由，並將其僅歸屬於當前激活配置文件中安裝的插件。未安裝的插件對應的宿主機註冊表會被標記爲覆蓋缺口。
- 衝突檢測：在賬本中查找同一配置文件下的工具名稱、路由前綴、提供者 ID、客戶端模塊 ID 以及順序敏感的消息鉤子。
- 版本漂移：檢測跨配置文件的版本差異，默認爲本地離線模式。可選的上游檢查獨立於預檢流程，且結果會被緩存。
- 變更時間線：快照追蹤添加、移除、版本轉換、配置文件遷移、能力變更和聲明變更。
- 升級預檢：在升級 DSH 前檢查插件兼容性，驗證
dsh.client.injectID 和宿主機對等範圍，並檢查配置文件中的agent-presets.default是否存在遷移問題。
使用方法¶
DSH Harbor 提供了 CLI 命令用於掃描和預檢。
升級預檢¶
升級前，你可以使用以下命令檢查插件在目標 DSH 版本下的兼容性：
# 列出發行標籤、最新版本和本地緩存的宿主機樹
harbor preflight --list
# 檢查 DSH 的下一個版本（或指定具體版本）
harbor preflight --dsh next
# 檢查特定版本，並以 JSON 格式輸出
harbor preflight --dsh 0.1.5-rc.2 --json
跨進程/非安裝狀態檢查¶
在不處於特定配置文件（如在 CI 環境中）或未安裝某個包時，可以顯式指定檢查對象：
# 檢查當前倉庫（需先構建）
harbor preflight --dsh next --plugin .
# 檢查遠程包
harbor preflight --dsh next --pack @scope/some-plugin@1.2.3
注意事項¶
- 運行環境與權限：DSH 插件在宿主機的 Node 運行時域中運行，擁有與 DSH 本身相同的本地權限。因此，安裝和啓用前應檢查源碼與許可證。
- Node 版本要求：
resolve hook需要 Node.js 版本不低於 20.6。 - 離線模式：默認掃描路徑爲離線模式，只有明確使用
--check-updates、harbor preflight或設置面板中的更新操作纔會聯繫註冊表。 - 配置檢查：DSH 0.1.2 引入了內置代理預設的重命名（
code->ptc）。如果settings.yaml中的agent-presets.default未遷移，新會話將失敗，預檢會報告該問題。 - 賬本性質：DSH Harbor 是已安裝插件的只讀賬本，用於提供證據和發現衝突，而非修復問題。
總結¶
DSH Harbor 專注於對已安裝的 DeepSeek Harness 插件進行客觀、證據優先的治理。它通過提供衝突檢測、版本漂移追蹤和升級預檢等機制，幫助開發者在複雜的插件生態中保持環境的可預測性和穩定性。
