环境迁移包 wjf1/dsh-portable

dsh-portable

给 DeepSeek Harness 用的离线 / 在线导入导出插件：把一台机器上正在工作的 DSH 主目录打包成单个 .dshpkg，在另一台机器上还原 —— 不需要联网、不需要 pnpm install、不需要手工改路径。

English · CHANGELOG · 发布流程 · 接力文档

为什么要有它

把 DSH 环境搬到另一台机器，麻烦有三层：

1. 一个能用的 profile 不止一个文件。 它是 profiles/<name>/ 加上带 node_modules 的插件、技能、hooks、任务板、存储、AGENTS.md、已下载运行时、会话日志。
2. 插件是靠 pnpm 联网装的。 内网机、被锁的办公电脑、代理坏掉的机器根本跑不了 dsh plugin add。
3. 配置里写死了绝对路径（C:\\Users\\me\\.dsh、/home/me/.dsh）和 profile 名。直接复制目录树，换台机器启动就是一堆坏掉的插件路径。

dsh-portable 三件事一起解决：把白名单内的根打成单个自描述归档；任何时刻都不走出白名单；导入时只重写真正含本机路径的那六个配置文件。

包里装什么

| 根 | 路径 | 默认 |
| profile | profiles/<name>（配置和插件的 node_modules） | 总是 |
| skills | skills | 总是 |
| skills-disabled | skills-disabled（宿主已禁用的技能） | 可选，默认不含（includeDisabledSkills） |
| hooks | hooks | 总是 |
| storages | storages | 总是 |
| 任务板 | task-board / todo-board 存储 | 总是 |
| 内置浏览器宿主 | dsh-builtin-browser-host | 总是 |
| 智能体指令 | AGENTS.md | 总是 |
| 会话日志 | sessions | 可选（includeSessions） |
| 运行时 | 已下载的运行时 | 可选（includeRuntimes） |
| 凭据 | .credentials.yaml | 可选，默认关闭 |
| source map | 包内 .map | 默认包含（includeSourceMaps） |
| 备份文件 | 配置旁 .bak- | 默认不含（includeBackups） |

skills-disabled 曾是默认包含（在真实机器上占整包 86%），现在与其它可选根一致：默认排除，勾选「已禁用的技能」或传 includeDisabledSkills: true 才打包。

表外的路径永远不会被采集 —— 代码里不存在"把整个主目录递归复制一遍"的步骤。

安装

dsh plugin --profile desktop add dsh-portable

插件必须登记在 profile 自己的 package.json 里 —— dependencies 和 dsh.profile.bundles 两处都要。把包目录手工拷进 profiles/<profile>/node_modules 看起来能跑，但该 profile 下次执行 npm install 时，npm 会把没声明的包当 extraneous 删掉；那之后面板照常渲染卡片，但每个请求都回 404。dsh plugin add（或在 profile 里 npm install dsh-portable）会把这两处一起写好。

然后打开 DSH 设置 → 便携迁移。设置页区块注册在 settings.section、顺序 70，中英文随宿主语言自动切换。

不按按钮就什么都不会写进 DSH 主目录。

面板怎么用

六个卡片区：

1. 导出 —— 勾选可选根、给文件起名、点导出。打包跑在 worker 线程里；进度条实时显示条目数，20 MB / 14 000 条目的包约 3 秒。填加密口令（留空则不加密）可以把整包用 AES-256-GCM 加密——口令丢失无法恢复。
2. 包列表 —— <DSH_HOME>/dsh-portable/exports 下的所有 .dshpkg，显示大小、修改时间，按钮为 选择 / 下载 / 分享 / 删除（删除需二次确认），加密包带「已加密」标记。选择把包标记给下面的导入卡片；下载在面板内分段拉取并显示进度条，支持断点续传（优先直写磁盘，过大的包交给浏览器原生下载器）——局域网分享只在两台机器同网时可用。
3. 上传 —— 选一个 .dshpkg，流式落盘（先写 .part 再改名），带百分比进度，2 GB 的包也不会进内存；加密包同样可以上传。
4. 导入 —— 选 merge 或 replace（当前选中项高亮），先预览（零写入），再点「执行导入」，此时会先弹出内联确认块，确认后才真正写入。子路径选择：预览后可勾选要导入的顶层项、或在附加框里填包内子路径（如 skills/my-skill），两者取并集，留空表示整个包；replace 模式只会把选中的路径移去备份。加密包先填解密口令。结果以键值表格呈现：落地项、被重写的路径数、备份目录、导入范围与 warning，并额外显示插件清单合并结果（本机保留的 bundle、包需要但本机缺失的 bundle）。导入完成后需要重启 DSH，写入的配置才会生效。
5. 局域网分享 —— 把包发布成一次性下载链接（http://<内网IP>:<端口>/d/<token>）。默认 1 次下载、60 分钟，支持 Range/HEAD，过期或下完返回 410。复制会把链接写进剪贴板，且只有真的写成功才显示「已复制」（纯 HTTP 来源下退回 textarea 方案）。无中继、无云端、无账号。
6. 备份 —— 导入前自动生成的备份（<DSH_HOME>/portable-backups/<stamp>），保留最近 5 份。每份都有恢复按钮：把该备份里的文件写回主目录，写回前会先把当前版本另存到 <stamp>-pre-restore。恢复后同样需要重启 DSH。

界面截图

截自 DSH 设置面板；图中的主目录用户名与局域网分享链接均为示例值。

导出卡片与包列表

上传、导入、局域网分享与备份

HTTP API

前缀：/dsh-portable/api。除下载路由与上传流式路由外，响应都是 JSON。鉴权复用宿主的 connection.requestRejection（cookie + 可信来源），该服务不存在时降级为仅回环地址可访问。

| 方法 | 路径 | 用途 |
| GET | /status | 宿主信息、包数量、当前任务、分享服务状态 |
| GET | /profiles | 本机 DSH 主目录里的 profile |
| GET | /jobs | 最近的任务（导出 / 预览 / 导入） |
| GET | /jobs/detail?id= | 单个任务的实时进度 |
| POST | /jobs/cancel | 取消任务 |
| POST | /export | 开始导出 |
| GET | /artifacts | 可导入的包列表（含 encrypted 标记） |
| GET | /artifacts/meta?id= | 单个包的 manifest（加密包回 400 ENCRYPTED，口令不进 URL） |
| GET | /artifacts/download?id= | 以附件形式把包流给浏览器；支持 Range/If-Range（206 断点续传）与 HEAD |
| POST | /artifacts/delete | 删除包（UI 里二次确认） |
| PUT | /upload/<name> | 上传包，流式落盘 |
| POST | /import/preview | 两阶段安装第一阶段（零写入） |
| POST | /import | 两阶段安装第二阶段（必须 confirm:true） |

/export、/import/preview、/import 共用这些可选字段：include（包内逻辑路径前缀数组，如 ["skills/my-skill"]，只导出/导入所选子路径）、passphrase（加密包口令，随请求体走，不进 URL、不进任务描述）。
| GET | /backups | 自动备份列表 |
| POST | /backups/restore | 把某份备份写回主目录（写回前先另存当前文件） |
| POST | /share | 生成一次性局域网下载链接 |
| GET | /share | 列出有效链接 |
| POST | /share/remove | 撤销链接 |

所有涉及"哪个包"的参数都只接受 artifactId（如 exports:machine-20261018.dshpkg），绝不接受文件路径。 /、\\、.. 与控制字符一律拒绝，所以模型或网页都没法借这个插件读写任意文件。

模型工具

注册到宿主的 tools 服务（服务不存在时静默跳过）：

| 工具 | 行为 |
| portable_export | 打包当前 profile，返回 id、大小、条目数、各根统计；支持 passphrase（加密）与 include（子路径） |
| portable_inspect | 只读 manifest，不导入；加密包传 passphrase |
| portable_import | 不带 confirm:true 就是 dry-run；带上才真正两阶段安装；支持 include（子路径）与 passphrase |
| portable_share | 生成一次性局域网链接（1 次下载、60 分钟） |

无宿主引导安装（目标机没装 DSH）

Windows
powershell -ExecutionPolicy Bypass -File bootstrap\install.ps1 preview .\machine.dshpkg
powershell -ExecutionPolicy Bypass -File bootstrap\install.ps1 install .\machine.dshpkg --yes

macOS / Linux
sh bootstrap/install.sh preview ./machine.dshpkg
sh bootstrap/install.sh install ./machine.dshpkg --yes

参数：--home <目录>（默认 $DSH_HOME 或 ~/.dsh）、--profile <名>、--mode merge|replace、--keep <n>、--passphrase <口令>（加密包）、--include <子路径>（可重复）、--yes。退出码：0 成功、1 失败、2 用法错误；非 TTY 且没有 --yes 时拒绝写入。

包格式

.dshpkg 就是 gzip 压缩的 tar，manifest 是第一条目：

.dsh-portable/manifest.json
profiles/desktop/...
skills/...
hooks/hooks.json
...

{
"format": "dsh-portable/1",
"createdAt": "2026-10-18T02:11:03.000Z",
"tool": { "name": "dsh-portable", "version": "0.1.0" },
"source": {
"hostname": "WORKSTATION",
"platform": "win32",
"arch": "x64",
"node": "v22.23.2",
"dshHome": "C:\\Users\\me\\.dsh",
"profile": "desktop"
},
"options": { "includeNodeModules": true, "includeSessions": false },
"stats": { "entries": 13774, "files": 13482, "dirs": 292, "links": 0, "bytes": 20664511 },
"roots": [{ "id": "skillsDisabled", "logical": "skills-disabled", "files": 13193, "bytes": 44615569 }]
}

因为就是普通 tar，tar -xzf machine.dshpkg 在任何机器上都能直接看包里的内容 —— 哪怕那台机器从没听说过 DSH。长路径走 PAX 扩展头，读取端是增量解析，PAX 正文跨 chunk 也能正确处理。

加密包（导出时填了口令）整体是一层 AES-256-GCM 容器：magic "DSHPKG-ENC1\n" + scrypt 盐(32B) + iv(12B) + 密钥确认块 + 密文 + 包尾 16B 认证标签，密钥由口令经 scrypt（N=2¹⁵）派生，全程流式。加密包不是明文 tar，tar -xzf 看不到内容；口令错误在读取最开始就会被拒绝（报「wrong passphrase or corrupted package」），篡改任何一个字节都无法通过认证。口令没有恢复途径——丢了就等于丢了包。

导入流水线

预览: 读 manifest ──► 每个顶层项的文件数/字节数/目标机是否存在 ──► 报告（零写入）安装: 解包到 <home>/portable-staging/<stamp>（边写边校验 sha256） ──► 目标 profile 名不同则重命名目录 ──► 重写 6 个配置文件里的本机路径 ──► 这 6 个文件备份到 <home>/portable-backups/<stamp> ──► 逐顶层项落地（merge：只增不减；replace：先移走再落） ──► 清理旧备份 ──► 删除暂存区

包尾的 .dsh-portable/checksums.json 记录每个文件的 sha256。导入时边写边算，对不上就直接拒绝该包，被篡改或传坏的包不会被静默还原成"看起来正常"的数据。没有该条目的包（旧包、手工打的包）仍可导入，但报告里是 verified: false，不会假装校验过。

磁盘余量。 导入会先把整包解开到 portable-staging/<stamp>，再合并到目标位置，因此峰值占用约为"解压后体积"叠加在现有 profile 之上。这次双写换来的是失败可回滚——落地前目标目录一点都没动。

取消导入时先让 worker 自行中止并退出（最多等 5 秒），确认退出不了才强制终止，因此暂存目录一定会被清掉：取消一个 1 GB 的导入不会留下 1 GB 垃圾。

路径重写刻意收窄：只碰 profiles//cordis.patch.yml、cordis.yml、package.json、pnpm-workspace.yaml、hooks/hooks.json、hooks/settings.json。插件包内部不重写，第三方完整性校验与 source map 不受影响。

安全模型

- 白名单采集。 代码里不存在递归遍历整个主目录的逻辑。
- 只认 artifactId，不认路径。 见上。
- 导入必须确认。 缺 confirm:true 的路由返回 400 CONFIRM_REQUIRED；模型工具默认 dry-run。
- 可选口令加密。 导出时可给整包加 AES-256-GCM（scrypt 派生密钥，见「包格式」）；错误口令立即拒绝，篡改无法通过认证。口令随请求体传递，不进 URL、不进任务描述。
- 解包防护。 200 000 条目上限、单文件 2 GB、总解压 8 GB、压缩比 200（输出超 64 MB 后才生效）、wx 不覆盖、safeJoin 挡 ..、符号链接为绝对路径或越界时拒绝；合并落地时再次校验符号链接目标，绝不还原指向主目录之外的链接。
- 逐文件校验。 包尾 checksums.json 收录每个文件的 sha256，导入时比对，不一致直接失败。
- 写之前先备份。 六个配置文件先复制到备份目录；replace 模式把要替换的目录移进 portable-backups/<stamp>/replaced/，不是删除；子路径选择时只移走所选路径本身。
- 凭据默认不进包。 .credentials.yaml 只有显式勾选才打包，面板上的勾选框直接标注风险。导出是纯本地操作，不上传任何数据。
- 分享链接范围极小。 一次下载、60 分钟、单文件、token 门禁，之后 410。没有目录列举，没有中继。

开发

npm test # 89 项：tar、archive、crypto、installer、jobs、routes、share、inspect
npm run check # 语法检查 + import 冒烟
npm run sync # 把本包拷进某个 profile 的 node_modules 做真机联调
npm run verify # 发布门禁：版本一致、文件清单、测试

没有构建步骤：index.js（宿主端）、lib/client.js（浏览器端 bundle，纯 React.createElement）、lib/.mjs 都是直接发布的源码。这是刻意约束 —— 插件必须能在包版本未知的宿主上加载，所以客户端半边只依赖 react 和 --dsw-alias-* CSS 变量。

兼容性

- DSH >= 0.1.7-rc.2
- Node ^22.15.0 || >= 24.0.0
- Windows / macOS / Linux（Windows 长路径走 \\?\ 前缀）

已知限制

- 会话日志默认不进包，因为里面有对话内容。
- 加密是可选项且无签名：不填口令的包是明文 tar，含凭据时请加密导出或放在加密介质上；口令一旦丢失无法恢复。
- 子路径选择器按逻辑路径前缀匹配（目录/文件级），不支持通配符。
- 指向 DSH 主目录之外的符号链接会被打进包，但在 Windows 上没有开发者模式时无法重建 —— 这种情况记 warning，不中断导入。

许可

MIT，见 LICENSE。