前言¶

在 DeepSeek Harness（DSH）裏，子代理並不是「縮小版父會話」，而是在創建瞬間被固定的一份權限快照：審批策略恆爲 never，沙箱檔位只繼承父會話當時的顯式 override。父會話若運行在 danger-full-access，子代理同樣不套沙箱，且模型側沒有放寬通道。Harness 把這叫 snapshot-at-delegation——子代理保留派發那一刻交出去的策略，卻沒有運營者的全局判斷。

對需要在生產或共享宿主上啓用子代理的開發者來說，缺口在於：框架刻意不在快照之上再設運營者可調的天花板。社區插件 dsh-subagent-guard（維護者 NightPainters，分類 admin-security）在這份快照之上疊三道閘：沙箱檔位硬頂、破壞性命令 denylist，以及通過 delegate 工具固定子代理的工具面與說明段落，並在冷恢復路徑上儘量把收窄後的面找回來。

這是什麼¶

dsh-subagent-guard 是 DSH 的安全向插件，一句話定位是：給子代理加 sandbox cap、破壞性命令拒絕列表、工具面限制，以及冷恢復時的策略重建。倉庫地址：GitHub — NightPainters/dsh-subagent-guard；社區目錄頁：SkillHub — NightPainters/dsh-subagent-guard（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。DSH 生態本身是「一切皆插件」；本插件解決的是子代理權限繼承過寬、shell 類工具誤傷宿主、以及官方 subagent 路徑無法可靠收窄工具面的問題。

核心功能¶

下面按 README 中的「三道閘」介紹；行爲以插件加載後的配置爲準，啓動時會打印一行生效配置（例如 subagentSandboxCap、規則條數等），便於覈對文檔默認值與部署值是否一致。

閘一：沙箱檔位硬頂¶

在 agent/created 時讀取子代理當前生效的沙箱檔位（會話 override 或部署默認）。若比配置項 subagentSandboxCap 更寬，則追加 sandbox/mode 事件將其壓下去。只降不升：已是 read-only 的子代理不會被抬到 workspace-write。

讀檔位發生在事件觸發時，而不是插件 apply() 時（0.4.3 起），避免服務尚未註冊時誤把更窄的子代理抬到 cap。若事件時仍讀不到檔位，則 fail-closed：強制壓到 subagentSandboxCap 並記 error。僅對插件加載之後創建的子代理生效。在 UI 或 profile 裏關閉「權限攔截」（enforceSandbox: false）會跳過整道閘，子代理完全跟隨父會話檔位。

閘二：命令黑名單¶

通過 ctx.tools.guard() 註冊單調門：在 tools/pre-execute 瀑布之後運行，返回字符串即拒絕，無 ask 繞過，子代理的 never 審批策略也繞不過。

檢查對象不是工具名白名單，而是參數裏攜帶命令串的工具，參數名由 commandArg 指定（默認 command）。默認規則覆蓋卷影刪除、還原點、磁盤分區、引導配置、關機重啓、cipher /w、sdelete 等難以靠日常文件操作恢復的場景；故意不攔 Remove-Item、del、rmdir 等，避免 agent 無法工作。匹配前對命令做歸一化（折行續寫、去引號、空白摺疊等，0.4.5）。

開啓 scriptInspection: true（默認）時，對 pwsh -File、bash ./script 等顯式腳本執行形式，會讀取目標文件內容再過同一套規則；超過 maxScriptBytes（默認 256 KiB）則拒絕執行。作用域由 denyScope 控制，例如 subagent 只攔子代理會話內的命令。

閘三：delegate 與工具面¶

DSH 0.2 起對外關閉了子代理工具的 persona / toolFilter 參數，但冷恢復路徑上 harness 仍會用 systemPrompt.section 與 tools.restrict。本插件註冊 delegate 工具：參數爲 prompt，以及可選的 persona、tools。流程是先在父會話 id 下登記策略，再 subagents.startActivation() 創建子代理，在 agent/created 中認領並施加；若子代理未消費策略則 cancel 並拋錯（fail-closed）。

除 restrict 可見面外，還在子代理上下文註冊 agent-scoped 的 guard，拒絕不在白名單內的 scoped 工具（例如未授權的 subagent）。開啓 enforceMaxTools: true 時，最終工具面爲模型傳入的 tools 與部署 maxTools 的交集。冷恢復時（0.4.3 起）會從子會話日誌中的固定說明段落與 可用工具： 行等重建收窄面；細節與邊界見倉庫 README.zh-CN「已知邊界」。

安裝與啓用¶

官方安裝命令如下：

dsh plugin add dsh-subagent-guard

也可在 profile 裏聲明爲 file: / link: 依賴，並把 dsh-subagent-guard 加入 dsh.profile.bundles；bundle 自帶 cordis.patch.yml，註冊行會自動插入。

運行環境要求（來自 package.json）：Node ^22.19.0 || >=24.0.0；peer 依賴 @deepseek-ai/cordis（>=4.0.4，optional）。插件以當前 DSH 進程權限運行，安裝前請自行審閱源碼與 MIT 許可證。

在 DSH 界面打開 插件 → dsh-subagent-guard，「描述」與「包含的組件」之間的卡片提供兩個 volatile 開關：工具面攔截（enforceToolFace）、權限攔截（enforceSandbox），點擊即寫入 profile patch 並立即生效。更細的黑名單、工具清單、腳本檢查應在 bundle 的 cordis.patch.yml 或 profile 按 id 覆蓋，例如：

- insert:
    - id: dsh-subagent-guard
      name: dsh-subagent-guard
      config:
        enabled: true
        enforceToolFace: true
        enforceSandbox: true
        subagentSandboxCap: workspace-write
        denyScope: subagent
        commandArg: command
        scriptInspection: true
        maxScriptBytes: 262144

自定義 denyPatterns 時須用 YAML 雙引號包裹正則源串；單引號會導致反斜槓被當作字面量，規則可能全部失效且無告警。若使用閘三的 delegate 並傳 tools，請使用 0.3.7 及以上版本：0.3.6 及更早在 fail-closed 取消路徑上可能觸發會話回放 fatal（見倉庫 docs/incidents/2026-10-29-cancel-cause-fatal.md）。

典型用法¶

1、安裝插件並確認啓動日誌中的生效配置與預期一致。

2、保持 enforceSandbox: true，將 subagentSandboxCap 設爲部署可接受的上限（如 workspace-write），避免父會話爲 danger-full-access 時子代理同檔裸奔。

3、需要收窄子代理能力時，讓父 agent 調用插件提供的 delegate（而非僅依賴官方 subagent）：在 tools 中列出允許的工具名；若需部署級上限，配置 enforceMaxTools: true 與 maxTools 列表。

4、僅希望子代理側攔破壞性 shell 命令時，保持 denyScope: subagent；父會話日常操作不受影響（在 delegationDepthOf 正常的前提下）。

5、驗證行爲可運行插件自帶測試（脫離宿主）：在插件目錄執行 npm test（README 記載爲六個套件、129 條用例）。

適用場景與注意¶

適合：在共享或高權限父會話下仍要派生子代理的團隊；希望默認擋掉刪卷影、格式化磁盤、關機等不可逆操作的部署；需要通過 delegate 明確子代理工具面、並關心 idle 喚醒後工具面被撐大的場景。

務必知曉：

• 正則與腳本 inspection 是事故與誤操作層面的護欄，不是對抗混淆或動態構造命令的沙箱；run_code、node -e、多層腳本鏈等仍依賴閘一的沙箱檔位兜底。
• 卡片上的兩個開關可被持有同一 Web 會話的人（或擁有 ego_* 等瀏覽器操作工具的 agent）改掉，開關本身不是權限邊界。
• 閘三隻約束本插件註冊的 delegate；窗口外官方 subagent / subagent_fork 仍可用，工具面可能未被收窄（閘一仍會壓沙箱）。README 對 CVE-2026-82533 等內核/本地 API 層風險有說明：策略層插件無法替代非管理員賬戶與可快照宿主。
• 社區目錄頁星標等元數據以站點展示爲準；功能與配置以 GitHub README（含 README.zh-CN.md）爲準。

結尾¶

經過上面的步驟，你可以在不動 Harness 快照語義的前提下，爲子代理加上運營者可調的沙箱天花板、單調的命令 guard，以及可 fail-closed 的委派工具面。進一步的黑名單規則、冷恢復邊界與版本變更見倉庫 CHANGELOG 與文檔目錄。

• 目錄頁：https://www.skillhub.cn/plugins/NightPainters/dsh-subagent-guard
• GitHub：https://github.com/NightPainters/dsh-subagent-guard