dsh-loupe

dsh-loupe

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

简体中文 | English

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

若需重度长上下文追问，推荐使用我的另一款插件 dsh-tree-view进行树分支询问。

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

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

功能

插件特点

快。 点「解释」的时候它已经在问了 —— 浮窗打开即提交，不用再按一次发送。推理档默认 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-<时间戳>，再只剥带标记的那一段，手写内容原样保留。

参数

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

数据与接口

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

{"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 字）…"}

GET  /plugins/dsh-loupe/probe     诊断：宿主能力 / 模型解析 / context 可写性 / 拖动事件 / 工作区探测
POST /plugins/dsh-loupe/explain   解释调用（SSE：meta / thinking / reasoning / first / delta / done / error）
GET  /plugins/dsh-loupe/history   历史（最新在前；?limit= &offset= &q= 搜索与分页）
GET  /plugins/dsh-loupe/context   读上下文
POST /plugins/dsh-loupe/context   写上下文（64 KB 上限）
POST /plugins/dsh-loupe/pin       保存成正式会话（客户端会话服务不可用时的兜底）
POST /plugins/dsh-loupe/debug     追加一行选词诊断日志（写进 debug.log）

lib/index.js       宿主半端 —— 路由 / prompt 组装 / 流式解析 / 落盘（只 import Node 内置模块）
lib/client.js      界面半端 —— 划词 / 浮标 / 浮窗 / 四个页签（手写模块，无构建步骤）
cordis.patch.yml   补丁
docs/              实施与修复记录，含「保存」链路的复盘

卸载

dsh plugin --profile <profile> remove dsh-loupe

~/.dsh/loupe/ 不会跟着删。想彻底清干净就手动删掉它。

后续计划

• 划词浮标（解释 / 设置）
• 浮窗：多轮追问、流式 markdown、可拖拽、位置记忆
• 独立通道：不建会话、不写会话日志
• 自带上下文（1.2.0 移除了自动累积，只注入手写内容）
• 历史留档与一键复原
• 保存成正式会话（自己选工作区）
• 玻璃质感开关
• 保存后的会话自动命名
• 历史检索与分页
• 推理过程可折叠
• 发布到 npm
• English README

参与贡献

Issue 和 PR 都欢迎。

许可证

MIT