dsh-rewind-plugin 0.4.1 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +176 -0
- package/README.md +101 -101
- package/lib/client.js +1 -1
- package/lib/index.js +471 -22
- package/lib/types/client/candidates.d.ts +5 -4
- package/lib/types/index.d.ts +1 -1
- package/lib/types/rewind.d.ts +3 -2
- package/lib/types/snapshot.d.ts +229 -4
- package/package.json +3 -3
- package/README.zh.md +0 -159
package/README.en.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# dsh-rewind
|
|
2
|
+
|
|
3
|
+
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).
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/dsh-rewind-plugin)
|
|
6
|
+
[](https://github.com/SiriLee/dsh-rewind/blob/main/LICENSE)
|
|
7
|
+
[](https://www.npmjs.com/package/dsh-rewind-plugin)
|
|
8
|
+
|
|
9
|
+
> English | [中文](README.md)
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
- **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**.
|
|
14
|
+
- **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.
|
|
15
|
+
- **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.
|
|
16
|
+
- **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.
|
|
17
|
+
|
|
18
|
+
## Preview
|
|
19
|
+
|
|
20
|
+
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**.
|
|
21
|
+
|
|
22
|
+
<table>
|
|
23
|
+
<tr>
|
|
24
|
+
<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>
|
|
25
|
+
<td align="center"><img src="assets/screenshots/mode-popover.png" width="440" alt="Mode-selection popover"><br><sub>Mode-selection popover</sub></td>
|
|
26
|
+
</tr>
|
|
27
|
+
<tr>
|
|
28
|
+
<td align="center"><img src="assets/screenshots/impact-list.png" width="440" alt="Impact list"><br><sub>"Conversation and code" impact list</sub></td>
|
|
29
|
+
<td align="center"><img src="assets/screenshots/rewind-candidates.png" width="440" alt="/rewind candidate picker"><br><sub>/rewind candidate picker</sub></td>
|
|
30
|
+
</tr>
|
|
31
|
+
</table>
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
dsh plugin --profile web add dsh-rewind-plugin
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
> ⚠️ The npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
|
|
40
|
+
|
|
41
|
+
## Usage
|
|
42
|
+
|
|
43
|
+
1. Find the user message you want to rewind to in the conversation, or type `/rewind` to open the candidate picker.
|
|
44
|
+
2. **Select it.** A small popover offers the two modes ("conversation and code" is only shown when there are restorable changes after the target).
|
|
45
|
+
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.
|
|
46
|
+
|
|
47
|
+
**Keyboard**: both the candidate picker and the mode popover support ↑↓ to move, Enter to confirm, Esc to cancel/back.
|
|
48
|
+
|
|
49
|
+
<details>
|
|
50
|
+
<summary><b>Edge notes</b></summary>
|
|
51
|
+
|
|
52
|
+
- Rewinds can be repeated — with no limit on stage or count.
|
|
53
|
+
- A rewind itself **cannot be undone**, but the withdrawn content stays in the session log and can be recovered by manually editing it.
|
|
54
|
+
- **Interruptions rewind too** — a `steering` interruption message the model hasn't read yet is also a valid rewind target.
|
|
55
|
+
- **A rewind interrupts the running turn** — to execute the rewind safely.
|
|
56
|
+
|
|
57
|
+
</details>
|
|
58
|
+
|
|
59
|
+
## Why it stands out
|
|
60
|
+
|
|
61
|
+
Compared with the common approaches, here is the trade-off this plugin makes on "rewind":
|
|
62
|
+
|
|
63
|
+
| Dimension | Common approach | This plugin |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| Conversation rewind | Fork / branch a new conversation | **In-place rewind** — no new session, no window switch |
|
|
66
|
+
| 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) |
|
|
67
|
+
| Dependencies | Often needs a Git repo or a full snapshot engine | **None** — no git required, works on any directory |
|
|
68
|
+
| Storage footprint | Whole-tree snapshots take space | **Lightweight** — only files touched by write tools are stored, persisted on disk |
|
|
69
|
+
|
|
70
|
+
## How it works
|
|
71
|
+
|
|
72
|
+
The mechanism is the same lineage as Claude Code's checkpointing (Claude Code's file history is also per-file records plus a re-scan of tracked files at each message — not a whole-tree snapshot). This plugin implements the same semantics on dsh:
|
|
73
|
+
|
|
74
|
+
### 1. Conversation rewind: in place, without losing the log
|
|
75
|
+
|
|
76
|
+
The session log is **append-only** — the plugin never rewrites history. A rewind appends an **empty-content marker** that "shadows out" everything after the target message, so both the model and the UI only see the part before it:
|
|
77
|
+
|
|
78
|
+
- The marker is **empty** — it never enters the model context and never renders as conversation content; what you and the agent see is exactly how the conversation looked at the target;
|
|
79
|
+
- Because this is "shadowing" rather than "deleting", **every withdrawn event stays in the log**, fully auditable;
|
|
80
|
+
- The marker reuses the number of the last-started turn and carries its own step frame — so dsh's own machinery (log replay, `/compact`, resume preflight) recognizes it correctly and never mistakes it for a real message (these compatibility details are pinned by dedicated probe tests, see [Development](#development)).
|
|
81
|
+
|
|
82
|
+
<details>
|
|
83
|
+
<summary><b>Implementation details (for maintainers)</b></summary>
|
|
84
|
+
|
|
85
|
+
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:
|
|
86
|
+
|
|
87
|
+
- The marker carries `sourceEventSeqs` covering every shadowed node, and `Session.append`'s surface rules validate the cut (a contiguous range on the current surface).
|
|
88
|
+
- Because the marker is **empty**, the harness derives it to `null` — it never enters the model context and never renders as conversation content.
|
|
89
|
+
- 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.
|
|
90
|
+
- 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.
|
|
91
|
+
|
|
92
|
+
</details>
|
|
93
|
+
|
|
94
|
+
A running turn (LLM thinking / streaming) is force-stopped first and the rewind waits for quiescence; if it can't stop, the rewind is aborted with an error.
|
|
95
|
+
|
|
96
|
+
### 2. File restore: before-backup + external-change tracking + disk reconciliation
|
|
97
|
+
|
|
98
|
+
The plugin tracks the write-class tools — `write`, `edit`, `str_replace_editor`:
|
|
99
|
+
|
|
100
|
+
1. **Before-backup**: the original content of every file is stored **before** it is written (captured after any approval gate lets the call through — an approval short-circuit cannot 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 across restarts** (100 most recent groups per session).
|
|
101
|
+
2. **External changes are tracked 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.
|
|
102
|
+
3. **Real disk reconciliation before restoring**: at rewind time the plugin reads each file's current content and compares it with 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 have zero side effects). Symlinks / hard links are skipped to avoid collateral damage.
|
|
103
|
+
|
|
104
|
+
<details>
|
|
105
|
+
<summary><b>Implementation details (for maintainers)</b></summary>
|
|
106
|
+
|
|
107
|
+
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**.
|
|
108
|
+
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`).
|
|
109
|
+
3. **External-change tracking** (`reconcileTracked`): at each message boundary the plugin re-scans tracked files and records a `recheck-<anchor>-<hash>` entry anchored to the boundary message whenever the on-disk state differs from the last seen state; the first sighting of a path always records (the first boundary after a restart unconditionally records the current state — redundant but correct, mirroring Claude Code's resume-then-re-stat behavior).
|
|
110
|
+
4. **Restore** (`/rewind @<seq> both`): `planRestore` probes the disk per record — `before === null` (the file did not exist at the target) plans a delete only when the file currently exists (an absent file already matches); `before === 'X'` plans a restore only when the current content differs from X (identical content is a no-op, idempotent); a probe failure is treated conservatively as differing (never silently skipped). Execution: restore = create parent dir + write back content; delete = remove the file (an already-absent file is tolerated as a no-op); symlinks / hard links are skipped (they share an inode with another name; restoring through one would clobber both); failures are recorded per file and never abort the pass.
|
|
111
|
+
5. A tool body that **throws** skips `tools/post-execute`; a `tools/result` safety net clears the pending capture so nothing leaks in memory. Backups persist across host restarts; `prune` keeps the newest 100 anchor groups per session.
|
|
112
|
+
|
|
113
|
+
</details>
|
|
114
|
+
|
|
115
|
+
## What it deliberately does NOT do
|
|
116
|
+
|
|
117
|
+
This plugin deliberately stays lightweight and focused on one thing — "conversation rewind". The following are **out of its scope**:
|
|
118
|
+
|
|
119
|
+
- **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).
|
|
120
|
+
- **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.
|
|
121
|
+
- **Fork / branch rewind** — the harness already provides this ("branch in new chat"); no need to reinvent it.
|
|
122
|
+
|
|
123
|
+
## Compatibility
|
|
124
|
+
|
|
125
|
+
- Node.js `^22.19.0 || >=24.0.0`.
|
|
126
|
+
- DeepSeek Harness web profile (`dsh --profile web`); peer `@deepseek-ai/*` packages are resolved by the harness at runtime.
|
|
127
|
+
|
|
128
|
+
> [!WARNING]
|
|
129
|
+
> This project and DeepSeek Harness are both in developer preview. Pin exact
|
|
130
|
+
> versions in reproducible environments and review the behavior notes above.
|
|
131
|
+
|
|
132
|
+
## Client contract
|
|
133
|
+
|
|
134
|
+
Third-party DOM plugins that need to know which transcript rows a rewind
|
|
135
|
+
withdrew should consume the stable, locale-independent helpers exported from
|
|
136
|
+
`dsh-rewind-plugin/client` — never parse
|
|
137
|
+
`outcome.text`. The `data-dsh-rewind-hidden` attribute marks withdrawn rows
|
|
138
|
+
(observational only). Details: [docs/client-contract.md](docs/client-contract.md).
|
|
139
|
+
|
|
140
|
+
## Known issues
|
|
141
|
+
|
|
142
|
+
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.
|
|
143
|
+
2. **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/troubleshooting.md](docs/troubleshooting.md)).
|
|
144
|
+
3. **Rewinds from `≤ v0.3.3`** — compaction (`/compact`) is unavailable for those sessions. Newer versions are compatible; for affected old sessions, start a new session.
|
|
145
|
+
|
|
146
|
+
## Security
|
|
147
|
+
|
|
148
|
+
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.
|
|
149
|
+
|
|
150
|
+
## Development
|
|
151
|
+
|
|
152
|
+
```sh
|
|
153
|
+
npm install # devDeps from the npm registry
|
|
154
|
+
npm run typecheck # tsc on all three surfaces (host + client + client-test)
|
|
155
|
+
npm test # vitest: all unit and compatibility suites
|
|
156
|
+
npm run build # esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
|
|
157
|
+
node scripts/verify-host.mjs # end-to-end verification of the built artifact
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`prepare` runs the full build, so git installs and `npm pack` / `npm publish` always produce a complete `lib/` and the `LICENSE`.
|
|
161
|
+
|
|
162
|
+
Maintainers: the module map and harness interface reference live in [docs/harness-reference.md](docs/harness-reference.md).
|
|
163
|
+
|
|
164
|
+
## Release
|
|
165
|
+
|
|
166
|
+
Releases go out through GitHub Actions Trusted Publishing (OIDC, no stored `NPM_TOKEN`): push a `v<version>` tag and CI publishes with Sigstore provenance.
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
npm version patch && git push origin main --tags
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
One-time npm-side setup and the full workflow details: [docs/release.md](docs/release.md).
|
|
173
|
+
|
|
174
|
+
## License
|
|
175
|
+
|
|
176
|
+
[MIT](LICENSE)
|
package/README.md
CHANGED
|
@@ -1,173 +1,173 @@
|
|
|
1
1
|
# dsh-rewind
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消息**——同窗口内完成，不新建分支、不换窗口，可一并还原工作区文件（完整 Claude Code `/rewind` 语义）。
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/dsh-rewind-plugin)
|
|
6
6
|
[](https://github.com/SiriLee/dsh-rewind/blob/main/LICENSE)
|
|
7
|
+
[](https://www.npmjs.com/package/dsh-rewind-plugin)
|
|
7
8
|
|
|
8
|
-
> English
|
|
9
|
+
> [English](README.en.md) | 中文
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
刻意聚焦、保持极简，只做一件事：**就地回退到任意远的用户消息**，还能**顺手还原改过的文件**。
|
|
11
12
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
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.
|
|
18
|
-
|
|
19
|
-
The plugin never rewrites the append-only session log and never touches your git repository.
|
|
13
|
+
- **回退 = 时间回溯**——目标消息及其之后的全部内容（agent 回复、工具调用）同时从**模型上下文**和**渲染对话**中撤回，不新建会话、不切换窗口；目标消息文本会回填输入框，改完可重发。**在原理上就真正无感、便捷**。
|
|
14
|
+
- **轻量工作区备份**——行为对齐 Claude Code：只跟踪写文件的工具，写前做轻量备份并**落盘持久化**，不依赖、也不触碰 git 仓库。一个轻型插件，即拥有**完备的智能体回退能力**。
|
|
15
|
+
- **信息安全优先**——插件从不删改会话日志（append-only），从不真正删除你的任何对话；文件还原限定在插件自己的备份目录。
|
|
16
|
+
- **完备测试系统**——单元、探针、端到端主机验证，覆盖兼容性探测、日志重放、续接、跨重启等场景；随 harness 升级持续维护，确保功能稳定。
|
|
20
17
|
|
|
21
|
-
##
|
|
18
|
+
## 效果预览
|
|
22
19
|
|
|
23
|
-
|
|
20
|
+
每条用户消息的操作行都有一个 **↶ 回退** 按钮。点击后弹出模式选择浮层——「**仅回退对话**」或「**回退对话和代码**」，后者会先展示文件变更清单再确认。还可以通过 **`/rewind` 命令**和**快捷键**便捷地选择和回退。
|
|
24
21
|
|
|
25
22
|
<table>
|
|
26
23
|
<tr>
|
|
27
|
-
<td align="center"><img src="assets/screenshots/rewind-button.png" width="440" alt="
|
|
28
|
-
<td align="center"><img src="assets/screenshots/mode-popover.png" width="440" alt="
|
|
24
|
+
<td align="center"><img src="assets/screenshots/rewind-button.png" width="440" alt="用户消息旁的 ↶ 回退按钮"><br><sub>用户消息旁的 ↶ 回退按钮</sub></td>
|
|
25
|
+
<td align="center"><img src="assets/screenshots/mode-popover.png" width="440" alt="模式选择浮层"><br><sub>模式选择浮层</sub></td>
|
|
29
26
|
</tr>
|
|
30
27
|
<tr>
|
|
31
|
-
<td align="center"><img src="assets/screenshots/impact-list.png" width="440" alt="
|
|
32
|
-
<td align="center"><img src="assets/screenshots/rewind-candidates.png" width="440" alt="/rewind
|
|
28
|
+
<td align="center"><img src="assets/screenshots/impact-list.png" width="440" alt="影响清单"><br><sub>「回退对话和代码」影响清单</sub></td>
|
|
29
|
+
<td align="center"><img src="assets/screenshots/rewind-candidates.png" width="440" alt="/rewind 候选面板"><br><sub>/rewind 候选面板</sub></td>
|
|
33
30
|
</tr>
|
|
34
31
|
</table>
|
|
35
32
|
|
|
36
|
-
##
|
|
33
|
+
## 安装
|
|
37
34
|
|
|
38
35
|
```sh
|
|
39
36
|
dsh plugin --profile web add dsh-rewind-plugin
|
|
40
37
|
```
|
|
41
38
|
|
|
42
|
-
|
|
39
|
+
> ⚠️ npm 上的 `dsh-rewind` 属于其他作者，请用 `dsh-rewind-plugin` 安装。
|
|
43
40
|
|
|
44
|
-
|
|
41
|
+
## 使用
|
|
45
42
|
|
|
46
|
-
|
|
43
|
+
1. 在对话中找到要回退的那条用户消息，或输入 `/rewind` 打开候选列表选择。
|
|
44
|
+
2. **选中它。** 小浮层提供两种模式（「回退对话和代码」仅在目标之后有可还原的变更时显示）。
|
|
45
|
+
3. 回退立即生效：对话回到目标消息当时的样子，被撤回消息的文本自动填入输入框——改完直接重发。
|
|
47
46
|
|
|
48
|
-
|
|
47
|
+
**键盘操作**：候选列表与模式浮层均支持 ↑↓ 移动、Enter 确认、Esc 取消/返回。
|
|
49
48
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
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.
|
|
49
|
+
<details>
|
|
50
|
+
<summary><b>边界说明</b></summary>
|
|
53
51
|
|
|
54
|
-
|
|
52
|
+
- 回退可以反复进行——没有阶段或次数限制。
|
|
53
|
+
- 回退本身**无法撤销**，但被撤回的内容仍保留在会话日志中，可手动编辑日志恢复。
|
|
54
|
+
- **插话也能回退**——模型尚未读取的 `steering` 插话消息，同样可作为回退目标。
|
|
55
|
+
- **回退会打断当前正在运行的回合**——确保回退安全执行。
|
|
55
56
|
|
|
56
|
-
|
|
57
|
+
</details>
|
|
57
58
|
|
|
58
|
-
|
|
59
|
+
## 本插件的优势
|
|
59
60
|
|
|
60
|
-
|
|
61
|
+
和常见的几种做法相比，本插件在"回退"这件事上的取舍：
|
|
61
62
|
|
|
62
|
-
|
|
63
|
+
| 维度 | 常见做法 | 本插件 |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| 对话回退 | Fork 分支新建对话 | **就地回退**——不新建会话、不切窗口，便捷回退 |
|
|
66
|
+
| 文件还原 | 无还原功能 / git 管理或完整快照 | **写前轻量备份**——写文件前自动存原内容，一键还原（对齐 Claude Code） |
|
|
67
|
+
| 依赖 | 常依赖 Git 仓库或完整快照引擎 | **无依赖**——不依赖 git，普通目录即可用 |
|
|
68
|
+
| 存储开销 | 整树快照占空间大 | **轻量**——只存被写工具改动过的文件，落盘持久化 |
|
|
63
69
|
|
|
64
|
-
|
|
70
|
+
## 原理
|
|
65
71
|
|
|
66
|
-
|
|
67
|
-
- 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.
|
|
68
|
-
- 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.
|
|
69
|
-
- 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.
|
|
70
|
-
- 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.
|
|
72
|
+
机制与 Claude Code 的 checkpointing 同源（Claude Code 的文件历史也是逐文件记录 + 每条消息重扫已跟踪文件，并非整树快照）。本插件实现的是同一套语义，落在 dsh 上：
|
|
71
73
|
|
|
72
|
-
|
|
74
|
+
### 1. 对话回退：怎么做到"就地"又不丢日志
|
|
73
75
|
|
|
74
|
-
|
|
76
|
+
对话日志是**只追加**的——插件绝不改写历史。回退的做法：往日志里追加一条**空内容标记**，用它把目标消息之后的全部对话内容"遮蔽"掉，让模型和界面都只看到目标之前的部分：
|
|
75
77
|
|
|
76
|
-
|
|
78
|
+
- 标记本身是**空的**——不进入模型上下文、不渲染成任何对话内容，agent 和你看到的对话就是目标消息当时的样子；
|
|
79
|
+
- 因为只是"遮蔽"而非"删除"，**被撤回的每一条事件都完整留在日志里**，审计可追溯；
|
|
80
|
+
- 标记复用"最后一个已开始的回合"的编号，并自带独立的步骤框架——让 dsh 自身的机制（日志重放、`/compact` 压缩、续接检查）都能正确识别它，不会误认为真实对话（这些兼容细节经过专门的探针测试固化，见[开发](#开发)一节）。
|
|
77
81
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
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.
|
|
81
|
-
4. A tool body that **throws** skips `tools/post-execute`; a `tools/result` safety net clears the pending capture so nothing leaks in memory.
|
|
82
|
+
<details>
|
|
83
|
+
<summary><b>实现细节（给维护者）</b></summary>
|
|
82
84
|
|
|
83
|
-
|
|
85
|
+
插件向会话日志追加一条空内容标记 `assistant/message`，其 `surfaceOp: { op: 'replace', start, end }` 把目标消息之后的全部 surface 节点替换为标记本身：
|
|
84
86
|
|
|
85
|
-
|
|
87
|
+
- 标记携带 `sourceEventSeqs` 覆盖所有被遮蔽节点，`Session.append` 的 surface 规则校验切割合法性（仅限当前 surface 上的连续区间）。
|
|
88
|
+
- 因为标记**内容为空**，harness 会将其派生为 `null`——永不进入模型上下文、也永不渲染成对话内容。
|
|
89
|
+
- 标记的 **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 号则标记只是上一个已完成回合尾部的一次无害追加，永不与新回合冲突。
|
|
90
|
+
- 标记自带**幽灵步骤框架**——自己的 `step/start` … `step/end`，step 号取该回合未用过的新号（`markerStepOf`）：harness 的 token-meter 重放要求每条 `assistant/message` 位于打开的 step 内，裸标记则会让该会话的 `/compact` 失效。
|
|
86
91
|
|
|
87
|
-
|
|
88
|
-
- **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.
|
|
89
|
-
- **Fork / branch rewind and `/compact`** — the harness already provides these ("branch in new chat", compact).
|
|
92
|
+
</details>
|
|
90
93
|
|
|
91
|
-
|
|
94
|
+
若 agent 正在运行（LLM 思考/流式输出），会先强制停止并等待安静下来再回退；停不下来则中止并报错。
|
|
92
95
|
|
|
93
|
-
|
|
96
|
+
### 2. 文件还原：写前备份 + 外部变更追踪 + 磁盘比对
|
|
94
97
|
|
|
95
|
-
|
|
96
|
-
| --- | --- | --- |
|
|
97
|
-
| 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 |
|
|
98
|
-
| 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 |
|
|
99
|
-
| Tracked-change scope | Only write-class tool edits (like Claude Code) | Any Git-managed file (Git worktree required) |
|
|
100
|
-
| Public service API | No — a focused single-purpose plugin | Yes — `ctx.changeLedger` service + `/turn-rewind` HTTP endpoint |
|
|
98
|
+
插件跟踪写文件的工具——`write`、`edit`、`str_replace_editor`：
|
|
101
99
|
|
|
102
|
-
|
|
100
|
+
1. **写前备份**：每次写文件**之前**先把原内容存下来（在审批门放行之后捕获——审批短路不会漏备份，被拒绝的调用也不会记录；读取失败只警告、不阻塞写操作）。备份按当前对话轮次分组，**跨重启保留**（每会话保留最近 100 组）。
|
|
101
|
+
2. **外部变更也追踪**：每条用户消息边界会重新检查所有已跟踪文件——外部编辑或删除（写工具从没参与过的改动）同样被记录下来，回退时一并还原。
|
|
102
|
+
3. **还原前真实磁盘比对**：回退时实时读取文件当前内容，与目标状态比对——**只操作真正不一致的文件**：改过的写回最早备份、目标之后新建的删除、已一致的一律跳过（重复回退零副作用）。符号/硬链接跳过，避免误伤。
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
<details>
|
|
105
|
+
<summary><b>实现细节（给维护者）</b></summary>
|
|
105
106
|
|
|
106
|
-
-
|
|
107
|
-
-
|
|
107
|
+
1. **写前备份**（`tools/execute`，around-dispatch 阶段）：读取目标文件，把解析后的路径与内容放入 pending 表。此阶段只在任何 pre-execute 审批门放行之后运行——审批 `ask` 短路（dsh-edit-approval）**无法跳过**备份，被拒绝的调用也不会记录。若读取失败（如权限错误），该次变更直接不入备份——插件只在日志中警告，**不会阻塞写操作**。
|
|
108
|
+
2. **落盘提交**（`tools/post-execute`）：备份按当前轮**锚点消息 seq** 写入 `~/.dsh/rewind-snapshots/<会话>/<锚点 seq>/<callId>.json`。
|
|
109
|
+
3. **外部变更追踪**（`reconcileTracked`）：消息边界处重扫已跟踪文件，磁盘状态与上次记录不同则记录一条 `recheck-<锚点>-<hash>` 条目（锚定边界消息）；首见路径必记（重启后第一次边界无条件记录当前状态——冗余但正确，对应 Claude Code 的 resume 后 restat 行为）。
|
|
110
|
+
4. **还原**（`/rewind @<seq> both`）：`planRestore` 对每条记录实时探测磁盘——`before === null`（目标时不存在）仅当文件当前存在才计划删除（已缺失即已达成）；`before === 'X'` 仅当当前内容 ≠ X 才计划还原（一致即 no-op，幂等）；探测失败保守视为不一致（绝不静默跳过）。执行时 restore = 建父目录 + 写回内容，delete = 删文件（已不存在容忍为 no-op）；符号/硬链接跳过（与另一名字共享 inode，透过一个还原会误伤两个）；失败逐文件记录、不中止整轮。
|
|
111
|
+
5. 工具体**抛异常**会跳过 `tools/post-execute`；`tools/result` 兜底清掉 pending，避免内存泄漏。备份跨 host 重启持久化，`prune` 每会话有界保留最近 100 组锚点。
|
|
108
112
|
|
|
109
|
-
>
|
|
110
|
-
> This project and DeepSeek Harness are both in developer preview. Pin exact
|
|
111
|
-
> versions in reproducible environments and review the behavior notes above.
|
|
113
|
+
</details>
|
|
112
114
|
|
|
113
|
-
##
|
|
115
|
+
## 明确不做的事
|
|
114
116
|
|
|
115
|
-
|
|
116
|
-
withdrew should consume the stable, locale-independent helpers exported from
|
|
117
|
-
`dsh-rewind-plugin/client` (`hiddenSeqsOf`, `targetSeqOfArgs`) — never parse
|
|
118
|
-
`outcome.text`. The `data-dsh-rewind-hidden` attribute marks withdrawn rows
|
|
119
|
-
(observational only). Details: [docs/client-contract.md](docs/client-contract.md).
|
|
117
|
+
本插件刻意保持轻量、聚焦"对话回退"这一件事，以下场景**不属于它的职责**：
|
|
120
118
|
|
|
121
|
-
|
|
119
|
+
- **整树 / Git 级快照**——只跟踪写类工具编辑 + 已跟踪文件的外部改动，从未被工具碰过的文件不还原。需要 Git 工作树级的完整快照回退时，请交给专门的快照工具（或你的 git）。
|
|
120
|
+
- **子代理的编辑**——不追踪（同 Claude Code）：子代理运行在自己的会话里，其备份无法由父会话的回退还原，只会在磁盘上残留。
|
|
121
|
+
- **fork / 分支回退**——harness 已内置「在新对话中分支」，不重复造轮子。
|
|
122
122
|
|
|
123
|
-
|
|
123
|
+
## 兼容性
|
|
124
124
|
|
|
125
|
-
|
|
125
|
+
- Node.js `^22.19.0 || >=24.0.0`。
|
|
126
|
+
- DeepSeek Harness web 配置档（`dsh --profile web`）；peer `@deepseek-ai/*` 包由 harness 运行时解析。
|
|
126
127
|
|
|
127
|
-
|
|
128
|
+
> [!WARNING]
|
|
129
|
+
> 本项目与 DeepSeek Harness 均处于开发者预览阶段。可复现环境请 pin 精确版本，
|
|
130
|
+
> 并阅读上述行为说明。
|
|
131
|
+
|
|
132
|
+
## 客户端契约
|
|
133
|
+
|
|
134
|
+
需要获知哪些转录行被回退撤回的第三方 DOM 插件，应使用 `dsh-rewind-plugin/client` 导出的稳定、与本地化无关的纯函数，切勿解析 `outcome.text`。`data-dsh-rewind-hidden` 属性标记被撤回的行（仅观测性）。
|
|
135
|
+
详见：[docs/client-contract.zh.md](docs/client-contract.zh.md)。
|
|
128
136
|
|
|
129
|
-
|
|
137
|
+
## 已知问题
|
|
130
138
|
|
|
131
|
-
|
|
139
|
+
1. **导出的日志是完整内容**——回退只是把消息从模型上下文和视图中移除，`/export` 导出的会话日志包含**已撤回的消息**。本插件无法改动导出。
|
|
140
|
+
2. **v0.2.4 及更早版本**回退过的会话，继续对话后可能加载历史失败。可安装 v0.3.3 及之前版本的随附修复工具处理（[完整步骤](docs/troubleshooting.zh.md)）。
|
|
141
|
+
3. **v0.3.3 及更早版本**回退过的会话，压缩对话（compact）不可用。新版本已兼容；受影响的旧会话建议新建会话。
|
|
132
142
|
|
|
133
|
-
##
|
|
143
|
+
## 安全
|
|
144
|
+
|
|
145
|
+
本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和代码」时被改写，备份与还原都限定在 `~/.dsh/rewind-snapshots/` 内。不触碰你的 git 仓库，无网络请求，不访问任何凭据。删除 `~/.dsh/rewind-snapshots/` 仅清除文件备份（对话回退不受影响），插件会自动重建。
|
|
146
|
+
|
|
147
|
+
## 开发
|
|
134
148
|
|
|
135
149
|
```sh
|
|
136
|
-
npm install # devDeps
|
|
137
|
-
npm run typecheck # tsc
|
|
138
|
-
npm test # vitest
|
|
139
|
-
npm run build # esbuild
|
|
140
|
-
node scripts/verify-host.mjs #
|
|
150
|
+
npm install # devDeps 来自 npm registry
|
|
151
|
+
npm run typecheck # tsc 三面编译（host + client + client-test）
|
|
152
|
+
npm test # vitest：全部单元与兼容性测试套件
|
|
153
|
+
npm run build # esbuild：lib/index.js（host ESM）+ lib/client.js（loader 闭包）+ .d.ts
|
|
154
|
+
node scripts/verify-host.mjs # 端到端验证构建产物
|
|
141
155
|
```
|
|
142
156
|
|
|
143
|
-
`npm
|
|
144
|
-
([docs/compat-audit.md](docs/compat-audit.md)): scenario-generated logs drive the
|
|
145
|
-
real harness packages (token-meter, compaction, session-stats/title/goal folds,
|
|
146
|
-
resume preflight) through rewind markers and assert the compatibility
|
|
147
|
-
invariants. A failing probe is a discovered incompatibility, not a mock
|
|
148
|
-
artifact. One finding is recorded: **R-OPENSTEP** — a log carrying an
|
|
149
|
-
unclosed `step/start` (crash leftover) makes any later step activity,
|
|
150
|
-
including a rewind's ghost-step frame, break token-meter replay (and
|
|
151
|
-
/compact). Harness `0.1.1-rc.2` fixes the crash path (`interruptedTurnClosers`
|
|
152
|
-
closes leftover step/turn boundaries on load). A plugin-side guard was tried
|
|
153
|
-
and reverted: it produced false positives on real session logs (rewind
|
|
154
|
-
feature broken), so the plugin deliberately ships no guard — the residual
|
|
155
|
-
risk (runtime-produced unclosed steps) is accepted.
|
|
156
|
-
|
|
157
|
-
`prepare` runs the full build, so git installs and `npm pack` / `npm publish` always produce a complete `lib/` and the `LICENSE`.
|
|
157
|
+
`prepare` 执行完整构建，所以 git 安装与 `npm pack` / `npm publish` 总会产出完整的 `lib/` 与 `LICENSE`。
|
|
158
158
|
|
|
159
|
-
|
|
159
|
+
维护者：模块地图与 harness 接口参考见 [docs/harness-reference.md](docs/harness-reference.md)
|
|
160
160
|
|
|
161
|
-
##
|
|
161
|
+
## 发布
|
|
162
162
|
|
|
163
|
-
|
|
163
|
+
通过 GitHub Actions Trusted Publishing（OIDC，无存储 `NPM_TOKEN`）发布：推送 `v<版本>` tag，CI 即带 Sigstore provenance 发布。
|
|
164
164
|
|
|
165
165
|
```sh
|
|
166
166
|
npm version patch && git push origin main --tags
|
|
167
167
|
```
|
|
168
168
|
|
|
169
|
-
|
|
169
|
+
一次性 npm 侧配置与完整流程：见 [docs/release.md](docs/release.md)。
|
|
170
170
|
|
|
171
|
-
##
|
|
171
|
+
## 许可
|
|
172
172
|
|
|
173
173
|
[MIT](LICENSE)
|
package/lib/client.js
CHANGED
|
@@ -92,7 +92,7 @@ function hiddenSeqsOf(snap) {
|
|
|
92
92
|
|
|
93
93
|
// src/client/candidates.ts
|
|
94
94
|
var PREVIEW_CHARS = 80;
|
|
95
|
-
var DEFAULT_CANDIDATE_LIMIT =
|
|
95
|
+
var DEFAULT_CANDIDATE_LIMIT = 100;
|
|
96
96
|
function messagePreviewOf(message) {
|
|
97
97
|
const text = message.content.map((block) => block.type === "text" && typeof block.text === "string" ? block.text : "").join("").replace(/\s+/g, " ").trim();
|
|
98
98
|
return text.length <= PREVIEW_CHARS ? text : `${text.slice(0, PREVIEW_CHARS - 1)}\u2026`;
|