@khorsheed/dsh-client-message-tools 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 变更记录
 
+## 0.3.0（2026-09-11）
+
+适配宿主 0.1.5 线。
+
+- **BREAKING**：minHost 前移至 `0.1.5-rc.1`；宿主 `0.1.2-rc.1` ~ `0.1.4.x` 的用户请停留在 0.2.x 线（末版 `0.2.0`）
+- 撤回/恢复投影适配 0.1.5 的会话格式：`assistant/attempt`（每次模型尝试一条聚合 settlement）取代已退役的 `assistant/chunk`；surfaceOp replace 字段 `start`/`end` 更名 `startSeq`/`endSeq`，撤回与就地编辑写出的替换 op 同步改用新名
+- 开发基线随仓内 pin 对齐官方 `0.1.5-rc.1` / cordis `4.0.2`；peer 范围保持宽松
+
+## 0.2.0（2026-09-10）
+
+适配宿主 0.1.2 线。
+
+- **BREAKING**：minHost 前移至 `0.1.2-rc.1`；宿主 `0.1.0-rc.6` ~ `0.1.1-rc.2` 的用户请停留在 0.1.x 线（末版 `0.1.0`）
+- 会话事件读取走 `Session.snapshotEvents()` / `eventAt`（`session.events` 已随宿主移除），事件序号全面品牌化为 `SessionSeq`
+- 导入面迁移：client bundle 不再引用宿主已删除的 `dsh-client-runtime`
+
 ## 0.1.0（2026-08-22）
 
 首个公开发布；此前在内部迭代至 0.4.x。

package/README.en.md

@@ -2,17 +2,11 @@
 
 English | [中文](README.md)
 
-Edit, withdraw, and restore user messages in the dsh web GUI: every user message grows a copy / edit / withdraw action row. Withdrawals really remove the message (and everything after it) from the model context, collapse it into an expandable divider, and can replay it back at the tail — no core-package edits.
+Sent messages can still be edited or withdrawn — and a withdrawal really deletes them from the model's memory, not just marks them.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions1.png" width="480" alt="copy / edit / withdraw action row on a user message">
+Said something too fast, or the conversation went off the rails? Until now all you could do was send another message to correct course. This plugin puts a row of small buttons on every message you send: copy, edit, withdraw. Editing rewrites in place and re-sends, and the model answers the new text; withdrawing takes that message and everything after it out of the model context, folding it into an expandable "N messages withdrawn" divider — and the original text lands back in your composer draft (never auto-sent). Changed your mind? The divider's "restore to end of conversation" puts it all back.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions2.png" width="480" alt="in-place editing: saving re-sends as a new message; the edited original leaves the model context">
-
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions3.png" width="480" alt="the confirmation dialog before withdrawing, spelling out the consequences">
-
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions4.png" width="480" alt="withdrawn messages collapse into a divider, restorable to the end of the conversation">
-
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions5.png" width="480" alt="restored messages return to the conversation as they were">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions1.png" width="640" alt="copy, edit, and withdraw action buttons under a user message">
 
 ## Features
 
@@ -22,6 +16,14 @@ Edit, withdraw, and restore user messages in the dsh web GUI: every user message
 - **Draft backfill** — a landed withdrawal puts the original text back into the composer draft, never auto-sent.
 - **Restore to tail** — 「恢复到对话末尾」 replays user messages verbatim and assistant text as a 「已恢复」 group; tool calls never replay.
 
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions2.png" width="640" alt="in-place editing: the message becomes an input with a model picker; saving re-sends it as a new message, and the edited original leaves the model context">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions3.png" width="640" alt="the confirmation dialog before withdrawing, explaining that the message and everything after it will be hidden from the model and the original text backfilled into the composer">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions4.png" width="640" alt="withdrawn content folds into an expandable divider with a restore-to-end-of-conversation button at the bottom">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions5.png" width="640" alt="restored messages return to the tail of the conversation as they were, grouped under a Restored section">
+
 ## Install
 
 ```sh
@@ -36,8 +38,10 @@ dsh plugin --profile web remove @khorsheed/dsh-client-message-tools
 
 ## Compatibility
 
-- npm release line (`@deepseek-ai/dsh@0.1.1-rc.2`): ✅ full — built and tested against the rc.8 type surface. This build REQUIRES rc.8: chat-node owner props dropped `loadImage` for the required `renderMessageImages` attachment-slot renderer — stay on the previous build on rc.6/rc.7 hosts. — also verified on 0.1.1-rc.1 (additive audit, 2026-08-21); re-audited for rc.2 (2026-08-22): consumed surface unchanged, full build+test green
-- source line (deepseek-harness master): ✅
+- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ✅ full — adapted to the 0.1.5-rc.1 format v2/v3 (`assistant/attempt` replaces `assistant/chunk`; the surfaceOp replace fields `start`/`end` are renamed `startSeq`/`endSeq`), full build+test green; minHost moves up to 0.1.5-rc.1 — older hosts stay on the previous release line.
+- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.5-rc.1)
+
+**Version line mapping**: the first release after 0.2.0 supports host `0.1.5-rc.1` and later; hosts on `0.1.2-rc.1` stay on `0.2.0`, hosts on `0.1.0-rc.6` ~ `0.1.1-rc.2` stay on the 0.1.x release line (last release `0.1.0`).
 
 ## Known Limitations
 
@@ -59,7 +63,7 @@ dsh plugin --profile web remove @khorsheed/dsh-client-message-tools
 
 **Projection and hiding.** The plugin's Definition claims the replacement into a divider anchored at its seq. Hiding is two-layer: the shadowed user renderer renders nothing inside a hidden span, and a dynamic stylesheet drops every chat row whose `data-chat-flow-key` (`ChatNodeSeat.tsx`) anchors inside the span, covering assistant steps, tool calls, and turn tails. The hider probes that undocumented attribute on its first non-empty rule set and, on a miss, enters a bounded retry (MutationObserver plus deadline) so a not-yet-mounted chat doesn't disable it; only an expired window disables it — one `console.warn`, renderer-only hiding — and the observer outlives the disable, so late-mounting rows reactivate it. It never throws. The divider expands in place to a read-only replay of the span (user originals plus assistant text, folded from the live node store) with the 「恢复到对话末尾」 action; a span whose rows fell out of the loaded window shows 「撤回的内容不在当前已加载的历史中」 instead.
 
-**Restore** is a tail replay of the whole withdrawn span, never an in-place repair: the surface fold is positional — a replaced span splices into exactly one node (`applySurfacePlan`) — so the span cannot re-enter the model context where it was, and its model-side hiding is never undone. The host walks the log interval `[start, seq)` delimited by the replacement itself and appends every replayable entry in original order: user messages verbatim (an edit replacement's content IS the last edit's text, so it replays as such) and each assistant reply's text as a framed plugin-sourced user message — `assistant/message` cannot carry a plugin source and the trace forbids assistant appends outside a step, so role fidelity is carried by the frame `(以下是先前被撤回、现随恢复放回的助手回复)`, stripped from display. An interrupted step without `assistant/message` is merged from its `assistant/chunk` rows (reasoning-only fragments preserved). Tool calls/results never replay: the pairing cannot be re-entered and side effects are not replayable. Replayed rows render as the 「已恢复」 group — user bubbles with the full action row, assistant text via the official `MarkdownText` — and the divider carries a 「已恢复」 badge while a live restore row cites the span; withdrawing the restored rows again clears the badge and re-enables the action (restore events stay in the log).
+**Restore** is a tail replay of the whole withdrawn span, never an in-place repair: the surface fold is positional — a replaced span splices into exactly one node (`applySurfacePlan`) — so the span cannot re-enter the model context where it was, and its model-side hiding is never undone. The host walks the log interval `[start, seq)` delimited by the replacement itself and appends every replayable entry in original order: user messages verbatim (an edit replacement's content IS the last edit's text, so it replays as such) and each assistant reply's text as a framed plugin-sourced user message — `assistant/message` cannot carry a plugin source and the trace forbids assistant appends outside a step, so role fidelity is carried by the frame `(以下是先前被撤回、现随恢复放回的助手回复)`, stripped from display. An interrupted attempt without `assistant/message` is merged from its `assistant/attempt` event's embedded compact stream (reasoning-only content preserved). Tool calls/results never replay: the pairing cannot be re-entered and side effects are not replayable. Replayed rows render as the 「已恢复」 group — user bubbles with the full action row, assistant text via the official `MarkdownText` — and the divider carries a 「已恢复」 badge while a live restore row cites the span; withdrawing the restored rows again clears the badge and re-enables the action (restore events stay in the log).
 
 **Why the projection cannot hide the span (the upstream seam a durable fix needs).** The assembler runs every Definition's `match` per event with no veto (`conversation-assembler.ts:370`), and `match(event)` reads only the current event; shadowed events keep `surfaceOp: 'append'` (the range metadata lives on the replacement only), so they still match the built-in Definitions, which exclude *replacement* events, not shadowed ones. Node `visibility` is set only by the owning Definition, the assembler forbids withdrawing a materialized node, and a node key is bound to its Definition's kind — a plugin can neither flip nor impersonate an official node. Shadowing the other `conversation.chat.node` keys fails too: the official components are not exported, and `command`/`turn-tail`/`tool-call` declare child slots a shadow cannot re-declare (`tool-call` owns the unbounded per-tool-name `tool.call.toolview` slot). The official compaction pipeline makes the same choice by design — a replaced span stays in the transcript.
 

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/message-tools/README.en.md
-packages/message-tools/README.en.md: 762548813b3941a7240fbefe010c88ea0570e0c8
-packages/message-tools/README.md: ae9a40fd42ec8372b1eb0f60b671f46cdc050681
+packages/message-tools/README.en.md: bd272494cd2c60cb8845549496c103da8c3826ea
+packages/message-tools/README.md: 594842e812e8c0e9eba3670926bcb09881576b57

package/README.md

@@ -1,26 +1,28 @@
-# dsh-client-message-tools
+# @khorsheed/dsh-client-message-tools
 
 [English](README.en.md) | 中文
 
-为 dsh Web 界面的用户消息提供编辑、撤回与恢复:每条用户消息都有复制/编辑/撤回操作行。撤回是真撤回——消息及其后内容彻底离开模型上下文,折叠成可展开的分隔线,还能重放回对话末尾——不改动任何核心包。
+发出去的话还能改、还能撤——撤回是真从模型记忆里删掉，不是打个标记。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions1.png" width="480" alt="用户消息上的复制/编辑/撤回操作行">
+话说快了、方向跑偏了，以前只能再发一条往回找补。这个插件给你发出的每条消息配上一排小按钮：复制、编辑、撤回。编辑是原地改完重新发，模型按新内容重新回答；撤回会把这条消息和它后面的所有内容一起请出模型上下文，折叠成一条可以展开的「已撤回 N 条消息」分隔线，原话还会自动回填到输入框草稿（绝不替你发送）。后悔了，点分隔线上的「恢复到对话末尾」就能把内容原样放回去。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions2.png" width="480" alt="原位编辑:保存后以新消息重新发送,被编辑消息不再进入模型上下文">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions1.png" width="640" alt="用户消息下方的复制、编辑、撤回操作按钮">
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions3.png" width="480" alt="撤回前的确认弹窗,说明影响范围">
+## 特性
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions4.png" width="480" alt="撤回后折叠成分隔线,可一键恢复到对话末尾">
+- **每条用户消息都有操作行**——用户气泡与已吸入轮次的 steering 消息带复制、编辑、撤回操作。
+- **就地编辑**——内联编辑框带真实可用的模型 chip；保存后从该处重新生成，已编辑的气泡可再次编辑。
+- **真撤回，不是打标记**——消息及其后整个尾部离开模型上下文，折叠为可展开的「已撤回 N 条消息」分隔线。
+- **草稿回填**——撤回成功后把原文回填到 composer 草稿，绝不自动发送。
+- **恢复到尾部**——「恢复到对话末尾」把用户消息逐字重放、助手文本重放为「已恢复」组；工具调用永不重放。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions5.png" width="480" alt="恢复后消息原样回到对话">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions2.png" width="640" alt="原位编辑：消息变成带模型选择的输入框，保存后以新消息重新发送，被编辑消息不再进入模型上下文">
 
-## 特性
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions3.png" width="640" alt="撤回前的确认弹窗：说明这条消息及其后内容将对模型隐藏、原文会回填到输入框">
 
-- **每条用户消息都有操作行**——用户气泡与已吸入轮次的 steering 消息带复制、编辑、撤回操作。
-- **就地编辑**——内联编辑框带真实可用的模型 chip;保存后从该处重新生成,已编辑的气泡可再次编辑。
-- **真撤回,不是打标记**——消息及其后整个尾部离开模型上下文,折叠为可展开的「已撤回 N 条消息」分隔线。
-- **草稿回填**——撤回成功后把原文回填到 composer 草稿,绝不自动发送。
-- **恢复到尾部**——「恢复到对话末尾」把用户消息逐字重放、助手文本重放为「已恢复」组;工具调用永不重放。
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions4.png" width="640" alt="撤回后的内容折叠为可展开的分隔线，底部有「恢复到对话末尾」按钮">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-actions5.png" width="640" alt="恢复后消息原样回到对话末尾，归入「已恢复」分组">
 
 ## 安装
 
@@ -28,7 +30,7 @@
 dsh plugin --profile web add @khorsheed/dsh-client-message-tools
 ```
 
-重启 web 实例后生效;卸载即精确还原之前的组合。
+重启 web 实例后生效；卸载即精确还原之前的组合。
 
 ```sh
 dsh plugin --profile web remove @khorsheed/dsh-client-message-tools
@@ -36,46 +38,48 @@ dsh plugin --profile web remove @khorsheed/dsh-client-message-tools
 
 ## Compatibility
 
-- npm 发布线(`@deepseek-ai/dsh@0.1.1-rc.2`):✅ 完整——基于 rc.8 类型面构建并通过测试。本构建**要求 rc.8**:chat-node owner props 移除了 `loadImage`,改为必填的 `renderMessageImages` 附件槽渲染器——在 rc.6/rc.7 宿主上请停留在上一个构建。——亦在 0.1.1-rc.1 上验证(纯增量审计,2026-08-21)；rc.1→rc.2 复核(2026-08-22):消费面无变化,全量构建测试通过
-- 源码线(deepseek-harness master):✅
+- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 完整——适配 0.1.5-rc.1 的 format v2/v3（`assistant/attempt` 取代 `assistant/chunk`；surfaceOp replace 字段 `start`/`end` 更名 `startSeq`/`endSeq`），全量构建测试通过；minHost 前移至 0.1.5-rc.1，旧宿主请停留在旧发布线。
+- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.5-rc.1）
+
+**版本线对照**：0.2.0 之后的首个发布起支持宿主 `0.1.5-rc.1` 及以后；宿主 `0.1.2-rc.1` 请停留在 `0.2.0`，宿主 `0.1.0-rc.6` ~ `0.1.1-rc.2` 请停留在 0.1.x 发布线（末版 `0.1.0`）。
 
 ## 已知限制
 
-- **全区间隐藏依赖一个未文档化的 DOM 属性**——上游若移除它,隐藏退化为仅渲染器层(用户消息仍被隐藏),`console.warn` 一次,绝不报错。
+- **全区间隐藏依赖一个未文档化的 DOM 属性**——上游若移除它，隐藏退化为仅渲染器层（用户消息仍被隐藏），`console.warn` 一次，绝不报错。
 - **编辑仅支持文本**——原消息的图片附件不会带入重发。
-- **恢复是尾部重放,不是原位修复**——助手文本以带框架的用户角色消息重放,工具调用/结果永不重放;撤回区间始终留在模型上下文之外,恢复入口只在撤回分隔线上。
-- **context 与排队消息不在范围内**——context 消息沿用官方渲染器(无操作行);仍在排队的消息由官方队列条带编辑/移除。
+- **恢复是尾部重放，不是原位修复**——助手文本以带框架的用户角色消息重放，工具调用/结果永不重放；撤回区间始终留在模型上下文之外，恢复入口只在撤回分隔线上。
+- **context 与排队消息不在范围内**——context 消息沿用官方渲染器（无操作行）；仍在排队的消息由官方队列条带编辑/移除。
 
 ## 实现原理
 
 <details>
-<summary>内部结构(点击展开)</summary>
+<summary>内部结构（点击展开）</summary>
 
-**架构。** 浏览器半部分以官方用户消息渲染器的视觉克隆(`conversation.chat.node` 槽位、key `user` 与 `steering`、priority -1)替换默认渲染并新增操作行,同时注册四个 `ConversationNodeDefinition`:撤回投影为可展开的「已撤回 N 条消息」分隔线(N = 区间隐藏的用户可见消息数),编辑替换投影为带「已编辑」徽标的原位气泡,恢复条目投影为「已恢复」组里的重放行。Host 半部分是 `messageTools` Typert Remote 服务(`withdraw` / `edit` / `restore`);客户端经 `ctx.remote.$mount` 自行挂载生成的 Remote contribution,无需改动任何核心包。
+**架构。** 浏览器半部分以官方用户消息渲染器的视觉克隆（`conversation.chat.node` 槽位、key `user` 与 `steering`、priority -1）替换默认渲染并新增操作行，同时注册四个 `ConversationNodeDefinition`：撤回投影为可展开的「已撤回 N 条消息」分隔线（N = 区间隐藏的用户可见消息数），编辑替换投影为带「已编辑」徽标的原位气泡，恢复条目投影为「已恢复」组里的重放行。Host 半部分是 `messageTools` Typert Remote 服务（`withdraw` / `edit` / `restore`）；客户端经 `ctx.remote.$mount` 自行挂载生成的 Remote contribution，无需改动任何核心包。
 
-**编辑**即原位替换:host 追加一条 `user/message` replacement,其内容就是编辑后的新文本(区间覆盖目标消息及 surface 尾部——编辑旧消息就是放弃其后的一切),随后经 `agent.followup` 投递一条极简插件来源触发消息启动重新生成。模型上下文里新文本只出现一次;旧内容留在日志里作审计。会话有运行中的轮次时先取消它并等待完全落定——落定指被取消轮次的收尾(工具结果、`turn/end`)全部落盘,而不是 `running` 翻转;等待有界,迟迟不落定的轮次以「编辑失败」拒绝,取消失败则不编辑。支持编辑链:已编辑气泡可再次编辑,目标是上一个 replacement 的 seq。编辑框的模型 chip 与 composer、/model 弹层共享按会话的 `ModelDirectory`(`ctx.get('modelDirectories')`,可选服务)——组合里没有 ui-model-selection 就不渲染 chip——切换经 host 校验后作用于重新生成的轮次。
+**编辑**即原位替换：host 追加一条 `user/message` replacement，其内容就是编辑后的新文本（区间覆盖目标消息及 surface 尾部——编辑旧消息就是放弃其后的一切），随后经 `agent.followup` 投递一条极简插件来源触发消息启动重新生成。模型上下文里新文本只出现一次；旧内容留在日志里作审计。会话有运行中的轮次时先取消它并等待完全落定——落定指被取消轮次的收尾（工具结果、`turn/end`）全部落盘，而不是 `running` 翻转；等待有界，迟迟不落定的轮次以「编辑失败」拒绝，取消失败则不编辑。支持编辑链：已编辑气泡可再次编辑，目标是上一个 replacement 的 seq。编辑框的模型 chip 与 composer、/model 弹层共享按会话的 `ModelDirectory`（`ctx.get('modelDirectories')`，可选服务）——组合里没有 ui-model-selection 就不渲染 chip——切换经 host 校验后作用于重新生成的轮次。
 
-**撤回**是真撤回,不是打标记:host 追加一条 `user/message` surface replacement(与 compaction 同一机制),区间覆盖目标消息及之后的所有 surface 节点,该区间由此离开 `session.surface`,不再进入模型上下文;与编辑同款的 cancel-and-settle 编排保证流式内容不会落到 replacement 之后。事件为插件来源,`sourceEventSeqs` 引用每一个被遮蔽节点,方法返回前经 `SessionStore.flush` 落盘——它本身就是审计轨迹。不引入新事件类型:harness 之外的类型无法携带 `ignorable: true`,持久化的未知类型会让 session-persistence 重载时拒绝整个日志。撤回成功后把目标原文回填到 composer 草稿(空草稿直接填入、非空换行追加、落 info 提示)——绝不自动发送,失败则不回填;编辑路径不触发回填。
+**撤回**是真撤回，不是打标记：host 追加一条 `user/message` surface replacement（与 compaction 同一机制），区间覆盖目标消息及之后的所有 surface 节点，该区间由此离开 `session.surface`，不再进入模型上下文；与编辑同款的 cancel-and-settle 编排保证流式内容不会落到 replacement 之后。事件为插件来源，`sourceEventSeqs` 引用每一个被遮蔽节点，方法返回前经 `SessionStore.flush` 落盘——它本身就是审计轨迹。不引入新事件类型：harness 之外的类型无法携带 `ignorable: true`，持久化的未知类型会让 session-persistence 重载时拒绝整个日志。撤回成功后把目标原文回填到 composer 草稿（空草稿直接填入、非空换行追加、落 info 提示）——绝不自动发送，失败则不回填；编辑路径不触发回填。
 
-**投影与隐藏。** 插件的 Definition 把 replacement 认领为锚定在其 seq 上的分隔线节点。隐藏分两层:被遮蔽的用户渲染器对区间内用户消息渲染为空;一张动态样式表把 `data-chat-flow-key`(`ChatNodeSeat.tsx`)锚点落在区间内的聊天行一律隐藏,覆盖助手步骤、工具调用、turn 尾部。隐藏器在首个非空规则集探测这个未文档化属性,探测落空进入有界重试(MutationObserver 加截止时限),避免聊天区尚未挂载时误停用;只有窗口耗尽仍探不到行才停用——`console.warn` 一次,退化为仅渲染器隐藏——且 observer 在停用后仍存活,行晚到会重新生效,绝不报错。分隔线可就地展开只读回放撤回区间(用户原文加助手文本,从实时节点存储折叠)并提供「恢复到对话末尾」;行已掉出加载窗口的区间显示「撤回的内容不在当前已加载的历史中」。
+**投影与隐藏。** 插件的 Definition 把 replacement 认领为锚定在其 seq 上的分隔线节点。隐藏分两层：被遮蔽的用户渲染器对区间内用户消息渲染为空；一张动态样式表把 `data-chat-flow-key`（`ChatNodeSeat.tsx`）锚点落在区间内的聊天行一律隐藏，覆盖助手步骤、工具调用、turn 尾部。隐藏器在首个非空规则集探测这个未文档化属性，探测落空进入有界重试（MutationObserver 加截止时限），避免聊天区尚未挂载时误停用；只有窗口耗尽仍探不到行才停用——`console.warn` 一次，退化为仅渲染器隐藏——且 observer 在停用后仍存活，行晚到会重新生效，绝不报错。分隔线可就地展开只读回放撤回区间（用户原文加助手文本，从实时节点存储折叠）并提供「恢复到对话末尾」；行已掉出加载窗口的区间显示「撤回的内容不在当前已加载的历史中」。
 
-**恢复**是整个被撤回区间的尾部重放,不是原位修复:surface 折叠是位置性的——被替换区间只接续成一个节点(`applySurfacePlan`)——区间无法回到模型上下文原位,其模型侧隐藏也永不回退。host 沿撤回 replacement 自身划定的日志区间 `[start, seq)` 把可重放内容按原始顺序逐条追加到尾部:用户消息逐字重放(编辑替换的内容就是最后一次编辑的新文本,恢复时即以此为准),每条助手回复的文本以带框架的插件来源用户消息重放——`assistant/message` 无法携带插件来源,且轨迹不允许在 step 之外追加助手消息,因此角色保真由框架 `(以下是先前被撤回、现随恢复放回的助手回复)` 承担,UI 上不显示该框架。未落成 `assistant/message` 的中断步骤从其 `assistant/chunk` 片段合并重放(只有 reasoning 时保留 reasoning)。工具调用/结果永不重放:配对无法重新进入,副作用不可重放。重放行渲染为「已恢复」组——用户气泡带完整操作行,助手文本走官方 `MarkdownText`——分隔线在存在引用该区间的存活恢复行期间显示「已恢复」徽标;再次撤回这些恢复行会清掉徽标并重新启用恢复操作(恢复事件始终留在日志里)。
+**恢复**是整个被撤回区间的尾部重放，不是原位修复：surface 折叠是位置性的——被替换区间只接续成一个节点（`applySurfacePlan`）——区间无法回到模型上下文原位，其模型侧隐藏也永不回退。host 沿撤回 replacement 自身划定的日志区间 `[start, seq)` 把可重放内容按原始顺序逐条追加到尾部：用户消息逐字重放（编辑替换的内容就是最后一次编辑的新文本，恢复时即以此为准），每条助手回复的文本以带框架的插件来源用户消息重放——`assistant/message` 无法携带插件来源，且轨迹不允许在 step 之外追加助手消息，因此角色保真由框架 `(以下是先前被撤回、现随恢复放回的助手回复)` 承担，UI 上不显示该框架。未落成 `assistant/message` 的中断尝试从其 `assistant/attempt` 事件内嵌的紧凑流合并重放（只有 reasoning 时保留 reasoning）。工具调用/结果永不重放：配对无法重新进入，副作用不可重放。重放行渲染为「已恢复」组——用户气泡带完整操作行，助手文本走官方 `MarkdownText`——分隔线在存在引用该区间的存活恢复行期间显示「已恢复」徽标；再次撤回这些恢复行会清掉徽标并重新启用恢复操作（恢复事件始终留在日志里）。
 
-**为什么投影层做不到(彻底修复所需的上游 seam)。** 组装器对每个事件运行所有已注册 Definition 的 `match`,没有否决机制(`conversation-assembler.ts:370`),且 `match(event)` 只能读当前事件;被遮蔽事件在日志里仍保持 `surfaceOp: 'append'`(区间元数据只存在于 replacement 自身),因此依然命中各内置 Definition——内置 Definition 排除的是 *replacement* 事件,不是被遮蔽事件。节点的 `visibility` 只能由产出它的 Definition 设置,组装器禁止把已物化节点撤回为 null,节点 key 又与其 Definition 的 kind 绑定——插件既无法翻转也无法冒充官方节点。遮蔽其余 `conversation.chat.node` key 同样行不通:官方组件没有导出,`command`/`turn-tail`/`tool-call` 声明了子槽位而遮蔽无法重复声明(`tool-call` 还持有 key 空间无界的按工具名 keyed 的 `tool.call.toolview` 槽位)。官方 compaction 流水线在设计上就做了同样选择——被替换的区间保留在 transcript 里。
+**为什么投影层做不到（彻底修复所需的上游 seam）。** 组装器对每个事件运行所有已注册 Definition 的 `match`，没有否决机制（`conversation-assembler.ts:370`），且 `match(event)` 只能读当前事件；被遮蔽事件在日志里仍保持 `surfaceOp: 'append'`（区间元数据只存在于 replacement 自身），因此依然命中各内置 Definition——内置 Definition 排除的是 *replacement* 事件，不是被遮蔽事件。节点的 `visibility` 只能由产出它的 Definition 设置，组装器禁止把已物化节点撤回为 null，节点 key 又与其 Definition 的 kind 绑定——插件既无法翻转也无法冒充官方节点。遮蔽其余 `conversation.chat.node` key 同样行不通：官方组件没有导出，`command`/`turn-tail`/`tool-call` 声明了子槽位而遮蔽无法重复声明（`tool-call` 还持有 key 空间无界的按工具名 keyed 的 `tool.call.toolview` 槽位）。官方 compaction 流水线在设计上就做了同样选择——被替换的区间保留在 transcript 里。
 
 **模型体验。**
 
-- *编辑替换*——模型读到编辑后的文本,原消息之后的内容全部消失;其后跟一条短触发消息(`(用户编辑了上一条消息，请按编辑后的内容重新回答)`)。Token 影响:被遮蔽区间的全部 token 离开后续请求,新增编辑后消息与触发消息。KV Cache:prompt 前缀从编辑点失效。
-- *撤回替换*——区间被一条占位消息(`(用户撤回了这条消息及其后的所有内容)`)取代。Token 影响:区间的全部 token 离开,只新增一条短消息。KV Cache:前缀从替换点失效——取舍与 compaction 相同;撤回越早的消息,失效的缓存前缀越多。
-- *恢复重放*——区间的可重放内容(用户消息逐字、助手文本带框架)按原始顺序追加到尾部,插件标记并引用原事件;工具调用/结果的 token 不进入。KV Cache:不超出普通尾部追加的范围。
+- *编辑替换*——模型读到编辑后的文本，原消息之后的内容全部消失；其后跟一条短触发消息（`(用户编辑了上一条消息，请按编辑后的内容重新回答)`）。Token 影响：被遮蔽区间的全部 token 离开后续请求，新增编辑后消息与触发消息。KV Cache：prompt 前缀从编辑点失效。
+- *撤回替换*——区间被一条占位消息（`(用户撤回了这条消息及其后的所有内容)`）取代。Token 影响：区间的全部 token 离开，只新增一条短消息。KV Cache：前缀从替换点失效——取舍与 compaction 相同；撤回越早的消息，失效的缓存前缀越多。
+- *恢复重放*——区间的可重放内容（用户消息逐字、助手文本带框架）按原始顺序追加到尾部，插件标记并引用原事件；工具调用/结果的 token 不进入。KV Cache：不超出普通尾部追加的范围。
 
-**导出。** `/client` 导出插件本体(`apply`/`inject`)与 `MessageToolsRemote` 类型;host 侧导出 `MessageToolsService` 类,`/types` 子路径提供线上类型。
+**导出。** `/client` 导出插件本体（`apply`/`inject`）与 `MessageToolsRemote` 类型；host 侧导出 `MessageToolsService` 类，`/types` 子路径提供线上类型。
 
 </details>
 
 ## 开发
 
-隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo(`packages/message-tools`)。问题与贡献请移步该仓库。
+隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo（`packages/message-tools`）。问题与贡献请移步该仓库。
 
 ## 变更记录