前言¶

DeepSeek Harness (DSH) 的插件掛載機制在運行時通過 identityFromManifest 函數解析包身份。當插件掛載行中的 name 爲路徑時，系統會向上查找最近的 package.json，並要求 name 和 version 字段均非空。如果缺失或爲空，DSH 會拋出 REQUEST_EXTENSION 錯誤，導致每個官方 DeepSeek 請求失敗。這種錯誤通常被誤認爲是模型或賬號問題。

dsh-plugin-guard 是針對此場景的防護插件，旨在防止因掛載配置不當導致的請求中斷。

插件簡介¶

名稱：dsh-plugin-guard
維護者：Linicc
分類：admin-security
許可證：MIT

該插件通過鏡像上游解析規則，實現三層防禦機制，確保插件掛載配置符合規範。

核心功能¶

插件提供以下核心能力：

1. Startup self-heal
   在插件 apply() 時，掃描所有配置文件的補丁層。對於不符合規範的插件模塊，在旁邊寫入一個最小化的合規 package.json。此過程是全配置文件範圍的，每會話成本約 1ms。

2. Check-on-write
   監聽配置文件的寫入操作（.yml/.yaml）。每次寫入後立即重新審計並修復，將結果輸出到控制台。

3. 三個命令行工具
   - dsh_guard_audit：列出所有可能拋出錯誤的配置行。
   - dsh_guard_repair：爲不合規的插件目錄寫入缺失的 package.json（冪等，不會覆蓋現有文件）。
   - dsh_guard_verify：在掛載前檢查插件條目是否能通過上游解析規則。

安裝與配置¶

推薦以 DSH bundle 的形式安裝。該插件聲明瞭 dsh.bundle.patch，安裝後會自動將插件行插入到配置中。

dsh plugin --profile <profile> add github:Linicc/dsh-plugin-guard

安裝後，需要在配置中啓用插件並設置參數：

- id: plugin-guard
  name: dsh-plugin-guard
  config:
    autoRepair: true       # 自動修復缺失的 package.json (默認: true)
    verbose: false         # 是否輸出審計詳情到控制台
    # profileRoot: "..."   # 默認掃描路徑爲 $DSH_HOME/profiles

使用示例¶

1. 審計當前配置
   運行 dsh_guard_audit 查看哪些行會導致解析失敗。

2. 修復配置
   運行 dsh_guard_repair 自動爲缺失 package.json 的目錄生成文件。

3. 預檢查
   在掛載新插件前，使用 dsh_guard_verify 確認其能通過解析規則。

實現細節與安全邊界¶

插件完全鏡像上游的解析規則（包括路徑判斷、manifest 查找、字段校驗），確保不會出現不一致。

安全邊界：
- 僅當插件目錄完全沒有 package.json 時才寫入，不會修改其他包的 manifest。
- 如果違規的 manifest 屬於祖先目錄（如 profile 根目錄），該問題標記爲 repairable: false，交由人工處理，插件不會自動修改。
- 所有審計和寫入操作均包裹在 try/catch 中，確保插件自身不會成爲導致請求失敗的元兇。

適用場景¶

• 本地開發時，直接掛載文件路徑而非包名。
• 插件目錄缺少 package.json 文件。
• 需要嚴格保證插件掛載配置與上游解析規則一致。

總結¶

dsh-plugin-guard 通過啓動自愈、寫入監聽和命令行工具，爲 DeepSeek Harness 插件掛載提供了安全網。它將原本會導致全局請求失敗的配置錯誤，轉化爲可審計、可修復的本地問題。

插件目錄 | GitHub 倉庫