前言¶
DeepSeek Harness（DSH）里，一段会话并不只是聊天日志：sessionId 落在 ~/.dsh/sessions/<projectKey(cwd)>/<sessionId>/ 下，日志 frame 1 里又写了一份 cwd，~/.dsh/storages/workspace.json 里的 workspace.sessionIds 再决定它出现在哪个工作区列表。想换目录或合并工作区时，手改文件夹或 registry 很容易撞上三类实际问题：复制而非移动导致重复 sessionId、registry 指向已删除数据使整个工作区打不开、或在 DSH 运行时直接改 workspace.json 被内存中的 registry 覆盖。下面介绍社区插件 dsh-session-migration（维护者 Alvin070911），在会话头提供一个按钮，按 DSH 自身的存储约定做迁移、备份与健康检查。
这是什么¶
dsh-session-migration 是 DSH 客户端插件：在任意会话头部的 utilities 区出现一个图标按钮（双面板加箭头），打开迁移面板。它把整段会话的 log、header.cwd、工作区归属 一并迁到目标工作区或自定义目录，并附带会话浏览、一键导出备份、工作区健康检查。实现上只调用 DSH 自带服务，遵循「移动而非复制」、只改 frame 1、通过 live workspaceRegistry 写注册表等约定。当前 GitHub 星标为 0；package.json 版本为 0.1.0，许可证 MIT。
生态上，DSH 以「一切皆插件」组织能力；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
资料中列出的能力如下，写入正文前已与 README 对齐。
会话迁移¶
- 迁到已有工作区，或通过「custom path」浏览/输入任意目录。
- 先 preflight，再执行；自动备份、字节级校验、失败自动回滚，并输出可复制的手动回滚命令。
- 可选把源工作区 顶层文件/目录 一并挪到目标；若目标存在同名项则拒绝；源目录保留为空目录，以免同目录下其他会话失效。
- 当前正在使用的会话不能迁移自身（日志仍被打开，插件会拒绝）。
会话列表与健康检查¶
- 列表展示：id、工作目录、日志大小、frame 数、最后写入、当前归属、问题标记。
- 健康检查覆盖：悬空引用、重复 id、header 与目录不一致、空日志、工作区目录缺失、未注册会话等；其中 dangling-reference 可通过 live registry 一键清理，无需关闭 DSH。
导出备份¶
将 session 目录复制到你指定的目的地，并附带 migration-export.json 清单，不修改 registry。
安装与启用¶
安装命令以仓库 README 为准，不要用名称自行拼接 dsh plugin add。
本地目录（自托管常用）：
plugin_manager install_bundle target = C:\path\to\dsh-session-migration
从 GitHub：
plugin_manager install_bundle target = git+https://github.com/Alvin070911/dsh-session-migration.git
也可在 profile 的 cordis.patch.yml 中自行插入：
- insert:
- id: session-migration
name: dsh-session-migration
浏览器端由 dsh.client 声明自动加载。若按钮未出现，刷新页面一次——新装的客户端 bundle 需要页面重新遍历模块图。
插件在 cordis.patch.yml 中支持 config（默认值见下）。数据目录位于 <dshHome>/plugin-data/dsh-session-migration/（pending.json、自动备份、手动导出等）。
- id: session-migration
name: dsh-session-migration
config:
backupBeforeMove: true
keepBackups: 10
tryImmediateAttach: true
pendingApplyDelayMs: 2500
dshHome: ''
sessionsRoot: ''
dshHome 默认为 $DSH_HOME，否则 ~/.dsh；sessionsRoot 默认为 <dshHome>/sessions。
安装前建议在 GitHub 仓库 阅读源码与 MIT 许可证。插件以当前 DSH 进程权限访问会话与 registry，仅在可信环境安装。
典型用法¶
按 README 的可复现流程操作：
- 打开任意会话，在头部 utilities 找到迁移图标。
- 在左栏选择要迁移的会话（不能选当前正在使用的会话）。
- 选择目标工作区，或切换到「custom path」输入/浏览目录。
- 阅读 preflight：project-key 变化、目标 session 路径、是否会新建工作区、可选文件迁移的数量与冲突。
- 点击「Start migration」，再「Confirm migration」。
- 结果按步骤列出：backup → data move → header rewrite → verification → file move → workspace membership。
关于「需要重启」¶
工作区归属写入可能报告 pending-restart，这是设计行为而非失败：live workspace registry 是启动时从 session header 建的快照，插件无法在运行时原地刷新；运行中手写 workspace.json 属于资料中的 crash mode C。membership 会进入队列 ~/.dsh/plugin-data/dsh-session-migration/pending.json，在下次 DSH 启动后应用并写日志。一般只需重启一次，会话即出现在新工作区；「Pending」页也可尝试更早重试。
安全模型与日志处理（简要）¶
README 强调的不变量包括：只移动不复制；registry 仅通过 workspaceRegistry 且在数据就位后写入；只改 frame 1 的 cwd；frame 1 之后内容做完整性比对；重复迁到同一目标为 same-target 无操作；失败会回滚数据与 .bak，并打印回滚命令。
另一点对开发者重要：不要用 zlib.zstdDecompressSync(log) 当整文件解压——它通常只返回第一帧 header，误判为空会话可能删掉真实历史。本插件按 RFC 8878 走帧边界（必要时 magic 扫描），分块计帧，仅替换 frame 1。
手动回滚时，须在 DSH 完全退出 后按迁移输出中的命令操作；目录内 session.v4.jsonl.zstd.bak 是改写前的日志，DSH 不会把它当作正式代次。若要撤销排队中的 membership，还需从 pending.json 删除对应项。
适用场景与注意¶
适合： 需要把某段会话连同 cwd 与工作区归属迁到新目录；希望批量浏览会话、做 registry/磁盘一致性检查；迁前自动备份或单独导出备份。
注意：
duplicate-session、cwd-mismatch、id-mismatch、空/缺失日志等需按健康检查说明人工处理，不能一键修。- 可选「搬走源目录顶层文件」遇重名会直接拒绝。
- membership 变更常需一次 DSH 重启才在 UI 中完全体现。
结尾¶
dsh-session-migration 把「迁 session 目录 + 改 header + 改工作区注册」收成会话头的一个面板，并围绕 DSH 真实的三处绑定关系做了 preflight、备份与回滚。若你在多工作区、多目录间整理会话，可先装 bundle、刷新页面，再用健康检查摸清现场，再做单次迁移。
