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-*），不是插件包名

免责声明

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