移动工作区插件 · 安装与使用图文教程

一、插件是什么 · 装的是哪个文件

这个插件让 DeepSeek Harness 在移动硬盘 / U 盘上创建完全自包含的便携工作区：会话、插件、工程文件、交付、日志、账号凭据全部落在盘上；拔盘显示脱机，插盘自动重新识别；换一台装了本插件的电脑插上盘即可继续工作。

「安装插件」装的是整个目录，不是某个单独文件。目录名 portable-workspace-plugin（包名 dsh-portable-workspace）。关键文件如下：

二、安装（每台电脑装一次）

1把整个 portable-workspace-plugin 目录放到本机一个固定、不会被删的位置，例如 E:\DSH工作区\portable-workspace-plugin。

2在 DSH 里用 plugin_manager 安装这个目录（把下面的路径换成你自己的绝对路径）：

plugin_manager  install_bundle  E:\DSH工作区\portable-workspace-plugin

返回 application: applied、warnings: [] 即成功。等价地在会话里说「把这个目录作为 bundle 插件安装」也可以。

3侧栏「全局面板」里出现 「移动工作区」 入口（U 盘图标），点击打开主面板。首次进入可能是空态：

4改了 JS 之后要重载插件才生效（或重启 DSH）：

plugin_manager  set_bundle  dsh-portable-workspace  enabled=false
plugin_manager  set_bundle  dsh-portable-workspace  enabled=true

两次都返回 application: applied 即完成。这是开发/升级时最常用的动作。

三、使用流程（图解）

3.1 初始化这块盘

插入 U 盘后点「重新扫描」。第一次使用点「初始化这块盘」，填入根目录（例如 H:\Protable-DSH）。插件会在盘上写根标记 .dsh-portable.json（含随机 rootId），并建好三个目录：Protable-Workspaces / Projects / support。

3.2 新建移动工作区

点「新建移动工作区」，填写根目录 / 名称 / 备注，密码可留空（留空 = 不设密码）。设密码时要输入两次（密码 + 确认密码），两次不一致会红字提示；每个密码框右侧有一个「小眼睛」按钮，点一下可明文查看输入内容。

3.3 打开（先验密码）

点「打开」。有密码的工作区会弹密码框，输错会被拒绝且不启动：

3.4 检查依赖插件

密码通过后，插件核对工作区声明的插件清单。缺插件会弹对话框，区分「必需 / 可选」，并给出「一键安装缺失插件」「连可选插件一起装」「跳过，直接打开」：

3.5 打开成功后

约十几秒后弹出「打开 · 便携实例地址」对话框，给出一个带 token 的随机端口 URL（如 http://127.0.0.1:5xxxx/?token=…）。点「在新窗口打开」会打开一个独立的便携实例窗口。它是全新的 DSH home，第一次进入会看到初始引导页；如果之前点过「同步本机登录」，就已经带着账号，无需重新登录。

3.6 新版面板与「添加插件」

工作区行上现在有一排按钮：打开 / 登出 / 修改密码 / 添加插件 / 迁移 / 删除；有密码且已解锁时会显示绿色「已解锁」徽章。「添加插件到这块盘」对话框里可填包名、勾选「作为可选插件」：

四、账号、密码与安全操作

4.1 同步本机登录（单向、显式）

卷卡片上的「同步本机登录」把本机 .credentials.yaml / .anonymous-user-id 复制到盘上的便携 home，永不从盘回写本机。这样换电脑不用重新登录。对应的「退出登录」会把盘上这两个凭据删掉。不想把账号带在 U 盘上就不要点同步（凭据以明文 YAML 随盘，保管好 U 盘）。

4.2 登出 / 重新验密码

「登出」会停掉便携实例并清掉本次解锁状态。之后再次打开必须重新输密码。此外：

• 移动盘重新插拔后也要重新验密码 —— 解锁状态只存在 Host 进程内存里，不落盘；拔盘导致重扫、换盘符、DSH 重启、插件重载都会让它失效。
• 便携实例进程若已退出，解锁状态也会自动过期。

4.3 修改密码

「修改密码」对话框要求：当前密码（无密码的工作区留空）、新密码、确认新密码。旧密码错误 / 两次新密码不一致都会拒绝。新密码留空 = 取消密码。

4.4 删除工作区（强确认）

点「删除」会弹确认框，必须：

1. 手动输入固定文字：我已知晓删除该工作区，无法恢复！（不输入或输错，确认按钮不可用，Host 端也会再次校验，防止直接调接口绕过）；
2. 输入工作区密码（未设密码的留空）。

两者都满足才真正删除（连同会话、工程、日志一起）。

4.5 迁移

「迁移」把工作区复制到另一块盘或本地硬盘路径，可勾选「迁移后删除源工作区」。迁移会重写 rootId 并记 origin，重写每份会话日志 header 里的绝对 cwd 并把会话目录收拢到新位置（否则 jsonl 后端判定损坏），同步修正 workspace registry；新路径写入本机索引，重新扫描即可识别。

五、插件市场与「添加插件」常见问题

Q1：「添加插件到这块盘」是从网上下载，还是从本机复制？

从 npm 官方源下载，装到移动盘上的便携配置 Protable-DSH\support\home\profiles\portable，不是从本机已装插件里复制。链路是：随包 node 跑随包 pnpm 执行 pnpm add <包名> → 成功后把带 dsh.bundle 的包追加进 dsh.profile.bundles（这一步才真正激活，只 add 到 dependencies 是不会被加载的）→ 重启便携实例生效。U 盘是 exFAT、无硬链接，冷装一个带几百个传递依赖的插件实测约 2–5 分钟；装过一次后 node_modules 留在盘上，下次秒开。

Q2：为什么之前「只能添加 dshmarket」，其它加不了？

不是限制，是包名写错。插件市场里显示的是短名（dsh-web-all、modlens），而 npm 上的真实包名带作者前缀（@linxin666/dsh-web-all、@liustack/modlens）。用短名去请求 registry.npmjs.org/dsh-web-all 必然 404；dshmarket 没有 scope，所以能装上。日志里的 ERR_PNPM_FETCH_404 ... dsh-web-all is not in the npm registry 正是这个原因。

Q3：为什么本地市场搜得到的插件，便携版搜不到？

便携市场本身是好的（8.9k 条目，见图 6），「搜不到」是按最新版兼容性过滤：市场索引里 @linxin666/dsh-web-all 的最新版 0.4.15 要求 engines.dsh >=0.2.2-rc.1，而本机 DSH 是 0.2.1-rc.5 不满足，于是被「已隐藏 60 个与 DSH 0.2.1-rc.5 不兼容的插件」过滤掉；本机桌面市场的缓存还停在旧的 0.4.14（>=0.2.1-rc.3 满足），所以本机搜得到。解决办法：用「添加插件到这块盘」直接填短名 dsh-web-all（或完整包名），让插件自动挑兼容版本安装 —— 不必依赖市场搜索结果。

Q4：该用 --profile desktop 还是 --profile web？

都不对。便携实例的 DSH_HOME 被指向 H:\Protable-DSH\support\home，profile 名固定是 portable（lib/constants.js 的 PROFILE_NAME）。在便携实例的会话里执行 dsh plugin --profile desktop add dshmarket 或 --profile web，会写到本机 desktop / 便携 home 里那个用户自建的 web profile，都不是当前实例实际用的 portable，因此「装了却看不到市场」。

六、工作机制与依赖

一句话：每个工作区 = 移动盘上的一份独立 DSH 数据 + 本机 DSH 启动的一个独立 CLI 实例。打开工作区时，插件生成一个 --patch 覆盖层并启动便携实例：

DeepSeek Harness.exe --expose-internals <cli.js> portable \
    --patch <工作区>/launch/cordis.patch.yml --port 0 --no-open

依赖（都是本机已有的，不需要额外装东西）：

• 本机 DeepSeek Harness：用它的 CLI（dsh-desktop-host/lib/cli.js）、随包 node、随包 pnpm、asar 内的基础 bundles。插件本身零 DSH 包依赖，服务都从 ctx 运行时取。
• npm 官方源可达：仅「安装插件」时需要联网下载；已装过的插件全在盘上，离线也能开。
• 盘上标记文件：识别桥梁；本机仅残留一个索引 ~/.dsh/portable-workspace/roots.json（只记路径，不含任何工作区数据）。

边界 物理拔插未做真实断电测试（用移除根标记模拟），跨电脑未做双机实测（只有一台机器）；其余功能均在真实 U 盘 H: 上全流程验证通过。

七、DeepSeek Harness 升级时，插件如何同步更新

先说结论：插件不会随 DSH 升级「自动更新」，但也不会被升级删掉，通常升级后照常可用；要不要更新、怎么更新，取决于你是「本机插件」还是「盘上插件」这两类。

7.1 两类东西，升级行为不同

7.2 升级后可能发生什么

• 正常情况下：DSH 升级只换掉安装目录里的程序与内置 bundles。插件是软链接到固定目录，profile 里那条 link: 记录还在，重启后自动加载，无需任何操作。
• 兼容性：插件不声明 engines.dsh 硬红线，且所有能力都通过公开 Service / ctx 取得，一般跨小版本可用。若升级后内部 Service 契约变化，现象会是面板报错或打不开 —— 这时把插件目录里的代码更新到适配新版的版本，再 set_bundle false→true 重载即可（数据仍在盘上，不会丢）。
• 便携实例会自动「跟上」新 DSH：因为每次打开工作区都是用本机当前的 DeepSeek Harness.exe + cli.js 启动。所以升级 DSH 后，下次打开工作区，便携实例就跑在新版上了。
• 可能要重新验一次密码：升级/重启 DSH 会清掉进程内的解锁状态，这是设计使然（安全），重新输一次密码即可。
• 版本差异导致的「隐藏插件」：这正是 Q3 的现象 —— DSH 升级后，市场按新版 engines.dsh 重新过滤；升级到 ≥0.2.2-rc.1 后，dsh-web-all 0.4.15 之类原本被隐藏的插件就会重新出现。

7.3 想让插件本体也升级，怎么做

1. 把新版本的插件文件覆盖到原目录（保持路径不变，因为 profile 是 link: 到这个目录）；
2. plugin_manager set_bundle dsh-portable-workspace enabled=false 再 enabled=true 重载，或重启 DSH；
3. 若目录要换位置，重新执行一次 install_bundle <新路径>。

整个过程不需要动移动盘，工作区数据不动、不迁移。

八、命令速查与目录结构

常用命令 / 动作

# 安装（每台电脑一次）
plugin_manager  install_bundle  <插件目录绝对路径>

# 改代码后重载
plugin_manager  set_bundle  dsh-portable-workspace  enabled=false
plugin_manager  set_bundle  dsh-portable-workspace  enabled=true

# 添加插件（在面板里操作即可，等价于下列链路）
pnpm --dir <盘>:\Protable-DSH\support\home\profiles\portable add <完整包名>
# 然后把包名追加进该 profile 的 package.json → dsh.profile.bundles，重启便携实例

盘上目录

<盘>:\Protable-DSH\
├─ .dsh-portable.json             根标记（kind/rootId/format），盘符无关识别的桥梁
├─ Protable-Workspaces\
│  └─ <ws-id>\
│     ├─ workspace.json           清单：名称、密码 scrypt、插件声明、profile、origin
│     ├─ sessions\                会话日志（.jsonl.zstd）
│     ├─ storages\                存储域 / 会话投影缓存 / workspace registry
│     ├─ logs\                    launch.log、plugins.log
│     └─ launch\                  cordis.patch.yml、start-portable.cmd、runtime.json
├─ Projects\<ws-id>\             工程文件与交付（默认工作目录也指向这里）
└─ support\home\                 便携 DSH_HOME：profiles\portable\、.credentials.yaml 等

九、如何卸载移动工作区插件

卸载是按电脑进行的：它只把这台电脑 profile 里那条 link: 软链接移除，不会删除移动盘上的任何数据。卸载后换一台仍装了插件的电脑插上盘，工作区照常打开。

1. 先关掉便携实例：在「移动工作区」面板点「关闭全部便携实例」（或逐个「登出」）。插件卸载时的清理钩子也会尝试终止便携进程，但先手动关一次更稳妥，避免残留 detached 进程继续占用 DeepSeek Harness.exe。
2. 停用再移除 bundle（两步都做，顺序不要反）：

   plugin_manager  set_bundle    dsh-portable-workspace  enabled=false
   plugin_manager  remove_bundle  dsh-portable-workspace

   也可以在 DSH 的「插件」面板里找到「移动工作区」→ 停用 → 移除。enabled=false 会触发插件的 dispose 清理，remove_bundle 再从 profile 的 dependencies / dsh.profile.bundles 里删掉这条记录。
3. 确认侧栏入口消失：刷新或重启 DSH，「移动工作区」入口不再出现即卸载完成。
4. （可选）忘掉记住的卷：删除本机桥梁文件 C:\Users\<用户>\.dsh\portable-workspace\roots.json。它只记录「这台电脑见过哪些移动工作区根路径」，不含任何工作区数据；删掉后再插盘会当作全新卷重新识别（不会丢数据）。
5. （可选）删除插件目录：因为是 link: 安装，移除 bundle 后本机那个解压出来的插件目录就可以安全删掉了。