dsh-rewind-plugin 0.8.0-alpha.1 → 0.9.0-alpha.2

package/docs/rewind-fix.zh.md

@@ -0,0 +1,88 @@
+# 回退标记更新指南
+
+> [English](rewind-fix.md) | 中文
+
+## 适配
+
+- **DSH**：`0.1.2-rc.1`
+- **dsh-rewind**：`0.9.0-alpha.1`
+
+## 背景
+
+`dsh-rewind` 的回退是**同一会话**的消息回退。它从不新建分支，同时遵循保守策略：**不删除任何历史**（会话日志是 append-only 审计轨迹），只在日志里**追加一条标记**，表示“模型可见的对话从这条消息继续，其后内容回卷”。旧版插件的 **rewind 标记**用的是「幽灵步骤框架」写法，在 DSH v0.1.2-rc.1 及之前版本长期验证有效。
+
+但 DSH v0.1.3（alpha）引入了更严格的**会话格式校验**。我们提前发现：旧版本往会话日志里写入的 **rewind 标记**，在这种严格校验下**无法自证合法**，届时会导致**碰过 `/rewind` 的旧会话打不开**。
+
+插件做了两阶段准备，已在新版本中包含：
+
+1. **新产生的 rewind 标记换成新格式**（向前）——这一步是**正确、低风险**的长期改动（见 [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
+```
+或者复制到任意合适的位置。
+
+### 第三步 · 新建会话，或选一个从未回退过的会话
+
+命令只处理已关闭的会话，而且不能在自己身上运行——建议你：
+- **新建一个会话**，先随便发一条消息初始化窗口，确保能看到命令执行过程和结果
+- 选择一个**从未回退过**（不需要更新）的会话
+
+然后在**这个新会话窗口里**运行命令，去更新那些需要处理的旧会话。
+
+> ⚠️ 别在「本身就需要更新、且正开着」的会话里运行——命令会跳过本会话，以及任何正被打开/使用的会话。
+
+### 第四步 · 预览更新范围
+
+在编辑区域输入 `/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.1.3`）的 `v0 → v1 → v2` 迁移到来时，如果你完成了 `rewind` 标记更新，标记本身就不会阻断它。
+- 个别会话还可能因**未闭合的 turn**（某次回合被打断/取消、没写 `turn/end`）等问题而卡住迁移——根据实测分析，这些问题普遍存在，**与 rewind 无关**，属 DSH 侧自身问题，本工具不处理。**所以更新完标记并不保证一定能升到下一 DSH 线。**

package/lib/client.js

@@ -1333,7 +1333,7 @@ function createRewindBridge(deps) {
 }
 
 // src/client/build-info.ts
-var PLUGIN_VERSION = true ? "0.8.0-alpha.1" : "dev";
+var PLUGIN_VERSION = true ? "0.9.0-alpha.2" : "dev";
 var BUILD_HASH = true ? "ca24fc4e" : "dev";
 
 // src/client/locales.ts