LLM Wiki 深度解读与接入指南
围绕一个常见误解展开：llmwiki 不是"提前把文档解析成 wiki"的 RAG，而是把 LLM 当成 wiki 编辑员的脚手架。本文先讲清楚架构，再说怎么把它当知识库接到 Claude Code 这类 agent 上替代 RAG。
1. 先纠正一个普遍误解
很多人初看 llmwiki 会以为它的工作模式是：
"把文档解析成 wiki → 下次再来搜索"
这句里有两个动作被无意识合并了。项目实际上把它们拆成了两套独立的子系统：
| 你以为的一个动作 | 项目里实际上的两个动作 |
|---|---|
| "把文档解析成 wiki" | ① 把文档解析成搜索索引 （自动、机械） ② 由 LLM 撰写出 wiki 页面（人工、编辑） |
llmwiki 确实有"提前解析" ，但解析的产物不是 wiki ，而是给 search 工具用的全文索引。真正的 wiki 是 Claude 后续一篇篇手写的 markdown。
2. 两层架构
第一层：自动解析（不经过 LLM）
完全在后台运行，FastAPI + 文件监听器干的活：
你扔进 workspace/ 的 paper.pdf
↓ pdf-oxide / Mistral / openpyxl 等解析器
documents 表里存原文 + document_pages（按页）
↓ services/chunker.py 切片
document_chunks 表（带 header_breadcrumb / page 号）
↓ FTS5 自动 trigger
chunks_fts 全文索引（porter stemming）参考代码：shared/sqlite_schema.sql。
设计上这层被刻意降级成"派生状态"------README 反复强调 "filesystem is the source of truth, SQLite is derived index" ，删了能重建（./llmwiki reindex）。
这一层是你脑子里"提前解析"那部分，只是输出形态是 SQLite，不是 markdown。
第二层：Claude 用 5 个工具"编辑" wiki
Karpathy 设计的精髓不是"AI 自动总结一切"，而是 「LLM as a wiki editor」------把 LLM 当成一个有手有眼能改文件的维基编辑员。
5 个 MCP 工具的本质就是给 Claude 配齐"编辑员的工具箱"：
| 工具 | 类比 |
|---|---|
guide |
入职须知（告诉它 wiki 的结构、写作规范、引用格式） |
search |
翻阅资料柜（FTS5 关键词 + 引用图查询） |
read |
读具体那本书的第 3--7 页 |
write |
在 /wiki/concepts/xxx.md 落笔，含 frontmatter / mermaid / 脚注引用 |
delete |
清理过时页面 |
最关键的是 guide 工具返回的指令体（mcp/tools/guide.py），它强制要求 Claude：
- 必须更新
overview.md（hub 页）和log.md（行为日志） - 写到
/wiki/concepts/（抽象概念）和/wiki/entities/（具体实体）两个目录 - 每页必须有 YAML frontmatter、mermaid/表格、
[^1]: paper.pdf, p.12这种脚注引用 - 每次 write 之后自动解析出引用图（
document_references表），下次 read 能看到 "Referenced by"
完整数据流
你的 PDF/MD/Excel
│
▼ [自动后台]
┌─────────────────────┐
│ pdf-oxide / chunker │ ← 这是 "提前解析"，但只是建搜索索引
│ → SQLite FTS5 │
└──────────┬──────────┘
│
│ ┌────────────────────────────────────────┐
│ │ 你跟 Claude 说："读 papers/ 写综述" │
│ └─────────────────┬──────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────┐
│ Claude（通过 MCP 调 5 个工具） │
│ ┌────────┐ ┌──────┐ ┌──────┐ │
│ │ guide │→│search│→│ read │ ← FTS5 │
│ └────────┘ └──────┘ └──────┘ │
│ ↓ 思考 │
│ ┌──────┐ │
│ │write │ → /wiki/concepts/attention.md
│ └──────┘ │
└──────────────────────────────────────┘
│
▼
┌────────────────────┐
│ /wiki/*.md │ ← **这才是 wiki**
│ （Claude 撰写的） │
└────────────────────┘3. 为什么 Karpathy 要这么设计
直觉模型："文档进来 → AI 自动总结成 wiki → 之后查 wiki"------这是 RAG / 自动摘要范式。
Karpathy 的反范式------不要预先全量总结，理由三点：
- 预生成会变质：你今天没问的问题，AI 总结的角度大概率不是你明天关心的方向。预总结 = 浪费 token + 大概率重写。
- wiki 的价值在交叉引用 ：单篇 PDF 自动摘要不难，难的是 "这篇里讲的 attention 和上周那篇里讲的 attention 对应同一个 entity 页吗？要不要修 5 个交叉链接？" ------ 这才是 wiki 的真正成本，按需增量维护才合算。
- LLM 是个编辑员，不是个 batch job ：你和 Claude 对话提了一个问题 → 它调 search/read → 思考 → 觉得这个洞察值得沉淀 → write 成一篇 wiki 页 → 顺手更新 overview + log。wiki 是对话的副产品，不是预处理产物。
所以 5 个工具就够了：
- 解析/索引是后台基础设施（不需要给 LLM）
- 智能（理解、组织、写作）来自 LLM 自己
- wiki 的存储是 markdown 文件（不需要数据库 API）
中文 README 那句 "LLM Wiki 本身不调用任何 LLM" 就是这个意思------这个项目本身是给 LLM 用的脚手架，不是个会自己总结的 AI 产品。
4. 把 llmwiki 当知识库接到 Agent（替代 RAG）
llmwiki 暴露给外部的接入口有 3 个层级：
| 层级 | 协议 | 文件 | 典型客户端 |
|---|---|---|---|
| ① stdio MCP | MCP over stdin/stdout | mcp/local_server.py |
Claude Desktop / Code / Cursor / Cline |
| ② Streamable HTTP MCP | MCP over HTTP（Supabase token 鉴权） | mcp/hosted.py |
任何 MCP HTTP client / 远程 agent |
| ③ FastAPI REST | 普通 HTTP（Web 前端用的，没有官方对外承诺） | api/routes/*.py |
hack 兜底 |
90% 场景应该走 ① 或 ②。
4.1 整体流程（Claude Code 本机场景）
┌──────────────────────────────────────────────────────────────┐
│ 一次性：把 llmwiki 注册为 Claude Code 的 MCP 服务 │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 每次开会话：第一句话定调（让它读 guide） │
└──────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────┴─────────────────────┐
▼ ▼
「冷启动期」 「稳态期」
你说："读这批 PDF，写 wiki" 你说："X 是什么 / Y 怎么做"
Claude: search → read → write Claude: search → read
产出: wiki/concepts/*.md 命中: 已写好的 wiki 页
（这一步才真正替代 RAG）4.2 Step 1 --- 注册 MCP（一次性）
bash
cd /Users/caicongyang/IdeaProjects/github/hackthon/llmwiki
./llmwiki init ./demo-workspace
claude mcp add llmwiki-demo \
/Users/caicongyang/IdeaProjects/github/hackthon/llmwiki/llmwiki \
mcp /Users/caicongyang/IdeaProjects/github/hackthon/llmwiki/demo-workspace
claude mcp list # 验证能看到 llmwiki-demo往 demo-workspace/ 扔 PDF/MD/Excel，文件监听器会自动建索引（这一步在后台，不经 Claude）。
Cursor 配
~/.cursor/mcp.json；Claude Desktop 跑./llmwiki mcp-config ./demo-workspace拿 JSON 片段。
4.3 Step 2 --- 会话第一句话（定调）
这一步最关键，决定 agent 走"RAG-like 查询模式"还是"维基编辑模式"：
| 想要的行为 | 第一句话模板 |
|---|---|
| 用知识库回答问题（替代 RAG） | "Use the llmwiki-demo MCP. Call guide first, then answer my questions by searching the wiki first, falling back to source documents only if the wiki is incomplete." |
| 边查边沉淀（冷启动建库） | "Use llmwiki-demo. Call guide, then ingest the PDFs in papers/: read them, write concept and entity pages under /wiki/, update overview and log." |
| 维护已有 wiki（lint） | "Use llmwiki-demo. Call guide, then run a lint pass: find uncited sources, stale pages, missing cross-references." |
为什么强调 "Call guide first" ：guide 工具会把 188 行的工作流指令灌进 Claude 的上下文（包括 frontmatter 格式、引用规范、必须更新 overview/log 等）。不调 guide，行为会退化成普通 grep + 写 markdown。
4.4 实际跑起来长什么样
你说："总结一下这几篇论文的核心贡献，建个 attention 概念页。"
Claude 内部自动走链：
1. guide() → 拿到工作流规范
2. search(mode="list", path="/papers/**") → 看有哪些文件
3. read(path="papers/attention.pdf", pages="1-5") → 读摘要
4. read(path="papers/attention.pdf", pages="6-15") → 读细节
5. read(path="papers/scaling.pdf", pages="1-3")
6. ... 迭代 ...
7. write(path="/wiki/concepts/", title="attention.md",
content="---\ntitle: Attention\n...\n---\n\n## 概念...\n[^1]: attention.pdf, p.3")
8. write(path="/wiki/log.md", append=True,
content="## [2026-05-23] ingest | Transformer papers ...")
9. write(path="/wiki/overview.md", str_replace=...) → 更新源数量下次问 "什么是 multi-head attention" ------它会先 search(mode="search", path="/wiki/**", query="multi-head") 命中你上一轮 Claude 自己写的 attention.md，直接给你引用了脚注的精炼答案。这就是 llmwiki 替代 RAG 的关键时刻。
4.5 "边查边写"的两个循环与写入语义
命名说明：前文为简洁把写操作统称
write。实际 MCP 把"写"拆成三个独立原语------create（新建页）、edit（页内精确查找替换）、append（页尾追加），再加delete。下面用真实工具名。
llmwiki 的日常使用，就是两个循环在交替转：
循环 A --- Ingest（你加新源 → Claude 写）
read(新源)
↓ 和你确认要点
create/edit /wiki/concepts/*.md （抽象概念页）
create/edit /wiki/entities/*.md （具体实体页）
edit /wiki/overview.md （更新源数量 + 关键发现）
append /wiki/log.md （记一条 ingest）一个源通常牵动 5--15 个页面 ：新建几页 + 回改受它影响的旧页。这正是 §3 说的"wiki 的真正成本在交叉引用维护"。
循环 B --- Q&A（你提问 → Claude 边查边补）
search(mode="search", path="/wiki/**", query=...) ← 先查已沉淀的 wiki
├─ 命中且够用 → 直接答（带脚注）
└─ 没命中 / 不全 → read 原始源补齐
↓ 若是值得留存的新结论
create /wiki/concepts/新页.md ← 答完顺手落盘
append /wiki/log.md（记一条 query）关键在最后一步：答完把新洞察沉淀回 wiki，下次同类问题直接命中 wiki、不再翻原文------这就是 §5 "retrieve-generate-curate-recall" 复利的落地动作。
写入语义（避免误解：写 ≠ 重新生成整个 wiki）
| 性质 | 说明 |
|---|---|
| 落盘对象 | 只写 /wiki/*.md（真实文件，先写盘再更新索引）；根目录 / 下的源只读、永不被改 |
| 粒度 | 按页增量 。一次 Q&A 可能只 edit 一页 + append 一条 log，其余页原样不动 |
| 不覆盖 | create 命中已存在的页会被拒绝 ，需显式 overwrite=true 才整页推翻；edit / append 都是局部改 |
| 一致性 | 每次写完，返回里会列出"哪些页引用了刚改的页"，据此回改 → 配合 search(mode="references") 查引用图 |
实战提示 ：本地是 FTS5 关键词搜索，中文长 query 命中差。例如查 积分 不足 充值 可能 0 命中 ，拆成 积分 反而命中 7 条 （同时命中已写好的 concepts/credits-and-billing.md 整合页 + 原始 FAQ 汇总.md）。查 wiki 优先于查源，是这套模式省 token 的关键。
5. 和传统 RAG 的本质差异
| 阶段 | 传统 RAG | llmwiki 模式 |
|---|---|---|
| 检索决策权 | 检索器（用户 query 直接 embedding） | agent （Claude 决定查 /wiki/** 还是 /、关键词怎么拆、迭代几次） |
| 检索粒度 | top-k chunk（500 tokens 一坨原文） | 先看 wiki 概要页 → 不够再 read 原 PDF 指定 page 范围 |
| 检索算法 | 向量相似度 | SQLite FTS5（porter stemming 关键词） |
| 命中的是什么 | 原始 chunk（上下文可能支离破碎） | Claude 之前写过的整合页 + 脚注回原 PDF 页码 |
| 复用成本 | 每次问都重跑 retrieval | 答过的问题沉淀成 wiki，下次直接命中 |
| 写入回路 | 没有（只读） | 有，agent 答完顺手把新洞察落盘 |
范式差异 ：传统 RAG 是 「retrieve-then-generate」一次性的 ；llmwiki 是 「retrieve-generate-curate-recall」长期复利的。
tools/search.py 里 mode 选项是 list / search / references------没有自动语义检索 。这是有意为之：检索策略让 LLM 自己决定，而不是预先 embedding 兜底。
6. 必须注意的 4 个坑
-
FTS5 是关键词搜索，不是向量搜索。 中文用 porter 分词（按空格/标点切），中文长 query 命中率比英文差。需要语义搜索则走 hosted 模式（PGroonga）或自己接
voyage/turbopuffer，本地默认没有。 -
冷启动很慢，要先建一轮 wiki。 第一次接入空 workspace 时 agent 没东西可查；让它先做一次 "ingest" 把核心资料写成 wiki 再切到查询模式，复利才会启动。
-
每个 workspace 一个 MCP 条目。 不要把所有项目堆在同一个文件夹下让 Claude 自己挑------会污染上下文。一个研究主题 = 一个
llmwiki init+ 一个claude mcp add。 -
agent 的 tool-call 是花 token 的。 平均一次回答会调 3--8 次工具，相比 RAG 的"一次性塞 chunk"成本更高，但换来 wiki 沉淀。所以 适合长期项目 （反复回到同一批资料），不适合一次性问答（那种场景纯 RAG 更便宜）。
7. 可直接复制的开工模板
bash
# 0. 进入仓库根
cd /Users/caicongyang/IdeaProjects/github/hackthon/llmwiki
# 1. 建库
./llmwiki init ./demo-workspace
# 2. 把资料拖进 demo-workspace/（任意子目录）
# 3. 注册到 Claude Code
claude mcp add llmwiki-demo \
/Users/caicongyang/IdeaProjects/github/hackthon/llmwiki/llmwiki \
mcp /Users/caicongyang/IdeaProjects/github/hackthon/llmwiki/demo-workspace
# 4. 启 Web 看效果（可选）
./llmwiki serve ./demo-workspace &进入 Claude Code 会话，第一句：
Use the
llmwiki-demoMCP server. Callguidefirst.Phase 1 (ingest) : read all PDFs/MDs under
papers/, create concept pages under/wiki/concepts/and entity pages under/wiki/entities/, update/wiki/overview.mdand append to/wiki/log.mdper the guide.Phase 2 (Q&A) : when I ask questions, search
/wiki/**first, only fall back to raw sources if the wiki is incomplete; if you find a new insight worth keeping, write it as a new wiki page before answering.
这套提示词进去之后，Claude Code 这个 agent 就把 llmwiki 当成自己的长期记忆 + 检索器了，行为上就是"知识库替代 RAG"。
8. 一句话总结
- 架构本质 ：两段独立的事------① 解析→FTS5 索引（机械、预先、给 search 用） ② Claude 边对话边写 →
wiki/*.md（增量、按需、LLM 当编辑员）。 - Karpathy 的精髓 ：LLM 是 wiki 的作者，不是 wiki 的运行时 。所以暴露的是
guide/search/read/write/delete这 5 个文件编辑级原语，而不是generate_wiki_from_folder()黑盒。 - 替代 RAG 的方式 ：把 llmwiki 注册成 MCP server，agent 自己用 search/read 拉知识，自己用 write 把答案沉淀回 wiki，用复利换 token 成本。