dsh-rewind-plugin 0.2.7 → 0.2.9

package/README.zh.md

@@ -1,46 +1,26 @@
 # dsh-rewind
 
-[English](README.md)
-
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：**同一会话窗口的 in-place 对话回退**（Claude Code `/rewind` 语义）——把模型上下文剪回更早的一条用户消息，并可基于**落盘的写前备份**还原工作区文件。
 
-> **状态**：已发布 npm（`dsh-rewind-plugin`，v0.2.7），经 GitHub Actions Trusted Publishing + Sigstore provenance 构建发布。目标为 web 配置档（`dsh --profile web`）。交互以 Claude Code 的 rewind 为参考，并贴合 dsh Web 实际 UI。
->
-> **v0.2.7 要点**：输入框回填改为事件驱动（重开会话不再复活已撤回文本）；子代理编辑不跟踪（对齐 Claude Code）；并发回退有防护；「回退代码」选项仅在存在跟踪变更时显示（兼容新旧 host/client 混合版本）。
-
 [![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)
 
-## 目录
-
-- [✨ 功能特性](#-功能特性)
-- [📸 截图](#-截图)
-- [工作原理](#工作原理)
-- [📦 安装](#-安装)
-- [使用](#使用)
-- [行为细节与限制](#行为细节与限制)
-- [明确不包含](#明确不包含)
-- [兼容性](#兼容性)
-- [开发](#开发)
-- [发布](#发布)
-- [目录结构](#目录结构)
-- [License](#license)
-
-## ✨ 功能特性
-
-| 特性 | 说明 |
-| --- | --- |
-| 同窗口原地回退 | 在**任意**用户消息旁点 ↶ 按钮：该消息及之后全部内容（agent 回复、工具调用）从模型上下文**与**渲染对话中撤回——不新建会话、不切换窗口 |
-| 时间回溯语义 | 回退到某消息会**连同撤回该消息本身**；其文本自动填入输入框，可修改后重发 |
-| Claude Code 式文件还原 | 写类编辑在执行**前**被备份并落盘；「回退对话和代码」把文件还原到编辑前内容、删除目标之后新建的文件 |
-| 影响清单确认 | 「回退对话和代码」先展示要还原/删除的文件清单再确认（目标之后无跟踪变更时不显示该选项，对齐 Claude Code 的 code-restore 可见性） |
-| 与审批类插件共存 | 捕获在 `tools/execute`（around-dispatch 阶段）：其他插件的 pre-execute 审批短路（如 dsh-edit-approval）无法跳过备份，被拒绝的调用也不会记录 |
-| 路径按会话 cwd 解析 | 相对路径按 fs-tools 的 session-cwd 规则解析到**真实文件**，记录解析后的 display path |
-| 还原直写真实文件 | 还原走纯 `node:fs` 直接落盘；符号链接与硬链接跳过并警告（不通过共享 inode 误伤） |
-| 重启后仍可还原 | 备份落在磁盘 `~/.dsh/rewind-snapshots/<会话>/<锚点 seq>/`，每会话保留最近 100 组 |
-| 本地化 | `zh` / `en` 文案，注册进 dsh 的 locale 体系 |
-
-## 📸 截图
+> [English](README.md) | 中文
+
+刻意保持聚焦，只做一件事：**就地回退到任意更早的用户消息**。
+
+| 模式 | 对话 | 工作区文件 |
+| --- | --- | --- |
+| **仅回退对话** | 剪回目标消息之前 | 不动 |
+| **回退对话和代码** | 剪回目标消息之前 | 还原到目标之前的 state（改过的文件写回、之后新建的文件删除） |
+
+回退即**时间回溯**：目标消息及其之后全部内容（agent 回复、工具调用）从模型上下文**与**渲染对话中撤回——不新建会话、不切换窗口——目标消息的文本会回填输入框，可修改后重发。
+
+插件从不改写 append-only 会话日志，从不触碰你的 git 仓库。
+
+## 效果预览
+
+每条用户消息的操作行上多出一个 **↶ 回退** 按钮。点击后弹出模式选择浮层；「回退对话和代码」会先展示待还原/删除的文件清单再确认（目标之后无跟踪变更时不显示该选项，对齐 Claude Code 的 code-restore 可见性）。
 
 <table>
   <tr>
@@ -53,123 +33,71 @@
   </tr>
 </table>
 
-## 工作原理
+在输入框手动输入 `/rewind`（含裸命令）会被**拦截**——提交时弹出临时提示，指向消息旁的 ↶ 按钮。
 
-两部分协同：**对话回退**（同窗口 in-place）与 **checkpoint 文件还原**（Claude Code 式写前备份）。
-
-### 1. 对话回退
-
-插件向会话日志追加一条**空内容标记** `assistant/message`，其 `surfaceOp: { op: 'replace', start, end }` 把目标消息之后的全部 surface 节点替换为标记本身：
-
-- 标记携带 `sourceEventSeqs` 覆盖所有被遮蔽节点，`Session.append` 的 surface 规则校验切割合法性（仅限当前 surface 上的连续区间）。
-- 因为标记**内容为空**，harness 会将其派生为 `null`——永不进入模型上下文、也永不渲染成对话内容。agent 与用户看到的对话都回到目标消息当时的样子。
-- 标记的 **turn 号复用最后一个已开始的回合**（`markerTurnOf`），而不是「最后回合 + 1」：harness 的 agent loop 恰好用 `最后 turn/start + 1` 编号下一条真实回合。若标记也取这个数，日志里就会出现同一 turn 的 `assistant/message` 先于 `turn/start` 的乱序，客户端 conversation 构建器会以 `conversation Context …:turn-tail… received an update before its start Match` 拒绝重放——历史加载失败、整个对话从界面消失（0.2.4 及之前的真实缺陷，已在 0.2.5 修复）。复用已消费的 turn 号则标记只是上一个已完成回合尾部的一次无害追加，永不与新回合冲突。
-- append-only 日志**不被改写**——审计轨迹完整保留每条被撤回的事件，只有模型可见的 surface 被剪掉，下一条请求从目标消息起派生上下文。
-
-若 agent 正在运行（LLM 思考/流式输出），会先强制停止（`cancel({ kind: 'user' })`）并等待 quiescence 再回退；停不下来则中止并报错。
-
-### 2. Checkpoint 文件还原
-
-插件跟踪写类工具：`write`、`edit`、`str_replace_editor`（变更子命令 `create` / `str_replace` / `insert`）：
-
-1. **写前备份**（`tools/execute`，around-dispatch 阶段）：读取目标文件，把解析后的路径与内容放入 pending 表。此阶段只在任何 pre-execute 审批门放行之后运行——所以审批 `ask` 短路（dsh-edit-approval）**无法跳过**备份，被拒绝的调用也不会记录。
-2. **落盘提交**（`tools/post-execute`）：备份按当前轮**锚点消息 seq** 写入 `~/.dsh/rewind-snapshots/<会话>/<锚点 seq>/<callId>.json`。
-3. **还原**（`/rewind @<seq> both`）：锚点 ≥ 目标的每条备份生效——被修改的文件写回其**最早一次**捕获的 before 内容，目标之后新建的文件被删除，符号/硬链接跳过。写入走纯 `node:fs`，不经 fs 服务。
-4. 工具体**抛异常**会跳过 `tools/post-execute`；`tools/result` 兜底清掉 pending，避免内存泄漏。
-
-备份跨 host 重启持久化，每会话有界保留最近 100 组锚点。
-
-## 🔧 故障修复：历史加载失败（`…turn-tail… received an update before its start Match`）
-
-0.2.4 及之前版本在回退**之后继续对话**的场景下会损坏会话的客户端重放：标记的 turn 号
-与下一条真实回合的 `turn/start` 编号冲突，重新打开会话时界面报
-`历史加载失败：conversation Context …:turn-tail… received an update before its start Match（internal）`，
-历史整段消失。0.2.5 起新的回退不再产生该冲突；但**已损坏的会话需要离线修复**（日志是
-append-only 的，不能在内存中改写）。
-
-修复工具**已随 npm 包发布**（`dsh-rewind-repair`）——无需下载源码：
+## 安装
 
 ```sh
-# 1. 先完全退出 dsh web / host（会话处于驻留内存时，磁盘修复会被下次 checkpoint 覆盖）
-# 2. 运行离线修复（扫描 ~/.dsh/sessions 下所有会话，把标记 turn 改回最后一个已开始的回合）
-npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair
-npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair -- --dry-run  # 只预览不写盘
-# 3. 重启 dsh web，损坏的会话即可正常加载历史
+dsh plugin --profile web add dsh-rewind-plugin
 ```
 
-也可以全局安装一次（`npm i -g dsh-rewind-plugin`）后直接运行 `dsh-rewind-repair`；
-源码方式为 `node scripts/repair-markers.mjs`（参数相同）。
-
-工具只改写 `dsh-rewind` 空标记事件的 `data.turn` 字段（保持 seq / 顺序 / zstd 帧结构不变），
-改前自动备份原文件为 `session.jsonl.zstd.bak-<时间戳>`；不改动任何其它事件，可安全重复运行。
+装完重启 `dsh web`（`--profile web`）。
 
-## 📦 安装
+> ⚠️ npm 上的 `dsh-rewind` 属于其他作者，请用 `dsh-rewind-plugin` 安装。
 
-已发布 npm——推荐走 registry 路径。**装完重启 dsh web（`--profile web`）。**
+给贡献者：可从本地 checkout 或 pin 的 commit 安装——`dsh plugin --profile web add /path/to/dsh-rewind` 或 `dsh plugin --profile web add github:SiriLee/dsh-rewind#<sha>`。git 安装首次会失败：pnpm 默认禁止 git 依赖执行构建脚本，需先在 profile 的 `pnpm-workspace.yaml` 加 `allowBuilds`；之后 pnpm 会执行插件的 `prepare`（完整构建）并装入 profile。
 
-> ⚠️ 注意：npm 上的 `dsh-rewind` 属于其他作者，请用 `dsh-rewind-plugin` 安装。
-
-### 方式 A：registry（推荐）
+## 使用
 
-```sh
-dsh plugin --profile web add dsh-rewind-plugin
-```
+1. **hover** 任意你发送过的用户消息——操作行出现 **↶ 回退** 按钮。
+2. **点击它。** 目标即这条消息；小浮层提供两种模式（目标之后没有跟踪的变更时，「回退对话和代码」不显示）。
+3. 回退以一条会话内命令执行；结果消息确认，被撤回消息的文本自动填入输入框，可编辑后重发。
 
-### 方式 B：本地 checkout（作者 / 贡献者）
+↶ 按钮只出现在**当前会话视图**渲染的用户消息行上——回退其他会话前先切换到该会话。回退本身可再回退（标记进入日志），但文件还原动作不再记录新备份。
 
-```sh
-cd dsh-rewind
-npm install      # devDeps 来自 npm registry，无需 harness checkout
-npm run build    # 完整构建：lib/（host ESM + client bundle + .d.ts）
-dsh plugin --profile web add /path/to/dsh-rewind   # link 安装
-```
+## 原理
 
-### 方式 C：GitHub（pin commit，可复现）
+### 1. 对话回退（同窗口就地）
 
-```sh
-dsh plugin --profile web add github:SiriLee/dsh-rewind#<commit-sha>
-```
+插件向会话日志追加一条**空内容标记** `assistant/message`，其 `surfaceOp: { op: 'replace', start, end }` 把目标消息之后的全部 surface 节点替换为标记本身：
 
-首次安装会失败：pnpm 默认禁止 git 依赖执行构建脚本。按 CLI 提示在 profile 的
-`pnpm-workspace.yaml`（如 `$DSH_HOME/profiles/web/pnpm-workspace.yaml`）中加
-`allowBuilds` 后重试；pnpm 随后会执行插件的 `prepare`（完整构建）并装入 profile。
+- 标记携带 `sourceEventSeqs` 覆盖所有被遮蔽节点，`Session.append` 的 surface 规则校验切割合法性（仅限当前 surface 上的连续区间）。
+- 因为标记**内容为空**，harness 会将其派生为 `null`——永不进入模型上下文、也永不渲染成对话内容。agent 与用户看到的对话都回到目标消息当时的样子。
+- 标记的 **turn 号复用最后一个已开始的回合**（`markerTurnOf`），而不是「最后回合 + 1」：harness 恰好用 `最后 turn/start + 1` 编号下一条真实回合。若标记也取这个数，日志里就会出现同一 turn 的 `assistant/message` 先于 `turn/start` 的乱序，客户端 conversation 构建器会以 `conversation Context …:turn-tail… received an update before its start Match` 拒绝重放——历史加载失败、整个对话从界面消失。复用已消费的 turn 号则标记只是上一个已完成回合尾部的一次无害追加，永不与新回合冲突。
+- append-only 日志**不被改写**——审计轨迹完整保留每条被撤回的事件，只有模型可见的 surface 被剪掉，下一条请求从目标消息起派生上下文。
 
-## 使用
+若 agent 正在运行（LLM 思考/流式输出），会先强制停止（`cancel({ kind: 'user' })`）并等待 quiescence 再回退；停不下来则中止并报错。
 
-### 通过消息旁的按钮回退
+### 2. Checkpoint 文件还原
 
-1. **hover** 任意你发送过的用户消息——操作行出现 **↶ 回退** 按钮。
-2. **点击它。** 目标即这条消息（第一步完成）。弹出小浮层（第二步）：
-   - **仅回退对话** —— 把模型上下文剪回这条消息之前；工作区文件不动。
-   - **回退对话和代码** —— 同样的上下文裁剪，并把工作区文件还原到该消息之前的状态。先显示影响清单（待还原/删除的文件），确认后执行。
-   - 目标之后**没有**跟踪的文件变更时，该选项**不显示**（对齐 Claude Code 行为）。
-3. 回退以一条会话内命令执行；结果消息确认（如「已撤回 seq N 及之后内容；还原 M 个文件」），被撤回消息的文本自动填入输入框，可编辑后重发。
+插件跟踪写类工具：`write`、`edit`、`str_replace_editor`（变更子命令 `create` / `str_replace` / `insert`）：
 
-### 回退 = 撤回（时间回溯）
+1. **写前备份**（`tools/execute`，around-dispatch 阶段）：读取目标文件，把解析后的路径与内容放入 pending 表。此阶段只在任何 pre-execute 审批门放行之后运行——审批 `ask` 短路（dsh-edit-approval）**无法跳过**备份，被拒绝的调用也不会记录。若读取失败（如权限错误），该次变更直接不入备份——插件只在日志中警告，**不会阻塞写操作**。
+2. **落盘提交**（`tools/post-execute`）：备份按当前轮**锚点消息 seq** 写入 `~/.dsh/rewind-snapshots/<会话>/<锚点 seq>/<callId>.json`。
+3. **还原**（`/rewind @<seq> both`）：锚点 ≥ 目标的每条备份生效——被修改的文件写回其**最早一次**捕获的 before 内容，目标之后新建的文件被删除，符号/硬链接跳过（它们与另一名字共享 inode，透过一个还原会误伤两个）。写入走纯 `node:fs`，不经 fs 服务——sandbox / 远程 backend 下路径解析可能受限。
+4. 工具体**抛异常**会跳过 `tools/post-execute`；`tools/result` 兜底清掉 pending，避免内存泄漏。
 
-回退到某消息会**撤回该消息及它之后的所有内容**——渲染对话与 agent 上下文都回到这条消息之前。命令结果会说明，且该消息文本会填回输入框供重发。
+备份跨 host 重启持久化，每会话有界保留最近 100 组锚点。
 
-### 手动 `/rewind` 不支持
+## 明确不做的事
 
-`/rewind` 命令仅作为按钮的内部调用通道存在。在输入框手动输入 `/rewind`（含裸命令）会被**拦截**——提交时弹出临时提示，指向消息旁的 ↶ 按钮。
+- **整树 / git-first 快照**——只备份写类工具编辑。`bash`、其他工具与外部程序的修改不在备份内、无法还原：与 Claude Code 相同，官方同样不覆盖，此类回退交由用户 git 处理。
+- **子代理（subagent）的编辑**——不跟踪（同 Claude Code）：子代理运行在自己的会话里，其备份无法被父会话的回退还原。
+- **fork / 分支回退与 `/compact`**——harness 已内置（「在新对话中分支」、compact）。
+- **快捷键**（esc+esc 打开回退菜单）——规划中的后续项。
 
-## 行为细节与限制
+## 与同类项目对比
 
-- 只跟踪**插件运行期间、经写类工具**的变更（`write` / `edit` / `str_replace_editor`）。`bash`、其他工具或外部程序的修改不在备份内、无法还原——与 Claude Code 相同，官方同样不覆盖，此类回退交由用户 git 处理。
-- **子代理（subagent）的编辑不跟踪**——与 Claude Code 相同。子代理运行在自己的会话里，其备份无法被父会话的回退还原；插件直接跳过捕获，而不是记录到永远读不到的位置。
-- 写前备份读取失败时（如权限错误）该次变更不会入备份，`both` 回退无法还原它——插件会在日志中警告，但**不会阻塞写操作**。
-- 文件还原/删除直写**真实本地文件系统**；sandbox / 远程 backend 下路径解析可能受限。
-- 符号链接与硬链接不写入（它们与另一名字共享 inode，还原会互相污染）——跳过并在结果中提示。
-- 回退本身可再回退（标记进入日志），但文件还原动作不再记录新备份。
-- ↶ 按钮只出现在**当前会话视图**渲染的用户消息行上；回退其他会话前先切换到该会话。
-- 目标之后没有跟踪的文件变更时，模式浮层只显示「仅回退对话」（Claude Code 同样隐藏 code-restore 选项）。
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 还有 [Anionex/dsh-turn-rewind](https://github.com/Anionex/dsh-turn-rewind)——同样是回退插件，用户面想法相同（每条消息下挂一个动作，回退对话并还原工作区文件），但路线不同：
 
-## 明确不包含
+| 维度 | dsh-rewind（本项目） | Anionex dsh-turn-rewind |
+| --- | --- | --- |
+| 对话回退 | **同窗口就地**——把模型可见 surface 剪回目标；append-only 日志原封不动 | 在上一 `turn/end` 处**派生新 Session**；原会话永远保留 |
+| 文件还原引擎 | **轻量写前备份**，只跟踪写类工具，纯 `node:fs` 还原 | **Change Ledger**——持久化还原点引擎，带 Git 围栏、审批门、救援点与崩溃对账 |
+| 跟踪范围 | 仅写类工具编辑（同 Claude Code） | 任意 Git 管理文件（要求 Git worktree） |
+| 公共服务 API | 无——聚焦单用途插件 | 有——`ctx.changeLedger` 服务 + `/turn-rewind` HTTP 端点 |
 
-- 快捷键（esc+esc 打开回退菜单）——规划中的后续项。
-- `/compact` —— harness 已内置。
-- fork / 分支回退 —— harness 内置的「在新对话中分支」。
-- 整树 / git-first 快照（覆盖 bash 与外部修改）——**明确不做**，与 Claude Code 原生 rewind 保持一致（官方同样不覆盖，把此类回退交给用户 git）。
+本质区别：dsh-turn-rewind 因保持日志不可变而必须派生新会话；本插件用空标记**就地剪掉**模型可见 surface，于是原对话在同一个窗口继续——这段并不平凡的实现（见[已知问题](#已知问题)）正是 dsh-turn-rewind 绕开的部分。
 
 ## 兼容性
 
@@ -180,63 +108,40 @@ dsh plugin --profile web add github:SiriLee/dsh-rewind#<commit-sha>
 > 本项目与 DeepSeek Harness 均处于开发者预览阶段。可复现环境请 pin 精确版本，
 > 并阅读上述行为说明。
 
+## 已知问题
+
+`v0.2.4` 及之前版本创建的回退在随后继续对话时可能损坏客户端重放（标记 turn 与下一个 `turn/start` 撞号）。离线修复工具**已随 npm 包内置**（`dsh-rewind-repair`）。只影响升级前就已存在的旧会话——全新安装永不触发。
+
+完整步骤见：[docs/troubleshooting.zh.md](docs/troubleshooting.zh.md)
+
+## 安全
+
+本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。文件写入仅在你选择「回退对话和代码」时发生，备份与还原都限定在 `~/.dsh/rewind-snapshots/` 内。不触碰你的 git 仓库，无网络请求，不访问任何凭据。
+
 ## 开发
 
 ```sh
 npm install            # devDeps 来自 npm registry
 npm run typecheck      # tsc 双面编译（host + client）
-npm test               # vitest：rewind / snapshot / hidden / session-cwd / 集成（46 例）
+npm test               # vitest：rewind / snapshot / hidden / session-cwd / 集成
 npm run build          # esbuild：lib/index.js（host ESM）+ lib/client.js（loader 闭包）+ .d.ts
 node scripts/verify-host.mjs   # 端到端验证构建产物（18 项检查）
 ```
 
-`prepare` 执行完整构建，所以 git 安装与 `npm pack` / `npm publish` 总会产出完整的
-`lib/` 与 `LICENSE`。
+`prepare` 执行完整构建，所以 git 安装与 `npm pack` / `npm publish` 总会产出完整的 `lib/` 与 `LICENSE`。
 
-维护者参考：[docs/harness-reference.md](docs/harness-reference.md) 收录 DeepSeek
-Harness 接口文档（子系统文档 + 关键源码索引）。
+维护者：模块地图与 harness 接口参考见 [docs/harness-reference.md](docs/harness-reference.md)；发布步骤见 [docs/release.md](docs/release.md)。
 
 ## 发布
 
-通过 GitHub Actions Trusted Publishing（OIDC，无存储 `NPM_TOKEN`）发布：
+通过 GitHub Actions Trusted Publishing（OIDC，无存储 `NPM_TOKEN`）发布：推送 `v<版本>` tag，CI 即带 Sigstore provenance 发布。
 
 ```sh
-npm version patch && git push origin main --tags   # 触发 .github/workflows/publish.yml
+npm version patch && git push origin main --tags
 ```
 
-- workflow 校验 tag 与 `package.json` 版本一致，跑 typecheck + 测试 + 完整构建 +
-  产物验证，以 `--provenance`（Sigstore）发布，并创建 GitHub Release。**幂等**——
-  已发布的版本会跳过。CI（`.github/workflows/ci.yml`）在每次 push / PR 跑相同检查，
-  外加 `npm pack --dry-run` 校验 tarball 含 `lib/` 与 `LICENSE`。
-- 一次性 npm 侧配置（仓库内无法代做）：打开
-  [dsh-rewind-plugin](https://www.npmjs.com/package/dsh-rewind-plugin) →
-  **settings → Trusted Publisher → Add**，Provider **GitHub Actions** ·
-  Organization or user **`SiriLee`** · Repository **`dsh-rewind`**（GitHub 仓库名，
-  与 npm 包名可不同）· Workflow filename **`publish.yml`** · Environment
-  **留空** · Allowed actions **`npm publish`**。配置好后 push `v<version>` tag
-  即自动发布。
-
-## 目录结构
-
-```
-src/index.ts            host 插件：/rewind 命令 + checkpoint 流水线（tools/execute|post-execute）
-src/rewind.ts           纯函数规划：目标解析、surface 范围、候选列表
-src/snapshot.ts         checkpoint 存储（磁盘写前备份、还原/preview、有界清理）
-src/session-cwd.ts      session-cwd 解析（fs-tools 规则）
-src/client/index.ts     client 插件：消息行 ↶ 按钮 + 手动 /rewind 拦截
-src/client/popover.ts   模式选择浮层（both 模式影响清单确认）
-src/client/hidden.ts    被撤回区间计算（hiddenSeqsOf），纯函数
-src/client/locales.ts   zh / en 文案（LocaleNamespaceMap）
-src/client/styles.ts    注入样式（dsh 设计 token）
-scripts/build.mjs       esbuild：lib/index.js（host ESM）+ lib/client.js（loader 闭包）+ .d.ts
-scripts/verify-host.mjs 端到端验证构建产物（18 项检查）
-tests/                  vitest 套件（rewind / snapshot / hidden / session-cwd / 集成，46 例）
-docs/harness-reference.md   维护者文档：DeepSeek Harness 接口参考
-assets/screenshots/     界面截图
-cordis.patch.yml        bundle patch（挂载双面插件行）
-package.json            dsh.bundle + dsh.client 声明、optional peerDependencies
-```
+一次性 npm 侧配置与完整流程：见 [docs/release.md](docs/release.md)。
 
-## License
+## 许可
 
 [MIT](LICENSE)

package/docs/harness-reference.md

@@ -32,3 +32,26 @@ Also under `docs/` at the repo root: `persistence-catalog.md` (full
 | User bubble rendering | [packages/client/ui-conversation/src/client/chat/MessageItem.tsx](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/ui-conversation/src/client/chat/MessageItem.tsx) |
 | Client `SessionFace` (`command` / `cancel`) | [packages/client/runtime/src/client/contract/session.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/runtime/src/client/contract/session.ts) |
 | Client `PendingWait` (`respond`) | [packages/client/runtime/src/client/sessions/pending.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/runtime/src/client/sessions/pending.ts) |
+
+## Plugin source layout
+
+```
+src/index.ts            host plugin: /rewind command + checkpoint pipeline (tools/execute|post-execute)
+src/rewind.ts           pure planning: target resolution, surface range, candidate listing
+src/snapshot.ts         checkpoint store (disk before-backups, restore/preview, bounded prune)
+src/session-cwd.ts      session-cwd resolution (fs-tools rule)
+src/client/index.ts     client plugin: per-message ↶ button + manual /rewind guard
+src/client/popover.ts   mode-selection popover (both-mode impact confirm)
+src/client/hidden.ts    withdrawn-span computation (hiddenSeqsOf), pure
+src/client/locales.ts   zh / en copy (LocaleNamespaceMap)
+src/client/styles.ts    injected styles (dsh design tokens)
+scripts/build.mjs       esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
+scripts/verify-host.mjs end-to-end host verification (18 checks)
+scripts/repair-markers.mjs  offline marker-turn repair tool (ships as `dsh-rewind-repair`)
+tests/                  vitest suites (rewind / snapshot / hidden / session-cwd / integration)
+docs/                   maintainer docs: harness reference, troubleshooting, release steps
+assets/screenshots/     UI screenshots
+cordis.patch.yml        bundle patch (mounts the dual-face plugin row)
+package.json            dsh.bundle + dsh.client manifests, optional peerDependencies
+```
+

package/docs/release.md

@@ -0,0 +1,90 @@
+# Release
+
+## First release (manual, one-time)
+
+Trusted Publisher can only be configured once the package exists, so the first
+version is published locally:
+
+```sh
+npm login
+npm publish --access public
+```
+
+- If prompted for `EOTP`: complete the browser auth link the CLI prints, or
+  retry with a 6-digit code — `npm publish --otp=<code>`.
+- The first version carries no provenance (local path) — acceptable; every CI
+  release after that publishes with Sigstore/SLSA provenance automatically.
+
+## Configure Trusted Publisher (npmjs.com, one-time)
+
+Open `https://www.npmjs.com/package/dsh-rewind-plugin` → package **settings** →
+**Trusted Publisher**:
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `SiriLee` |
+| Repository | `dsh-rewind` (the GitHub repo, not the npm name) |
+| Workflow filename | `publish.yml` |
+| Environment | empty |
+| Allowed actions | `npm publish` |
+
+## Subsequent releases (CI, automatic)
+
+```sh
+npm version patch
+git push origin main --tags   # triggers .github/workflows/publish.yml
+```
+
+- The workflow verifies the tag matches `package.json`, runs typecheck + tests +
+  a full build + artifact verification, publishes with `--provenance`
+  (Sigstore), and creates a GitHub Release. It is **idempotent** — an already
+  published version is skipped.
+- CI (`.github/workflows/ci.yml`) runs the same checks on every push / PR, plus
+  a `npm pack --dry-run` sanity check that the tarball carries `lib/` and
+  `LICENSE`.
+
+---
+
+# 发布流程
+
+## 首次发布（手动，一次性）
+
+Trusted Publisher 要求**包已存在**才能配置，因此首个版本走本地发布：
+
+```sh
+npm login
+npm publish --access public
+```
+
+- 若提示 `EOTP`（一次性密码）：按 CLI 输出的浏览器认证链接完成认证，或用
+  authenticator 的 6 位码 `npm publish --otp=<code>` 重试。
+- 首个版本无 provenance（本地路径），合规；之后每次 CI 发布自动带
+  Sigstore/SLSA provenance。
+
+## 配置 Trusted Publisher（npmjs.com，一次性）
+
+打开 `https://www.npmjs.com/package/dsh-rewind-plugin` → 包右上角 **settings**
+→ **Trusted Publisher**：
+
+| 字段 | 值 |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `SiriLee` |
+| Repository | `dsh-rewind`（GitHub 仓库名，与 npm 包名可不同） |
+| Workflow filename | `publish.yml` |
+| Environment | 留空 |
+| Allowed actions | `npm publish` |
+
+## 后续发布（CI 自动）
+
+```sh
+npm version patch
+git push origin main --tags   # 触发 .github/workflows/publish.yml
+```
+
+- workflow 校验 tag 与 `package.json` 版本一致，跑 typecheck + 测试 + 完整
+  构建 + 产物验证，以 `--provenance`（Sigstore）发布并创建 GitHub Release。
+  **幂等**——已发布的版本会跳过。
+- CI（`.github/workflows/ci.yml`）在每次 push / PR 跑相同检查，外加
+  `npm pack --dry-run` 校验 tarball 含 `lib/` 与 `LICENSE`。

package/docs/troubleshooting.md

@@ -0,0 +1,39 @@
+# Troubleshooting
+
+[简体中文](troubleshooting.zh.md)
+
+## History load failure: `…turn-tail… received an update before its start Match`
+
+Versions `≤ 0.2.4` corrupted client replay when a rewind was **followed by further
+conversation**: the marker's turn number collided with the next real turn's
+`turn/start`, so reopening the session showed
+
+```
+Failed to load history: conversation Context …:turn-tail… received an update before its start Match (internal)
+```
+
+and the history vanished. Rewinds created from `0.2.5` on no longer produce the
+collision, but **already-corrupted sessions need an offline repair** (the log is
+append-only — it cannot be rewritten in memory).
+
+The repair tool ships **inside the npm package** (`dsh-rewind-repair`) — no
+source checkout needed:
+
+```sh
+# 1. Fully quit dsh web / host first (while a session is resident in memory,
+#    a disk repair is overwritten by the next checkpoint)
+# 2. Run the offline repair (scans every session under ~/.dsh/sessions,
+#    rewriting each marker's turn back to the last started turn)
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair -- --dry-run  # preview only
+# 3. Restart dsh web — the repaired sessions load their history again
+```
+
+Or install it globally once (`npm i -g dsh-rewind-plugin`) and run
+`dsh-rewind-repair` directly; from a source checkout the same tool is
+`node scripts/repair-markers.mjs` (identical flags).
+
+The tool only rewrites the `data.turn` of `dsh-rewind` empty-marker events
+(keeping seqs, order, and the zstd frame structure intact), backs up the original
+file to `session.jsonl.zstd.bak-<timestamp>` before writing, and never touches
+any other event — safe to run repeatedly.

package/docs/troubleshooting.zh.md

@@ -0,0 +1,31 @@
+# 故障修复
+
+[English](troubleshooting.md)
+
+## 历史加载失败：`…turn-tail… received an update before its start Match`
+
+0.2.4 及之前版本在回退**之后继续对话**的场景下会损坏会话的客户端重放：标记的 turn 号
+与下一条真实回合的 `turn/start` 编号冲突，重新打开会话时界面报
+
+```
+历史加载失败：conversation Context …:turn-tail… received an update before its start Match（internal）
+```
+
+历史整段消失。0.2.5 起新的回退不再产生该冲突；但**已损坏的会话需要离线修复**（日志是
+append-only 的，不能在内存中改写）。
+
+修复工具**已随 npm 包发布**（`dsh-rewind-repair`）——无需下载源码：
+
+```sh
+# 1. 先完全退出 dsh web / host（会话处于驻留内存时，磁盘修复会被下次 checkpoint 覆盖）
+# 2. 运行离线修复（扫描 ~/.dsh/sessions 下所有会话，把标记 turn 改回最后一个已开始的回合）
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin -- dsh-rewind-repair -- --dry-run  # 只预览不写盘
+# 3. 重启 dsh web，损坏的会话即可正常加载历史
+```
+
+也可以全局安装一次（`npm i -g dsh-rewind-plugin`）后直接运行 `dsh-rewind-repair`；
+源码方式为 `node scripts/repair-markers.mjs`（参数相同）。
+
+工具只改写 `dsh-rewind` 空标记事件的 `data.turn` 字段（保持 seq / 顺序 / zstd 帧结构不变），
+改前自动备份原文件为 `session.jsonl.zstd.bak-<时间戳>`；不改动任何其它事件，可安全重复运行。