中文 | English
kiwix-wiki — 离线维基百科数据库查询插件
给 DSH 里的模型 / Agent 加一条完全离线的百科查询通道：wiki_search / wiki_read / wiki_books
三个工具向你自己的 kiwix-serve（官方 ghcr.io/kiwix/kiwix-serve）查询预先下载好的 ZIM 数据包，
返回真实存在的条目正文、搜索命中与书目信息。
它是什么
- 不是网页搜索：不碰搜索引擎、不抓网页、不需要 API key、不产生任何外网流量。所有请求只发往
你配置的
baseUrl（默认本机 http://127.0.0.1:8090），数据来自已经落盘的 ZIM 快照。
- 不是实时资讯：内容是快照，截止到该 ZIM 的 dump 日期（例如
2026-08 的中文维基 354 万条）。
新近事件查不到；要更新就换新版 ZIM，插件会自动跟到最新一份 dump，不用改配置。
什么时候用：内网 / 隔离环境 / 弱网或没有外网出口；给本地小模型补事实能力；
需要可复现、可验证的答案（返回的是 ZIM 里的原文，不受搜索结果排序漂移影响）；
不希望检索内容出网。有网时它是 web_search / web_fetch 的补充，而不是替代。
从零开始？ 看 docs/quickstart.md：用官方 Docker 镜像起 kiwix-serve、
下载 ZIM、装插件、怎么改 baseUrl（默认 http://127.0.0.1:8090）、排错与安全提示。
注册的模型工具
| 工具 | 作用 | 关键参数 |
|---|
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）、去掉日期的系列名，或书名子串。
前置条件与安装
本插件不含数据，需要自己准备两样东西：
kiwix-serve HTTP 服务 —— 官方镜像 ghcr.io/kiwix/kiwix-serve（或官方 kiwix-tools 二进制）；- ZIM 数据文件 —— 从官方库 https://download.kiwix.org/zim/ 或 https://library.kiwix.org 下载，
放进 kiwix-serve 的服务目录。
装进 DSH（包名 dsh-kiwix-wiki，两种来源任选）：
# 方式一：从 npm 安装（最省事）
dsh plugin --profile web add dsh-kiwix-wiki
# 方式二：从本地目录安装（源码 / 克隆下来的仓库，本仓库位于 /path/to/kiwix-wiki）
dsh plugin --profile web add /path/to/kiwix-wiki
# 也可手工在 profile 的 package.json 里加一行："dsh-kiwix-wiki": "link:/path/to/kiwix-wiki"
dsh web # Host 插件改完必须重启才生效
完整步骤（Docker 部署、ZIM 选型、配置改法、排错表）见 docs/quickstart.md。
配置（Config，均可省略取默认值）
config:
baseUrl: http://127.0.0.1:8090 # kiwix-serve 地址，随时可改
defaultBook: zh # 建议填别名（zh/en/medicine/simple），自动跟随最新版 ZIM
timeoutMs: 15000
maxTextChars: 24000
catalogTtlMs: 60000 # 书库目录缓存毫秒数；调小可更快发现新加入的 ZIM
baseUrl 默认指向本机 http://127.0.0.1:8090。要连局域网/远端服务器只改这一个键，二选一：
- 写进 profile patch
$DSH_HOME/profiles/<profile>/cordis.patch.yml（优先级最高，推荐）；
- 或用叠加文件、不动 profile：
dsh web --patch examples/kiwix-wiki.patch.yml。
两种写法的完整示例见 docs/quickstart.md 第 5 节
与 examples/kiwix-wiki.patch.yml。地址不可达时，报错会直接点名 baseUrl。
ZIM 换版不用改配置：defaultBook 推荐写别名（zh）或去掉日期的系列名（wikipedia_zh_all_maxi），
两者都自动选中该系列最新的那一份 dump。若确实填了带日期的精确名（如 wikipedia_zh_all_maxi_2025-09），
而服务器上只剩新版（…_2026-08），插件会回退到同系列最新 dump，并在结果里带一条 note 说明；
显式传给工具的 book 参数永不替换，找不到就报错并列出可用书库。
零依赖：仅使用 Node 内置 node:http / node:https，无 npm 依赖、无构建步骤
（刻意不用 global fetch，原因见 lib/kiwix.js 头部注释）。
测试
npm test # 离线单元测试 + 集成测试（Kiwix 服务器不可达时集成测试自动跳过）
集成测试默认连 http://127.0.0.1:8090，可用环境变量 KIWIX_TEST_URL 指向别的服务器。
部署素材
许可
本插件代码：MIT，见 LICENSE。ZIM 数据不在本仓库内，版权归各内容来源方
（详见 docs/quickstart.md 第 10 节）；
本项目与 Wikimedia Foundation、Kiwix/openZIM 无隶属关系。
