引用溯源 yupaoa/dsh-citation

dsh-citation

划选回答里的一段 → 右键「添加到对话」→ 变成输入框里一个引用胶囊

给 DeepSeek Harness 用的第三方插件：把某一条回复里的一段原文引用进下一条消息，发送时以「第几轮、哪个字符区间、原文全文」的形式交给模型；气泡里再折叠回一只胶囊。

Select a passage in a reply, right-click Add to conversation, and it becomes an
uneditable quote chip in the composer. On send, the chip expands into a block that tells the
model which turn, which character range, and the exact text — and folds back into a chip inside the sent bubble.

官方已有同类功能：DSH 0.2.2-alpha.2 起内置「引用文本」——输出是 Markdown > 引用块，不带出处。本插件多给模型 turn / range 出处，入口相同，详见「与官方功能的关系」。

环境要求：DSH >= 0.2.1-rc.3（依赖该版本的输入框引用胶囊与气泡 userText 规则），
Node.js ^22.19.0 || >=24.0.0（随宿主）。

与官方功能的关系

DSH 0.2.2-alpha.2（2026-10-28）起，官方已内置引用能力（@deepseek-ai/dsh-message-quotes）：选中回复里的文字，点选区旁的引用文本按钮，内容进入输入框，发送后折叠预览。入口与本插件相同，但交给模型的东西不同：

| | 官方（0.2.2-alpha.2+） | 本插件 |
| 送给模型的内容 | 普通 Markdown 引用块，每行一个 > 前缀 | <citation turn step range anchor session> + <quote> |
| 出处（第几轮、哪个字符区间） | 没有——模型只知道「用户引用了一段话」 | 有，可定位到具体轮次与字符区间 |
| 输入框里的形态 | QuoteNode，文字可编辑 | 原子胶囊，不可编辑，只能整块删除 |
| 入口 | 选区旁的浮动按钮 | 右键菜单「添加到对话」 |

怎么选：只要把一段话引进来 → 用官方，可以直接卸掉本插件；想让模型知道「这段话出自第几轮、哪几个字符」→ 用本插件。

共存保护：本插件会探测宿主的 insertQuote 能力（官方引用正是走它）。一旦发现宿主已经自带引用入口，就不再注入右键菜单项，把选区右键让回浏览器原生菜单，避免出现两个「引用」。
所以在 0.2.2 之后装它不会打架，只是它会安静下来；0.2.1 及更早没有这个能力，功能照常。

下面几节描述的都是本插件自己的入口与行为。

它能做什么

- 🖱️ 右键菜单多一项：在已经生成完的回复里划选文字后右键，菜单里除了「复制」还有 添加到对话。只有一个合法的选区时才接管右键，其它情况一律放行浏览器原生菜单。
- 🧩 引用胶囊，不可编辑：点它之后输入框里出现 引用 · 第3轮 · 128字 的原子胶囊。
它不是文本，删不掉半个字——只能整块删除，也不会被你不小心改坏。
- 👀 悬停才看原文：鼠标移到胶囊上（输入框里和已发送的气泡里都算）才展开被引原文，可选中复制；移开即收起。浮层不抢焦点、不改草稿。
- 📨 发送时变成模型可读的引用块：

我引用了以下 1 条回复内容： <citation turn="3" step="0" range="128:412" anchor="a1b2c3d4" session="d4f1…"> <quote>被引用的那一段原文，逐字保留</quote> </citation>

你的问题

模型因此能分辨「这是第 3 轮回答里字符 128–412 的那一段」，而不是一段来路不明的引文。
前缀在已发送的气泡里会被折叠回胶囊，正文照常显示。
- 🛡️ 只在能引用的时候出现：跨两条回复的选区、正在流式生成的回复、按钮 / 代码块工具条 / 思考块里的选区、空白选区——一律不出自定义菜单项（理由见下表）。
- 🚫 不重复、不贪多：同一段重复引用会被挡下，一条消息最多 5 段引用——再多就是拿上下文换便利。
- ↩️ 回退对话也认得：dsh-rewind 回退时会把「当时发送的原文」塞回输入框，插件检测到其中的引用块就重建成「胶囊 + 正文」，不会留一堆机器标记。
- 🌗 跟随主题、只碰自己：菜单 / 浮层深色、跟随宿主的暗色界面；样式全部以 .dsh-citation- 命名，不动宿主任何选择器。

它刻意不做什么

| 不做 | 原因 |
| 不截断你要引用的原文（超过 20000 字才裁剪） | 裁剪会悄悄改掉引用内容；真要超限时保留头 75% + 尾 25%，并在块里写明省略了多少字，模型不会误以为引用完整 |
| 不跨消息拼接引用 | 拼出来的 turn / range 一定是错的，宁可不出菜单 |
| 不接管流式生成中的回复 | 内容还会变，引用无法复现 |
| 不提供「缩小/改写引用」 | 引用应当是原话；要摘要就让模型自己去做 |
| 不注册任何模型工具或斜杠命令 | 引用是人的动作，不该成为模型可自主调用的能力 |
| 不改草稿里你写的字 | 只插入 / 删除胶囊本身，正文一个字都不动 |

权限与边界

一句话

不读写任何文件、不发起任何网络请求、不注册工具、不读凭据；唯一会变的是你输入框里的草稿，以及你按下发送后那条消息的内容。

插件以宿主进程的同等权限运行（DSH 的第三方插件没有独立沙箱），所以这里列的是它实际用到的能力，也是你审计时该看的那几条。

会写入的东西

| 位置 | 何时 | 写什么 |
| 输入框草稿 | 点「添加到对话」时 | 通过宿主公开的 insertReference / insertText / setDraft 插入胶囊，不直接改 DOM 里的文字。草稿的持久化由宿主负责（会话草稿 本来就存在那里） |
| 会话消息 | 你按下发送时 | 胶囊展开成上方那段引用块文本；这是草稿文本的变换，不额外发请求、不额外落盘 |
| 页面 DOM（临时） | 菜单 / 浮层 / 提示条显示期间 | 挂在 <body> 下的三个自建节点，关闭即移除；对应样式也只有一个 |
| 剪贴板 | 只有你点菜单里的「复制」 | navigator.clipboard.writeText，失败退回 execCommand('copy')；从不读剪贴板、不轮询 |
| 本次进程内存 | 插件生命周期内 | 一个 文案 → 引用 的映射表（上限 50 条，供悬停反查原文）；卸载即消失 |

只读的东西

- 回复正文的 DOM：data-chat-flow-kind="assistant-step"、data-chat-turn、 data-chat-anchor-key、data-conversation-session、data-streaming——用来判断「这是第几轮的哪一段」。这些是宿主内部契约而非公开 API，见「兼容性」。
- 宿主服务：conversation.input（拿输入框 shell）、inputTriggers（注册引用源 / 展开胶囊）、 uiConversation.userText + slots（气泡里折叠渲染）、locale（中英文案）、sessions （会话 id → scope）。
- 你的选区：只在你右键的那一刻读一次 getSelection()。

一概不碰

- 文件系统：不读、不写、不列举任何文件（连自己的配置都不落盘）；
- 网络：没有出站请求，也没有入站路由——不开端口、不建服务器、不挂 webServer 路由；
- 凭据：不碰 ~/.dsh/.credentials.yaml、环境变量里的密钥、模型 provider 配置；
- 模型与提示词：不改系统提示词、不改模型选择、不注入额外的人设段；
- 会话的工具集 / 命令表 / 技能 / 插件组合：一样都不改；
- 其它插件与其它配置行：只 patch 自己那一行；
- 你的工作区文件与历史会话：除了你要发送的那条消息本身。

一处需要知情的实现细节（可审计）

为了让「回退对话」不把引用块显示成原始标记，插件包装了 conversation.input.for(scope) 返回的 shell 的 setDraft（存下原函数，卸载时逐个还原）。它只在收到含 我引用了以下 前缀的草稿时才动手，其它写入原样透传；重建失败时会退化为「剥掉机器标记、保留正文」，绝不把内容改丢。

想彻底关掉

卸载插件即可，没有任何残留：不写配置文件、不留后台进程、不改宿主设置。历史消息里的引用块会以纯文本形式显示（内容不丢）。

安装

要求：DSH >= 0.2.1-rc.3、Node.js ^22.19.0 || >=24.0.0。dsh plugin add 会把参数原样透传给
pnpm add。本插件没有发布到 npm，只有下面两种装法。

1) 直接从 GitHub 安装（推荐；client.js 已提交，无需构建）
dsh plugin add --profile desktop "github:yupaoa/dsh-citation"
若上面的 shorthand 不被接受，用等价的显式写法：
dsh plugin add --profile desktop "git+https://github.com/yupaoa/dsh-citation.git"

2) 从本地目录安装（开发 / 离线）
dsh plugin add --profile desktop "link:D:\path\to\dsh-citation"

把 --profile desktop 换成你自己的 profile 名；dsh plugin list --profile desktop 查看已装插件。

没有 dsh CLI 时手工装（三处都要改）：

1. ~/.dsh/profiles/desktop/node_modules\dsh-citation 建一个指向本目录的 Junction （cmd /c mklink /J <上面这个路径> D:\path\to\dsh-citation）；
2. profile 的 package.json：dependencies 加 "dsh-citation": "link:D:/path/to/dsh-citation"， dsh.profile.bundles 末尾加 "dsh-citation"；
3. 重启 DSH。

装完必须重启

插件在宿主启动时装配（引用源、右键菜单、气泡规则都在启动阶段注册）。
安装 / 卸载 / 升级后请完全退出并重启 DSH，只刷新页面不够。

卸载

dsh plugin remove --profile desktop dsh-citation

用

1. 在任意一条已经生成完的 AI 回复里划选一段文字；
2. 右键 → 添加到对话；
3. 输入框里出现 引用 · 第3轮 · 128字 的胶囊，正文一个字都不多；
4. 鼠标移到胶囊上 → 浮层显示被引原文（可选中复制），移开收起；
5. 正常输入、按 Enter 发送；
6. 发送后的气泡里，前缀折叠成同一个胶囊，正文照常显示。

什么时候不出菜单

| 情况 | 行为 | 原因 |
| 选区跨了两条回复 | 不出菜单 | 拼出来的引用一定错，宁可不动 |
| 回答还在流式生成 | 不出菜单 | 内容还会变，引用无法复现 |
| 选中的是按钮 / 代码块工具条 / 思考过程 | 不出菜单 | 那不是回答的正文 |
| 选中空白 | 不出菜单 | 没有内容可引 |
| 同一段已经引用过 | 提示「这一段已经引用过了」 | 避免重复占上下文 |
| 一条消息已引 5 段 | 提示上限 | 再多就是拿上下文换便利 |

兼容性

- 目标版本 DSH 0.2.1-rc.3；在 0.2.2-alpha.2（官方已内置引用）上会自动让出右键菜单，见上一节。
- 依赖宿主的内部 DOM 契约（见「只读的东西」）。这些不是公开 API，宿主大版本升级后可能失效；失效时插件会安静地不再出菜单，不会崩 UI、不会破坏原生右键菜单。
- 气泡折叠依赖 uiConversation.userText 规则与 conversation.user.text.node 槽位；缺这些服务的宿主上，插入与发送仍然工作，只是气泡里不会折叠。
- 如果宿主的编辑器不接受引用胶囊，插件退化为插入一行位置标记 引用 · 第3轮 · 字符 128–412——此时模型按位置定位，没有原文冗余。
- 刷新页面后，草稿里恢复的胶囊因为查不到「文案 → 原文」映射，悬停只显示宿主原生提示。

开发

npm test # node --test test/.test.js，无依赖、无网络（51 个用例）

client.js 是单文件客户端半身：第三方插件只能提供一个 window.__ModuleLoader__.load 工厂，多文件需要打包链，所以这里用 //#region 分区，不引入构建步骤。

测试里没有浏览器：test/fake-dom.js 是个最小假 DOM（菜单、浮层、提示条、胶囊悬停都在它上面回归）， test/harness.js 用假 window.__ModuleLoader__ 加载 client.js 并注入可记录的假 ctx。

本地试用：

dsh plugin add --profile desktop "link:D:\path\to\dsh-citation"
完全退出并重启 DSH

给贡献者的三条红线

1. window.__ModuleLoader__.load({ id }) 里的 id 必须是 dsh-citation——内核用解析出的包名作为浏览器模块身份；写错会导致该行永远注册不上。test/smoke.test.js 会盯着这一条。
2. 引用源必须提供 candidates：宿主的 @ 菜单会对每个 @ 源无条件调用
source.candidates(...).then(...)，缺了它整个 @ 提及会抛错。我们有 async () => [] 占位。
3. 协议解析靠字面量 </quote>\n</citation>：转义只处理 \ 和 <（用 \u003c）， > 与 & 保持原样——别顺手把 > 也转了，解析器会失效。

反馈与贡献

- 🐛 Bug / 功能建议：Issues
- 🔧 代码贡献：PR 前请确保 npm test 全绿
- 🔐 安全问题：见 Issues（当前无独立安全流程）

许可证

MIT © 2026 yupaoa

从回复里引用一段话——右键、加入会话、带着出处发出去。

DeepSeek Harness 的第三方插件。在已完成的助手回复里选中文字，点 Add to conversation，这段话就变成输入框里一个不可编辑的胶囊。提交时胶囊展开成一段块，带上轮次、字符范围和原文；发出去的气泡再把这段块折回同一个胶囊。

需要 DSH >= 0.2.1-rc.3 与 Node.js ^22.19.0 || >=24.0.0。仓库里已提交可直接运行的 client.js，
所以 GitHub 安装和本地安装现在就能用。本插件未发布到 npm。

DSH 现在也自带这个功能了。 从 0.2.2-alpha.2 起，宿主能把选中的内容以普通 Markdown 引用块的形式引用到输入框——但没有出处。本插件补上 turn / range 出处，入口相同；见下方与内置功能的关系。

1) straight from GitHub (recommended — no build step, the artifact is committed)
dsh plugin add --profile desktop "github:yupaoa/dsh-citation"

2) local directory (development / offline)
dsh plugin add --profile desktop "link:D:\path\to\dsh-citation"

安装、升级或移除插件后，请完全重启 DSH——只刷新页面不够。卸载用 dsh plugin remove --profile desktop dsh-citation。

与内置功能的关系

DSH 0.2.2-alpha.2（2026-10-28）自带引用功能（@deepseek-ai/dsh-message-quotes）：在回复里选中文字，点选区旁边的 Quote text 按钮，内容就会进入输入框，发送后显示为折叠预览。同一个入口，不同的载荷：

| | 内置（0.2.2-alpha.2+） | 本插件 |
| 模型收到什么 | 普通 Markdown 引用块，每行一个 > | <citation turn step range anchor session> + <quote> |
| 溯源信息（轮次、字符范围） | 无 —— 模型只知道文字被引用了 | 有，能定位到具体轮次和范围 |
| 输入框里 | 可编辑的 QuoteNode | 原子化、不可编辑的 chip |
| 入口 | 选区旁的浮动按钮 | 右键 → Add to conversation |

只需要文字，用内置的就够；想让模型知道文字来自哪一轮、哪些字符，用本插件。

共存。 插件会探测宿主是否具备 insertQuote 能力（内置引用路径用的就是它）。宿主已支持引用时，插件不再注入自己的右键菜单项，把选区的右键交给浏览器，这样你不会看到两个引用入口。在 0.2.1 及更早版本上，该能力不存在，一切按上文所述运行。

它做什么

- 右键菜单多一项。 在已完成的助手回复里选中有效内容时，菜单提供 Copy 和 Add to conversation；其他选区（跨两条回复、流式输出中、按钮、代码块工具栏、思考块、空白）一律交给浏览器原生菜单。
- 原子化、不可编辑的 chip。 Quote · turn 3 · 128 chars —— 改不了其中一半，只能整体删除。
- 悬停显示原文，输入框里和已发送气泡里都支持；原文可选中、可复制，且不会抢焦点。
- 发送时生成模型可读的块：

I quoted the following 1 passage from earlier replies:
<citation turn="3" step="0" range="128:412" anchor="a1b2c3d4" session="d4f1…"> <quote>the quoted passage, verbatim</quote> </citation>

your question

（中文界面输出 我引用了以下 1 条回复内容：。）前缀在已发送气泡里会折回成 chip。
- 不静默截断。 20000 字符以内原文照录；超出则保留头部 75% 和尾部 25%，并在块中说明丢弃了多少字符。
- 不重复，每条消息最多五条引用。
- 回退后仍可用。 dsh-rewind 会把最初提交的文本推回输入框；插件识别出该块后重建 chip 和正文，而不是显示原始标记。

权限与边界

不访问文件系统，不发网络请求（入站出站都没有），不注册工具或斜杠命令，不读取凭据。唯一会变的是你的草稿和你发送的消息。 DSH 插件以宿主进程的权限运行 —— 没有独立沙箱 —— 所以本节列出实际用到的能力，审计时该看的就是这些。

| 面 | 何时 | 内容 |
| Composer 草稿 | 你点击 Add to conversation | 通过宿主的公开 insertReference / insertText / setDraft 插入 chip；草稿持久化仍由宿主负责 |
| 会话消息 | 你按下发送 | chip 展开成上面的块 —— 一次草稿文本转换，不发额外请求，不做额外写入 |
| 页面 DOM（临时） | 菜单 / 浮层 / toast 显示期间 | <body> 下三个自建节点，关闭时移除；一个 |
| 剪贴板 | 仅当你选择 Copy | navigator.clipboard.writeText，回退到 execCommand('copy')；从不读取剪贴板 |
| 进程内存 | 插件生命周期内 | 一张 label → citation 映射（最多 50 条），用于悬停查找 |

只读面：回复 DOM（data-chat-turn、data-chat-anchor-key、data-conversation-session、data-streaming、data-chat-flow-kind="assistant-step" —— 宿主内部契约，不是公开 API）、conversation.input / inputTriggers / uiConversation.userText / slots / locale / sessions 服务，以及你的选区（右键时读取一次）。

有个实现细节值得知道：为了让回退后的草稿仍可读，插件包装了 conversation.input.for(scope) 的 setDraft（保留原函数，卸载时还原）。它只处理带 我引用了以下 前缀的草稿；重建失败就剥掉机器标记、保留正文，内容不会丢。

卸载后不留痕迹：没有配置文件，没有后台进程，不改宿主设置。旧消息里的引用保留为纯文本。

已知限制

- 依赖宿主内部 DOM 契约（目标：DSH 0.2.1-rc.3）。如果未来宿主版本改了它，插件会静默停止提供菜单 —— 绝不向 UI 抛错，也绝不破坏原生右键菜单。
- 气泡折叠需要 uiConversation.userText 规则和 conversation.user.text.node 插槽；缺了它们，插入和发送仍可用，只是气泡不折叠。
- 页面重载后，恢复的 chip 无法解析回对应引用（label 映射按会话隔离），悬停只显示宿主原生 tooltip。

开发

npm test # node --test test/*.test.js — no dependencies, no network (51 cases)

client.js 是单文件客户端半边（window.__ModuleLoader__.load 工厂、//#region 分段、不用打包器）。测试在 Node 里跑，对着最小假 DOM（test/fake-dom.js）和假 window.__ModuleLoader__（test/harness.js），所以菜单、浮层和 toast 不用浏览器也能覆盖。

MIT © 2026 yupaoa