dsh-loupe

dsh plugin --profile web add dsh-loupe

<div align="center">

<img src="assets/logo.png" alt="dsh-loupe" width="140" />

dsh-loupe

轻量DSH划词（句）解释插件

简体中文 | [English](README.en.md)

选中 DSH 对话里的一个词或一句话，浮窗里把它讲明白。快速，轻量，无额外会话污染。

若需重度长上下文追问，推荐使用我的另一款插件

dsh-tree-view进行树分支询问。







</div>

---

选中一个词，将显示面板：

点「解释」，浮窗直接开问：

功能

🖱️ 划词即弹 · 选中正文里任意文字，选区下方浮出「解释 / 设置」两个入口。

🪟 浮窗回答 · 不是侧栏。单实例、可多轮追问（第二问起都带着本浮窗的前文）、流式 markdown、能拖走、位置记住。

🔌 不建会话 · 只发一次模型请求：不写会话日志、不注册工具，左侧列表不会变脏。

📚 自带上下文 · 用插件自己的 context.md，不拖 agent 的全量上下文 —— 更快也更省。

🧾 上下文只有你写的 · context.md 只注入你手写的内容；插件不把自己的答案写回去。

🗂️ 全量留档 · 每次问答都进历史，可按关键词搜索、分页翻；点一条就复原回浮窗接着问。

📌 可存成正式会话 · 值得留下的解释，选个目标工作区一存，就成了左侧列表里的真会话，并自动命名为「划词 · <词>」。

🌐 中英双语 · 界面与提示词中英双语；auto 取宿主设置里的语言偏好（locale.preference），没有则用浏览器语言，也可以手动锁定。

🧠 推理可折叠 · 模型自己的推理过程默认收起，想看再展开；从历史复原时它还在。

🌗 跟随主题 · 深浅主题与皮肤跟随宿主；宿主没提供设计令牌时按系统深浅兜底。

🔑 零配置 · 借用宿主的 llm 服务，不用填 API key。

🫧 玻璃质感 · 半透明 + 背景模糊，可在参数页关掉。

插件特点

快。 点「解释」的时候它已经在问了 —— 浮窗打开即提交，不用再按一次发送。推理档默认 off，实测三次首字 503ms / 544ms / 634ms，整段答案 1.7–2.5 秒。它也不把 agent 的全量上下文拖进来，只发你选的那句加一本小本子；小本子放在 prompt 的固定位置，还能吃到宿主的 prompt 缓存。

准。 发给模型的只有三样：你选中的文字、它所在的那条消息（默认只带这一条）、以及 context.md（上限 2200 字）。不掺主会话那几十万 token，也就没有无关内容把解释带偏。context.md 里可以写术语表和你自己的用法偏好，它只装你写的东西 —— 插件不会把自己的答案写回去（1.2.0 起如此，见「自动累积为什么被移除」）。

追问是接着说的，不是重新解释。 浮窗里的第二问起，客户端会把本浮窗已经完成的问答一起发上去（最近 6 轮），宿主组装成真正的多轮请求，并换一套「续答」框定：只答新问题、不复述、不再通篇重讲选中文字。上下文只注入你手写的内容，前几轮的答案由对话本身承载 —— 不重复注入，也就不可能被它带着复述自己。

轻。 宿主半端只 import node:fs / node:os / node:path / node:crypto，零第三方依赖；界面半端是手写的模块加载器模块，没有构建产物要同步。它不建会话、不写会话日志、不注册工具 —— 跑完只留下两个文件：context.md 和 history.jsonl。

只做一件事。 它不聊天、不总结、不改代码，就是把选中的这段解释清楚。一次问答，读完关掉；真要展开成长期讨论，点「保存」把它交回主会话。

安装

本地目录（推荐）

git clone https://github.com/Rice00/dsh-loupe.git
dsh plugin --profile <profile> add link:/abs/path/to/dsh-loupe

补丁会往 profile 里插一行（loupe）。然后重启这个 profile —— 宿主插件模块在进程内缓存，运行中的 harness 读不到新行。只改界面的话刷新浏览器就够了。

link: 是活链接，改源码立刻生效；代价是装完之后不能挪动这个目录。想连文件一起复制走用 file:，以后每次改都要重装。

从 npm 或 GitHub

dsh plugin --profile <profile> add dsh-loupe                    # npm
dsh plugin --profile <profile> add github:Rice00/dsh-loupe      # GitHub

让 AI 助手帮你装

请帮我安装 DSH 插件 dsh-loupe：

1) 装进 web profile，三种来源任选：
     从 npm：
       dsh plugin --profile web add dsh-loupe
     从 GitHub：
       dsh plugin --profile web add github:Rice00/dsh-loupe
     或从本地检出（填这个文件夹的绝对路径）：
       dsh plugin --profile web add link:<绝对路径>
2) 重启该 profile —— 宿主插件模块在进程内缓存，新行只在启动时读。
   （只改界面的话，刷新浏览器就够了。）
3) 验证：随便打开一个会话，在正文里选中一句话。
   选区下方应浮出「解释 / 设置」；点「解释」应弹出浮窗并流式作答，
   浮窗底部应有一行统计（N 字 · 首字 …ms · 共 …ms）。
4) 不灵就看设置页第四栏「诊断」：它把宿主 llm 服务、模型解析、
   context.md 可写性、拖动事件计数、工作区探测结论逐项列出来。

常见问题

会污染我的主会话吗？

不会。只发一次模型请求，不建会话、不写会话日志、不注册工具。

要填 API key 吗？

不用。走宿主已有的 llm 服务，默认跟随 agent-default-model。

它和「侧边对话」有什么不同？

侧边对话会把主会话的整个历史 fork 一份，几十万 token；这个插件只带上你选的那句话和一本小本子。

为什么默认 off 推理档？

解释单段文字用不上高推理。同一个问题实测 off 首字 544ms，low 2806ms。嫌答得浅就在参数页调 low。

关掉浮窗，内容还在吗？

在。全在 history.jsonl 里，设置页「历史」点一条就能接着问。

浮窗拖不动？

设置页「诊断」里有拖动事件计数 —— 拖一下看数字涨不涨，就知道事件有没有传到宿主。

玻璃质感没效果？

需要浏览器支持 color-mix。不支持时自动退回实底，其余功能照常。

界面能换英文吗？

能。设置页「参数」里的「界面语言」选 en，界面与提示词立刻变英文；auto 取宿主设置里的语言偏好，没有则用浏览器语言（宿主页面上的 lang 是模板固定值，不参与判断）。主题不用选，它自己跟随宿主。

自动累积为什么被移除

1.0.x 里，每解释一次就把「选区 → 答案前 160 字」追加进 context.md 的受控区块，再随每轮请求注入 system。1.2.0 起这块逻辑整体删掉了，原因有四条：

• 它是历史数据的劣质副本。 history.jsonl 已经存了完整的问答原文；累积出来的只有截断到 160 字的摘要，很多从句子中间切断，却要占 prompt 预算。
• 它把模型自己的措辞喂回去。 追问时模型读到自己上一轮的答案，就会接着复述 —— 这是「追问重复上一答」的主要来源之一。
• 它挤掉了用户自己写的东西。 实测一份长期使用的 context.md：自动累积占 99.9%，60 条顶到上限，而 2200 字注入预算只装得下最新 14 条；手写术语表一条也进不去。
• 它在破坏自己的前提。 每答完就改文档，system 的稳定前缀每轮都变，宿主的 prompt 缓存无从命中。

升级不会丢东西：迁移先备份 context.md.bak-<时间戳>，再只剥带标记的那一段，手写内容原样保留。

参数

设置页「参数」里改，下一次解释就生效。

参数 · 默认 · 说明

推理档 · off · off / low / high / max。解释单段文字用不上高推理。

邻域条数 · 0 · 0 / 1 / 2 / 4。选区前后各带几条对话进 prompt。0 = 只带所在那条消息。

玻璃质感 · on · on / off。半透明 + 背景模糊；关掉是实底，拖动更跟手。

上下文上限 · 2200 · 800 / 2200 / 4000 / 8000 字符。context.md 注入的长度上限。

界面语言 · auto · auto / zh / en。auto 取宿主设置里的语言偏好（locale.preference），没有则用浏览器语言；宿主页面上的 lang 属性是模板固定值，不参与判断。只翻译界面与提示词。

数据与接口

<details>

<summary>给要改代码或接管线的人</summary>

数据落在 ~/.dsh/loupe/（有 DSH_HOME 就跟着它）：

context.md     插件上下文（只有你手写的内容）
history.jsonl  全部问答记录（只追加，不重写；超过 8MB 时只读尾部）
debug.log      选词诊断日志（每次选词一行 JSON；超过 512 KB 只留最后 200 行）

1.2.0 起不再写「自动累积」区块。升级时插件会把旧文件里的那块剥掉、原样备份成 context.md.bak-<时间戳>，迁移结果同时出现在 /probe 的 contextMigration 与设置页「上下文」页顶部。

debug.log 记的是「这一次框选，宿主实际拿到了什么」—— 排查「词明明在对话里，解释却说没出现」这类问题时用它，比 history.jsonl 更直接：

{"at":1792424435881,"kind":"assistant-step","turn":"51","node":"14:assistant-step51:3",
 "len":2093,"sent":1915,"win":[193,2093],"anchor":921,
 "selAt":[196,300,460],"winAt":[18,122,282],"head80":"…（前面省略 193 字）…"}

字段 · 含义

kind / turn / node · 取中的那一条消息的节点类型、所属轮次、节点键

len / sent · 那条消息的总字数 / 实际送进 prompt 的字数（超出 1900 时按选区开窗）

win · 窗口在原消息里的起止下标

selAt / winAt · 选区在原消息里 / 在送出的窗口里的位置；winAt 为空说明没包住

head80 · 送出窗口的前 80 字（用来一眼确认取到的是哪一段）

默认一直记录，纯本地文件。

…(truncated)