前言¶
在 DSH 里跑 Agent 时，事实检索往往依赖 web_search 或 web_fetch：需要外网、可能受排序与摘要质量影响，内网或隔离环境里更是直接不可用。若你希望模型能查百科条目、且答案来自本地已落盘的数据、可复现可核对，就需要一条不经过搜索引擎的通道。
下面介绍社区插件 kiwix-wiki（npm 包名 dsh-kiwix-wiki，维护者 MingShi350）。它通过本机或局域网内的 kiwix-serve 读取预先下载的 ZIM 快照，向 Agent 注册 wiki_search、wiki_read、wiki_books 三个工具；不抓网页、不需要 API key、不产生指向公网检索的流量。有网时它适合作为联网工具的补充，而不是替代。
这是什么¶
kiwix-wiki 是 DSH Host 插件：所有查询只发往你在配置里指定的 baseUrl（默认 http://127.0.0.1:8090），数据来自 kiwix-serve 挂载的 ZIM 文件。插件本身不含百科数据，你需要自行部署 kiwix-serve 并下载 ZIM（例如从 download.kiwix.org 或 library.kiwix.org）。
与实时网页搜索相比，有两点需要心里有数：
- 内容是该 ZIM 的快照，截止到 dump 日期；新近事件查不到，更新需换新版 ZIM。
- 换 ZIM 版本时，若
defaultBook使用别名（如zh）或去掉日期的系列名，插件会跟到同系列最新 dump，一般不必改配置。
当前版本（资料中 package.json）：1.4.1，许可证 MIT，运行需 Node >= 20。
核心功能：三个模型工具¶
| 工具 | 作用 | 关键参数 |
|---|---|---|
wiki_search |
全文搜索（摘要片段与总数）或精确标题检索（mode=title） |
query, mode, book, limit, offset |
wiki_read |
按精确标题读取整篇文章（纯文本，自动截断） | title, book, maxChars |
wiki_books |
列出本地 ZIM 书库（名称/语言/文章数/是否有全文索引） | language, query |
默认书库指向中文维基百科（内置默认别名 zh，可改为本地某本 ZIM 的精确文件名）。book 支持精确 ZIM 名、别名（zh / en / medicine / simple）、去掉日期的系列名，或书名子串。若显式传入带日期的 book 而服务器上已无该文件，插件会报错并列出可用书库；配置里的 defaultBook 则在找不到精确名时会回退到同系列最新 dump，并在结果中带 note 说明。
实现上插件零 npm 依赖，仅用 Node 内置 node:http / node:https 访问 kiwix-serve。
前置条件¶
安装插件前，先准备两样东西：
- kiwix-serve：官方 Docker 镜像
ghcr.io/kiwix/kiwix-serve，或官方 kiwix-tools 二进制。 - ZIM 文件：下载后放入 kiwix-serve 的服务目录。
仓库内提供 examples/docker-compose.yml（官方镜像 + 本地 ZIM 目录）与 docs/quickstart.md，用于从零起服务、选型 ZIM、改 baseUrl 与排错。
安装与启用¶
装进 DSH（web profile）可用下面两种方式之一，命令来自项目 README：
# 方式一：从 npm 安装（最省事）
dsh plugin --profile web add dsh-kiwix-wiki
# 方式二：从本地目录安装（源码或已克隆的仓库）
dsh plugin --profile web add /path/to/kiwix-wiki
dsh web # Host 插件改完必须重启才生效
也可在 profile 的 package.json 中增加 "dsh-kiwix-wiki": "link:/path/to/kiwix-wiki" 后同样执行 dsh web。
配置¶
配置块键名为 Config，字段均可省略以使用默认值。典型写法如下：
config:
baseUrl: http://127.0.0.1:8090 # kiwix-serve 地址
defaultBook: zh # 建议别名，自动跟随最新版 ZIM
timeoutMs: 15000
maxTextChars: 24000
catalogTtlMs: 60000 # 书库目录缓存；调小可更快发现新 ZIM
baseUrl 要指向局域网或远端 kiwix-serve 时，只改这一键即可。推荐写入 $DSH_HOME/profiles/<profile>/cordis.patch.yml；或使用叠加文件：dsh web --patch examples/kiwix-wiki.patch.yml。完整示例见仓库 docs/quickstart.md 第 5 节与 examples/kiwix-wiki.patch.yml。地址不可达时，报错会直接点名 baseUrl。
典型用法（Agent 侧）¶
Agent 在对话中按需调用工具即可，无需额外 HTTP 接口：
- 用
wiki_books确认当前 kiwix-serve 上有哪些 ZIM、语言与全文索引情况。 - 用
wiki_search按关键词或标题（mode=title）找条目，必要时指定book、limit、offset。 - 用
wiki_read按精确标题拉取正文，maxChars控制返回长度上限（与全局maxTextChars配合）。
集成测试默认连 http://127.0.0.1:8090；本地未起 kiwix-serve 时集成测试会自动跳过。开发者可在插件目录执行：
npm test
环境变量 KIWIX_TEST_URL 可指向其他 kiwix-serve 地址。
适用场景与注意¶
适合：内网、 air-gapped、弱网或无稳定外网出口；给本地小模型补可验证的百科事实；不希望检索内容出网；需要答案与 ZIM 原文一致、减少「搜索摘要漂移」。
注意：
- 不是实时资讯，时效性以 ZIM dump 为准。
- 插件随 DSH Host 进程运行，权限与当前
dsh web用户一致；安装前请阅读 GitHub 源码 与 MIT 许可证，并自行评估 ZIM 数据来源的版权说明（见仓库docs/quickstart.md许可与致谢一节）。本项目与 Wikimedia Foundation、Kiwix/openZIM 无隶属关系。 - DSH 社区插件目录为独立站点 skillhub.cn，与 DeepSeek / 幻方无官方从属关系。
结尾¶
kiwix-wiki 把「本地 kiwix-serve + ZIM」封装成 Agent 可调用的三条百科工具，在不能或不想依赖公网检索的环境里，仍能给模型一条离线、可核对的事实通道。目录页：skillhub.cn/plugins/MingShi350/kiwix-wiki；源码与文档：github.com/MingShi350/kiwix-wiki。
