前言¶
在使用 DSH 進行智能體開發時，常見的問題是智能體依賴摘要數據（如目錄計數）而非第一手證據，誤判數據丟失或狀態異常，進而錯誤修改核心存儲，導致應用崩潰。dsh-agent-guard 是爲此類場景設計的 DSH 柵欄插件，它要求智能體先讀取證據再執行操作，並在寫入時進行攔截與備份。
是什麼¶
dsh-agent-guard 是一個 DSH 安全護欄插件。它的核心價值在於：證據優先的只讀檢查、寫入時的治理攔截，以及每回合的回滾點記錄。該插件零運行時依賴、無網絡請求、無遙測數據。它由用戶 a5557 維護。
核心能力¶
證據優先的只讀檢查¶
插件通過 guard_inspect 工具讀取所有會話的第一手身份頭信息。它會識別並標記 DSH 內部刻意不註冊的 origin: "subagent" 記錄，避免將內部數據結構誤判爲數據丟失。
寫入治理與攔截¶
插件在 tools/pre-execute 階段攔截受保護的寫入操作：
1. 拒絕未停止時的寫入：當 DSH 未確認停止時，對核心數據的寫入一律拒絕。
2. 備份再允許：允許的寫入必須先備份，默認限制爲 8MiB/文件。若備份失敗或超限，寫入被拒絕。
3. 斷路器機制：若同一路徑連續兩次寫入且校驗和不一致，觸發斷路器，需人工介入。
4. 腳本生成攔截：智能體生成的 .bat/.cmd/.ps1/.sh 若引用受保護路徑，會被標記爲 emit-script 並拒絕。
每回合回滾點¶
插件維護每回合的回滾點。當發生破壞性操作時，這些點可用於恢復狀態。
客戶端 UI 集成¶
插件提供客戶端 UI，集成在側邊欄和設置頁面中，顯示護欄狀態、回滾點和最近受保護的操作。
安裝與啓用¶
安裝插件需要指定 profile。插件在 package.json 中聲明瞭 dsh.bundle.patch，因此添加包後會將其掛載爲 profile 層。
# 從註冊表安裝指定版本
dsh plugin --profile <profile> add dsh-agent-guard@0.1.0
# 從本地目錄安裝（路徑需絕對）
dsh plugin --profile <profile> add <absolute-path-to-this-directory>
典型用法¶
插件提供了命令行工具，同時也通過 UI 自動攔截。
工具命令¶
# 生成證據報告（只讀，不修改任何數據）
guard_inspect(scope?, workspace?, maxSessions?, includeHeaders?, redact?)
# 查看護欄自身狀態與日誌
guard_journal(action?, limit?, snapshot?)
自動攔截規則¶
上述攔截規則在插件安裝後自動生效。guard_journal 的 action: "trace" 可查看單次操作詳情，action: "rollback" 則返回人工回滾指令（無自動回滾功能）。
注意事項與清理¶
數據持久化¶
卸載插件 (dsh plugin --profile <profile> remove dsh-agent-guard) 僅移除註冊配置，不會刪除任何數據，包括回滾點。如需清理，需手動刪除數據目錄。
# 清理回滾點數據（手動操作）
rm -rf "$DSH_HOME/agent-guard"
pnpm 殘留¶
插件不會清理 pnpm 生成的 node_modules/.bin/dsh-agent-guard* shim 文件，這是 pnpm 的行爲，非插件殘留。
UI 限制¶
UI 界面嚴格爲只讀。沒有修復功能、遷移功能或回滾按鈕。
結語¶
dsh-agent-guard 爲 DSH 提供了底層的安全防線，確保智能體在讀取證據的基礎上進行操作，防止因誤判導致的數據破壞。相關文檔與源碼可參考社區目錄或 GitHub 倉庫。
