会话迁移 hong-yu-Zhu/dsh-migration

dsh-migration · DSH 数据迁移插件

v0.1.0（预览版） · 本插件由 DeepSeek Harness（AI）使用 DeepSeek 设计完成。

把 DeepSeek Harness（DSH） 的对话（会话）与插件在一台电脑和另一台电脑之间迁移，双通道：

- 离线 ZIP：勾选内容 → 加密导出 zip → 拷到目标机 → 导入
- Git 同步：配置远程仓库，内容加密后推送 / 拉取（增量提交，天然去重）

导入幂等去重：按 session-id / 插件名@版本 / 内容指纹(sha256) 三键判定，已同步的内容自动跳过，绝不重复导入。

✨ 特性

- 双通道：ZIP 离线迁移 + Git 增量同步，任选其一
- 内容加密：AES-256-GCM，口令经 PBKDF2-SHA256（600k 迭代）派生
- 幂等去重：再次导入/拉取只报告“已存在”，不产生副本
- 自举：导出包自动包含迁移插件自身，目标机导入一次即获得 /migration 能力（含 Git 通道）
- 官方内容不掺水：官方 @deepseek-ai/* bundle 不导出（目标机同版本 dsh 自带），只迁移第三方插件
- 零依赖：压缩用 vendored fflate，无需 npm 安装任何新增依赖
- 安全加固：导入路径穿越防护、zip 炸弹防护、CSRF 请求头、zstd 魔数校验（详见 安全说明）

📦 安装

前提：目标机已安装 DSH（npx @deepseek-ai/dsh web 可启动）。

当前为预览版，通过源码装配方式挂载到 DSH Web profile：

1) 拉取本仓库（或下载源码）到任意目录，例如 D:\plugins\dsh-migration
git clone https://github.com/hong-yu-Zhu/dsh-migration.git D:\plugins\dsh-migration

2) 建立 junction（等价 pnpm link），让 web profile 的 node_modules 可解析 $profiles = "$env:USERPROFILE\.dsh\profiles\web" New-Item -ItemType Junction -Path "$profiles\node_modules\dsh-migration" -Target "D:\plugins\dsh-migration"

3) 向 cordis.patch.yml 追加挂载条目（注意：结尾勿留多余空行/字面 \n） Add-Content "$profiles\cordis.patch.yml" "n- insert:n - id: dsh-migrationn name: dsh-migrationn config: {}"

重启 dsh web 后，左侧出现「迁移」Tab 即安装成功。

打包版（零依赖桌面 exe）同理：把插件 link 进 ~/.dsh-desktop/dsh-home/profiles/web。
若后续发布到 npm，将提供 npm i dsh-migration 的标准安装方式。

🚀 快速开始

GUI（左侧「迁移」Tab）

1. 勾选要转移的会话 / 插件 / 插件数据 / 附件
2. 导出为 ZIP：加密开关（默认开）→ 输入口令 → 生成下载
3. 导入 ZIP：选择文件 → 输入口令（若加密）→ 查看报告（新增/跳过/冲突）
4. Git 同步：填远程 URL / 分支 / Token → 保存 → 推送 / 拉取

对话命令（agent 可调用）

migration export D:\backup\m.zip [--password 口令] [--no-encrypt] [--sessions id1,id2] [--plugins 插件1,插件2] migration import D:\backup\m.zip [--password 口令] [--force] migration git push [--password 口令] migration git pull [--password 口令]

- --force：冲突时覆盖本地（默认冲突跳过并在报告中列出）
- 缺省 = 导出全部（会话 / 插件 / 附件 / 配置 / 插件数据）

HTTP API（GUI 调用的后端，亦可 curl）

所有写操作（POST）需携带自定义请求头 x-dsh-migration: 1（CSRF 防护；GUI 自动携带）。
git 推送/拉取支持 https Token 认证：在配置里填写 Token 即可（仅按次注入 git 命令，不落盘到 .git/config）。

GET /migration/api/health ← 是否可用 GET /migration/api/discover ← 本机内容清单 GET /migration/api/config ← 读取配置 POST /migration/api/config ← 保存配置（git remote/branch/token、encrypt），需请求头 POST /migration/api/export ← body: {selection, passphrase, encrypt} → zip 流，需请求头 POST /migration/api/import ← body: zip 字节 (+?passphrase=&force=1) → 报告，需请求头 POST /migration/api/git/push ← {selection, passphrase, encrypt} → {message, hash}，需请求头 POST /migration/api/git/pull ← {passphrase, force} → 报告，需请求头

curl 示例：

curl -X POST -H "x-dsh-migration: 1" -H "content-type: application/json"
-d '{"git":{"remote":"https://github.com/u/repo.git","token":"ghp_xxx"}}'
http://127.0.0.1:3080/migration/api/config

🔐 安全说明

- 默认排除 .credentials.yaml（API 凭据）——刻意不导出
- Git 推送内容默认加密；仍建议使用私有仓库
- Token 明文存于 <DSH_HOME>/dsh-migration.json（权限 0600），与 dsh 凭据同级处理；git 命令按次注入 Token（不写入 .git/config），错误输出自动脱敏
- 导入路径穿越防护：迁移包内所有落位路径经包含性校验，.. / 绝对路径 / 越界一律拒绝并记录错误，绝不写入 DSH_HOME 之外
- Zip 炸弹防护：解压前先解析 zip 中央目录，条目数（≤ 50,000）与解压总字节（≤ 2 GiB）超限直接拒绝
- CSRF 防护：写操作要求 x-dsh-migration: 1 头，跨站页面无法伪造
- zstd 魔数校验：会话文件不是有效 Zstandard 数据则拒绝写入（防止目标机启动崩溃）
- 建议从可信来源获取迁移包后再导入

🧱 架构与设计要点

- 数据根 = DSH_HOME（环境变量优先，默认 ~/.dsh；打包版自然指向 ~/.dsh-desktop/dsh-home）
- 配置存 <DSH_HOME>/dsh-migration.json（git 远程 / 分支 / token、加密开关、sourceId）
- 加密：AES-256-GCM；口令 PBKDF2-SHA256(600k) 派生；仅内容加密，清单/指纹明文（便于导入前预检与去重）
- 会话按原路径原样落位（session 文件内部含身份校验，目录头与内容必须一致），并做 zstd 魔数校验
- 插件数据目录 = 插件自声明 dsh.migration.dataDirs + 内置映射表（memory→memories 等）
- 压缩用 vendored fflate，零新增依赖

🗂 项目结构

dsh-migration/
├── lib/
│ ├── index.js # host 入口：HTTP 路由 + 对话命令 │ ├── client.js # client 界面（迁移 Tab，UMD 零构建） │ └── engine/ │ ├── discover.js # 会话 / 插件 / 数据 / 附件发现 │ ├── engine.js # 导出打包 + 导入应用（去重/报告） │ ├── archive.js # zip 封装（vendored fflate） │ ├── encrypt.js # AES-256-GCM + PBKDF2 │ ├── git.js # Git 同步通道（push / pull / token 认证） │ └── vendor/ # fflate（MIT）零依赖副本 ├── tests/engine.test.mjs # 引擎单测（zip/加密/git/幂等/安全） ├── tools/ # 开发辅助脚本（测试 home 装配、端到端验证） ├── package.json ├── README.md # 本文档 └── CHANGELOG.md # 版本历史

🧪 开发与测试

node --test tests/engine.test.mjs # 引擎单测（zip / 加密 / git / 幂等 / 安全防护）
node tools/assemble-test-home.mjs # 装配隔离的测试 DSH_HOME
node tools/verify-pull.mjs # 端到端：新机器安装→配置→pull→重启验证

端到端已在独立 home 验证：导出→导入、加密口令、Git 本地裸仓库 push→pull→新机器启动可见。

📜 版本历史

详见 CHANGELOG.md。当前 v0.1.0（预览版）。

🤝 反馈与贡献

- 遇到 Bug / 有想法？欢迎在 Issues 提出
- 想贡献代码？Fork 后提交 Pull Request 即可
- 请附带可复现步骤（涉及迁移包时请脱敏）

📄 License

MIT © 2026 hong-yu-Zhu