llm-wiki

LLM Wiki — Karpathy 知识库模式

实验性技能 — 持续迭代中。 作者：Lewis Liu（[email protected]）· 灵感来自 Karpathy 的 llm-wiki Gist

核心理念

不同于 RAG（每次查询都重新检索原始文档），大模型会将原始资料编译成一个持久、相互链接的维基。每次摄取、查询、检查和审计都会让维基更加丰富。知识不断累积——人类则通过结构化的反馈渠道参与其中，而不是依赖容易丢失的临时纠正。

• 你负责：搜集原始资料、提出好问题、指引方向，以及针对 AI 出错之处提交反馈。
• 大模型负责：所有撰写、交叉引用、归档、记录，以及根据你的反馈采取行动。

维基是一个持续演进的产物，包含五种操作——compile、ingest、query、lint、audit。每次会话都从阅读 CLAUDE.md 和 wiki/index.md 开始。

目录结构

<wiki-root>/
├── CLAUDE.md          ← Schema: scope, conventions, current articles, gaps
├── log/               ← Per-day operation log (one file per day)
│   ├── 20260409.md
│   └── 20260410.md
├── audit/             ← Human feedback inbox (one file per comment)
│   ├── 20260409-143022-claude-code-size.md
│   └── resolved/      ← Processed feedback, archived with resolution notes
├── raw/               ← Immutable source documents (LLM reads, never writes)
│   ├── articles/
│   ├── papers/
│   ├── notes/
│   └── refs/          ← Pointer files for large binaries kept outside raw/
├── wiki/              ← LLM-generated knowledge (LLM writes, you read)
│   ├── index.md       ← Master catalog — every page, structured by category
│   ├── concepts/      ← Concept/topic pages (split into subfolders when >1200 words)
│   ├── entities/      ← People, tools, papers, organizations
│   └── summaries/     ← Per-source summary pages
└── outputs/
    └── queries/       ← Query answers (promote durable ones to wiki/)

CLAUDE.md 是架构文件——最重要的配置文件。它会告诉大模型维基的范围、命名约定、当前文章列表、待解决的问题和研究空白。请阅读 references/schema-guide.md，了解其中应包含的内容。每次会话开始时都要阅读此文件。

核心原则

以下四条规则适用于所有内容。如果未来的指令与其中任何一条冲突，请在采取行动前告知用户。

1. 分而治之

单个概念页面绝不应试图从头到尾涵盖一个复杂主题。目标：每页 400–1200 字。如果某个主题会超出这个范围：

• 创建一个子文件夹：wiki/concepts/<topic>/
• 在 wiki/concepts/<topic>/index.md 中创建一个简短的索引页面——包含定义、子页面列表和每页的一句话摘要
• 将每个方面分别放入一个文件：wiki/concepts/<topic>/<aspect>.md
• 在 wiki/index.md 中通过缩进的项目符号展示层级结构

示例结构（摘自一个真实的维基）：

wiki/tech/claude-code/
├── index.md                         (overview + links to sub-pages)
├── Claude_Code_Architecture.md
├── Claude_Code_Agent_Framework.md
├── Claude_Code_Bridge_System.md
├── Claude_Code_Query_Engine.md
├── Claude_Code_Skills_Plugins.md
├── Claude_Code_State_Management.md
└── Claude_Code_Tool_System.md

一个包含所有七个方面的冗长文件既难以阅读，也无法建立链接。七个主题明确的文件加一个索引页面，能提供导航、按需阅读、清晰的反向链接，以及小范围的审计目标。

2. 图表使用 Mermaid，公式使用 KaTeX

• 任何流程图、时序图、层级图或状态图都必须用 mermaid 编写——绝不使用 ASCII 艺术图。ASCII 方框很快就会变得过时，而且无法添加注释。

  ```mermaid
  flowchart LR
      A[raw/article.md] --> B[summary]
      B --> C[concept page]
      C --> D[index.md]
  ```
  

• 任何公式都必须用 KaTeX 编写：行内公式 $f(x) = \sum_i w_i x_i$，或块级公式 $$...$$。

两者都可以在网页查看器（服务端 KaTeX、客户端 mermaid）和 Obsidian 的默认设置中渲染。

3. 原始文件策略

小型文本资料（md、txt、小型 pdf、小型图片）→ 复制到 raw/<subfolder>/。

大型二进制文件（视频、模型权重、安装程序、数据集、大于 10 MB 的大型 PDF）→ 不要复制。改为：

• 在 raw/refs/<slug>.md 创建一个指针文件，内容如下：

  ---
  kind: ref
  external_path: /Volumes/external/models/llama-3-70b/
  size: ~140 GB
  ---
  

  然后简要说明文件是什么，以及它对这个维基为何重要。
• 维基页面引用 [[raw/refs/<slug>]]，与引用其他来源的方式完全相同。

这样可以让维基仓库便于使用 git 管理，并保持可移植性。

4. 审计是人类提供反馈的渠道

维基由 AI 撰写，有时会出错。原始资料由人类撰写，彼此之间也可能相互矛盾。audit/ 目录是人类纠正两者的方式，可避免反馈在聊天记录中丢失。

• 人类通过 Obsidian 插件或网页查看器提交反馈。每条反馈都是 audit/ 中的一个文件，包含 YAML 前置元数据（锚点、目标、严重性）和 Markdown 正文。
• AI 必须定期运行 audit 操作——绝不能默默忽略 audit/*.md 文件。
• 处理反馈后，将文件移至 audit/resolved/，追加一个 # Resolution 部分，并在 log/YYYYMMDD.md 中记录日志。

完整的文件格式和处理工作流，请参阅 references/audit-guide.md。

---

五种操作

对维基执行的每项操作都属于这五种之一。每项操作都会在当天的日志文件（log/YYYYMMDD.md）中追加一条记录。

1. compile

根据现有的 raw/ 材料（重新）整理 wiki 内容，包括拆分过长的页面、合并近似重复的页面，以及重建 index.md。

运行时机：完成一批大量导入后；现有页面超过 1200 个单词时；index.md 不再反映实际情况时；或用户说“清理 wiki”时。

步骤：

1. 阅读 CLAUDE.md、wiki/index.md 和目标子树中的每个文件。
2. 对于每个超过约 1200 个单词的页面：规划将其拆分到 concepts/<topic>/，包含一个索引和若干子页面。写入前先与用户确认计划。
3. 对于每对近似重复的页面：提出合并方案。确认后再重写。
4. 重新生成 wiki/index.md，确保每个页面恰好列出一次。
5. 记录：## [HH:MM] compile | <所做的工作 — 涉及的文件、拆分、合并>

2. ingest

添加一个新来源。一个来源通常会涉及 5–15 个 wiki 页面。

步骤：

1. 将来源保存到合适的子文件夹：
   • 网页文章 → raw/articles/<slug>.md
   • 论文 → raw/papers/<slug>.md（大型 PDF 提取出的文本）
   • 笔记 → raw/notes/<slug>.md
   • 大型二进制文件 → raw/refs/<slug>.md 指针文件（见 raw 文件策略）
2. 完整阅读来源内容。
3. 创建 wiki/summaries/<slug>.md（200–400 个单词，提炼关键要点，而非改写；见 references/article-guide.md）。
4. 在 wiki/concepts/ 中创建或更新相关概念页面。遵循分而治之原则：如果概念页面会超过 1200 个单词，就拆分，而不是硬塞在一起。
5. 对于来源中提及的任何新人物 / 工具 / 论文 / 组织，在 wiki/entities/ 中创建或更新实体页面。
6. 更新 wiki/index.md，将新页面列入合适的类别下。
7. 记录：## [HH:MM] ingest | <slug> — <一行描述>（涉及 N 个页面）

3. query

回答基于 wiki 内容的问题，而非一般知识问题。

步骤：

1. 阅读 wiki/index.md。按类别查找相关页面。
2. 完整阅读确定的页面；沿着 wiki 链接再跟进一层。
3. 如果 wiki 中的材料不足，请如实说明，并建议接下来可以导入什么，而不要编造内容。
4. 综合答案，并使用 [[Page Name]] 在文中引用页面。
5. 保存到 outputs/queries/<YYYY-MM-DD>-<question-slug>.md。
6. 如果答案具有长期价值（例如比较、分析或新的综合结论），则将整理后的版本提升到 wiki/concepts/，并添加到 index.md。
7. 记录：## [HH:MM] query | <question-slug>（如果已提升，则另起一行记录 ## [HH:MM] promote | ...）。

4. lint

健康检查。运行：

python3 scripts/lint_wiki.py <wiki-root>

脚本会报告：

• 失效的 wiki 链接 — [[Target]]，但 Target.md 不存在
• 孤立页面 — 没有入站 wiki 链接的页面
• 缺少索引条目 — 未列入 wiki/index.md 的页面
• 被频繁链接但缺失的页面 — [[X]] 被引用 3 次或以上，但没有对应页面
• log/ 结构 — log/ 中的多余文件或文件名不正确
• audit/ 结构 — audit/*.md 中格式错误的 YAML frontmatter
• 审计目标解析 — 每个未关闭审计的 target 文件都必须存在

对于每个问题，提出修复方案，与用户确认后再应用。记录：## [HH:MM] lint | 发现 <N> 个问题，已修复 <M> 个。

5. audit

处理来自 audit/ 的人工反馈。

步骤：

1. 运行 python3 scripts/audit_review.py <wiki-root> --open 获取按组归类的列表。
2. 对每条待处理的审计，阅读文件。使用 anchor_before / anchor_text / anchor_after 窗口，在目标文件中定位准确范围（行号可能已偏移）。
3. 决定采取的操作：
   • 接受：将更正应用到目标文件。
   • 部分接受：应用合理的部分，并在处理结果中说明其余部分。
   • 拒绝：在处理结果中说明原因——反馈可能基于对范围的误读，或与矛盾的来源有关。
   • 暂缓：将其添加到 CLAUDE.md 的“开放研究问题”中，并在审计文件中添加评论，保留该文件。
4. 对已应用的审计，在审计文件末尾追加 # Resolution 部分：

   # Resolution
   
   2026-04-10 · accepted.
   Fixed the file count (was "~1,900", corrected to "~1,800" per commit abc123).
   Updated: tech/Claude_Code.md lines 47–48.
   

5. 将文件从 audit/ 移至 audit/resolved/。文件名保持不变。
6. 为每条已解决的审计记录日志：

   ## [HH:MM] audit | resolved 20260409-143022-a1b2 — <one-line what>
   

7. 切勿删除审计文件。即使是被拒绝的审计，也要连同拒绝理由写入处理结果部分，一并移至 resolved/——这是有价值的历史记录。

完整的审计文件格式请参阅 references/audit-guide.md。

---

工具

工具	用途
Obsidian	用于浏览 Wiki 的 IDE；图谱视图可显示各项内容之间的关联
plugins/obsidian-audit/	Obsidian 插件 — 选择文本 → 添加反馈 → 写入 audit/
web/	本地 Node.js 服务 — 预览已渲染 Mermaid 和数学公式的 Wiki；选择内容 → 反馈 → audit/
scripts/scaffold.py	初始化新的 Wiki 目录树
scripts/lint_wiki.py	七轮健康检查
scripts/audit_review.py	按目标文件归类待处理/已解决的审计
qmd	可选的本地语义搜索（超过 100 页时很有用）

Obsidian 插件和 Web 查看器都会以相同格式并使用相同的锚点算法写入审计文件，因此无论通过哪一方提交反馈，都可以通过任一方处理。

开始创建新的 Wiki

python3 scripts/scaffold.py <wiki-root> "<Topic Title>"

这会创建完整的目录树（包括 log/<today>.md、audit/、audit/resolved/）、一个基于新模板的空白 CLAUDE.md，以及一个采用推荐分类布局的空白 wiki/index.md。

搭建完成后：

1. 填写 CLAUDE.md — 定义范围、命名规范和初始研究问题。
2. 开始导入来源。
3. 提出问题以逐步构建 outputs/queries/；将经久适用的答案提升为正式内容。
4. 定期运行 lint。
5. 累积新的反馈时运行 audit。

wiki/index.md 格式

LLM 会在每次编译时重建 index.md，并在每次导入时更新它。格式如下：

# Index — <Topic>

> One-sentence scope of the wiki.

## 🔖 Navigation
- [[#Concepts]] · [[#Entities]] · [[#Summaries]] · [[#Open Questions]]

## Concepts
### <Category A>
- [[concepts/Foo]] — one-line summary
- [[concepts/Bar/index|Bar]] — (folder-split) one-line summary
    - [[concepts/Bar/aspect-1]] — ...
    - [[concepts/Bar/aspect-2]] — ...

### <Category B>
- ...

## Entities
- [[entities/Andrej Karpathy]] — AI researcher, author of the llm-wiki pattern

## Summaries (chronological)
- 2026-04-09 — [[summaries/llm-wiki-gist]] — Karpathy's original Gist

## Open Questions
- Q1: ...

规则：

• 每个 Wiki 页面都必须在 index.md 中恰好出现一次。lint 会强制检查这一点。
• 按文件夹拆分的概念通过缩进项目符号展示层级。
• index.md 和 CLAUDE.md 是 AI 在会话开始时会读取的文件。

log/ 格式

完整详情请参阅 references/log-guide.md。最低要求：

• 每天一个文件：log/YYYYMMDD.md
• H1 为日期；每条记录使用 H2，格式为 ## [HH:MM] <op> | <one-line description>
• 操作：compile、ingest、query、lint、audit、promote、split、scaffold

快速检索历史记录：grep -rh "^## \[" log/ | tail -20。

使用场景

• 深入研究 — 数周内阅读某个主题的论文或文章；Wiki 会随着你的理解不断演进，审计记录则可防止 AI 错误悄然累积
• 个人 Wiki — 将日记、笔记和想法汇编成个人百科全书；之后对任何有异议的内容发表评论，AI 会进行更正
• 团队知识库 — 汇集 Slack 讨论串、会议记录和文档；团队成员通过 Web 查看器提交更正
• 阅读伴侣 — 随阅读进度逐章归档书籍内容；最终构建出丰富的配套 Wiki

参考资料

• references/schema-guide.md — 在 CLAUDE.md 中应填写的内容
• references/article-guide.md — 如何编写优质 Wiki 文章（长度、维基链接、mermaid、数学公式、分而治之）
• references/log-guide.md — log/ 文件夹约定
• references/audit-guide.md — 审计文件格式、锚点策略、处理工作流
• references/tooling-tips.md — Obsidian 设置、Web Clipper、qmd、插件 + 网页安装