多版本管理器 dsh-so/dshvm

dshvm

DeepSeek Harness CLI（dsh）多版本管理器 —— 装任意版本，一条命令切换，按版本隔离数据。

版本可以来自 npm、GitHub（发布包或源码）或本地 checkout；切换只改一个指针，不必重新下载；跨平台、零运行时依赖，只要 Node ≥ 18。不想敲命令的话，同仓库自带桌面启动器 dshvm-ui。

= 18">

简体中文 · English

dshvm 把 dsh 的版本与数据拆开来管：每个版本装进自己的槽位 ~/.dsh-versions/dsh-<id>/，全局 dsh 只是一层极薄的连接器 —— 读指针，转发给激活版本的 bin；数据默认共享一个 $DSH_HOME，需要时用 isolate 切成每版本一份。不 fork、不改上游行为：装哪个版本，跑的就是哪个版本的原样代码。

社区项目 —— 与 DeepSeek 官方无隶属关系。"dsh" 是社区对 @deepseek-ai/dsh CLI 的称呼。

安装

| 渠道 | 命令 | 说明 |
| npm（推荐） | npm install -g @dsh-so/dshvm | 发布版，零运行时依赖 |
| 本地 checkout | npm install -g --force <path> | 发布前从源码自测；--force 用于覆盖同名全局包 |

npm install -g @dsh-so/dshvm
dshvm setup

setup 会收编你现有的全局 dsh、安装 dshvm 连接器，并把激活版本指向它。此后 dsh 由 dshvm 接管，随时可以 dshvm use 切到别的版本。

图形界面（dshvm-ui）

本节整节都是图形界面用法；只用命令行的话，可跳过本节直接看快速上手，之后的「命令」等章节也都只涉及 CLI。

不想敲命令时，用同仓库的桌面启动器 dshvm-ui（Tauri 2 + React）：列出 / 切换 / 安装 / 隔离版本，一键拉起任意版本的 dsh web，并管理正在运行的实例 —— 启动失败会给出原因并留下日志，不会「点了没反应」。界面五区排布：顶栏 → 状态条（当前默认、启动按钮、中英切换、⚙ 设置）→ 版本区（已安装 / 可安装）→ 运行中面板 → 底栏状态。状态由 UI 直读 ~/.dsh-versions（DSHVM_HOME 可覆盖），所有变更操作一律转给 dshvm CLI —— 界面和命令行看到的永远是同一份事实。

获取与首次启动

| 渠道 | 内容 |
| NSIS 安装器 | dshvm-ui__x64-setup.exe；机器上已有 Node/npm 时自动执行 npm install -g @dsh-so/dshvm + dshvm setup |
| MSI | 纯应用安装（不含上述自动化） |
| 源码构建 | 需 Tauri 2 + Rust 工具链 + WebView2，见 ui/README.md |

安装包随 GitHub Releases 发布；某个 Release 还没附二进制时，按 ui/README.md 从源码构建。

打开后若检测到 dshvm 未安装，会先进引导页而非主界面，按提示补环境即可：

- 引导页列出 Node.js / npm / dshvm 三项检测结果；缺 Node.js 时可一键下载并运行 Node 官方 LTS 安装器（装完点「重新检测」，必要时重启应用）；
- Node/npm 就绪后点「一键安装 dshvm」：等于执行 npm install -g @dsh-so/dshvm + dshvm setup，npm 输出实时滚动在页面上；
- 用 NSIS 安装器装的应用，在已有 Node 的机器上已自动做完这一步，打开即是主界面。

安装新版本

入口：「已安装」页底部的 ＋ 安装新版本，或「可安装」页每行的 安装。

- 「可安装」列表合并 npm registry（走你自己的 npm，跟随你的镜像/代理配置）与 DSH GitHub tags（git ls-remote，无 token、无速率限制），结果本地缓存 1 小时，↻ 刷新强制拉最新。首行 ★ 推荐版本 即 npm 的 latest；alpha/beta 默认折叠在「更多」里，勾选「显示 alpha/beta 预发布版」展开（rc 直接可见）。
- 安装对话框接受裸版本号 / npm:x / github:owner/repo#ref / 本地路径，并附三个快捷标签（npm latest / npm 指定版本 / GitHub tag）。过程分阶段显示（解析版本 → npm 下载安装 → 注册版本…）并计时；npm 警告折叠计数；失败时给出退出码、日志末尾原文与「复制日志」，安装中随时可取消。
- 安装从不改动当前默认版本，装完需要 ⋯ → 设为默认 切过去。

管理已安装版本

「已安装」页每个版本一行：●/○ 标出默认，来源徽章（store / npm-global / gh-source / local），以及 默认、🔒隔离、副本（隔离数据拷贝自共享目录）标记。行内 ⋯ 菜单：

| 操作 | 行为 |
| 设为默认 | 等于 dshvm use <id>，全局 dsh 立即改指 |
| 隔离（空白环境） | dshvm isolate <id>：给该版本一个独立的空 $DSH_HOME |
| 隔离（拷贝现有数据） | dshvm isolate --copy：把共享 ~/.dsh 复制一份过去，行内多一枚「副本」标 |
| 取消隔离 | dshvm unisolate <id>：回到共享数据 |
| 移除… | 弹确认框：删除代码槽 + 注册信息 + 隔离数据目录，不可撤销；若移除的是默认版本，额外警告「默认会被清空，重新指定前 dsh 无法运行」 |
| 复制 bin 路径 | 该版本 bin.js 的绝对路径进剪贴板 |

两个指针不一致时（active.txt 与 current-bin.txt 指向不同），底栏会提示「激活指针不一致」。

启动 dsh web 与实例管理

每行的「启动」按钮，或状态条的「启动」（启动当前默认版本）。启动在后台做的事：从 3080 起找成对空闲的端口（dsh 同时占 127.0.0.1:N 和 0.0.0.0:N+1）→ 先建日志 ~/.dsh-versions/logs/<版本>-<UTC时间戳>.log（每版本保留 10 份），之后任何失败（版本未知 / bin 损坏 / 端口耗尽）都会把原因写进去 → 启动 node <bin> web --port N --no-open，隔离版本注入自己的 DSH_HOME → 等待就绪（最多 15 秒）→ 捕获 dsh 打印的 http://127.0.0.1:N/?token=… 并用它打开浏览器。登录 token 只在启动时打印一次，由 UI 代管。

运行中的实例列在下方「运行中」面板，每行 日志 / 打开 / ■ 停止：

- 本应用启动的实例能力齐全；手动启动（外部）实例也能看到（扫描 netstat 与 node 命令行发现）、可以停止，但「打开」给不了 token——直接打开只会 401，请用它自己终端里打印的带 token 地址；
- 面板列表每 3 秒刷新；外部实例启动时立即扫一次、之后每 60 秒扫一次；进程一停，对应行自动消失；点「停止」该行立即移除，不等扫描。

启动失败不静默：「启动状态」区为每次未成功的启动保留一行 —— 启动中… / 启动失败 / 已拦下，带原因（悬停看全文）、日志（失败的启动必有一份）、重试；底栏同步显示完整错误详情。

共用数据目录守卫：要启动的版本没有隔离、而另一个未隔离实例正在运行时，先拦下并弹确认框 —— dsh 目前只有进程内单写者，共享 ~/.dsh 的第二个实例打不开活动会话（SessionAlreadyOwnedError）。可选「仍然启动」，或「隔离并启动」（先给该版本独立空目录再启动；之后 ⋯ → 取消隔离 可还原）。

设置

右上角 ⚙：退出时停止所有 web 实例（默认关闭，实例不随应用退出而停；存于 ~/.dsh-versions/ui-settings.json）和检查更新。应用启动几秒后会静默检查一次新版本（无更新、离线都不打扰），发现新版会弹窗展示版本号与更新说明，下载带进度，完成后自动重启完成安装——更新包经签名校验，以 GitHub Releases 的 latest.json 为更新源。

开发构建、架构与排障见 ui/README.md。

快速上手

dshvm install 0.1.2-rc.1 # 安装一个版本 dshvm use 0.1.2-rc.1 # 切到它 dshvm list # 查看版本（ = 当前激活）
dsh --version # 运行激活版本

⚠ 会话格式里程碑：请勿跳版本升级

dsh 在下列版本变更了会话格式，新版 dsh 首次运行时会自动迁移 ~/.dsh 里的数据：

| 里程碑版本 | 会话格式 |
| 0.1.3-alpha.1 | v2 |
| 0.1.5-alpha.1 | v3 |
直接跳过某个里程碑版本升级（如 0.1.2 → 0.1.5-alpha.1），新 dsh 读不到中间格式、可能把旧会话数据破坏且无法恢复。请逐版本升级：先安装并切到 0.1.3-alpha.1、运行一次 dsh 完成迁移，再继续往上升。

dshvm 会在关键节点拦截这类升级：dshvm install / dshvm use 命中时会打印醒目的双语警告；dshvm-ui 的「设为默认」则会弹出确认框，列出被跳过的节点和迁移步骤。

功能特性

- 一条命令切换 — dshvm use <version> 重定向全局 dsh；免重复下载，离线可用。
- 会话格式守护 — 跨越 dsh 会话格式变更节点（0.1.3-alpha.1→v2、0.1.5-alpha.1→v3）的升级会被提醒，避免跳版本迁移破坏旧会话。
- 源码预发布版 — 不在 npm 上的版本（如 0.1.3-alpha.1）会从 DSH GitHub 仓库自动构建。
- 按版本数据隔离 — dshvm isolate 给某个版本独立的 $DSH_HOME（会话、插件、配置）。
- 多种安装来源 — npm、GitHub（发布包或源码）、本地 checkout。
- 桌面启动器 — 同仓库的 dshvm-ui（Tauri 2 + React）：列表 / 切换 / 安装 / 隔离、一键拉起 dsh web、管理运行中的实例。
- 跨平台、零运行时依赖 — 仅需 Node >= 18。

环境要求

- Node.js ≥ 18 —— 装 dshvm 要它，跑 dsh 也要它。
- npm —— 安装 dshvm、以及从 npm 装 dsh 版本时使用。
- tar —— 解压 GitHub 源码包时使用。
- git —— 仅当某个构建需要读取 git 元数据时使用。

命令

| 命令 | 作用 |
| dshvm list | 列出已注册版本。 |
| dshvm use <version> | 切换全局 dsh（支持前缀匹配）。 |
| dshvm install | 安装版本 —— 见「安装来源」。 |
| dshvm register <version> <path> | 按现状登记包根或 bin（不构建）。 |
| dshvm unregister <version> | 删除注册表条目（激活项需 --force）。 |
| dshvm remove <version> | 删除槽位 + 注册表条目（含隔离数据）。 |
| dshvm isolate <version> [--copy] | 给版本建全新独立 ~/.dsh；--copy 从共享播种。 |
| dshvm unisolate <version> | 去掉隔离副本，回到共享 ~/.dsh。 |
| dshvm exec [args] | 启动激活的 dsh（连接器用）；自动适配 web 端口。 |
| dshvm setup / repair / doctor | 首次设置 / 自愈连接器 / 体检。 |
| dshvm current / which [v] | 查看激活版本 / 某版本 bin 路径。 |

安装来源

dshvm install 安装一个 dsh 版本：

| 来源 | 示例 |
| npm 注册表（@deepseek-ai/dsh） | dshvm install 0.1.2-rc.1 · npm:alpha |
| GitHub 仓库，自动 | dshvm install github:deepseek-ai/deepseek-harness · .../#dsh-v0.1.3-alpha.1 · 任意 https://github.com/... |
| GitHub 发布资产 | gh-release:<o/r>[@tag][#asset] |
| 强制源码 | gh:<o/r>[@ref][#subpath] |
| 本地源码 / tarball | dshvm install E:\src\deepseek-harness · ./pkg.tgz |

自动回退 —— 裸版本号 dshvm install <version> 会自动重试：若 <version> 不在 npm 上，就从 github:deepseek-ai/deepseek-harness#dsh-v<version> 源码构建（CLI 包用 #apps/cli 钉位）。所以 dshvm install 0.1.3-alpha.1 即便没发到 npm 也能装。

- 选项：--as <id> 改注册版本 ID；--bin <name> 为多 bin 包选 bin；GITHUB_TOKEN/GH_TOKEN 提升 GitHub 限速（也能访问私有仓库）。
- GitHub 源码树解压会跳过 Windows tar 无法创建的条目（符号链接）并给警告；若构建需要读取 git 元数据，dshvm 会先加一个单提交快照，使 tarball 也能构建。

隔离数据与使用场景

所有版本默认共享一个 $DSH_HOME（默认 ~/.dsh）—— 插件、profiles、会话、配置、凭证。isolate 给某个版本一份独立的。三种场景，先看表：

| 场景 | 命令 | 说明 |
| 隔离拷贝升级 —— 保留现有会话/数据，新版本独立运行 | dshvm isolate <version> --copy | 把共享 ~/.dsh 拷进该版本自己的数据，升级不会污染你在用的会话环境 |
| 多版本管理，正常升级 | dshvm install <version> | 正常安装版本，和所有版本一样共享默认 ~/.dsh |
| 完全隔离环境测试 | dshvm isolate <version> | 一个全新、空白的 $DSH_HOME —— 不拷贝任何东西、不影响任何现有数据 |

isolate 之后，dshvm use <version> 把该版本指向它自己的 $DSH_HOME。这份状态存在磁盘上，所以跨终端、重启仍生效 —— 但它不是 shell 变量（echo $DSH_HOME 为空；是连接器在 dsh 进程内注入）。查看：cat ~/.dsh-versions/active-data.txt。

A. 完全独立的版本 —— isolate + use

dshvm isolate 0.1.3-alpha.1 # 该版本全新、空白的 $DSH_HOME dshvm use 0.1.3-alpha.1 # 激活它（写入 $DSH_HOME 指针）

现在该版本只用自己那份数据：插件落到它自己的 profiles 目录；你在里面建的会话 / 配置不会泄漏到共享 ~/.dsh 或其它版本。

B. 共享同一份数据 —— 只要 use

dshvm use 0.1.2-rc.1（未隔离）读写共享的 ~/.dsh；所有版本看到同一套插件、配置与会话。

C. 独立但要接续现有数据 —— isolate --copy

dshvm isolate 0.1.3-alpha.1 --copy # 先拷贝你的共享 ~/.dsh，再转为独立

D. 跨终端、重启仍生效 —— 但不进你 shell 的环境变量

隔离状态存在磁盘上（~/.dsh-versions/active-data.txt + isolate/<id>/），所以任何窗口 / 进程、甚至重启后 dsh 都用它 —— 但你终端里 echo $DSH_HOME 是空（连接器只在它启动的 dsh 进程内注入）。查看：cat ~/.dsh-versions/active-data.txt。

E. 切走 / 去掉隔离

dshvm use 0.1.2-rc.1 # 回到共享 ~/.dsh dshvm unisolate 0.1.3-alpha.1 # 删掉隔离副本，回到共享 ~/.dsh

F. 插件到底装在哪（两层）

- ~/.dsh-versions/dsh-<id>/ —— dsh 的代码（bin + 它自己的 node_modules）。插件不是装这里。
- $DSH_HOME（=~/.dsh）—— 插件、profiles、会话、配置、skills、附件、凭证。

工作原理

dsh（连接器）-> 读 ~/.dsh-versions/current-bin.txt -> node <激活 bin> ~/.dsh-versions/versions.json = 版本 -> { bin, kind, realVersion } ~/.dsh-versions/active.txt = 激活版本 ID

- 连接器（dsh.cmd / dsh.ps1 / dsh）是极薄转发器，运行激活版本；bin 路径来自各包 package.json 的 bin 字段。
- 每个版本从自己的 node_modules 解析依赖；源码槽位在槽位内构建，workspace 链接保持有效。
- kind 取值：npm-global、store、source/gh-source、local。

环境变量

| 变量 | 含义 | 默认 |
| DSHVM_HOME | 版本主目录。 | ~/.dsh-versions |
| DSHVM_BIN_DIR | 连接器目录覆盖。 | npm 全局 bin 目录 |
| GITHUB_TOKEN / GH_TOKEN | GitHub API 令牌。 | — |

DSH_HOME 是 dsh 的数据主目录，由隔离数据模式使用，不是 dshvm 的设置项。

卸载

按需选一档：每档都会移除 dshvm，区别是保留多少受管状态（连接器、版本、数据）。

| 档 | 命令 | dsh 结果 |
| 0 | npm uninstall -g dshvm | 照常可用（连接器 + ~/.dsh-versions 保留） |
| 1 | + 移除/还原 dshvm 连接器 | 回退到你自己的 npm 全局 dsh |
| 2 | + rm -rf ~/.dsh-versions | 只剩你自己的 npm 全局 dsh |

源码 checkout 位于 ~/.dsh-versions 之外，所以第 2 级也不会删它们 —— 只删 dshvm 指向它们的指针。

常见问题

- use 会影响运行中的会话吗？ 不会 —— 已运行的进程保持原版本；新启动的 dsh 用激活版本。
- dsh web 报端口被占用？ dshvm 自动适配：占用则用下一个空闲端口（--port）；也可 dsh web --port <n> 自定。
- 版本不在 npm 上（如 0.1.3-alpha.1）？ dshvm install 0.1.3-alpha.1 自动回退到 DSH GitHub 源码构建。
- 含符号链接的仓库在 Windows 解压失败？ 跳过并警告；DSH 本体可构建。仅当没有可用的根目录时才失败。
- 只支持 Windows？ 不是 —— 连接器与路径跨平台；CI 也覆盖 Linux / macOS。

开发

npm test # 离线套件（不会安装 dsh）
npm run test:install # 真实 dsh 安装 + 运行检查（需联网）

- npm test 逐个跑 test/*.test.js（各自独立进程内 node:test，stdio 继承）并做 lib/ 加载检查；用临时 home，不会碰你的 ~/.dsh-versions，在受限沙箱也能跑。
- npm run test:install 在临时环境装遍每个真实来源（npm dsh、一个通用 npm 包、GitHub 发布 tgz）；设 DSHVM_TEST_SOURCE=1 还会构建一个不在 npm 上的源码版。
- CI 在 Ubuntu/macOS/Windows 上对 Node 18/20/22 跑离线套件；真实安装集成为手动 workflow_dispatch 任务。

参与贡献

欢迎提 Issue 和 PR。改动提交前先跑一遍离线套件 npm test（不联网、不碰你的 ~/.dsh-versions）；涉及桌面的改动见 ui/README.md。

许可

MIT —— © dshvm 贡献者。DSH 版权归 DeepSeek 所有；dshvm 是独立的社区工具。