@wavexzore/sandbox

基于本地 Docker 的 OpenCode 编码沙箱插件。

功能概述

• 通过 @opencode-ai/plugin 注册 OpenCode 插件钩子
• 用 Docker 后端实现替换 14 个核心工具：bash、bash-stop、bash-output、bash-status、read、write、edit、multiedit、apply_patch、glob、grep、ls、lsp、get-preview-url
• 通过 dockerode 为每个 OpenCode 会话创建独立的 Docker 容器
• 将宿主机工作目录 bind mount 到容器内
• 在容器内执行 Shell 命令，在宿主机保留 LSP 诊断能力
• OpenCode 会话删除时自动清理容器

架构概览

插件层               custom-tools · session-events · system-transform
                           │
工具层               14 个沙箱工具 (bash/read/write/edit/patch/glob/grep/ls/lsp/...)
                           │
核心层               session-manager ──► docker-sandbox (Sandbox 接口)
                     shell/ · write/ · read/ · edit/ · lsp/
                     path-map (宿主机↔容器) · project-data-storage
                           │
基础设施层           dockerode · tar-stream · diff · vscode-jsonrpc
                     Docker Engine ──► bind mount (宿主机 worktree ↔ 容器 /repo)

关键设计要点：

• 写入管线：权限检查 → BOM 处理 → 文件上传 → 格式化 → LSP 诊断，完整链路一条龙
• 先读后写守卫：文件必须先被读取后才能写入（由 readRegistry 强制执行）
• 9 策略编辑回退：精确匹配 → 行首匹配 → 块锚点 → 空白忽略 → 缩进忽略 → 转义处理等
• LSP 懒加载：语言服务器仅在首次访问文件时启动
• 双轨 Git：容器端通过 docker exec 执行 git 命令，宿主机端通过 child_process 执行

安装

在 $HOME 目录下运行安装命令（默认 user scope）：

npx @wavexzore/sandbox install

安装器会自动完成：将插件写入 OpenCode 全局配置、创建版本化存储目录、生成 bin shim 并设置 PATH。

其他命令：

npx @wavexzore/sandbox install --dry-run --json   # 预览安装内容
npx @wavexzore/sandbox doctor --json               # 诊断安装状态
npx @wavexzore/sandbox uninstall                   # 卸载

运行要求

• 本地运行的 Docker 守护进程
• 沙箱镜像，默认为 opencode-sandbox:latest
• Node.js（安装器/helper 需要）

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | SANDBOX_IMAGE | opencode-sandbox:latest | 沙箱容器使用的 Docker 镜像 | | DOCKER_SOCKET | /var/run/docker.sock | Docker 守护进程 socket 路径 |

项目级配置（.opencode/sandbox.json）

{
  "image": "opencode-sandbox:latest",
  "shell": {
    "defaultTimeoutMs": 120000,
    "maxOutputBytes": 200000,
    "maxOutputLines": 2000,
    "allowWorkdirOutsideProject": false
  },
  "lsp": {
    "enabled": true
  }
}

沙箱镜像

docker build -t opencode-sandbox:latest -f packages/sandbox/Dockerfile packages/sandbox

默认容器项目路径为 /home/sandbox/project。

宿主机 LSP

工作目录通过 bind mount 挂载，因此映射文件在宿主机和容器中均可访问。插件在宿主机上运行 LSP 服务器，提供诊断和代码导航：

• TypeScript/JavaScript：typescript-language-server
• Go：gopls
• Python：python-lsp-server

这些是用于编辑中项目的工具，不是产品运行时模块。

工具参考

| 工具 | 说明 | 执行位置 | |------|------|----------| | bash | 执行 Shell 命令（前台/后台模式） | 容器 | | bash-stop | 停止后台命令 | 容器 | | bash-output | 读取后台命令输出 | 容器 | | bash-status | 查询后台命令状态 | 容器 | | read | 读取文件或目录（含二进制检测） | 容器 | | write | 覆写文件（diff + 格式化 + 诊断） | 容器 | | edit | 文本替换编辑（9 策略回退匹配） | 容器 | | multiedit | 对单个文件原子应用多个编辑 | 容器 | | patch | 应用统一补丁（add/delete/update/move） | 容器 | | glob | 按 glob 模式搜索文件 | 容器 | | grep | 按文本模式搜索文件内容 | 容器 | | ls | 列出目录内容 | 容器 | | lsp | 语言服务操作（hover/定义/引用/诊断等 14 种操作） | 宿主机 | | get-preview-url | 获取沙箱端口的预览 URL | 容器 |

包目录结构

src/
├── index.ts                # 包入口（re-export）
└── sandbox/
    ├── index.ts            # 插件入口 (sandboxPlugin)
    ├── tools.ts            # 工具工厂注册中心
    ├── cli/                # CLI: install/uninstall/doctor/setup-path/help
    ├── core/               # 核心层
    │   ├── docker-sandbox.ts      # Sandbox 接口实现
    │   ├── session-manager.ts     # 会话生命周期管理
    │   ├── shell/                 # Shell 执行子系统
    │   ├── write/                 # 写入管线子系统
    │   ├── read/                  # 读取子系统
    │   ├── edit/                  # 编辑子系统（9 策略回退）
    │   └── lsp/                   # LSP 客户端池 + 诊断
    ├── tools/              # 14 个工具实现
    ├── git/                # 双轨 Git（容器 + 宿主机）
    └── plugins/            # OpenCode 钩子（工具、事件、系统提示）
dist/                       # 生成的 ESM（npm pack 目标）

开发

npm --workspace @wavexzore/sandbox run typecheck
npm --workspace @wavexzore/sandbox run lint
npm --workspace @wavexzore/sandbox test
npm --workspace @wavexzore/sandbox run build
npm --workspace @wavexzore/sandbox run verify