dsh-plugin-container

> DeepSeek Harness（DSH）的 Docker 容器沙箱 部署级插件。 > 在会话视图环中新增「容器」页签，提供 仅观察 / 干预 双模式原生 UI、**39 个 docker_* 模型工具、15 个 /dock-api/* HTTP 路由，并完整对齐官方 dsh-plugin-vm-sandbox v0.1.0 的全部能力**：快照/回滚、文件传输、端口转发、后台任务、审计、共享协作、配额与回收、网络策略、自定义资源、初始化脚本、多容器并行执行、增强状态查询。

---

为什么需要这个插件？

官方 dsh-plugin-vm-sandbox 依赖 OrbStack（macOS 专属）。Linux 用户与 Windows 用户没有 OrbStack，就无法获得会话级沙箱能力。

本插件以 本地 Docker Engine 作为底层，把 VM 沙箱的能力一一映射到 Docker：

> Docker 与 OrbStack 是两种不同抽象：OrbStack 的 orb clone 按需复制磁盘、orb push/pull 直接进入 VM；Docker 版本使用 docker commit 镜像快照与 docker cp 文件传输，语义等价、实现完全 Docker-native。网络策略则通过 dsh-sandbox 公网 bridge 与 dsh-sandbox-internal 内部网络（docker network create --internal）实现。

---

项目定位

• 部署级插件：与官方 VM 沙箱一致，不依赖私有 RPC。面板数据全部通过宿主 webServer 暴露的 /dock-api/* 标准 HTTP 路由获取。
• 官方目录结构：严格参照 dsh-plugin-vm-sandbox 仓库布局（根包 prepare → dsh-plugin-container/lib 发布入口；内层 dsh-plugin-container/ 为 npm 发布包；cordis.patch.yml 自动插入 ui-container）。
• 零运行时依赖：Host 半区只使用 Node 内置模块与官方 docker CLI；Client 半区仅依赖 react 浏览器模块。
• 跨平台：只要 Docker CLI 能连上 Docker Engine 即可使用 —— Linux、Windows（Docker Desktop）、macOS（Docker Desktop / OrbStack Docker context）全部支持。

功能特性

原生级 UI（会话视图环「容器」页签）

• 毛玻璃渐变背景、状态呼吸灯、玻璃拟态统计卡、丝滑展开/切换动画。
• 顶部模式切换：仅观察（默认，隐藏全部写操作）/ 干预（显示创建、启动、停止、重启、快照、删除）。
• 容器 / 快照两个视图；容器支持搜索与「全部 / 本会话 / 运行中」过滤。
• 每个容器行内展示状态、镜像、CPU / 内存占用；展开后提供 概览 / 日志 / Shell / 任务 / 端口 五个页签。
• 概览：完整 inspect 配置、挂载、实时 CPU/内存/根分区、uptime、资源限额。
• 日志：docker logs 最近 500 行，支持跟随刷新。
• Shell：docker_exec 执行记录（命令 / 耗时 / 退出码 / stdout+stderr）与 只读实时 stdout/stderr 观察流（暂停 / 清空 / 重连，90 秒无读取自动回收）。
• 任务：该容器的后台任务列表；端口：该容器的端口转发隧道列表。
• 创建弹窗：镜像、名称、CPU / 内存 / shm / 磁盘配额、启动命令或初始化脚本、端口 / 环境变量 / 卷、网络、重启策略、内部网络 / 完全无网络 / TTY。
• 快照弹窗：备注说明后一键 docker commit 快照；快照列表支持一键恢复 / 删除。
• 全部使用 DSH 官方 --dsw-alias-* 设计令牌，自动适配浅色 / 深色主题与品牌变量。
• 静态设计稿：见仓库 [docs/ui-preview.html](./docs/ui-preview.html)。

快照与回滚

• docker_snapshot：基于官方 docker commit --change LABEL ... 生成带 dsh.snapshot=1 标签的快照镜像，自动保存来源容器的 run spec（端口 / 卷 / 环境 / 网络 / 资源限额 / 命令）。
• docker_snapshot_list：列出全部快照及本会话快照。
• docker_restore：删除当前容器 → 用快照镜像 + 原 run spec 重建 → 按原状态启动 / 保持创建态；快照记录保留，可重复回滚。
• docker_snapshot_delete：docker rmi -f 永久删除快照镜像。
• 限额：全局 64 个、每会话 16 个。

文件传输

• docker_upload / docker_download：基于官方 docker cp，支持文件与目录递归。
• local_path 强制约束在 DSH 工作区内（sandboxPolicy.workspaceRoot），防止任意宿主机路径读取。

端口转发

• docker_port_forward：在容器所在 bridge 网络上启动 alpine/socat 代理容器，-p 127.0.0.1:host_port:proxy_port 映射到本地回环；无需修改原容器、无需重建。
• 自动分配空闲本地端口或指定 host_port；bind_host 仅允许 localhost / 127.0.0.1 / ::1。
• docker_port_forward_list / docker_port_forward_stop（按 tunnel_id 或 host_port 停止）。
• 隧道状态持久化，容器删除 / 恢复 / 插件对账时自动回收代理容器。

后台任务

• docker_job_submit：命令经 base64 写入容器 /tmp/.dsh-jobs/<job-id>/，以 nohup sh run.sh & 在容器内后台执行，不受单次 docker_exec 超时限制。
• docker_job_list / docker_job_status / docker_job_stop / docker_job_output。
• 每会话最多 32 个运行中任务；容器删除 / 恢复时自动终止并标记错误。

审计

• 所有 39 个工具调用（含 docker_cli 直通）统一经过审计包装器：记录 sessionId、容器、操作名、参数摘要、耗时、成功 / 失败与错误。
• 面板操作（创建 / 启停 / 删除 / 快照 / 恢复）同样写入审计。
• docker_audit 支持按 session / container / operation 过滤。

共享协作与资源治理

• docker_share / docker_unshare：把当前会话容器共享给其他会话；mode=exec（执行 / 传输 / 任务 / 端口转发）或 mode=manage（额外允许生命周期 / 网络 / 快照）。
• docker_policy：每会话最大容器数（1–8，默认 8）、闲置自动停止分钟数（默认 30）、闲置自动删除天数（默认 0 关闭）。
• 全局运行上限 64，超过后仅自动停止本插件创建的、超过 15 分钟未使用的旧容器，绝不干扰用户手工容器。
• 归档 / 删除会话自动清理其容器；domain/changed、session/disposed 事件驱动 + 每 5 分钟对账。

网络策略

• docker_network_policy：public_access / internal_access / isolated / isolate_network。

- public_access=false：保存当前网络，断开除 dsh-sandbox-internal 外的网络，接入 --internal 内部网络（无法访问公网）。 - internal_access=false：断开沙箱内部网络。 - isolated=true：断开全部网络，等价 --network none。 - isolate_network=true：仅保留内部网络并强制 public_access=false。

• 策略持久化，容器每次启动时自动重新应用。

基础 Docker 能力（保留并增强）

原有 18 个工具全部保留：docker_info、docker_ps、docker_images、docker_pull、docker_run、docker_start、docker_stop、docker_restart、docker_rm、docker_rmi、docker_logs、docker_exec、docker_inspect、docker_stats、docker_network、docker_volume、docker_build、docker_cli。

---

架构

浏览器 (client, lib/client.js)                       Node (host, lib/index.js)
┌────────────────────────────────────────┐  fetch   ┌───────────────────────────────────────────┐
│ window.__ModuleLoader__.load({...})    │ ───────▶ │ webServer.register({kind:'exact',...})     │
│ slots.inject('conversation.view')      │          │ /dock-api/status|inspect|logs|top|op|      │
│ 原生 UI: 模式/统计/创建/详情/日志/Shell │ ◀─────── │   create|shell|snapshot|restore|...        │
│ 快照/任务/端口视图                       │  JSON    ├───────────────────────────────────────────┤
└────────────────────────────────────────┘          │ tools.register × 39 (docker_*)             │
                                                     │ execFile/spawn('docker', ...)              │
                                                     │ 状态 ~/.dsh/container-sandbox/state.json  │
                                                     └───────────────────────────────────────────┘

• Host 侧：零外部运行时依赖；负责执行 Docker CLI、维护日志观察 / socat 代理子进程、注册 HTTP 路由与模型工具、治理配额 / 闲置回收 / 归档清理。
• Client 侧：CJS closure-factory bundle，仅依赖 react；注入 conversation.view（id docker，order 10.5，label「容器」）。
• 可卸载性：路由 disposer、工具注册、watcher 进程、socat 代理、定时器与样式均通过 ctx.effect 管理，插件卸载时自动清理。

安全模型

• 默认只读 UI：未切换到「干预」模式前不显示任何写操作入口。
• 删除二次确认：容器删除需二次点击确认；快照删除使用原生 confirm 二次确认。
• Shell 观察无交互通道：只读 docker logs -f 流，不带 stdin，模型无法通过该面板注入命令。
• 工作区路径约束：docker_upload / docker_download / docker_build 的宿主机路径必须位于工作区内。
• 共享权限边界：插件登记的容器按 owner / exec / manage 三级校验；跨会话未共享的操作会被拒绝。
• 不引入私有 RPC：面板全部走标准 HTTP 路由，权限边界与 DSH 部署插件保持一致。
• 输出截断与超时保护：长输出截断、Docker 调用默认 120 秒超时（pull/build 等长任务 10–15 分钟上限）。

安装

方式 A：dsh CLI 从 GitHub 安装（推荐）

需要已安装 pnpm 与 dsh CLI：

npx -p @deepseek-ai/dsh dsh plugin --profile web add https://github.com/GHJIVHIDD/dsh-plugin-container
# 或 git 简写
npx -p @deepseek-ai/dsh dsh plugin --profile web add GHJIVHIDD/dsh-plugin-container

安装过程由官方机制自动完成：

1. pnpm 从仓库安装包并写入 profile 的 dependencies。 2. 根据 dsh.bundle 声明自动 reconcile 进 dsh.profile.bundles 层。 3. 应用 cordis.patch.yml，自动插入 ui-container 行，无需手工编辑配置。

重启 dsh（web 或 headless）后刷新浏览器即可看到「容器」页签。

方式 B：Releases tgz 安装

从 Releases 下载 dsh-plugin-container-1.0.3.tgz，在包所在目录执行：

dsh plugin --profile web add ./dsh-plugin-container-1.0.3.tgz

方式 C：手动安装

# 1. 将包复制到 profile 的插件目录
cp -R dsh-plugin-container ~/.dsh/profiles/web/node_modules/@dsh-community/

# 2. 在用户补丁层注册插件行
cat >> ~/.dsh/profiles/web/cordis.patch.yml << 'EOF'

- insert:
    - id: ui-container
      name: '@dsh-community/dsh-plugin-container'
EOF

# 3. 重启 profile

卸载

dsh plugin --profile web remove @dsh-community/dsh-plugin-container
# 手动安装的：移除补丁中的 ui-container 行并删除包目录

使用

dsh --profile web

进入任意会话点击「容器」页签；智能体可直接调用 docker_create、docker_exec、docker_snapshot、docker_upload、docker_job_submit、docker_network_policy 等 39 个工具管理 Docker 沙箱。

兼容性

• 面向 DeepSeek Harness web profile。
• 需要 Web 端启用 @deepseek-ai/dsh-client-runtime 与 @deepseek-ai/dsh-client-ui-conversation。
• 宿主机需要 docker CLI 位于 PATH 且能连接 Docker Engine。

- Linux：Docker Engine / rootless Docker / Docker Desktop。 - Windows：Docker Desktop（建议启用 WSL2 backend）。 - macOS：Docker Desktop 或 OrbStack 的 Docker context。

• 端口转发依赖 alpine/socat（官方镜像，首次使用自动 pull）。
• 插件版本：1.0.3。

验证

仓库内置两级测试，必须全部通过：

# 1. 结构 + 语法 + 39 工具/15 路由 + schema + live docker_info + client 沙箱模拟
npm run verify

# 2. 真实 Docker 集成冒烟:创建/并行 exec/生命周期/上传下载/后台任务/
#    端口转发实测回显/快照回滚/共享/策略/网络策略/审计/清理核验
npm run smoke

# 3. 生成 releases 包并校验 tarball 内容
npm run pack

verify 覆盖

• 双半区语法检查。
• Host ESM 导出 apply + inject。
• Mock Cordis 上下文下 39 个工具与 15 个路由注册、effects disposer 清理。
• 与 dsh-plugin-vm-sandbox 对应的 19 组工具 schema 参数逐项比对。
• 真实 docker_info 调用（Docker daemon 不可用时硬失败）。
• Client bundle 在 Node vm 浏览器沙箱中执行，断言 id、apply/inject、slots.inject('conversation.view') 与样式挂载/卸载。

smoke 覆盖（真实 Docker）

1. docker_info 实时探测。 2. docker_create 带 cpus/memory/shm_size 创建容器，docker_status 校验 owner / running / runtime。 3. docker_exec 双容器并行执行。 4. docker_stop / docker_start / docker_restart。 5. docker_upload / docker_download 内容一致性。 6. 后台任务提交、轮询完成、列表、完整日志。 7. alpine/socat echo 容器 + docker_port_forward，宿主机 nc 实测回显，转发停止。 8. docker_snapshot → 修改容器 → docker_restore → 校验快照标记恢复 → docker_snapshot_delete。 9. docker_share 后跨会话 exec、docker_unshare。 10. docker_policy 设置。 11. docker_network_policy 公网关闭 / 内部网络应用 / 恢复。 12. docker_audit 过滤校验。 13. finally 中自动清理全部 dsh-smoke-* 容器、dsh-pf-* 代理、dsh-snap-* 快照镜像，并验证无残留。

目录结构

dsh-plugin-container/
├── package.json                 # 仓库根即插件源包(含 dsh.bundle / dsh.client)
├── scripts/
│   ├── prepare.mjs              # 根包 prepare:构建 dsh-plugin-container/lib
│   ├── verify.mjs               # 严格静态/结构/live 验证
│   ├── smoke.mjs                # 真实 Docker 集成冒烟
│   └── package.mjs              # 生成并校验 releases tgz
├── dsh-plugin-container/
│   ├── package.json             # 内层发布包
│   ├── cordis.patch.yml         # 自动插入「容器」页签的 patch 层
│   ├── src/
│   │   ├── index.js             # Host 侧实现(39 工具 + 15 路由)
│   │   ├── client.js            # 浏览器端原生 UI
│   │   └── types/index.d.ts     # Host 类型声明
│   ├── lib/                     # prepare 生成的发布入口(已提交)
│   └── scripts/prepare.mjs
├── docs/
│   └── ui-preview.html          # UI 静态设计稿(可独立浏览器打开预览)
├── LICENSE
└── README.md

v1.0.0 更新内容（详细）

新增能力（对齐 dsh-plugin-vm-sandbox）

• docker_snapshot / docker_snapshot_list / docker_restore / docker_snapshot_delete

- docker commit --change LABEL 带标签快照镜像；自动保存/恢复 run spec；限额治理。

• docker_upload / docker_download

- docker cp 双向文件传输，工作区路径约束。

• docker_port_forward / docker_port_forward_list / docker_port_forward_stop

- alpine/socat 代理容器端口转发，支持本地端口自动分配与回收。

• docker_job_submit / docker_job_list / docker_job_status / docker_job_stop / docker_job_output

- 容器内 /tmp/.dsh-jobs 后台任务执行器，含状态探测与日志输出。

• docker_audit

- 39 个工具 + 面板操作统一审计包装器，支持过滤查询。

• docker_share / docker_unshare / docker_policy

- 会话间 exec/manage 共享、每会话配额、闲置停止/删除回收。

• docker_network_policy

- 公网 / 内部网络 / 完全隔离 / 仅内部网络四类策略，持久化重放。

• docker_status

- 增强状态：IP、网络、挂载、资源限额与实时用量、uptime、最近 Shell、任务、隧道。

• docker_create

- VM 风格创建工具：自动命名、资源规格、初始化脚本、隔离网络。

• docker_exec 增强

- containers 数组并行执行、timeout_ms、Shell 执行记录。

• docker_run 增强

- cpus/memory/memory_swap/shm_size/pids_limit/disk_quota、isolated/isolate_network、会话归属登记。

UI 重构

• 从旧版简单列表升级为原生级完整控制台：

- 渐变光晕背景 + 玻璃拟态统计卡 + 状态呼吸灯。 - 仅观察 / 干预双模式分段控件。 - 容器 / 快照双视图、搜索、过滤。 - 五页签详情（概览 / 日志 / Shell / 任务 / 端口）。 - 创建容器弹窗、快照备注弹窗、操作 toast、确认式删除。 - 使用 DSH 官方设计令牌，自动主题适配。

工程化重构

• 仓库布局严格对齐官方 dsh-plugin-vm-sandbox（根包 + 内层发布包 + prepare）。
• scripts/verify.mjs 全面重写：39 工具 / 15 路由 / 19 组 schema 比对 / live daemon 探测 / 浏览器沙箱执行。
• 新增 scripts/smoke.mjs：真实 Docker 18 项集成冒烟与清理核验。
• 新增 scripts/package.mjs：npm pack 生成 releases tgz 并校验 tarball 内容。
• 状态持久化升级至 ~/.dsh/container-sandbox/state.json（containers / snapshots / shares / policies / network / jobs / tunnels / audit）。

兼容性与破坏性变更

• 旧的 7 个 /dock-api/* 路由与 18 个 docker_* 工具全部保留，现有用法不受影响。
• 插件登记容器新增 owner / share 权限校验；跨会话未共享时，原可操作行为会被拒绝（更安全，与 VM 沙箱一致）。
• docker_run / docker_create 默认网络由 bridge 改为 dsh-sandbox（自动创建），便于统一网络策略治理；可通过 network 参数覆盖。

v1.0.3 修复内容（详细）

• 修复面板创建容器时 pids_limit 留空被透传为 --pids-limit "" 导致 Docker 报 invalid argument "" 的问题；空值现在与未传值一致，不再生成参数。
• scripts/verify.mjs 新增静态回归断言：buildRunArgs 的 pids-limit 分支必须带非空字符串保护。
• 修复后 /dock-api/create 全参数路径实测通过。

v1.0.2 修复内容（详细）

• 修复 /dock-api/create 路由错误分支的 sessionId 作用域错误：缺少 session 或创建失败时，catch 分支原先会因未定义变量再次抛错，导致 webServer 返回 400 空响应而不是 JSON 500。
• scripts/verify.mjs 新增路由错误路径回归：直接调用 /dock-api/create 缺失 session 的 handler，断言返回 JSON 500 且 handler 不 reject。
• 完整 HTTP 路由实测（15/15）在 v1.0.2 通过。

v1.0.1 修复内容（详细）

• 修复 docker_job_stop 主动停止的后台任务，在随后 docker_job_list / docker_job_status 探针中被错误覆盖为 running 的终态污染问题。
• readJobStatus 现在对 done / error / stopped 三种终态严格保护：终态不会被 docker exec 探针的 running / dead 覆盖，endTime 与退出码同样保持稳定。
• scripts/smoke.mjs 新增回归断言：提交长任务 → docker_job_stop → docker_job_list 必须保持 stopped 且 endTime 非空。

License

This project is licensed under the Apache License 2.0. See the full license at https://www.apache.org/licenses/LICENSE-2.0.