dsh-word-vault

dsh plugin --profile web add dsh-word-vault

dsh-word-vault · 英语生词库

多用户英语生词库 DSH 插件（适配 DSH 0.2+）：复制 → 鼠标处弹窗点选 → 入库并反馈，LLM 自动翻译，SQLite 计次，按时间 / 频次 / 掌握度查询，并输出可打印的趣味单词记忆卡（HTML / PDF / Word），配套考试闭环。1.10 起卡片与答题页的单词/例句都能点着听（🔊 Windows 自带语音，离线）；1.11 起可一键批量选词（每次 +10、最多 50）、考试错词一键出「能发音的在线复习卡」、卡面例句带中文对照。

---

界面预览 / Screenshots

词库总览 / Library · 记忆卡（每块带 IPA）/ Cards

!library · !cards

在线答题 / Quiz · 原生设置面板 / Settings

!exam · !settings

四张图分别对应：词库总览、记忆卡（每块上排真实音标 / 下排中文谐音 + 规律小字）、

在线答题（四选项、连对 3 次标记已学会）、DSH 原生设置面板。

环境要求（先看这条）

• 本版（1.11.0）适配 DSH 0.2 及以上（0.2.0-rc.1 / 0.2.0-rc.2 桌面版实测通过；0.1.7 亦兼容）。

0.2 完整可用——host 工具、浏览器端设置页、桌面版 GUI（dsh-app:// 协议）都跑通；

peerDependencies 上界已从 <0.2.0-0 抬到 <0.3.0-0。DSH 0.1.7 换了设置契约

（浏览器端 settingsScope → configForms），本版的设置面板是按新契约重写的。

• 本版新增：语音发音 🎧 —— 记忆卡与在线答题页的单词/例句旁各有一个 🔊，点了朗读；

用 Windows 自带语音合成（SAPI），离线、不联网、不调模型；出卡/出卷时后台预热，

点击即秒开（详见下文「发音」一节）。

• DSH 0.1.5 及更早装本版会这样（实测结论）：
• 工具、词库、/word-vault 页面、常驻助手照常可用；
• 设置面板不会出现——0.1.5 的浏览器端没有 configForms 这个服务，插件声明的客户端半边

会停在 pending，左侧看不到「英语生词库」这一项；

• 只想在 0.1.5 上用，就装上一版：dsh plugin --profile web add dsh-word-vault@1.0.2。
• 从插件市场装完、配置界面显示异常：先重启一次 DSH。市场会把它当临时条目热挂载

（条目 id 带 mkt- 前缀），那个条目的设置命名空间和本插件硬写的 dsh-word-vault 对不上；

重启后由 bundle 层加载，就正常了。

1. 录入（P1 已交付两条通道）

通道 · 触发 · 取词 · 常驻进程

① 剪贴板 + 点选弹窗（主线） · 用户照常 Ctrl+C · 助手只读剪贴板（序列号检测变更），宿主切词后弹窗 · PowerShell 助手

③ 对话录入（标配兜底） · 在 DSH 里贴文字 → wordvault_add · 宿主直接切词入库 · 不需要

主线交互（2026-09-16 定案）

用户要求"必须有正反馈、且不要什么复制都往库里灌"，因此改成点选才入库：

Ctrl+C 复制英文
   → 助手发现剪贴板变化，把文本交给宿主切词（约 0.3s）
   → 在【鼠标所在位置】弹出对话框（多显示器下跟随鼠标那块屏）：
        ┌───────────────────────────────┐
        │ 生词入库 · 识别到 4 词         │
        │ plant  world  share  animal   │
        │ [ 用户1 ] [ 用户2 ] [ 忽略 ]   │
        └───────────────────────────────┘
   → 点「用户N」→ 入库 → 同一窗口变成反馈（2.6s 后自动消失）：
        ┌───────────────────────────────┐
        │ ✔ 已录入成功                   │
        │ 4 词 → 用户1                   │
        │ 今日累计录入 12 词             │
        └───────────────────────────────┘
   → 20 秒没人点（可配）→ 自动消失、**不落库**

• 常驻小条：默认在屏幕右上角（距右边缘 40px），显示「生词库监听中 / 今日累计 N 词 / 最近一次结果」。可以用鼠标拖到任何地方，松手即记住位置（写在 word-vault-runtime\chip-pos.json，重启后仍在原位；若换了显示器/分辨率导致位置落在屏幕外，会自动回到默认角落）。
• 外观：白底卡片 + 淡蓝边框/标题条 + 淡黄高亮（今日累计条、忽略按钮）+ 黑字；进程已设为 DPI-aware，在高缩放（本机 125%）下 1:1 渲染不发虚。外观基准图见 docs/ui-chip.png（小条）与 docs/ui-dialog.png（点选弹窗）——这两张是 test/helper-visual.ps1 自动截的实机图。
• 不落库的三种情况：没人点选、点「忽略」、超时。普通复制（终端命令、配置片段）因此不会被误录。
• 需要旧的"复制即录"手感时，设置里把 autoCommit 打开即可。

为什么不用全局热键 + 模拟 Ctrl+C：见记忆「全局热键方案的结构性成本」——修饰键侧别码（左 Ctrl = 0xA2）、模拟复制要写剪贴板而跨进程 OLE 剪贴板写会互锁、注入的按键需要目标程序泵消息才生效。剪贴板监听把这三点全部消掉。

2. 架构

① 常驻助手 scripts/capture.ps1（PowerShell + WinForms，纯 ASCII 源码）
   轮询剪贴板序列号 → 变更时读文本/图片 → 追加写队列 JSONL
        ↓ 文件协议（本机 PowerShell 管道回传不可靠，全部走文件）
② 宿主 index.mjs / capture.mjs
   增量读队列(250ms) → 有归属就入库；无归属则切词并写"待点选"提示
   读命令文件(commit/dismiss) → 入库或丢弃 → 写回执(含今日累计)
        ↓
③ 工具层 wordvault_*（对话可用，不依赖助手进程）

文件 · 方向 · 内容

capture-queue.jsonl · 助手 → 宿主 · 每行 {ts,kind:'text' · 'image',text,imagePath,via,user}

capture-prompt.json · 宿主 → 助手 · {id,at,wordCount,words[],preview} → 触发弹窗

capture-commands.jsonl · 助手 → 宿主 · 每行 {ts,action:'commit' · 'dismiss',id,user}

capture-result.json · 宿主 → 助手 · {at,ok,message,todayCount,user,kind,id} → 弹窗/小条显示

capture-status.json · 助手 → 宿主 · 助手状态（含 dialog.visible/title，供自检与测试）

capture-trigger.txt · 宿主 → 助手 · 写入用户名 = 立刻抓一次当前剪贴板

capture-debug.log · 助手 → 宿主 · 调试日志（debug=true 时）

运行时文件落在 <dbPath 所在目录>\word-vault-runtime\。

3. 工具

工具 · 用途

wordvault_add · 把一段英文录入指定用户库（切词 → 翻译 → 落库 → 计次）

wordvault_query · 按时间区间 / 出现次数区间 / 掌握状态 / 排序 查询词条

wordvault_status · 库统计 + 各用户 + 助手状态 + 最近录入日志（自检排障用）

wordvault_capture_clipboard · 请求助手立刻抓一次剪贴板

wordvault_fix_last · 撤销最近一次录入 / 改到另一个用户库

wordvault_make_cards · 生成记忆卡内容（拆解块 + 荒诞梗 + 7 年级英文例句），可只重做指定词

wordvault_export_cards · 出记忆卡 HTML / PDF / Word + 首页预览

wordvault_exam_start · 按范围出题 + 起本地答题页（可顺带出打印卷）

wordvault_exam_answer · 手工录分（批改打印卷/对话答题）

wordvault_exam_result · 考试结算与错题清单

wordvault_exam_paper · 导出可打印试卷 + 参考答案

wordvault_scan_photo · 扫照片找被标记的印刷词(输出联络图)

wordvault_photo_status · 照片通道进度

4. 记忆卡输出（P2）

把选定范围的生词导成可打印的趣味单词记忆卡：拆词 + 一句荒诞梗钉住拼写 + 一句 7 年级能读懂的英文例句（看这个词在真实语境里怎么用）。版式与「拆解三法 / 梗四判据」照搬 workbuddy 专家包 funny-word-cards（本插件自包含，不依赖那个专家目录）。

流程

选范围(时间/频次/掌握度/指定词) → 缺卡片的用 LLM 生成拆词+梗+例句 → 落 cards 表 → 出片
   ├─ HTML  卡片版(A4 分页,可直接浏览器打印)
   ├─ PDF   Edge headless 打印成 A4 PDF
   ├─ Word  pandoc 转 .docx(表格版,便于再编辑)
   └─ PNG   首页预览图(排版自检用:确认第 4 行勾选框没被切掉)

老卡片（缺例句或缺段音标）会在出卡/出片时按 limit 逐步补齐，补生成走故事锁，不会换掉已定稿的荒诞梗。

点着听：卡片 HTML 里单词与例句旁各有一个 🔊（2026-10-05 起），点了用 Windows 自带语音朗读；PDF / Word 是打印件，没有按钮（纸面点不了）。

例句中文对照：英文例句下方一行小灰中文（2026-10-15 起）。译文由模型直译（≤25 字，不加解释），落在 cards.example_cn；老卡缺这行就不显示，下次出卡时自动补（按用户要求"按需补"，不做全量预热）。

工具：wordvault_make_cards（只生成内容）、wordvault_export_cards（出片，缺卡的默认先自动生成）。

卡片规格（与专家包一致）

• A4 竖版，每页 8 张（2 列 × 4 行），单面打印
• 每张卡四层：词头（序号圆标 + 大字单词 + 音标/词性/释义）→ 拆解块（字母片段 ↔ 中文音，上下对齐）→ 荒诞句（橙色左边框一句话）→ 英文例句 + 「已攻下」勾选框
• 例句是初一（7 年级）能读懂的典型用法句（6~12 词、简单时态、不含从句），句中的目标词蓝色加粗；2026-10-03 起它取代了原来的「默写区两条虚线」（老卡还没补上例句时仍显示虚线）；其下另有一行中文对照（见上）
• 单词 ≥11 字母自动缩小字号；不足 8 张时空位印成虚线框「空位 · 错词重写区」，不留白纸
• ⚠️ 每页张数与 CSS 是联动的（8 张/页时每卡约 65mm 高，字号间距是一整套），所以 PER_PAGE 固定在代码里不开放配置；要改必须同步改 cards.mjs 的 CARD_CSS

内容质量闸门（代码侧硬校验，不信模型自述）

…(truncated)