会话迁移 yvban/dsh-session-mover

dsh-session-mover

把 DSH 会话从一个工作区安全搬到另一个工作区，保留可续聊的完整历史。
在工作区之间安全迁移 DSH 会话 —— 帧级 zstd 头部改写，字节级校验。

一个 DeepSeek Harness（DSH）插件：在 设置 → 会话迁移 里选目标工作区、选会话、点一下，就把会话搬过去，归属即时更新、无需重启。

为什么需要它

DSH 的会话日志是多帧 zstd，并且有一条硬性约定：第 1 个帧必须只包含 header 那一行，其余每帧独立可解码（带 checksum）。DSH 读取时用 assertZstdHeaderFrame 校验，不满足就抛 SessionPersistenceCorruptionError，而会话枚举会静默跳过这条日志 —— 表现就是：

迁移完成后，那个对话在侧边栏里彻底消失（文件其实完好）。

手工改 header 时最容易踩的两个坑：

1. 把整份日志一次性重压。改完 cwd 后重压全文，会把「头部帧 + 上千个事件帧」塌缩成单个帧，正好触发上面那条校验。
2. 硬编码日志文件名。文件名带格式世代号：v0 叫 session.jsonl.zstd，vN(N>0) 叫 session.vN.jsonl.zstd。硬编码 v0 名字的实现，在较新的 DSH 上会一个会话都定位不到（实测 0/31）。

本插件按帧处理、按目录里实际存在的世代解析文件名，从根上避开这两个问题。

功能

| 能力 | 说明 |
| 迁移会话 | 设置 → 会话迁移：选目标工作区 → 选会话 → 迁移 |
| 按标题认会话 | 列表显示会话标题（与侧边栏同源），并标出它当前属于哪个分组；支持按标题 / 路径 / ID 过滤 |
| 帧级改写 | 只重压第 1 帧（header，写入新 cwd），body 帧字节原样保留 |
| 字节级校验 | 帧数不变 + 每个 body 帧逐字节比对 + 头部 id/cwd 核对；不做全量解压，大日志也不吃内存 |
| 整目录备份 | 迁移前把整个会话目录 + manifest.json 备份到 <DSH_HOME>/storages/session-mover-backup/<id>/<时间戳>/ |
| 拒绝覆盖 | 目标工作区已有同 id 会话时直接拒绝，不动原会话 |
| 事务性 | 先写临时文件并校验，通过后才 rename；任何一步失败都会清掉半成品 |
| 归属热更新 | 通过官方实体 API（WorkspaceEntity.attachSession / detachSession）更新分组，无需重启 |
| 帧结构修复 | 已经被"整份重压"搞坏、在界面里消失的会话，可以就地修复（修复前自动备份） |

标题从哪来

标题有两个来源，按"快 → 准"的顺序取；取不到只是不显示，绝不影响迁移：

1. 投影缓存（快）：<DSH_HOME>/storages/session_projcache/sessions/<id>.json 里的 record.rows.title.val。本机实测覆盖 22/31 个会话。缓存只是显示提示，可能滞后于日志。
2. sessionQuery.readTitleSnapshots()（准）：官方公开服务，从日志里折叠标题事件。
只对缓存里没有标题的会话调用，避免每次打开面板都全量读日志。

分组列来自 workspaceRegistry.list() 的成员关系；没有归属的显示为「未分组」。

安装

有 git（标准写法）
dsh plugin --profile <你的 profile> add github:yvban/dsh-session-mover#main

没有 git：pnpm 解析 github: 依赖需要 git，可以改用归档 tarball 的 URL
dsh plugin --profile <你的 profile> add https://github.com/yvban/dsh-session-mover/archive/refs/heads/main.tar.gz

<你的 profile> 通常是 web；桌面版是 desktop。如果 PATH 里没有 dsh，用应用自带的 CLI：

& '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add github:yvban/dsh-session-mover#main

装完重启 DSH（客户端面板在启动时加载），然后打开 设置 → 会话迁移。

使用

1. 目标工作区：下拉里选一个已注册的工作区。
2. 选中会话：列表按创建时间倒序，每行显示标题 / 当前分组 / 原始 cwd / 体积 / 会话 ID。
- 打开中 的会话不能迁移（日志被写句柄占着）。
- 标了 帧结构异常 的会话先用「修复帧结构」，修完重启 DSH 就会重新出现。
3. 迁移选中会话：完成后归属即时生效，不用重启。

HTTP 接口（面板用的就是这三个）

| 方法 | 路径 | 说明 |
| GET | /plugins/dsh-session-mover/state | 工作区清单 + 会话清单（含 readable / live / title / 分组） |
| POST | /plugins/dsh-session-mover/migrate | { sessionId, targetWorkspaceId } |
| POST | /plugins/dsh-session-mover/repair | { sessionId } |

两个 POST 需要 x-dsh-session-mover: session-mover 头，并通过 Host 的本机同源校验；跨站请求会被拒。

已知边界

- 正在 DSH 里打开的会话不能迁移（日志被写句柄占着），返回 409。请先关掉那个会话。
- 热更新归属只用到一个非公开方法：workspaceRegistry.indexHeader()。attachSession 会用内存里启动时缓存的头部索引校验 cwd，文件搬走后该索引过期，必须先刷新它。这一点无法用公开 API 替代。若该方法在某版本不存在，插件会自动退回「直写 workspace.json」并提示需要重启；再不行就只搬文件，重启后手动把会话拖进目标分组。
- 迁移不会改动 defaultWorkspaceId，也不会动别的会话。
- 只用 Node 内置模块，无第三方运行时依赖。

开发与测试

node --check lib/migrate.js
node --check lib/index.js
node --check lib/client.js
node tests/unit.mjs # 12 项
node tests/host.test.mjs # 10 项

覆盖内容：

- 路径编码（projectKey / encodeSegment）与真实 sessions 目录名逐字一致（含中文路径）；
- 合成多帧 fixture 的完整迁移：header 改写、body 帧逐字节不变、旧目录删除、备份与 manifest；
- 世代感知定位：v0 与 vN 两种命名都能定位并沿用同名迁移；文件名世代与 header.version 不一致时判定为不可读；
- 单帧塌缩（历史上导致会话消失的那个 bug）的检测与修复，修复后内容零丢失且幂等；
- no-overwrite、迁移到同工作区的 no-op、日志位置与头部 cwd 不符时拒绝；
- host 集成测试：用模拟 ctx 真实跑通 apply() → 路由注册 → 鉴权（跨站 403、缺确认头 403）→ 迁移成功（attach/detach/indexHeader 调用与文件落位都有断言）→ 打开中的会话 409 → 修复入口；
- 标题优先级：缓存命中直接用，缓存缺失才查 sessionQuery，并断言命中过的不会重复查；
- 归属更新必须被证实：模拟上游 attachSession 静默无效（成员被 canonical-cwd 过滤丢掉）时，插件必须报 disk 而不是 hot，并如实说明需要重启——避免「报成功但侧边栏没有」；
- 真实 DSH 会话根目录的只读回归（本机 31/31 可定位、可读；没有真实目录时自动跳过）。

License

MIT