# 回退标记更新指南

> [English](rewind-fix.md) | 中文

## 适配

- **DSH 版本**：`v0.1.2-rc.1`。
- **插件版本**：`v0.9.0-alpha.1`，`v0.9.0-alpha.2`，`v0.9.0`，`v0.9.1`（推荐）。
- **适用人群**：计划使用未来版本 DSH，且使用过早期版本插件（≤ 0.8.0）的用户。

## 背景

`dsh-rewind` 的回退是**同一会话**的消息回退。它从不新建分支，会话日志保持同一份。插件遵循保守策略：不删除任何历史，只在会话日志里**追加一条 rewind 标记**，表示“模型可见的对话从这条消息继续，其后内容回卷”。旧版插件的 **rewind 标记**用的是「幽灵步骤框架」写法，在 DSH `v0.1.2-rc.1` 及之前的版本长期验证有效。

但从 `v0.1.3-alpha.1` 开始，DSH 引入了更严格的**会话格式校验**。我们提前发现：旧版本往会话日志里写入的 **rewind 标记**，在这种严格校验下**无法自证合法**，届时会导致**回退过的旧会话打不开**。

插件做了两阶段准备，已在新版本中包含：

1. **新产生的 rewind 标记换成新格式**（向前）——这一步是**正确、低风险**的长期改动（对标官方 `/compact` 设计，见 [README](../README.md)「原理」一节），新格式对**新旧版本** DSH 均完全兼容。

2. **提供 `/dsh-rewind-fix` 命令**（向后）——对于**已经存在**的旧会话，本插件提供便捷更新命令，把旧标记「翻译」成新格式，让会话重新可用。

本文档主要讲解**更新命令**的使用方法。

## 警告

1. **会直接编辑会话日志** —— 把旧回退标记更新为新格式。设计上对**多个网页窗口、退出重启、切换会话、关机断电**等场景都已做安全处理：只处理**已关闭**的会话，写前加锁+备份、失败自动回滚、可重复运行（**幂等**）；只动标记本身，不删任何对话内容、**无信息丢失**。

2. **会重置对应的快照备份** —— 格式更新会改变事件序号，**被更新过的会话**，其用于「回退对话和代码」时**还原文件**的对应快照备份将不再匹配，因此会被插件**清除**。这只影响**文件还原**，备份会重新开始记录；没被更新的会话快照不变。

## 操作步骤

### 第一步 · 确认版本

先确认你当前的 DSH 与插件版本落在「适配」范围里——这是前提。版本不符时，工具可能不可用或行为不符。你可以直接问 AI「当前的 DSH 与 dsh-rewind 插件版本」，并确认是否在「适配」范围内。

### 第二步 · 手动备份（可选）

命令会改写会话文件、删掉部分快照，稳妥起见先备份一下。默认数据目录是 `~/.dsh`（若你设置了 `$DSH_HOME`，请用它的值）：
```sh
cp -r ~/.dsh/sessions          ~/.dsh/sessions.backup
cp -r ~/.dsh/rewind-snapshots  ~/.dsh/rewind-snapshots.backup
```
或者复制到任意合适的位置。你也可以直接让 AI 帮你完成数据的备份。

### 第三步 · 新建会话，或选一个从未回退过的会话

命令只处理已关闭的会话，而且不能在自己身上运行——建议你：
- **新建一个会话**，先随便发一条消息初始化窗口，确保能看到命令执行过程和结果
- 选择一个**从未回退过**（不需要更新）的会话

然后在**这个新会话窗口里**运行命令，去更新那些需要处理的旧会话。

> 别在「本身就需要更新、且正开着」的会话里运行——命令会跳过本会话，以及任何正被打开/使用的会话。

### 第四步 · 预览更新范围

在编辑区域输入 `/dsh-rewind-fix` 并发送。它只扫描、不写盘。执行时编辑区会正常锁定。**不要中途切换会话窗口**。完成后会告诉你：扫描了几个会话、其中几个将被更新、几个跳过、几个失败。确认是你预期的那几项，再进下一步。
```
/dsh-rewind-fix
```

### 第五步 · 执行

确认无误后，重新输入命令并加 `--apply` 真正执行：
```
/dsh-rewind-fix --apply
```
这一步会真的改动会话日志、把旧标记更新成新格式，**可能需要几分钟**。请耐心等它跑完，**不要中途切换会话窗口**或关闭 DSH——被切到的会话会被**安全地跳过**（不损坏，但这次不会更新，需重新执行）。更新失败的会话保持原状态不变、无破坏，可重新进行更新。被更新的会话会同时**清掉对应的文件快照备份**，更早消息回退时文件还原不可用。

### 第六步 · 重启 DSH，再预览确认

执行完后重启一下 DSH，然后**再跑一次预览**：
```
/dsh-rewind-fix
```
如果提示已经没有待更新的会话，说明标记已全部更新到位，旧会话就能正常打开了。如果还有未更新的会话，可能是执行时被加载过，在临时会话窗口重启并重试即可。

### 第七步 · 确认正常后删除备份（可选）

继续使用一段时间，确认一切功能正常后，删掉第二步拷贝的备份即可：
```sh
rm -rf ~/.dsh/sessions.backup ~/.dsh/rewind-snapshots.backup
```

## 补充说明

- 当前会话日志仍为 v0 格式；DSH 后续的 `v0 → v1 → v2 → v3` 迁移到来时，如果你完成了 `rewind` 标记更新，标记本身就不会阻断它。
- 个别会话还可能因**未闭合的 turn**（某次回合被打断/取消、没写 `turn/end`）等问题而卡住迁移——根据实测分析，这些问题普遍存在，**与 rewind 无关**，属 DSH 侧自身问题，本工具不处理。**所以更新完标记并不保证一定能升到下一 DSH 线。**