前言¶

在 DeepSeek Harness（DSH）裏裝插件，常見風險不是「裝不上」，而是裝完之後 dsh web 起不來：配置被改亂、node_modules 對不上、某個 bundle 插件在啓動階段直接崩掉。手工回退通常要翻 package.json、cordis.yml 和鎖文件，再跑一遍 pnpm install，費時且容易漏步驟。

dsh-plugin-guard（維護者 lxzy-7）面向這類場景：在每次插件變更前自動快照，啓動失敗時自動回退，並生成事故報告供下一輪 Agent 會話分析。它在 SkillHub 社區目錄的分類爲 admin-security，當前 GitHub 星標 31。

這是什麼¶

一句話：DSH 的插件安裝安全網——安裝前自動快照、一鍵或自動回退、守護啓動、事故報告自動觸發 Agent 分析。

它不靜態審查插件源碼，也不單獨「沙箱測試」插件；而是通過文件快照 + 真實啓動健康檢查，保證每次變更可逆、啓動失敗可自動恢復、事故有據可查。

工作流程¶

下面介紹 guard 在一次插件安裝後的完整鏈路：

安裝插件（任意方式）
   │  tools.guard hook：安裝前進程內自動快照
   ▼
守護啓動（boot-guard 腳本）
   │  啓動前快照 → 啓動 dsh web → 健康檢查
   ├─ 健康 ─────────────────────────────► 正常通過
   └─ 不健康 ─► 自動回退到上一個好快照 → 重試一次
               → 寫入事故報告 + 設置 pending 標記
               → 下一輪會話提示 Agent 分析
               → 修復後調用 incident_resolved 清除標記

問題如何被檢測到¶

理解檢測邊界，才能判斷 guard 能防什麼、防不了什麼。

1、快照是純文件複製。 快照只複製 5 個配置文件：package.json、pnpm-lock.yaml、pnpm-workspace.yaml、cordis.yml、cordis.patch.yml。不運行插件，不評估行爲。

2、啓動級檢測會真正跑一遍 harness。 boot-guard 腳本啓動完整的 dsh web 進程（加載所有已裝插件，包括剛裝的那個），在超時內對 HTTP / 做健康檢查。若插件導致加載錯誤、啓動崩潰或服務無響應，檢查失敗，guard 會殺掉進程樹、自動回退到上一個好快照並重試一次。

自 v0.3.1 起，檢查還會確認 Web 客戶端是否真正渲染——有些插件崩潰會讓頁面黑屏但 HTTP 仍返回 200，此時客戶端會上報渲染崩潰，boot-guard 會回退而非誤判爲健康。事故報告還會記錄每個快照對應的 dsh 版本，並在 harness 升級後插件不兼容、profile 回退無法解決時給出標記。

自 v0.3.2 起，若回退加重試仍失敗（例如 DSH 升級導致插件不兼容），boot-guard 會從啓動日誌定位問題插件，將其 隔離（在 cordis.patch.yml 追加 disabled: true），在不加載該插件的情況下啓動，並報告被隔離的插件及恢復方式（dsh-guard quarantine --undo <id>）。

3、純運行時問題不在安裝時檢測。 插件能正常安裝和啓動，但在特定操作下才崩潰或損壞狀態，guard 無法在安裝階段預測。此類情況可手動調用 dsh_rollback action=incident 生成問題定位報告（最近啓動日誌、服務端 stderr、配置與上一個好快照的 diff），並設置 pending 標記；因每次變更前都有快照，也可隨時手動回退。

核心功能¶

安裝前自動快照¶

通過 tools.guard hook，在進程內於插件安裝前自動拍快照。若在終端手動執行 dsh plugin add，可配合 dsh-guard CLI 先執行 dsh-guard snapshot。

守護啓動與自動回退¶

推薦通過 scripts/boot-guard.sh（macOS/Linux）或 scripts/boot-guard.ps1（Windows）啓動，而非直接運行 dsh web。啓動失敗時自動回退並重試；仍失敗則隔離問題插件。

Web UI 備份管理¶

在 設置 → 備份管理 中：按環境查看快照列表、加載指定備份、手動創建快照、設置每個環境保留的快照數量（最少 2 個）。自 v0.3.0 起，還在 設置 → 插件 → 插件配置 註冊了設置卡片，通過 harness settings 服務編輯同一保留數量，與備份管理面板和 CLI 通過 config.json 保持同步。

Agent 工具¶

每個 profile 會話中註冊以下工具：

CLI（dsh-guard）¶

應用無法啓動時也可使用：

snapshot  [--profile X] [--tag T] [--reason R] [--force]
list      [--profile X]
rollback  [--profile X] [--id I | --good] [--skip-install]
keep      [N]                     # 查看或設置每 profile 保留上限（最少 2）
health    [--port N]
incident  [--kind K] [--no-marker]
resolve
profiles

Windows 一鍵回退¶

包內附帶 scripts/rollback.cmd，安裝後位於 $DSH_HOME/profiles/<profile>/node_modules/dsh-plugin-guard/scripts/rollback.cmd。可創建快捷方式，雙擊即可恢復所有 profile 的上一個好快照並執行 pnpm install --frozen-lockfile。即使應用無法啓動也能工作，且會在環境變量未設置時自行推導 DSH_HOME。

安裝與啓用¶

當前版本 0.3.2，要求 Node.js >= 18，許可證 MIT。以下爲 README 中的安裝命令：

# 從 GitHub 源碼安裝
dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard

# 從倉庫內 tarball 安裝
dsh plugin --profile web add https://raw.githubusercontent.com/lxzy-7/dsh-plugin-guard/main/dist/dsh-plugin-guard-0.3.2.tgz

安裝後重啓 dsh web。這是標準 bundle 插件，加入 profile 層棧後自動生效。（發佈後也可通過 dsh plugin --profile web add dsh-plugin-guard 從 npm 安裝。）

啓用守護啓動（強烈建議）： 用 boot-guard 腳本替代直接運行 dsh web。Windows 啓動器示例：

@echo off
set DSH_HOME=%~dp0.dsh-home
cd /d %~dp0
powershell -NoProfile -ExecutionPolicy Bypass -File node_modules\dsh-plugin-guard\scripts\boot-guard.ps1

可選 CLI shim： 將包內的 dsh-guard（scripts/guard-cli.js）加入 PATH，在終端執行 dsh plugin add 前先 dsh-guard snapshot，或用它包裝自己的 dsh 命令，覆蓋不走 tools.guard hook 的手動安裝。

配置與存儲路徑¶

$DSH_HOME/guard/config.json（首次寫入時自動創建，字段均可選）：

{
  "keepSnapshots": 10,
  "port": 3080
}

• keepSnapshots：每個 profile 保留的快照數，範圍 2–100，默認 10，超出時裁剪舊快照。
• port：健康檢查與事故報告使用的 Web 端口，默認 3080；若 dsh web 使用其他端口需相應修改，CLI 也可傳 --port。

所有路徑以 $DSH_HOME 爲根（未設置環境變量時默認爲 ~/.dsh）：

$DSH_HOME/rollbacks/<profile>/<stamp>/    快照（5 個配置文件 + manifest.json）
$DSH_HOME/guard/logs/                     啓動/服務日誌、事故報告、last-boot.txt
$DSH_HOME/guard/pending-incident.json     待處理事故標記
$DSH_HOME/guard/config.json               guard 設置

回退語義¶

回退 = 恢復 4 個配置文件 + pnpm install --frozen-lockfile，以精確復現 node_modules。回退還會刪除 node_modules 中殘留的 bundle 插件符號鏈接（pnpm 對失效的 link: 條目不會自動清理）。

適用場景與注意¶

適合誰： 經常嘗試社區插件、在 profile 層疊多個 bundle、或需要無人值守安裝回退的 DSH 用戶。尤其適合把 dsh web 當作日常開發入口、不願在配置損壞時手工排查的場景。

需要注意：

• guard 以當前 dsh 進程的權限運行，安裝任何插件前都應檢查源碼與許可證（本插件爲 MIT）。
• 它保證變更可逆和啓動失敗可恢復，不能替代對插件行爲的業務層審查。
• 純運行時故障需主動觸發 incident 或依賴手動回退，不要假設「裝完沒報錯就永遠安全」。
• 健康檢查會真正啓動 harness 及所有已裝插件；若環境對啓動副作用敏感，應先在測試 profile 驗證。

鏈接¶

• SkillHub 目錄頁：https://www.skillhub.cn/plugins/lxzy-7/dsh-plugin-guard
• GitHub 倉庫：https://github.com/lxzy-7/dsh-plugin-guard

SkillHub 是面向中國用戶的 Skills 社區目錄，與 DeepSeek / 幻方無官方從屬關係；DSH 生態遵循「一切皆插件」的理念，guard 是在這層生態裏爲插件安裝過程加的一道安全網。