LLM Wiki 搭建指南：从知识摄取到代理协作

当知识散落在几十个供应商文档、研究 PDF 和零散笔记中，每次对话都要从头复述背景，这种重复消耗正在成为 AI 辅助工作的隐性成本。Andrej Karpathy 提出的 LLM Wiki 模式给出了一个结构化的回应：用 Markdown 页面加 YAML 元数据组织知识，让人类和 AI 代理共同维护、按需查询。

一位开发者在实际工作中落地了这套方案，并将其适配到名为 Cereja Flamejante 的项目中。以下是这套系统从设计到实现的关键决策。

为什么需要 LLM Wiki 而非普通笔记

普通笔记的问题不在于存储，而在于缺乏可操作的结构。LLM Wiki 的核心区别在于三层设计：原始来源被完整保留、相关页面之间建立链接、一份指导文档告诉代理如何维护整个知识库。

Karpathy 描述的模型包含三个组件：保留的原始文件、相互关联的笔记页面、以及一份指引 AI 代理维护 wiki 的规范文档。开发者在此基础上做了适配，使用 Obsidian 本地同步来阅读笔记和浏览链接关系。图谱视图可以看到知识之间的连接，但作者特别提醒：一个漂亮的连接图不等于一个有充分证据支撑的论断。要核实信息，必须回到原始来源。

这里有一个关键区分：持久知识和代理上下文是两回事。一个知识库可能有数百条笔记，但一次具体任务只需要其中少数几条。RAG（检索增强生成）负责从知识库中检索相关片段，而知识组织本身承担的是完全不同的功能。

RAG（检索增强生成） 是一种将外部知识库与生成式模型结合的技术范式：在模型生成回答之前，先通过向量检索或关键词匹配从知识库中找出与问题最相关的若干文本片段，再把这些片段作为上下文一并送入模型。它的核心价值在于让模型基于可追溯的外部证据作答，而不是仅依赖训练时固化的参数记忆，从而降低幻觉并支持知识更新。RAG 的典型流程包括切分文档、生成嵌入向量、建立索引、检索召回、重排序和拼装上下文。它与本 wiki 的关系是互补的：wiki 负责把知识组织成稳定、可审查、带来源追溯的结构，RAG 则负责在具体任务中按需召回其中少量片段。理解这一分工，才能明白为什么一个精心维护的知识库并不会因为有了 RAG 就变得多余。

Wiki 如何嵌入代理工作流

在 Cereja 的架构中，Núcleo 负责记录知识、证据、解读和论点；Editorial Engine 准备发布内容；Agentic Factory 维护代理角色和各系统间的共享控制。Wiki 在这个架构中的作用是让知识变得可查询。

Guides（指南）指引具体工作：描述流程、顺序和任务所需的信息。举个例子，代理要准备一篇关于某项研究的文章，它需要来源、局限性和编辑指令。代理可以提出一个综合判断，但批准这个判断作为 Cereja 的官方立场、以及授权发布，是两个独立的决策。

这就是代理层的角色：组织执行过程中的查询和工具使用。它需要同时知道两件事——在哪里查找知识，以及可以执行哪些操作。

这套流程中，部分环节仍然是人工完成的。

摄取从命令开始，而非自动触发

在开发者最初的工作 wiki 中，把文档放入 raw/ 目录并不会自动触发摄取。需要有人主动请求处理，或者趁任务结束时顺手完成。

系统通过 check 来发现那些没有被任何笔记引用的文件。如果某个来源被有意丢弃，就记录原因。这样文件不再显示为待处理项，但也不会从历史中消失。没有 watcher，也没有定时任务——因为文件夹并不会每分钟都发生变化，这个流程在实际使用中已经足够。

在 Cereja 中，同样的触发方式被沿用：一条命令。实现的顺序是先做来源追溯记录，再做提取和综合。

raw/                       # 原始本地文件
sources/                   # 来源追溯和阅读笔记
tools/ingest_source.py      # 摄取命令
examples/wiki-ingestion/  # Cereja 自有示例

命令会计算文件的 SHA-256 哈希值。这个哈希标识文件的字节内容，并被纳入笔记文件名。如果笔记已存在，命令返回其路径并保留已有标注。

 digest = hashlib.sha256(path.read_bytes()).hexdigest()
 destination = target_dir / f"source-{digest}.md"
 
 if destination.exists():
     return destination, False

工作 wiki 使用归一化后的来源地址（记录在 resource 中）作为身份标识。在 Cereja 中，这两个功能被拆开：哈希标识内容，引用记录来源。这样可以检测不同的字节内容，但不能解决所有重复问题——两个 PDF 可能代表同一项研究。版本更新时还需要关联不同版本。

SHA-256 是 SHA-2 家族中的一种密码学哈希函数，能把任意长度的输入映射为固定的 256 位（64 个十六进制字符）摘要。它具备三个对本场景重要的性质：确定性（同一字节内容永远得到同一哈希）、雪崩效应（输入哪怕改动一个字节，输出也会大幅变化）、以及抗碰撞性（极难找到两个不同输入得到相同摘要）。因此，用文件内容的 SHA-256 作为笔记文件名，天然实现了“内容寻址”：相同文件重复摄取会命中已有笔记，内容不同则自动生成新笔记。需要注意，哈希标识的是字节层面，两个表述同一研究的不同 PDF 会得到不同哈希，所以系统仍需引用字段来记录来源身份，二者配合才能既检测内容差异又处理语义重复。

来源追溯：每条笔记必须说清出处

Cereja 的笔记以 draft 状态创建，记录标题、声明的作者、原始文件路径、哈希值、可用时的 URL、声明的权利状态和摄取日期。命令会将未知字段标记为 unknown。

可以通过以下命令运行实现自带的示例：

 python tools/ingest_source.py examples/wiki-ingestion/source-demo.md \
   --title "Cereja 收集示例" \
   --author "Cereja Flamejante" \
   --rights "自有演示材料" \
   --public-note

--public-note 选项确认文件名和元数据可以公开出现，但它不授予文档本身的任何权利。raw/ 中的原始文件默认不纳入 Git。发布 PDF 之前必须检查其许可协议。当不允许再分发时，可以保留引用和自己的原创分析，同时尊重来源的权利。

综合判断发生在摄取之后

在工作 wiki 中，PDF 文本提取使用 Poppler 的 pdftotext。知识库没有 OCR 功能。当文档包含图片形式的页面时，模型可以直接以图像方式阅读。

LLM 撰写综合内容并标注页码。笔记将文档中的陈述与我们自己的解读和保留意见分开记录。同时记录生成所用的模型和 token 消耗。概念和实体笔记指向来源笔记。

在 Cereja 中，当前命令只创建来源追溯记录。这些字段让当前状态一目了然：

 type: "source"
 status: "draft"
 certainty: "unverified"
 published: "unknown"
 extraction_status: "not_attempted"

在这个流程中，文档的提取和摘要尚未实现。阅读之后，需要记录方法、人群或范围、局限性，以及支撑每项论断的原文段落。Cereja 的证据 schema 指导这项审查。

一条生成的综合内容只有在经过人工提升之后，才会成为规范知识（系统认可的参考）。而且「由 Kell 批准」不等于「由 Kell 撰写」——作者身份的来源追溯始终保持。

检查机制：谁来审核被遗漏的内容

工作 wiki 中的 check 验证元数据、链接、笔记长度和索引中的存在性，同时标记未处理的来源，并核对派生笔记是否保留了来源的限制条件。

笔记从 draft 开始。有人在 review_stage 中记录阅读状态。提升到 stable 需要人类负责人；check 会拒绝将稳定笔记归属于模型。打开 PR 的人不批准自己的 PR。

这些验证有助于维护知识库，但它们不会替我们阅读研究。一个链接可能正常工作但指向不合适的来源。仍然需要人来评估什么真正支撑了一项论断。

在 Cereja 中，覆盖率、权利和提升的 check 仍需适配和测试。同时需要尊重 Núcleo 已经在使用的状态定义。不加核实地复制名称只会制造新的混乱。

按需查询：不要把整个知识库塞进上下文

在 Núcleo 中，流程从任务出发，定位适用的规则，查阅所需的材料。这个集合进入代理上下文，知识库的其余部分仍然可供查询。

Anthropic 将这种按需查询描述为一种上下文组织策略，同时也指出了一项成本：代理需要在执行过程中探索知识库。

为 newsletter 准备内容时，一个任务可能要求比较两项研究。代理收到来源及其局限性，以及写作指引。它提出的结论仍然需要经过审查。

更多文档不能解决所有故障。有时缺少的是一条信息，有时缺少的是工具施加的限制或对结果的验证。在增加另一个文件夹之前，需要先弄清楚到底缺的是哪一块。

OKF 带来的可移植性问题

Google Cloud 提出的 Open Knowledge Format（OKF）倡导用 Markdown 表示知识、用 YAML 元数据和概念间的链接来组织内容。

这之所以值得关注，是因为它将知识格式与生产和查询知识的工具分离开来。知识库可以跨工具共享，而不依赖单一界面。

OKF v0.1 仍是一个初步提案。使用 Markdown 和元数据并不会让知识库自动与其兼容——需要逐项核对规范。

YAML（YAML Ain't Markup Language）是一种以缩进表达层级、以键值对表达字段的序列化格式，常用于配置文件和数据文件的头部元数据。在本 wiki 的笔记中，文件顶部由 --- 包裹的区域就是 YAML front matter，用来声明 type、status、certainty、published 等结构化字段。相比 Markdown 正文，YAML 元数据更适合被程序解析和校验，因此 check 机制能够读取这些字段来判断笔记状态、链接完整性和提升资格。YAML 对缩进和冒号后空格敏感，一个常见的实践是保持字段名和取值风格统一，并让自动化工具负责写入而非手写，以减少格式错误导致的解析失败。

首次测试与下一步计划

开发者用一个自有 Markdown 演示文件执行了命令。第一次调用创建了笔记。第二次返回同一条笔记，没有覆盖它。

测试验证了字节保留、人工标注保留、重新摄取、内容变更、路径边界和公开元数据确认。实现位于 PR #34，两个新测试通过。完整测试套件出现了一个已有的 Flame 失败，与 Windows 路径分隔符有关。

这些结果确认了命令的特定行为，但尚未测量时间节省或策展质量提升。PDF 提取、可审查的综合内容和覆盖率检查是下一步。OCR 和文件夹监控留待实际使用证明需要时再做。

作者的目标是用这个知识库汇集研究、跟踪问题并准备 Cereja 的内容策展。从来源追溯开始，是因为需要能够回到文档并理解哪些内容已经过核实。下一步的考验是在 newsletter 的真实选题中使用这些笔记。

在你的知识库中，你如何区分一条由 AI 生成的笔记和一条已经过人工审查的信息？