会话镜像备份 Kadima-code/dsh-session-mirror

dsh-session-mirror

English: README.en.md

一个纯 host 的 DSH（DeepSeek Harness）插件：把每个对话各自备份成一份最新文件，支持按需恢复、按规则清理，并在源被删除时保留备份防误删。

- 版本：0.1.0 · 许可：BSD-3-Clause
- 形态：纯 host、零外部依赖（只用 Node 内置模块），无浏览器半 —— 不会崩应用
- 默认备份目录：E:\DshChatBackup

它管哪几件事

1. 增量备份：启动 / 每轮对话结束 / 关闭时自动备份；没变化的不重复拷，改了先拷临时文件、校验完整再原子替换。
2. 主 / 子识别 + 两份人读索引：《对话总览.md》目录树、《对话清单.md/html》详表（状态、主/子、对话长度、开启/结束/归档/删除时间、到期）。
3. 一键恢复：支持会话 ID 前缀、标题关键字、甚至只记得标题里跳着的几个字；先预览，加 yes 才真恢复。
4. 清理与到期回收站：手动清理子对话备份；可选「到期自动清理」——到期先进回收站，留 7 天再真删。
5. 安全兜底：只动备份不动原文件；坏帧绝不覆盖好文件；自动清理默认关闭。

快速开始（安装）

本插件是标准 bundle 插件，安装 = 包落地 + profile 登记 + 完全重启 DSH。

方式一：npm（发布后）

npm i @kadima-code/dsh-session-mirror

随后在 ~/.dsh/profiles/desktop/package.json 登记（见下方「profile 登记」）。

方式二：Release zip

把 zip 解压到 ~/.dsh/_plugins/dsh-session-mirror，再按下方登记。

方式三：本地目录 link

dependencies 里写 "@kadima-code/dsh-session-mirror": "link:<插件目录绝对路径>"。

profile 登记（~/.dsh/profiles/desktop/package.json）

{
"dependencies": {
"@kadima-code/dsh-session-mirror": "link:C:/Users/<你>/.dsh/_plugins/dsh-session-mirror" },
"dsh": {
"profile": {
"bundles": [
// …其它…
"@kadima-code/dsh-session-mirror"
]
}
}
}

⚠️ 改完必须「完全退出 DSH」再启动（关掉应用进程，不只是按 Ctrl+R 刷新页面）。插件代码是宿主侧加载，Ctrl+R 只换前端，不会加载新插件代码。

本包自带 cordis.patch.yml（由 package.json 的 dsh.bundle.patch 指向），加载器会自动挂载。

功能详解

1）备份

自动触发：DSH 启动后约 8 秒、每轮对话结束（去抖 8 秒）、DSH 关闭时各跑一次。没有固定定时周期。

增量规则：按「文件大小 + 最后修改时间」判断——没有备份就全拷一份；已备份但没变化就跳过；有变化才重新拷贝。

可靠性：每次先拷到临时文件 → 校验 zstd 帧完整 → 才原子替换正式文件。因此永远不会用半个文件盖掉好文件。

防误删：源里已删除的会话，备份保留并标记 orphaned（已删除）。

手动补一次：对话里说「备份一下」，或用「+ → 指令」菜单 mirror-backup。

2）主 / 子识别与两份索引

每个会话文件第一行是 session 头，含 origin / parentSession / delegationDepth。判定为子对话：origin === 'subagent' 或含 parentSession 或 delegationDepth > 0；否则为主对话。

插件在备份目录生成两份人读索引：

- 《对话总览.md》：工作区 → 主对话 → 子对话 的目录树，附标题、时间、大小、备份路径，标出 活跃 / 归档 / 已删除 / 置顶；子对话用 🧹 标「少用·可清理」。
- 《对话清单.md》（另出 对话清单.html 网页版）：13 列表格 —— 名字、状态、主/子、对话长度、大小、开启时间、结束时间、归档时间、删除时间、到期、备份时间、ID、工作区。

对话长度是复合指标：文件大小 + 我发消息条数 + AI 回复条数 + 最后活动时间/存活时长。超过 2MB 的大会话只解最后一帧取「最后活动时间」，避免逐条精算拖慢。

说明：开启/结束时间取自会话自带记录，准确；归档时间/删除时间只能是「插件第一次检测到」的时刻（DSH 本身不保存这两个时间），可能比你实际操作晚几分钟。

3）恢复

三种入口：

- 对话里说：「恢复对话：<标题里的字/词 或 ID 前缀>」
- 「+ → 指令」菜单：mirror-restore <字/词 或 ID> → 先预览；mirror-restore <字/词 或 ID> yes → 真恢复
- 命令行：node tools/restore.mjs（交互式）/ --list 只列可恢复的已删除主对话 / <查询> --yes；也可双击 tools\一键恢复.bat

模糊匹配：支持标题包含、跳字子序列（如「诗技」能对上「古诗词…技能」）、ID 前缀。命中唯一才自动选中；命中多个会把候选（名字·状态·ID 前 8 位）列出来让你再补字或报 ID，绝不乱猜。

恢复做什么：把该会话的备份文件拷回 ~/.dsh/sessions/<工作区>/<会话ID>/，并把会话 id 回填到 ~/.dsh/storages/workspace.json 对应工作区（若原为归档状态会自动取消归档）。回 DSH 按 F5 即可见。

安全：默认先预览（dryRun）；目标已存在不覆盖、只补登记。

4）清理与到期回收站

手动清理子对话备份：

- 对话里说「清理子对话备份」或菜单 mirror-clean（默认只预览，列出要清理的清单）
- 确认执行：菜单 mirror-clean yes，或命令行 node tools/clean.mjs --yes
- 清掉的会话 id 记入 _mirror-clean-skip.json，以后不再重新备份

到期自动清理（默认关闭）：打开后会按以下规则把到期的备份先移入 _回收站/，再留 7 天，之后才真删。

| 对象 | 规则 |
| 活跃的主对话 | 永不自动删 |
| 子代理 | 「子代理最后结束时间 距 主对话最后结束时间 > 3 天」才清（参照是主对话，不是当前时间） |
| 子代理（父主对话已被删除） | 父删日 + 7 天，取更早者 |
| 已删除的主对话 | 留 30 天（该条规则为可选项，默认未启用） |
| 归档的会话 | 不动 |
| 置顶 / 收藏 | 不参与判断（判断只看标记） |

开关：存在文件 _mirror-autoclean.on，或配置 autoClean: true。关闭状态下只做标记与统计，绝不删除任何东西（回收站也不动）。

5）安全与已知限制

- 只动备份，不碰原文件：所有删除都发生在 E:\DshChatBackup 内。
- 坏帧保护：拷贝前校验 zstd 帧完整性，不合格的副本会被丢弃并保留旧副本。
- 两阶段删除：到期先进 _回收站，留 7 天再真删，中途可反悔捞回。
- 自动清理默认关闭：需你显式开启才执行。
- 已知限制：
- 归档时间 / 删除时间是「插件第一次检测到」的时刻，不是精确操作时间；
- 大文件（>2MB）的对话长度只按最后活动时间近似；
- DSH 内核升级后，建议先跑一次回归（备份 / 恢复 / 清理各一次）再长期使用；
- 子对话备份清理后，若源仍在，会记入 skip 名单不再备份（避免反复备份-清理）。

配置（profile 层传 config）

| 键 | 默认 | 说明 |
| enabled | true | 关闭后插件不执行任何备份 |
| dest | E:\DshChatBackup | 备份根目录 |
| verbose | false | 是否在日志里输出每份明细 |
| autoClean | false | 是否开启到期自动清理（也可用 _mirror-autoclean.on 开关） |

备份目录里有哪些东西

E:\DshChatBackup\
sessions\ 每个对话的备份，目录结构与 ~/.dsh/sessions 一致 _mirror-state.json 每份备份的状态（大小/时间/主或子/标题/是否已删除/指标） _mirror.log 每次运行记录（超 5MB 自动轮转为 _mirror.log.1）怎么恢复.txt 中文恢复说明（首次运行写入）对话总览.md 人读目录树对话清单.md / .html 人读详表（13 列）待清理子代理名单.html/txt 清理预览清单子对话清理对照表.html 全部子对话 vs 符合规则的红黑对照 _回收站\ 到期备份先进这里，留 7 天再真删（含 _manifest.json） _mirror-autoclean.on 自动清理开关（存在=开） _mirror-clean-skip.json 已清理、不再重新备份的会话 id

命令与工具速查

| 场景 | 对话工具 | 「+ → 指令」菜单 | 命令行 |
| 立即备份 | session_mirror_now | mirror-backup | — |
| 恢复 | session_mirror_restore | mirror-restore <查询> [yes] | tools/restore.mjs |
| 清理子对话 | session_mirror_clean | mirror-clean [yes] | tools/clean.mjs [--yes] |
| 查看到期 | — | — | tools/clean.mjs --expiring |
| 自动清理开关 | — | — | tools/clean.mjs --auto-on / --auto-off |
| 清空回收站(超7天) | — | — | tools/clean.mjs --purge |

「+ 菜单」命令名只能是英文小写；需要参数的命令在命令后跟参数即可（如 /mirror-restore 作图）。

开发说明

- 纯 host ESM，零外部依赖，无需构建；lib/index.js 即全部逻辑。
- 依赖 DSH 的两个契约：ctx.tools.register(spec): Promise<void>；ctx.get('commands').register({name, description, handler})，其中 handler 必须返回 CommandResult 对象 {kind:'success'|'error', text}（返回裸字符串会报错）。

License

BSD-3-Clause。见 LICENSE。