dsh-rewind-plugin 0.15.0 → 0.15.1

package/docs/rewind-fix.md

@@ -1,89 +0,0 @@
-# Rewind-marker update guide
-
-> English | [中文](rewind-fix.zh.md)
-
-## Applies to
-
-- **DSH version**: `0.1.2-rc.1`.
-- **Plugin version**: `v0.9.0-alpha.1`, `v0.9.0-alpha.2`, `v0.9.0`, `v0.9.1` (recommended).
-- **Audience**: users planning to use a future DSH version who used an early plugin (≤ 0.8.0).
-
-## Background
-
-`dsh-rewind` rewinds **within the same session** — it never forks a branch, and the session log stays the single source. The plugin follows a conservative policy: it deletes no history, and only **appends a rewind marker** telling DSH "the model-visible conversation continues from this message; everything after it is rolled back". Older plugin versions wrote that **rewind marker** as a "ghost step frame", which worked reliably on DSH `v0.1.2-rc.1` and earlier.
-
-But starting with DSH `v0.1.3-alpha.1`, a stricter **session-format validation** is introduced. We discovered ahead of time that the **rewind markers** written by older plugin versions **cannot be validated** under those stricter checks, so **a session that was rewound may fail to open**.
-
-The plugin is prepared in two parts, both shipped in the new version:
-
-1. **New rewind markers use the new shape** (forward) — this is a **correct, low-risk**, long-term change aligned with the official `/compact` design (see the [README](../README.en.md), the "How it works" section), and the new shape is fully compatible with **both old and new** DSH.
-
-2. **The `/dsh-rewind-fix` command** (backward) — for **already-existing** old sessions, the plugin shipped an update command (removed in plugin `0.10.x`) that translated those old markers into the new shape so the sessions were usable again.
-
-This document covers mainly the **update command**.
-
-## Warnings
-
-1. **It directly edits the session log** — it rewrites old rewind markers into the new format. The design already handles the common cases safely (**multiple web windows**, **exit / restart**, **switching sessions**, **power loss**): it only touches **closed** sessions, locks and **backs up** each one before writing, **rolls back** on failure, and is **idempotent** (safe to re-run). It changes the marker only — it deletes no conversation content and **loses no information**.
-
-2. **It resets the matching snapshot backups** — the format update renumbers event seqs, so a session that was **updated** has its snapshot backups (the lightweight backups used to **restore files** for "conversation and code") no longer match, and the plugin **clears** them. This only affects **file restore** (those sessions can't use snapshots to restore files); backups start recording fresh. Sessions that weren't updated keep their snapshots.
-
-## Steps
-
-### Step 1 · Confirm your versions
-
-First confirm your DSH and plugin versions are in the "Applies to" range — it's a prerequisite. If either is out of range, the tool may be unavailable or behave differently. You can just ask the AI for your current DSH and dsh-rewind plugin versions and check they're in range.
-
-### Step 2 · Back up manually (optional)
-
-The command rewrites session files and clears some snapshots, so a backup is a good idea. The default data directory is `~/.dsh` (if you've set `$DSH_HOME`, use its value):
-```sh
-cp -r ~/.dsh/sessions          ~/.dsh/sessions.backup
-cp -r ~/.dsh/rewind-snapshots  ~/.dsh/rewind-snapshots.backup
-```
-Or copy them anywhere convenient. You can also let the AI run the backup for you.
-
-### Step 3 · Start a new session, or pick one that was never rewound
-
-The command only handles **closed** sessions, and it can't run on itself. So:
-- **Start a new session** — ideally send any message first to initialize the window so you can see the command's progress and output.
-- Or pick a session that was **never rewound** (one that needs no update).
-
-Then run the command **in this new session**, and it will update the old sessions that need it.
-
-> Don't run it in a session that itself needs updating and is currently open — the command skips this session, and any other currently-open/in-use session.
-
-### Step 4 · Preview the update scope
-
-Type `/dsh-rewind-fix` in the composer and send it. It only scans, doesn't write. The editor locks while it runs, which is normal. **Don't switch session windows midway**. When it finishes, it reports how many sessions were scanned, how many will be updated, how many skipped, and how many failed. Confirm those are what you expect before moving on.
-```
-/dsh-rewind-fix
-```
-
-### Step 5 · Execute
-
-Once you're sure, re-enter the command with `--apply` to actually run it:
-```
-/dsh-rewind-fix --apply
-```
-This really rewrites the session logs and updates the old markers, and **may take a few minutes**. Please let it finish — **don't switch to another session window or close DSH** while it runs: a session you switch to is **safely skipped** (no corruption, but it won't be updated this pass and you'll need to re-run). A session that fails stays as it was, unharmed, and can be updated again later. Sessions that are updated also get their matching **snapshot backups cleared**, so file restore to earlier messages is no longer available for them.
-
-### Step 6 · Restart DSH and preview again
-
-After the run, restart DSH, then **preview once more**:
-```
-/dsh-rewind-fix
-```
-If it says there are no more sessions to update, the markers are all current and the old sessions will open normally. If there are still sessions to update, they may have been loaded during the run — restart in a temporary session window and retry.
-
-### Step 7 · Delete the backup after confirming (optional)
-
-Use it for a while, and once everything works, delete the backup from step 2:
-```sh
-rm -rf ~/.dsh/sessions.backup ~/.dsh/rewind-snapshots.backup
-```
-
-## Notes
-
-- The session logs are still v0 format; when DSH's later `v0 → v1 → v2 → v3` migration arrives, if you've completed the `rewind` marker update, the markers themselves won't block it.
-- Some sessions may still be blocked by an **unclosed turn** (a turn that was interrupted/cancelled and never wrote `turn/end`). Per the empirical analysis these are widespread and **unrelated to rewind** — they're a DSH-side issue and this tool doesn't handle them. **So updating the markers doesn't guarantee you can upgrade to the next DSH line.**

package/docs/rewind-fix.zh.md

@@ -1,89 +0,0 @@
-# 回退标记更新指南
-
-> [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` 命令**（向后）——对于**已经存在**的旧会话，本插件曾提供便捷更新命令（已在插件 `0.10.x` 移除），把旧标记「翻译」成新格式，让会话重新可用。
-
-本文档主要讲解**更新命令**的使用方法。
-
-## 警告
-
-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 线。**

package/docs/snapshot-auto-cleanup.md

@@ -1,78 +0,0 @@
-# Snapshot cleanup
-
-The plugin saves a backup of each file before it's edited, so you can rewind your
-code to an earlier point. These backups are called **snapshots**, and they're
-grouped by message and stored per session.
-
-`/snapshot-auto-cleanup` helps you manage those snapshots — whether you want to
-reclaim disk space from old sessions or clear the **current** session so its
-rewind history starts fresh.
-
-## What it does
-
-**Automatic cleanup** (off by default): the plugin can remember which sessions
-you've stopped using, and now and then remove their snapshots to keep disk usage
-down. It never touches your active session, and it never touches your
-conversation.
-
-**Manual**: even with automatic cleanup off, you can run the cleanup yourself —
-see [Commands](#commands) below.
-
-## Commands
-
-```
-/snapshot-auto-cleanup                       show the current settings
-/snapshot-auto-cleanup on|off                turn automatic cleanup on or off
-/snapshot-auto-cleanup max-age <days>        how many idle days before a session's snapshots are removed
-/snapshot-auto-cleanup run                   preview what the automatic cleanup would remove
-/snapshot-auto-cleanup run --apply           actually remove those snapshots
-/snapshot-auto-cleanup run --current         preview clearing this session's snapshots
-/snapshot-auto-cleanup run --current --apply actually clear this session's snapshots
-```
-
-`run` always starts as a preview; add `--apply` to make the change. `run` works
-whether or not automatic cleanup is on.
-
-## Settings
-
-The auto-cleanup switch and the idle-day cutoff are this plugin entry's own
-configuration. View and edit them on the **Plugins** page, in this plugin's
-configuration card, or with the `/snapshot-auto-cleanup` command:
-
-<img src="../assets/screenshots/cleanup-setting.png" alt="Plugin configuration card: auto cleanup and idle time (days)" width="600">
-
-- `autoCleanupEnabled` — whether automatic cleanup runs (default `false`).
-- `autoCleanupMaxAgeDays` — how many idle days before a session's snapshots are removed (default `30`). Only positive integers are accepted, so a broken setting can never delete everything.
-
-## When automatic cleanup runs
-
-When it's enabled, automatic cleanup runs in the background at most **once a
-day** — and only after 24 hours have passed since the last cleanup. The clock is
-saved to `<dsh home>/snapshot-cleanup-last-sweep.json`, so restarting the host
-can't make it run early. To clean up right now instead of waiting, use
-`/snapshot-auto-cleanup run`.
-
-## Safety
-
-- Only rewind **snapshots** are ever removed: a session's snapshot directory
-  holds the before-write file backups plus their bookkeeping (staged captures,
-  rescue copies, restore journals), and that is all the cleanup touches. Your
-  conversation is never touched, and the plugin never rewrites or deletes your
-  session history.
-- Automatic cleanup never removes your **active** session's snapshots — only
-  sessions that have been idle past the cutoff.
-- `run --current` clears the current session's snapshots; if a turn is currently
-  running, the plugin pauses it first, then clears. This is one-way for that
-  session's file-rewind history: you can't rewind code to before the clear, but
-  your conversation stays intact, and the session starts recording fresh
-  snapshots from now on.
-
-## Known limitation
-
-The plugin keeps the most recent **100 anchor groups'** snapshots per session (one
-group per user message). If you rewind or compact a lot in one long session,
-those 100 slots can be taken up by messages that are no longer reachable, so you
-may find you can't rewind as far back as you'd like. (Claude Code behaves the
-same way.) To get back to a clean state, run
-`/snapshot-auto-cleanup run --current --apply` to clear the current session and
-start fresh.

package/docs/snapshot-auto-cleanup.zh.md

@@ -1,48 +0,0 @@
-# 快照清理
-
-插件会在每次修改文件前保存一份备份，方便你把代码回退到之前的状态。这些备份叫**快照**，按消息分组、按会话存放。
-
-`/snapshot-auto-cleanup` 帮你管理这些快照——既可以回收旧会话占用的磁盘，也可以清空**当前**会话、让它从"现在"重新开始记录回退历史。
-
-## 它能做什么
-
-**自动清理**（默认关闭）：插件会记住哪些会话你已不再使用，并定期移除它们的快照以节省磁盘。它**绝不**触碰你当前活跃的会话，也**绝不**触碰你的对话。
-
-**手动**：即使自动清理是关闭的，你也可以自己执行清理——见下[命令](#命令)。
-
-## 命令
-
-```
-/snapshot-auto-cleanup                       查看当前设置
-/snapshot-auto-cleanup on|off                开启/关闭自动清理
-/snapshot-auto-cleanup max-age <天数>        会话失活多少天后移除其快照
-/snapshot-auto-cleanup run                   预演：看自动清理会移除什么
-/snapshot-auto-cleanup run --apply           真正移除这些快照
-/snapshot-auto-cleanup run --current         预演：看清空本会话快照会怎样
-/snapshot-auto-cleanup run --current --apply 真正清空本会话快照
-```
-
-`run` 一开始总是预演；加 `--apply` 才真正执行。`run` 无论自动清理是否开启都能用。
-
-## 设置
-
-自动清理开关与失活天数保存在**本插件条目自身的配置**中。可在**插件**页本插件的配置卡片查看与修改（自动清理开关、失活天数），也可用 `/snapshot-auto-cleanup` 命令查看和设置：
-
-<img src="../assets/screenshots/cleanup-setting.png" alt="插件配置卡片：自动清理与不活跃时间（天）" width="600">
-
-- `autoCleanupEnabled` — 是否运行自动清理（默认 `false`）。
-- `autoCleanupMaxAgeDays` — 会话失活多少天后移除其快照（默认 `30`）。只接受正整数，因此一个损坏的设置永远不可能"删掉一切"。
-
-## 自动清理何时运行
-
-开启后，自动清理在后台运行，**一天最多一次**——且距上次清理已满 24 小时才会执行。这个时钟保存在 `<dsh home>/snapshot-cleanup-last-sweep.json`，所以重启宿主也不会让它提前运行。想立刻清理而不等待，用 `/snapshot-auto-cleanup run`。
-
-## 安全
-
-- 只会移除回退用的**快照**：一个会话的快照目录里只有写前文件备份及其附属记录（暂存副本、救援副本、还原日志），清理也只动这些。你的对话绝不会被动到，插件也绝不改写或删除你的会话历史。
-- 自动清理**永不**移除你**当前活跃**会话的快照——只清理已失活超过阈值的会话。
-- `run --current` 会清空当前会话的快照；若此刻有正在进行中的回合，插件会先暂停它再清空。这对该会话的文件回退历史是**不可逆**的：你无法回退到清空之前的代码状态，但你的对话保持完整，会话会从"现在"开始重新记录快照。
-
-## 已知限制
-
-插件每个会话只保留**最近 100 组锚点**的快照（每条用户消息一组）。若你在一个很长的会话里多次回退或压缩，这 100 个名额常会被"已经无法再回退到"的消息占满，你可能无法回退到想要的位置。（Claude Code 也是同样行为。）想恢复到一个干净状态，运行 `/snapshot-auto-cleanup run --current --apply` 清空当前会话、重新开始。