前言¶
如果你在用 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
