dsh-quote-annotate-pro 0.2.11 → 0.2.12

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 本项目的所有重要变更都记在这里。版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## 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,12 +4,31 @@
 [![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 starts with `【引用 · 第N轮 · 角色】`, so it always knows which turn and whose message.
+
+> 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
 
@@ -19,10 +38,15 @@
 | 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 |
+| **Turn-accurate context** | The quote block starts with `【引用 · 第3轮 · 你的消息】` followed by the quoted text, so the model knows exactly 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 +75,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,12 +4,31 @@
 [![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 行，轮次/角色那一行被隐藏），点它跳回原文并高亮；而发给模型的文本仍然以 `【引用 · 第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`；
+2. 输入框里出现引用；**输入框上沿**同时出现一条引用块，点它可跳回原文；
+3. 发送后气泡里仍是紧凑引用块，点它随时回到原文并高亮；每轮结束处还有「引用提问 / 引用回答」，可整段引用该轮。
 
 ## 功能
 
@@ -19,41 +38,15 @@
 | 引用 chip | 输入框里出现 `引用1` 的原子 chip（短标签）；发送时展开为完整引用块 |
 | **引用块（输入框内）** | 插入引用后输入框里只显示**原文片段**（位置行隐藏）；**点一下即跳回原文并高亮** —— 不做任何可见的"跳转"提示 |
 | **对话页里的紧凑引用** | 已发送消息里的引用同样只显示**紧凑原文块**（最多 3 行）。**消息文本仍以 `【引用 · 第N轮 · 角色】` 开头** —— 界面隐藏、模型照旧知道出处 |
-| **模型侧精确定位** | 引用块首行是 `【引用 · 第5轮 · 你的消息】`，后接 `> 原文`，让模型明确知道**哪一轮、谁说的** |
+| **模型侧精确定位** | 引用块首行是 `【引用 · 第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)。
 
 ## 安装
 
@@ -90,18 +83,50 @@ emit('slash/input-insert-reference', { reference, span })      ← 官方会话
   ▼
 本插件 codec.serialize(ref) → 完整引用块
      【引用 · 第5轮 · DSH 回复】
-     > 原文……
+     原文……
      （你的评语）
   ▼
 模型收到"哪一轮 + 谁说的 + 原文"
 
-跳回原文：引用块/锚点 → [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 类顺序。）
+
 ## 开发
 
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-quote-annotate-pro",
-  "version": "0.2.11",
-  "description": "划词批注与引用锚点：划词 → 批注 → 引用；输入框与消息里只显示紧凑的原文引用块（轮次/角色行隐藏），点一下跳回原文并高亮；发给模型的引用块仍标明轮次与角色，多轮对话不再猜。纯客户端，不访问外部服务。",
+  "version": "0.2.12",
+  "description": "划词批注与引用锚点：划词 → 批注 → 引用；引用块在输入框和已发送消息里始终可见（最多 3 行、位置行隐藏），点一下跳回原文并高亮；发给模型的文本仍标明轮次与角色。纯客户端，锚点存本地 localStorage。",
   "keywords": ["dsh", "dsh-plugin", "deepseek-harness", "quote", "annotate", "selection", "reference", "anchor"],
   "license": "MIT",
   "type": "module",