dsh-retrace 0.4.10 → 0.4.11

package/README.md

@@ -2,11 +2,9 @@
 
 # 🧭 dsh-retrace
 
-**Retrace · 回溯** — Recall · Edit-and-resend · Regenerate, plus **in-conversation
-versioning**: a timeline of every rewind, artifact rollback, and a fork map of the
-paths your conversation explored (roadmap). A Harness enhancement plugin for the
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web GUI and
-Desktop app (both share the same Web frontend).
+**Recall · Edit-and-resend · Regenerate**, plus **write-safe** in-conversation
+versioning — the **Agent business layer (production-grade guarantees)** for
+DeepSeek Harness.
 
 [![npm version](https://img.shields.io/npm/v/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
@@ -18,113 +16,73 @@ Desktop app (both share the same Web frontend).
 
 </div>
 
-> ## ⚡ Install in one minute
->
-> **Option A — one command (recommended):** with DeepSeek Harness's `dsh` CLI:
->
-> ```sh
-> dsh plugin --profile desktop add dsh-retrace   # DSH Desktop
-> # or: dsh plugin --profile web add dsh-retrace  # standalone Web
-> ```
->
-> **Option B — downloaded this repo as ZIP (or handing this link to an AI):**
-> unpack it and run `dsh plugin --profile desktop add <folder>` — or install
-> straight from GitHub, no unpacking:
->
-> ```sh
-> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
-> ```
->
-> Follow [📦 Installation](#-installation) → *Manual install* for the exact
-> file-edit steps.
->
-> **Option C — no command line at all:** install the community plugin market
-> once, then install dsh-retrace from its UI:
->
-> ```sh
-> dsh plugin --profile desktop add dshmarket   # one time
-> ```
->
-> Restart, then **Settings → Plugin Market** → search **dsh-retrace** →
-> **Install** (one click). The market lists plugins from the curated
-> [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-> registry; dsh-retrace is listed there.
->
-> > ⚠️ **Restart required after install.** Quit and reopen **DSH Desktop**
-> > (or restart the `dsh` process for a standalone Web deployment) — a running
-> > app keeps the previous bundle in memory and will not hot-reload it.
->
-> Hover any assistant reply → **↩ / ↻**; any user message → **✎** — that's it.
-
-DeepSeek Harness stores every conversation as an **append-only event log**, so there is
-no built-in "undo". `dsh-retrace` brings back the three moves every chat deserves —
-**撤回 (recall)**, **编辑重发 (edit-and-resend)**, **重新生成 (regenerate)** — and then
-goes further: because a recall only rewinds the **context**, while files the agent
-already changed stay changed, retrace versions your conversation **and its artifacts**
-in one place.
-
-Recall / edit **remove the target messages from the conversation view and the model
-context** — that is exactly the effect you see. What stays untouched is the underlying
-**durable transcript**: it remains append-only, old events are never rewritten or deleted,
-and the plugin merely appends one valid replacement event (the same `replace` primitive
-the built-in compaction uses) to rewind the surface — so the log keeps a full audit trail
-of every rewind. On top of that trail, retrace records version boundaries, touched files
-and (optionally) git state, and lets you roll back artifacts or jump back to any point
-in the conversation — all **inside the same session**, no session-switching.
-
-> ✅ **Timeline + artifact rollback are live (0.4.x)** — recall / edit /
-> regenerate, the version timeline, artifact rollback (git-first, snapshot
-> fallback), jump-to-conversation and marker pre-write validation (three-layer
-> contract guard) are all in. The fork map (P2) is in progress per [PLAN.md](./PLAN.md).
+**Recall / edit-and-resend / regenerate** — the three moves every conversation
+deserves. But rewinding is not just "delete a message": DeepSeek Harness stores
+conversations in an append-only event log, so a recall only rewinds the context
+while changed **artifact files stay changed**. dsh-retrace versions the
+conversation **and its artifacts** together, and guarantees **every rewind is
+legal — never dirtying the log, never breaking /compact**.
+
+> 🛡️ **Write safety** · 🔍 **Deep offline checks** · 🔄 **Detect → repair → guard** — see below.
 
 ---
 
-## ✨ Features
+## ⚡ One-minute install
 
-| Action | Where | What happens |
-| --- | --- | --- |
-| **↩ 撤回** (recall) | hover any assistant reply, or the row under any user message | Removes the **whole exchange round** (the input **and** the agent's output, tool rows included) from both the model context and the conversation view; the input text is echoed into the composer so you can re-ask or re-edit immediately. A small transient notice marks the rewind and disappears once you keep typing. |
-| **✎ 编辑重发** (edit & re-send) | row under any user message | The edited round is rewound and the new text is re-sent. By default **only the edited round** is replaced — earlier history stays visible; the optional "fresh conversation" setting rewinds the whole surface (earlier messages then leave the model context, and stay visible in the view as a marker notice by default). A collapsed **"original input"** reference sits right under the new message — click to expand, configurable off. |
-| **↻ 重新生成** (regenerate) | hover any assistant reply | The reply (and everything after it) is rewound and hidden, then the original prompt is re-sent so the agent answers again. |
+> Requires DeepSeek Harness with the `dsh` CLI. **Restart DSH after install** (a running app does not hot-reload).
 
-**Versioning & rollback (live in 0.4.x)** — every rewind is also recorded as a **version**:
+```sh
+dsh plugin --profile desktop add dsh-retrace    # DSH Desktop
+# or Web: dsh plugin --profile web add dsh-retrace
+# or GitHub: dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+# or ZIP: dsh plugin --profile desktop add ~/plugins/dsh-retrace
+```
 
-- 🕘 **Timeline** — a **Versions** tab in the conversation view (on par with the official 对话/轨迹 tabs, since 0.4.2): every version (type, time, message count, file-change badges, summary), pushed live via `session/projection` (no polling), windowed for long histories; event inspection reuses the official Trajectory ledger.
-- ↩️ **Artifact rollback** — each version offers **context-only / artifacts-only / both** rollback with a dry-run preview; git-first (commit-free checkout of the listed paths) with content-addressed snapshot fallback. The rollback itself is recorded as a new version (`restore`) — rollback of a rollback.
-- 🧭 **Jump-to-conversation** — one click from a version to that point in the conversation (auto-loads earlier history, anchor highlight).
-- 🧹 **Bounded storage** — file snapshots keep the most recent N versions (default 50); a throttled background sweep prunes snapshots of truncated versions, keeping long sessions bounded.
+**No command line?** Install the community plugin market once, then find
+**dsh-retrace** in **Settings → Plugin Market** and install it with one click:
 
-**Why it's different**
+```sh
+dsh plugin --profile desktop add dshmarket    # one time
+```
 
-- 🎯 **Whole-round recall** — one click removes the input *and* its output (including tool rows), not just a single bubble.
-- 🖥️ **Web + Desktop** — the same plugin covers both surfaces of DeepSeek Harness.
-- 🔒 **Removed from view & context, not from the log** — recalled/edited messages disappear from the conversation view and the model context, while the durable transcript is never rewritten or deleted; the plugin only appends valid, typed session events (the same `replace` primitive the built-in compaction uses), so the log keeps a full audit trail.
-- 🧠 **View ⇄ context in sync** — the conversation view always reflects exactly what the agent sees.
-- ⚡ **Try in 30 seconds** — the dynamic form installs in your current session with no rebuild.
+After the restart, hover any assistant reply → **↩ / ↻**; any user message → **✎**.
+Full steps in [📦 Installation](#-installation).
 
 ---
 
-## 🚀 Quick start
+## 🛡️ Production-grade guarantees (all live in 0.4.x)
 
-The one-line install is at the top of this page (**⚡ Install in one minute**).
-This section covers the same ground with more detail.
+| | Capability | What it means |
+|---|---|---|
+| 🛡️ | **Write safety** | Every rewind passes a three-layer pre-write contract guard; running agents are auto-stopped (official `cancel`/`whenIdle`); turn-interval markers are wrapped in a temporary step — **rewinds never dirty the log, /compact never breaks** |
+| 🔍 | **Deep offline checks** | Companion `dsh-log-contract` ships 30+ contract rules (token-meter pairing / cross-step references / physical order / inbox replay), validated against real corrupted-session fixtures — it finds the class of problem that makes /compact permanently fail |
+| 🔄 | **Detect → repair → guard** | A watchdog snapshots the log at the first sign of concurrent writes; offline `fix` neutralizes problem markers and clips cross-step references in place; pre-write validation stops bad events before they land |
 
-> Requires DeepSeek Harness with the `dsh` CLI. Installs the plugin as a profile
-> bundle and automatically rebuilds the Web client:
+---
 
-```sh
-# DSH Desktop (desktop profile)
-dsh plugin --profile desktop add dsh-retrace
+## ✨ Features
 
-# standalone Web (`dsh web` / web profile)
-dsh plugin --profile web add dsh-retrace
-```
+| Action | Where | What happens |
+| --- | --- | --- |
+| **↩ Recall** | hover any assistant reply, or the row under any user message | Removes the **whole exchange round** (the input **and** the agent's output, tool rows included) from both the model context and the conversation view; the input text is echoed into the composer so you can re-ask or re-edit immediately. A small transient notice marks the rewind and disappears once you keep typing. |
+| **✎ Edit & re-send** | row under any user message | The edited round is rewound and the new text is re-sent. By default **only the edited round** is replaced — earlier history stays visible; the optional "fresh conversation" setting rewinds the whole surface (earlier messages then leave the model context, and stay visible in the view as a marker notice by default). A collapsed **"original input"** reference sits right under the new message — click to expand, configurable off. |
+| **↻ Regenerate** | hover any assistant reply | The reply (and everything after it) is rewound and hidden, then the original prompt is re-sent so the agent answers again. |
+
+**Versioning & rollback (live in 0.4.x)** — every rewind is also recorded as a **version**:
+
+| | What | |
+|---|---|---|
+| 🕘 | **Timeline** | a **Versions** tab in the conversation view: every version (type, time, message count, file-change badges), pushed live via `session/projection` (no polling), windowed for long histories |
+| ↩️ | **Artifact rollback** | **context-only / artifacts-only / both** with dry-run preview; git-first + content-addressed snapshot fallback; the rollback is itself a new version (`restore`) |
+| 🧭 | **Jump-to-conversation** | one click from a version to that point in the conversation (auto-loads history, anchor highlight) |
+| 🧹 | **Bounded storage** | snapshots keep the most recent N versions (default 50); throttled background sweep prunes truncated ones |
 
-> ⚠️ **Restart after install.** A running app keeps the previously loaded bundle
-> in memory, so **quit and reopen DSH Desktop** (or restart the `dsh` process for
-> a standalone Web deployment) before the plugin activates.
+**Why it's different** (the interaction layer — the guarantees above are the storage layer):
 
-After the restart, hover any assistant reply, or any user message, and use ↩ / ✎ / ↻.
+- 🎯 **Whole-round recall** — removes the input *and* its output (tool rows included), not just a single bubble.
+- 🖥️ **Web + Desktop** — one plugin, both DeepSeek Harness surfaces.
+- 🧠 **View ⇄ context in sync** — the conversation view always reflects exactly what the agent sees.
+- ⚡ **Try in 30 seconds** — the dynamic form installs in your current session with no rebuild.
 
 ---
 
@@ -265,13 +223,13 @@ The dynamic host registers the same operations behind the package-private
    rewound `session.deriveMessages()`.
 3. **Client** (`lib/client.js`) registers:
    - a `user-actions` conversation node under every user message
-     (编辑 / 撤回 row with an inline editor); recall echoes the text into the
+     (an edit/recall row with an inline editor); recall echoes the text into the
      composer,
    - the `recall-marker` node renderer: a notice row that injects CSS hiding
      every shadowed message row from the flow (view and model context stay in
      sync), plus the optional original-input comparison block,
    - the `retrace` entry in the `conversation.chat.assistant-actions`
-     strip (撤回 / 重新生成),
+     strip (recall / regenerate),
    - preference toggles and the retention limit under Settings → General.
 
 > Two different layers are at play: the **durable transcript** (append-only; old
@@ -302,16 +260,21 @@ The dynamic host registers the same operations behind the package-private
 
 ## 🗺️ Roadmap
 
-Built per [PLAN.md](./PLAN.md):
+**What's in today (0.4.x):**
+
+- Recall / edit-and-resend / regenerate, each written through a three-layer
+  **pre-write contract guard** and a safe-edit path (auto-stop the agent, temp-step
+  markers) — rewinds never corrupt the log or break `/compact`.
+- In-session **version timeline** + **artifact rollback** (git-first, snapshot
+  fallback, dry-run preview, jump-to-conversation).
+- **Fork map + session lineage** in the conversation view.
+- **Real-time watchdog** — snapshots the log at the first sign of concurrent writes.
+- Companion **`dsh-log-contract`**: 30+ offline contract rules + in-place repair
+  (`fix --neutralize` / `--clip-crossstep`) for sessions that would fail `/compact`.
 
-- **P1 — Timeline & artifact rollback** ✅ *shipped in 0.4.x*: an in-session version
-  timeline (messages, thinking, touched files), artifact snapshots (git-first,
-  snapshot-fallback, opt-in), rollback with dry-run preview, and jump-to-conversation
-  navigation.
-- **P2 — Fork map** 🔨 *in progress*: a flow graph of the conversation's turns with fork
-  points at every rewind, thinking flow per turn, branch-intent cards, and version
-  comparison.
-- More locales beyond 简体中文 / English.
+**What's next** — see the [public roadmap](./docs/ROADMAP.md) for the agent
+business-layer plan (runtime guard, interruption governance, ecosystem-facing
+interfaces). This README only describes what is already shipped.
 
 ---
 
@@ -359,6 +322,15 @@ and the [issue tracker](https://github.com/yamingmou/dsh-retrace/issues).
 
 Listed on the [dsh-plugin topic](https://github.com/topics/dsh-plugin).
 
+Part of the **Agent business layer (production-grade guarantees)** — see the
+[public roadmap](./docs/ROADMAP.md) for the framework-agnostic layer and how
+dsh-retrace is its DeepSeek Harness implementation. Companion components:
+
+- [**dsh-log-contract**](https://github.com/yamingmou/dsh-log-contract) — the
+  business layer's "doctor": 30+ offline contract rules + in-place repair
+  (`fix --neutralize` / `--clip-crossstep`). Installed automatically as a
+  dependency; also published standalone for direct use.
+
 > **Install straight from GitHub** (no npm registry needed — handy when you
 > hand this repo's link to an AI or want the latest commit):
 >
@@ -389,24 +361,27 @@ DeepSeek Harness community.
 MIT
 
 
-## 🧭 会话日志考古（retrace CLI）
+## 🧭 Session archaeology (`retrace` CLI)
 
-DSH 会话日志持久化了每次工具调用的完整输入输出——数据资产与审计资产。
-`retrace` CLI 提供只读考古能力（复用 dsh-log-contract 0.3.0 的契约与提取）：
+Every tool call's full input/output is persisted in the session log — a data and
+audit asset. The `retrace` CLI provides read-only archaeology (reusing
+dsh-log-contract's contracts and extraction):
 
 ```sh
-retrace index <session>                        # 工具调用索引（A1）
-retrace query <session> --cmd "seed-scale"     # 按命令正则查输出（A1）
-retrace extract <session> --pattern "seed-scale" --out ./found   # 导出输出（A2）
-retrace file-history <session> <path>          # 文件 write/edit 历史版本（A3）
-retrace file-diff <session> <path> 0 5         # 两版本行级 diff（A3）
-retrace lineage <session>                      # 会话 parent 链谱系（A4）
+retrace index <session>                        # tool-call index (A1)
+retrace query <session> --cmd "seed-scale"     # search outputs by command regex (A1)
+retrace extract <session> --pattern "seed-scale" --out ./found   # export outputs (A2)
+retrace file-history <session> <path>          # write/edit history of a file (A3)
+retrace file-diff <session> <path> 0 5         # line diff between two versions (A3)
+retrace lineage <session>                      # parent-chain lineage (A4)
 ```
 
-<session> 为完整日志路径或 sessionId（自动在 ~/.dsh/sessions 查找）。全部只读。
+`<session>` is a full log path or a sessionId (auto-looked-up under
+`~/.dsh/sessions`). All read-only.
 
-**分叉图里的会话谱系（A4,UI）**：Fork map 视图头部展示当前会话的
-`parentSession` 接续链（当前会话 → 父 → 根,`←` 方向）。数据来自
-`GET /api/plugins/retrace/lineage?sessionId=`（只读 header 遍历,带环保护）,
-与 CLI `retrace lineage` 同一语义。这样"这个会话是从哪个会话接着干/分叉出来的"
-在界面上一眼可见——也是分叉图拓扑的元数据源。
+**Session lineage in the fork map (A4, UI)**: the Fork map view header shows the
+current session's `parentSession` chain (session → parent → root, `←` direction).
+Data comes from `GET /api/plugins/retrace/lineage?sessionId=` (read-only header
+walk with cycle protection), the same semantics as the CLI `retrace lineage` —
+so "which session did this one continue/fork from" is visible at a glance, and
+serves as the fork-topology metadata source.

package/README.zh.md

@@ -2,10 +2,8 @@
 
 # 🧭 dsh-retrace
 
-**Retrace · 回溯** —— 在 **撤回 · 编辑重发 · 重新生成** 之上，更进一步：
-为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 对话提供
-**单会话内的版本化**——每一次回退的时间线、产物回退，以及对话走过的分叉路径图（路线图）。
-同时支持 **Web 端** 与 **桌面客户端**（两者共用同一套 Web 前端）。
+**撤回 · 编辑重发 · 重新生成**，加上**写安全**的会话版本化 —— DeepSeek Harness 的
+**Agent 业务层（生产级保证）** 实现。
 
 [![npm version](https://img.shields.io/npm/v/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
@@ -17,54 +15,46 @@
 
 </div>
 
-> ## ⚡ 一分钟安装
->
-> **方式 A —— 一条命令（推荐）：** 需要带 `dsh` CLI 的 DeepSeek Harness：
->
-> ```sh
-> dsh plugin --profile desktop add dsh-retrace   # DSH 桌面版
-> # 或：dsh plugin --profile web add dsh-retrace  # 独立 Web 部署
-> ```
->
-> **方式 B —— 从 GitHub 下载了 ZIP（或把本仓库链接直接丢给 AI）？** 解压到固定位置
-> （如 `~/plugins/dsh-retrace`）后执行 `dsh plugin --profile desktop add ~/plugins/dsh-retrace`；
-> 或**直接从 GitHub 安装，无需解压**：
->
-> ```sh
-> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
-> ```
->
-> 更详细的文件级步骤见 [📦 安装](#-安装) → *手动安装*。
->
-> **方式 C —— 完全没有命令行？** 先装一次社区插件市场，再从市场 UI 一键安装
-> dsh-retrace：
->
-> ```sh
-> dsh plugin --profile desktop add dshmarket   # 只需一次
-> ```
->
-> 重启后进入 **设置 → Plugin Market** → 搜索 **dsh-retrace** → **安装**（一键）。
-> 市场收录自 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-> 精选目录，dsh-retrace 已在其中。
->
-> > ⚠️ **安装后必须重启。** 运行中的应用不会热加载 bundle，请**退出并重新打开
-> > DSH Desktop**（独立 Web 部署则重启 `dsh` 进程）后插件才会生效。
->
-> 重启后悬停任意助手回复 → **↩ / ↻**；任意用户消息 → **✎**，即可使用。
+**撤回 / 编辑重发 / 重新生成** —— 每个会话都该有的三个操作。但回退不只是「撤掉一条
+消息」：DeepSeek Harness 把对话存在 append-only 事件日志里，撤回只回退上下文，改过的
+**产物文件不会自动还原**。dsh-retrace 把对话**和它的产物**一起版本化，并且保证
+**每次回退都合法、不弄脏日志、不破坏 /compact**。
+
+> 🛡️ **写安全** · 🔍 **深层体检** · 🔄 **检测→修复→守护** —— 详见下方「生产级保证」。
+
+---
+
+## ⚡ 一分钟安装
+
+> 需要带 `dsh` CLI 的 DeepSeek Harness；装完**重启 DSH** 生效（运行中的应用不会热加载）。
+
+```sh
+dsh plugin --profile desktop add dsh-retrace    # DSH 桌面版
+# 或 Web 部署：dsh plugin --profile web add dsh-retrace
+# 或从 GitHub 直装：dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+# 或从 ZIP 解压后：dsh plugin --profile desktop add ~/plugins/dsh-retrace
+```
+
+**没有命令行？** 先装一次社区插件市场，再在 **设置 → Plugin Market** 搜
+**dsh-retrace** 一键安装：
+
+```sh
+dsh plugin --profile desktop add dshmarket    # 只需一次
+```
+
+重启后，悬停任意助手回复 → **↩ / ↻**；任意用户消息 → **✎**。详细步骤见
+[📦 安装](#-安装)。
 
-DeepSeek Harness 的对话是「只追加（append-only）」的事件日志，本身没有撤销能力。
-`dsh-retrace` 先为对话补上聊天本该有的三个操作 —— **撤回**、**编辑重发**、
-**重新生成**；再往前一步：撤回只回退了**上下文**，而智能体已经改过的**产物文件**
-不会自动还原——retrace 把对话**和它的产物**放在一起做版本化。
+---
+---
 
-撤回/编辑后，目标消息会**从对话视图和模型上下文中移除**——你看到的「删除」正是这个
-效果。但底层的**持久化日志不会被改写或删除**：它始终保持只追加，旧事件原样保留，
-插件只是在日志末尾追加一条合法的替换事件（与内置压缩使用的 `replace` 原语一致）来
-回退对话表面，因此日志保留每一次回退的完整审计痕迹。在这条痕迹之上，retrace 记录
-版本边界、触碰文件与（可选的）git 状态，支持产物回退与跳转到对话任意位置——全部
-发生在**同一会话内**，不换会话。
+## 🛡️ 生产级保证（0.4.x 全部已上线）
 
-> ✅ **时间线 + 产物回退已上线（0.4.x）** —— 撤回/编辑/重新生成、版本时间线、产物回退（git 优先 + 快照兜底）、跳转对话、marker 写前校验均已可用；分叉图（P2）按 [PLAN.md](./PLAN.md) 推进中。
+| | 能力 | 说明 |
+|---|---|---|
+| 🛡️ | **写安全** | 每次回退过三层写前契约校验；运行中的 agent 自动停止（官方 `cancel`/`whenIdle`）；轮次间 marker 用临时 step 包裹 —— **回退永不弄脏日志，/compact 永不失效** |
+| 🔍 | **深层体检** | 配套 `dsh-log-contract` 30+ 条契约规则（token-meter 配对 / 跨 step 引用 / 物理序 / inbox 重放），用真实损坏会话当测试集 —— 能找出让 /compact 永久失效的那类问题 |
+| 🔄 | **检测→修复→守护** | 看门狗在并发写入第一时间快照日志；离线 `fix` 原地中和问题 marker、裁剪跨 step 引用；写前校验在坏事件落盘前拦住 |
 
 ---
 
@@ -78,44 +68,24 @@ DeepSeek Harness 的对话是「只追加（append-only）」的事件日志，
 
 **版本化与回退（0.4.x 已上线）** —— 每次回退都会被记录为一个**版本**：
 
-- 🕘 **时间线** —— 会话视图新增「版本」Tab（与官方「对话/轨迹」平级，0.4.2 起）：展示每个版本（类型/时间/消息数/文件变更徽标/摘要），经 `session/projection` 推送帧实时更新（零轮询），大列表窗口化渲染；事件原文查看复用官方「轨迹」台账。
-- ↩️ **产物回退** —— 每个版本支持 仅对话 / 仅产物 / 两者 三种回退范围，先干跑预览再执行；git 优先（commit-free checkout 清单路径）+ 内容寻址快照兜底。回退本身记录为新版本（`restore`），可以再回退。
-- 🧭 **跳转对话** —— 从时间线一键跳转到对话对应位置（自动翻页加载更早历史 + 锚点高亮）。
-- 🧹 **存储有界** —— 文件快照只保留最近 N 个版本（默认 50）；节流后台扫掠回收被截断版本的快照，长会话不膨胀。
+| | 能力 | 说明 |
+|---|---|---|
+| 🕘 | **时间线** | 「版本」Tab（与官方「对话/轨迹」平级）：每个版本的类型/时间/消息数/文件变更徽标，经 `session/projection` 推送帧实时更新（零轮询），大列表窗口化 |
+| ↩️ | **产物回退** | 仅对话 / 仅产物 / 两者，先干跑预览再执行；git 优先 + 内容寻址快照兜底；回退本身是新版本（`restore`），可以再回退 |
+| 🧭 | **跳转对话** | 从时间线一键跳转到对应位置（自动翻页加载更早历史 + 锚点高亮） |
+| 🧹 | **存储有界** | 快照只保留最近 N 个版本（默认 50）；节流后台扫掠回收被截断版本 |
+
+**为什么与众不同**（交互层差异——上面的保证是存储层）：
 
 **为什么与众不同**
 
 - 🎯 **整轮撤回** —— 一键移除输入 *和* 它的输出（含工具行），而不只是单条气泡。
 - 🖥️ **Web + Desktop 双端** —— 同一插件覆盖 DeepSeek Harness 两种界面。
-- 🔒 **删除的是视图与上下文，不是日志** —— 被撤回/编辑的消息从对话视图和模型上下文中
-  消失，但持久化日志从不被改写或删除；插件只追加合法、带类型的会话事件（与内置压缩
-  使用的 `replace` 原语一致），日志保留完整审计痕迹。
 - 🧠 **视图 ⇄ 上下文同步** —— 对话视图永远反映智能体真正看到的内容。
 - ⚡ **30 秒上手** —— 动态插件形式无需重建即可在当前会话试用。
 
 ---
 
-## 🚀 快速开始
-
-页首的 **⚡ 一分钟安装** 是最短路径；本节给出同样内容的更详细说明。
-
-> 需要带 `dsh` CLI 的 DeepSeek Harness。以 profile bundle 方式安装，并自动重建 Web 客户端：
-
-```sh
-# DSH Desktop（desktop profile）
-dsh plugin --profile desktop add dsh-retrace
-
-# 独立 Web 部署（`dsh web` / web profile）
-dsh plugin --profile web add dsh-retrace
-```
-
-> ⚠️ **安装后需要重启。** 运行中的应用仍在内存中保留之前加载的 bundle，请**退出并
-> 重新打开 DSH Desktop**（独立 Web 部署则重启 `dsh` 进程）后插件才会生效。
-
-重启后，悬停任意助手回复或用户消息，即可使用 ↩ / ✎ / ↻。
-
----
-
 ## 📦 安装
 
 ### 1. Profile bundle（推荐）
@@ -265,11 +235,15 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
 
 ## 🗺️ 路线图
 
-按 [PLAN.md](./PLAN.md) 推进：
+**当前已具备（0.4.x）：**
 
-- **P1 — 时间线与产物回退** ✅ 已上线（0.4.x）：单会话内的版本时间线（版本/消息/思考/工具节点），产物快照（git 优先 + 快照兜底，可开关），带干跑预览的回退，以及跳转到对话位置；marker 写前校验（三层契约）守护日志。
-- **P2 — 分叉图** 🔨 推进中：对话回合的流程分叉图，每次回退都是分叉点，逐回合思考流，分支意图卡、版本对比。
-- 支持更多语言（当前：简体中文 / English）。
+- 撤回 / 编辑重发 / 重新生成——每次回退都过**三层写前校验**与安全编辑路径（自动停 agent、临时 step 包裹 marker），**不会损坏日志、不会破坏 /compact**。
+- 单会话**版本时间线** + **产物回退**（git 优先 + 快照兜底、干跑预览、跳转对话）。
+- 对话视图内的**分叉图** + **会话谱系**。
+- **实时看门狗**——并发写入第一时间快照日志。
+- 配套 **`dsh-log-contract`**：30+ 条离线契约规则 + 原地修复（`fix --neutralize` / `--clip-crossstep`），能处理会让 /compact 永久失败的会话。
+
+**未来计划**——见 [公开路线图](./docs/ROADMAP.md)（agent 业务层规划：运行时守护、中断治理、生态开放接口）。本 README 只描述已上线的能力。
 
 ---
 
@@ -316,6 +290,13 @@ npm pack --dry-run    # 校验发布文件清单
 
 收录于 [dsh-plugin topic](https://github.com/topics/dsh-plugin)。
 
+**Agent 业务层（生产级保证）** 的一部分——见 [公开路线图](./docs/ROADMAP.md)
+（框架无关的业务层定义，dsh-retrace 是它在 DeepSeek Harness 上的实现）。配套组件：
+
+- [**dsh-log-contract**](https://github.com/yamingmou/dsh-log-contract) —— 业务层的
+  「医生」：30+ 条离线契约规则 + 原地修复（`fix --neutralize` / `--clip-crossstep`）。
+  作为依赖自动安装，也独立发布供直接使用。
+
 > **直接从 GitHub 安装**（无需 npm registry —— 适合把本仓库链接丢给 AI，或想装最新提交）：
 >
 > ```sh
@@ -341,3 +322,27 @@ DeepSeek Harness 插件生态的精选总览见
 ## 📄 License
 
 MIT
+
+---
+
+## 🧭 会话日志考古（retrace CLI）
+
+DSH 会话日志持久化了每次工具调用的完整输入输出——数据资产与审计资产。
+`retrace` CLI 提供只读考古能力（复用 dsh-log-contract 的契约与提取）：
+
+```sh
+retrace index <session>                        # 工具调用索引（A1）
+retrace query <session> --cmd "seed-scale"     # 按命令正则查输出（A1）
+retrace extract <session> --pattern "seed-scale" --out ./found   # 导出输出（A2）
+retrace file-history <session> <path>          # 文件 write/edit 历史版本（A3）
+retrace file-diff <session> <path> 0 5         # 两版本行级 diff（A3）
+retrace lineage <session>                      # 会话 parent 链谱系（A4）
+```
+
+<session> 为完整日志路径或 sessionId（自动在 ~/.dsh/sessions 查找）。全部只读。
+
+**分叉图里的会话谱系（A4, UI）**：Fork map 视图头部展示当前会话的
+`parentSession` 接续链（当前会话 → 父 → 根,`←` 方向）。数据来自
+`GET /api/plugins/retrace/lineage?sessionId=`（只读 header 遍历,带环保护）,
+与 CLI `retrace lineage` 同一语义。这样「这个会话是从哪个会话接着干/分叉出来的」
+在界面上一眼可见——也是分叉图拓扑的元数据源。

package/lib/client.bundle.js

@@ -1136,7 +1136,9 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   };
   const ROW_H = 64;
   const list = versions ?? [];
-  const visible = list.slice(Math.max(0, Math.floor(scrollTop / ROW_H) - 2), Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2));
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+  const visibleEnd = Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+  const visible = list.slice(visibleStart, visibleEnd);
   (0, import_react.useEffect)(() => {
     if (list.length === 0) return void 0;
     return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-timeline-list"));
@@ -1175,11 +1177,11 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop)
     }, [
       (0, import_react.createElement)("div", { key: "spacer", style: { height: `${list.length * ROW_H}px`, position: "relative" } }, [
-        visible.map((record) => (0, import_react.createElement)(VersionRow, {
+        visible.map((record, i) => (0, import_react.createElement)(VersionRow, {
           key: record.versionId,
           record,
           t,
-          top: list.indexOf(record) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onPreview: () => requestPreview(record),
           onTrajectory: () => switchToViewTab("trajectory"),
           onJump: () => jump(record.boundarySeq)
@@ -1301,10 +1303,9 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
     return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-fork-list"));
   }, [nodes.length]);
   const ROW_H = 56;
-  const visible = nodes.slice(
-    Math.max(0, Math.floor(scrollTop / ROW_H) - 2),
-    Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
-  );
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+  const visibleEnd = Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+  const visible = nodes.slice(visibleStart, visibleEnd);
   return (0, import_react.createElement)("div", { className: "dsh-rt-view" }, [
     (0, import_react.createElement)("div", { key: "head", className: "dsh-rt-timeline-head" }, [
       (0, import_react.createElement)("span", { key: "title", className: "dsh-rt-timeline-title" }, t("fork.title")),
@@ -1341,13 +1342,13 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop)
     }, [
       (0, import_react.createElement)("div", { key: "spacer", style: { height: `${nodes.length * ROW_H}px`, position: "relative" } }, [
-        visible.map((node) => (0, import_react.createElement)(ForkRow, {
+        visible.map((node, i) => (0, import_react.createElement)(ForkRow, {
           key: node.seq,
           node,
           boundary: boundaryBySeq.get(node.seq),
           markerText: markerBySeq.get(node.seq),
           t,
-          top: nodes.indexOf(node) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onJump: () => jumpToAnchor(store, node.seq)
         }))
       ])

package/lib/client.js

@@ -1485,7 +1485,11 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   // ---- windowed list (uniform rows, zero-dep) ----
   const ROW_H = 64
   const list = versions ?? []
-  const visible = list.slice(Math.max(0, Math.floor(scrollTop / ROW_H) - 2), Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2))
+  // 2026-08-30 渲染卡死修复（与 ForkView 同）：带起始索引切片，渲染用索引算 top——
+  // 原 `list.indexOf(record)` 是 O(N²)（每可见行线性查找），大会话渲染风暴。
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2)
+  const visibleEnd = Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
+  const visible = list.slice(visibleStart, visibleEnd)
 
   // Same view-area height trap as the fork list (see bindListHeight).
   useEffect(() => {
@@ -1534,11 +1538,11 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop),
     }, [
       createElement('div', { key: 'spacer', style: { height: `${list.length * ROW_H}px`, position: 'relative' } }, [
-        visible.map((record) => createElement(VersionRow, {
+        visible.map((record, i) => createElement(VersionRow, {
           key: record.versionId,
           record,
           t,
-          top: list.indexOf(record) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onPreview: () => requestPreview(record),
           onTrajectory: () => switchToViewTab('trajectory'),
           onJump: () => jump(record.boundarySeq),
@@ -1702,11 +1706,14 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
   }, [nodes.length])
 
   // ---- windowed list (uniform rows, zero-dep; same as the versions view) ----
+  // 2026-08-30 渲染卡死修复：visible 改为带起始索引的切片，渲染时直接用索引算
+  // top——原实现 `nodes.indexOf(node)` 在每次渲染对每个可见节点做 O(N) 线性查找
+  // （2047 节点 × ~15 可见行 = 每次渲染 ~30K 次比较，React 重渲染风暴 → 转圈、
+  // Renderer CPU 27.7%，526f1835 打开卡死）。其他会话节点少不触发，仅大会话暴露。
   const ROW_H = 56
-  const visible = nodes.slice(
-    Math.max(0, Math.floor(scrollTop / ROW_H) - 2),
-    Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2),
-  )
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2)
+  const visibleEnd = Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
+  const visible = nodes.slice(visibleStart, visibleEnd)
 
   return createElement('div', { className: 'dsh-rt-view' }, [
     createElement('div', { key: 'head', className: 'dsh-rt-timeline-head' }, [
@@ -1745,13 +1752,13 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop),
     }, [
       createElement('div', { key: 'spacer', style: { height: `${nodes.length * ROW_H}px`, position: 'relative' } }, [
-        visible.map((node) => createElement(ForkRow, {
+        visible.map((node, i) => createElement(ForkRow, {
           key: node.seq,
           node,
           boundary: boundaryBySeq.get(node.seq),
           markerText: markerBySeq.get(node.seq),
           t,
-          top: nodes.indexOf(node) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onJump: () => jumpToAnchor(store, node.seq),
         })),
       ]),

package/lib/dynamic-client.js

@@ -1142,7 +1142,9 @@ return {
         };
         const ROW_H = 64;
         const list = versions ?? [];
-        const visible = list.slice(Math.max(0, Math.floor(scrollTop / ROW_H) - 2), Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2));
+        const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+        const visibleEnd = Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+        const visible = list.slice(visibleStart, visibleEnd);
         (0, import_react.useEffect)(() => {
           if (list.length === 0) return void 0;
           return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-timeline-list"));
@@ -1181,11 +1183,11 @@ return {
             onScroll: (event) => setScrollTop(event.target.scrollTop)
           }, [
             (0, import_react.createElement)("div", { key: "spacer", style: { height: `${list.length * ROW_H}px`, position: "relative" } }, [
-              visible.map((record) => (0, import_react.createElement)(VersionRow, {
+              visible.map((record, i) => (0, import_react.createElement)(VersionRow, {
                 key: record.versionId,
                 record,
                 t,
-                top: list.indexOf(record) * ROW_H,
+                top: (visibleStart + i) * ROW_H,
                 onPreview: () => requestPreview(record),
                 onTrajectory: () => switchToViewTab("trajectory"),
                 onJump: () => jump(record.boundarySeq)
@@ -1307,10 +1309,9 @@ return {
           return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-fork-list"));
         }, [nodes.length]);
         const ROW_H = 56;
-        const visible = nodes.slice(
-          Math.max(0, Math.floor(scrollTop / ROW_H) - 2),
-          Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
-        );
+        const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+        const visibleEnd = Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+        const visible = nodes.slice(visibleStart, visibleEnd);
         return (0, import_react.createElement)("div", { className: "dsh-rt-view" }, [
           (0, import_react.createElement)("div", { key: "head", className: "dsh-rt-timeline-head" }, [
             (0, import_react.createElement)("span", { key: "title", className: "dsh-rt-timeline-title" }, t("fork.title")),
@@ -1347,13 +1348,13 @@ return {
             onScroll: (event) => setScrollTop(event.target.scrollTop)
           }, [
             (0, import_react.createElement)("div", { key: "spacer", style: { height: `${nodes.length * ROW_H}px`, position: "relative" } }, [
-              visible.map((node) => (0, import_react.createElement)(ForkRow, {
+              visible.map((node, i) => (0, import_react.createElement)(ForkRow, {
                 key: node.seq,
                 node,
                 boundary: boundaryBySeq.get(node.seq),
                 markerText: markerBySeq.get(node.seq),
                 t,
-                top: nodes.indexOf(node) * ROW_H,
+                top: (visibleStart + i) * ROW_H,
                 onJump: () => jumpToAnchor(store, node.seq)
               }))
             ])

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-retrace",
   "description": "Retrace · 回溯 — Recall, edit-and-resend, regenerate, and conversation/artifact versioning (timeline, rollback, fork map) for DeepSeek Harness — Web and Desktop",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",