LLM Wiki — 卡帕蒂知识库模式

实验性技能 — 正在迭代中。

作者：Lewis Liu（lylewis@outlook.com）· 灵感来自 [Karpathy 的 llm-wiki Gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)

核心理念

与传统的 RAG（每次查询时重新检索原始文档）不同，LLM 不是重复检索，而是将原始资料编译为一个持久、相互链接的知识库。每一次的导入、查询、校验和审计操作都会让知识库变得更丰富。知识持续积累——而人类通过结构化的反馈渠道参与其中，而非依赖临时、易丢失的纠错。

• 你负责：获取原始材料、提出高质量问题、引导方向、对 AI 出错之处提交反馈。
• LLM 负责：所有写作、交叉引用、归档、账目管理以及响应你的反馈。

该知识库是一个动态演进的产物，包含五种操作：compile、ingest、query、lint、audit。每次会话开始前，需先阅读 CLAUDE.md 和 wiki/index.md。

目录结构

<wiki-root>/
├── CLAUDE.md          ← 模式文件：定义范围、命名规范、当前文章列表、研究空白
├── log/               ← 每日操作日志（每天一个文件）
│   ├── 20260409.md
│   └── 20260410.md
├── audit/             ← 人工反馈收件箱（每条反馈一个文件）
│   ├── 20260409-143022-claude-code-size.md
│   └── resolved/      ← 已处理的反馈，归档并附上解决说明
├── raw/               ← 不可变的原始文档（LLM 只读，不写入）
│   ├── articles/
│   ├── papers/
│   ├── notes/
│   └── refs/          ← 大型二进制文件的指针文件，存放于 raw/ 外部
├── wiki/              ← LLM 生成的知识内容（LLM 写，你读）
│   ├── index.md       ← 主目录 —— 所有页面按类别组织
│   ├── concepts/      ← 概念/主题页面（超过 1200 字时拆分为子文件夹）
│   ├── entities/      ← 人物、工具、论文、组织等实体
│   └── summaries/     ← 每个原始来源的摘要页
└── outputs/
    └── queries/       ← 查询回答（可持久化的内容可提升至 wiki/）

CLAUDE.md 是模式文件——最重要的配置项。它告诉 LLM 知识库的范围、命名约定、当前文章列表、待解决问题和研究空白。每次会话开始前都应阅读此文件。详见 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                         （概述 + 子页面链接）
├── 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 箱形图会迅速过时，且无法注释。

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/<子文件夹>/。
• 大型二进制文件（视频、模型权重、安装包、数据集、大于 10MB 的 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 正文。
• LLM 必须定期运行 audit 操作 —— 绝不能静默忽略 audit/*.md 文件。
• 当反馈被采纳后，文件移入 audit/resolved/，并附加 # Resolution 部分，同时在 log/YYYYMMDD.md 中记录日志。

详见 references/audit-guide.md 中的完整文件格式与处理流程。

五大操作

对知识库的所有操作均属于以下五种之一。每次操作都会在当天的日志文件（log/YYYYMMDD.md）中追加一条记录。

1. compile

根据现有 raw/ 材料重构知识库内容 —— 包括拆分过大的页面、合并近似重复内容、重建 index.md。

何时运行：在大批量导入后、某页面超过 1200 字、index.md 与实际不符，或用户要求“清理知识库”时。

步骤：

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 文件策略）

1. 完整阅读该来源。
2. 创建 wiki/summaries/<slug>.md（200–400 字 —— 关键收获，非全文重写；参见 references/article-guide.md）。
3. 创建或更新 wiki/concepts/ 中的相关概念页面。遵循分而治之原则：若概念页面将超过 1200 字，则应拆分而非强行塞入。
4. 为任何新提及的人物 / 工具 / 论文 / 组织创建或更新 wiki/entities/ 中的实体页面。
5. 更新 wiki/index.md，使新页面出现在正确分类下。
6. 记录日志：## [HH:MM] ingest | <slug> — <一句话描述> (影响 N 个页面)

3. query

基于 wiki 内容回答问题，不依赖通用知识。

步骤：

1. 阅读 wiki/index.md。按类别扫描相关页面。
2. 完整阅读已识别的页面；跟随一级内部链接。
3. 若 wiki 中材料不足，应如实说明，并建议下一步应摄入的内容，而非自行编造。
4. 整合答案，使用 [[页面名称]] 格式在文中引用来源。
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>

脚本报告以下问题：

• 失效的 wikilink — [[目标]] 所指向的 目标.md 文件不存在
• 孤立页面 — 无任何反向链接的页面
• 缺失索引条目 — 页面未列在 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 “待研究问题”部分，保留在 audit/ 并添加注释。

1. 对已应用的审计，在审计文件末尾追加 # Resolution 部分：

   # Resolution

   2026-04-10 · accepted.
   修正了文件数量（原为“~1,900”，根据提交 abc123 更正为“~1,800”）。
   已更新：tech/Claude_Code.md 第 47–48 行。

1. 将文件从 audit/ 移动至 audit/resolved/。文件名保持不变。
2. 每个已解决的审计记录一条日志：

   ## [HH:MM] audit | resolved 20260409-143022-a1b2 — <一句话说明>

1. 从不删除审计文件。被拒绝的文件也进入 resolved/，并在其回复部分保留拒绝理由 —— 这是宝贵的历史记录。

详见 references/audit-guide.md 了解完整的审计文件格式。

工具

Obsidian 插件与网页预览器均以相同格式和相同的锚点算法生成审计文件，因此从任一端提交的反馈均可由任一端处理。

启动新 wiki

python3 scripts/scaffold.py <wiki-root> "<主题标题>"

创建完整目录结构（含 log/<今天>.md、audit/、audit/resolved/），基于新模板生成空白的 CLAUDE.md 和空白的 wiki/index.md，并包含推荐的分类布局。

初始化后：

1. 填写 CLAUDE.md —— 明确范围、命名规范、初始研究问题。
2. 开始摄入来源。
3. 提出问题以构建 outputs/queries/；将持久性答案提升至 wiki/concepts/。
4. 定期运行 lint。
5. 当有新反馈积累时，运行 audit。

wiki/index.md 格式

LLM 在每次编译时会重建 index.md，且每次摄入都会触及其更新。格式：

索引 — <主题>

本维基的简要范围说明。

🔖 导航

• [[#概念]] · [[#实体]] · [[#摘要]] · [[#开放问题]]

概念

<类别 A>

• [[concepts/Foo]] — 一句话摘要
• [[concepts/Bar/index|Bar]] — （文件夹拆分）一句话摘要

- [[concepts/Bar/aspect-1]] — ...

- [[concepts/Bar/aspect-2]] — ...

<类别 B>

• ...

实体

• [[entities/Andrej Karpathy]] — AI 研究员，llm-wiki 模式的提出者

摘要（按时间顺序）

• 2026-04-09 — [[summaries/llm-wiki-gist]] — Karpathy 的原始 Gist

开放问题

• Q1: ...

规则：

• 每个维基页面必须在 index.md 中恰好出现一次。lint 工具会强制执行此规则。
• 文件夹拆分的概念通过缩进的项目符号展示层级结构。
• index.md 与 CLAUDE.md 共同构成 AI 在会话开始时读取的内容。

log/ 目录格式

详见 references/log-guide.md 获取完整说明。最低要求如下：

• 每天一个文件：log/YYYYMMDD.md
• H1 为日期；每个条目使用 H2 格式：## [HH:MM] <操作> | <一句话描述>
• 操作类型：compile、ingest、query、lint、audit、promote、split、scaffold

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

使用场景

• 深度研究 — 在数周内阅读某主题的相关论文或文章；维基随你的理解不断演化，审计日志可防止 AI 错误无声积累
• 个人维基 — 将日记、笔记、想法整理成个人百科全书；后续可对任何内容发表不同意见，AI 会进行修正
• 团队知识库 — 来自 Slack 聊天、会议记录、文档的内容输入；团队成员可通过网页查看器提交修改
• 阅读伴侣 — 随着每章阅读进度逐章归档；最终形成一个丰富的辅助维基

参考资料

• references/schema-guide.md — CLAUDE.md 中应包含的内容
• references/article-guide.md — 如何撰写高质量维基文章（篇幅、维基链接、mermaid 图表、数学表达式、分而治之策略）
• references/log-guide.md — log/ 目录的命名规范
• references/audit-guide.md — 审计文件格式、锚点策略、处理流程
• references/tooling-tips.md — Obsidian 配置、网页剪藏工具、qmd、插件及网页安装方法