Wiki-Runner

高性能、多语言的 Wikipedia 最短点击路径搜索引擎与本地 Web 应用。

English · 构图说明 · Wiki-Race 兼容性 · 参与贡献

Wiki-Runner 使用 C++17 双向 BFS 搜索 Wikipedia 的最短有向路径，并可在线检查路径是否能 在 wiki-race.com 的页面规则下复现。GUI 和 CLI 都会显示每一步应该寻找的链接文字。

特性

• C++17 双向 BFS 与 mmap CSR 图；
• 支持 zh、en、ja 等 Wikipedia 语言；
• 支持重定向别名和中文简繁标题；
• 在线排除隐藏或过期链接；
• 缓存最短路径及其全部连续子路径；
• 缓存页面解析结果和已验证路径，不保存完整 HTML；
• 无 C++ 第三方库，无前端构建依赖。

环境准备

目前要求 64 位小端 Linux、Python 3、GNU Make 和支持 C++17 的编译器。在 Ubuntu/Debian 上可安装：

sudo apt update
sudo apt install -y build-essential python3 python3-venv

编译并运行测试：

make -j
make test

准备图数据

首次运行前，下载并构建所需语言的 Wikipedia 图：

make prepare WIKI_LANG=zh

切换语言：

make prepare WIKI_LANG=en
make prepare WIKI_LANG=ja

日语的 Wikimedia 代码是 ja，也可以输入 jp。下载器支持断点续传和 MD5 校验； 构图器会直接解析压缩 SQL dump，不需要数据库服务。中文构图所需的 OpenCC 会自动安装 到项目的 .venv 中。

如需固定数据版本：

make prepare WIKI_LANG=en SNAPSHOT=20260701

首次构建大型 Wikipedia 需要较长时间和充足磁盘空间。下载文件、资源需求和构图参数见 BUILD_GRAPH.md。

运行

Web GUI

make serve WIKI_LANG=zh

打开 。GUI 的 HTML 验证开关默认关闭，此时只运行快速离线 查询；打开后才会在线检查每条边，并显示在上一页需要点击的文字。 两次实际 Wikipedia 页面请求至少间隔 5 秒；遇到 HTTP 429 时会按照 Retry-After 延长等待（至少 60 秒）并只重试一次。

在线验证 CLI

make path-live WIKI_LANG=zh FROM="数学" TO="哲学"

解析结果默认缓存在 data/live-cache/ 中 24 小时。可以调整缓存时间：

make path-live WIKI_LANG=zh CACHE_HOURS=6 FROM="数学" TO="哲学"

建议为 Wikipedia 请求设置包含联系方式的 User-Agent：

export WIKI_RUNNER_USER_AGENT="Wiki-Runner/1.0 (you@example.com)"

离线 CLI

只搜索本地 SQL 图，不执行 Wiki-Race 在线验证：

./bin/wiki-runner \
  --graph data/zhwiki-latest/graph \
  path 数学 哲学

其他命令：

./bin/wiki-runner --graph /path/to/graph suggest 数学 10
./bin/wiki-runner --graph /path/to/graph stats
./bin/wiki-runner --graph /path/to/graph benchmark 1000

Wiki-Race 验证

Wiki-Runner 先从本地图得到最短候选路径，再通过 Wikipedia Action API 获取候选路径上 的页面。遇到游戏中不可点击的边时，它会排除该边并重新搜索。成功路径中的每一条边都 经过在线页面验证，锚文本会显示在 GUI 和 CLI 中。

这一步不需要 API key、账户或全站 HTML 下载。详细过滤规则和正确性边界见 WIKI_RACE.md。

缓存与资源上限

默认配置会把 C++ 路径与标题缓存限制在 512 MiB，并把进程地址空间硬限制在 8192 MiB。搜索 worker 会在启动时按预算自动减少。CLI 磁盘缓存最多使用 4096 MiB， GUI 的 IndexedDB 数据预算为 384 MiB，因此默认持久缓存总预算低于 5 GiB。

make serve MEMORY_LIMIT_MIB=6144 CACHE_MEMORY_MIB=256
make path-live CACHE_MAX_MIB=2048 FROM="