隔离沙箱管理器33moren33/dsh-box

DSH 沙箱

选一个官方版本，开一台隔离的 dsh每个按钮背后，都是一条你也能敲的命令Agent 自己驾驶时，窗口如实显示它走的每一步随时一键收回控制权，窗口关掉再打开，什么都不丢

快速开始
·
Agent 怎么用
·
命令
·
沙箱是什么

= 20" />

Fable 5 辅助

0.5.3：起沙箱不再闪黑窗，回执给的地址拿来就能打开。

以前每起一台沙箱，屏幕上会有个黑框占掉两秒。那个框不是本程序开的：dsh 自己去开默认浏览器，做法是另起一个小程序来交接网址，而它在 Windows 上会拿到一个自己的控制台窗——那是别人的孙进程，我们没法给它加「不要窗口」的开关。所以改成把这件事接过来：告诉 dsh 别开，由本程序自己开。浏览器照常弹出来，只是不再带那两秒黑框。

⚠️ 只在认得这个开关的 dsh 上才告诉它别开，而认不认是问它本人、不是看版本号——老版本既不认这个开关，本来也不会自己开浏览器。

新版 dsh 的页面要带一把钥匙才进得去，而以前印出来的是不带钥匙的半个地址：点开落在「需要认证」上，看起来像服务坏了。现在 start 和 ls 给的都是完整地址。⛔ 半个地址比没有地址更坏——它把人指向完全错误的方向。

⚠️ 中间两个小版本没有单独的段落：0.5.1 修好了绿色版和安装版上「mcp 敲下去三百毫秒就退、退出码 0、零输出」；0.5.2 修好了 get signin 之后沙箱起不来（凭证改按能装下内容的最老那种版式写）。

0.5.0：Agent 那张脸——dsh-box mcp，以及每个答案都带判词。

同一张命令表长出第三张脸：dsh-box mcp 起一个 MCP 服务，每条命令就是一个同名工具，Agent 不必读任何文档就知道有什么、参数是什么。工具调用的背后仍是那条你也能敲的命令行。

每一行 JSON 从此带 verdict：ok 答出来了 ／ failed 关于你问的那台的判定 ／ error 请求或本工具的问题 ／ partial 做了一半。退出码 0／1／2／3 只是它的投影。ls 的机器答案改成总览：每台沙箱一行、插件只给数目，要细节再往下问。

⛔ 旧版 agent attach / detach 已删：接管不必声明，会改状态的命令自己登记，窗口照样如实显示。

0.4.0：命令收成十个动词，--version 也收文件夹。

45 条命令收成十个：ls、get、rm、start、stop、set、logs、ui、agent、help，对象做成参数。⛔ 旧名一个都不留。

同时多认两种 dsh：你自己从源码构建的，和某个应用自带的。--version 里带斜杠就按文件夹读，不带就还是版本号——一根轴，一个旗标。钉版核对照实报一句，但不拦着：那棵树不是我们装的。

⛔ 0.3.5 的窗口在 Windows 上一次都打不开，这一版修了。

0.3.3：npm 上的插件，装得上，也起得来了。

npm 上的第三方插件多数不随包带官方依赖——它们指望在运行的那台 dsh 身上现拿零件。以前从 dsh-box 装这类包，dsh 会因为找不到零件拒载整棵插件树。这一版从根上解决：下载一次，每个 dsh 版本各配一套对版的零件货架（硬链接，不占多余磁盘），沙箱换哪个版本启动都自动对版；装进日常档案柜则是整份拷进去——之后你自己敲 dsh 一样加载，把 dsh-box 删掉也毫发无损。

窗口也跟上了：插件可以直接从 npm 按包名装，下载进度实时可见，插件行显示版本号。照旧，每个按钮背后都是一条你也能敲的命令。

快速开始

npx dsh-box ui        # 界面开在浏览器里，不用安装

注意你在哪个目录敲的这条命令——数据就建在那个目录下的 dsh-box-files/data。今天在 D 盘敲、明天在 E 盘敲，会得到两个互相看不见的数据目录，沙箱像是"丢了"，其实在另一个文件夹里。想固定住，见数据目录。

想要双击打开的原生小窗，去 Releases 下安装包。 两条路是同一个程序的两张皮——同一个本地服务、同一张页面。

⭐ 0.3.5 起，那个 exe 自己也是命令行：双击是窗口，带参数就是命令行。

dsh-box.exe ls --json         # 安装版 / 便携包，带参数即命令行
dsh-box.exe set path on       # 把它所在的目录加进你自己的 PATH
dsh-box                       # 进了 PATH 之后，任何目录直接敲

⛔ 0.3.4 及更早的 exe 没有这张脸：带参数会挂住不返回，文件名也还是 dsh-box-shell.exe。0.3.5 起统一叫 dsh-box.exe。安装版装完会自动替你敲一次 set path on；便携包自己敲一次。npm 全局装的那份用不着——npm 已经把垫片放在它的全局目录里了。

配置窗打开后是三步：选一台 dsh → 选一个档案柜 → 起。不选版本就用你自己装的那台 dsh；选了下载的版本，第一次会下（约 200–260MB），之后复用。

agent 正在驾驶时的配置窗

不想用界面就直接给命令，每一步都能单独跑：

npx dsh-box ls machine                                # 能用哪些 dsh：本机装的、已下载的、你指过的文件夹
npx dsh-box get machine 0.1.1-rc.2                    # 下载一个官方版本
npx dsh-box get plugin dsh-memory-pyramid --to 试验台   # 从 npm 装一个插件进沙箱
npx dsh-box start --new --plugin ./my-plugin          # 开一台新沙箱，把本地插件装进去
npx dsh-box start --new --version D:\dsh-build        # 用你自己构建的那份 dsh 起
npx dsh-box ls --json                                 # 任何命令加 --json，给脚本和 Agent 用

从源码跑就是 node bin/cli.js ui。

Agent 怎么用

命令行本来就是给 Agent 准备的：有 --help，任何命令加 --json 就以 JSON 回话，失败也是 JSON，且带一个不会变的 code。所以这里不做常驻 HTTP API。

MCP 是同一张命令表的另一张脸，不是另写一套。 挂进 Claude Code 之类的客户端只要一行：

{"mcpServers":{"dsh-box":{"command":"npx","args":["dsh-box","mcp","--box",""]}}}

之后每条命令就是一个同名工具（ls_sandbox、get_plugin、start、stop），参数就是旗标去掉 --；每次调用的背后仍是那条命令行，答案就是那一行 JSON。⛔ 不在工具表里的只有不返回的那两样：ui（开着就一直服务）和 mcp 自己。

每一行 JSON 都带判词 verdict，退出码只是它的投影：

| verdict | 退出码 | 意思 |
|---|---|---|
| ok | 0 | 答出来了 |
| failed | 1 | 关于你问的那台的判定：沙箱不在、dsh 没起来、闸门拒了。请求没错，是世界说了不 |
| error | 2 | 请求或本工具的问题：不认识的命令、别的命令的旗标、工具崩了 |
| partial | 3 | 做了一半再被拒，答案里写着做了哪一半 |

MCP 里只有 error 会标成工具出错；failed 和 partial 是答案，不是故障。

接管不必声明。 会改状态的命令自己登记，配置窗看得见谁在动：顶上一条蓝带，页面里每个被动到的控件挂上编号，下面就地展开一份命令轨迹——每一步都渲染成你可以照着重跑的那行命令。做完了、被拒了、拒的理由是什么，都在上面。

npx dsh-box ls memory       # 上次接管期间做了什么（含被拒绝的）
npx dsh-box ls history      # 这个数据目录里做过的所有事

锁在服务端，不在页面上。 Agent 的命令在跑的那几秒里，窗口发出的一切命令由服务端直接拒绝；命令一结束锁自动解开，没有「收回」这一步——没有什么被占着。页面上的置灰因此退化成纯装饰：标错一个控件，最坏是它看起来能点、点了给句说明，再也变不成损害。

判据一句话：窗口关掉再打开，不丢任何东西。

先记两个词

| 词 | 是什么 |
|---|---|
| 档案柜 | 一个 DSH_HOME。装对话、配置、登录。start  里那个名字说的就是它，日常那台叫 main |
| 工作区 | dsh 干活的那个项目文件夹。这是 dsh 官方的叫法 |

一次启动 ＝ 两根轴

start  =  用哪台 dsh（机器）  ×  开哪个档案柜（DSH_HOME）

- 机器：不写就是你自己装的那台 dsh；--version  改用 dsh-box 下载的那份；--version  改用你指的那一份——自己从源码构建的，或某个自带 dsh 的应用。带斜杠就按文件夹读，版本号里不会有斜杠。
- 档案柜：写沙箱名开那一台 ／ --new 开一台新的 ／ 写 main 开你日常的 ~/.dsh。

什么都不沿用上次。 版本、沙箱、工作区三处继承全部去掉了：同一条命令永远得到同一个结果，这比少敲几个字重要。

闸门只拦一件事：拿不是你自己装的那台 dsh（下载的，或你指的文件夹）去开你真实的 ~/.dsh。这一格当场拒绝，并把配置窗自己弹出来等人点；人点了之后，由那扇窗把这条命令跑掉。⛔ 没有旗标能绕开它。其余一律不弹窗——可撤销的动作弹窗，只会训练人点掉真正重要的那一个。

插件是档案柜的属性

不是「这次启动的选项」。插件装进哪个档案柜，就写进那个档案柜自己的配置，你自己敲 dsh 一样加载。

- --plugin  是加，--unplug  是减，不写就是什么都不改。
- 想要一台纯官方的 dsh，就新建一个沙箱。
- 本地文件夹和 npm 上的包都能装。本地的是链过去的，改完源码下次启动就生效。
- npm 的包只下载一次，所有沙箱、所有 dsh 版本共用；每次启动自动对准这次用的那个版本的官方零件。
- 装进日常档案柜是整份拷进去的——之后不经过 dsh-box、自己敲 dsh 也加载，删掉 dsh-box 它还在。
- 每次改动前先备份，set plugin --undo 退回上一步；卸载要逐字节回到原样，不是肉眼对，是 hash 对。

命令

ls    [对象]                    看。不给对象就是此刻的全景
get    [--from/--to]      拿进来：machine（下版本）· plugin · signin · chat
rm                        拿走：machine · plugin · sandbox · signin · setting
start  | --new          起一台。可带 --version · --plugin · --unplug
stop   | --all | --window | --download
set                     plugin · workspace · source · lang · path · 两个提醒
logs   | --version  | --package
ui                              打开配置窗（关它是 stop --window）
mcp                             起一个 MCP 服务，每条命令就是一个同名工具
help                            细则分三层，越问越细

细则看 help （例如 help start）。机器可读的一份是 --help --json，给出的就是驱动这个命令行的那张表。

语言

中英文都内置，随时切。语言是这个数据目录的设置，不是页面的偏好：

npx dsh-box set lang en

命令行与配置窗一起变。窗口右上角那个开关背后跑的就是这条命令——所以窗口仍然没有多出任何能力。没设过就跟这台电脑的系统语言走。

数据目录

下载的版本、所有沙箱、插件包、过程日志，全在一个叫 data 的文件夹里。数据跟着程序走，浏览器里不存任何东西——配置窗只是视图，清掉浏览器缓存和 cookie 什么都不丢：

- npx 或从源码跑，它建在你当前所在的目录下，dsh-box-files/data。
- 装了桌面版、或解压了便携包，它就在 exe 旁边的 dsh-box-files/ 里。那个文件夹只装两样：boot 是程序，data 是你的家当。覆盖解压就是升级——boot 换新，data 一个字不动。只有当 exe 待在写不进去的地方（比如 Program Files），数据才退到你的用户目录。

用 npx 的人建议把位置固定下来，二选一：每次在同一个目录里敲；或设一次环境变量 DSH_BOX_HOME=（单次命令用 --box  也行），之后在哪儿敲都是同一份数据。找不到自己的沙箱时，先看任何命令输出的第一个字段——那就是它正在用的数据目录。

如果指定的位置已经有个同名文件夹、里面有东西、又不是本工具建的，工具会另起一个名字，不会写进别人的目录。

需要什么

Node 20 或更新，仅此而已。

dsh 通过 npm 分发，启动文件是个 Node 脚本，所以没有 Node 就跑不了 dsh。除此之外什么都不需要，工具本身没有任何运行时依赖。

它不 import 任何 @deepseek-ai 包。 官方改插件接口与它无关，全程在 dsh 进程外面：建目录、写配置文件、设 DSH_HOME、启动官方的 dsh。

Windows：有几段 Node 处理不了带中文的路径

Node 自己的缺陷，不是本工具的（#61067、#61878）。递归删除和递归拷贝，只要路径里有中文、日文、重音字母或 emoji，就回报成功、什么都没做，有时直接让进程崩掉。本工具已经绕开，在下面每一段版本上都正常。

| 正常 | 有缺陷 |
|---|---|
| 20.x、21.x | 22.17 – 22.21（现行 LTS，至今未修） |
| 22.0 – 22.16 | 23.x 全线 |
| 24.15 或更新 | 24.0 – 24.14 |
| 25.9 或更新、26.x | 25.0 – 25.8 |

每一格都是下载那一版真跑出来的。只在 Windows 上，Linux 与 macOS 不受影响。

写在这里，是因为你机器上别的 Node 程序不一定绕开了。用户名是「张三」或 José 的人，路径里到处都是这类字符。要一个干净的，装 24.15 或更新。

沙箱是什么

一个沙箱就是一个 DSH_HOME —— 一台 dsh 的整个档案柜：装了哪些插件、配置、工作区名册，以及所有对话记录。给它一个新的档案柜就等于一台全新的 dsh；把文件夹删掉，那台 dsh 就不复存在，没有「卸载」这个步骤。

「沙箱」不是安全隔离。 它只隔 DSH_HOME，权限和你平时那台一模一样——能读写你的文件，花你真实的钱。隔开的是版本、插件、配置和对话，不是这台电脑。

三件要知道的事：

对话记录属于它发生的那个档案柜。 两个沙箱打开同一个项目文件夹，看到的历史也不同。

沙箱用的是你真实的登录。 导入默认打开，省得每个沙箱都重配一遍 API Key；沙箱里的对话是真实请求，真实计费。

沙箱里的对话能拿回来。 get chat --from  --to  把对话从一个档案柜复制进另一个，按 session 幂等，重复执行不会多出来。

网络

下载版本要连 npm 官方仓库。工具不替你决定走不走代理：开始下载前先直连试一次，通就走直连，不通就走你系统里已配置的代理，并把选了哪条写进日志。绕开代理只对 npm 仓库这一个域名生效，其它请求照旧。

桌面壳

npx tauri build

产出双击即用的小窗与 NSIS 安装包。壳是 Rust 写的，只做四件事：找系统 Node、挑一个空闲端口、拉起上面那个同样的 Node 服务、关窗时收割整棵进程树。页面和逻辑与浏览器里那份是同一份。
构建需要 Rust 工具链。macOS 与 Linux 的产物必须在对应系统上产出，无法从 Windows 交叉构建。两个平台的未签名程序都会被拦一次：Windows 点更多信息 → 仍要运行，macOS 是 Gatekeeper。

常见问题

License

MIT