dsh-rewind-plugin 0.4.1 → 0.5.0

package/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Thanks for considering a contribution to dsh-rewind. This file is short on
+purpose: the authoritative spec for how the repo works is `AGENTS.md` (read it
+first), and the docs live under `docs/` with an index in `docs/README.md`.
+
+## Project principles
+
+- **Focused on purpose** — one thing: in-window rewind to any earlier user
+  message, never forking a session.
+- **Security first** — session logs are append-only; file restores stay inside
+  the plugin's own backup directory. See `SECURITY.md`.
+- **Minimal** — avoid over-abstraction; keep the plugin light and maintainable.
+
+## Prerequisites
+
+- Node `^22.19.0 || >=24.0.0` (see `engines` in `package.json`), npm.
+
+## Setup and commands
+
+```sh
+npm install            # devDeps from the npm registry
+npm run build          # esbuild → lib/ (host ESM + client closure + types)
+npm run check          # one-shot full gate: typecheck + test + build + verify:host + pack --dry-run
+npm run typecheck      # tsc --noEmit (host / client / client-test)
+npm test               # vitest: unit + compatibility suites
+npm run verify:host    # end-to-end host verification (full check suite)
+```
+
+`prepare` runs the build, so `npm pack` / `npm publish` always carry a fresh
+`lib/` and `LICENSE`.
+
+## Before you open a PR
+
+- **Every change must pass** `npm run check`.
+- Commit messages use conventional commits with **English** subjects
+  (`feat` / `fix` / `docs` / `test` / `refactor` / `chore` / …). Code comments
+  are written in English.
+- Keep `rewind.ts` pure and `snapshot.ts` host-independent — if a change needs
+  I/O or harness types in the planning layer, that is a design smell.
+
+## Documentation rules
+
+- New/changed behavior that is durable (formats, contracts, compatibility
+  findings) must update the relevant doc in the same PR:
+  - **`docs/format.md`** — any change to the on-disk format (bump version,
+    migrate, or move the state root; no silent re-interpretation).
+  - **`docs/contract/client-contract.md`** — any change to the meaning of
+    `@<seq>` / `sourceEventSeq` / `data-dsh-rewind-hidden`; breaking a listed
+    stability tier is a minor/major version bump.
+  - **`docs/compat/audit.md`** — new compatibility findings (it is the single
+    source of truth; other docs link to it instead of restating).
+  - **`SECURITY.md`** — any change to the security model (trust boundary,
+    mutation gates, containment, crash handling).
+- Bilingual docs use the `.md` / `.zh.md` file split; keep the two mirrors in
+  sync.
+
+## Testing expectations
+
+- Pure planning (`rewind.ts`, `hidden.ts`) → unit tests in `tests/`.
+- Store behavior (`snapshot.ts`) → `tests/snapshot.test.ts`, plus crash-safety
+  scenarios in `tests/crash-safety.test.ts` via the test-only `crash` seam
+  (`RestoreRunOptions.crash`).
+- Harness interaction → the compatibility suites
+  (`compat-invariants` / `compat-interop` / `compat-gaps`) and
+  `scripts/verify-host.mjs`.
+
+## Releasing
+
+Releases are CI-driven via GitHub Actions Trusted Publishing (OIDC, no stored
+token): push a `v<version>` tag and CI publishes with Sigstore provenance. Full
+details: `docs/release/release.md`.

package/README.en.md

@@ -0,0 +1,174 @@
+# dsh-rewind
+
+Conversation rewind for DeepSeek Harness: **rewind the conversation to any earlier user message in one click, in the same window** — no new branch, no window switch, with optional workspace-file restore (full Claude Code `/rewind` semantics).
+
+[![npm version](https://img.shields.io/npm/v/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
+[![tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2FSiriLee%2Fdb3b9260351c2b26eb3d201c2ed29df1%2Fraw%2Fbadge.json)](https://github.com/SiriLee/dsh-rewind/actions/workflows/ci.yml)
+
+> English | [中文](README.md)
+
+A deliberately focused plugin with one job: **rewind to any user message, no matter how far back, in place** — and conveniently **restore the files it changed** along the way.
+
+- **Rewinding is time-travel** — the target message and everything after it (agent replies, tool calls) are withdrawn from the model context *and* the rendered transcript at once, with no new session and no window switch; the target's text is offered back in the composer so you can edit and re-send it — **truly seamless and convenient by design**.
+- **Lightweight workspace backup** — Claude Code-aligned behavior: only file-writing tools are tracked, a lightweight before-backup is **persisted on disk**, and your git repository is never touched or relied on. One lightweight plugin gives you a **complete** agentic rewind capability.
+- **Privacy-first** — the plugin never deletes or rewrites the session log (append-only) and never actually deletes any of your conversation; file restores stay inside the plugin's own backup directory. Full security model: [SECURITY.md](SECURITY.md).
+- **A complete test system** — unit, probe, and end-to-end host verification, covering compatibility probing, log replay, resume, cross-restart and other scenarios; maintained continuously as the harness evolves to ensure feature stability.
+
+## Preview
+
+Every user message carries a **↶ rewind** button in its action row. Clicking it opens a mode-selection popover — "**rewind conversation only**" or "**rewind conversation and code**", the latter showing the file-change list for confirmation first. You can also rewind conveniently via the **`/rewind` command** or a **keyboard shortcut**.
+
+<table>
+  <tr>
+    <td align="center"><img src="assets/screenshots/rewind-button.png" width="440" alt="Per-message ↶ rewind button"><br><sub>Per-message ↶ rewind button</sub></td>
+    <td align="center"><img src="assets/screenshots/mode-popover.png" width="440" alt="Mode-selection popover"><br><sub>Mode-selection popover</sub></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="assets/screenshots/impact-list.png" width="440" alt="Impact list"><br><sub>"Conversation and code" impact list</sub></td>
+    <td align="center"><img src="assets/screenshots/rewind-candidates.png" width="440" alt="/rewind candidate picker"><br><sub>/rewind candidate picker</sub></td>
+  </tr>
+</table>
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-rewind-plugin
+```
+
+> ⚠️ The npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
+
+## Usage
+
+1. Find the user message you want to rewind to in the conversation, or type `/rewind` to open the candidate picker.
+2. **Select it.** A small popover offers the two modes ("conversation and code" is only shown when there are restorable changes after the target).
+3. The rewind takes effect immediately: the conversation returns to how it looked at the target message, and the withdrawn message's text is filled back into the composer — edit and re-send.
+
+**Keyboard**: both the candidate picker and the mode popover support ↑↓ to move, Enter to confirm, Esc to cancel/back.
+
+<details>
+<summary><b>Edge notes</b></summary>
+
+- Rewinds can be repeated — with no limit on stage or count.
+- A rewind itself **cannot be undone**, but the withdrawn content stays in the session log and can be recovered by manually editing it.
+- **Interruptions rewind too** — a `steering` interruption message the model hasn't read yet is also a valid rewind target.
+- **A rewind interrupts the running turn** — to execute the rewind safely.
+
+</details>
+
+## Why it stands out
+
+Compared with the common approaches, here is the trade-off this plugin makes on "rewind":
+
+| Dimension | Common approach | This plugin |
+| --- | --- | --- |
+| Conversation rewind | Fork / branch a new conversation | **In-place rewind** — no new session, no window switch |
+| File restore | No restore feature / git-managed or whole-tree snapshot | **Lightweight before-backups** — auto-captured before writes, one-click restore (aligned with Claude Code) |
+| Dependencies | Often needs a Git repo or a full snapshot engine | **None** — no git required, works on any directory |
+| Storage footprint | Whole-tree snapshots take space | **Lightweight** — only files touched by write tools are stored, persisted on disk |
+
+## How it works
+
+The whole design rests on two principles, simple but deliberate: **the conversation half "masks, never deletes", and the file half "backs up before the write, reconciles against the real disk before restoring."** It shares lineage with Claude Code's checkpointing — Claude Code's file history is also per-file records plus a re-scan of tracked files at every message, not a whole-tree snapshot. This plugin brings the same semantics to dsh, and makes them lighter and more robust.
+
+### 1. Conversation rewind: a single "mask", not a delete
+
+`append-only` is a hard rule: the session log only grows and is never rewritten — the foundation of auditability and privacy. A rewind never touches history; it makes a single move: append **one empty-content message marker** to the end of the log and use it to "mask out" everything after the target message, so the model and the UI see only the part before it.
+
+- The marker is **empty** — it never enters the model context and never renders as conversation content; what you and the model see is exactly how the conversation looked at the target. True "in place".
+- Because this is **masking, not deleting**, every withdrawn event stays in the log — auditable, traceable, and in principle manually recoverable.
+- The marker is deeply **aware of dsh internals**: it reuses the **last-started turn** number (never "last turn + 1") and carries its own **ghost step frame**. So the harness's own log replay, `/compact`, and resume preflight all recognize it and never mistake it for a real message.
+
+> **Design highlight**: the entire conversation rewind is **a single append**. It's deterministic, auditable, and — because the log was never broken — a "clean" time-travel. Minimal action, complete semantics. The compatibility subtleties with the harness (ghost step frame, reused turn number) are where this plugin is genuinely professional — each is pinned by a dedicated probe test.
+
+### 2. File restore: lightweight checkpointing, "back up before the change"
+
+The file half follows Claude Code's checkpoint semantics — **per-file before-backups plus a re-scan of tracked files at each message**, not a whole-tree snapshot. This trade-off saves space, and it's actually more complete:
+
+- **Before-backup**: tracks the write-class tools (`write`, `edit`, `str_replace_editor`) and stores the original content **before** each write. Timing is the key — it captures after any approval gate lets the call through: an approval short-circuit can't skip the backup, and a denied call never records; a read failure only warns, never blocks the write. Backups are grouped by conversation turn and **persist on disk** across restarts.
+- **External changes count too**: at every user-message boundary the plugin re-checks all tracked files — edits or deletions made outside the write tools are recorded as well and restored by a later rewind. "Lightweight" but not "incomplete".
+- **Reconcile against the real disk before restoring**: the most interesting decision. At rewind time the plugin reads each file's current content and compares it to the target state — **only files that actually differ are touched**: modified files are written back to their earliest backup, files created after the target are deleted, files already matching are skipped. Repeated rewinds are therefore **idempotent with zero side effects** and never produce "ghost impact".
+- **Safety boundary**: symlinks / hard links are skipped so one restore can't clobber another name of the same file; paths are sanitized so nothing ever escapes the backup root; a per-file failure never aborts the pass.
+
+> **Design highlight**: **"reconcile against the real disk before acting"** is the most insightful decision in this checkpoint design — it never assumes blindly; it trusts the disk, doing what must be done and skipping what must not.
+
+### Design highlights
+
+| Design | Why it matters |
+| --- | --- |
+| A single append is a whole rewind | Minimal action, maximal semantics; the log is never mutated |
+| Mask, never delete | History is always auditable and in principle recoverable |
+| Before-backup, grouped by turn, persisted on disk | Space-efficient, survives restarts, Claude Code-aligned |
+| Identical content stored as a link (dedup) | Hundreds of repeated writes cost almost nothing; links are materialized before their group is evicted, never left dangling |
+| Session-level auto-cleanup | Removes only long-inactive sessions' snapshots; the active session and the chat log are never touched |
+| Reconcile against the real disk before restoring | Idempotent, zero side effects, no collateral damage |
+| Ghost step frame + reused turn number | Deeply compatible with the host, pinned by probe tests |
+| Crash safety (atomic writes + restore journal) | Continue or roll back cleanly after a crash |
+| Pure-function planning + probed store | Fully unit-testable without a host; test-driven |
+
+## What it deliberately does NOT do
+
+This plugin deliberately stays lightweight and focused on one thing — "conversation rewind". The following are **out of its scope**:
+
+- **Whole-tree / Git-level snapshots** — only write-class tool edits plus external changes to already-tracked files are backed up; files never touched by a tool are not restored. For whole-worktree snapshot rollback, use a dedicated snapshot tool (or your git).
+- **Subagent edits** — not tracked (same as Claude Code): a subagent runs its own session, so its backups could never be restored by a rewind of the parent session.
+- **Fork / branch rewind** — the harness already provides this ("branch in new chat"); no need to reinvent it.
+
+## Compatibility
+
+- Node.js `^22.19.0 || >=24.0.0`.
+- DeepSeek Harness web profile (`dsh --profile web`); peer `@deepseek-ai/*` packages are resolved by the harness at runtime.
+
+> [!WARNING]
+> This project and DeepSeek Harness are both in developer preview. Pin exact
+> versions in reproducible environments and review the behavior notes above.
+
+## Client contract
+
+Third-party DOM plugins that need to know which transcript rows a rewind
+withdrew should consume the stable, locale-independent helpers exported from
+`dsh-rewind-plugin/client` — never parse
+`outcome.text`. The `data-dsh-rewind-hidden` attribute marks withdrawn rows
+(observational only). Details: [docs/contract/client-contract.md](docs/contract/client-contract.md).
+
+## Known issues
+
+1. **Exported logs are complete** — a rewind only removes messages from the model context and the view; the exported session log (`/export`) still contains **withdrawn messages**. This plugin cannot alter exports.
+2. **Lightweight file rewind has a cost** — in specific cases not all changes can be rewound. Consistent with Claude Code. See: [File-rewind tracking boundary](docs/compat/tracking-boundary.md).
+3. **Rewinds from `≤ v0.2.4`** — sessions rewound with these versions may **fail to load history** after more conversation. Install a v0.3.3-or-earlier release and use its bundled repair tool ([docs/compat/troubleshooting.md](docs/compat/troubleshooting.md)).
+4. **Rewinds from `≤ v0.3.3`** — compaction (`/compact`) is unavailable for those sessions. Newer versions are compatible; for affected old sessions, start a new session.
+
+## Security
+
+This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and code"; backups and restores stay under `~/.dsh/rewind-snapshots/`. It never touches your git repository, makes no network requests, and accesses no credentials. Delete `~/.dsh/rewind-snapshots/` to wipe file backups only (chat rewinds are unaffected); the plugin rebuilds automatically. Full security model: [SECURITY.md](SECURITY.md).
+
+## Development
+
+```sh
+npm install            # devDeps from the npm registry
+npm run check          # one-shot full gate: typecheck + test + build + verify:host + pack --dry-run
+npm run typecheck      # tsc on all three surfaces (host + client + client-test)
+npm test               # vitest: all unit and compatibility suites
+npm run build          # esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
+node scripts/verify-host.mjs   # end-to-end verification of the built artifact
+```
+
+`prepare` runs the full build, so git installs and `npm pack` / `npm publish` always produce a complete `lib/` and the `LICENSE`.
+
+Maintainers: the module map and harness interface reference live in [docs/harness-reference.md](docs/harness-reference.md).
+
+Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Release
+
+Releases go out through GitHub Actions Trusted Publishing (OIDC, no stored `NPM_TOKEN`): push a `v<version>` tag and CI publishes with Sigstore provenance.
+
+```sh
+npm version patch && git push origin main --tags
+```
+
+One-time npm-side setup and the full workflow details: [docs/release/release.md](docs/release/release.md).
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,173 +1,177 @@
 # dsh-rewind
 
-In-place conversation rewind for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): Claude Code's `/rewind` semantics inside the **same session window** — cut the model context back to an earlier user message, and optionally restore workspace files from disk-persisted before-backups.
+DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消息**——同窗口内完成，不新建分支、不换窗口，可一并还原工作区文件（完整 Claude Code `/rewind` 语义）。
 
 [![npm version](https://img.shields.io/npm/v/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
-[![npm license](https://img.shields.io/npm/l/dsh-rewind-plugin.svg)](https://github.com/SiriLee/dsh-rewind/blob/main/LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
+[![tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2FSiriLee%2Fdb3b9260351c2b26eb3d201c2ed29df1%2Fraw%2Fbadge.json)](https://github.com/SiriLee/dsh-rewind/actions/workflows/ci.yml)
 
-> English | [中文](README.zh.md)
+> [English](README.en.md) | 中文
 
-A deliberately focused plugin with one job: rewind to any earlier user message, in place.
+刻意聚焦、保持极简，只做一件事：**就地回退到任意远的用户消息**，还能**顺手还原改过的文件**。
 
-| Mode | Conversation | Workspace files |
-| --- | --- | --- |
-| **Rewind conversation only** | Cut back to the target message | Untouched |
-| **Rewind conversation and code** | Cut back to the target message | Restored to their state before it (modified files written back, later-created files deleted) |
-
-Rewinding is time-travel: the target message and everything after it (agent replies, tool calls) are withdrawn from the model context *and* the rendered transcript — no new session, no window switch — and the target's text is offered back in the composer so you can edit and re-send it.
-
-The plugin never rewrites the append-only session log and never touches your git repository.
+- **回退 = 时间回溯**——目标消息及其之后的全部内容（agent 回复、工具调用）同时从**模型上下文**和**渲染对话**中撤回，不新建会话、不切换窗口；目标消息文本会回填输入框，改完可重发。**在原理上就真正无感、便捷**。
+- **轻量工作区备份**——行为对齐 Claude Code：只跟踪写文件的工具，写前做轻量备份并**落盘持久化**，不依赖、也不触碰 git 仓库。一个轻型插件，即拥有**完备的智能体回退能力**。
+- **信息安全优先**——插件从不删改会话日志（append-only），从不真正删除你的任何对话；文件还原限定在插件自己的备份目录。完整安全模型：[SECURITY.md](SECURITY.md)。
+- **完备测试系统**——单元、探针、端到端主机验证，覆盖兼容性探测、日志重放、续接、跨重启等场景；随 harness 升级持续维护，确保功能稳定。
 
-## Preview
+## 效果预览
 
-Each user message gains a compact **↶ rewind** action in its action row. Clicking it opens a mode-selection popover; "conversation and code" first shows the exact restore / delete list for confirmation (the option is hidden when there are no tracked changes — like Claude Code's code-restore visibility).
+每条用户消息的操作行都有一个 **↶ 回退** 按钮。点击后弹出模式选择浮层——「**仅回退对话**」或「**回退对话和代码**」，后者会先展示文件变更清单再确认。还可以通过 **`/rewind` 命令**和**快捷键**便捷地选择和回退。
 
 <table>
   <tr>
-    <td align="center"><img src="assets/screenshots/rewind-button.png" width="440" alt="Per-message ↶ rewind button"><br><sub>Per-message ↶ rewind button</sub></td>
-    <td align="center"><img src="assets/screenshots/mode-popover.png" width="440" alt="Mode-selection popover"><br><sub>Mode-selection popover</sub></td>
+    <td align="center"><img src="assets/screenshots/rewind-button.png" width="440" alt="用户消息旁的 ↶ 回退按钮"><br><sub>用户消息旁的 ↶ 回退按钮</sub></td>
+    <td align="center"><img src="assets/screenshots/mode-popover.png" width="440" alt="模式选择浮层"><br><sub>模式选择浮层</sub></td>
   </tr>
   <tr>
-    <td align="center"><img src="assets/screenshots/impact-list.png" width="440" alt="Impact list"><br><sub>"Conversation and code" impact list</sub></td>
-    <td align="center"><img src="assets/screenshots/rewind-candidates.png" width="440" alt="/rewind candidate picker"><br><sub>/rewind candidate picker</sub></td>
+    <td align="center"><img src="assets/screenshots/impact-list.png" width="440" alt="影响清单"><br><sub>「回退对话和代码」影响清单</sub></td>
+    <td align="center"><img src="assets/screenshots/rewind-candidates.png" width="440" alt="/rewind 候选面板"><br><sub>/rewind 候选面板</sub></td>
   </tr>
 </table>
 
-## Install
+## 安装
 
 ```sh
 dsh plugin --profile web add dsh-rewind-plugin
 ```
 
-Restart `dsh web` (`--profile web`) after installing.
+> ⚠️ npm 上的 `dsh-rewind` 属于其他作者，请用 `dsh-rewind-plugin` 安装。
 
-> ⚠️ The npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
+## 使用
 
-For contributors: install from a local checkout or a pinned commit — `dsh plugin --profile web add /path/to/dsh-rewind` or `dsh plugin --profile web add github:SiriLee/dsh-rewind#<sha>`. A git install fails on first run until you add an `allowBuilds` key to the profile's `pnpm-workspace.yaml` (pnpm blocks git dependencies from running build scripts); after that it runs the plugin's `prepare` and installs it.
+1. 在对话中找到要回退的那条用户消息，或输入 `/rewind` 打开候选列表选择。
+2. **选中它。** 小浮层提供两种模式（「回退对话和代码」仅在目标之后有可还原的变更时显示）。
+3. 回退立即生效：对话回到目标消息当时的样子，被撤回消息的文本自动填入输入框——改完直接重发。
 
-## Usage
+**键盘操作**：候选列表与模式浮层均支持 ↑↓ 移动、Enter 确认、Esc 取消/返回。
 
-1. **Hover** any user message you sent — a **↶ rewind** button appears in its action row.
-2. **Click it.** The target is that message; a small popover offers the two modes ("conversation and code" is hidden when no tracked file changes exist after the target).
-3. The rewind executes as an in-session command; a result message confirms, and the withdrawn message's text is filled back into the composer for editing and re-sending.
+<details>
+<summary><b>边界说明</b></summary>
 
-**Command-line entry**: type a bare `/rewind` and press Enter to open the candidate picker; selecting a target continues the same flow as the button.
+- 回退可以反复进行——没有阶段或次数限制。
+- 回退本身**无法撤销**，但被撤回的内容仍保留在会话日志中，可手动编辑日志恢复。
+- **插话也能回退**——模型尚未读取的 `steering` 插话消息，同样可作为回退目标。
+- **回退会打断当前正在运行的回合**——确保回退安全执行。
 
-Both the candidate picker and the mode popover support the keyboard: ↑↓ to move, Enter to confirm, Esc to cancel/back.
+</details>
 
-Rewinds can be repeated (each appends a marker to the log). A rewind cannot be undone through the plugin, but the withdrawn messages can be recovered by manually editing the session log. The file-restore action is not re-backed up.
+## 存储管理
 
-## How it works
+快照（写前备份）存储于 `~/.dsh/rewind-snapshots/`。插件对**同一会话**的快照做内容去重（内容未变则存为链接）并保留最近 100 组锚点；**手动删除该目录**仅清除文件备份（对话回退不受影响），插件会自动重建。
 
-### 1. Conversation rewind (in-place)
+另提供**全局自动清理**（默认关闭）：把**长期不活跃**的会话快照整目录移除，不影响活动会话与对话日志。用 `/snapshot-auto-cleanup` 命令**查看与设置**，配置写入 `~/.dsh/snapshot-cleanup.json`。详见：[快照自动清理](docs/snapshot-auto-cleanup.zh.md)。
 
-The plugin appends an **empty-content marker** `assistant/message` into the session log whose `surfaceOp: { op: 'replace', start, end }` replaces every surface node after the target message with the marker:
+## 本插件的优势
 
-- The marker carries `sourceEventSeqs` covering every shadowed node, and `Session.append`'s surface rules validate the cut (a contiguous range on the current surface).
-- Because the marker is **empty**, the harness derives it to `null` — it never enters the model context and never renders as conversation content. Agent and user both see the conversation exactly as it was at the target.
-- The marker's **turn number reuses the last started turn** (`markerTurnOf`), never `lastTurn + 1`: the harness numbers its next real turn exactly `last turn/start + 1`, so a `maxTurn + 1` marker would sit *before* that `turn/start` — the client conversation builder rejects the ordering (`…turn-tail… received an update before its start Match`) and history load fails. Reusing an already-consumed turn makes the marker a harmless trailing update on the previous completed turn's tail — it can never collide with a future turn.
-- The marker rides a **ghost step frame** — its own `step/start` … `step/end` with a fresh step number (`markerStepOf`) — because the harness token-meter requires every `assistant/message` to sit inside an open step of the same turn/step; a bare idle-time marker would fail its replay and break `/compact` for the session.
-- The append-only log is **untouched** — every withdrawn event stays in the audit trail; only the model-visible surface is cut, so the next request derives its context from the target onward.
+和常见的几种做法相比，本插件在"回退"这件事上的取舍：
 
-A running turn (LLM thinking / streaming) is force-stopped first (`cancel({ kind: 'user' })`) and the rewind waits for quiescence; if it can't stop, the rewind is aborted with an error.
+| 维度 | 常见做法 | 本插件 |
+| --- | --- | --- |
+| 对话回退 | Fork 分支新建对话 | **就地回退**——不新建会话、不切窗口，便捷回退 |
+| 文件还原 | 无还原功能 / git 管理或完整快照 | **写前轻量备份**——写文件前自动存原内容，一键还原（对齐 Claude Code） |
+| 依赖 | 常依赖 Git 仓库或完整快照引擎 | **无依赖**——不依赖 git，普通目录即可用 |
+| 存储开销 | 整树快照占空间大 | **轻量**——只存被写工具改动过的文件，落盘持久化 |
 
-### 2. Checkpoint file restore
+## 原理
 
-The plugin tracks the write-class tools — `write`, `edit`, `str_replace_editor` (mutating commands `create` / `str_replace` / `insert`):
+整套设计只有两条主线，核心哲学朴素却克制：**对话部分「只遮蔽、不删除」，文件部分「改前先备份，还原时对照真实磁盘」**。机制与 Claude Code 的 checkpointing 同源——Claude Code 的文件历史也是逐文件记录 + 每条消息重扫已跟踪文件，并非整树快照；本插件把同一套语义落在 dsh 上，并做得更轻、更稳。
 
-1. **Before-capture** at `tools/execute` (the around-dispatch stage): the target file is read; the resolved path + content are held in a pending map. This stage runs only after any pre-execute approval gate let the call through — an `ask` short-circuit (dsh-edit-approval) **cannot skip** the backup, and a denied call never records. If the read fails (e.g. a permission error), the change is simply not backed up — the plugin warns in the log but **does not block the write**.
-2. **Disk commit** at `tools/post-execute`: the before-backup is written under the turn's anchor message seq (`~/.dsh/rewind-snapshots/<session>/<anchor seq>/<callId>.json`).
-3. **Restore** (`/rewind @<seq> both`): every backup anchored at or after the target applies once reconciled with the current disk — modified files are written back to their **earliest** captured before-state, files created after the target are deleted, files already matching the target state are left untouched (idempotent). Symbolic / hard links are skipped (they share an inode with another name; restoring through one would clobber both). Writes go through plain `node:fs`, independent of the fs service — under sandbox / remote backends, path resolution may be restricted.
-4. A tool body that **throws** skips `tools/post-execute`; a `tools/result` safety net clears the pending capture so nothing leaks in memory.
+### 1. 对话回退：一次「遮蔽」，而不是「删除」
 
-Backups persist across host restarts, bounded to the newest 100 anchor groups per session.
+`append-only` 是铁律：会话日志只追加、从不改写——这是可审计与信息安全的地基。回退从不动历史，它只做一步：往日志末尾追加**一条内容为空的消息标记**，用它把目标消息之后的全部内容「遮蔽」掉，让模型和界面都只看得到目标之前的部分。
 
-## What it deliberately does NOT do
+- 标记本身是**空的**——不进入模型上下文、不渲染成任何对话内容，模型和你看到的对话就是目标消息当时的样子，真正的「就地」；
+- 因为是「遮蔽」而非「删除」，**被撤回的每一条事件都完整留在日志里**，可审计、可追溯，原则上也随时能手动恢复；
+- 标记非常「懂」dsh——它复用**最后一个已开始的回合**的编号（而不是「最后回合 + 1」），并自带一个独立的**幽灵步骤框架**。于是 harness 自己的日志重放、`/compact` 压缩、续接检查都能正确识别它，绝不会把它误认为真实对话。
 
-- **Whole-tree / git-first snapshots** — only write-class tool edits plus external changes to already-tracked files are backed up; files never touched by a tool are not restored: the same limitation as Claude Code, which defers such rollbacks to the user's git.
-- **Subagent edits** — not tracked (same as Claude Code): a subagent runs its own session, so its backups could never be restored by a rewind of the parent session.
-- **Fork / branch rewind and `/compact`** — the harness already provides these ("branch in new chat", compact).
+> **设计点睛**：整个对话回退就是**一条**追加。它确定、可审计，且因为日志从未被破坏，回溯是「干净的」——用最小的动作，实现最完整的语义。那些与 harness 内部的兼容细节（幽灵步骤框架、复用回合号）正是插件的专业所在，每一条都由专门的探针测试固化。
 
-## Comparison with similar projects
+### 2. 文件还原：轻量检查点，「改前备份」
 
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) also has [Anionex/dsh-turn-rewind](https://github.com/Anionex/dsh-turn-rewind) — a rewind plugin with the same user-facing idea (a per-message action that rolls the conversation back and restores workspace files), but a different approach:
+文件部分对齐 Claude Code 的检查点语义——**逐文件、写前备份 + 每条消息重扫已跟踪文件**，而不是整树快照。这项取舍既省空间，又更完整：
 
-| Dimension | dsh-rewind (this plugin) | Anionex dsh-turn-rewind |
-| --- | --- | --- |
-| Conversation rollback | **In-place, same session/window** — the model-visible surface is cut back to the target; the append-only log is untouched | **Forks a new Session** at the previous `turn/end`; the original session is always retained |
-| File-restore engine | **Lightweight before-backups** of write-class tools only, restored via plain `node:fs` | **Change Ledger** — a durable restore-point engine with Git fences, an approval gate, rescue points and crash reconciliation |
-| Tracked-change scope | Only write-class tool edits (like Claude Code) | Any Git-managed file (Git worktree required) |
-| Public service API | No — a focused single-purpose plugin | Yes — `ctx.changeLedger` service + `/turn-rewind` HTTP endpoint |
+- **改前备份**：追踪写类工具（`write`、`edit`、`str_replace_editor`），在**每次写文件之前**先把原内容存下来。关键在时机——在审批门放行之后捕获：审批短路不会漏备份，被拒绝的调用也不会留下记录；读取失败只警告、从不阻塞写操作。备份按对话轮次分组锚定，**落盘持久化**，重启也还在。
+- **外部变更也追**：每条用户消息边界，插件重新检查所有已跟踪文件——那些从没经过写工具、被外部改过或删掉的文件，同样被记录，回退时一并还原。这让「轻量」却不「残缺」。
+- **还原前对照真实磁盘**：这是最值得说的一点。回退时插件实时读取文件当前内容，与目标状态逐一比对——**只操作真正不一致的文件**：改过的写回最早备份、目标之后新建的删除、已经一致的跳过。重复回退因此**零副作用、幂等**，绝不会出现「幽灵影响」。
+- **安全边界**：符号/硬链接跳过，避免透过一个还原误伤另一个名字；路径经安全化处理，**绝不越出备份根目录**；单个文件失败绝不中止整轮还原。
 
-The essential difference: dsh-turn-rewind keeps the log immutable and therefore forks a new session; this plugin cuts the model-visible surface in place with an empty marker, so the original conversation continues in the same window — the non-trivial part (see [Known issues](#known-issues)) that dsh-turn-rewind sidesteps.
+> **设计点睛**：**「对照真实磁盘再动手」** 是这套检查点里最有洞察力的决定——它从不盲目假设，而是以磁盘为准，该做的做、不该做的跳过。
 
-## Compatibility
+### 设计亮点一览
 
-- Node.js `^22.19.0 || >=24.0.0`.
-- DeepSeek Harness web profile (`dsh --profile web`); peer `@deepseek-ai/*` packages are resolved by the harness at runtime.
+| 设计 | 为什么值得 |
+| --- | --- |
+| 一次追加即一次回退 | 极小动作、极大语义，且日志从不被破坏 |
+| 只遮蔽、不删除 | 历史永远可审计，原则上可恢复 |
+| 改前备份 + 按轮分组 + 落盘 | 省空间、跨重启、对齐 Claude Code |
+| 同内容存为链接（去重） | 上百次重复写入几乎不占空间；淘汰组前先落地链接，绝不悬空 |
+| 会话级自动清理 | 只移除长期不活跃会话的快照，活动会话与对话日志永不触及 |
+| 对照真实磁盘再还原 | 幂等、零副作用、不误伤 |
+| 幽灵步骤框架 + 复用回合号 | 与宿主深度兼容，且被探针测试固化 |
+| 崩溃安全（原子写 + 还原日志） | 断电/崩溃后仍可续做或回滚 |
+| 纯函数规划 + 注入探针的存储 | 无需宿主即可单测，测试驱动 |
 
-> [!WARNING]
-> This project and DeepSeek Harness are both in developer preview. Pin exact
-> versions in reproducible environments and review the behavior notes above.
+## 明确不做的事
+
+本插件刻意保持轻量、聚焦"对话回退"这一件事，以下场景**不属于它的职责**：
+
+- **整树 / Git 级快照**——只跟踪写类工具编辑 + 已跟踪文件的外部改动，从未被工具碰过的文件不还原。需要 Git 工作树级的完整快照回退时，请交给专门的快照工具（或你的 git）。
+- **子代理的编辑**——不追踪（同 Claude Code）：子代理运行在自己的会话里，其备份无法由父会话的回退还原，只会在磁盘上残留。
+- **fork / 分支回退**——harness 已内置「在新对话中分支」，不重复造轮子。
 
-## Client contract
+## 兼容性
 
-Third-party DOM plugins that need to know which transcript rows a rewind
-withdrew should consume the stable, locale-independent helpers exported from
-`dsh-rewind-plugin/client` (`hiddenSeqsOf`, `targetSeqOfArgs`) — never parse
-`outcome.text`. The `data-dsh-rewind-hidden` attribute marks withdrawn rows
-(observational only). Details: [docs/client-contract.md](docs/client-contract.md).
+- Node.js `^22.19.0 || >=24.0.0`。
+- DeepSeek Harness web 配置档（`dsh --profile web`）；peer `@deepseek-ai/*` 包由 harness 运行时解析。
+
+> [!WARNING]
+> 本项目与 DeepSeek Harness 均处于开发者预览阶段。可复现环境请 pin 精确版本，
+> 并阅读上述行为说明。
 
-## Known issues
+## 客户端契约
 
-Rewinds created with versions `≤ v0.2.4` could corrupt client replay when followed by more conversation (a marker turn collides with the next `turn/start`). Only pre-upgrade sessions are affected. The offline repair tool (`dsh-rewind-repair`) was shipped before v0.4.0 and is no longer provided from v0.4.0 on — install a pre-v0.4.0 release if you need it ([docs/troubleshooting.md](docs/troubleshooting.md)).
+需要获知哪些转录行被回退撤回的第三方 DOM 插件，应使用 `dsh-rewind-plugin/client` 导出的稳定、与本地化无关的纯函数，切勿解析 `outcome.text`。`data-dsh-rewind-hidden` 属性标记被撤回的行（仅观测性）。
+详见：[docs/contract/client-contract.zh.md](docs/contract/client-contract.zh.md)。
 
-Rewinds from `≤ v0.3.3` appended a bare marker (no step frame); the harness token-meter rejects such a log on replay, so `/compact` fails for that session. Newer versions are compatible; affected old sessions have no online repair yet — start a new session.
+## 已知问题
 
-## Security
+1. **导出的日志是完整内容**——回退只是把消息从模型上下文和视图中移除，`/export` 导出的会话日志包含**已撤回的消息**。本插件无法改动导出。
+2. **轻量文件回退存在代价**——特定情况可能无法回退所有修改。行为与 Claude Code 一致。详见：[文件回退的追踪边界](docs/compat/tracking-boundary.zh.md)。
+3. **v0.2.4 及更早版本**回退过的会话，继续对话后可能加载历史失败。可安装 v0.3.3 及之前版本的随附修复工具处理（[完整步骤](docs/compat/troubleshooting.zh.md)）。
+4. **v0.3.3 及更早版本**回退过的会话，压缩对话（compact）不可用。新版本已兼容；受影响的旧会话建议新建会话。
 
-This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and code"; backups and restores stay under `~/.dsh/rewind-snapshots/`. It never touches your git repository, makes no network requests, and accesses no credentials.
+## 安全
 
-> **Note:** a rewind only hides messages from view — the exported session log (`/export`) still contains them, and this plugin cannot alter exports. To remove a conversation completely, delete its session file.
+本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和代码」时被改写，备份与还原都限定在 `~/.dsh/rewind-snapshots/` 内。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的全局自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
 
-## Development
+## 开发
 
 ```sh
-npm install            # devDeps from the npm registry
-npm run typecheck      # tsc on all three surfaces (host + client + client-test)
-npm test               # vitest: rewind / snapshot / hidden / session-cwd / integration / compat-invariants / compat-interop
-npm run build          # esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
-node scripts/verify-host.mjs   # boot the BUILT host artifact end-to-end (incl. real /compact after rewind)
+npm install            # devDeps 来自 npm registry
+npm run check          # 一键全检：typecheck + test + build + verify:host + pack --dry-run
+npm run typecheck      # tsc 三面编译（host + client + client-test）
+npm test               # vitest：全部单元与兼容性测试套件
+npm run build          # esbuild：lib/index.js（host ESM）+ lib/client.js（loader 闭包）+ .d.ts
+node scripts/verify-host.mjs   # 端到端验证构建产物
 ```
 
-`npm test` and `verify-host` include the **compatibility probe suites**
-([docs/compat-audit.md](docs/compat-audit.md)): scenario-generated logs drive the
-real harness packages (token-meter, compaction, session-stats/title/goal folds,
-resume preflight) through rewind markers and assert the compatibility
-invariants. A failing probe is a discovered incompatibility, not a mock
-artifact. One finding is recorded: **R-OPENSTEP** — a log carrying an
-unclosed `step/start` (crash leftover) makes any later step activity,
-including a rewind's ghost-step frame, break token-meter replay (and
-/compact). Harness `0.1.1-rc.2` fixes the crash path (`interruptedTurnClosers`
-closes leftover step/turn boundaries on load). A plugin-side guard was tried
-and reverted: it produced false positives on real session logs (rewind
-feature broken), so the plugin deliberately ships no guard — the residual
-risk (runtime-produced unclosed steps) is accepted.
+`prepare` 执行完整构建，所以 git 安装与 `npm pack` / `npm publish` 总会产出完整的 `lib/` 与 `LICENSE`。
 
-`prepare` runs the full build, so git installs and `npm pack` / `npm publish` always produce a complete `lib/` and the `LICENSE`.
+维护者：模块地图与 harness 接口参考见 [docs/harness-reference.md](docs/harness-reference.md)
 
-Maintainers: the module map and harness interface reference live in [docs/harness-reference.md](docs/harness-reference.md); publishing steps in [docs/release.md](docs/release.md).
+贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)
 
-## Release
+## 发布
 
-Releases go out through GitHub Actions Trusted Publishing (OIDC, no stored `NPM_TOKEN`): push a `v<version>` tag and CI publishes with Sigstore provenance.
+通过 GitHub Actions Trusted Publishing（OIDC，无存储 `NPM_TOKEN`）发布：推送 `v<版本>` tag，CI 即带 Sigstore provenance 发布。
 
 ```sh
 npm version patch && git push origin main --tags
 ```
 
-One-time npm-side setup and the full workflow details: [docs/release.md](docs/release.md).
+一次性 npm 侧配置与完整流程：见 [docs/release/release.zh.md](docs/release/release.zh.md)。
 
-## License
+## 许可
 
 [MIT](LICENSE)