Wisper-beep/dsh-runbox

dsh-runbox

DeepSeek Harness 的隔离执行地基：把 agent 的 shell、文件、进程、终端与后台任务，从宿主本地搬进一次性容器里执行。

一个用于 DeepSeek Harness（dsh）的隔离执行基座。

容器化、可丢弃、有资源与网络边界、执行过程可审计。

当前状态

尚不可用的开发预览。 地基、Docker 后端与 shell 前台执行已落地，并在真实容器上验证通过；其余 provider 按里程碑推进中。

| 里程碑 | 内容 | 状态 |
|---|---|---|
| M0 | 官方 seam 契约、monorepo 骨架、CI、最小插件加载 | ✅ 已完成 |
| M1 | Docker 箱生命周期；shell 前台执行 | ✅ 已在 CI 真机验证 |
| M2 | subprocess 与 fs provider | ✅ 已在 CI 真机验证 |
| M3 | 交互式 stdin | ✅ 已在 CI 真机验证 |
| M4 | 执行世界统一 | ✅ 已完成 |
| M4 | 真实终端（PTY） | ✅ 已在 CI 真机验证 |
| M4 | ctx.terminals 后端、provider-jobs | 未开始 |
| M5 | Web UI（设置 / 状态 / 审计）、网络与资源策略 | 未开始 |
| M6 | Podman / WSL2 / microVM / SSH 第二后端、一致性测试套件 | 未开始 |

各包当前状态：

| 包 | 状态 |
|---|---|
| @dsh-runbox/core | 可用：后端注册表、箱契约、策略翻译、fail-closed 选择 |
| @dsh-runbox/backend-docker | 可用：端点候选探测 + 完整箱生命周期（建 / 执行 / 停 / 删 / 列） |
| @dsh-runbox/provider-shell | 前台执行可用；后台进程与 danger-full-access 明确报错 |
| @dsh-runbox/provider-subprocess | 可用：spawn / 流式输出 / 批式与交互式 stdin / 偏移读取 / 进程树终止 / 真实终端（pty） |
| @dsh-runbox/provider-fs | 可用：读取 / 变更 / 围栏 / 版本守卫 / 换行风格保持 |
| @dsh-runbox/sandbox-bridge | 占位，待 M2 |
| @dsh-runbox/provider-jobs | 占位，待 M3 |
| @dsh-runbox/provider-terminal | 占位，待 M3 |
| @dsh-runbox/ui | 占位，待 M4 |

占位包被调用时抛 RunboxNotImplementedError，不会静默空转——一个“什么都不做也不报错”的 provider 会让上层误以为隔离已经生效。

用途

为什么需要它

DeepSeek Harness 官方文档 docs/subsystems/sandbox.zh.md 写道：

「容器、microVM 和远程执行是完整能力 seam 的同级实现，而非 ctx.sandbox 的提供方。」

官方把这三类点名为预期扩展形态，但尚未实现；社区侧同样是空的（对 npm 上 4646 个 dsh-plugin 做密度探测，容器化执行后端的有效实现为 0，podman 为 0，Windows 沙箱原语为 0。见 research/gap-report.md）。

它做什么

- 真实边界：read-only / workspace-write 由容器挂载标志在挂载命名空间层面强制，不是应用层的自觉。
- 可丢弃、可复现：每份工作区一个箱子，跑完即弃；环境由镜像定义。落在同一工作区下的 shell、文件、子进程与后台任务共用这一个箱。
- 零改上层：实现的是官方 capability seam，审批、权限、成本、审计等既有插件无需改动即可获得隔离能力。
- 失败即拒绝：容器不可用时抛 SandboxUnavailableError，绝不静默回落到宿主执行。

架构

dsh 上层（无需改动）
agent-loop · tool-bash · tool-fs · tool-terminal · tool-jobs · 审批 / 权限
│  只认 seam，不认实现
dsh-runbox
core       后端注册表 · 会话与箱绑定 · 策略翻译 · fail-closed · 审计 · 孤儿回收
providers  subprocess │ fs │ shell │ terminal │ jobs
backends   docker / podman │ wsl2 │ microVM │ ssh        ← 同一接口，可插拔
ui         设置卡 · 状态面板 · 审计时间线
│  Engine API（npipe / unix socket）
一次性容器：只读 rootfs + tmpfs · 工作区同路径挂载 · cgroup 限额 · 默认无网络

包划分

| 包 | 职责 |
|---|---|
| core | 后端注册表、箱契约、SandboxMode → 围栏配置翻译、fail-closed 选择、审计 |
| backend-docker | Docker / Podman Engine API 后端（不依赖 docker CLI） |
| provider-subprocess | ctx.subprocess 实现：spawn 进箱、stdio、退出码、进程树终止 |
| provider-fs | ctx.fs 实现：读写与编辑路由进箱，遵守工作区边界 |
| provider-shell | ctx.shell 实现：箱内 bash 执行器 |
| provider-terminal | ctx.terminals 后端：箱内持久 PTY |
| provider-jobs | ctx.jobs 实现：后台任务登记与回收 |
| sandbox-bridge | 逐调用沙箱模式 → 箱围栏配置，并上报强制执行度 |
| conformance | 验收门禁：加载、注册可逆、fail-closed |
| ui | Web 设置卡、箱状态面板、审计时间线 |

关键机制

契约门禁。 provider-* 包继承官方抽象 seam 类（如 ShellExecutor）。官方 rc 版本一旦改签名，npm run build 直接失败——dsh 处于 developer preview 且明说会有破坏性变更，这是最可靠的一根安全绳。

fail-closed。 后端选择逐个探测，全部不可用时抛 BackendUnavailableError。代码里不存在“降级为不隔离”的分支，并有测试守着。

执行世界一致。 官方要求 ctx.fs 与 ctx.subprocess 共享同一个执行世界，因此 fs.processPath() 交给子进程的路径在箱内必须可打开。做法是让世界由工作区根标识，并按一条确定的规则解析：调用方确知根时（如 shell 拿到 ctx.sandboxPolicy.workspaceRoot）以它为准；否则若 cwd 落在某个已挂载的世界根之下就复用它；再否则以 cwd 自身为根。第二条是收敛的关键——它让“先由 shell 建箱、再由 subprocess 在里面跑”自动落到同一个箱，不需要任何跨 provider 的注册协议。

宿主的 Windows 路径与箱内 Linux 路径的映射由 core/paths.ts 承担（E:\repo\a.txt → /e/repo/a.txt）。

注册即可逆。 所有注册都走 Cordis 的 ctx.effect，返回注销函数，热卸载不留残余。

使用

环境要求

- Node.js ≥ 22
- Docker 或 Podman（M1 起需要；用于承载箱）

安装

git clone https://github.com/Wisper-beep/dsh-runbox.git
cd dsh-runbox
npm ci --legacy-peer-deps

--legacy-peer-deps 是必须的，原因见已知问题。

在 dsh 中加载

核心地基（必需）
dsh plugin --profile web add @dsh-runbox/core

Docker 后端
dsh plugin --profile web add @dsh-runbox/backend-docker

执行层（M1 起可用）
dsh plugin --profile web add @dsh-runbox/provider-shell
dsh plugin --profile web add @dsh-runbox/provider-subprocess

加载 provider 即接管对应能力。每个 context 只能有一个实现，因此挂上 provider-shell 后不应再挂官方的 bash-local。

验证

npm run build   # tsc -b：同时是类型检查与构建
npm test        # 含 M0 加载门禁、fail-closed、策略翻译、引擎探测

开发

packages/    十个包，见上表
docs/        01-选题提案.md（论证与设计）｜ 02-seam契约速览.md（官方接口要点，实现依据）
research/    生态调研证据：4646 插件快照、空白核验、可复现脚本
scripts/     fetch-seam-contracts.py（拉官方类型契约）｜ scaffold-packages.mjs（生成包骨架）

常用命令：

npm run build        # 类型检查 + 构建（= 契约门禁）
npm test             # 单元与门禁测试
npm run seams:pull   # 拉取官方 seam 类型契约 → reference/dsh-seams/（不入库）

reference/dsh-seams/ 是官方包的解包产物（第三方代码，MIT），可用脚本随时重建，因此不提交。契约稳定后应把版本号写回 scripts/fetch-seam-contracts.py 的 MANIFEST 锁定。

契约要点见 docs/02-seam契约速览.md。

已知问题

1. npm ci 必须带 --legacy-peer-deps。

官方 seam 包的 peer 闭包包含一个未发布到 npm 的包：@deepseek-ai/dsh-type-meta（registry 返回 404），npm 的 peer 自动安装会因此中断整个 install。仓库根 .npmrc 已固定该行为。类型层面由 skipLibCheck 兜住，运行时的真实实例由宿主 dsh 提供；上游补发该包后即可移除。

2. 两个 seam 行为尚未实现。

provider-subprocess 的 spawnTerminal 在 pty 不可用时抛错而不退回管道——交互式程序（vim、REPL、top）在管道下会立刻表现出错误行为，而调用方只会看到「程序自己退出了」，排查方向完全是错的。

3. 文件变更在进程内按策略围栏，不绕容器。

provider-fs 的变更由它自己按 ctx.sandboxPolicy 判定（read-only 拒绝一切写入、workspace-write 限定在工作区内），与官方 fs-sandbox 同构；容器侧的只读挂载是进程侧的纵深防御，管的是 bash 越界。两层语义一致，各管一条路径。

4. 需要 Linux 容器引擎。

Windows 容器引擎不支持只读 rootfs（invalid option: read-only mode is not supported for Windows containers），因此兑现不了承诺的文件效果围栏。create() 会先读 /info 的 OSType，非 Linux 直接抛 UnsupportedModeError 并说明怎么办，而不是降级成可写 rootfs 的假隔离。

5. 契约门禁是编译期的。

它能证明签名一致，不能证明行为一致。行为一致性由 packages/conformance 与 backend-docker 的集成用例覆盖——后者在真实容器里建箱、执行、验证宿主无副作用、验证只读真的拒绝写入；引擎不具备时整组跳过而不是失败。

许可
MIT，与 DeepSeek Harness 保持一致。