Word-Hover-dsh

dsh-plugin-word-hover · 英文悬停词典

在 DeepSeek Harness 里读 AI 英文回复时，鼠标悬停任意英文单词 → 单词出现「被选中」高亮 → 自动弹出音标、词性、中文释义、英文释义、双语例句。

• 目标应用：DSH Desktop 0.2.0-rc.2（Web GUI / Electron）
• 形态：一个 bundle 包（宿主端插件 + Web 客户端插件）
• 无需 API Key，无需额外端口，不发送任何对话内容
• 许可证：MIT（代码）· 第三方数据来源

⚠️ 合规提示（请先读）

默认主源是有道词典的公开网页接口（非官方 API），插件按你的悬停行为逐词请求。 仅供个人学习使用，请勿用于商业用途或批量抓取。 需要商用请把 provider 改为 custom 并指向你自有的合规后端。 数据版权归各词典提供方所有，本项目与有道、DeepSeek 等主体无隶属关系。

---

一、功能

发音与音标

• 默认发美音，且只读一次。 菜单里可以改成英音；

关于「为什么必须停一下」（设计取舍）

如果只用 caretRangeFromPoint 判断，它在字符间隙、行首缩进甚至空白处都会吸附到最近的字符 —— 结果是鼠标还没碰到单词释义就弹出来，滑过一行英文时更是频繁误触发。所以本插件做了两层防护：

1. 精确命中测试：光标必须真的落在单词的可见矩形内；垂直方向再收缩 14%/6%， 避免走在行距里也算命中（收缩量与高亮胶囊的外扩量对齐，碰到胶囊就一定响应）。
2. 停稳才计时：指针连续移动时计时器不断重排，只有停下 200ms 才开始悬停计时， 再等 hoverDelayMs（默认 240ms）才查词。

代价是「有意悬停」比纯 hover 慢一点（约 440ms）。如果你更想要快，把 hoverDelayMs 调到 200；如果想要更稳，调大它。若你希望完全不自动弹层，把 trigger 改成 click。

---

二、安装

前置

• DSH 版本：0.2.0-rc.2（其它版本可能需调整选择器，见 §五）
• Node.js ≥ 22（仅构建时需要；仓库已含构建产物，正常安装不需要）

1. 从 GitHub 安装

在 DSH 界面里打开 Plugins 面板，输入仓库地址：

github:ilyskyo/Word-Hover-dsh

2. 从本地目录安装

先把仓库克隆/下载到本机，然后在 Plugins 面板里选择本地安装，填入该目录的绝对路径（示例）：

D:\plugins\Word-Hover-dsh

装完 必须完全退出 DSH 再重新打开（关闭窗口 ≠ 退出进程），新的宿主端模块与客户端 bundle 才会加载。

4. 重新构建客户端 bundle（改源码后才需要）

lib/client.js 已随仓库提交，正常安装不需要构建：

node tools/build.mjs

5. 确认生效

• 打开一个含 AI 英文回复的会话，把鼠标停在任意英文单词上；
• 或在开发者控制台执行：

__DSH_WORD_HOVER__.debug()          // 查看选择器命中情况与当前配置
__DSH_WORD_HOVER__.openSettings()  // 打开设置面板

6. 验证选择器与真实页面是否一致（推荐）

因为选择器来自对 DSH 包的分析，建议用真实页面验证一次：

# 1) 用调试端口启动 DSH（先完全退出已运行的实例）
& "D:\DeepSeekHarness\DeepSeekHarness.exe" --remote-debugging-port=9222
# 2) 打开一个含 AI 英文回复的会话，然后运行：
node scripts/verify-page.mjs

它会只读地报告：选择器命中数、正文采样、Range 矩形测量、插件挂载状态、主题 token 可用性。

---

三、配置

配置写在 profile 或 $DSH_HOME 的 cordis.patch.yml 里对应条目的 config。

⚠️ DSH 的 patch 条目是「整体替换 config」，不是合并。 覆盖时必须把想保留的字段全部重写。

- id: dsh-word-hover
  config:
    enabled: true
    trigger: hover            # hover | click
    hoverDelayMs: 240         # 悬停触发延迟
    hideDelayMs: 250          # 移出后关闭延迟
    lockOnClick: true
    speakEnabled: true
    provider: youdao          # 主源：youdao | freedict | suggest | custom
    fallbackProviders: [suggest, freedict]
    timeoutMs: 8000
    concurrency: 4
    missSuppressMs: 300000    # 上游答复"查不到"的词在此期间不重复请求；0 = 不抑制
    allowDirectFallback: false # 宿主不可用时允许客户端直连公网（有 CORS/合规风险）
    proxy: true
    proxyRateLimitPerMinute: 120
    accent: us                # 发音口音：us 美音（默认）| uk 英音
    phoneticDisplay: us       # 音标显示：no 不显示 | us 只美音 | uk 只英音 | both 都显示
    showTags: true            # 话题 · 标签单独成行
    excludeSelectors: []      # 额外排除的 CSS 选择器

界面上的 ⋮ 菜单与设置面板改的是同一份配置：宿主 config 提供默认值，用户偏好 （浏览器 localStorage）覆盖之。菜单里的改动会立刻重绘当前浮层，不需要重新悬停。

用你自己的合规后端

把 provider 设为 custom，并把 lookupPath 指向你的后端（支持绝对 URL）：

    provider: custom
    lookupPath: 'https://your-backend.example.com/dict-lookup'

后端只要返回同样的结构即可：

{
  "word": "hello",
  "phonetic": "həˈloʊ",
  "meanings": [
    { "partOfSpeech": "感叹词", "translation": "你好", "definition": "A greeting.", "example": "Hello, everyone." }
  ],
  "source": "your-backend"
}

---

四、架构

┌─ 浏览器（DSH Web GUI） ─────────────────────────────────────────┐
│  lib/client.js（__ModuleLoader__ 注册，自包含闭包）              │
│    dom.js        按鼠标坐标即时查询 DOM（只读，不改任何宿主节点） │
│    overlay.js    Shadow DOM 里的高亮块 + 浮层 + 设置面板          │
│    sessionmemo.js 在途请求折叠 + 「查不到」短时抑制               │
│    lookup.js     并发 4 / 8s 超时 / AbortController              │
│    speak.js      speechSynthesis → mp3 回落                      │
└──────────────────────────┬──────────────────────────────────────┘
                           │ GET /word-hover/dict（同源，无 CORS、无 Key）
┌──────────────────────────▼──────────────────────────────────────┐
│  lib/index.js（宿主端 Cordis 插件）                              │
│    输入校验（只接受单个英文单词）                                 │
│    令牌桶限流（默认 120 次/分钟/IP）                              │
│    在途请求合并                                                   │
│    provider 降级链：youdao → suggest → freedict                  │
│    /word-hover/settings 设置回显                                 │
│    /word-hover/test   连通性自检（带 CORS）                       │
└─────────────────────────────────────────────────────────────────┘

为什么高亮不改 DOM

需求要的是「单词被选中」的观感，但修改宿主 DOM（把单词包成 <span>）在 DSH 里代价很高： DSH 的消息正文是 React + 增量 Markdown 解析（只有尾部 1–2 个块会更新，其余块复用已冻结的 React element），插入包裹元素会与 React 的重渲染争夺同一批节点，并破坏文本复制。

所以本插件一行宿主 DOM 都不改：

1. 用 document.caretRangeFromPoint(x, y) 取光标下的字符；
2. 扩展成单词边界，用 Range.getClientRects() 量出精确矩形；
3. 在插件自己的 Shadow DOM 里画一个同位置的高亮块（视觉上等价于选中）。

结果：复制是原文、Markdown 渲染不受影响、流式输出不会把高亮冲掉、1000 词消息也不卡 （没有 per-word 监听，也没有预扫描）。

---

五、已知风险与限制

1. 词典接口是非官方的

主源 dict.youdao.com/jsonapi 是有道词典网页版使用的公开接口，不是官方开放平台 API：

• 没有 SLA，随时可能变更字段或限制访问；
• 属于非官方接口，请自行评估使用风险。

个人学习自用风险可控；请勿用于商业分发或批量抓取。 如需商用，请把 provider 改成 custom 指向你自有的合规后端（例如有道智云、百度翻译的付费接口）。

目录

dsh-plugin-word-hover/
├── package.json              # dsh.bundle + dsh.client 声明
├── cordis.patch.yml          # 插入 Loader 行的 bundle patch（含完整默认配置）
├── icon.svg                  # 插件管理器卡片图标（原创 SVG）
├── locale/{zh,en}.json       # 插件管理器列表页的标题与描述
├── lib/
│   ├── index.js              # 宿主端：路由、限流、降级链
│   ├── client.js             # 客户端 bundle（由 tools/build.mjs 生成，需提交）
│   └── providers/            # youdao / suggest / freedict / common
├── src/client/               # 客户端源码（11 个模块）
├── tools/build.mjs           # 零依赖构建：把 src/client/* 压成一个自包含闭包
└── scripts/                  # 测试与验证脚本（无测试框架依赖）

---

六、许可证与合规

• 代码：MIT。你可以自由使用、修改、分发、商用本代码。
• 词典数据：不在本许可证范围内，版权归各词典提供方所有。详见 THIRD-PARTY-NOTICES.md。

本项目默认主源是非官方公开接口，仅供个人学习使用，请勿用于商业用途或批量抓取。 如需商用，请把 provider 改为 custom 并指向你自有的合规后端。

本项目是第三方个人作品，与 DeepSeek、网易有道等任何主体无隶属、赞助或背书关系。