前言¶

在 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