| DSH 版本 | 需要 dsh >= 0.1.2-rc.1（插件清单里声明的引擎要求）；终端执行 dsh --version 查看 |
|---|---|
| 远端主机装 tmux | 插件默认使用持久会话：sudo apt-get install -y tmux；工作组的沙盒机（deepseek / armbian）已预装 |
| 主机写进清单 | 目标主机加到 ~/.dsh/dsh-ssh.json（与 @linxin666/dsh-ssh 共用同一个主机库），或在 dsh-ssh 的 SSH 面板里添加 |
任选其一：图形界面走社区市场；脚本化 / 服务器走 dsh plugin；内网离线走手工安装。三者最终都落在同一个 profile 上。
| 方式 | 适用 | 入口 |
|---|---|---|
| 一 · 社区市场 | DSH Desktop 图形界面 | 添加目录源 → 列表里一键安装（推荐） |
| 二 · 命令行 | 脚本化、远程机器 | dsh plugin --profile <profile> add … |
| 三 · 手工安装 | 内网、离线、需指定 pnpm 版本 | 在 profile 目录内用 pnpm 加包，再补挂载清单 |
latestVersion 已指向 0.1.1。sb_cwd / sb_session / sb_exec / sb_ls / sb_read / sb_write。dsh plugin）dsh plugin --profile desktop add @hakehuang/dsh-ubuntu-sandbox@0.1.1
dsh plugin 做的事只是把参数转发给 profile 目录里的 pnpm：它只装依赖，不写挂载清单。
装完必须确认 ~/.dsh/profiles/<profile>/package.json 的 dsh.profile.bundles 数组里有
"@hakehuang/dsh-ubuntu-sandbox"；缺了不会报错，只是工具永远不出现。
# 检查挂载清单里有没有这一行 node -e "const p=require(process.env.USERPROFILE+'/.dsh/profiles/desktop/package.json');console.log(p.dsh.profile.bundles)" # 或直接看合成后的插件树（出现 id: ubuntu-sandbox 即已挂载） dsh --profile desktop --dump-config | Select-String ubuntu-sandbox
node_modules/.modules.yaml 里的 packageManager 与 storeDir，用同一个大版本的 pnpm 来装，避免 store 版本不匹配（见 常见报错）。pnpm add --save-exact @hakehuang/dsh-ubuntu-sandbox@0.1.1package.json：dependencies 与 dsh.profile.bundles 各加一条。# 更新到指定版本（推荐显式写版本号，便于回滚与复现） dsh plugin --profile desktop add @hakehuang/dsh-ubuntu-sandbox@0.1.1 # 更新到最新版 dsh plugin --profile desktop add @hakehuang/dsh-ubuntu-sandbox@latest # 确认当前落地版本 node -p "require(process.env.USERPROFILE+'/.dsh/profiles/desktop/node_modules/@hakehuang/dsh-ubuntu-sandbox/package.json').version" # 看看 npm 上有哪些版本 npm view @hakehuang/dsh-ubuntu-sandbox versions # 卸载 dsh plugin --profile desktop remove @hakehuang/dsh-ubuntu-sandbox # 再从 package.json 的 dsh.profile.bundles 里删掉包名，然后重启 DSH
| 0.1.1 · 当前 | 修复安装阻断：0.1.0 声明 schemastery ^3.18.2，而公共 npm 源最新只有 3.18.0，导致 npm / pnpm install 与社区市场安装都以 notarget 失败。现已改为 ^3.18.0。功能行为与 0.1.0 一致。 |
|---|---|
| 0.1.0 · 已废弃 | 首个发布：sb_cwd / sb_session / sb_exec / sb_ls / sb_read / sb_write 六个工具，默认 tmux 持久会话。存在上述安装阻断，请勿使用（npm 上已标记 deprecated 并指向 ≥0.1.1）。 |
package.json 与 pnpm-lock.yaml。
node_modules/@hakehuang/dsh-ubuntu-sandbox/package.json 版本号应为 0.1.1，目录内有 lib/*.js 与 cordis.patch.yml。dsh --profile desktop --dump-config 的输出里应出现 - id: ubuntu-sandbox 与 name: '@hakehuang/dsh-ubuntu-sandbox'。sb_cwd alias:<主机别名>，再 sb_exec "uname -a; tmux -V"；sb_session action:status 应显示 mode: on (default)。下面几条是安装/更新时最常遇到的，按现象对号入座即可。
| ERR_PNPM_UNEXPECTED_STORE |
原因：profile 的 node_modules 由 pnpm 10 建立（链接自 store\v10），而 DSH 对每一次包管理操作都强制使用它自带的 pnpm 11（要 store\v11），于是拒绝在旧 store 上继续。处置 A（一次性根治，推荐）：完全退出 DSH Desktop 后，在 profile 目录里执行 & "$env:APPDATA\DSH Desktop\runtime-commands\bin\pnpm.cmd" install，把整棵树迁到 v11 store；之后 GUI、市场与 dsh plugin 都恢复正常。必须在关闭状态下做：运行中的进程会锁定原生模块。处置 B（不动现有树）：用与现有 store 匹配的 pnpm（先看 .modules.yaml 的 packageManager）手工安装，再把包名补进 dsh.profile.bundles。
|
|---|---|
| notarget / No matching version | 装的是 0.1.0：它要求的 schemastery ^3.18.2 在公共源并不存在。改装 0.1.1 或更高。 |
| 装完了但工具不出现 | 两件事各查一遍：dsh.profile.bundles 是否含该包名；是否已重启 DSH（新 bundle 不热加载）。 |
| 插件被忽略、完全不挂载 | 包内 cordis.patch.yml 的行名必须等于包名 @hakehuang/dsh-ubuntu-sandbox——loader 是按包名解析这一行的。自己改包名后务必同步这个文件。 |
| sb_* 报 tmux 相关错误 | 远端缺 tmux：sudo apt-get install -y tmux；也可在 sb_session 里关闭会话模式（不推荐，会失去 cd / export 的跨调用保持）。 |
| 长任务被超时打断 | 非会话模式下命令超时会被直接杀掉。开启会话（sb_session action:on）后超时不再杀进程，用 sb_session action:reset 可恢复一个干净 shell。 |
| Windows 上 git 凭据 / HTTPS 检查异常 | DSH 的文件沙箱会限制子进程与证书栈：需要 git 凭据的操作要放宽沙箱权限；校验 HTTPS 请用 Node 的 fetch，不要用 curl（Windows Schannel 在沙箱内会失败）。 |