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（工具调用预算）、P=3（连续空搜索耐心阈值）、k=5（SelectPages 上限）、每 10 篇文章触发一次 LLM 周期修复——均为默认值，可在 agent.py / compile.py 中调整。

测试

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

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

• wiki_search 无向量嵌入：以页名/别名/标签/摘要的结构化匹配为主、正文匹配回退（论文本就如此排序优先级）；未接入嵌入模型。
• 未复现实验：不含基准评测代码（HotpotQA/MuSiQue/2Wiki/AuthTrace）。
• Agent 工具协议优先原生 function calling，端点不支持时自动降级为 JSON action：既跟上主流工具调用，又兼容任意 OpenAI 兼容端点（含不支持 tools 参数的本地模型）。降级双触发：LLM 客户端无 chat_tools 方法 / 运行时端点拒绝 tools（ToolsUnsupported）。
• 文档删除（仓库扩展）：论文未定义删除语义；llm_wiki/delete.py 实现算法 1 的逆过程——反查引用 → 删孤儿页 → LLM 重验证存活页事实 → 级联清链 → 重建索引，以结构校验零错误收尾。