前言¶
在 DSH 裏用 bash 工具跑 lark-cli、gh 這類 CLI 時，常見情況是：命令既要寫會話工作區，又要寫 ~/.lark-cli、~/Library/Application Support/lark-cli/ 或 ~/.config/gh 等用戶目錄。默認的 workspace-write 沙箱只允許寫工作區、/tmp 和系統臨時目錄，寫家目錄會被內核拒絕，模型往往會帶上 sandbox_permissions: danger-full-access 重試，於是每次都要點授權；若把整個會話切成完全權限，又等於放棄文件隔離。
社區裏已有多種「工作區外寫入」方案：有的把命令放到沙箱外執行，有的用配置給所有命令統一加可寫目錄，有的用審批代答。下面介紹的是維護者 laoer 發佈的 dsh-whitelist-auto-approval（npm 包名同插件 id，GitHub：laoer/dsh-whitelist-auto-approval），分類爲 admin-security。它只做一件事：對命中白名單的可執行文件，在內核沙箱內保留工作區可寫，並僅爲該次調用追加聲明的可寫根（默認 $HOME，可用 roots 收窄），從而避免爲寫 token 或緩存反覆申請 danger-full-access，且不把整段會話升權。
這是什麼¶
dsh-whitelist-auto-approval 給 DSH 的 bash 沙箱增加「按命令生效的白名單」。白名單裏的 CLI（默認包含 lark-cli、gh）在 macOS / Linux 上仍跑在內核沙箱裏；命中規則時，可寫根變爲「會話工作區 + 規則裏的目錄」，而不是彈出完全權限授權。非白名單命令行爲不變，該彈窗照舊彈。命令只寫工作區時不需要本插件——默認沙箱已足夠。
和同類做法的差異¶
README 按「放行後命令在哪執行」做了對比，本插件屬於「按命令追加可寫根」：匹配到某條規則時，只在沙箱 profile / argv 上 overlay 額外可寫根，且僅對該次命中的命令生效；匹配的是經 PATH 解析後的可執行文件，不是任意命令字符串。擴展沙箱目錄（如 dsh-write-protect）、帶升級授權的白名單（dsh-sandbox-allowlist）、審批代答類插件，要麼全局加目錄，要麼在沙箱外跑——隔離面更大。需要 deny 規則、網絡策略或按目錄全局授權時，應選用對應方案，而不是指望本插件包攬。
工作原理（簡述）¶
每條 bash 命令會經過 ctx.shell.resolve(request) 得到 sandboxPolicy，再由 ctx.sandbox.confine() 轉成 runner 的 argv / profile。插件在 macOS / Linux 上裝飾這兩步：命中規則則保留 workspaceRoot，設置 extraWritableRoots（默認 $HOME），並在 confine 階段按 runner 追加 overlay（Seatbelt 追加 SBPL、bwrap 加 --bind、Landlock 加 --rw）。overlay 失敗時退回原策略並告警，失敗安全——寧可多彈窗，不會誤放行。Windows 或無法識別 runner 時退回舊行爲（把可寫根換成 $HOME），因 ACL 沙箱無法像 POSIX 那樣追加 profile。
匹配規則（開發者需要知道的邊界）¶
插件根據「整條命令的寫足跡是否落在被信任程序的寫足跡內」判定是否放行，而不是簡單 substring 匹配（除非顯式使用 shape: any）。
在默認 shape: strict 下：
- 管道第一段必須是白名單程序：
argv[0]經PATH+realpath，且可執行文件不能落在工作區 //tmp/ 系統臨時目錄（防同名腳本劫持）。 - 後續管道僅允許寫中立過濾器：
tail、head、wc，參數爲數字或固定開關；不允許tee、| sh、sed -i等。 - 重定向只允許不打開路徑的形態，如
2>&1、>/dev/null。 - 拒絕
;、&&（除可選的cd <dir> &&前綴）、命令替換、heredoc 等；allowCdPrefix默認可剝掉cd /repo && lark-cli ...。 ./lark-cli或/tmp/.../lark-cli等模型指定的路徑形式不匹配。
插件還會註冊系統提示段 tool:bash:auto-approval，把當前規則告訴模型；可通過 promptHint: false 關閉。規則可在設置頁修改，下一輪對話生效，不必在每個倉庫的 AGENTS.md 裏重複。
窄化可寫範圍時，README 建議先用 roots 列出 app 私有目錄並保持 strict，確認無新的 file access denied 後，再對確需複雜 shell 寫法的規則單獨設 shape: any（有額外安全代價，且 any 配整棵 $HOME 會在加載時被丟棄）。
核心功能¶
- 按命令白名單在內核沙箱內追加可寫根，默認放行
lark-cli、gh，避免僅爲寫用戶目錄反覆danger-full-access。 - macOS / Linux 通過 Seatbelt / bwrap / Landlock overlay 實現「工作區 + 額外根」；不替換官方 row，不改審批策略與會話模式。
- 設置頁 命令自動放行（或 Plugins → Command Auto-Approval →
bash-sandbox-auto-approval）管理規則表；保存寫入 profile 的cordis.patch.yml，對下一次 bash 調用立即生效。 - 高級項（
audit、extraPath、allowCdPrefix、upgradeFromReadOnly、trace等）可在~/.dsh/profiles/<profile>/cordis.patch.yml中整段覆蓋同 id 的config（注意是同 id 整段替換，非合併）。
安裝與啓用¶
要求：DSH Desktop（帶 profile），macOS 或 Linux，bash 路徑。包版本在 npm 上可見（資料中示例爲 dsh-whitelist-auto-approval@0.4.0），許可證 MIT。
從 npm 安裝（推薦）¶
在 agent 或支持的環境中：
plugin_manager(action="install_bundle", target="dsh-whitelist-auto-approval")
或在 Desktop Plugins → Add plugin 填寫包名 dsh-whitelist-auto-approval（可帶版本）。
CLI 管理的 profile 可使用：
dsh plugin add dsh-whitelist-auto-approval
Desktop 的 profile 由應用持有，Desktop 用戶請用 Plugins 頁或 plugin_manager，不要假設 CLI profile 與 Desktop 互通。
從 GitHub 或本地目錄¶
plugin_manager(action="install_bundle", target="https://github.com/laoer/dsh-whitelist-auto-approval.git")
plugin_manager(action="install_bundle", target="/絕對路徑/dsh-whitelist-auto-approval")
裝完後若 Plugins 頁未出現 bundle，完全退出 DSH 再打開。首次安裝或更新後需重啓一次以加載 Web 端 client.js；之後在 UI 改規則無需重啓。
典型用法¶
在 UI 中管理白名單¶
經過上面的安裝與重啓：
- 打開左下角 設置；
- 左側點 命令自動放行；
- 在規則表增刪改
command/name/grant/root等，點 保存。
例如默認即已包含 lark-cli 與 gh；跑 lark-cli docs +update ... 且需寫 ~/.lark-cli 時，命中後應在沙箱內完成寫入而不再觸發完全權限彈窗（在 strict 形態下命令需符合 README 中的管道與重定向約束）。
收窄可寫根（YAML 示例）¶
僅允許 Lark 相關目錄可寫、寫法仍用 strict：
- name: lark-cli
command: lark-cli
roots:
- ~/.lark-cli
- ~/Library/Application Support/lark-cli
shape: strict
高級配置需編輯 profile patch，並保留 bash-sandbox-auto-approval 條目下完整 config 字段。
適用場景與注意¶
適合：經常在 DSH 會話裏調用必須寫用戶目錄的固定 CLI（文檔中的 lark-cli、gh），希望減少 danger-full-access 點擊，又不願整會話脫離沙箱的開發者。
不適合：需要 deny 規則、網絡策略、或「所有命令共享一組額外可寫目錄」的場景——應選用 README 對比表中的其他插件。
安全與信任：插件以當前 DSH 進程權限運行；白名單修改僅通過用戶 UI 或 profile patch，不註冊 agent 可改白名單的工具。安裝前請自行查看 GitHub 倉庫 源碼與 MIT 許可證。grant: full 等在 UI 中有顯式警告。社區目錄頁 skillhub.cn 爲獨立生態站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-whitelist-auto-approval 把「寫家目錄」從「每次 danger-full-access」改成「僅對白名單命令追加可寫根、仍在內核沙箱內執行」，在 admin-security 類插件裏補了按命令粒度收緊隔離這一條路。需要細節、匹配表與 overlay 行爲時，以倉庫 README 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/laoer/dsh-whitelist-auto-approval
- GitHub：https://github.com/laoer/dsh-whitelist-auto-approval
