@khorsheed/dsh-client-message-tools 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 变更记录
 
+## 0.3.5（2026-10-26）
+
+- **长消息自动折叠**：你发出的消息超过 600 字或 12 行时，在所有会话里折叠成约十行、底部渐隐，点开看全文；会话里最新的一条保持展开，直到你发下一条。你自己点过的展开/收起按消息记在浏览器里。
+- **折叠按钮放进气泡里**：展开/收起不再单独占一行，改成气泡右下角的小圆形箭头（折叠时压在渐隐上，展开后收进底部留白并翻转方向），深浅主题下都清楚。
+- **会话引用显示成标签**：用 @ 菜单引用的其它会话，在你的消息气泡里显示为「@标题」标签，不再露出 `@[标题](dsh-session:…)` 原文；句子中间的标签留在句子里。
+- **README 重写**：改为大白话说明；仓内目录随 npm 包名改为 `packages/client-message-tools`（包名不变，安装与设置无感）。
+
+## 0.3.4（2026-10-22）
+
+适配宿主 0.2.1 线：verifiedHost 前移至 0.2.1-rc.1，`@deepseek-ai/dsh-*` peer 区间加宽覆盖 0.2.1 并声明 `engines.dsh`（`>=0.1.5-rc.1 <0.3.0-0`）；退役 load 期 invariant 伴生探针（本包为空仪式，无行为变化）。
+
+- **shadow 渲染跟随宿主字号轴**（修复 [Khorsheed/dsh-plugins#1](https://github.com/Khorsheed/dsh-plugins/issues/1)，841ab4c0）：shadow 用户气泡与撤回分隔线此前硬编码字号行高（气泡 16px/24px，是官方气泡迁 token 前的旧克隆）——非默认 `ui-theme.fontSize` 下 shadow 气泡比官方面大约 23%，默认字号下也是 16px 对官方 14px。现在气泡、分隔线标题、回放条目的字号行高全部镜像官方（ui-chat MessageItem）并跟随 body 发布的字号轴，标记与前导几何随轴缩放；模型 chip 属 composer chrome 保持固定
+- **用户消息图片改经 0.2.1 官方图片工厂渲染**：0.2.1-alpha.3 移除 `renderMessageImages`、官方图廊迁到 ui-attachment 的 `conversation.images.content` 工厂；shadow 的两个视图在自身渲染里就地调用该工厂（与官方槽位条目同一渲染路径，像素一致），旧宿主优先走 legacy prop——0.1.5 至 0.2.1-alpha.2 行为不变，组合里没有 ui-attachment 时按官方同款语义省略不渲染、工厂后到即自愈。minHost 不变。见 [Agent Note](../../.agents/notes/implemented/architecture/2026-10-18-host-021-message-tools-images-factory.md)
+- **修复编辑/撤回后「已调用工具」折叠头残留**：宿主 ≥0.1.7-alpha.1 把一轮的过程行包进按组键盖章的容器，此前的隐藏规则只按节点键逐行生效——成员行藏了，折叠头容器还亮着，被撤回的内容看似「只剩工具行」。现在组成员关系读官方类型化分组契约（而非 DOM），全部成员隐藏的组容器一并隐藏，部分隐藏的组保留其头。见 [Agent Note](../../.agents/notes/implemented/bug-fix/2026-10-14-message-tools-group-row-hiding.md)
+
 ## 0.3.3（2026-09-30）
 
 无功能变更。加宽 `@deepseek-ai/dsh-*` peer 区间以覆盖宿主 0.2.0（0.2.0 的兼容闸会禁用 peer 区间不覆盖宿主版本的已装插件）。

package/README.en.md

@@ -1,86 +1,52 @@
-# dsh-client-message-tools
+# @khorsheed/dsh-client-message-tools
 
 English | [中文](README.md)
 
-Sent messages can still be edited or withdrawn — and a withdrawal really deletes them from the model's memory, not just marks them.
+Take back or rewrite what you already sent — and a withdrawal really makes the model forget, it doesn't just hide the message on screen.
 
-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.
+Said something too fast, or the conversation went off course? Until now you could only send another message to patch it up, and the detour stayed in the model's memory. With Message Tools, every message you send gets a small row of buttons: want to say it differently, hit edit, change it and resend, and the model answers the new text; want it unsaid, hit withdraw, and the model no longer sees that message or anything after it — while the original text goes back into your composer for you to fix and send again.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions1.png" width="640" alt="copy, edit, and withdraw action buttons under a user message">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions1.png" width="560" alt="copy, edit, and withdraw action buttons under a user message">
 
-## Features
+## What it does
 
-- **Action row on every user message** — copy, edit, and withdraw on user bubbles and admitted steering messages.
-- **Edit in place** — inline editor with a working model chip; saving regenerates the turn from that point, and edited bubbles edit again.
-- **Real withdrawal, not a marker** — the message and the whole tail after it leave the model context, collapsing into an expandable 「已撤回 N 条消息」 divider; expanding it replays the withdrawn user text, the images sent with those messages, and the assistant text (image-only messages count toward N).
-- **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.
+- **Edit and get a fresh answer**: hit edit and the message turns into an input box in place — you can switch the model too; "Save and resend" and the model answers again from there. Edited messages can be edited again.
+- **Withdraw means forgotten**: the message and everything after it leave the model's context; the conversation keeps only a "Withdrawn N messages" line you can expand to read the original.
+- **Your words come back to the composer**: the withdrawn text lands back in the input box for you to rework — it is never sent for you.
+- **Changed your mind? Put it back**: "Restore to the end of the conversation" brings the withdrawn content back, as it was, at the end.
+- **Long messages fold up**: a pasted wall of text folds to about ten lines; "Show all" opens it. The newest message always stays open.
+- **Mentioned sessions read at a glance**: when you @ another session in a message, the bubble shows a small tag with that session's title instead of a raw link.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-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-basic/main/docs/screenshots/message-actions2.png" width="560" 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-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-basic/main/docs/screenshots/message-actions3.png" width="560" 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-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-basic/main/docs/screenshots/message-actions4.png" width="560" 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-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">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions5.png" width="560" alt="restored messages return to the tail of the conversation as they were, grouped under a Restored section">
 
 ## Install
 
-```sh
-dsh plugin --profile web add @khorsheed/dsh-client-message-tools
-```
-
-Restart the web instance to activate; uninstall restores the previous composition exactly.
+In DSH, open Plugins → Add plugin, enter the package name below and click Install:
 
-```sh
-dsh plugin --profile web remove @khorsheed/dsh-client-message-tools
+```
+@khorsheed/dsh-basic
 ```
 
-## Compatibility
-
-- 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. The Session V4 producer-owned source (kind `message-tools`) also writes durably on a 0.1.5 host: 0.1.5's `user/message` admission only requires a non-empty kind string.
-- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.7-rc.2) — Session V4 adaptation: the write side moved to the producer-owned source (kind `message-tools`; V4 native admission refuses the retired `kind: 'plugin'` wrapper), and the read side accepts the new kind, `plugin:message-tools` (the V3→V4 migrated form), and the released V3 wrapper (served verbatim on a 0.1.5 host); the `conversation.chat.node` rc.1 contract (the new hookContext/inject shapes, the `SessionEventLike` match-event union) re-verified; the ui-primitives icon rename (`Icon*Outline14/16` → `Icon*OutlineMedium`) followed.
-
-**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
-
-- **Full-span hiding relies on an undocumented DOM attribute** — if upstream drops it, hiding degrades to renderer-only (user messages still hidden) with one `console.warn`, never an error.
-- **Edit and withdrawal backfill are text-only** — image attachments of the original message do not enter the resend or the backfilled composer draft; they stay visible in the divider's expanded replay, so you can send them again yourself (the host has no public "set draft text + images" API — images can only be re-registered as a fresh upload).
-- **Restore is a tail replay, not an in-place repair** — assistant text replays as framed user-role messages, tool calls/results never; the span stays out of the model context, and the restore entry exists only on withdrawal dividers.
-- **Context and queued messages are out of scope** — context messages keep the official renderer (no action row); the official queue dock already edits/removes queued messages.
-
-## How it works
-
-<details>
-<summary>Internals (click to expand)</summary>
-
-**Architecture.** The browser half shadows the official user-message renderer (`conversation.chat.node`, keys `user` and `steering`, priority -1) with a visual clone that adds the action row, and registers four `ConversationNodeDefinition`s: a withdrawal projects as an expandable 「已撤回 N 条消息」 divider (N = user-visible messages hidden by the span), an edit replacement as an in-place bubble with an 「已编辑」 badge, and a restore entry as a replayed row in the 「已恢复」 group. The host half is the `messageTools` Typert Remote service (`withdraw` / `edit` / `restore`); the client mounts its generated Remote contribution via `ctx.remote.$mount`, so no core-package edits are needed.
-
-**Edit** is an in-place replacement: the host appends one `user/message` replacement whose content IS the edited text (spanning the target and the surface tail — editing an old message discards what followed it), then starts regeneration via `agent.followup` with a minimal producer-sourced trigger. The edited text appears exactly once in the model context; the old content stays in the log as the audit trail. A running turn is cancelled first and awaited until fully settled — settle means the cancelled turn's teardown (tool results, `turn/end`) has fully landed in the log, not the `running` flip; the wait is bounded, a turn that never settles rejects with 「编辑失败」, and a failed cancel rejects without editing. Edit chains work: an edited bubble edits again, targeting the previous replacement's seq. The editor's model chip shares the per-session `ModelDirectory` (`ctx.get('modelDirectories')`, optional) with the composer and the /model popup — without ui-model-selection no chip renders — and the switch applies to the regenerated turn.
-
-**Withdrawal** is real, not a marker: the host appends a `user/message` surface replacement (the compaction mechanism) spanning the target and every surface node after it, so the span leaves `session.surface` and never reaches the model again; the same cancel-and-settle choreography as edit keeps streaming content from landing after the replacement. The event carries the producer-owned source (kind `message-tools`), cites every shadowed node in `sourceEventSeqs`, and is durable (`SessionStore.flush`) before the method returns — it is the audit trail. No new event type is introduced: an out-of-harness type cannot carry `ignorable: true`, and a persisted unknown type would make session-persistence refuse the log on reload. A landed withdrawal backfills the target's original text into the composer draft (blank fills, non-empty appends a new line, info notice) — never auto-sent, nothing on failure; edits never backfill.
-
-**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 — text and the images sent with them — plus assistant text, folded from the live node store; images render through the official attachment gallery slot `renderMessageImages`, and a composition without it degrades to the text replay instead of throwing) 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 producer-sourced user message — `assistant/message` requires the model 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.
-
-**Model experience.**
-
-- *Edit replacement* — the model reads the edited text and nothing that followed the original, plus one short trigger (`(用户编辑了上一条消息，请按编辑后的内容重新回答)`). Token effect: the shadowed span's tokens leave subsequent requests; the edit adds the edited message plus the trigger. KV cache: the prompt prefix is invalidated from the edit point.
-- *Withdrawal replacement* — the span is replaced by one placeholder (`(用户撤回了这条消息及其后的所有内容)`). Token effect: the span's tokens leave; one short message is added. KV cache: the prefix is invalidated from the replacement point — the same trade compaction makes; withdrawing an older message discards more cached prefix.
-- *Restore replay* — the span's replayable content (user messages verbatim, assistant text behind the frame) appends at the tail in original order, producer-tagged and citing original events; tool tokens stay out. KV cache: none beyond an ordinary tail append.
+Message Tools comes with Basic Essentials. Once installed, the button row sits under every message you send, in any session.
 
-**Exports.** `/client` exports the plugin body (`apply`/`inject`) and the `MessageToolsRemote` type; the host export is the `MessageToolsService` class plus wire types under `/types`.
+## Known limitations
 
-</details>
+- Edit and withdraw bring back text only: images in the original message are not resent or put back in the composer — upload them again if you need them (they stay visible in the withdrawal record).
+- Restore puts the content back at the end of the conversation, not in its original place; the agent's tool calls from back then are not replayed.
+- Messages still waiting in the queue are not covered — edit those from the queue bar above the composer.
 
-## Development
+## Compatibility
 
-Part of the [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo (`packages/message-tools`). Issues and contributions welcome there.
+Requires DSH 0.1.5-rc.1 or later; verified on 0.2.1-rc.1.
 
-## Changelog
+## For developers
 
-See [CHANGELOG.md](CHANGELOG.md).
+- Per-host-line compatibility details, how edit / withdraw / restore work and what they do to the model's context: see the [full reference](https://github.com/Khorsheed/dsh-plugins/blob/main/packages/client-message-tools/docs/reference.en.md).
+- You can also install it alone: enter `@khorsheed/dsh-client-message-tools` in Add plugin, or run `dsh plugin --profile web add @khorsheed/dsh-client-message-tools`, then restart.
+- Part of [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) — file issues and contributions there; changes are in [CHANGELOG.md](CHANGELOG.md).

package/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record: the git blob hash of each side as of the
 # 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: 497c066e41b335c76e0a9ff910c81cf036e525d4
-packages/message-tools/README.md: 78ac08d243b717b3325a65f31b60f03c53bc4329
+#   pnpm run verify-translation-pairing --write packages/client-message-tools/README.en.md
+packages/client-message-tools/README.en.md: 23904d71e3ab4dfe9cf172b1daa21a0feee60411
+packages/client-message-tools/README.md: 32abe70978661af681ba76496234cd16cc40158e

package/README.md

@@ -2,85 +2,51 @@
 
 [English](README.en.md) | 中文
 
-发出去的话还能改、还能撤——撤回是真从模型记忆里删掉，不是打个标记。
+发出去的话还能改、还能撤——撤回是真的让模型忘掉，不只是在界面上藏起来。
 
-话说快了、方向跑偏了，以前只能再发一条往回找补。这个插件给你发出的每条消息配上一排小按钮：复制、编辑、撤回。编辑是原地改完重新发，模型按新内容重新回答；撤回会把这条消息和它后面的所有内容一起请出模型上下文，折叠成一条可以展开的「已撤回 N 条消息」分隔线，原话还会自动回填到输入框草稿（绝不替你发送）。后悔了，点分隔线上的「恢复到对话末尾」就能把内容原样放回去。
+话说快了、方向跑偏了，以前只能再发一条往回找补，跑偏的那段还一直留在模型的记忆里。装上消息工具，你发的每条消息下面都有一排小按钮：想换个说法就点编辑，改完重新发，模型照新内容重新回答；想当没说过就点撤回，这条和它后面的内容模型都不会再看到，原话还会放回输入框，等你改好再发。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions1.png" width="640" alt="用户消息下方的复制、编辑、撤回操作按钮">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions1.png" width="560" alt="用户消息下方的复制、编辑、撤回操作按钮">
 
-## 特性
+## 能做什么
 
-- **每条用户消息都有操作行**——用户气泡与已吸入轮次的 steering 消息带复制、编辑、撤回操作。
-- **就地编辑**——内联编辑框带真实可用的模型 chip；保存后从该处重新生成，已编辑的气泡可再次编辑。
-- **真撤回，不是打标记**——消息及其后整个尾部离开模型上下文，折叠为可展开的「已撤回 N 条消息」分隔线；展开即可只读回放被撤回的用户原文、随消息发出的图片与助手文本（纯图片消息同样计入 N）。
-- **草稿回填**——撤回成功后把原文回填到 composer 草稿，绝不自动发送。
-- **恢复到尾部**——「恢复到对话末尾」把用户消息逐字重放、助手文本重放为「已恢复」组；工具调用永不重放。
+- **改完就重新回答**：点编辑，消息原地变成输入框，还能顺手换个模型；点「保存并重新发送」，模型从这里重新回答。改过的消息还能再改。
+- **撤回是真忘掉**：撤回后这条消息和它后面的内容都不再进入模型的上下文，对话里只留一条「已撤回 N 条消息」，点开还能看原文。
+- **原话回到输入框**：撤回的那句话自动放回输入框，改一改再发；它不会替你发出去。
+- **后悔了能放回来**：点「恢复到对话末尾」，撤回的内容原样回到对话最后。
+- **长消息自动折起**：贴了一大段的消息折成十来行，点「展开全部」再看；最新那条一直展开着。
+- **@ 过的会话一眼认出**：消息里 @ 了另一个会话，气泡里显示成带会话标题的小标签，不是一串链接。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions2.png" width="640" alt="原位编辑：消息变成带模型选择的输入框，保存后以新消息重新发送，被编辑消息不再进入模型上下文">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions2.png" width="560" alt="原位编辑：消息变成带模型选择的输入框，保存后以新消息重新发送，被编辑消息不再进入模型上下文">
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions3.png" width="640" alt="撤回前的确认弹窗：说明这条消息及其后内容将对模型隐藏、原文会回填到输入框">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions3.png" width="560" alt="撤回前的确认弹窗：说明这条消息及其后内容将对模型隐藏、原文会回填到输入框">
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions4.png" width="640" alt="撤回后的内容折叠为可展开的分隔线，底部有「恢复到对话末尾」按钮">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions4.png" width="560" alt="撤回后的内容折叠为可展开的分隔线，底部有「恢复到对话末尾」按钮">
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions5.png" width="640" alt="恢复后消息原样回到对话末尾，归入「已恢复」分组">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/message-actions5.png" width="560" alt="恢复后消息原样回到对话末尾，归入「已恢复」分组">
 
 ## 安装
 
-```sh
-dsh plugin --profile web add @khorsheed/dsh-client-message-tools
-```
-
-重启 web 实例后生效；卸载即精确还原之前的组合。
+在 DSH 的「插件 → 添加插件」里输入下面的包名，点安装：
 
-```sh
-dsh plugin --profile web remove @khorsheed/dsh-client-message-tools
+```
+@khorsheed/dsh-basic
 ```
 
-## Compatibility
-
-- 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，旧宿主请停留在旧发布线。Session V4 的生产者归属 source（kind `message-tools`）在 0.1.5 宿主同样合法落盘：0.1.5 的 `user/message` 准入只要求非空 kind 字符串。
-- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.7-rc.2）——Session V4 适配：写侧改生产者归属 source（kind `message-tools`，V4 原生准入拒绝退役的 `kind: 'plugin'` 包装），读侧兼认新 kind、`plugin:message-tools`（V3→V4 迁移形态）与 V3 包装存量（0.1.5 宿主原位读取）；`conversation.chat.node` rc.1 契约（hookContext/inject 新形状、match 事件 `SessionEventLike` 并集）复验通过；ui-primitives 图标改名（`Icon*Outline14/16` → `Icon*OutlineMedium`）跟进。
-
-**版本线对照**：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` 一次，绝不报错。
-- **编辑与撤回回填只带文本**——原消息的图片附件不会带入重发或回填的输入框草稿；图片仍留在分隔线的展开回放里，可以自行另发（宿主没有"文本 + 图片一起设置草稿"的公开 API，图片只能作为一次新上传重新登记）。
-- **恢复是尾部重放，不是原位修复**——助手文本以带框架的用户角色消息重放，工具调用/结果永不重放；撤回区间始终留在模型上下文之外，恢复入口只在撤回分隔线上。
-- **context 与排队消息不在范围内**——context 消息沿用官方渲染器（无操作行）；仍在排队的消息由官方队列条带编辑/移除。
-
-## 实现原理
-
-<details>
-<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，无需改动任何核心包。
-
-**编辑**即原位替换：host 追加一条 `user/message` replacement，其内容就是编辑后的新文本（区间覆盖目标消息及 surface 尾部——编辑旧消息就是放弃其后的一切），随后经 `agent.followup` 投递一条极简生产者来源触发消息启动重新生成。模型上下文里新文本只出现一次；旧内容留在日志里作审计。会话有运行中的轮次时先取消它并等待完全落定——落定指被取消轮次的收尾（工具结果、`turn/end`）全部落盘，而不是 `running` 翻转；等待有界，迟迟不落定的轮次以「编辑失败」拒绝，取消失败则不编辑。支持编辑链：已编辑气泡可再次编辑，目标是上一个 replacement 的 seq。编辑框的模型 chip 与 composer、/model 弹层共享按会话的 `ModelDirectory`（`ctx.get('modelDirectories')`，可选服务）——组合里没有 ui-model-selection 就不渲染 chip——切换经 host 校验后作用于重新生成的轮次。
+- 编辑和撤回只带回文字：原消息里的图片不会跟着重发或回到输入框，要的话自己再传一次（撤回记录里还能看到它们）。
+- 恢复是把内容放回对话末尾，不是放回原来的位置；当时 agent 调用工具的过程不会重演。
+- 还在排队、没发出去的消息不归它管，用输入框上方的排队条去改。
 
-**撤回**是真撤回，不是打标记：host 追加一条 `user/message` surface replacement（与 compaction 同一机制），区间覆盖目标消息及之后的所有 surface 节点，该区间由此离开 `session.surface`，不再进入模型上下文；与编辑同款的 cancel-and-settle 编排保证流式内容不会落到 replacement 之后。事件为生产者来源（source kind `message-tools`），`sourceEventSeqs` 引用每一个被遮蔽节点，方法返回前经 `SessionStore.flush` 落盘——它本身就是审计轨迹。不引入新事件类型：harness 之外的类型无法携带 `ignorable: true`，持久化的未知类型会让 session-persistence 重载时拒绝整个日志。撤回成功后把目标原文回填到 composer 草稿（空草稿直接填入、非空换行追加、落 info 提示）——绝不自动发送，失败则不回填；编辑路径不触发回填。
-
-**投影与隐藏。** 插件的 Definition 把 replacement 认领为锚定在其 seq 上的分隔线节点。隐藏分两层：被遮蔽的用户渲染器对区间内用户消息渲染为空；一张动态样式表把 `data-chat-flow-key`（`ChatNodeSeat.tsx`）锚点落在区间内的聊天行一律隐藏，覆盖助手步骤、工具调用、turn 尾部。隐藏器在首个非空规则集探测这个未文档化属性，探测落空进入有界重试（MutationObserver 加截止时限），避免聊天区尚未挂载时误停用；只有窗口耗尽仍探不到行才停用——`console.warn` 一次，退化为仅渲染器隐藏——且 observer 在停用后仍存活，行晚到会重新生效，绝不报错。分隔线可就地展开只读回放撤回区间（用户原文与随消息发出的图片、加助手文本，从实时节点存储折叠；图片交给官方附件画廊槽位 `renderMessageImages` 渲染，组合里没有它时退化为纯文本回放而不报错）并提供「恢复到对话末尾」；行已掉出加载窗口的区间显示「撤回的内容不在当前已加载的历史中」。
-
-**恢复**是整个被撤回区间的尾部重放，不是原位修复：surface 折叠是位置性的——被替换区间只接续成一个节点（`applySurfacePlan`）——区间无法回到模型上下文原位，其模型侧隐藏也永不回退。host 沿撤回 replacement 自身划定的日志区间 `[start, seq)` 把可重放内容按原始顺序逐条追加到尾部：用户消息逐字重放（编辑替换的内容就是最后一次编辑的新文本，恢复时即以此为准），每条助手回复的文本以带框架的生产者来源用户消息重放——`assistant/message` 只能携带 model 来源，且轨迹不允许在 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 里。
-
-**模型体验。**
-
-- *编辑替换*——模型读到编辑后的文本，原消息之后的内容全部消失；其后跟一条短触发消息（`(用户编辑了上一条消息，请按编辑后的内容重新回答)`）。Token 影响：被遮蔽区间的全部 token 离开后续请求，新增编辑后消息与触发消息。KV Cache：prompt 前缀从编辑点失效。
-- *撤回替换*——区间被一条占位消息（`(用户撤回了这条消息及其后的所有内容)`）取代。Token 影响：区间的全部 token 离开，只新增一条短消息。KV Cache：前缀从替换点失效——取舍与 compaction 相同；撤回越早的消息，失效的缓存前缀越多。
-- *恢复重放*——区间的可重放内容（用户消息逐字、助手文本带框架）按原始顺序追加到尾部，插件标记并引用原事件；工具调用/结果的 token 不进入。KV Cache：不超出普通尾部追加的范围。
-
-**导出。** `/client` 导出插件本体（`apply`/`inject`）与 `MessageToolsRemote` 类型；host 侧导出 `MessageToolsService` 类，`/types` 子路径提供线上类型。
-
-</details>
-
-## 开发
+## Compatibility
 
-隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo（`packages/message-tools`）。问题与贡献请移步该仓库。
+需要 DSH 0.1.5-rc.1 或更新版本，已在 0.2.1-rc.1 上验证。
 
-## 变更记录
+## 给开发者
 
-见 [CHANGELOG.md](CHANGELOG.md)。
+- 各宿主版本线的兼容细节、编辑 / 撤回 / 恢复的实现原理和对模型上下文的影响，见[完整参考](https://github.com/Khorsheed/dsh-plugins/blob/main/packages/client-message-tools/docs/reference.md)。
+- 也可以单独安装：在「添加插件」里输入 `@khorsheed/dsh-client-message-tools`，或 `dsh plugin --profile web add @khorsheed/dsh-client-message-tools`，重启后生效。
+- 隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins)，问题与贡献请到该仓库；变更见 [CHANGELOG.md](CHANGELOG.md)。