dsh-retrace 0.4.8 → 0.4.10

package/README.md

@@ -18,6 +18,44 @@ 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
@@ -68,6 +106,9 @@ in the conversation — all **inside the same session**, no session-switching.
 
 ## 🚀 Quick start
 
+The one-line install is at the top of this page (**⚡ Install in one minute**).
+This section covers the same ground with more detail.
+
 > Requires DeepSeek Harness with the `dsh` CLI. Installs the plugin as a profile
 > bundle and automatically rebuilds the Web client:
 
@@ -83,8 +124,7 @@ dsh plugin --profile web add dsh-retrace
 > 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 ↩ / ✎ / ↻.
+After the restart, hover any assistant reply, or any user message, and use ↩ / ✎ / ↻.
 
 ---
 
@@ -105,14 +145,17 @@ dsh plugin --profile <name> add dsh-retrace
 > 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:
 
+> **Downloaded this repo as a ZIP?** Unpack it somewhere stable (e.g.
+> `~/plugins/dsh-retrace`), then either
+> `dsh plugin --profile desktop add ~/plugins/dsh-retrace`, or follow the
+> steps below with the dependency line pointing at the folder:
+> `"dsh-retrace": "file:~/plugins/dsh-retrace"`.
+
 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:
@@ -148,6 +191,9 @@ The same result with plain file edits and `pnpm` — exactly the steps
 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`.
+For the latest GitHub commit without a release: use
+`"dsh-retrace": "github:yamingmou/dsh-retrace"` (standard pnpm git
+dependency syntax) in the same `dependencies` block, then `pnpm install`.
 
 ### 3. npm package + composition (classic)
 
@@ -311,10 +357,23 @@ and the [issue tracker](https://github.com/yamingmou/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).
+Listed on the [dsh-plugin topic](https://github.com/topics/dsh-plugin).
+
+> **Install straight from GitHub** (no npm registry needed — handy when you
+> hand this repo's link to an AI or want the latest commit):
+>
+> ```sh
+> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+> # or with pnpm directly into a profile:
+> cd ~/.dsh/profiles/desktop && pnpm add github:yamingmou/dsh-retrace
+> ```
+>
+> Then restart DSH Desktop as usual. The `dsh-log-contract` dependency is
+> pulled in automatically.
+
+A curated overview of the DeepSeek Harness plugin ecosystem lives at
+[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+(third-party listing — verify availability before relying on it).
 
 ---
 

package/README.zh.md

@@ -17,6 +17,41 @@
 
 </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` 先为对话补上聊天本该有的三个操作 —— **撤回**、**编辑重发**、
 **重新生成**；再往前一步：撤回只回退了**上下文**，而智能体已经改过的**产物文件**
@@ -62,6 +97,8 @@ DeepSeek Harness 的对话是「只追加（append-only）」的事件日志，
 
 ## 🚀 快速开始
 
+页首的 **⚡ 一分钟安装** 是最短路径；本节给出同样内容的更详细说明。
+
 > 需要带 `dsh` CLI 的 DeepSeek Harness。以 profile bundle 方式安装，并自动重建 Web 客户端：
 
 ```sh
@@ -94,13 +131,14 @@ dsh plugin --profile <name> add dsh-retrace
 > `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` 帮你做的那些步骤：
 
+> **从 GitHub 下载了 ZIP？** 解压到固定位置（如 `~/plugins/dsh-retrace`），
+> 然后执行 `dsh plugin --profile desktop add ~/plugins/dsh-retrace`；或按下面步骤，
+> 把依赖行指向该文件夹：`"dsh-retrace": "file:~/plugins/dsh-retrace"`。
+
 1. 打开 profile 清单（默认位置：DSH Desktop 为 `~/.dsh/profiles/desktop`，
    独立 Web 为 `~/.dsh/profiles/web`），同时加入依赖**和** bundle 层条目：
 
@@ -276,9 +314,21 @@ npm pack --dry-run    # 校验发布文件清单
 
 ## 📚 生态
 
-收录于 [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)。
+收录于 [dsh-plugin topic](https://github.com/topics/dsh-plugin)。
+
+> **直接从 GitHub 安装**（无需 npm registry —— 适合把本仓库链接丢给 AI，或想装最新提交）：
+>
+> ```sh
+> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+> # 或直接用 pnpm 装进 profile：
+> cd ~/.dsh/profiles/desktop && pnpm add github:yamingmou/dsh-retrace
+> ```
+>
+> 然后照常重启 DSH Desktop。`dsh-log-contract` 依赖会自动带上。
+
+DeepSeek Harness 插件生态的精选总览见
+[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+（第三方收录，使用前请自行确认可用性）。
 
 ---
 

package/lib/dynamic-host.js

@@ -121,13 +121,19 @@ return {
         content: [],
         source: { kind: 'model', provider: model.provider, model: model.model },
       }
-      // R2 路径一（2026-08-30 事故闭环）：有打开的 step（回合中编辑）时，marker 携带
-      // 该 step 的 turn/step —— token-meter 配对通过，不产生 T1 违规、不刷屏。
-      // 无打开 step（轮次间编辑，常态）才回退 turn:null（配合 markerT1Broken 标注）。
+      // R2 根治（2026-08-30 事故闭环 v2）：
+      // - 有打开的 step（回合中编辑）：marker 携带该 step 的 turn/step → token-meter 配对通过；
+      // - 无打开 step（轮次间编辑，常态）：**自动开一个临时 step 包裹 marker**
+      //   （step/start → marker → step/end，turn 用 nextTurn，step 恒 1）。
+      //   官方 token-meter 要求 assistant/message 必须有打开的 step（lib/index.js:590，
+      //   stepStart===void 0 即抛）——turn-null 或伪造 turn/step 都过不了；
+      //   临时 step 是唯一能让轮次间 marker 合法化的形态（foldSurface/token-meter/客户端
+      //   Location boundary 三层验证全过）。不再产生 turn-null marker → 不再刷屏。
       const openStep = findOpenStep(session)
+      const nextTurn = nextTurnOf(session)
       const data = {
-        turn: openStep ? openStep.turn : null,
-        step: openStep ? openStep.step : null,
+        turn: openStep ? openStep.turn : nextTurn,
+        step: openStep ? openStep.step : 1,
         message: marker,
         editor: {
           targetSeq,
@@ -139,11 +145,20 @@ return {
       if (typeof validate === 'function') {
         const result = await validate(session, { type: 'assistant/message', data, surfaceOp, sourceEventSeqs })
         if (result && result.t1Ok === false) {
-          // R2：标注该 marker 会破坏 /compact（不阻断编辑）。
+          // 理论上临时 step 后 T1 恒通过；残留 fallback 标注（防御）。
           data.editor.markerT1Broken = true
         }
       }
-      return session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+      // 轮次间编辑：开临时 step 包裹（marker 前后成对，token-meter 需要打开的 step）
+      const openedStep = openStep === null
+      if (openedStep) {
+        session.append('step/start', { turn: nextTurn, step: 1 })
+      }
+      const markerEvent = session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+      if (openedStep) {
+        session.append('step/end', { turn: nextTurn, step: 1 })
+      }
+      return markerEvent
     }
     
     /**
@@ -164,6 +179,20 @@ return {
       return open
     }
     
+    /**
+     * 下一个 turn 号：scan 最大 turn（turn/start、step/start、assistant/message、user/message
+     * 的 data.turn 中取最大）+1。无任何 turn 时从 1 起。
+     */
+    function nextTurnOf(session) {
+      const events = Array.isArray(session?.events) ? session.events : []
+      let max = 0
+      for (const event of events) {
+        const t = event?.data?.turn
+        if (typeof t === 'number' && Number.isSafeInteger(t) && t > max) max = t
+      }
+      return max + 1
+    }
+    
     function createEditorApi(ctx, sessions, agents, log = () => {}, hooks = {}) {
       /** One in-flight op per session; later ops wait for the earlier one. */
       const locks = new Map()
@@ -204,7 +233,10 @@ return {
         if (!agent || typeof agent.status !== 'string' || agent.status !== 'running') return
         if (typeof agent.cancel === 'function' && typeof agent.whenIdle === 'function') {
           try {
-            agent.cancel({ kind: 'plugin-retrace-edit' })
+            // 官方 AgentCancelCause 类型只有 user/parent/hook/disposed 四种
+            // （dsh-commands typert.host.js:166）——用 { kind: 'user' } 与 UI 停止按钮同义，
+            // 中断的 turn/end 会按官方语义记录 reason。
+            agent.cancel({ kind: 'user' })
             await agent.whenIdle()
             return
           } catch (error) {

package/lib/host-core.js

@@ -112,13 +112,19 @@ export async function appendEditorMarker(session, span, op, targetSeq, originalT
     content: [],
     source: { kind: 'model', provider: model.provider, model: model.model },
   }
-  // R2 路径一（2026-08-30 事故闭环）：有打开的 step（回合中编辑）时，marker 携带
-  // 该 step 的 turn/step —— token-meter 配对通过，不产生 T1 违规、不刷屏。
-  // 无打开 step（轮次间编辑，常态）才回退 turn:null（配合 markerT1Broken 标注）。
+  // R2 根治（2026-08-30 事故闭环 v2）：
+  // - 有打开的 step（回合中编辑）：marker 携带该 step 的 turn/step → token-meter 配对通过；
+  // - 无打开 step（轮次间编辑，常态）：**自动开一个临时 step 包裹 marker**
+  //   （step/start → marker → step/end，turn 用 nextTurn，step 恒 1）。
+  //   官方 token-meter 要求 assistant/message 必须有打开的 step（lib/index.js:590，
+  //   stepStart===void 0 即抛）——turn-null 或伪造 turn/step 都过不了；
+  //   临时 step 是唯一能让轮次间 marker 合法化的形态（foldSurface/token-meter/客户端
+  //   Location boundary 三层验证全过）。不再产生 turn-null marker → 不再刷屏。
   const openStep = findOpenStep(session)
+  const nextTurn = nextTurnOf(session)
   const data = {
-    turn: openStep ? openStep.turn : null,
-    step: openStep ? openStep.step : null,
+    turn: openStep ? openStep.turn : nextTurn,
+    step: openStep ? openStep.step : 1,
     message: marker,
     editor: {
       targetSeq,
@@ -130,11 +136,20 @@ export async function appendEditorMarker(session, span, op, targetSeq, originalT
   if (typeof validate === 'function') {
     const result = await validate(session, { type: 'assistant/message', data, surfaceOp, sourceEventSeqs })
     if (result && result.t1Ok === false) {
-      // R2：标注该 marker 会破坏 /compact（不阻断编辑）。
+      // 理论上临时 step 后 T1 恒通过；残留 fallback 标注（防御）。
       data.editor.markerT1Broken = true
     }
   }
-  return session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+  // 轮次间编辑：开临时 step 包裹（marker 前后成对，token-meter 需要打开的 step）
+  const openedStep = openStep === null
+  if (openedStep) {
+    session.append('step/start', { turn: nextTurn, step: 1 })
+  }
+  const markerEvent = session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+  if (openedStep) {
+    session.append('step/end', { turn: nextTurn, step: 1 })
+  }
+  return markerEvent
 }
 
 /**
@@ -155,6 +170,20 @@ export function findOpenStep(session) {
   return open
 }
 
+/**
+ * 下一个 turn 号：scan 最大 turn（turn/start、step/start、assistant/message、user/message
+ * 的 data.turn 中取最大）+1。无任何 turn 时从 1 起。
+ */
+export function nextTurnOf(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  let max = 0
+  for (const event of events) {
+    const t = event?.data?.turn
+    if (typeof t === 'number' && Number.isSafeInteger(t) && t > max) max = t
+  }
+  return max + 1
+}
+
 export function createEditorApi(ctx, sessions, agents, log = () => {}, hooks = {}) {
   /** One in-flight op per session; later ops wait for the earlier one. */
   const locks = new Map()
@@ -195,7 +224,10 @@ export function createEditorApi(ctx, sessions, agents, log = () => {}, hooks = {
     if (!agent || typeof agent.status !== 'string' || agent.status !== 'running') return
     if (typeof agent.cancel === 'function' && typeof agent.whenIdle === 'function') {
       try {
-        agent.cancel({ kind: 'plugin-retrace-edit' })
+        // 官方 AgentCancelCause 类型只有 user/parent/hook/disposed 四种
+        // （dsh-commands typert.host.js:166）——用 { kind: 'user' } 与 UI 停止按钮同义，
+        // 中断的 turn/end 会按官方语义记录 reason。
+        agent.cancel({ kind: 'user' })
         await agent.whenIdle()
         return
       } catch (error) {

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.8",
+  "version": "0.4.10",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",