汉语词典 GJY-cmd/dsh-cn-dict

dsh-cn-dict

给 DeepSeek Harness（DSH）用的本地离线汉语词典：一个 Agent 模式 + 一个模型可见工具，直连本地 SQLite 词库。

本仓库只包含代码与文档，不包含任何词库数据。
首次运行建库脚本时会自动联网下载所需数据到缓存目录（见数据来源与下载）。
各数据源的来源与许可状况见 DATA-LICENSES.md——其中一份上游未声明许可，务必先读。

它提供什么

- 一个 DSH Agent 模式（zh-dict，显示名「汉语词典」）：模式内的会话获得完整标准工具集 + 词典能力，并带三条作答纪律（作答前先查库、未收录要标注来源、不把模型记忆说成词库条目）
- 一个模型可见工具 dict_lookup：字级资料（部首/笔画/异体字/文字组件/粤语/闽南音）、词语释义、成语（释义+出处+例句）、歇后语、汉英对译；繁体输入自动折简；另有全文检索

三条作答纪律由模式的人设前缀 + 插件注册的提示词节共同强制，所以它表现为一个独立的词典模式，而不是「多了个工具」。

最快上手：让 AI 帮你装。 安装只需改路径、装 bundle、重启客户端，交给一个能读写文件的 AI 编码助手（例如 DSH 自身的 Agent）即可——安装一节里有可直接复制的一段话。安装前建议先扫一眼 DATA-LICENSES.md，数据许可里有一项需要你自己判断。

仓库内容

dsh-cn-dict/
├─ README.md 本文件 ├─ DATA-LICENSES.md 数据来源、许可、构建期网络访问说明 ← 重要 ├─ LICENSE 代码许可（MIT） ├─ NOTICE 第三方数据来源与署名要求 ├─ package.json 插件包 @GJY-cmd/dsh-cn-dict ├─ index.js 插件实现（注册 dict_lookup + 提示词节） ├─ tools/ │ └─ build-cn-dict.cjs 建库脚本（下载 → 解压 → 建 SQLite） └─ preset/ 可选：把「汉语词典」模式装进 profile 的 bundle ├─ package.json ├─ index.js ├─ cordis.patch.yml └─ locale/zh.json

不包含（见为什么不附带数据）：

- chinese.sqlite（约 182 MB）
- cache/（约 97 MB 源数据）

依赖与要求

- Node.js ≥ 22.5（需要内置的 node:sqlite；实测在 Node 24.21 正常）
- 零第三方依赖：插件与建库脚本都只用 Node 内置模块（node:sqlite / node:zlib / node:http / node:fs）
- 这一点是刻意的：DSH 的插件常以 junction / symlink 方式链入 profile，Node 会按真实路径解析依赖，源码目录没有 node_modules 时任何外部依赖都会 Cannot find package 并导致整个预设加载失败

安装

建议：让 AI 帮你装

安装涉及改路径、装 bundle、重启客户端，还要按环境适配——交给一个能读写文件的 AI 编码助手（例如 DSH 自身的 Agent）最省事，也是本项目推荐的安装方式。

在 DSH 里新建会话，把下面这段直接发给它：

帮我在本机安装 dsh-cn-dict（DSH 的本地离线汉语词典插件）。
代码在当前工作目录（或我给你的路径）。请先完整读 README.md 与 DATA-LICENSES.md，然后：1) 运行建库脚本生成词库（需要联网下载约 98 MB 数据）；
2) 把插件与 preset 安装进我当前的 DSH profile；
3) 校验预设能被加载、dict_lookup 工具可用；
4) 最后告诉我该怎么验证（我该新建会话还是需要重启客户端）。
遇到报错先读文档里的「常见报错」和「技术要点」，不要随手改 profile 配置。

两点交代清楚，能显著提高一次成功率：

- 让它先读文档再动手——安装的坑（profile 配置不能手改、插件必须零依赖、Config 必须是 Standard Schema）都写在技术要点里，AI 读了就不会重踩
- 把词库路径交给它决定，或明确告诉它你想放哪（词库约 182 MB，建议放在有空间的盘）

你仍然需要自己确认两件事：数据来源的许可（见 DATA-LICENSES.md）与词库落盘位置。

下面是手工步骤，供想自己动手或排查问题时使用。

插件包需要能被 profile 解析到。两种方式：

A. 本地包 + junction（开发/自用）

1. 把本仓库放到一个固定目录，例如 D:\dsh-cn-dict
2. 让 profile 能解析到它（示例为 Windows 的 junction）： New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\<profile>\node_modules\@GJY-cmd\dsh-cn-dict" -Target "D:\dsh-cn-dict"

3. 在 profile 的 bundle patch 里声明它，或直接用下面的 preset/ 安装模式

B. 用 preset/ 安装「汉语词典」模式

1. 编辑 preset/cordis.patch.yml，把 cn-dict 那一行的 dbPath 改成你的词库路径
2. 用 DSH 的插件管理器安装这个 bundle（plugin_manager → install_bundle，目标为该目录的绝对路径）
3. 重启 DSH，新建会话时模式列表里会出现「汉语词典」注意：DSH 的 profile 配置（package.json 的 dsh.profile.bundles 与 cordis.patch.yml）只能由应用自己的机制写入。手工编辑会被应用重写掉——这是踩过的坑。

数据来源与下载

建库脚本自带下载：首次运行时会把需要的文件取到缓存目录，这一步需要联网。

| 文件 | 字节数 | 下载地址 |
| word.json | 27,354,320 | GitHub：pwxcoo/chinese-xinhua → data/word.json |
| ci.json | 26,129,191 | 同上 → data/ci.json |
| idiom.json | 10,319,857 | 同上 → data/idiom.json |
| xiehouyu.json | 约 1.2 MB | 同上 → data/xiehouyu.json |
| Dictionary.json | 33,190,508 | GitHub：max32002/chinese_dictionary → 根目录 ⚠️ 见许可说明 |
| cedict.txt.gz | 3,981,100 | CC-CEDICT 官方导出：https://www.mdbg.net/chinese/export/cedict/cedict_1_0_ts_utf-8_mdbg.txt.gz |

合计约 97.7 MB；已就绪的文件不会重复下载。

几点说明：

- 字节数用于校验：脚本按上表核对。大小一致即说明版本相符；不一致会报出是哪个文件、实际多少字节，并拒绝使用。
- GitHub 访问：部分网络环境下 raw.githubusercontent.com 直连受限，脚本因此在两个公共 GitHub 代理前缀（ghproxy.net、gh-proxy.com）之间轮换重试。这是第三方代理，请求会经过它们：
- 它们与本项目无关联，可用性、稳定性与隐私处理不作任何保证
- 支持直连的环境建议改脚本用直连（把代理前缀数组留空即可）
- 也可以完全不用脚本下载：自行把文件放进缓存目录，脚本按字节数校验后会直接使用

- max32002 有两个版本可选：Dictionary.json（8 万字，但只有「部首/笔画」完整）与 Dictionary_lite.json（1 万字，但部首/笔画/异体字/同义字/文字组件都完整）。上表用的是完整版，也就是本项目的默认用法。
- cedict.txt.gz 必须是 gzip：脚本按 gz 读取。若你从其他渠道拿到未压缩文本，请自行压缩并命名为 cedict.txt.gz。

构建词库

node tools/build-cn-dict.cjs <缓存目录> <输出.sqlite>
例：
node tools/build-cn-dict.cjs D:\dsh-cn-dict-data\cache D:\dsh-cn-dict-data\chinese.sqlite

- 首次运行会下载缺的源文件到缓存目录（已存在的按字节数校验后跳过）
- 输出库每次重建，重跑是幂等的
- 实测：下载约 5 分钟（取决于网络），建库本身约 10 秒，成品库约 182 MB

常见报错

| 现象 | 原因与处理 |
| 卡在下载 / HTTP 403 / HTTP 502 | GitHub 直连或所用代理受限。换代理、改直连，或自行下载文件放进缓存目录 |
| 下载失败：size mismatch | 拿到的版本不同或文件不完整。换渠道重下；若确认版本无误，可改脚本 SOURCES 表里该项的期望字节数 |
| cedict.txt.gz 取不到 | mdbg.net 的导出是动态端点，偶发不可用。从 CC-CEDICT 项目主页 找其他渠道，压缩成 gz 后命名为 cedict.txt.gz 放进缓存目录 |
| 词库未收录（查询时） | 不是建库问题——上游数据本身没有该词条，属已知限制 |
| 控制台中文显示为乱码 | 通常是 Windows 控制台编码问题，不影响写入数据库；用 chcp 65001 或换终端确认 |

形成的表结构

| 表 | 内容 | 来源 |
| chars | 字级：部首、部首笔画、总笔画、异体字、同义字、文字组件、普通话/粤语/闽南音、Unicode | max32002/chinese_dictionary ⚠️ 见许可说明 |
| words | 字条与词条释义、拼音、笔画 | pwxcoo/chinese-xinhua（MIT） |
| ci | 词语释义 | pwxcoo/chinese-xinhua（MIT） |
| idioms | 成语：释义、出处、例句、拼音、缩写 | pwxcoo/chinese-xinhua（MIT） |
| xiehouyu | 歇后语：谜面 → 谜底 | pwxcoo/chinese-xinhua（MIT） |
| english | 汉英对译 | CC-CEDICT（CC BY-SA 4.0） |
| simp_of | 繁 → 简映射 | 由上述来源推导 |
| search_fts | 跨表全文索引（FTS5） | 推导 |

只用许可清晰的来源（推荐做法）

若你不希望引入许可不明的那一份，不提供 Dictionary.json 即可——脚本会跳过 chars 表，其余表照常建。代价是失去字级资料（部首/笔画/异体字/文字组件/粤语闽南音），字条释义仍可由 chinese-xinhua 提供。此时全部数据仅剩 MIT + CC BY-SA 4.0 两份，组合库按 CC BY-SA 4.0 发布即可。

（若你希望脚本在缺失该文件时直接失败而不是跳过，把 FILES 表里该项标记为必需即可。）

配置

| 配置项 | 默认 | 说明 |
| dbPath | 无（必填） | 词库 SQLite 路径；插件配置或环境变量 DSH_CN_DICT_DB |
| defaultLimit | 5 | 单次返回条数上限 |
| includeEnglish | true | 中文条目是否附英文对译 |

配置通过插件的 Config（Standard Schema 接口）声明，可在 profile 的 patch 行 config 里覆盖。

工具行为

dict_lookup(word, mode?, detail?, limit?, english?)

- mode: lookup（默认）——精确查词：字、词语、成语、歇后语、汉英；繁体自动折简；未收录时返回前缀相近词条，并提示改用模型自身知识且需标注
- mode: search——全文检索：按释义找词、按部件找字等
- detail: brief|normal|full——释义详细度，默认 brief；full 才输出完整原文与例句
- english: false 可关掉中文条目的英文对译

token 开销（实测）

用 deepseek-flash、缓存命中率约 96% 的会话测得：

| 项 | 优化前 | 现版本 |
| 工具定义（每轮请求都发） | 585 tok | 331 tok |
| 提示词节（每轮请求都发） | 278 tok | 92 tok |
| 固定合计 | 863 tok/请求 | 423 tok/请求 |
| 单次查字 | 365 tok | 56 tok |
| 单次成语 | 294 tok | 156 tok |
| 10 词任务内容 | 1479 tok | 641 tok |

做过的优化：

1. 字条/词条去重——查单字时 chars 与 words 描述同一条目，原先各输出一遍
2. detail 档位——源数据释义是上千字符的无差别长文（古文例句、交叉引用），按行截断即去掉绝大部分噪声
3. 压缩固定开销——工具定义 471→187 字符、提示词节 323→104 字符（原先把纪律条款写了两遍）；成语查询时【词语】那份长文压成一句，因为【成语】条目已给出完整权威释义

关于额度，一个诚实的说明

固定开销虽然每轮都发，但绝大部分会命中上下文缓存，按缓存命中价计费（比未命中输入便宜约 50 倍、比输出便宜 200 倍）。以实测的一轮为例（未缓存输入 934 / 缓存读取 25,856 / 输出 784）：

- 单轮成本 ≈ ¥0.0046（空闲价）/ ¥0.0092（高峰价）
- 输出占 68%，未缓存输入 20%，缓存读取仅 11%
- 词典插件自身的固定开销 ≈ ¥0.0000085/轮，1000 轮不到一分钱

也就是说：省固定头部的实际收益远小于「省输出」。若你要进一步压，优先压工具返回内容的长度（那部分每轮都是新增 token，进不了缓存），而不是压固定头部。

已知限制

1. 没有单一权威开源「全量现代汉语词典」。本词库是三份开源数据拼合：常用字词、成语、歇后语覆盖较好，但收词量不等同于《现代汉语词典》（那是版权作品）。
2. 部分常用词缺纯中文释义：例如「苹果」只能给汉英对译，因为所用开源数据里没有该词的独立中文条目。此时模型会按纪律标注并自行补充。
3. 笔画数两套口径：chars.strokes_total 来自 max32002（繁体字形口径），words.strokes 来自 chinese-xinhua（简体口径）；同一字可能差 1，当前按来源分别展示。
4. words.explanation 原始释义是长文（含古文例句与交叉引用，单条可达上千字符），由 detail 档位截断，full 才完整输出。
5. 建库需要联网（脚本自带下载），且依赖 GitHub 与 mdbg.net 可达；部分网络环境需要镜像/代理。详见数据来源与下载与 DATA-LICENSES.md。

为什么不附带数据

1. 许可：组合库包含 CC BY-SA 4.0 的 CC-CEDICT（传染性），且含一份上游未声明许可的数据，直接分发有风险。详见 DATA-LICENSES.md。
2. 体积：182 MB 的 SQLite 加 97 MB 源文件不适合放进 git 仓库或 npm 包（GitHub 单文件 100 MB 上限）。

所以本仓库只放「如何构建」，由使用者自行获取数据。

许可

- 代码：MIT，见 LICENSE
- 数据：不适用 MIT。你自行构建出的词库受各上游数据源许可约束，见 NOTICE 与 DATA-LICENSES.md

关于本仓库本身

本仓库是已就绪的发布物：代码已清掉开发期的本地路径与前缀，文档中的占位符也已替换为实际值。
因此原文档里「发布前需要替换的占位符」「发布前：代码需要对齐本文档」两节已不再适用，故移除。

仓库里不包含词库与源数据（体积大且受第三方许可约束），建议的 .gitignore 已随仓库提供。

技术要点（这些坑别踩回去）

| 要点 | 原因 |
| 插件必须零外部依赖 | DSH 常以 junction / symlink 把插件链入 profile；Node 按真实路径解析依赖，源码目录没有 node_modules 时任何 import '@xxx/yyy' 都会 Cannot find package，并导致整个预设加载失败 |
| Config 必须是 Standard Schema | 宿主按 Config['~standard'].validate(config) 校验行 config。导出普通 JSON Schema 对象会在激活时报 Cannot read properties of undefined (reading 'validate') |
| 客户端 bundle 必须放 lib/client.js | DSH 的客户端模块系统按 exports["./client"] 解析，且约定产物在 lib/；放包根目录不会被下发（本项目不含客户端部分，此条留给想加 UI 的人） |
| 不要手工写 profile 配置 | profile 的 package.json 与 cordis.patch.yml 由应用自己维护，手工编辑会被重写。安装走 plugin_manager 的 install_bundle |
| 声明 dsh.client.inject 前先确认模块名 | dsh.client.inject 里的名字是客户端模块名（@deepseek-ai/dsh-client-*），不是插件包名 |

免责声明

本项目只提供「本地查询工具 + 建库脚本」。词库数据由你自行从第三方开源仓库/站点获取，著作权与许可状况请自行核实。作者不对上游数据的许可状态、准确性或合法性作任何保证，也不对使用者依此分发数据所产生的后果承担责任。本文档不构成法律意见。