前言¶
在 DSH 中移动一套完整配置到另一台机器时，有三个常见痛点：profile 不是单个文件，而是由多个目录和文件组成的树；插件通过 pnpm 网络安装，离线环境或受限网络无法安装；配置文件内嵌绝对路径，直接复制后路径失效。dsh-portable 针对这些问题，提供一套打包、迁移、还原的方案。
是什么¶
dsh-portable 是一个 DeepSeek Harness 插件，由维护者 wjf1 开发。它把当前 DSH home 中选定的内容打包成单个 .dshpkg 文件，包含 profile（含插件及其 node_modules）、skills、hooks、task boards、AGENTS.md 等内容，在另一台机器上还原时自动修正路径，无需网络、无需 pnpm install，也不需要手动修复配置。
核心功能¶
打包与导出¶
插件在 DSH 设置中提供「便携迁移」面板，导出时选择要包含的根目录，命名后导出。打包过程在后台线程运行，约 14000 条目、20 MB 的包约 3 秒。可选项包括：
- sessions：会话日志
- runtimes：已下载运行时
- credentials：.credentials.yaml
- source maps：*.map 文件
- backups：配置文件旁的 .bak- 文件
不包含在列表中的内容不会被收集，代码中没有递归复制整个 home 目录的逻辑。
包管理¶
导出的文件保存在 <DSH_HOME>/dsh-portable/exports/ 下，面板中显示文件名、大小、修改时间，提供选择、下载、分享、删除操作。选择后用于导入卡片，下载将文件流出到浏览器，可在局域网共享或通过 U 盘传递。
导入与合并¶
导入支持「合并」或「替换」两种模式。选择后先预览，零写入，再确认后执行导入。导入结果以键值对展示：应用项、重写的路径、备份目录、警告信息，以及插件列表合并情况（本地已有的 bundles 与包中需要的 bundles）。导入后需重启 DSH 使配置生效。
局域网分享¶
LAN share 卡片可生成一次性下载链接，格式为 http://<lan-ip>:<port>/d/<token>。默认限制为 1 次下载、60 分钟有效，支持 Range/HEAD 请求，过期或用尽后返回 410。链接复制到剪贴板时会校验是否真正写入成功。不使用中继或云服务，无账号。
自动备份¶
在导入前，插件会自动在 <DSH_HOME>/portable-backups/<时间戳>/ 保存一份当前配置的副本，保留最近 5 个。每个备份提供「恢复」按钮，恢复前会将当前版本保存为 <时间戳>-pre-restore，恢复后同样需要重启 DSH。
HTTP API¶
插件提供 REST API，基础路径为 /dsh-portable/api。所有响应为 JSON，除下载和上传文件流外。认证复用 DSH 的 connection.requestRejection 防护机制，无服务时回退到仅本地请求。
主要端点包括：
- GET
/status：主机信息、包数量、活跃任务、分享服务器状态 - GET
/profiles：当前 DSH home 中的 profile 列表 - GET
/jobs：最近导出/预览/导入任务 - GET
/jobs/detail?id=：单个任务及实时进度 - POST
/jobs/cancel：取消运行中的任务 - POST
/export：开始导出 - GET
/artifacts：可用于导入的包列表 - GET
/artifacts/meta?id=：单个包的清单 - GET
/artifacts/download?id=：以附件形式流式下载包 - POST
/artifacts/delete：删除包（需 UI 确认） - PUT
/upload/<name>：流式上传包到磁盘 - POST
/import/preview：预览（零写入） - POST
/import：执行导入（需 confirm:true） - GET
/backups：自动备份列表 - POST
/backups/restore：恢复备份 - POST
/share：创建一次性分享链接 - GET
/share：列出活跃链接 - POST
/share/remove：撤销链接
所有接口使用 artifactId 而非文件路径，拒绝 /、\\、.. 及控制字符，避免任意文件读写。
模型工具¶
插件在 host tools 服务注册了三个工具：
portable_export：打包当前 profile，返回 id、大小、条目数、各根目录的拆分portable_inspect：读取包清单但不导入portable_import：dry run 模式下不写入，带confirm:true时执行两阶段安装portable_share：创建一次性 LAN 链接（1 次下载、60 分钟）
安装与启用¶
在 DSH 中执行以下命令安装：
dsh plugin --profile desktop add dsh-portable
安装后，在 DSH 设置中找到「便携迁移」面板（顺序 70，中英文双语）。面板显示前才进行写入。
典型用法¶
离线迁移¶
在开发机器上导出包，通过 U 盘或局域网拷贝到目标机器。在目标机器的 DSH 设置中导入，选择合并或替换模式，预览后执行。导入后重启 DSH，整套配置即可使用。
局域网快速分享¶
在两台同网段机器上启动 DSH，在「LAN share」卡片中点击复制，将链接发送给另一台机器，即可直接下载包进行导入。
回滚操作¶
在导入前，插件已在 <DSH_HOME>/portable-backups/ 创建时间戳备份。若导入结果不理想，可在「Backups」卡片中选择备份并恢复，恢复前会保存当前版本。
适用场景与注意¶
适合需要在多台机器间同步或迁移 DSH 配置、在离线或受限网络环境下部署 DSH、需要定期备份并快速回滚的场景。
注意：插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证（MIT）。所有文件操作均受限于配置的根目录白名单，避免任意文件访问。
结尾¶
dsh-portable 提供了一套从打包、传输到还原的完整流程，把 DSH 的配置管理从手动复制和路径修复中解放出来。更多细节可查阅插件目录页与 GitHub 仓库。
