数据迁移

DSH 设置 → FileSnap → 数据迁移 是各版本共用的入口。选择任务，点击“扫描旧版数据”，检查会话清单，再点击确认。关闭设置不会撤销已经完成的文件迁移；如中断，重新扫描即可判断剩余工作。

从 0.3.1 起，插件加载时默认自动执行注册的迁移任务（autoMigrate: true）。已兼容数据跳过；正在使用的会话留待下一次启动或手动重试。设置页展示本次启动的内存结果，不向对话追加自定义操作日志。共享同一日志目录的多个 DSH 进程应先停止其他实例，或设置 autoMigrate: false 后统一手动迁移。

branch-status-titles-v1 将会话自身最新的旧 ↩ 标题转为 🔴 Inactive ·，通过追加 DSH 原生 session/title 事件完成，保留既有事件与分支边界。没有可靠状态信息的普通标题不会被推测为 Active；之后成功的回退与 redo 会设置两端的红绿灯状态。

本版任务#

legacy-session-events-v1：旧版插件及早期预览版 → 0.3.0+ 的会话兼容迁移。

旧版把 filesnap/point、filesnap/rewound、filesnap/redone 写进会话，早期文件预览版还写入 filesnap/reply。宿主在插件缺席时可能拒绝这些未知事件。迁移为这些历史事件补上 ignorable: true，不改变消息、序号、分支继承边界或其他插件的事件。旧记录保留是为维持已有引用；本版不会继续写这些事件，也不会另外保存操作流水。

扫描当前宿主持久化服务中的会话，只支持 JSONL 与 .jsonl.zstd 后端。手动扫描不写文件；启动时的自动任务会继续执行带备份的迁移。清单包含待迁移、已加载、失败和不支持的项目；本来就兼容的会话自动跳过。

确认与备份#

• 确认令牌五分钟有效，只能使用一次。确认时再次核对文件摘要，扫描后变化的日志要求重新扫描。
• 已加载会话不迁移。关闭后重新扫描；如果仍占用，重启 DSH 后先打开设置。迁移期间也会阻止目标会话被同时加载。
• 每份修改过的日志旁保留 .before-filesnap-migration-<id> 原始备份。先写临时文件并同步，再原子替换。
• Zstd 日志保留独立的头部压缩帧；不会把多帧日志当成一段文本截断。
• 每个会话单独报告成功、跳过或失败。成功后可再次扫描验证；已完成的任务是幂等的。
• 如需回滚，先停止使用该存储的 DSH，再用所报告的备份替换对应原文件。不要在宿主运行时手工覆盖日志。

后续版本如何接入#

迁移任务统一注册在 src/migrations.ts。每项有稳定任务 id、适用来源/目标版本和幂等变换函数。新增版本迁移复用同一个界面的任务列表、扫描、确认、备份及结果流程，不另加散落按钮。

目前执行器处理独立的会话 JSONL 文件；未来若迁移快照引擎格式或其他存储后端，需要为该数据源增加相应的适配和验证，不能把它冒充成会话日志修复。

界面无法启动时#

本包还带独立的离线修复工具，不需要加载插件即可处理旧会话。先停止所有使用同一会话目录的 DSH 进程。--root 是 DSH 会话日志目录，不是 FileSnap 快照目录。

node lib/migrate-session-logs.js --root /path/to/dsh/sessions
node lib/migrate-session-logs.js --root /path/to/dsh/sessions --write --dsh-stopped

第一条只扫描，第二条备份并修复。工具位于已安装插件的 lib/ 下；也可以在源码仓库运行 npm run build 后执行。