dsh-session-migrate
DSH 会话日志跨版本迁移——把低版本 generation（v0 等）投放到当前实例可识别的位置，
由 DSH 在打开该日志时沿迁移边自动还原到当前格式版本。
为什么需要它
DSH 会话日志格式是预发布格式，随 harness 版本演进（v0 → v1 → v2 → v3）。
官方不提供迁移命令，但持久化层在打开日志时会沿迁移边串行还原。
本插件负责「安全投放」，迁移本身交给 DSH——这样格式再演进也不会过期。
核心机制
转换一条会话需要两步，缺一不可：
| 步骤 | 动作 | 说明 |
|---|
| ① 投放 | 写入 sessions/--<cwd编码>--/<id>/session.jsonl.zstd | 改写 header.cwd，只重建首帧 |
| ② 触发 | WebSocket session/follow | 只有这步才会真的产出 vN 文件 |
实测对照（决定了为什么必须有 ②）：
| 动作 | 是否触发迁移 |
|---|
session/list（HTTP） | ✗ |
session/page（HTTP 冷读，能读出内容） | ✗ |
session/follow（WebSocket 流式） | ✓ lock 与 vN 立刻落盘 |
功能
| 能力 | 入口 | 说明 |
|---|
| 旧会话扫描 | legacy.js | 扫描 session.old/，读出 id / 版本 / cwd / 帧结构 |
| 体检与迁移路径 | GET /check | 首帧契约、帧数、目标版本能力、v0→v1→v2→v3 规划 |
| 工作区探测 | GET /workspaces | 候选工作区列表 |
| 导入 | POST /import | multipart 上传或 JSON {paths}；支持 .jsonl / .jsonl.zstd / .zip |
| 转换 | POST /convert | 投放 + 触发迁移，可传 trigger:false 只投放 |
| 布局修复 | POST /fix-layout | 移出 sessions/ 下非法裸目录（否则工作区列表全空） |
| 转换去重 | POST /convert 内置 | 转换时按会话 id 全工作区查重：同 id 已存在于其它工作区则提示并移出旧份备份（可恢复），重新转换到本次目标工作区，杜绝「一个会话两次恢复到不同工作区」 |
| CLI | node cli.mjs | list / check / fix / import，可脱离 DSH 独立运行 |
用法
CLI
node cli.mjs list <DSH_HOME> # 列会话与布局问题
node cli.mjs check <文件> [--home <DSH_HOME>] # 单文件体检（含目标版本与迁移路径）
node cli.mjs fix <DSH_HOME> # 移出 sessions/ 下非法裸目录
node cli.mjs import <源文件|源目录> <DSH_HOME> # 双路径导入（含 subagents）
node cli.mjs import <源> <DSH_HOME> --cwd <cwd> # 指定目标 cwd
HTTP
curl -s localhost:30801/api/session-migrate/state
curl -s 'localhost:30801/api/session-migrate/check?file=<会话文件绝对路径>'
curl -s -X POST localhost:30801/api/session-migrate/convert \
-H 'content-type: application/json' \
-d '{"ids":["session-xxx"],"cwd":"/path/工作区/测试","trigger":true}'
两个必须避开的坑
坑 1｜备份放错位置 → 工作区列表全空
sessions/ 根下只允许 --<cwd编码>-- 形式的目录。放任何裸目录会让 DSH 报
uses the unsupported flat-file layout，表现为工作区列表为空。
所有备份一律放 <home>/../session-backups/（home 之外）。
坑 2｜zstd 整体重压缩 → 会话读取失败
v0 布局是每行一个独立 zstd frame，且首帧必须正好是 header 那一行。
「解压→改→重压」会合并成 1 帧，DSH 报
corrupt Zstandard session log: first frame is not exactly one header line。
正确做法：只重建首帧，其余字节原样拼接。
目录结构
cli.mjs 命令行入口（零依赖，可独立运行）
assets/
preview-gen.mjs 预览页生成器（跑真实 lib/client.js，垫片宿主环境；--serve 起局域网静态服务器）
preview.html 生成物：单文件自包含预览页（内联 React/ReactDOM UMD + 假数据接口）
lib/fixture.mjs 预览用假数据（/state 响应体，覆盖各状态分支）
lib/serve.mjs 局域网静态服务器（只读托管 assets，拦截路径穿越）
lib/
index.js 插件唯一入口（工具注册 + 系统提示词 + HTTP 接线）
client.js 设置侧边栏页面（浏览器半侧，四个分区）
routes.js HTTP 接口编排
follow.js WebSocket 触发迁移（Node 实现，无需 Python）
legacy.js 旧会话扫描与索引
workspace.js 工作区候选探测
i18n/{zh,en}.json 外置多语言字典
engine/ 迁移引擎（帧 / 布局 / 版本 / 导入 / 体检）
zstd.js 帧级读写与首帧契约
zip.js 最小 zip 解包（导入时把导出包解开成标准目录形式）
layout.js cwd 编码、目标路径推导、布局校验
target.js 版本探测与迁移边规划（不硬编码版本号）
import.js 投放（跨工作区去重 + 备份 + 转码 + 重建首帧 + 子会话）
inspect.js 体检与布局修复
test/
test-client.mjs client 契约自测（模块装配 / 槽注册 / 同步文案）
浏览器半侧与官方约定一致：入口声明在 package.json 的 exports["./client"]
（值为 ./lib/client.js），与 @deepseek-ai/dsh-client-* 系列插件同构——DSH 客户端
模块系统按该子路径解析并聚合，不走顶层散落文件。
每项能力只有一份实现：版本探测统一走 engine/target.js，帧读写统一走
engine/zstd.js，触发迁移统一走 follow.js（Node）。
界面预览
assets/preview-gen.mjs 生成一个单文件自包含的界面预览页：它加载仓库里真实的
lib/client.js（不是另写的 mockup），只垫片宿主环境（__ModuleLoader__ / require /
locale / slots / fetch），因此界面与真实插件一致，也能暴露真实渲染与交互缺陷。
node assets/preview-gen.mjs # 生成 assets/preview.html
node assets/preview-gen.mjs --serve # 生成并用局域网静态服务器托管（默认端口 8099）
PORT=8080 node assets/preview-gen.mjs --serve
生成物内联 React 与 ReactDOM 的 UMD 构建，双击即开、离线可用，不需要 DSH 在运行。
预览页里的数据是假的（覆盖待转换 / 已转换 / 不可迁移 / 不可读 / cwd 越界各分支），
勾选、选工作区、导入、转换都可点，改动只留在页面内，不写任何文件。
React 的 UMD 从 DSH 安装根的 pnpm store 取；ReactDOM 常未随 DSH 安装，生成器会依次
查 DSH 数据目录下的 cache/react-umd/ 与 /tmp/rd/，都没有时按提示下载即可：
mkdir -p /tmp/rd/umd && curl -sSL -o /tmp/rd/umd/react-dom.development.js \
https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js
DSH_ROOT / REACT_UMD_DIR / REACT_DOM_UMD_DIR 可显式覆盖查找结果。
设置侧边栏
lib/client.js 挂载「设置 → 侧边栏 → 会话迁移」，四个分区：
| 分区 | 作用 |
|---|
| 环境 | 目标版本 / 旧会话目录 / 工作区根 / 待转换计数，含布局异常告警 |
| 导入 | 选择 .zip / .jsonl / .jsonl.zstd 上传到 session.old/ |
| 列表 | 扫描 session.old/，显示 cwd / 版本 / 已转换版本 / 大小，可勾选 |
| 转换 | 选目标工作区 → 投放选中项（改写 cwd），随后由 DSH 读取该条记录时迁移 |
注册方式：客户端 inject 声明 slots，在 settings.section 槽注册条目
（{ name, id, order, label } + 页面组件）。词条经宿主
GET /api/session-migrate/i18n 拉取，源码只保留首屏所需的同步兜底。
版本记录
| 版本 | 日期 | 变更 |
|---|
| 1.0.3 | 2026-09-20 | 全量审计清理（独立 CLI git-sluice 口径：warning 121 → 19，评分 77.5 → 83.5）。引擎与 HTTP 侧 I/O 隐患清除：follow.js token 探测改「readdirSync 一次性收进内存集合、循环内零 I/O」，WebSocket 连接拆 bindSocketLifecycle / attachSocketEvents / withHandshakeContext，快照等待拆 waitForSnapshot，静默收尾统一 endQuietly / destroyQuietly / closeQuietly；routes.js 请求体读取改 for await 异步迭代（IncomingMessage 原生可迭代，消 Promise 手动嵌套）；预览静态服务器 serve.mjs 改 fs/promises（stat + readFile），请求处理拆 handleRequest；client.js 设置分区注册拆 injectSection、CSS 行高 / 字重提为 CSS_LINE_HEIGHT / CSS_TITLE_WEIGHT 常量；index.js 工具注册拆 registerTools、列表格式化拆 formatSessionList；预览生成器 CSS 字号 / 白色通道提 PREVIEW_LINE_HEIGHT / CSS_WHITE_CHANNEL 常量。lib/client.js 加入 .auditignore（单文件入口架构的固有行数 / 嵌套不入审）。 |
| 1.0.2 | 2026-09-19 | 修复 .zip 导出包导得进、列不出、转不了：导入接口接受 .zip，但旧会话扫描只认 .jsonl / .jsonl.zstd，两者口径不一致，zip 落盘后扫描不到，/convert 会以「会话不在列表里」失败。改为导入时即解包成标准目录形式 <会话id>/session.jsonl，后续列表 / 转换全走既有路径。新增 lib/engine/zip.js：零依赖最小解包（只用 node:zlib），走中央目录定位数据——导出工具常在本地头把长度写 0 并改用 data descriptor，照本地头解析会得到 0 长度而解不出内容；条目名统一剥成基名挡路径穿越，解压后校验体积上限挡 zip 炸弹。导入语义统一为「同名覆盖 + 覆盖前留底」（原先会另起带时间戳的新目录，导致同一会话在列表里出现多条）；扫描跳过 *.before-import-* 留底目录并按会话 id 去重。另：转换内置全工作区去重——同一会话 id 已存在于其它工作区（不同 cwd 目录）时，提示并把旧份整体移出到 session-backups/（可恢复，非物理删除），再转换到本次目标工作区，杜绝「一个会话两次恢复到不同工作区」的重复副本；CLI import 与 /convert 均生效。 |
| 1.0.1 | 2026-09-19 | 浏览器半侧 lib/client.js 内部整理（不拆文件、不引入构建链——DSH 只读 exports["./client"] 的单文件，官方插件同样是「源码分多文件 + 打包成单文件」，行数由段落注释与小函数承担）。消除两份事实来源：源码内联的 14 个词条兜底删去，只保留首屏同步渲染必需的 settings.title / common.loading，权威字典统一为 lib/i18n/{zh,en}.json（各 62 键，实测覆盖代码用到的全部 45 键）；renderStatus 拆为 renderStatusHeader / renderStatusGrid / ； 里的槽注册抽成 / ， 从 5 层嵌套降为平铺；ID 截断长度 20 / 12 提为 / 命名常量。修 TDZ 隐患： 从文件中部移到末尾，原先依赖函数提升、若 factory 被同步调用会命中常量 TDZ。 |
许可
MIT
