llm-wiki

LLM Wiki

一项用于在用户选择的任意文件系统位置构建和维护由 LLM 整理的知识库的技能，遵循 Andrej Karpathy 在 2026 年 4 月的 gist 中描述的模式。一个个人 Wiki 可以跨项目累积知识，也可以将 Wiki 隔离在单个项目中。用户整理来源并提出问题；LLM 负责记录和维护。

用一段话概括这种模式

传统 RAG 会在每次查询时从原始片段重新推导知识，不会累积任何内容。LLM Wiki 模式则反其道而行：当出现新的来源时，LLM 会将其一次性编入持久化、结构化的 Wiki——提取概念、编写实体页面、更新交叉引用，并标记矛盾。之后的查询会读取预先综合整理好的 Wiki，而不是原始来源。知识不断累积。用户负责选择来源并提出好问题；LLM 则负责总结、链接和一致性维护，而这些工作正是人们放弃维护 Wiki 的原因。

何时使用此技能

触发场景非常广泛。只要用户在一段时间内持续积累文本材料——研究论文、文章、转录稿、会议记录、书籍章节、客户通话记录、代码仓库、日记条目——并且希望将这些材料整理起来，而不是每次会话都把它们堆进聊天中，就适用此技能。它既适用于单个来源（“摄取这篇论文”），也适用于对现有 Wiki 的常规操作（“我的 Wiki 对扩散模型是怎么说的”“检查 Wiki”“还缺少什么”）。

在进行任何其他操作之前，先确定 Wiki 的位置。按以下优先顺序选择：用户指定的路径、最近项目说明中的路径、全局 Agent 说明中的路径，然后是当前项目中的 wiki/。读取确定的 Wiki 中的 SCHEMA.md；其中可能会覆盖此处记录的默认设置。切勿在未说明的情况下合并两个 Wiki。如果不存在 Wiki，请执行下方的引导步骤。

此技能中的所有相对 wiki/ 和 raw/ 路径，都指向已确定的 Wiki 和原始来源根目录，不一定是当前工作目录。

架构：三层，三种操作

Wiki 由三层和三种操作组成。请熟悉这些术语，因为此技能的其余部分都以此为基础。

三层分别是原始来源（用户整理的来源材料——文章、论文、PDF、转录稿；内容不可更改，LLM 只读取，不修改）、Wiki（由 LLM 生成的 Markdown 页面目录——实体页面、概念页面、比较、摘要；此层完全由 LLM 维护），以及架构规范（Wiki 根目录中的 SCHEMA.md 文件，用于记录此 Wiki 特有的约定——页面类型、命名规则、标签分类体系、摄取工作流自定义项；与用户共同演进）。

三种操作分别是摄取（收到新来源；LLM 读取来源、编写摘要页面、更新相关实体和概念页面，并追加日志）、查询（用户提出问题；LLM 通过索引浏览 Wiki、读取相关页面并综合答案——通常还会将答案存为新页面，让探索成果不断累积），以及检查（定期健康检查；LLM 扫描矛盾、过时的论断、孤立页面、缺失的概念和损坏的链接）。

关于这些操作的规范说明，请阅读 references/architecture.md。有关分步流程，请按需阅读 references/ingest-workflow.md、references/query-workflow.md 和 references/lint-workflow.md。

图谱层（已编译，可选）

页面可以在 frontmatter 中包含类型化的 graph: 元数据。内置提取器会将每个页面编译到 wiki/graph/：nodes.jsonl、edges.jsonl、graph.sqlite、graph.graphml。Markdown 是权威来源；图谱是可重新生成的索引。没有 graph: 的页面仍会作为节点出现（根据其 type/kind 推导），并根据正文中的维基链接生成低置信度的 mentions 边。类型化语义边（例如 founded、proposed、depends_on）必须有明确的来源和证据引文——绝不可根据训练数据推断并生成。

图谱层的约定（谓词词汇表、节点 ID 格式、必需字段）位于 wiki/graph/ontology.yaml。完整参考见 references/graph-workflow.md。完成实质性导入后，运行内置脚本：

uv run --script scripts/wiki_graph_lint.py wiki/      # check ontology + evidence + alias collisions
uv run --script scripts/wiki_graph_extract.py wiki/   # rebuild nodes.jsonl, edges.jsonl, graph.sqlite, graph.graphml
python scripts/wiki_graph_query.py wiki/ neighbors --node product:konvy

如果 wiki/graph/ontology.yaml 不存在，说明该 wiki 尚未启用图谱，应将图谱步骤视为无操作——不要凭空创建文件。

存储范围和布局

Wiki 的存储范围独立于技能的安装范围。全局安装技能只会让它在各个项目中可用；这不会创建或选择全局 wiki。

使用以下两种布局之一：

• 个人全局 wiki： 使用 ~/wiki/ 等稳定的根目录，并将原始来源放在 ~/wiki/raw/。将 Agent 的全局指令指向该用户级路径。这样便可以有意地将任意项目中的内容导入同一个不断积累的知识库。
• 项目 wiki： wiki/ 和 raw/ 位于项目中，并由该项目的 Agent 记忆文件引用。适用于知识需要按仓库隔离或进行版本管理的情况。

全局 wiki 不会自动扫描或导入项目。只有在用户要求导入，或其全局指令要求保留相关发现时，才添加项目来源和持久化发现。

项目本地的默认布局为：

<project-root>/
├── wiki/
│   ├── SCHEMA.md              ← conventions, the "config file" — read this FIRST
│   ├── index.md               ← entry point: catalog of all pages with one-line summaries
│   ├── log.md                 ← append-only chronological log of ingests/queries/lints
│   ├── indexes/               ← (appears once index.md shards) per-category indexes
│   ├── entities/              ← pages about specific things (people, products, papers, places)
│   ├── concepts/              ← pages about ideas, methods, frameworks
│   ├── sources/               ← per-source summary pages (one per ingested source)
│   └── synthesis/             ← cross-cutting analyses, comparisons, query results filed back
├── raw/                       ← the user's source material (PDFs, .md clippings, images)
│   └── assets/                ← downloaded images referenced by raw clippings
└── ...

此布局仅为默认选项，并非强制要求。全局 wiki 可以将 raw/ 放在 wiki 根目录内，任一范围也可以使用其他名称，例如 kb/、notes/ 或 vault/。请遵循 SCHEMA.md。

可扩展性原则

LLM Wiki 模式最大的失败风险，就是 Wiki 本身变成上下文瓶颈。简单粗暴的实现通常在几百个页面左右就会崩溃：LLM 要么每次查询都读取过多页面，要么因为跳过了相关页面而开始产生幻觉。这项技能的设计几乎完全围绕着避免这一问题。以下原则不可妥协；忽略它们，模式就会在规模扩大时崩溃。

原子化页面。 每个 Wiki 页面只讲一个概念，并且保持精简——建议上限为 400 行或约 2,000 个词，硬性上限为 800 行。如果页面超出这个范围，就将其拆分：把子概念提取到独立页面，并在父页面中添加链接。一个页面单独就占用上下文窗口 30% 的情况，是设计不佳的信号。

索引优先导航。 回答查询时，绝不要盲目地对 Wiki 使用 grep 或 glob。始终先读取 index.md（或 indexes/ 下相关的分片索引），找出候选页面，然后只深入查看这些页面。索引经过专门设计，读取成本很低——每个页面一行，不包含正文——它就是让整个模式具备可扩展性的缓存。

分片索引。 当 index.md 本身超过约 300 行，或 Wiki 页面数超过约 150 页时，应将其分片：把特定类别的条目移到 indexes/<category>.md 文件中（例如 indexes/entities.md、indexes/concepts.md、indexes/sources.md，或更细分的领域分片），并让顶层 index.md 成为这些分片的目录。这样读取索引需要两步查找，但每一步的范围都有限。

每个页面都添加 YAML frontmatter。 每个 Wiki 页面都必须以 frontmatter 开头，至少包含 type、tags、sources 和 updated。捆绑的 wiki_search.py 脚本无需读取页面正文即可按这些字段筛选。参见 references/page-conventions.md。

精准编辑，而非重写。 更新页面时（例如，新摄取的来源提到了一个已有实体，因此需要添加交叉引用），使用 str_replace 只修改相关部分。重写整个页面既缓慢，又会耗费大量令牌，还可能丢失之前的细节。

通过 grep 查找反向链接。 若要查找所有引用某个实体的页面，请运行 grep -rl "\[\[entity-name\]\]" wiki/，而不是逐页阅读查找提及。捆绑脚本让这项操作更加简单。

分块摄取来源。 摄取大型原始来源（长篇 PDF、书籍章节、冗长的文字记录）时，应分块读取，而不是一次性全部加载。摄取工作流会处理这项任务——参见 references/ingest-workflow.md。

大型 Wiki 使用搜索脚本。 Wiki 页面数超过约 300 页后，单纯查找索引可能无法为模糊查询找到合适的页面。使用 scripts/wiki_search.py 进行章节级混合检索，并可选用 frontmatter 筛选器和结构化的 --json 证据行。默认路径会运行本地 BAAI/bge-small-en-v1.5 FastEmbed 模型，通过 sqlite-vec 将生成的向量存储在 wiki/.wiki-cache/embeddings.sqlite 中，并使用 RRF 融合语义排序和 BM25 排序。初始化和升级时会通过 uv 运行 scripts/setup_wiki.py，安装固定版本的 FastEmbed、sqlite-vec 和 PyYAML，缓存模型，并同步每个章节，完成后才会报告设置就绪。Wiki 内容和查询文本都不会离开本机。如需不依赖外部依赖的 BM25，可使用 python scripts/wiki_search.py "query" --no-embed 绕过 PEP 723 解析。

完整的扩展操作手册（包括阈值和迁移步骤），请阅读 references/scaling-playbook.md。

初始化新建知识库

询问用户想要一个全局个人知识库，还是一个项目知识库。然后针对选定的基础目录运行引导脚本：

# Project wiki: <project-root>/wiki and <project-root>/raw
python scripts/init_wiki.py <project-root> [--wiki-dir wiki] [--raw-dir raw]

# Personal global wiki: ~/wiki with raw sources at ~/wiki/raw
python scripts/init_wiki.py <home-directory> --wiki-dir wiki --raw-dir wiki/raw

此操作会创建目录结构，放入 SCHEMA.md、index.md 和 log.md 的模板，然后运行强制性的本地运行时设置。设置过程会通过 uv 安装固定版本的依赖项，在缺少 BAAI/bge-small-en-v1.5 时下载该模型，构建解析缓存，并为当前所有分区生成嵌入。除非设置过程输出 "status": "ready"，否则不得将初始化或升级视为已完成。

运行引导脚本前，使用 references/retrieval-setup.md 中的分组访谈，确认路径、模型缓存位置、图谱用法以及 Agent 记忆集成。不要询问 API 密钥或是否同意使用服务提供商：这里没有远程嵌入流程。--no-embed 仍是后续搜索时确定性的词法搜索备用选项，不可用于跳过强制设置。

然后建议将知识库接入 Agent 记忆，以便后续会话能找到它：个人全局知识库使用包含稳定用户级路径的全局指令，项目知识库则使用包含相对路径的项目记忆文件。文件名取决于 Agent：Claude Code 使用 CLAUDE.md，Codex / Cursor / OpenCode / Pi / OpenClaw 使用 AGENTS.md，Gemini CLI 使用 GEMINI.md。完整工作流和两种配置段写法见 references/agent-memory-integration.md。未经用户批准，绝不要写入记忆文件。

摄取工作流（摘要）

完整工作流见 references/ingest-workflow.md；以下是其概要。收到新来源时，首先将来源原文写入 raw/（如为网络文章，则使用 Markdown 版本）。然后阅读来源；如果内容较长，则分块阅读；并在 wiki/sources/ 中创建一个来源摘要页面，以来源 slug 命名，补全 frontmatter，并引用原始文件。然后找出该来源涉及的现有实体页面和概念页面；针对每个页面，使用 str_replace 精确更新相关部分，而不是重写整个页面。找出该来源引入的新实体或概念，并为其创建新页面，再从相关现有页面添加链接，避免这些页面成为孤立页面。使用新页面更新 index.md（或相关分片）。在 log.md 中追加一行，包含日期、操作类型和来源标题。最后与用户讨论要点——哪些内容让他们感到意外、哪些值得跟进——并提出将这段讨论整理为综合页面归档。

查询工作流（摘要）

完整版本见 references/query-workflow.md。若要根据知识库回答查询：先阅读 index.md（或相关分片）；根据单行摘要找出候选页面；阅读这些页面（以及其中列出的任何看起来相关的反向链接）；使用 [[wikilink]] 引用所用页面来综合答案；并提出将综合后的答案归档到 synthesis/，以便后续查询受益。如果索引没有显示合适的候选页面，则运行 uv run --script <skill-root>/scripts/wiki_search.py "query terms" --wiki <absolute-wiki-root>，执行本地混合检索并按相关度排序；仅在无需依赖项的词法 BM25 检索时添加 --no-embed。明确写出已安装技能的路径和目标知识库路径。如果知识库似乎缺少相关主题的内容，应直言说明，不要编造；并将其标记为候选摄取目标。

lint 工作流（摘要）

完整版本见 references/lint-workflow.md。Lint 最好按固定周期运行（每处理 N 批内容后或每周一次），而不是每次操作都运行。随附的 python scripts/wiki_lint.py 会自动发现结构性问题——孤立页面、失效的 [[wikilinks]]、过大的页面、缺失或格式错误的 frontmatter、过时的 updated 日期。对于需要大模型进行的语义检查：阅读近期更新的页面，查找与旧说法相矛盾的内容；找出被提及但没有独立页面的概念；并建议用户可能想通过网页搜索或新增来源来补充的内容缺口。始终将 lint 结果作为待用户批准的修改建议，而不是既成事实——知识库属于用户，未经告知就改写会损害信任。

需要防范的失败模式

围绕这篇 gist 的社区讨论揭示了几种值得牢记的失败模式，因为这类做法出问题时通常就是这些原因。请阅读并了解需要主动避免的情况。

第一种是无声损坏——对某个来源的误读变成看似权威的知识库页面，继而影响对后续来源的解读，错误在不知不觉中不断累积。缓解措施：知识库中的每条说法都必须在 frontmatter 中包含 sources: 条目，指向原始文件；lint 检查应标出无法找到来源的说法。在摄取过程中如有疑问，应在知识库文本中保留余地（“来源声称 X，但其他来源尚未证实”），而不是直接断言。

第二种是知识库读取自身输出导致的偏移——大模型开始把先前的知识库页面视为事实依据，不再对照原始来源进行核查。缓解措施：摄取过程中更新现有页面时，在合并新内容前，重新阅读与现有说法相关的原始来源。不要只相信知识库对来源内容的说法。

第三种是维护负担不断攀升——一位在 gist 评论区发表意见的人指出，随着知识库不断扩展，LLM-Wikis 可能需要更多而非更少的人工投入，因为大模型的输出需要越来越多的监督。缓解措施是遵循上述可扩展性规范（分片索引、原子页面、frontmatter、lint 脚本），并保持稳定的 lint 检查频率。如果 lint 报告开始多到用户无法审阅，说明知识库已超出当前规范的适用范围，需要修订架构。

第四种是范围蔓延到不适用的领域——这种模式适合积累文本研究资料，但不适合高度依赖关系的数据（组织架构图、财务账目、结构化数据集），这类数据用真正的数据库会更合适。如果用户的领域本质上是关系型的，应明确指出这一点，并推荐更合适的工具，而不是强行让 Markdown 承担不适合的工作。

参考文件

参考文件是详细操作流程的权威依据。在执行相关操作时再阅读，不要提前阅读。

• references/architecture.md — 深入讲解三层结构和三项操作，附页面格式示例及各项设计选择背后的理由
• references/ingest-workflow.md — 分步讲解摄取流程，包括大型来源的分块读取，以及各页面类型的模板
• references/query-workflow.md — 讲解从索引 → 页面 → 反向链接的导航模式、何时回退使用搜索脚本，以及如何将答案作为综合页面归档
• references/lint-workflow.md — 讲解检查内容、如何呈现检查结果，以及检查频率
• references/page-conventions.md — 讲解 frontmatter 架构、页面命名、链接语法、页面类型定义和大小规则
• references/scaling-playbook.md — 讲解何时拆分索引、何时引入搜索脚本，以及知识库超出当前约定承载能力的信号
• references/agent-memory-integration.md — 讲解如何将全局或项目知识库接入 Agent 指令，包含不同版本的配置段和引导对话脚本
• references/retrieval-setup.md — 必需的初始化/升级设置：路径、模型缓存、固定版本的本地依赖、全语料库向量同步、就绪检查，以及不含机密信息的 SCHEMA.md 状态
• references/graph-workflow.md — 可选的图层：本体、frontmatter 架构、何时添加有类型的边而非普通 wikilink，以及提取/检查/查询流程

内置脚本

这些脚本刻意保持精简，旨在避免 LLM 每次调用时都重新实现相同的辅助工具。每个脚本都在自己的 --help 输出和文件顶部附有文档。

• scripts/init_wiki.py — 引导初始化或升级知识库，然后要求完成已验证的运行时/索引设置
• scripts/setup_wiki.py — 通过 uv 安装固定版本的 FastEmbed/sqlite-vec/PyYAML，缓存本地模型，并同步解析索引和向量索引
• scripts/wiki_search.py — 基于本地混合检索的章节级搜索，支持 JSON 证据、筛选条件、增量缓存，以及无依赖的词法回退
• scripts/wiki_lint.py — 结构健康检查（孤立页面、失效链接、超大页面、frontmatter 验证、日期过期）
• scripts/wiki_stats.py — 快速汇总知识库大小、各类型页面数量和链接密度；可用于判断何时拆分索引
• scripts/wiki_graph_extract.py — 通过固定版本的 PyYAML，将图元数据和 wikilink 编译为 JSONL、SQLite 和 GraphML
• scripts/wiki_graph_lint.py — 通过固定版本的 PyYAML，根据本体验证有类型的边
• scripts/wiki_graph_query.py — 在 graph.sqlite 中查询邻居 / 边 / 事实 / 最短路径

模板

assets/ 中的模板是起始样板：引导初始化知识库时会将其复制到用户的知识库中，之后由用户自行编辑和演进。

• assets/SCHEMA.md.template — 新知识库的规范架构文档
• assets/index.md.template — 空索引文件
• assets/log.md.template — 空日志文件
• assets/page.md.template — 带有 frontmatter 脚手架的通用知识库页面
• assets/ontology.yaml.template — 起始图本体，复制到 wiki/graph/ontology.yaml
• assets/graph_README.md.template — wiki/graph/ 的说明文档（规范文件与生成文件）
• assets/graph_gitignore.template — wiki/graph/ 的 .gitignore（默认忽略 graph.sqlite 和 graph.graphml）

从任务经验中学习并演进技能

对于“从这项任务中学习”、/wiki:learn、“改进此流程”或 /wiki:evolve，请阅读 references/evolution-workflow.md。使用 scripts/wiki_evolve_loop.py 进行有界训练、持久化证据整合、连贯的完整技能提案、验证选择和独立最终测试。scripts/wiki_evolve.py 用于记录手动经验，并负责审核、应用和回滚。共享适配器支持九种 Agent 宿主，并支持持久、可观察的跟踪记录、工作流产物和跨 Agent 迁移。执行前，请配置已授权的调用／时间预算；严格的美元限额必须使用有界 API 运行器。常规 wiki 使用方式不变。

复用来源页、概念页和综合页来存放证据、模式和实验摘要。将假设与已验证的观察结果分开，保留反例及模型／工具的适用范围，并在再次提出建议前查阅已驳回的历史记录。执行期间保持事实 wiki 可用，并避免将实验历史带入常规上下文。切勿从源文本推断授权、捏造结果，或将流畅的拟议指令视为已测试内容。未经授权的运行器和预算，不得启动付费评估。

随附的 eval/evolution/pilot/suite.json 和语料库提供了 20 个查询任务，可作为起点。scripts/wiki_evolve_claude.py 是可选的、经过身份验证的 Claude CLI 适配器；其他模型使用相同的 JSON 运行器契约。.evolution/ 用于保存持久实验凭据，不纳入常规 wiki 工具。安装／升级会以幂等方式添加 .experience-template.json、.pattern-template.md 及其归档 README。不要编辑无关技能或全局 Agent 指令。如果经过验证的流程属于分发式插件，请遵循仓库的 SemVer 和 PR／发布规则。