dsh-term-glossary

dsh plugin --profile web add dsh-term-glossary

dsh-term-glossary（术语速查）




在 DSH 对话中选中一个术语，点击选区旁的「搜索」按钮，就地查看该术语的解释：基本含义、用途、常见用法，并附带本次回答的 token 用量。解释通过旁路模型调用完成，不占用当前会话的轮次与上下文。

版本

仓库根目录即插件包（package.json 位于根目录）。包已发布至 npm：dsh-term-glossary，并已收录进 DSH 插件市场（精选列表条目、dsh.so 制品页），也可作为 git 依赖或预构建包安装。

版本 · 标签 · 分支 · 主要变化

0.1.0 · v0.1.0 · main · 首个版本：选中术语后就地显示解释。Host 半边为单体实现，仅以「选中的术语 + 所在句子」作为上下文，提示词面向计算机领域读者。

0.2.0 · v0.2.0 · v2 · 增加会话线索领域适配；输出上限提高至 2400 token 并新增 truncated 标记；index.js 改为按内容哈希装载 lib/impl.js，Host 侧改动无需重启 dsh 即可生效。

0.3.0 · v0.3.0 · v3 · 交互重做：选中文本后先显示「搜索」按钮，由读者决定何时发起请求；解释框常驻至主动关闭，等待期间显示进度，返回后显示 token 用量与模型；移除框内追问输入。

0.3.1 · v0.3.1 · v3 · 模型路由自适应：按会话当前路由、profile 默认模型依次尝试，传输层失败时自动换用下一条路由重试一次；错误信息本地化并列出已尝试的路由。

0.3.2 · v0.3.2 · v3 · 文档版本：README 同步插件市场收录信息与三种安装方式。代码与 0.3.1 完全一致。

0.3.3 · v0.3.3 · v3 · 安全加固：读者关闭解释框即中止模型调用（不再空跑到 60 秒超时）；已产生文本的失败不再换路由重试（避免同一次点击重复计费）；错误信息脱敏（去掉 URL、截断长度，完整错误只写宿主日志）。

0.3.4 · v0.3.4 · v3 · 继续加固：查询限流（同时 2 个、每分钟 20 次，超限 429）；会话线索只读取仍挂载的会话；客户端先截取选区附近的文本再处理，长对话不再整段跑正则；README 补安全边界与部署提醒。

0.3.5 · v0.3.5 · v3 · 解释框可拖动：按住标题栏移到任意位置（自动限制在视口内），双击标题栏复位；关闭按钮与框内选区不受影响。解决小窗遮挡正文的问题。

0.3.6 · v0.3.6 · v3 · 答案缓存：相同术语 + 相同句子 + 同一会话的直接复用，不再重复调用模型；Host 侧 LRU（默认 30 分钟 / 50 条，可用 cacheTtlMs/cacheMax 调整，0 关闭）+ 客户端内存缓存（关掉再开瞬开）；缓存命中不占并发与每分钟额度，框底显示「缓存命中 · 本次未调用模型」。

0.3.7 · v0.3.7 · v3 · 关闭方式改为只认右上角 ×：点框外、按 Esc 都不再关闭，方便连续查多个术语；拖动后的位置在切换术语时也保留，只有点 × 才复位。

0.3.8 · v0.3.8 · v3 · 多框并存：再查一个词会新开一个解释框而不是替换原有框，多个框可同时显示、各自拖动、各自关闭（关闭只中止自己那次调用）；同一术语 + 同一句子已有框时不再重复开框；新框按打开顺序错开摆放。

0.3.9 · v0.3.9 · v3 · 并发上限从 2 提到 4：连开多个解释框时不再那么容易被限流（每分钟 20 次的额度不变）。

查看版本差异：git diff main v3。

用法

1. 在对话或任意正文区域选中一个术语，选区旁显示「搜索」按钮；此时不会发起任何请求。

2. 点击「搜索」，就地弹出解释框并显示进度。

3. 多个词可以同时看：再去正文里选下一个词、点「搜索」，会新开一个框而不是替换已有的框。多个框同时显示，各自拖动、各自关闭；同一术语 + 同一句子已经有框时不会再开一个（那一次「搜索」按钮不会出现）。

4. 回答返回后，框底列出本次消耗的 token（输入 / 缓存 / 输出 / 合计）与使用的模型。

5. 按住标题栏可以拖动解释框，把它挪到不挡正文的位置；双击标题栏回到默认位置（选区下方）。拖动后的位置会一直保留，只有点 × 关闭后才复位。

6. 关掉后又想再看同一个词：直接再选一次、点「搜索」即可 —— 相同术语 + 相同句子 + 同一会话的答案会被缓存，不再调用模型、也不再花 token，框底显示「缓存命中 · 本次未调用模型」。缓存 30 分钟内有效（可用行配置调整），页面刷新后 Host 侧缓存仍然有效。

7. 每个框只有自己的右上角 × 能关闭它：点击正文、点击框外、按 Esc 都不会关闭 —— 这样你可以一边留着已有解释，一边继续查下一个词。

被选中的术语会连同所在句子一并发送，因此「这个」「它」等指代性表述同样可用。框内不支持追问，如需继续提问请在对话中进行。

安装

前置条件：带 Web 界面的 DSH，即 Desktop 应用或 dsh web 启动的 Web 版本。插件声明了 webServer 与 llm 两个硬依赖：前者用于注册 /api/term-glossary/explain 路由，后者用于发起旁路模型调用；两者缺一时插件不会激活。

方式一：从插件市场安装（推荐，无需命令行）

打开 设置 → 插件 → 市场，搜索 dsh-term-glossary，点击安装即可；安装完成后按 Ctrl + R 刷新页面。市场条目已同时关联 npm 包与预构建包，会按可用性自动选择下载来源。

也可以在 DSH 对话中交由 Agent 完成安装，例如发送：帮我安装插件 dsh-term-glossary（等价说法：用 plugin_manager 的 install_bundle 安装 dsh-term-glossary）。

方式二：从 npm 安装

npm 提供的是预构建产物，无需本地构建授权，国内镜像已同步，安装过程不需要访问 GitHub：

dsh plugin --profile <profile 名称> add dsh-term-glossary

安装完成后按 Ctrl + R 刷新页面即可使用。

方式三：从源码安装

适用于需要修改代码，或需要使用 v2、main 等旧版本的情况。

1. 获取源码。 默认分支为 v3，直接 clone 即可：

git clone https://github.com/ashz555/dsh-term-glossary.git

2. 安装本地目录。 在 DSH 对话中让 Agent 安装该目录（仓库根即插件包）：

用 plugin_manager 的 install_bundle，安装 D:\path\to\dsh-term-glossary

等价的工具调用参数为 plugin_manager / action: install_bundle / target: <仓库根的绝对路径>。依赖安装、bundle 注册与启用均由该调用完成，无需手工修改 profile 的 package.json 或 cordis.patch.yml，也不需要在 profile 目录中执行 pnpm。

3. 确认生效。 安装结果应为 application: applied，而非 restart-required；随后刷新页面即可使用。若该 profile 此前加载过同名插件的另一份代码（例如插件目录曾变更位置），需要重启一次 dsh 才会切换到新的实现。

其他安装来源：也可将本仓库作为 git 依赖安装（github:ashz555/dsh-term-glossary#v3），或指向 Release 中的预构建包（此地址始终指向最新版本）：

dsh plugin --profile <profile 名称> add https://github.com/ashz555/dsh-term-glossary/releases/latest/download/dsh-term-glossary.tgz

网络受限时：插件市场条目同时提供 npm 包、预构建包与 git 仓库三种来源，任一可达即可安装；其中预构建包与 git 依赖都不需要访问 npm。

安装位置与移动限制

install_bundle 注册的是 link:<该目录> 依赖，profile 直接指向该源码目录而非另行复制。目录被移动或删除后插件即失效，需要重新安装。

卸载

让 Agent 调用 plugin_manager / action: remove_bundle / target: dsh-term-glossary，或在插件管理页面中禁用、移除该 bundle。

⚠️ 开发提示：本仓库的工作树同时是被 link: 的插件目录，切换分支会改变 profile 正在加载的插件（例如从 v3 切换到 main 等于把运行中的插件替换为 0.1.0 实现）。需要对比其他版本时，请使用 git worktree add ../check <branch> 在其他目录检出。

领域适配

插件不预设术语所属领域。每次请求由 Host 半边读取当前会话自身的内容作为领域线索，交由模型判断术语所属领域（计算机、医学、法律、金融、化学等），并要求使用该领域通行的说法解释。

线索来自 sessionQuery，其行为均以真实会话数据验证：

线索 · 来源 · 说明

会话标题 · sessionQuery.readTitle · 概括会话主题

读者发送的消息 · sessionQuery.filterEvents 中的 user/message 语义文档 · 取最近 6 条，每条不超过 400 字，总计不超过 1500 字

线索采集包含两条基于实测结果确定的清洗规则：

• 不采用 assistant 语义文档：真实会话中，assistant 文档会渲染整条 surface 消息，工具调用会以 write {"content": …} 这类机器载荷出现，对判断领域没有价值，只会挤占有效线索。
• 剔除 DSH 自身的运行时通知：Current runtime context. …、The approval policy changed … 等注入内容在日志中同样属于 user/message，实测占用了大量线索长度；现已被过滤，并按文本去重。

代价：每次解释的输入增加约 200–700 token，取决于读者消息长度；线索为本地读取，实测耗时 20–40 ms，不产生额外的模型调用。

接口

POST /api/term-glossary/explain
Header: x-dsh-plugin: dsh-term-glossary
Body: { term, context?, question?, sessionId?, history?: [{ role, text }] }
200 : { ok: true, data: { answer, truncated, usage, model: { provider, model } } }
错误: { ok: false, error: { code, message } }

usage 为 provider 的 token 计数（inputTokens / outputTokens / totalTokens，命中缓存时另有 cacheReadTokens），界面直接显示于框底；truncated 为真表示模型停在上限、回答不完整。

sessionId 缺失或格式不合法时，静默降级为「无背景线索」；sessionQuery 缺失或读取失败同样降级，不会导致解释失败。

question 与 history 仍由接口接受（带历史的一次调用已由自检覆盖），但 0.3.0 起的界面不再发送这两个字段：框内追问已移除，字段保留供后续多轮界面或其他调用方使用。

配置

…(truncated)