前言¶
在 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：
