dsh-plugin-term-dictionary 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# 更新日志
+
+本文件记录**发布出去**的版本。每一项都是可验证的行为，不写计划。
+
+## 未发布
+
+### 词条包与分享码
+
+- `tools/make-pack-index.mjs`：把 `packs/` 里的包扫成 `packs/index.json`（各自的 sha256、条数、分类、
+  可取的 https 地址），`--check` 不写文件、不一致即非零退出。索引是**确定性**的（`updatedAt` 取目录里
+  最新那个包的时间），所以 `--check` 才可能通过——第一版不是，这个 bug 被端到端用例逼出来。
+- 宿主：缓存里的包**对不上索引承诺的摘要**时会**重新取一次**再判定。摘要是权威、缓存不是；
+  否则重发包之后读者会在大约一天里看到 `checksum-mismatch`，看起来就像包坏了。
+- `packs/README.md`：发一个源的完整步骤与两条硬规则。
+- 端到端用例：真跑生成器 → 把生成出来的索引与包喂给真实路由 → 摘要必须通过；篡改一个字节必须被拒；
+  同 URL 新字节新摘要必须通过（证明会重取而不是拿缓存判死）。
+- `lib/core/pack.js`：包形状、按分类切片、允许字段的精确白名单（`context`/`notes`/`feedback`/
+  `untrusted`/`pinned`/`source`/历史计数/墓碑都进不去）、索引形状与 `refuseUrl`（只允许 https）。
+- `lib/pack-code.js`（宿主）：`dshpack1:` + base64url(raw-deflate) 分享码，解码时剥空白、
+  区分 `not-a-code`/`corrupt`/`too-large`，**解压上限 4 MiB**（防解压炸弹）。
+- 宿主路由：`POST /pack`（build / decode）、`GET /source/index`、`GET /source/pack`。
+  索引 1 小时、包 24 小时的磁盘缓存；源不可达而缓存还在 → 返回上次内容并标 `stale`；
+  索引里不可用的行丢掉并计数；包的 `sha256` 与索引承诺不符则拒绝。
+- 界面：面板第三个二级页「词条包」——生成分享码 / 下载包文件、粘贴分享码**先预览再导入**、
+  源的增删与刷新（列表显示名称/作者/许可/条数/分类/校验和，点预览才取回）。
+- 导入路径收成一条：`importEntries()` 由导入 / 导出页与词条包页共用（重复项报告、已删除词条的
+  勾选、"精心构造的复活"因此只有一份实现）；分类勾选行提成共享组件 `CategoryChecklist`
+  ——**变异 harness 先发现它有两份**。
+- 源地址规则三处共用（设置存储 / 页面添加源 / 宿主发起请求前），页面不可能接受传输层会拒绝的地址。
+- `settings.packSources`：源的列表（去空白、同一条规则过滤、去重、上限 12）。
+- 用例的 vm 沙箱补上 `URL`（真实页面有）：缺它时页面把每个地址都判成 `bad-url`，
+  "拒绝 http" 的检查因此看到的是错的理由。
+- 打包修复：`files` 白名单漏了 `lib/pack-code.js`（装出来的包 import 会失败）——
+  这是发布闸门"装进干净目录再 import"这一步第一次抓到真问题。
+
+### 复制词条
+
+- 每行一个**复制**图标、编辑器里一个**复制词条**按钮：一次点击把词条写成可读文本
+  （`术语（中文名）` / 解释 / `例：…`），**不需要先选中**。
+- 修掉"选中想复制却被切走"这一类：结束选中的那一下点击不再被当作选择手势。
+  以前面板里双击词条中的词会打开编辑器、正文里拖选句子（选区结束在标记词上）会切进词典，
+  现在两条路都不动，规则统一在 `lib/core/selection.js`。
+
+## 未发布
+
+### 反馈
+
+- **词条上可以留言**：编辑器里的「反馈」块记录问题类型（解释不对 / 术语不对 / 不该收录 / 其他）
+  与一句自己的说明；面板多了一个「已标记」视图，每行一个「撤回标记」。
+- **「解释不可信」是一条会给机器看的判断**：标上之后，自动解释**不会再覆盖**这条词条
+  （规则在数据层 `recordSighting`，所以页面的队列、将来的后台刷新、宿主自己的 `record` 动作都受它约束），
+  列表与已标记视图里都带徽标。
+- **重新生成会告诉模型上一次被否掉了**：页面发 `retry: true`，宿主在提示词末尾追加一句固定的话。
+  用户自己的备注永远不会发给模型——那是把备注变成指令。
+- **反馈报告**：导入 / 导出页可以把标记导出成一个文件（下载或复制）。报告里**永远没有会话原文**
+  （构造上就没有这个字段），当前解释要另外勾选才附上。
+- **也可以记进宿主自己的反馈日志**：宿主半边用 `ctx.inject(["sessionFeedback"], …)` 接这条可选服务
+  （和 `llm` 同一个模式），页面 POST 到自己的 `/feedback` 路由。**没有**把它写成客户端的
+  `remote.sessionFeedback`：实测这个桌面端没有 `remote` 服务，写进客户端 `inject` 会让整个包
+  永远等待、插件整体不加载。没有这条通道的组合会如实回答 `unavailable`，报告照样能导出。
+
+## 1.0.0 — 2026-10-10
+
+首个正式版。功能面：自动收录、标注、悬停解释、点击进词条、面板四个视图与两个二级页、
+设置页、导入 / 导出。
+
+### 收录与标注
+
+- **自动收录**：agent 回复渲染完成后扫描英文技术词、缩写、`camelCase` / `snake_case` 命名与内置词库里的
+  中文术语，每条消息最多新建 3 条、每分钟有独立预算；代码块与输入框不参与。
+- **标注**走 CSS Custom Highlight API：不写宿主的 DOM，因此正文的文本节点与偏移不会被改动；
+  行内代码与正文遵守**同一条**匹配规则。
+- **收录门槛可调**：最短词长、是否收代码风格命名、是否收中文术语。
+- **删除是黑名单**：删掉的词不会被自动重新收录，导入默认也跳过它；「已删除」视图里可以**撤回**。
+
+### 鼠标手势
+
+- **悬停**在指针停稳 `hoverInMs`（默认 110ms，设置页可调 0–200ms）后浮出简短解释；
+  读出延迟默认 **0**（给"离开"加延迟读起来像卡顿）。
+- **点击**已标注的词进入词典对应词条并滚动到视野；词典里没有的词弹卡片提供「创建词条 /
+  用模型生成解释」；选中词句出现「添加词条」按钮。
+- 命中是**一次文本走查的查表**：caret 给出 `(节点, 偏移)`，标注层记下每段标记的区间，
+  命中即查表——不读包围盒、不按比例估算字符位置。这一条是本版与早期实现最大的区别，
+  也是"有下划线但悬停/点击没反应"那一类问题的根因。
+- 指针层只此一份：早期由第二个插件（`dsh-plugin-term-wikilink`）承担的那半边已合并进来并退役，
+  两层各算一次、结论不一致的结构性问题因此消失。
+
+### 面板
+
+- **四个视图**：全部 / 待补充 / 已钉选 / **已删除**（墓碑列表 + 逐行撤回）。
+- **两个二级页**：**设置**（11 项偏好：两态用开关、多值用选项条、范围内的数用滑杆 + 数字框）与
+  **导入 / 导出**。
+- 词条行整块可点（行内按钮保留各自语义）；批量选择一次写入，每条各留一个墓碑。
+- **钉选**的词条不会被「清空词典」带走，确认框里写明「删几条、留几条」。
+
+### 导入 / 导出
+
+- 导出可按**全部**或**按分类**（分类就是词条的「领域」，清单由数据统计得出）；一个分类都不选 =
+  导出空文件，而不是"那就全导"。
+- 导出文件**不带**本机的看到历史（`seen` / `lastSeenAt` / `createdAt`），带 `pinned`——那是用户的判断。
+- 导入逐条判定归宿并**报告各自条数**：新建、已存在（原样保留）、被你删过（默认跳过，可显式勾选
+  「导入我删除过的词条」，勾选后这些词条会被导入并从已删除列表撤回）、重复或无效。
+- 导入**不读**文件里的 `source`：所有导入的词条都由保存路径记成 `user`，那是唯一被合并当作
+  「用户意图」的来源。
+
+### 模型解释
+
+- 生成解释走 profile 里挂载的 `llm` 服务：优先用**配置里指定的路由**，其次用 profile 自己的选择，
+  最后才回退到注册表里的第一条——并且只对**凭据缺失**这一类失败继续换线路，模型侧的失败如实报告。
+- 解释语言（跟随界面 / 中文 / 英文）与详细程度（一句话 / 标准 / 详细）是设置页里的偏好，
+  `zh` 字段始终是中文。
+
+### 同步与存储
+
+- 文档形状：活词条在 `entries`，墓碑在 `backing` 且键列在 `deletedKeys`；本机文件写在
+  `~/.dsh/dsh-plugin-term-dictionary/dictionary.json`，宿主路由 `/dsh-term-dictionary/{state,entries,explain}`。
+- 合并是并集 + **墓碑裁决**：删除只在 `mergeRecords` 一处决定，复活需要"用户要过的记录、且严格
+  晚于那次删除"。一台时钟落后的机器不会因为"现在比删除新"而把删除撤销掉。
+
+### 已知限制
+
+见 README 的「已知限制」一节。其中一条要特别说明：**点击"词典里没有的词"仍走几何命中**
+（`blockAtPoint` → `elementFromPoint` 复核 → 偏移换算），那条路上的快照老化问题没有做过对照实验；
+悬停已经不依赖它。
+
+## 0.1.0 — 2026-10-08
+
+内部版本：面板、收录、标注、模型解释的最初实现。未发布。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lakerian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.