LLM Wiki 范式实战：给任何开源项目建可信架构 wiki

岚叔（@LufzzLiz）看到 Karpathy 2026 年初提出的 LLM Wiki 范式后，4 天后建了第一个 wiki，6 天后第二个。最近一段时间陆续做出 7 个 wiki 项目。

为什么花时间做 wiki？

传统 README、Notion、飞书文档不够用吗？

LLM 让知识管理的根本矛盾松动了。过去几十年所有"个人知识库"运动都败在同一件事上：维护成本随规模超线性增长，最后人都放弃了。

RAG 看起来解决了，但它每次查询都重新检索、重新合成，知识不积累、不复利。Karpathy 提出的新范式：让 LLM 增量维护一个持久化的 markdown wiki。交叉引用预建好，矛盾预标注，合成预完成。人负责策展和提问，LLM 负责所有摘要、链接、归档。

三层架构：raw / wiki / schema

所有 wiki 遵循同一个抽象：

raw/         # 原始内容（源码、PDF、网页快照），不可变，LLM 只读不改
wiki/        # LLM 维护的结构化笔记（概念页、实体页、合成页）
schema/      # 人机共建的规则（CLAUDE.md / SCHEMA.md），定义页面格式、标签、工作流

raw 是真相的锚，任何时候有疑问都能回溯到原文
wiki 是被"编译"过的知识，交叉引用、对比、矛盾都已经预先标注好
schema 是人对 LLM 的"教学大纲"，告诉 LLM 怎么命名、怎么打标签、什么时候创建新页

两种范式

范式	适用	目录结构
个人知识库（Karpathy 原版）	阅读笔记、跨领域沉淀	5 层：raw / sources / entities / concepts / syntheses
代码仓库 wiki（简化版）	跟踪开源项目架构	3 层：concepts / entities / changelog

共同骨架：

index.md：给 LLM 看的扁平导航，每个页面一行摘要
log.md：所有操作的追加日志，跨会话连续性的关键
SCHEMA.md 或 CLAUDE.md：页面格式、标签体系、操作规则
[[wikilinks]]：Obsidian 兼容的双向链接

三大核心操作

Ingest（导入）：把一份资料拆成 5-15 个 wiki 页面：

完整阅读原文（不是只看标题）
与人讨论要点（确认理解对了）
在 index 里搜重，避免重复创建
原文存到 raw/（永不修改）
创建 sources/ 摘要页，标 reliability（peer-reviewed / official / expert / social / unknown）
必须读相关页面全文再决定怎么更新（禁止只看 index 摘要就改）
提取 entities、concepts，必要时创建 syntheses
同步 index.md + log.md

Query（查询）：综合多页回答问题，够"重"就归档：

答案综合 ≥3 来源、跨领域对比、揭示新关联 → 自动归档为 synthesis

Lint（健康检查）：9 类问题自动扫描：

矛盾点（同一主题不同结论）/ 过时页 / 孤儿页 / 悬空链接 / 标签近义 / 摘要准确性 / 未解决问题汇总…

贯穿三大操作的硬规则：所有页面的结论必须能追溯到源码 文件:行号 或原文 URL；做不到，宁可不写。这条规则是 wiki 区别于"AI 自由总结"的核心。

用 Claude Code Skill 落地

把规则做成 Claude Code skill 后，触发变得很轻：

~/.claude/skills/wiki/
  SKILL.md         # 薄路由层（触发词 + 命令决策树 + 新建 wiki 引导）
~/wiki/
  CLAUDE.md        # 厚 schema（页面格式、标签、ingest 工作流的权威规则）

命令体系：/wiki add /wiki ingest /wiki query /wiki lint /wiki status /wiki deprecate /wiki retract /wiki merge。也支持自然语言，说"把这个加到 wiki 里"它就懂。

跨会话连续性靠每次新会话固定读三个文件：CLAUDE.md → index.md → log.md 最近 10 条。

实践：五步教程

以 x-algorithm-wiki 为案例（34 页 / 6,800 行）。

Step 1 · 立项 + 锁源码

# 拉源码，锁定 commit 或 tag（避免后续 ingest 与源码漂移）
git clone https://github.com/xai-org/x-algorithm /tmp/x-algorithm
cd /tmp/x-algorithm && git checkout 0bfc279

# 新建 wiki 仓库 + 复制 schema 模板
mkdir ~/code/x-algorithm-wiki && cd $_
git init && mkdir -p concepts entities changelog
cp ~/code/lanshu-wiki-skill/schema/wiki-code-repo-SCHEMA.md ./SCHEMA.md
echo "# Wiki Index" > index.md && echo "# Wiki Log" > log.md

打开 SCHEMA.md，填两个 ⚠️ 字段：Domain 描述（项目 + commit + 覆盖的核心子系统）+ Tag Taxonomy（项目特定的标签体系）。

Step 2 · 让 LLM 通读源码产首批页

读 SCHEMA.md，按它的规则给 <源码绝对路径> 做架构 wiki。从最核心的 5 个模块开始。硬规则：每个结论必须带 文件:行号 锚点，覆盖不到的不写。

一次产出 10-20 页 concept + entity，总计 2,000-5,000 行。核心纪律是「结论可追溯」。

Step 3 · Lint 全量核对

每写完一批就 /wiki lint：

悬空 [[wikilink]] / frontmatter 缺字段 / 标签近义重复 → 工具自动扫
随机抽 2-3 页对照源码全文核验 → 发现隐性错误的唯一办法
发现 wiki 结论与官方文档冲突 → 写进 changelog 而不是悄悄改（保留审计痕迹）

x-algorithm-wiki 当时核 29 页 482 个锚点，发现 3 处出入，全部进 changelog。

Step 4 · 双层导览 ⭐ 关键升级

加 guide/ 目录，按「技术页 + 白话页配对」做：

技术页（concepts/）	白话页（guide/）
`system-architecture.md`（源码级）	`how-it-works.md`（类比讲清楚五大组件，不写代码）
`candidate-selection.md`（Selector trait + TopKScore）	`how-posts-are-picked.md`（选秀收尾类比）

白话页同样遵守可追溯规则：每条核心结论在白话页末尾的「出处」表里指到对应技术页 + 源码锚点。

Step 5 · 持续打磨

定期 lint：随项目升级修锚点失效、补术语解释
读者反馈回流：用户问的好问题立刻补进 faq，新话题就开新页

踩过的坑

同概念多种命名是头号杀手：创建新页前先 grep index.md 找近义页
不读全文就改是二号杀手：schema 强制"更新前必读全文"
标签每月 lint 一次：不去重的话，一年后 30 个标签里 10 个语义重叠
changelog + log.md 是审计轨：每次操作追加，问题溯源不慌

边界

规模上限 ~2000 页：index.md 要装得下所有页面摘要供 LLM 一次性读完。超过 ~1000 页就要考虑按领域拆子 wiki
多人并发协作还粗糙：当前 skill 主打单人/小团队场景
Token 成本不可忽视：让 LLM 通读 5 万行源码做首批 ingest，一次约 100k-500k input token（ $0.3-1.5），一个中等项目 wiki 全周期$ 5-30 量级

致谢

核心思想来自 Andrej Karpathy 2026 年 4 月发表的 LLM Wiki gist（只有 75 行）。三层架构、三大操作、index + log 的设计、"知识应该编译而非每次解释执行"的论证，全部来自那 75 行。

Vannevar Bush 1945 年的 As We May Think 提出了 Memex：个人化、人工策展、文档之间充满"联想路径"的桌面知识库。他给后人留了一个未解问题："谁来维护这些关联？"这个问题压垮了之后 80 年所有的个人知识库尝试。Karpathy 给出了答案：让 LLM 来做维护。