dsh-retrace 0.3.0

package/HUMANS.txt

@@ -0,0 +1,18 @@
+/* HUMANS.TXT */
+/* dsh-retrace — an open-source plugin for DeepSeek Harness */
+
+/* Team */
+OfferKuai — AI Job Application Assistant
+Founder: Zhaofeng (Yaming)
+Contact: contact@offerkuai.com
+Website: https://www.offerkuai.com
+
+/* Mission */
+Users need results, not repeated conversations.
+
+/* Acknowledgements */
+Thanks to all test users for their feedback and suggestions
+Thanks to the open-source community for their technical contributions
+
+/* License */
+MIT — see LICENSE

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dsh-retrace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+<div align="center">
+
+# 🧭 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. 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).
+
+[![npm version](https://img.shields.io/npm/v/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
+[![License: MIT](https://img.shields.io/npm/l/dsh-retrace)](https://github.com/azmavethy/dsh-retrace/blob/main/LICENSE)
+[![DSH plugin](https://img.shields.io/badge/DSH-plugin-4A90D9)](https://github.com/topics/dsh-plugin)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/azmavethy/dsh-retrace/pulls)
+
+**English** · [简体中文](./README.zh.md)
+
+</div>
+
+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.
+
+> 🚧 **Roadmap in progress** — the **P0 version-data service is live** (version
+> boundaries, touched-file windows, content-addressed artifact snapshots,
+> `session/projection` push + HTTP query channels, config wiring). Timeline &
+> artifact rollback (P1) and the fork map (P2) are being built per [PLAN.md](./PLAN.md).
+> Recall / edit / regenerate are live today.
+
+---
+
+## ✨ Features
+
+| 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 old message and its reply are rewound and hidden. By default the conversation **starts fresh** (earlier messages are hidden too and excluded from context); the edited text is sent and the agent answers. 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. |
+
+**Why it's different**
+
+- 🎯 **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.
+
+---
+
+## 🚀 Quick start
+
+> 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
+
+# standalone Web (`dsh web` / web profile)
+dsh plugin --profile web add dsh-retrace
+```
+
+> ⚠️ **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.
+
+That's it — after the restart, hover any assistant reply, or any user message,
+and use ↩ / ✎ / ↻.
+
+---
+
+## 📦 Installation
+
+### 1. Profile bundle (recommended)
+
+The package declares a `dsh.bundle` manifest, so it installs through the official
+plugin path into any profile:
+
+```sh
+dsh plugin --profile <name> add dsh-retrace
+```
+
+> ⚠️ **Restart required.** The install writes the new files and re-renders the
+> profile composition, but a running app does **not** hot-reload bundles — quit
+> and reopen **DSH Desktop** (or restart the `dsh` process for a standalone Web
+> deployment) to load the plugin. To uninstall:
+> `dsh plugin --profile <name> remove dsh-retrace` (then restart again).
+
+It also shows up in [dsh-market](https://github.com/dsh-market/dsh-market) for
+one-click install from inside Settings (same restart applies).
+
+### 2. Manual install (no `dsh` CLI)
+
+The same result with plain file edits and `pnpm` — exactly the steps
+`dsh plugin add` performs for you:
+
+1. Open the profile manifest (defaults: `~/.dsh/profiles/desktop` on DSH
+   Desktop, `~/.dsh/profiles/web` for standalone Web) and add **both** the
+   dependency and the bundle-layer entry:
+
+   ```json
+   {
+     "dependencies": {
+       "dsh-retrace": "^0.2.0"
+     },
+     "dsh": {
+       "profile": {
+         "bundles": [
+           "@deepseek-ai/dsh-base",
+           "@deepseek-ai/dsh-web-app",
+           "dsh-retrace"
+         ]
+       }
+     }
+   }
+   ```
+
+   (Keep whatever entries your profile already has; only add the two
+   `dsh-retrace` lines.)
+
+2. Install inside the profile directory:
+
+   ```sh
+   cd ~/.dsh/profiles/<name> && pnpm install
+   ```
+
+3. Restart DSH Desktop / the `dsh` process (see above).
+
+For local development, point the dependency at a checkout instead of the
+registry: `"dsh-retrace": "file:/path/to/dsh-retrace"` — or let
+`dsh` do it: `dsh plugin --profile <name> add /path/to/dsh-retrace`.
+
+### 3. npm package + composition (classic)
+
+```sh
+npm i dsh-retrace
+```
+
+Add the package to the harness composition (`cordis.yml` of the app/deployment you use):
+
+```yaml
+- name: 'dsh-retrace'
+```
+
+The client half is picked up automatically from the package's `dsh.client` metadata and
+bundled into the Web client (a client-module rebuild happens automatically when the
+composition changes). The Host half registers the same-origin HTTP route
+`/api/plugins/retrace/*` for the browser UI.
+
+### 4. Dynamic plugin (current session — no install, no rebuild)
+
+Use the **dynamic** entries shipped in the package. In the session where you want the
+feature:
+
+1. Open the plugin editor and define a new plugin from `lib/dynamic-host.js`
+   (Host half) and `lib/dynamic-client.js` (Client half).
+2. Approve and run the Client half.
+3. Done — hover any assistant reply, or any user message, and use ↩ / ✎ / ↻.
+
+The dynamic host registers the same operations behind the package-private
+`harness.handle` RPC (`retrace.recall` / `retrace.editAndResend` /
+`retrace.regenerate`).
+
+---
+
+## ⚙️ Settings → General
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| **编辑后显示原提问对照** | on | A collapsed "original input" reference under the re-sent message showing the **most recent** replaced text (reference only — never sent to the model). |
+| **编辑后从新对话开始** | on | After editing, hide earlier messages too so the conversation looks like a fresh start (the whole surface is rewound before re-sending). |
+
+---
+
+## 🧠 How it works
+
+```
+ durable transcript (append-only)          model context & view
+ ┌────────────────────────────────┐        ┌──────────────────┐
+ │ ... target message             │        │  … target message │
+ │     ↓ shadow span              │        │       ↓ rewind    │
+ │ [target … last surface node]   │ ─────▶ │  (empty replace   │
+ │     ↳ one replacement          │        │   = context cut)  │
+ │       assistant/message (empty)│        └──────────────────┘
+ │     ↳ optional original-input  │        agent.followup(new prompt)
+ └────────────────────────────────┘        → next turn rebuilds request
+```
+
+1. **Host core** (`lib/host-core.js`, zero runtime imports) locates the target
+   message in the session's live surface, computes the shadow span
+   `[message … last surface node]`, and appends one replacement
+   `assistant/message` with an **empty** body — a valid surface node that
+   derives to *no* model message, so the LLM context simply rewinds.
+2. **Edit / regenerate** additionally call `agent.followup(...)` with the
+   (new) prompt text; the agent's next turn builds its request from the
+   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
+     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 (撤回 / 重新生成),
+   - two preference toggles under Settings → General.
+
+> Two different layers are at play: the **durable transcript** (append-only; old
+> events are never rewritten or deleted) and the **model-visible surface** (rewound
+> by an appended replacement event). So the old events stay in the log as an audit
+> trail — but they are **synchronized out of both the model context and the visible
+> conversation**, and the view always reflects what the agent actually sees.
+> Persistence, projections and the transcript remain consistent because the plugin
+> only appends valid, typed session events.
+
+---
+
+## ⚠️ Requirements & limitations
+
+- Only **user messages** can be edited; recall works on user and assistant
+  messages. Tool results are shadowed along with the recalled range but are not
+  themselves recall targets.
+- The agent must be **idle**: while a reply is streaming you must stop it
+  (⏹) before recalling or editing. The Host rejects with `agent-busy`
+  otherwise.
+- Recall/edit operate on the **active model surface**: a message that was
+  already compacted away or previously recalled is rejected
+  (`target-shadowed`).
+- Regenerate re-sends only the **text** of the original prompt; prompts that
+  carried images fall back to the text-only content.
+
+---
+
+## 🗺️ Roadmap
+
+Built per [PLAN.md](./PLAN.md):
+
+- **P1 — Timeline & artifact rollback**: 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**: 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.
+
+---
+
+## 🛠️ Development
+
+```sh
+# structure
+lib/host-core.js       # transport-neutral host logic (no imports)
+lib/index.js           # published Host: harness RPC + HTTP route
+lib/client.js          # client SOURCE (React via import; pluggable transport)
+lib/client.bundle.js   # BUILT client bundle — the self-registering loader entry
+                       # (`window.__ModuleLoader__.load`) served by client-modules
+lib/dynamic-host.js    # GENERATED dynamic Host half (from lib/host-core.js)
+lib/dynamic-client.js  # GENERATED dynamic Client half (from lib/client.js)
+scripts/build-client.mjs      # bundle lib/client.js → lib/client.bundle.js
+scripts/generate-dynamic.mjs  # generate both dynamic entries from the canonical sources
+scripts/check-dynamic.mjs     # syntax-check the dynamic entries (function bodies)
+test/                 # vitest suite: host-core ops + generated-entry smoke tests
+.github/workflows/    # CI (syntax + build-sync + tests) and npm publish (v* tags)
+cordis.patch.yml      # dsh.bundle profile patch layer
+```
+
+```sh
+pnpm install          # install dev dependencies (vitest, esbuild)
+pnpm check            # syntax-check sources AND the generated dynamic entries
+pnpm build            # regenerate lib/dynamic-*.js + lib/client.bundle.js
+pnpm test             # run the host-core unit tests
+npm pack --dry-run    # verify the published file list
+```
+
+> ⚠️ **Generated files.** `lib/dynamic-host.js`, `lib/dynamic-client.js` and
+> `lib/client.bundle.js` are built artifacts generated from `lib/host-core.js`
+> and `lib/client.js` — never edit them by hand. CI fails when a committed
+> artifact is stale (`git diff --exit-code`), so run `pnpm build` before
+> committing. The dynamic client reuses the same client source as the published
+> one and only swaps the transport (`host.call` vs the HTTP route) via
+> `__setMessageEditorWire`.
+
+PRs and issues are welcome — see [CONTRIBUTING](./CONTRIBUTING.md) (coming soon)
+and the [issue tracker](https://github.com/azmavethy/dsh-retrace/issues).
+
+---
+
+## 📚 Ecosystem
+
+Listed on the [dsh-plugin topic](https://github.com/topics/dsh-plugin) and
+installable from [dsh-market](https://github.com/dsh-market/dsh-market). For a
+curated overview of the DeepSeek Harness plugin ecosystem, see
+[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin).
+
+---
+
+## 👥 Team
+
+Built by the [OfferKuai](https://www.offerkuai.com) team — an AI job application
+assistant on a mission that "users need results, not repeated conversations".
+Founder: Zhaofeng (Yaming). This plugin is released as open source for the
+DeepSeek Harness community.
+
+## 📄 License
+
+MIT

package/README.zh.md

@@ -0,0 +1,284 @@
+<div align="center">
+
+# 🧭 dsh-retrace
+
+**Retrace · 回溯** —— 在 **撤回 · 编辑重发 · 重新生成** 之上,更进一步:
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 对话提供
+**单会话内的版本化**——每一次回退的时间线、产物回退、以及对话走过的分叉路径图。
+同时支持 **Web 端** 与 **桌面客户端**(两者共用同一套 Web 前端)。
+
+[![npm version](https://img.shields.io/npm/v/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
+[![License: MIT](https://img.shields.io/npm/l/dsh-retrace)](https://github.com/azmavethy/dsh-retrace/blob/main/LICENSE)
+[![DSH plugin](https://img.shields.io/badge/DSH-plugin-4A90D9)](https://github.com/topics/dsh-plugin)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/azmavethy/dsh-retrace/pulls)
+
+**简体中文** · [English](./README.md)
+
+</div>
+
+DeepSeek Harness 的对话是「只追加（append-only）」的事件日志，本身没有撤销能力。
+`dsh-retrace` 先为对话补上聊天本该有的三个操作 —— **撤回**、**编辑重发**、
+**重新生成**;再往前一步:撤回只回退了**上下文**,而智能体已经改过的**产物文件**
+不会自动还原——retrace 把对话**和它的产物**放在一起做版本化。
+
+撤回/编辑后，目标消息会**从对话视图和模型上下文中移除**——你看到的"删除"正是这个
+效果。但底层的**持久化日志不会被改写或删除**：它始终保持只追加，旧事件原样保留，
+插件只是在日志末尾追加一条合法的替换事件（与内置压缩使用的 `replace` 原语一致）来
+回退对话表面，因此日志保留每一次回退的完整审计痕迹。在这条痕迹之上，retrace 记录
+版本边界、触碰文件与（可选的）git 状态，支持产物回退与跳转到对话任意位置——全部
+发生在**同一会话内**，不换会话。
+
+> 🚧 **路线图进行中** —— 时间线与产物回退（P1）、分叉图（P2）正在按
+> [PLAN.md](./PLAN.md) 开发;撤回/编辑/重新生成当前已可用。
+
+---
+
+## ✨ 功能
+
+| 操作 | 入口 | 效果 |
+| --- | --- | --- |
+| **↩ 撤回** | 悬停任意助手回复；或用户消息下方的操作行 | **移除整轮对话**（该条输入及其对应的输出、工具行一并消失），从模型上下文与对话视图中同步清除，并把输入原文**回显到输入框**方便立即修改后重发；一条短暂提示标记回退点，你继续输入后自动消失。 |
+| **✎ 编辑重发** | 用户消息下方的操作行 | 回退并隐藏旧消息及其回复。默认**从新对话开始**（此前的消息一并隐藏、不再进入上下文），发送修改后的文本让智能体作答；新消息下方有一个折叠的「原提问」对照，点击展开、可配置关闭。 |
+| **↻ 重新生成** | 悬停任意助手回复 | 回退并隐藏该回复及其后内容，重新发送原提问，让智能体重新作答。 |
+
+**为什么与众不同**
+
+- 🎯 **整轮撤回** —— 一键移除输入 *和* 它的输出（含工具行），而不只是单条气泡。
+- 🖥️ **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（推荐）
+
+包声明了 `dsh.bundle` 清单，可通过官方插件路径安装到任意 profile：
+
+```sh
+dsh plugin --profile <name> add dsh-retrace
+```
+
+> ⚠️ **安装后需要重启。** 安装会写入新文件并重新生成 profile 组合，但运行中的应用
+> **不会**热加载 bundle —— 请**退出并重新打开 DSH Desktop**（独立 Web 部署则重启
+> `dsh` 进程）来加载插件。卸载：`dsh plugin --profile <name> remove
+> dsh-retrace`（卸载后同样需要重启）。
+
+同时可在 [dsh-market](https://github.com/dsh-market/dsh-market) 里一键安装
+（安装后同样需要重启）。
+
+### 2. 手动安装（不依赖 `dsh` CLI）
+
+用纯文件编辑 + `pnpm` 装进同一个 profile —— 也就是 `dsh plugin add` 帮你做的那些步骤：
+
+1. 打开 profile 清单（默认位置：DSH Desktop 为 `~/.dsh/profiles/desktop`，
+   独立 Web 为 `~/.dsh/profiles/web`），同时加入依赖**和** bundle 层条目：
+
+   ```json
+   {
+     "dependencies": {
+       "dsh-retrace": "^0.2.0"
+     },
+     "dsh": {
+       "profile": {
+         "bundles": [
+           "@deepseek-ai/dsh-base",
+           "@deepseek-ai/dsh-web-app",
+           "dsh-retrace"
+         ]
+       }
+     }
+   }
+   ```
+
+   （保留 profile 原有条目，只需新增 `dsh-retrace` 这两处。）
+
+2. 在 profile 目录里安装：
+
+   ```sh
+   cd ~/.dsh/profiles/<name> && pnpm install
+   ```
+
+3. 重启 DSH Desktop / `dsh` 进程（见上文）。
+
+本地开发时，可以把依赖指向本地检出目录而不是注册表：
+`"dsh-retrace": "file:/路径/to/dsh-retrace"` —— 或者交给 `dsh`：
+`dsh plugin --profile <name> add /路径/to/dsh-retrace`。
+
+### 3. npm 包 + 组合文件（经典方式）
+
+```sh
+npm i dsh-retrace
+```
+
+在所使用的应用/部署的 `cordis.yml` 组合文件中加入一行普通插件条目：
+
+```yaml
+- name: 'dsh-retrace'
+```
+
+Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户端（组合变化时会自动
+重建客户端模块）；Host 半区为浏览器 UI 注册同源 HTTP 路由 `/api/plugins/retrace/*`。
+
+### 4. 动态插件（当前会话，免安装、免重建）
+
+包内提供了两个自包含的动态入口：
+
+1. 打开插件编辑界面，用 `lib/dynamic-host.js`（Host 半区）和
+   `lib/dynamic-client.js`（Client 半区）新建插件；
+2. 批准并运行 Client 半区；
+3. 完成 —— 悬停任意助手回复或用户消息，即可使用 ↩ / ✎ / ↻。
+
+动态 Host 通过 `harness.handle` 注册同一组操作
+（`retrace.recall` / `retrace.editAndResend` / `retrace.regenerate`）。
+
+---
+
+## ⚙️ 设置 → 通用
+
+| 设置项 | 默认 | 说明 |
+| --- | --- | --- |
+| **编辑后显示原提问对照** | 开 | 重发消息下方的折叠「原输入」引用，显示**最近一次**被替换的原文（仅作对照，不会进入模型上下文）。 |
+| **编辑后从新对话开始** | 开 | 编辑后连此前的消息也一并隐藏，让对话看起来像从新消息重新开始（重发前回退整个表面）。 |
+
+---
+
+## 🧠 工作原理
+
+```
+ 持久化日志（只追加）                     模型上下文与视图
+ ┌────────────────────────────────┐     ┌──────────────────┐
+ │ ... 目标消息                    │     │  … 目标消息       │
+ │     ↓ 阴影区间                  │     │       ↓ 回退      │
+ │ [目标 … 最后一个表面节点]        │ ───▶│  (空 replace      │
+ │     ↳ 追加一条替换型             │     │   = 上下文截断)   │
+ │       assistant/message（空）   │     └──────────────────┘
+ │     ↳ 可选「原提问」对照          │     agent.followup(新提示)
+ └────────────────────────────────┘     → 下一轮基于回退后的历史重建请求
+```
+
+1. **Host 核心**（`lib/host-core.js`，零运行时依赖）：在会话的活跃表面中定位目标
+   消息，计算阴影区间 `[消息 … 最后一个表面节点]`，追加一条**空内容**的替换型
+   `assistant/message` —— 空助手消息是合法表面节点，但派生不出任何模型消息，
+   因此 LLM 上下文直接回退。
+2. **编辑 / 重新生成**：额外调用 `agent.followup(...)` 发送（新的）提示文本，
+   智能体的下一轮请求基于回退后的 `session.deriveMessages()` 构建。
+3. **Client**（`lib/client.js`）注册：
+   - 每条用户消息下的 `user-actions` 对话节点（编辑/撤回行 + 内联编辑器）；
+     撤回后把原文回显到输入框，
+   - `recall-marker` 节点渲染器：提示行 + 注入 CSS 把被阴影化的消息行从对话流中
+     隐藏（视图与模型上下文保持同步），并可显示「原提问」对照块，
+   - `conversation.chat.assistant-actions` 中的 `retrace` 入口
+     （撤回/重新生成），
+   - 设置 → 通用 中的两个偏好开关。
+
+> 这里有两个不同层面：**持久化日志**（只追加；旧事件从不被改写或删除）与
+> **模型可见表面**（由追加的替换事件回退）。因此旧事件作为审计痕迹留在记录中——
+> 但它们会被**同步地从模型上下文和可见对话中清除**，界面始终反映智能体真正看到的内容。
+> 因为插件只追加合法、带类型的会话事件，持久化、投影与记录保持一致。
+
+---
+
+## ⚠️ 要求与限制
+
+- 只有**用户消息**可以编辑；撤回同时适用于用户与助手消息。工具结果会随区间一并
+  被阴影化，但不能单独作为撤回目标。
+- 智能体必须**空闲**：回复流式输出时需先点击 ⏹ 停止，再撤回或编辑；否则 Host
+  返回 `agent-busy`。
+- 撤回/编辑作用于**活跃模型表面**：已被压缩或此前已撤回的消息会被拒绝
+  （`target-shadowed`）。
+- 重新生成只重发原提示的**文本**部分；携带图片的提示会退化为仅文本重发。
+
+---
+
+## 🗺️ 路线图
+
+按 [PLAN.md](./PLAN.md) 推进:
+
+- **P1 — 时间线与产物回退**:单会话内的版本时间线(消息、思考、触碰文件),产物快照
+  (git 优先 + 快照兜底,可开关),带干跑预览的回退,以及跳转到对话位置。
+- **P2 — 分叉图**:对话回合的流程分叉图,每次回退都是分叉点,逐回合思考流,
+  分支意图卡,版本对比。
+- 支持更多语言（当前：简体中文 / English）。
+
+---
+
+## 🛠️ 开发
+
+```sh
+# 目录结构
+lib/host-core.js       # 传输无关的 Host 逻辑（无 import）
+lib/index.js           # 发布版 Host：harness RPC + HTTP 路由
+lib/client.js          # Client 源码（import React；传输层可插拔）
+lib/client.bundle.js   # 构建产物 —— 自注册 loader entry
+                       # （`window.__ModuleLoader__.load`），由 client-modules 提供
+lib/dynamic-host.js    # 生成的动态 Host 半区（源自 lib/host-core.js）
+lib/dynamic-client.js  # 生成的动态 Client 半区（源自 lib/client.js）
+scripts/build-client.mjs      # 打包 lib/client.js → lib/client.bundle.js
+scripts/generate-dynamic.mjs  # 从权威源生成两个动态入口
+scripts/check-dynamic.mjs     # 语法检查动态入口（函数体形态）
+test/                 # vitest 套件：host-core 操作 + 生成产物冒烟测试
+.github/workflows/    # CI（语法 + 构建同步 + 测试）与 npm 发布（v* tag）
+cordis.patch.yml      # dsh.bundle profile patch 层
+```
+
+```sh
+pnpm install          # 安装开发依赖（vitest、esbuild）
+pnpm check            # 语法检查源码与生成的动态入口
+pnpm build            # 重新生成 lib/dynamic-*.js 与 lib/client.bundle.js
+pnpm test             # 运行 host-core 单元测试
+npm pack --dry-run    # 校验发布文件清单
+```
+
+> ⚠️ **生成文件。** `lib/dynamic-host.js`、`lib/dynamic-client.js` 与
+> `lib/client.bundle.js` 是由 `lib/host-core.js` 和 `lib/client.js` 生成的构建
+> 产物 —— **请勿手改**。CI 会在构建产物与源码不同步时失败
+> （`git diff --exit-code`），因此提交前记得执行 `pnpm build`。动态 Client 与
+> 发布版共用同一份 client 源码，仅通过 `__setMessageEditorWire` 切换传输层
+> （`host.call` vs HTTP 路由）。
+
+欢迎提交 PR 与 issue —— 见 [CONTRIBUTING](./CONTRIBUTING.md)（筹备中）与
+[问题追踪](https://github.com/azmavethy/dsh-retrace/issues)。
+
+---
+
+## 📚 生态
+
+收录于 [dsh-plugin topic](https://github.com/topics/dsh-plugin)，可在
+[dsh-market](https://github.com/dsh-market/dsh-market) 一键安装。DeepSeek Harness
+插件生态的精选总览见 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)。
+
+---
+
+## 👥 团队
+
+由 [OfferKuai](https://www.offerkuai.com) 团队开发——一款 AI 求职助手，使命是
+「用户要的是结果，而不是反复的对话」。创始人：Zhaofeng（Yaming）。本插件以开源
+形式发布，回馈 DeepSeek Harness 社区。
+
+## 📄 License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-retrace — profile bundle patch layer.
+#
+# Mounts the plugin as one normal Cordis row in the target profile (the
+# package's `main` → lib/index.js Host half runs as that row). The package's
+# `dsh.client` metadata is scanned by the modules node half, and its client
+# half (exports["./client"] → lib/client.js) is bundled into the Web client
+# automatically while this row is enabled.
+#
+# Install into any profile with:
+#   dsh plugin --profile <name> add dsh-retrace
+# (manual: add "dsh-retrace" to the profile's dependencies and
+#  dsh.profile.bundles, then run `pnpm install` in the profile directory)
+# Restart DSH Desktop / the dsh process after installing or removing.
+
+- insert:
+    - id: dsh-retrace
+      name: dsh-retrace