前言¶
如果你在用 DeepSeek Harness（DSH）開發智能體，模型的 shell 命令默認跑在宿主機上，隔離邊界取決於執行器實現；Windows 上還有一層歷史包袱：早期做法是通過 cmd /c 啓動 npm .CMD shim，模型命令裏的 &、引號、%VAR% 會先被宿主機 shell 解析一遍。要做到「命令在硬隔離環境裏執行、argv 不經宿主機 shell 包裝」，需要一個更乾脆的方案。
下面介紹的 dsh-sandbox-micro 就是爲這件事準備的插件 bundle：把模型可見的 ctx.shell 替換爲 Linux 微虛擬機（microsandbox）中的 bash -c 執行器，同時保留一個直接面向 ctx.sandbox seam 的 provider。
這是什麼¶
omdsh-dev/dsh-sandbox-micro 是 DSH 生態的一個插件包，npm 包名 @deepseek-ai/dsh-sandbox-micro，MIT 許可，當前版本 0.0.1（package.json 中標記 private: true）。它解決的問題是：讓模型發出的 shell 命令在一個 microVM 裏執行，而不是直接落在宿主機上，且啓動探測失敗時寧可拒絕執行、也不退回未隔離模式。
安全模型：fail-closed 與 shell-free argv¶
插件的安全設計集中在三點：
- fail-closed 啓動探測。首次 confinement 前會探測
msb --version和msb doctor（後者檢查宿主機虛擬化前置條件）；失敗時緩存判決並拋出SANDBOX_UNAVAILABLE，絕不退回未隔離執行。 - shell-free argv 構造。不使用
cmd.exe或其他 shell 包裝不可信 argv，而是直接運行 microsandbox 依賴自帶的 Node shim，並顯式拒絕.CMD/.BAT覆蓋路徑。 - 默認斷網。默認加
--no-net，需要網絡時通過allowNetwork: true顯式放開。
另外，執行期的 runner 失敗是可識別的：runnerFailureRules 按 msb 0.6.15 的真實 stderr 方言校準，覆蓋鏡像拉取、掛載路徑、沙箱啓動和無效配置錯誤。
兩個 Cordis 入口¶
這個包暴露兩個 Cordis 入口，職責不同：
| 入口 | 服務 | 用途 |
|---|---|---|
@deepseek-ai/dsh-sandbox-micro |
ctx.sandbox |
直接調用 SandboxProvider.confine() 的兼容 provider。seam 不攜帶 env/cwd，因此 guest 固定爲 /work |
@deepseek-ai/dsh-sandbox-micro/shell |
ctx.shell |
模型 shell 工具實際使用的執行器。它能看到完整 ShellExecSpec，把 workdir 映射到 /work/<sub>，並通過 -e KEY=VALUE 轉發 ENV_OVERRIDES、spec.env 與 DSH_* |
配套的 cordis.patch.yml 做四件事：禁用官方 sandbox / bash-sandbox / pwsh-sandbox，插入 sandbox-micro 與 shell-micro，全平臺啓用 tool-bash，禁用 tool-pwsh（PowerShell 方言無法運行在 Debian guest 中）。
安裝與驗證¶
前置條件：
- Node
^22.19.0 || >=24.0.0 - microsandbox 0.6.15+（已作爲 dependency 隨包安裝）
- Windows 需要 Windows Hypervisor Platform；Linux/macOS 需要 msb 支持的本地後端
- 鏡像必須包含被包裝的程序；默認
debian已包含bash與常用 coreutils
推薦的安裝方式是 Profile Bundle：
dsh plugin --profile web add github:omdsh-dev/dsh-sandbox-micro
dsh plugin --profile headless add github:omdsh-dev/dsh-sandbox-micro
包內 dsh.bundle.patch 會在安裝後自動加入 profile layer stack，不需要手工改 patch。也可以本地打包安裝：
npm pack
dsh plugin --profile web add ./deepseek-ai-dsh-sandbox-micro-0.0.1.tgz
經過上面的步驟，用兩條命令確認配置已生效、執行器確實切換成功：
dsh --profile web --dump-config | grep -E 'sandbox-micro|shell-micro'
dsh run "運行 bash 命令驗證"
配置項¶
shell-micro 繼承 dsh-bash-local 的全部字段，並增加以下字段（sandbox-micro 使用同一組 microsandbox 字段）：
| 字段 | 默認值 | 說明 |
|---|---|---|
image |
debian |
guest 使用的 OCI 鏡像 |
memory |
512M |
VM 內存 |
msbPath |
"" |
可執行文件覆蓋；留空使用內置 microsandbox Node shim |
timeout |
未設置 | msb run --timeout，例如 60s |
extraFlags |
[] |
追加的 msb run flag，例如 ["--cpus", "2"] |
allowNetwork |
false |
true 時移除 --no-net |
probe |
doctor |
啓動探測級別：doctor 或 version |
策略映射與已知邊界¶
Sandbox 策略到 guest 的映射關係如下：
| Sandbox mode | guest 文件效果 | 網絡 |
|---|---|---|
read-only |
workspace 以 :ro 掛載到 /work |
默認關閉 |
workspace-write |
workspace 以讀寫掛載到 /work |
默認關閉 |
danger-full-access |
不進入 VM（由調用方直通） | — |
使用前有四條邊界需要清楚：
- guest 根文件系統與
/tmp是每次命令獨立的可寫層，退出後丟棄；策略語義針對宿主機文件效果。 ShellExecSpec.workdir必須在sandboxPolicy.workspaceRoot內，否則拒絕執行。- 只提供 bash shell；PowerShell 工具由 patch 禁用。
- 模型可見文件路徑從宿主機路徑切換爲 Linux
/work視圖；文件工具仍在宿主機路徑上工作，二者通過 workspace mount 保持一致。
如果你想改這個插件，先做 npm run check（typecheck + 單元測試 + build），再做 npm run test:e2e（可選，真實啓動 microVM 的冒煙測試）。
適用場景與注意事項¶
這個插件適合兩類場景：一是希望模型 shell 命令有微虛擬機級隔離的 DSH 用戶；二是在 Windows 上希望避免宿主機 shell 解析模型 argv 的團隊。注意 danger-full-access 策略下不會進入 VM，由調用方直通，此時隔離收益不適用。
最後提醒一點：插件以當前 dsh 進程的權限運行，安裝前應當檢查插件源碼與許可證（本項目爲 MIT）；同時當前版本爲 0.0.1，接入生產前建議先跑一遍 e2e 冒煙測試確認你的宿主機虛擬化環境可用。
小結¶
dsh-sandbox-micro 把 DSH 的可替換執行器機制用到了隔離這一層：fail-closed 的啓動探測、不經 shell 包裝的 argv 構造、默認斷網，再加上清晰的策略映射，讓模型 shell 命令的執行邊界變得可預期。
- 插件目錄頁：https://www.skillhub.cn/plugins/omdsh-dev/dsh-sandbox-micro（社區目錄，與 DeepSeek、幻方無官方從屬關係）
- GitHub 倉庫：https://github.com/omdsh-dev/dsh-sandbox-micro
