前言¶
在 DSH 的默认沙箱里，工作区外的写入通常会受到限制。如果希望沙箱内的 CLI 命令或 write/edit 文件工具写入工作区外的受信目录，常见做法是关闭沙箱，或逐次处理审批，但这会削弱沙箱边界，也会拖慢流程。
dsh-sandbox-allowlist 的做法是在保留 DSH 默认沙箱的前提下，增加一组可配置的“沙箱授权目录”。这些目录可以被沙箱内的 CLI 命令与 write/edit 文件工具写入，不需要每次审批，也不需要关闭沙箱。
DSH 的理念是“一切皆插件”，社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。dsh-sandbox-allowlist 由 developerdh 维护，许可证为 MIT。
这是什么¶
dsh-sandbox-allowlist 是一个 DSH 沙箱扩展插件。它向 DSH 默认沙箱的写入边界追加可配置的可信目录，使这些目录在沙箱内可被写入。
它解决的核心问题是：
- 工作区外的受信目录需要被沙箱内 CLI 命令写入。
write/edit文件工具需要写入工作区外的受信目录。- 希望减少逐次审批，同时不直接关闭沙箱。
核心功能¶
沙箱授权目录¶
插件通过 sandbox-allowlist 设置 namespace 管理授权目录。可配置的目录清单支持：
- 多个目录
- 通配符
**，匹配子树 - 通配符
*，匹配一级子目录 - 通配符
?，匹配单个非分隔符字符
这些目录会被追加进 DSH 默认沙箱的可写边界。命中授权目录的写入不需要每次审批，也不需要关闭沙箱。
CLI 命令与 write/edit 工具¶
沙箱内的 CLI 命令可以写工作区外的沙箱授权目录。
write/edit 文件工具也可以在 workspace-write 模式下写入沙箱授权目录。
注意：命中 allow 规则只跳过审批询问，命令仍然受文件沙箱约束，写盘边界不会改变。
命令白名单¶
插件支持命令放行规则，规则动作包括：
allow：放行，不询问ask：询问deny：拦截
规则按声明顺序求值，最后一条匹配的规则生效。未命中命令规则时，插件委托给下游，保留部署原有行为。
平台覆盖¶
插件覆盖：
- Windows：ACL 沙箱
- Linux：
bwrap
Linux 上，landlock / seatbelt 暂不支持。
设置与生效¶
命令规则和授权目录可以通过设置页或 settings.yaml 编辑，实时生效，无需重启。
纯插件实现¶
该插件通过插件机制工作，不修改任何 node_modules / 官方包代码。
Windows 授权回收¶
在 Windows 上，从配置中删除授权目录会触发自动对账，并回收此前写入的写 ACE。
如果回收失败，相关目录会保留在：
$DSH_HOME/sandbox-allowlist-grants.json
下次对账时自动重试。
如果插件被卸载后目录仍残留 ACE，可以使用应急清理脚本：
node scripts/revoke.mjs
安装与启用¶
Node 要求：
>=20.11
安装命令：
dsh plugin --profile web add dsh-sandbox-allowlist
如果进行本地开发调试，也可以先打出 tarball，再安装本地包：
pnpm pack --pack-destination /tmp/pkg
dsh plugin --profile web add /tmp/pkg/dsh-sandbox-allowlist-*.tgz
安装后，可在设置页或 settings.yaml 中编辑 sandbox-allowlist 配置。配置实时生效，无需重启。
典型用法¶
配置沙箱授权目录¶
授权目录配置在 sandbox-allowlist.allowedDirs 中。示例：
sandbox-allowlist:
allowedDirs:
- 'D:\Shared\Tools'
- 'D:\Shared\**'
- 'D:\Data\logs\*'
- 'D:\Work\202?'
- '/opt/tools/**'
含义如下：
D:\Shared\Tools：指定一个具体目录D:\Shared\**：匹配该目录的子树D:\Data\logs\*：匹配一级子目录D:\Work\202?：?匹配单个非分隔符字符/opt/tools/**：POSIX 风格路径同样支持
锚定盘符或根目录且带 ** 的模式会被拒绝，用于防止整盘遍历。不存在的路径会被跳过并告警；如果配置 strict: true，可以改为抛错。
配置命令白名单¶
命令白名单配置在同一个 sandbox-allowlist namespace 下。示例：
sandbox-allowlist:
commands:
default: delegate
rules:
- tool: bash
pattern: 'git *'
action: allow
- pattern: 'rm -rf *'
action: deny
说明：
default: delegate表示未命中规则时委托给下游，保留部署原有行为。rules按声明顺序求值，最后一条匹配的规则生效。pattern支持通配符，可用于忽略命令参数。- 命中
allow只跳过审批询问，命令仍受文件沙箱约束。 deny会直接拦截命令。- 规则通过设置页或
settings.yaml编辑，实时生效，无需重启。
运行自检测试¶
仓库提供以下测试入口：
npm test
npm run test:command-gate
npm run test:patch
npm run test:dry-mount
这些命令可用于验证通配符展开、命令规则、补丁组合和干挂载等行为。
适用场景与注意¶
适合以下场景：
- 需要在沙箱内写入工作区外的受信目录。
- 希望减少 CLI 命令的逐次审批，同时保留沙箱边界。
- 希望用统一配置管理授权目录和命令规则。
- 在 Windows ACL 沙箱或 Linux
bwrap环境中使用 DSH。
使用前需要注意：
- 沙箱授权目录将被沙箱内的 AI 代理直接写入，无需审批。只添加完全信任的目录。
- 授权目录必须已存在且归当前用户所有。
- Windows 上，授权目录需要能修改 DACL。
write/edit工具只在workspace-write模式下放行沙箱授权目录。- Linux 上只完整支持
bwrap；landlock/seatbelt暂不支持。 dsh升级时，如果相关基类签名变化，本插件可能需要小调。- 插件会在当前
dsh进程中运行。安装前应检查源码、依赖和许可证。
结尾¶
dsh-sandbox-allowlist 的价值在于：它不要求关闭 DSH 默认沙箱，也不要求每次写入都走审批，而是通过可配置的授权目录和命令规则，把受信边界显式地配置出来。
目录页：
https://www.skillhub.cn/plugins/developerdh/dsh-sandbox-allowlist
GitHub：
