dsh-quote-annotate-pro 0.2.11 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 本项目的所有重要变更都记在这里。版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## 0.3.0 — 编号批注 + 回复逐条对照
+
+- **批注自动编号**：同一条消息里每次插入批注都会编号（`批注 1`、`批注 2`…，删掉中间某条不会重号，见 `nextAnnotationNo()`）；
+  输入框里 chip 变成 `批注1`，发送后的引用块首行变成 `【批注 2 · 第5轮 · DSH 回复】` —— 模型看到的是"第几处批注 + 哪一轮 + 谁说的"
+- **评语写进正文**：评语不再作为普通文本追加在 chip 之后，而是作为 `批注：…` 跟在原文后面（空行分隔）——
+  发送出去的整条消息自带"原文 + 评语"，不再依赖草稿里散落的文本
+- **回复逐条对照**：第一条批注的位置行里内嵌「请按『Annotation 1：』『Annotation 2：』…格式逐条回应我的批注」的指令
+  （位置行在界面上被隐藏，模型仍然看得到）；模型回复里的 `Annotation N：` 会被渲染成 `批注 N` 芯片：
+  **悬浮显示该条批注的原文与评语，点击跳回原文并高亮**
+- **完全客户端实现**：编号、评语、回复芯片的数据都从消息 DOM 里自解析（引用块带 `data-dshq-no` / `-quote` / `-comment`），
+  不新增宿主半区代码、不改消息文本以外的任何语义；装饰逻辑仍遵守「不破坏用户选区 / 幂等 / 观察器内同步执行」三条约束
+- 兼容旧消息：0.2.x 发出去的 `【引用 · …】` 仍按原样渲染成紧凑引用块（只是没有编号与回复芯片）
+- 新增 `tools/test-client.mjs` 纯函数自检（编号 / 位置行解析 / 输入框摘要等 8 组断言，无需浏览器与网络）：
+  `npm test` 与 CI 都会跑；`lib/client.js` 末尾导出 `__test`（宿主只读 `name` / `inject` / `apply`，不影响加载）
+
+## 0.2.12 — 定位改造：从"功能罗列"改成"设计取舍"（README 首屏）
+
+- 首屏不再从"fork 了什么"讲起，改成一句话主张：**划词 → 批注 → 引用；发送之后引用块仍然看得见，点一下回到原文**
+- 新增「设计取舍」小节：与"把引用收进 chip / 标签"的常见做法做对照（气泡里能不能看见引的是哪段、怎么回到原文、模型侧是否带轮次角色、代价是什么），
+  明确本插件走的是**引用可见**这条路线 —— 依据是 2026-10 市场快照里同类插件约 20 个、多数采用折叠式设计
+- 新增「三步上手」（选区气泡 → 输入框引用条 → 消息里的引用块）与收录去向说明（in-DSH dshmarket / DSH Market / dsh-plugin.org / dsh.pub / dsh-xray / HackSing / awesome-deepseek-harness）
+- npm `description` 改为同一口径（强调"引用块始终可见 + 点回原文"，去掉容易引起歧义的网络表述）
+- README.en、package.json 同步；仅文档与元数据变更，代码行为不变
+
 ## 0.2.11 — 简介同步到当前行为（npm + GitHub）
 
 - npm 包的 `description` 还停留在 0.2.1 时代的表述（"输入框**上方**只显示原文片段"）—— 已改为如实描述当前行为：

package/README.en.md

@@ -4,25 +4,51 @@
 [![ci](https://github.com/zhao-guang-ai/dsh-quote-annotate-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/zhao-guang-ai/dsh-quote-annotate-pro/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-**Select → annotate → quote, inside a DSH conversation.** The selected text enters the composer as an anchored quote reference; on send it serializes into a structured quote block, and a quote bar under the composer jumps back to the exact source message and highlights it. The model sees `【引用 · 第N轮 · DSH 回复】` — which turn, whose message — so it no longer has to guess what "that part above" means.
+**Select → annotate → quote. After you send, the quote is still visible — and one click takes you back to the source.**
 
-> An enhanced fork of [`dsh-quote-annotate`](https://github.com/wangwei-wade/dsh-quote-annotate) (MIT, by wangwei-wade).
-> Upstream v0.1.1 **fails silently** on **DSH 0.2.0-rc.2** (loads without error, registers no UI at all). This fork fixes 4 compatibility
-> problems, adapts 2 further interface changes, and adds 3 capabilities. Still MIT — see [LICENSE](./LICENSE).
-> Full write-up: [SUMMARY.md](./SUMMARY.md) (Chinese).
+Selected text becomes an anchored quote block: in the composer and in the sent message it renders as a **compact quoted snippet** (max 3 lines, the turn/role line hidden), and clicking it jumps back to the source message and highlights it. What the model receives still carries **which annotation it is, which turn and whose message** (`【批注 2 · 第5轮 · DSH 回复】`) plus an instruction to answer with `Annotation 1:`, `Annotation 2:` … — and **each `Annotation N:` in the reply becomes a `批注 N` chip: hover to see the quoted text and your comment, click to jump back to the source.**
+
+> Listed in the in-DSH market (`dshmarket`), [DSH Market](https://dsh.market/?q=zhao-guang-ai%2Fdsh-quote-annotate-pro), [dsh-plugin.org](https://dsh-plugin.org/zh/plugins/zhao-guang-ai/dsh-quote-annotate-pro), dsh.pub, dsh-xray, HackSing/dsh-plugins, and [awesome-deepseek-harness](https://github.com/0xsline/awesome-deepseek-harness).
+
+## The design choice: keep the quote *visible* instead of folding it into a chip
+
+Most selection-quote/annotation plugins **hide the quote**: the bubble keeps only a `引用1` chip or a "批注 ×N" tag, and you open or hover it to see the text. This plugin takes the other road:
+
+| | Fold into a chip / tag (common) | **This plugin: compact quote block** |
+|---|---|---|
+| Sent bubble | Just a chip/tag — you can't see what was quoted | **Shows the quoted snippet** (max 3 lines, truncated) |
+| Comparing with the source | Hover or expand the tag | **Click the block → jump back + highlight** |
+| Composer | Short chip label | Same quoted snippet as in the message |
+| Model side | Implementation-dependent | Text still starts with `【引用 · 第N轮 · 角色】` — position preserved |
+| Cost | Cleaner bubbles | One grey quote area (hence 3 lines + hidden turn/role line) |
+
+In one sentence: **a quote is part of the conversation and should not be hidden.** If you prefer absolutely clean bubbles with quotes only on hover, other plugins do that better; if you keep asking "which sentence did I quote here?", that is why this plugin exists.
+
+## Quick start
+
+1. **Select text** in any message → a bubble appears above the selection → click 「批注」 → write a comment (optional) → `Enter`.
+2. A quote lands in the composer; a **quote strip above the composer** shows the same snippet and jumps back to the source on click.
+3. After sending, the bubble keeps the compact quote block — click it any time to return to the source and highlight it. Each finished turn also gets 「引用提问 / 引用回答」 to quote the whole turn.
 
 ## Features
 
 | Capability | Detail |
 | --- | --- |
 | Select & annotate | Select text in the transcript → a bubble appears above the selection → write a comment (optional) → `Enter` |
-| Quote chip | An atomic `引用1` chip (short label) lands in the composer; it expands to the full quote block on send |
+| **Automatic numbering** | Multiple annotations in one message are numbered (`批注 1`, `批注 2`, …; deleting one never reuses a number); the chip reads `批注1`, the model sees `【批注 N · 第5轮 · 角色】` |
+| Quote chip | An atomic `批注1` chip (short label) lands in the composer; it expands to the full quote block on send |
 | **Quote block (in the composer)** | After inserting a quote the composer shows only the **quoted text** (the turn/role line is hidden); click it to jump back to the source and highlight it — no visible "jump" affordance |
-| **Compact quotes in the transcript** | A sent message shows only a **compact quote block** (up to 3 lines). The message text still starts with `【引用 · 第N轮 · 角色】` — hidden in the UI, so the model keeps the position context |
-| **Turn-accurate context** | The quote block starts with `【引用 · 第3轮 · 你的消息】` followed by `> quoted text`, so the model knows exactly which turn and whose message |
+| **Compact quotes in the transcript** | A sent message shows only a **compact quote block** (up to 3 lines) followed by `批注：…`. The message text still starts with the position line — hidden in the UI, so the model keeps the position context |
+| **Per-annotation replies** | The protocol instruction is embedded in the first position line (hidden in the UI); `Annotation N:` in the model's reply renders as a `批注 N` chip — hover for the quoted text + comment, click to jump back to the source |
+| **Turn-accurate context** | The quote block starts with `【批注 2 · 第3轮 · 你的消息】` followed by the quoted text and your comment, so the model knows exactly which annotation, which turn and whose message |
 | Turn-level quoting | Every finished turn gets `引用提问` / `引用回答` buttons that quote the whole question or answer |
 | Anchors survive reload | The `ref → anchor` map is persisted in `localStorage` (per session, 60 entries max), so quotes still jump after a page refresh |
 
+> An enhanced fork of [`dsh-quote-annotate`](https://github.com/wangwei-wade/dsh-quote-annotate) (MIT, by wangwei-wade).
+> Upstream v0.1.1 **fails silently** on **DSH 0.2.0-rc.2** (loads without error, registers no UI at all). This fork fixes 4 compatibility
+> problems, adapts 2 further interface changes, and adds 3 capabilities. Still MIT — see [LICENSE](./LICENSE).
+> Full write-up: [SUMMARY.md](./SUMMARY.md) (Chinese).
+
 ## Install
 
 ```sh
@@ -51,10 +77,12 @@ composer chip (an official Lexical decorator node)
   │ on send, this plugin's codec serializes the ref
   ▼
 【引用 · 第N轮 · 角色】
-> quoted text
+quoted text
 (comment)
 
-jump back: quote bar / chip → [data-chat-anchor-key] row → scrollIntoView + highlight
+On the UI side the plugin wraps the turn/role line and the quoted text at render time:
+the line is hidden, the text becomes a compact block, and clicking the block scrolls
+back to the anchor and highlights it (no visible affordance).
 ```
 
 Official surfaces used: `slots` (`shell.overlay`, `conversation.chat.turnTail`, `conversation.input.dock`),

package/README.md

@@ -4,56 +4,53 @@
 [![ci](https://github.com/zhao-guang-ai/dsh-quote-annotate-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/zhao-guang-ai/dsh-quote-annotate-pro/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-**在 DSH 会话里划词 → 批注 → 引用**：选中的文字变成带锚点的引用进入输入框，发送时序列化为结构化引用块；输入框下方常驻一条**引用导航条**，点一下就能跳回原文并高亮。多轮对话里，模型看到的是 `【引用 · 第N轮 · 你的消息】`，不再需要猜"你说的是哪一处"。
+**划词 → 批注 → 引用；发送之后，引用块仍然看得见，点一下就能回到原文。**
 
-> 这是 [`dsh-quote-annotate`](https://github.com/wangwei-wade/dsh-quote-annotate)（MIT，作者 wangwei-wade）的增强 fork。
-> 上游 v0.1.1 在 **DSH 0.2.0-rc.2** 上会**静默失效**（既不报错也不注册任何 UI），本 fork 修掉了 4 个兼容性问题，
-> 并补上了 3 项能力；另有 2 个接口变化（当前会话、chip DOM 定位）一并适配。许可仍为 MIT，见 [LICENSE](./LICENSE)。
-> 完整汇总见 [SUMMARY.md](./SUMMARY.md)。
+选中的文字变成带锚点的引用块：输入框里、已发送的消息里都只显示**紧凑的原文片段**（最多 3 行，轮次/角色那一行被隐藏），点它跳回原文并高亮；而发给模型的文本仍标明**这是第几处批注 + 哪一轮 + 谁说的**（`【批注 2 · 第5轮 · DSH 回复】`），并要求模型按 `Annotation 1：`、`Annotation 2：` 逐条回应 —— **回复里的每个 `Annotation N：` 都会渲染成 `批注 N` 芯片，悬浮看原文与评语，点击跳回原文。**
+
+> 已收录：in-DSH 市场（`dshmarket`）、[DSH Market](https://dsh.market/?q=zhao-guang-ai%2Fdsh-quote-annotate-pro)、[dsh-plugin.org](https://dsh-plugin.org/zh/plugins/zhao-guang-ai/dsh-quote-annotate-pro)、dsh.pub、dsh-xray、HackSing/dsh-plugins、[awesome-deepseek-harness](https://github.com/0xsline/awesome-deepseek-harness)。
+
+## 设计取舍：引用块"看得见"，而不是收进 chip
+
+划词引用/批注这类插件，市场上的主流做法是**把引用收起来**：气泡里只剩一颗 `引用1` chip 或一个「批注 ×N」标签，原文要点开或悬停才能看到。本插件走的是另一条路：
+
+| | 收进 chip / 标签（常见做法） | **本插件：紧凑引用块** |
+|---|---|---|
+| 发送后的气泡 | 只剩 chip / 标签，看不到引的是哪段 | **直接显示原文片段**（最多 3 行，超长省略） |
+| 想对照原文 | 悬停或点开标签 | **点引用块 → 跳回原文并高亮** |
+| 输入框 | chip 短标签 | 同样显示原文片段，与消息里一致 |
+| 模型侧 | 取决于实现 | 文本仍带 `【引用 · 第N轮 · 角色】`，位置不丢 |
+| 代价 | 气泡更"干净" | 气泡会多一块灰底引用区（所以压到 3 行、隐藏位置行） |
+
+一句话：**引用是对话的一部分，不该被藏起来。** 如果你更希望气泡绝对干净、只在悬停时看引用，市面上有更合适的方案；如果你常要"这段是我引的哪一句"来回对照，这就是本插件存在的理由。
+
+## 三步上手
+
+1. 在任意消息里**选中一段文字** → 选区上方浮出小气泡 → 点「批注」→ 写评语（可留空）→ `Enter`；
+   同一条消息里可以连续批注多处，插件会自动编号（`批注 1`、`批注 2`…）；
+2. 输入框里出现带编号的引用；**输入框上沿**同时出现一条引用块，点它可跳回原文；
+3. 发送后气泡里仍是紧凑引用块，点它随时回到原文并高亮；模型回复里的 `Annotation 1：`、`Annotation 2：`
+   会变成 `批注 N` 芯片 —— **悬浮看这条批注的原文与评语，点击跳回原文**。
 
 ## 功能
 
 | 能力 | 说明 |
 |---|---|
 | 划词批注 | 会话里选中任意文字 → 选区上方浮出气泡（预览 + 「批注」）→ 编辑框里写评语（可留空）→ `Enter` 插入 |
-| 引用 chip | 输入框里出现 `引用1` 的原子 chip（短标签）；发送时展开为完整引用块 |
+| **自动编号** | 同一条消息里多处批注依次编号（删掉中间某条不会重号）；chip 显示 `批注1`，模型侧显示 `【批注 N · 第5轮 · 角色】` |
+| 引用 chip | 输入框里出现 `批注1` 的原子 chip（短标签）；发送时展开为完整引用块 |
 | **引用块（输入框内）** | 插入引用后输入框里只显示**原文片段**（位置行隐藏）；**点一下即跳回原文并高亮** —— 不做任何可见的"跳转"提示 |
-| **对话页里的紧凑引用** | 已发送消息里的引用同样只显示**紧凑原文块**（最多 3 行）。**消息文本仍以 `【引用 · 第N轮 · 角色】` 开头** —— 界面隐藏、模型照旧知道出处 |
-| **模型侧精确定位** | 引用块首行是 `【引用 · 第5轮 · 你的消息】`，后接 `> 原文`，让模型明确知道**哪一轮、谁说的** |
+| **对话页里的紧凑引用** | 已发送消息里的引用同样只显示**紧凑原文块**（最多 3 行），评语以 `批注：…` 跟在其后。**消息文本仍以位置行开头** —— 界面隐藏、模型照旧知道出处 |
+| **回复逐条对照** | 协议指令内嵌在第一条批注的位置行里（界面隐藏）；模型回复的 `Annotation N：` 渲染成 `批注 N` 芯片，悬浮显示原文 + 评语，点击跳回原文 |
+| **模型侧精确定位** | 引用块首行是 `【批注 2 · 第5轮 · 你的消息】`，后接原文与评语，让模型明确知道**哪一处、哪一轮、谁说的** |
 | 回合级引用 | 每条已完成回合尾部有「引用提问 / 引用回答」，整段引用该轮 |
 | 锚点持久化 | `ref → 锚点` 映射写入 `localStorage`（按会话，最多 60 条），**刷新页面后引用块仍能跳回原文** |
 | 中英自适应 | 按钮文案跟随界面语言（沿用上游） |
 
-## 与上游的差异
-
-### 兼容性修复（否则整插件静默失效）
-
-1. **缺 cordis 依赖声明** —— 上游 `apply(ctx)` 里 `const slots = ctx.get('slots')`，拿不到就 `return`。
-   没有声明 `inject: ['slots']` 时 `apply` 可能早于 slots 服务就绪执行，于是**无声退出，一个 UI 都不注册**。
-   → 本 fork 声明 `exports.name` + `exports.inject = ['slots']`，并给每一步注册加 `try/catch` + 上报。
-
-2. **`conversation.chat.turnTail` 已从 chain 变 list**（DSH 0.1.6-alpha.2 起）—— 上游仍用 `{ select, priority }` 注册，
-   会抛错；而它排在 4 个 overlay 注册**之前**，一崩全崩。→ 改为 `{ name, id, order }`。
-
-3. **chip 插入 API 变了** —— 上游调用 `input.insertReference(...)`，该对象在本版本没有此方法，永远退化为纯文本。
-   → 改走官方会话事件 `slash/input-insert-reference`（与 `dsh-better-sidebar` 同一条在本版本已验证的通路）。
-
-4. **回合尾部按钮不出现（快照形状变了）** —— 上游用 `useSession` 的快照 + `Array.isArray(snapshot.nodes)` + 节点 `seq`
-   来取该轮文本；本版本真实形状是 **Chat 快照（`useChat`）**、**`nodes` 是 Map**、**节点身份是 `anchorSeq`**、
-   文本在 `user.data.content[{type:'text'}]` / `assistant-step.data.blocks[{kind:'text'}]`，
-   assistant 节点 kind 也不是 `assistant` 而是 `assistant-step`。→ 全部按本版本形状重写取文与锚点解析。
-
-### 能力增强
-
-5. **当前会话解析** —— 上游读 `useSessions(s => s.current)`，而**本版本会话列表快照没有 `current` 字段**（恒为 `undefined`），
-   导致点「批注」只关掉气泡、什么都不发生。→ 改为由**会话作用域槽位**（`conversation.input.dock` 探针）回填 `sessionId`，
-   并去掉"必须先解析到会话才开编辑框"的门槛（解析失败也照常进入编辑，插入时再解析）。
-
-6. **引用块带轮次/角色** —— 上游只发 `> 原文`。→ 首行加 `【引用 · 第N轮 · 角色】`（轮次取自 `data-chat-turn`，角色取自 `data-chat-flow-kind`）。
-
-7. **输入框上方的引用块 + 锚点持久化** —— 本版本输入框 chip **没有 `data-*` 属性**（只有 CSS 类），上游"点 chip 跳转"不可能成立。
-   → 改为读官方输入状态 `occurrences`（`source === 'quote-ref'`）渲染引用块，只显示**原文片段**（不显示标签/轮次，保持简洁）；
-   `ref → 锚点` 落 `localStorage`，刷新后仍可跳。（输入框 chip 本体也支持点击跳转：按 `title` = label 反查 ref，不依赖 CSS 类顺序。）
+> 这是 [`dsh-quote-annotate`](https://github.com/wangwei-wade/dsh-quote-annotate)（MIT，作者 wangwei-wade）的增强 fork。
+> 上游 v0.1.1 在 **DSH 0.2.0-rc.2** 上会**静默失效**（既不报错也不注册任何 UI），本 fork 修掉了 4 个兼容性问题，
+> 并补上了 3 项能力；另有 2 个接口变化（当前会话、chip DOM 定位）一并适配。许可仍为 MIT，见 [LICENSE](./LICENSE)。
+> 完整汇总见 [SUMMARY.md](./SUMMARY.md)。
 
 ## 安装
 
@@ -89,19 +86,55 @@ emit('slash/input-insert-reference', { reference, span })      ← 官方会话
   │ 发送
   ▼
 本插件 codec.serialize(ref) → 完整引用块
-     【引用 · 第5轮 · DSH 回复】
-     > 原文……
-     （你的评语）
+     【批注 1 · 第5轮 · DSH 回复（请按「Annotation 1：」「Annotation 2：」…格式逐条回应）】
+     原文……
+
+     批注：你的评语
+  ▼
+模型收到"第几处批注 + 哪一轮 + 谁说的 + 原文 + 评语"
   ▼
-模型收到"哪一轮 + 谁说的 + 原文"
+模型回复里出现 Annotation 1：… → 插件渲染成「批注 1」芯片
+     （悬浮看原文+评语，点击跳回原文）
 
-跳回原文：引用块/锚点 → [data-chat-anchor-key] 行 → scrollIntoView + 高亮（无可见提示）
+界面侧：插件在渲染时把位置行与引用正文包成紧凑块（隐藏位置行、只留原文），
+        点击引用块 → 按锚点 scrollIntoView + 高亮（无可见提示）。
 ```
 
 用到的官方接口：`slots`（`shell.overlay` / `conversation.chat.turnTail` / `conversation.input.dock`）、
 `conversation.input`（草稿 + occurrences）、`sessions.binding/scope`、`inputTriggers.registerSource` + codec、
 DOM 锚点 `data-chat-anchor-key` / `data-chat-turn`。
 
+## 与上游的差异
+
+### 兼容性修复（否则整插件静默失效）
+
+1. **缺 cordis 依赖声明** —— 上游 `apply(ctx)` 里 `const slots = ctx.get('slots')`，拿不到就 `return`。
+   没有声明 `inject: ['slots']` 时 `apply` 可能早于 slots 服务就绪执行，于是**无声退出，一个 UI 都不注册**。
+   → 本 fork 声明 `exports.name` + `exports.inject = ['slots']`，并给每一步注册加 `try/catch` + 上报。
+
+2. **`conversation.chat.turnTail` 已从 chain 变 list**（DSH 0.1.6-alpha.2 起）—— 上游仍用 `{ select, priority }` 注册，
+   会抛错；而它排在 4 个 overlay 注册**之前**，一崩全崩。→ 改为 `{ name, id, order }`。
+
+3. **chip 插入 API 变了** —— 上游调用 `input.insertReference(...)`，该对象在本版本没有此方法，永远退化为纯文本。
+   → 改走官方会话事件 `slash/input-insert-reference`（与 `dsh-better-sidebar` 同一条在本版本已验证的通路）。
+
+4. **回合尾部按钮不出现（快照形状变了）** —— 上游用 `useSession` 的快照 + `Array.isArray(snapshot.nodes)` + 节点 `seq`
+   来取该轮文本；本版本真实形状是 **Chat 快照（`useChat`）**、**`nodes` 是 Map**、**节点身份是 `anchorSeq`**、
+   文本在 `user.data.content[{type:'text'}]` / `assistant-step.data.blocks[{kind:'text'}]`，
+   assistant 节点 kind 也不是 `assistant` 而是 `assistant-step`。→ 全部按本版本形状重写取文与锚点解析。
+
+### 能力增强
+
+5. **当前会话解析** —— 上游读 `useSessions(s => s.current)`，而**本版本会话列表快照没有 `current` 字段**（恒为 `undefined`），
+   导致点「批注」只关掉气泡、什么都不发生。→ 改为由**会话作用域槽位**（`conversation.input.dock` 探针）回填 `sessionId`，
+   并去掉"必须先解析到会话才开编辑框"的门槛（解析失败也照常进入编辑，插入时再解析）。
+
+6. **引用块带轮次/角色** —— 上游只发原文。→ 首行加 `【引用 · 第N轮 · 角色】`（轮次取自 `data-chat-turn`，角色取自 `data-chat-flow-kind`）。
+
+7. **输入框上方的引用块 + 锚点持久化** —— 本版本输入框 chip **没有 `data-*` 属性**（只有 CSS 类），上游"点 chip 跳转"不可能成立。
+   → 改为读官方输入状态 `occurrences`（`source === 'quote-ref'`）渲染引用块，只显示**原文片段**（不显示标签/轮次，保持简洁）；
+   `ref → 锚点` 落 `localStorage`，刷新后仍可跳。（输入框 chip 本体也支持点击跳转：按 `title` = label 反查 ref，不依赖 CSS 类顺序。）
+
 ## 开发
 
 ```
@@ -112,6 +145,7 @@ tools/check-manifest.mjs  清单一致性自检（CI 同款）
 
 ```sh
 npm run check    # 校验 package.json / patch / bundle 注册 id 是否一致
+npm test         # 客户端纯函数自检（编号 / 位置行解析 / 输入框摘要，无需浏览器与网络）
 npm run diag     # 起诊断接收端（默认 http://127.0.0.1:47821）
 ```
 

package/lib/client.js

@@ -83,10 +83,72 @@ window.__ModuleLoader__.load({
       if (role !== '') parts.push(role)
       return parts.join(' · ')
     }
-    /** 引用块首行：模型据此确定"哪一轮、谁说的"，多轮对话里不再靠猜。 */
-    function buildQuoteHeader(item) {
+    /** 引用块首行：模型据此确定"这是第几处批注、哪一轮、谁说的"，多轮对话里不再靠猜。 */
+    function buildQuoteHeader(item, no) {
       const label = anchorLabelOf(item)
-      return label === '' ? '' : '【引用 · ' + label + '】'
+      const numbered = typeof no === 'number' && Number.isFinite(no) && no > 0
+      const parts = [numbered ? '批注 ' + no : '引用']
+      if (label !== '') parts.push(label)
+      // 老格式（无编号且无位置信息）保持空串，避免出现只有「【引用】」的块
+      if (parts.length === 1 && parts[0] === '引用') return ''
+      return '【' + parts.join(' · ') + '】'
+    }
+    /** 批注编号：同一条消息内从 1 开始；删掉中间某条不会重号（取现有最大号 + 1）。 */
+    function nextAnnotationNo(draft) {
+      let max = 0
+      try {
+        const text = String(draft || '')
+        const re = /【批注\s*(\d+)/g
+        let m
+        while ((m = re.exec(text)) !== null) {
+          const n = Number(m[1])
+          if (Number.isFinite(n) && n > max) max = n
+        }
+      } catch (e) { /* ignore */ }
+      return max + 1
+    }
+    /** 位置行（兼容旧格式「【引用 · …】」与新格式「【批注 N · …】」；中间分隔符可能是 " · "） */
+    const QUOTE_HEADER_RE = /【(?:引用|批注)[^\n】]*】/
+    /** 从位置行里取批注编号（旧格式「【引用 · …】」没有编号，返回 null） */
+    function annotationNoOf(headerText) {
+      const m = /^【批注\s*(\d+)/.exec(String(headerText || ''))
+      if (!m) return null
+      const n = Number(m[1])
+      return Number.isFinite(n) && n > 0 ? n : null
+    }
+    /**
+     * 把「位置行 + 原文（空行）批注：…」拆成结构化块 —— 纯函数，单测与渲染共用：
+     *   { before, header, no, quote, comment, rest }
+     * 解析不了（没有位置行/没有原文）返回 null。
+     */
+    function parseQuoteBlock(raw) {
+      const text = String(raw || '')
+      const m = QUOTE_HEADER_RE.exec(text)
+      if (!m) return null
+      const after = text.slice(m.index + m[0].length)
+      const nl = after.indexOf('\n')
+      if (nl < 0) return null
+      const lines = after.slice(nl + 1).split('\n')
+      // 引用正文 = 位置行之后、直到空行之前的连续非空行（兼容旧格式的 "> " 前缀）
+      const quote = []
+      let i = 0
+      for (; i < lines.length; i++) {
+        if (lines[i].trim() === '') break
+        quote.push(lines[i].replace(/^>\s?/, ''))
+      }
+      if (quote.length === 0) return null
+      const rest = lines.slice(i).join('\n')
+      let comment = ''
+      const cm = /(?:^|\n)\s*批注[:：]\s*([^\n]*)/.exec(rest)
+      if (cm) comment = cm[1].trim()
+      return {
+        before: text.slice(0, m.index),
+        header: m[0],
+        no: annotationNoOf(m[0]),
+        quote: quote.join(' '),
+        comment,
+        rest,
+      }
     }
 
     // ============ 锚点持久化：刷新后 chip 仍能跳回原文 ============
@@ -441,7 +503,7 @@ window.__ModuleLoader__.load({
       if (!anchorKey && info.body) {
         const probe = String(info.body)
           .split('\n')
-          .map((line) => line.replace(/^【引用[^\n]*】\s*/, '').replace(/^> ?/, ''))
+          .map((line) => line.replace(/^【(?:引用|批注)[^\n]*】\s*/, '').replace(/^> ?/, ''))
           .join('\n')
           .trim()
           .slice(0, 24)
@@ -467,9 +529,13 @@ window.__ModuleLoader__.load({
     function refByLabel(label) {
       if (typeof label !== 'string' || label === '') return null
       const wanted = label.trim()
+      // 同名的 chip label 可能出现多次（每条消息的编号都从 1 开始）——
+      // refTargets 按插入顺序排列，取最后一个命中项（最近插入的那条）
+      let found = null
       for (const [ref, info] of refTargets) {
-        if (info && typeof info.label === 'string' && info.label.trim() === wanted) return ref
+        if (info && typeof info.label === 'string' && info.label.trim() === wanted) found = ref
       }
+      if (found !== null) return found
       // 退化：只按 `引用#N` 前缀匹配（label 可能被截断显示）
       const short = wanted.split('·')[0].trim()
       if (short.startsWith('引用#')) {
@@ -799,9 +865,6 @@ window.__ModuleLoader__.load({
         if (!open || !item) return
         try {
           const c = (comment || '').trim()
-          const header = buildQuoteHeader(item)
-          // 引用正文不再加 "> " 前缀：输入框与消息里都由插件渲染成紧凑块（前缀会在编辑器里露出一截符号）
-          const quoteBody = header === '' ? item.text : header + '\n' + item.text
           const conversation = rootCtx ? rootCtx.get('conversation') : undefined
           const sessions = rootCtx ? rootCtx.get('sessions') : undefined
           if (!conversation || !conversation.input || !sessions) {
@@ -822,11 +885,21 @@ window.__ModuleLoader__.load({
           }
           const input = conversation.input.for(binding.ctx)
           const st = input.state.getSnapshot()
+          // 编号：同一条消息内从 1 开始（删掉中间某条也不会重号）
+          const no = nextAnnotationNo(st.draft)
+          let header = buildQuoteHeader(item, no)
+          // 首条批注的头部内嵌"回复格式"指令：头部在界面上被隐藏，但模型看得到
+          if (no === 1 && header !== '') {
+            header = header.replace(/】$/, '（请按「Annotation 1：」「Annotation 2：」…格式逐条回应我的批注）】')
+          }
+          // 引用正文不加 "> " 前缀（前缀会在编辑器里露出一截符号）；
+          // 评语写进正文（空行 + 「批注：」前缀）：发送后整条消息自带"原文 + 评语"，回复侧才能对上号
+          const commentLine = c === '' ? '' : '\n\n批注：' + c
+          const quoteBody = header === '' ? item.text + commentLine : header + '\n' + item.text + commentLine
           const base = (st.draft || '').replace(/[\s\u00A0]+$/, '')
-          const commentTail = c === '' ? '' : '\n\n' + c
           const ref = 'q' + REF_RUN + (++refSeq)
-          // 输入框里的 chip 文案只要短、可区分即可（轮次/角色写在发送后的引用块里，不在输入框展示）
-          const chipLabel = '引用' + refSeq
+          // 输入框里的 chip 文案只要短、可区分即可（轮次/角色/评语写在发送后的引用块里，不在输入框展示）
+          const chipLabel = '批注' + no
           // 输入框与消息里显示的就是这段文本（实测：宿主消息 = 草稿文本，WYSIWYG）；
           // 因此位置行（【引用 · 第N轮 · 角色】）保留在文本里给模型用，界面上由插件渲染时隐藏。
           refTargets.set(ref, { sessionId, anchorKey: item.anchorKey || null, body: quoteBody, label: chipLabel })
@@ -853,11 +926,6 @@ window.__ModuleLoader__.load({
             clipboardText: quoteBody,
           })
           if (applied) {
-            // 把评论追加到 chip 之后
-            if (commentTail !== '') {
-              const st3 = input.state.getSnapshot()
-              input.setDraft(st3.draft.replace(/[ \t]+$/, '') + commentTail)
-            }
             try {
               const snap2 = input.state.getSnapshot()
               const occ2 = (snap2 && snap2.occurrences) || []
@@ -881,7 +949,7 @@ window.__ModuleLoader__.load({
           // 未生效：回退纯文本（内容不丢）
           refTargets.delete(ref)
           refCodecs.delete(ref)
-          input.setDraft(base === '' ? quoteBody + commentTail : base + '\n\n' + quoteBody + commentTail)
+          input.setDraft(base === '' ? quoteBody : base + '\n\n' + quoteBody)
           report('insert:fallback-plaintext', { ref, header })
           setStatus({ ok: false, text: 'chip 插入未生效，已回退为纯文本引用' })
           editorStore.close()
@@ -957,7 +1025,7 @@ window.__ModuleLoader__.load({
     const snippetOf = (body) => {
       const raw = String(body || '')
         .split('\n')
-        .filter((line) => line.trim() !== '' && !/^【引用/.test(line.trim()))
+        .filter((line) => line.trim() !== '' && !/^【(?:引用|批注)/.test(line.trim()) && !/^批注[:：]/.test(line.trim()))
         .map((line) => line.replace(/^>\s?/, ''))
         .join(' ')
         .replace(/\s+/g, ' ')
@@ -1081,6 +1149,9 @@ window.__ModuleLoader__.load({
 .dshq-cmp-quote{background:rgba(127,127,127,.10);border-radius:8px;padding:2px 10px;margin:2px 0}
 .dshq-cmp-quote-first{margin-top:4px}
 .dshq-cmp-quote-last{margin-bottom:4px}
+/* 回复里的「Annotation N」芯片：悬浮看原文+评语，点击跳回原文 */
+.dshq-anno-chip{display:inline-flex;align-items:center;margin:0 2px;padding:0 7px;border-radius:999px;background:rgba(127,127,127,.12);border:1px solid var(--dsw-alias-border-l1);color:var(--dsw-alias-label-secondary);font-size:11px;line-height:18px;cursor:pointer;vertical-align:baseline;user-select:none;white-space:nowrap}
+.dshq-anno-chip:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-brand-primary)}
 `
 
     // ============ 插件主体 ============
@@ -1322,7 +1393,6 @@ window.__ModuleLoader__.load({
         ctx.effect(() => {
           let timer = null
           let observer = null
-          const HEADER_RE = /【引用\s*·[^\n】]*】/
           const jumpByText = (text, pos) => {
             const probe = String(text || '').replace(/\s+/g, ' ').trim().slice(0, 24)
             if (probe === '') return
@@ -1368,37 +1438,128 @@ window.__ModuleLoader__.load({
             } catch (e) { /* ignore */ }
             return false
           }
-          /** 把承载「【引用…】\n原文…」的文本节点拆成：隐藏头部 + 紧凑引用块 + 其余文本 */
+          /** 把承载「位置行 + 原文（+ 批注：…）」的文本节点拆成：隐藏头部 + 紧凑引用块 + 其余文本 */
           const transformTextNode = (node) => {
             const raw = node.nodeValue || ''
-            const m = HEADER_RE.exec(raw)
-            if (!m) return false
-            const after = raw.slice(m.index + m[0].length)
-            const nl = after.indexOf('\n')
-            if (nl < 0) return false
-            const lines = after.slice(nl + 1).split('\n')
-            // 引用正文 = 头部之后、直到空行之前的连续非空行（兼容旧格式的 "> " 前缀）
-            const quote = []
-            let i = 0
-            for (; i < lines.length; i++) {
-              if (lines[i].trim() === '') break
-              quote.push(lines[i].replace(/^>\s?/, ''))
-            }
-            if (quote.length === 0) return false
-            const rest = lines.slice(i).join('\n')
+            const parsed = parseQuoteBlock(raw)
+            if (!parsed) return false
             const frag = document.createDocumentFragment()
-            const before = raw.slice(0, m.index)
-            if (before !== '') frag.appendChild(document.createTextNode(before))
+            if (parsed.before !== '') frag.appendChild(document.createTextNode(parsed.before))
             const hidden = document.createElement('span')
             hidden.className = 'dshq-sent-header'
-            hidden.textContent = m[0]          // 位置信息仍留在 DOM（只是不显示）
+            hidden.textContent = parsed.header   // 位置信息仍留在 DOM（只是不显示）
             frag.appendChild(hidden)
-            frag.appendChild(buildBlock(quote.join(' ')))
-            if (rest.trim() !== '') frag.appendChild(document.createTextNode(rest))
+            const block = buildBlock(parsed.quote)
+            // 回复侧「Annotation N」芯片靠这几项 dataset 对上号
+            if (parsed.no !== null) block.setAttribute('data-dshq-no', String(parsed.no))
+            block.setAttribute('data-dshq-quote', parsed.quote)
+            if (parsed.comment !== '') block.setAttribute('data-dshq-comment', parsed.comment)
+            frag.appendChild(block)
+            if (parsed.rest.trim() !== '') frag.appendChild(document.createTextNode(parsed.rest))
             node.parentNode.replaceChild(frag, node)
-            report('sent:decorated', { chars: quote.join(' ').length })
+            report('sent:decorated', { chars: parsed.quote.length, no: parsed.no })
             return true
           }
+          // ---- 回复侧「Annotation N：」→ 批注芯片（悬浮显示原文+评语，点击跳回原文） ----
+          const ANNO_TOKEN_RE = /Annotation\s*(\d+)\s*[:：]/g
+          /** 取"离这条回复最近的那条用户消息"里的批注数据（编号 → 原文/评语） */
+          const annotationMapBefore = (row) => {
+            const map = new Map()
+            try {
+              const all = document.querySelectorAll('[data-chat-flow-kind]')
+              const idx = Array.prototype.indexOf.call(all, row)
+              for (let i = idx - 1; i >= 0; i--) {
+                const r = all[i]
+                if (r.getAttribute('data-chat-flow-kind') !== 'user') continue
+                const blocks = r.querySelectorAll('.dshq-sent-quote[data-dshq-no]')
+                for (const b of blocks) {
+                  const no = Number(b.getAttribute('data-dshq-no'))
+                  if (!Number.isFinite(no)) continue
+                  map.set(no, {
+                    quote: b.getAttribute('data-dshq-quote') || '',
+                    comment: b.getAttribute('data-dshq-comment') || '',
+                  })
+                }
+                break
+              }
+            } catch (e) { /* ignore */ }
+            return map
+          }
+          const buildAnnoChip = (no, ann) => {
+            const chip = document.createElement('span')
+            chip.className = 'dshq-anno-chip'
+            chip.setAttribute('role', 'button')
+            chip.setAttribute('tabindex', '0')
+            chip.textContent = '批注 ' + no
+            chip.title = ann.comment !== '' ? '批注 ' + no + '：' + ann.comment : '批注 ' + no
+            chip.addEventListener('click', (ev) => {
+              const r = chip.getBoundingClientRect()
+              jumpByText(ann.quote, { left: r.left + 16, top: r.top })
+              if (ev && ev.stopPropagation) ev.stopPropagation()
+            })
+            chip.addEventListener('mouseenter', () => {
+              const r = chip.getBoundingClientRect()
+              const text = '原文：' + ann.quote + (ann.comment !== '' ? '\n\n批注：' + ann.comment : '')
+              tooltipStore.show({ text, label: '批注 ' + no, rect: { left: r.left, top: r.top, right: r.right, bottom: r.bottom } })
+            })
+            chip.addEventListener('mouseleave', () => { tooltipStore.hide() })
+            return chip
+          }
+          /** 把一个文本节点里的「Annotation N：」替换成芯片（同一节点可能有多处） */
+          const transformReplyNode = (node, map) => {
+            const raw = node.nodeValue || ''
+            if (raw.indexOf('Annotation') < 0) return false
+            ANNO_TOKEN_RE.lastIndex = 0
+            const parts = []
+            let last = 0
+            let m
+            let any = false
+            while ((m = ANNO_TOKEN_RE.exec(raw)) !== null) {
+              const no = Number(m[1])
+              const ann = map.get(no)
+              if (!ann || ann.quote === '') continue
+              parts.push(raw.slice(last, m.index))
+              parts.push(buildAnnoChip(no, ann))
+              last = m.index + m[0].length
+              any = true
+            }
+            if (!any) return false
+            parts.push(raw.slice(last))
+            const frag = document.createDocumentFragment()
+            for (const p of parts) {
+              if (typeof p === 'string') { if (p !== '') frag.appendChild(document.createTextNode(p)) }
+              else frag.appendChild(p)
+            }
+            node.parentNode.replaceChild(frag, node)
+            return true
+          }
+          const decorateReplies = () => {
+            try {
+              for (const row of document.querySelectorAll('[data-chat-flow-kind="assistant-step"], [data-chat-flow-kind="assistant"]')) {
+                if (row.dataset && row.dataset.dshqAnnoDone === '1') continue
+                // 流式输出中不动 DOM（还没定稿）
+                if (row.hasAttribute('data-streaming') || row.querySelector('[data-streaming]')) continue
+                if (selectionTouches(row)) continue
+                const map = annotationMapBefore(row)
+                if (map.size === 0) { if (row.dataset) row.dataset.dshqAnnoDone = '1'; continue }
+                let walker
+                try { walker = document.createTreeWalker(row, NodeFilter.SHOW_TEXT, null) } catch (e) { continue }
+                const targets = []
+                let n = walker.nextNode()
+                while (n) {
+                  const parent = n.parentElement
+                  const managed = parent && typeof parent.closest === 'function'
+                    ? parent.closest('.dshq-anno-chip') : null
+                  if (!managed && (n.nodeValue || '').indexOf('Annotation') >= 0) targets.push(n)
+                  n = walker.nextNode()
+                }
+                let done = false
+                for (const t of targets) { try { if (transformReplyNode(t, map)) done = true } catch (e) { /* ignore */ } }
+                if (row.dataset) row.dataset.dshqAnnoDone = '1'
+                if (done) report('reply:chips', { row: String(row.getAttribute('data-chat-anchor-key') || '').slice(0, 12) })
+              }
+            } catch (e) { report('reply:scan-throw', String((e && e.message) || e)) }
+          }
           const scan = () => {
             timer = null
             try {              for (const row of document.querySelectorAll(USER_ROW_SEL)) {
@@ -1416,7 +1577,7 @@ window.__ModuleLoader__.load({
                   // 已经装饰过的部分（隐藏的位置行 / 紧凑引用块）不再重复处理
                   const managed = parent && typeof parent.closest === 'function'
                     ? parent.closest('.dshq-sent-header, .dshq-sent-quote') : null
-                  if (!managed && HEADER_RE.test(n.nodeValue || '')) targets.push(n)
+                  if (!managed && QUOTE_HEADER_RE.test(n.nodeValue || '')) targets.push(n)
                   n = walker.nextNode()
                 }
                 if (targets.length === 0) continue
@@ -1424,6 +1585,7 @@ window.__ModuleLoader__.load({
                 for (const t of targets) { try { if (transformTextNode(t)) done = true } catch (e) { /* ignore */ } }
                 if (done && row.dataset) row.dataset.dshqSent = '1'
               }
+              decorateReplies()
             } catch (e) { report('sent:scan-throw', String((e && e.message) || e)) }
           }
           const schedule = () => { if (timer === null) timer = setTimeout(scan, 300) }
@@ -1448,7 +1610,7 @@ window.__ModuleLoader__.load({
                 const parent = n.parentElement
                 const managed = parent && typeof parent.closest === 'function'
                   ? parent.closest('.dshq-sent-header, .dshq-sent-quote') : null
-                if (!managed && HEADER_RE.test(n.nodeValue || '')) return true
+                if (!managed && QUOTE_HEADER_RE.test(n.nodeValue || '')) return true
                 n = walker.nextNode()
               }
               return false
@@ -1531,7 +1693,7 @@ window.__ModuleLoader__.load({
                   const t = String(el.textContent || '').trim()
                   if (!headerEl) {
                     // 位置行必须"整行且只有一行"，避免误把整个编辑器当成头部
-                    if (isSingleLine(t) && /^【引用\s*·[^\n]*】$/.test(t)) headerEl = el
+                    if (isSingleLine(t) && /^【(?:引用|批注)[^\n]*】$/.test(t)) headerEl = el
                     continue
                   }
                   if (t === '') break
@@ -1539,9 +1701,9 @@ window.__ModuleLoader__.load({
                   quoteEls.push(el)
                 }
                 if (!headerEl) {
-                  // 诊断：编辑器里出现了"【引用"但没能匹配成"位置行 + 正文行"时，把结构打出来
+                  // 诊断：编辑器里出现了"【引用/【批注"但没能匹配成"位置行 + 正文行"时，把结构打出来
                   const raw = String(ed.textContent || '')
-                  if (raw.indexOf('【引用') >= 0) {
+                  if (raw.indexOf('【引用') >= 0 || raw.indexOf('【批注') >= 0) {
                     const sig = raw.slice(0, 40) + '|' + kids.length
                     if (sig !== lastSig) {
                       lastSig = sig
@@ -1632,6 +1794,8 @@ window.__ModuleLoader__.load({
     exports.name = 'dsh-quote-annotate-pro'
     exports.inject = ['slots']
     exports.apply = apply
+    // 纯函数自检出口：tools/test-client.mjs 在 Node 里直接断言（宿主只读取 name/inject/apply）
+    exports.__test = { roleText, anchorLabelOf, buildQuoteHeader, nextAnnotationNo, annotationNoOf, parseQuoteBlock, snippetOf }
     return module.exports
   },
 })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-quote-annotate-pro",
-  "version": "0.2.11",
-  "description": "划词批注与引用锚点：划词 → 批注 → 引用；输入框与消息里只显示紧凑的原文引用块（轮次/角色行隐藏），点一下跳回原文并高亮；发给模型的引用块仍标明轮次与角色，多轮对话不再猜。纯客户端，不访问外部服务。",
+  "version": "0.3.0",
+  "description": "划词批注与引用锚点：划词 → 批注（自动编号）→ 引用；引用块在输入框和已发送消息里始终可见（最多 3 行、位置行隐藏），点一下跳回原文并高亮；模型按「Annotation N：」逐条回应，回复里的标签可悬浮看原文与评语。纯客户端，锚点存本地 localStorage。",
   "keywords": ["dsh", "dsh-plugin", "deepseek-harness", "quote", "annotate", "selection", "reference", "anchor"],
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
   },
   "scripts": {
     "check": "node tools/check-manifest.mjs",
+    "test": "node tools/test-client.mjs",
     "diag": "node tools/diag-sink.mjs"
   },
   "publishConfig": {

package/tools/test-client.mjs

@@ -0,0 +1,123 @@
+// 客户端 bundle 的纯函数自检（不依赖浏览器 DOM / 网络）
+// 运行：npm test   （node tools/test-client.mjs）
+//
+// 做法：给 client.js 提供最小化的 window/document/localStorage/fetch 桩，
+// 捕获 window.__ModuleLoader__.load(...) 注册的工厂，再调用工厂拿到 exports，
+// 然后断言 exports.__test 里的纯函数。这些函数是消息解析与编号的核心，回归风险最高。
+import { readFileSync } from 'node:fs'
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+const SOURCE = readFileSync(new URL('../lib/client.js', import.meta.url), 'utf8')
+
+let captured = null
+globalThis.window = {
+  __ModuleLoader__: { load: (spec) => { captured = spec } },
+  getSelection: () => null,
+  addEventListener() {},
+  removeEventListener() {},
+  innerWidth: 1280,
+  innerHeight: 800,
+}
+const fakeElement = () => ({
+  style: {},
+  className: '',
+  textContent: '',
+  dataset: {},
+  classList: { add() {}, remove() {}, toggle() {} },
+  setAttribute() {},
+  getAttribute() { return null },
+  appendChild() {},
+  addEventListener() {},
+  getBoundingClientRect() { return { left: 0, top: 0, right: 0, bottom: 0, width: 0, height: 0 } },
+})
+globalThis.document = {
+  createElement: fakeElement,
+  createDocumentFragment: () => ({ appendChild() {} }),
+  createTextNode: (t) => ({ nodeValue: t }),
+  createTreeWalker: () => ({ nextNode: () => null }),
+  head: { appendChild() {} },
+  body: { appendChild() {} },
+  querySelectorAll: () => [],
+  addEventListener() {},
+  removeEventListener() {},
+}
+globalThis.localStorage = { getItem: () => null, setItem() {}, removeItem() {} }
+globalThis.fetch = () => Promise.reject(new Error('offline (test)'))
+globalThis.requestAnimationFrame = () => 0
+globalThis.cancelAnimationFrame = () => {}
+globalThis.MutationObserver = class { observe() {} disconnect() {} }
+globalThis.NodeFilter = { SHOW_TEXT: 4 }
+
+// 以 data: URL 作为 ESM 加载 —— 源文件是"注册工厂"的脚本，不导出任何东西
+await import('data:text/javascript;charset=utf-8,' + encodeURIComponent(SOURCE))
+
+assert.ok(captured, 'client.js 应调用 window.__ModuleLoader__.load(...)')
+assert.equal(captured.id, 'dsh-quote-annotate-pro')
+const api = captured.factory((name) => (name === 'react' ? {} : {}))
+const { buildQuoteHeader, nextAnnotationNo, annotationNoOf, parseQuoteBlock, snippetOf, anchorLabelOf, roleText } = api.__test
+
+test('roleText / anchorLabelOf：轮次与角色文案', () => {
+  assert.equal(roleText('assistant-step'), 'DSH 回复')
+  assert.equal(roleText('user'), '你的消息')
+  assert.equal(roleText(null, 'tool-call'), '工具调用')
+  assert.equal(anchorLabelOf({ turn: 0, role: 'user' }), '第1轮 · 你的消息')
+  assert.equal(anchorLabelOf({ turn: 4, kind: 'assistant-step' }), '第5轮 · DSH 回复')
+  assert.equal(anchorLabelOf({}), '')
+})
+
+test('buildQuoteHeader：带编号 / 旧格式 / 空', () => {
+  assert.equal(buildQuoteHeader({ turn: 4, role: 'assistant-step' }, 2), '【批注 2 · 第5轮 · DSH 回复】')
+  assert.equal(buildQuoteHeader({ turn: 0, role: 'user' }), '【引用 · 第1轮 · 你的消息】')
+  assert.equal(buildQuoteHeader({}, undefined), '')
+})
+
+test('nextAnnotationNo：草稿内编号（空 → 1，取最大 + 1）', () => {
+  assert.equal(nextAnnotationNo(''), 1)
+  assert.equal(nextAnnotationNo('你好'), 1)
+  assert.equal(nextAnnotationNo('【批注 1 · 第3轮 · DSH 回复】\n原文'), 2)
+  assert.equal(nextAnnotationNo('【批注 1 · 第1轮 · 你的消息】\nA\n\n批注：x\n\n【批注 3 · 第2轮 · DSH 回复】\nB'), 4)
+  assert.equal(nextAnnotationNo('旧格式【引用 · 第1轮 · 你的消息】\n原文'), 1)
+})
+
+test('annotationNoOf：从位置行取编号（旧格式 → null）', () => {
+  assert.equal(annotationNoOf('【批注 7 · 第3轮 · DSH 回复】'), 7)
+  assert.equal(annotationNoOf('【批注 1 · 第1轮 · 你的消息（请按「Annotation 1：」格式回应）】'), 1)
+  assert.equal(annotationNoOf('【引用 · 第1轮 · 你的消息】'), null)
+  assert.equal(annotationNoOf(''), null)
+})
+
+test('parseQuoteBlock：新格式（原文 + 批注）', () => {
+  const raw = '【批注 2 · 第5轮 · DSH 回复】\n选中的原文片段\n\n批注：这条不太对'
+  const r = parseQuoteBlock(raw)
+  assert.ok(r)
+  assert.equal(r.no, 2)
+  assert.equal(r.header, '【批注 2 · 第5轮 · DSH 回复】')
+  assert.equal(r.quote, '选中的原文片段')
+  assert.equal(r.comment, '这条不太对')
+  assert.equal(r.before, '')
+  assert.match(r.rest, /批注：这条不太对/)
+})
+
+test('parseQuoteBlock：多行原文 / 前置文本 / 旧格式', () => {
+  const raw = '开头的一句话【引用 · 第2轮 · 你的消息】\n第一行\n第二行\n\n批注：补充说明\n结尾'
+  const r = parseQuoteBlock(raw)
+  assert.ok(r)
+  assert.equal(r.no, null)
+  assert.equal(r.before, '开头的一句话')
+  assert.equal(r.quote, '第一行 第二行')
+  assert.equal(r.comment, '补充说明')
+  assert.match(r.rest, /结尾/)
+})
+
+test('parseQuoteBlock：解析不了时返回 null', () => {
+  assert.equal(parseQuoteBlock('没有位置行的一段文字\n原文'), null)
+  assert.equal(parseQuoteBlock('【批注 1 · 第1轮 · 你的消息】'), null)
+  assert.equal(parseQuoteBlock(''), null)
+})
+
+test('snippetOf：输入框引用条只显示原文（不显示位置行/批注）', () => {
+  assert.equal(snippetOf('【批注 1 · 第1轮 · 你的消息】\n选中的原文\n\n批注：这条不对'), '选中的原文')
+  assert.equal(snippetOf('【引用 · 第2轮 · DSH 回复】\n> 旧格式原文'), '旧格式原文')
+  assert.equal(snippetOf(''), '')
+})