detpecca/LLM-Wiki

LLM-Wiki（论文实现）

对论文 《Retrieval as Reasoning: Self-Evolving Agent-Native Retrieval via LLM-Wiki》（arXiv:2605.25480）的独立实现：把文档编译成带双向链接的结构化 Wiki，查询时由 Agent 组合 wiki_search / wiki_read 进行遍历推理，并通过 Error Book 实现持久的自我纠错。

安装

python -m venv .venv
.venv/Scripts/pip install pyyaml pytest   # Windows
.venv/bin/pip install pyyaml pytest     # Linux/macOS

唯一运行时依赖是 pyyaml（LLM 调用走标准库 urllib）。

配置 LLM

OpenAI 兼容接口均可，环境变量三选一配置：

export LLM_WIKI_BASE_URL="https://api.moonshot.cn/v1"   # 默认值，可换任何兼容端点
export LLM_WIKI_API_KEY="sk-..."
export LLM_WIKI_MODEL="kimi-k2-0711-preview"            # 默认值，可换

本地模型（Ollama 等）：LLM_WIKI_BASE_URL=http://localhost:11434/v1。

使用

编译文档进 Wiki（算法 1 全流程：选页→编译→校验→Error Book→修复）
python -m llm_wiki --wiki ./wiki ingest my_notes.txt

提问（Agent 遍历：搜索→阅读→跟链接→充分性检查→作答）
python -m llm_wiki --wiki ./wiki query "哪部电影的导演更年长？"

检索 / 阅读 / 统计（命令行直用；也是 harness 插件调用的入口）
python -m llm_wiki --wiki ./wiki search "导演"
python -m llm_wiki --wiki ./wiki read entities/X concepts/Y
python -m llm_wiki --wiki ./wiki stats

结构校验（validate 命令跑 4 类确定性检查；第 5 类 unseen-overwrite 在编译期）
python -m llm_wiki --wiki ./wiki validate

代码自动修复；--finalize 追加 3 轮 代码↔LLM 修复（论文 §3.3 定稿阶段）
python -m llm_wiki --wiki ./wiki fix --finalize

删除一篇已入库的文档并恢复 Wiki 一致性（先 --dry-run 预览影响面）
python -m llm_wiki --wiki ./wiki delete my_notes.txt --dry-run
python -m llm_wiki --wiki ./wiki delete my_notes.txt

查看错误记录本
python -m llm_wiki --wiki ./wiki errorbook

（--wiki 是全局参数，需放在子命令之前。）

读/修复类命令（ingest/search/read/stats/validate/fix/errorbook）都支持 --json，供 DeepSeek Harness 插件（dsh-llm-wiki）以子进程方式驱动。delete 是破坏性的知识库管理，刻意只留给人工使用，不提供 --json、不暴露给 Agent。

无 API key 时可跑脚本化端到端演示（编译本论文自身 + 多跳查询）：

python examples/demo_paper.py

论文 → 代码 映射

| 论文 | 实现 |
|---|---|
| 算法 1 索引期编译（附录 D） | llm_wiki/compile.py（Compiler.compile_passage 逐行对应） |
| 页面 Schema（附录 E） | llm_wiki/schema.py + store.py（frontmatter + 三个必备章节 + 双向 wikilink） |
| 7 类错误分类（附录 F） | llm_wiki/validators.py（5 类确定性 + 2 类 LLM 验证） |
| Error Book 五阶段（§3.3） | llm_wiki/error_book.py（Discover→Attribute→Constrain→Inject→Verify&Close） |
| 双层修复（§3.3） | code_autofix / llm_periodic_fix / finalize（3 轮循环） |
| wiki_search/wiki_read（§3.2） | llm_wiki/search.py（结构化信号优先）+ store.read_many |
| 遍历策略与终止（§3.2、附录 H） | llm_wiki/agent.py（Tmax=15，P=3，作答前至少一次 wiki_read） |

超参数（论文 §4.4）

T_max=15（工具调用预算，计的是工具调用数而非模型轮次——原生 function calling 一轮返回多个 tool_calls 时每个都记账）、P=3（连续空搜索耐心阈值）、k=5（SelectPages 上限）。库 API 默认每 10 个 passage 触发一次周期修复；CLI 在每篇文档结束后运行 finalize()。

测试

.venv/Scripts/python -m pytest tests/ -q   # 129 个用例，FakeLLM 驱动，无需 API key

与论文的差异（刻意取舍）

- wiki_search 无向量嵌入：以页名/别名/标签/摘要的结构化匹配为主、正文匹配回退（论文本就如此排序优先级）；未接入嵌入模型。正文分数是纯兜底——只有当某个 token 在全部结构化信号上都未命中时才计入，正文出现次数无法为结构化命中叠加分数。
- 未复现实验：不含基准评测代码（HotpotQA/MuSiQue/2Wiki/AuthTrace）。
- Agent 工具协议优先原生 function calling，端点不支持时自动降级为 JSON action：既跟上主流工具调用，又兼容任意 OpenAI 兼容端点（含不支持 tools 参数的本地模型）。降级双触发：LLM 客户端无 chat_tools 方法 / 运行时端点拒绝 tools（ToolsUnsupported）。
- 文档删除（仓库扩展）：论文未定义删除语义；llm_wiki/delete.py 实现算法 1 的逆过程——反查引用 → 删孤儿页 → LLM 重验证存活页事实 → 级联清链 → 重建索引，以结构校验零错误收尾。
- 来源身份与归档：CLI 以文件名和完整内容的 SHA-256 短摘要生成 sourceId，避免同名/中文文件名覆盖；完整原文在 sources/articles/.md 中只保存一次，各 passage digest 使用 -NNN。
- 跨页矛盾处理边界：矛盾会被检测、写入 Error Book、定向复查并作为约束注入后续编译；自动页面重写目前仅处理无来源支撑的事实。