前言¶
DSH 的插件體系把能力拆到多個插件裏，但插件聲明不完整、任務原地循環、子代理嵌套過深、宿主重啓打斷會話等問題，都會影響正在執行的任務。
akira399/dsh-guardian 針對這些情況提供檢測和引導：它不直接終止任務，而是通過注入 user/message 引導 Agent 調整方向，同時提供預檢、狀態查詢和事件日誌入口。
這是什麼¶
dsh-guardian 是 DeepSeek Harness（DSH）任務防護插件，由 akira399 維護，許可證爲 MIT，版權標註爲 MIT © 2026 dsh-guardian contributors。
它的定位是：通過插件預檢、循環檢測、遞歸防護與中斷感知做檢測和引導，永不終止任務。package.json 聲明運行環境爲 node >=20。
核心功能¶
插件預檢¶
插件預檢用於檢查插件源碼中的服務聲明是否與用法一致。它會靜態分析 ctx.<服務> 用法與 inject 聲明是否一致，可識別缺失 timer、tools、settings 等服務，並給出修復提示。
預檢命令如下：
node <dsh-guardian>/scripts/preflight.mjs <插件目錄或 index.js>
也可以在代碼中調用：
import { scanSource } from "dsh-guardian/preflight";
循環檢測¶
循環檢測關注同一工具調用是否反覆發生。
當同一工具調用，按“名稱 + 參數指紋”判斷，在滑動窗口內重複達到 maxLoopRepeats 時，插件會判定爲循環，然後注入換方向提示，並記錄 LOOP_DETECTED。
遞歸防護¶
遞歸防護關注子代理和工作流嵌套深度。
當子代理或工作流嵌套深度超過 maxSubagentDepth 時，插件會注入收斂提示，並記錄 RECURSION_DETECTED。
中斷感知¶
中斷感知通過狀態路由提供當前會話的運行信息。
狀態路由會返回：
runningbusy- 嵌套深度
- 近期調用數
safeToRestart
其中 safeToRestart 用於判斷當前是否適合重啓。資料中的安全重啓助手會先查這個字段：如果存在運行中會話，則拒絕重啓，除非使用 -Force。
事件日誌與狀態查詢¶
事件會寫入 guardian/events.jsonl。資料中給出的本地查看路徑爲：
~/.dsh/guardian/events.jsonl
狀態路由可以查詢最近 50 條事件。
不終止任務¶
dsh-guardian 的核心行爲是引導，而不是終止。
它通過注入 user/message 引導 Agent 調整方向，不會主動結束任務。
安裝與啓用¶
由於插件以當前 dsh 進程權限運行，安裝前建議先檢查源碼與許可證。
確認環境滿足 node >=20 後，執行安裝命令：
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-guardian
插件默認啓用。修改 guardian 配置後熱生效，無需重啓。
典型用法¶
運行插件預檢¶
對某個插件目錄或入口文件做預檢：
node <dsh-guardian>/scripts/preflight.mjs <插件目錄或 index.js>
在代碼中調用預檢¶
如果需要在自己的工具鏈裏做靜態檢查，可以導入預檢模塊：
import { scanSource } from "dsh-guardian/preflight";
查看狀態¶
狀態路由如下：
GET /api/dsh-guardian/status
資料中也給出了具體地址示例：
GET http://127.0.0.1:3080/api/dsh-guardian/status
返回內容包括 running、busy、嵌套深度、近期調用數和 safeToRestart，並可查詢最近 50 條事件。
安全重啓助手¶
安全重啓腳本會先檢查 safeToRestart。如果仍有會話運行，它會拒絕重啓，除非使用 -Force。
命令示例：
powershell -NoProfile -ExecutionPolicy Bypass -File <dsh-guardian>\scripts\safe-restart.ps1
資料中僅說明強制重啓可加 -Force，未給出完整命令。
配置示例¶
settings.yaml 中的 guardian 配置示例如下：
guardian:
maxLoopRepeats: 4
maxSubagentDepth: 3
修改 guardian 配置後熱生效，無需重啓。
查看事件日誌¶
事件日誌路徑示例：
~/.dsh/guardian/events.jsonl
資料中事件日誌路徑同時出現 $DSH_HOME/guardian/events.jsonl 與 ~/.dsh/guardian/events.jsonl，兩者關係未明確。
運行驗證¶
資料中給出的驗證命令：
pnpm verify
適用場景與注意¶
適合需要管理 DSH 插件、檢查插件聲明、觀察長任務狀態，並希望在重啓前確認會話是否安全的人。
使用注意：
- 插件以當前
dsh進程權限運行，安裝前應檢查源碼與許可證。 dsh-guardian只做檢測和引導，不終止任務。- 資料未確認插件分類與星標數。
- 目錄頁鏈接來自線索，未抓取目錄頁正文。
safe-restart.ps1的強制重啓資料僅說明可加-Force，未給出完整命令。
結尾¶
dsh-guardian 的價值在於把 DSH 任務運行中常見的風險點做成可檢查、可觀察、可引導的防護路徑：插件預檢、循環檢測、遞歸防護、中斷感知，以及安全重啓檢查。它不提供任務終止動作，而是通過提示和事件記錄幫助 Agent 和開發者保持任務可控。
GitHub：
https://github.com/akira399/dsh-guardian
目錄頁（線索，未抓取正文）：
https://www.skillhub.cn/plugins/akira399/dsh-guardian
