LLM Wiki 机制学习指南

本指南只讲一件事：LLM Wiki 这套系统本身是怎么运转的——它的输入是什么、处理过程是怎样的、输出是什么。不涉及 raw 里的具体业务数据内容。

为什么要"编译"知识？（Karpathy 范式）

注：上表中"Token 大幅下降 / 零基础设施 / 复利增长"等结论来自 Karpathy 原始范式及社区实践的公开讨论，本节末的起源章节给出出处。

Karpathy 范式起源（外部背景补充）

起源事件

Karpathy 的经典类比与人机分工

Karpathy 原始三层架构

本仓库 vs Karpathy 原始范式（关键改造）

本 llm-wiki-overseas 仓库继承了范式的骨架，但为"企业级 + 多源自动拉取 + 自动发布"做了显著工程化改造。理解这些差异，是理解本仓库设计取舍的关键：

适用边界（来自社区实践）

出处：Karpathy LLM Wiki gist（gist.github.com/karpathy/442a6bf…）；社区解析文章（agentpedia.codes、掘金 coderMax《从知识检索到知识编译的范式革命》等，均为 2026-04 公开发布）。数据如"Token 减少 ~95%、比 RAG 高效 ~70 倍"为社区实践估算，非本仓库实测。

编译器类比（贯穿全文的主线）

系统提示词开篇即自我定义为「raw→LLM Wiki 编译器」。用传统编译器的概念来理解这套系统，一切都会变得清晰：

输入 / 处理 / 输出 全景图

INPUT输入总览：四类输入

LLM Wiki 编译器接收四类输入。前两类是"要编译什么"，第三类是"按什么规则编译"，第四类是"这次编译做什么"。

① raw/ 原始资料 —— 输入契约（只讲格式，不讲业务内容）

raw/ 是编译器的源代码目录。作为学习机制，你只需理解它的输入契约：有哪几类源、以什么格式落盘、如何被 Agent 读取。

iWiki 源的 frontmatter 契约（拉取时自动生成）

---
source_id: iwiki:4017234012       # 全局唯一主键
url: https://iwiki.woa.com/p/4017234012
title: "（源文档标题）"
version: 9                     # 版本号 → 增量判定的关键信号
content_changetime: 2026-02-10 10:24:28
fetched_at: 2026-07-15
status: raw                   # 标记这是未编译的原始层
---
（下面是原文正文，Agent 阅读的对象）

② _fetch_state.json —— 拉取账本（编译的触发信号）

这是编译器的"源文件时间戳表"。Agent 只读它来判断哪些源发生了变化。关键字段：

{
  "schema_version": 3,
  "docs": [{
    "source_id": "iwiki:4017234012",
    "source": {
      "type": "iwiki",
      "version": 9,               // iWiki 用整数版本号比较
      "content_hash": "sha256:04f3..."  // 正文规范化后的哈希（防"版本变但内容没变"）
    },
    "fetch": {
      "state": "fresh",           // pending|fresh|changed|fetching|error|removed
      "fetched_at": "2026-07-15"
    }
  }]
}

③ 系统提示词 —— Schema 层（最关键的输入）

Agent 的自我定位（提示词原文）

提示词定义的三层架构（编译器视角）

④ 调用指令 —— 告诉编译器这次做什么

每次调用必须显式指定 mode，与 operation 正交组合：

# 格式：mode（rebuild|incremental）+ operation（ingest|query|lint）+ 输入

mode=rebuild     operation=ingest                     # 全量重建（初始化/规范大改时）
mode=incremental operation=ingest source_id=iwiki:4028672179   # 增量摄入（日常默认）
mode=incremental operation=query "某某字段怎么查？"    # 查询，可选 --archive 归档
mode=incremental operation=lint                       # 健康检查，可选 --fix

PROCESSING处理器：Knot Agent

处理器 = Knot 平台上的 LLM Agent + 系统提示词。它是整个系统里唯一的"编译器本体"。下面按照它内部的处理流程逐步拆解。

处理第一步：增量候选判定（join 两份账本）

增量编译的核心问题是："哪些源需要重新编译？" Agent 通过同时读两份账本来判定，这正是编译器"增量编译"的本质——对比源文件时间戳和产物时间戳。

处理第二步：ingest 编译流程（核心）

确定候选源后，Agent 对每个源执行 ingest。这是把"源代码"翻译成"知识产物"的核心翻译过程：

• 读取源与状态：从 _fetch_state.json 找到候选 source_id 对应的 raw 文件路径，读取原文。
• 通读原文提炼：完整读原文，提炼 3–5 条关键要点（key_claims）。不臆造，原文没有的不写。
• 产出/更新 source 摘要页：每个源对应一篇 docs/sources/summary-{slug}.md，一一对应，记录 source_id/version/key_claims/confidence。
• 抽取实体与概念：识别原文中的实体（服务/平台/接口/库表…）和概念（机制/方法/术语…），创建或更新 entities/*.md 与 concepts/*.md。
• 建立交叉引用：新页面至少引用 2 个现有页面（标准 markdown 链接），形成知识网络。
• 标注矛盾：若新源与已有页面冲突，用引用块显式标注 > 矛盾标注（contradiction）：…，来源 sources/summary-x.md，并写入 frontmatter 的 contradictions，绝不悄悄覆盖旧结论。
• 归类 cluster：给新页面打主题分组标签；若出现新分组，登记到 index.md 与 overview.md。
• 更新系统页：更新 index.md（主目录，按主题分组）、sources/index.md（源清单）、log.md（追加操作记录）。
• 双提交闭环：先提交 docs 产物（Commit A）拿到 hash，再把 hash 回填进 _compile_state.json 单独提交（Commit B），详见 双提交工作流。

query 处理流程（读取 + 可选归档）

query 是"用已编译的知识库回答问题"，并可把有价值的新分析反哺回知识库：

• 定位：读 index.md 找到相关页面入口。
• 下钻：读相关概念/实体页，必要时进一步下钻到 sources/ 摘要页核对证据。
• 带引用作答：回答时标注信息来自哪些页面。
• 可选归档（--archive）：若问答中产生了有价值的横向对比或纵深分析，归档为 comparisons/*.md 或 syntheses/*.md，标记 filed_from_query: true。

lint 处理流程（一致性检查）

lint 是编译器的"静态检查/警告"，扫描知识库的结构健康度：

编译质量约束（红线，保证产物可信）

OUTPUT输出总览：四类产物

① docs/ 知识库结构

六种页面类型（产物的"类型系统"）

frontmatter：产物的机器可读元数据

每个产物页面头部都有 YAML frontmatter，这是知识图谱的"符号表"。以 concept 页为例：

---
type: concept
title: "概念名"
aliases: [别名, 缩写]          # 供 query 命中
sources: [sources/summary-x.md]   # 溯源：这页知识来自哪些源摘要
related: [entities/entity1.md]    # 交叉引用（≥2）
created: 2026-07-15
updated: 2026-08-03
confidence: high | medium | low   # 置信度
cluster: "{主题分组}"          # 与 index.md 分组一致
contradictions: []            # 与其它源的冲突
open_questions: []            # 未解决的缺口
---

互链网络：产物的核心价值

② _compile_state.json —— 编译状态输出

这是编译器写回的"构建缓存"，记录每个源已编译到什么程度，供下次增量判定：

{
  "schema_version": 3,
  "docs": [{
    "source_id": "iwiki:4017234012",
    "compile": {
      "state": "compiled",       // never_compiled|stale|compiling|compiled|compile_error|ignored
      "compiled_version": 9,     // 已编译到的源版本（与 fetch.version 比较判 stale）
      "compiled_commit": "63394f7", // 产出这批 docs 的 Commit A hash（双提交回填）
      "compiled_at": "2026-07-15",
      "error": null
    }
  }]
}

③ docs/log.md —— 操作审计输出

每次操作追加一条结构化、可 grep 的记录，只追加不删除：

## [2026-08-03] ingest | 摄入 {源标题}(iwiki:xxxx) 及 N 个 stale 源
Sources: iwiki:xxxx (never_compiled→compiled, v3), ...
Pages created: docs/sources/summary-xxx.md, docs/concepts/xxx.md
Pages updated: docs/index.md, docs/overview.md, docs/sources/index.md, docs/log.md
Key changes:
  - 简述本次新增/变更的知识点
Contradictions flagged: 无

④ iWiki 发布 —— 最终交付（sync_to_iwiki.py）

docs/ 编译完成后，由发布脚本推送到 iWiki。核心难点是页面互链的 docid 解析，用"两遍推送"解决：

状态机与增量闭环

整个系统靠两份账本的状态流转驱动增量。理解这两组状态，就理解了"编译器如何知道该编译什么"。

fetch.state（输入侧状态，Agent 只读）

compile.state（输出侧状态，Agent 独写）

双提交工作流（产物落地的闭环）

• 基础检查：新增/改动页有 H1；相对链接目标存在；必要时 py_compile 校验脚本。
• Commit A（wiki 产物）：git add docs/ 提交本次编译的所有页面（sources/concepts/entities/index/log…），读取其 commit hash。
• Commit B（状态回填）：把 Commit A 的 hash 写入 _compile_state.json 对应 source_id 的 compiled_commit（同时写 state=compiled、compiled_version、compiled_at），git add raw/_compile_state.json 单独提交。
• 一次性 push：A、B 都提交后再一次性推送，不停在未提交/未推送状态。

端到端实例：一个源的完整生命周期

把输入/处理/输出串起来，跟随一个 iWiki 源从被添加到最终发布的全过程：

• 输入 添加源：运维执行 fetch_raw.py --add 4028672179。脚本拉取正文、加 frontmatter、算 content_hash，落盘为 raw/xxx-4028672179.md，并在 _fetch_state.json 写入 fetch.state=fresh, version=3。
• 输入 触发编译：调用 mode=incremental operation=ingest source_id=iwiki:4028672179。
• 处理 候选判定：Agent join 两份账本，发现该 source_id 在 _compile_state.json 中缺失（never_compiled）→ 判定为候选。
• 处理 编译：通读原文 → 提炼 3–5 条要点 → 新建 sources/summary-xxx.md、若干 concepts/*.md 与 entities/*.md → 建立 ≥2 交叉引用 → 标注矛盾（若有）。
• 输出 写产物：更新 index.md（注册新页 + 主题分组）、overview.md、sources/index.md、log.md（追加 ingest 记录）。
• 输出 Commit A：git add docs/ && git commit -m "docs: ingest xxx"，得到 hash abc123。
• 输出 Commit B：把 abc123 回填进 _compile_state.json（state=compiled, compiled_version=3, compiled_commit=abc123），单独提交后 push。
• 发布 sync：CI 触发 sync_to_iwiki.py，第一遍给新页建档拿 docid、第二遍解析链接推送，iWiki 上出现可搜索、可互跳的新文档。
• 再处理 下次源更新：某天该 iWiki 文档被人改动，fetch_raw 拉到 version=4。下次 ingest 时 join 账本发现 compiled_version(3) < version(4) → stale → 只重编这一个源的相关页面（增量），其余页面纹丝不动。

从零复现 LLM Wiki 的最小清单

• 输入 搭输入管道：准备 fetch_raw.py（或任意拉取脚本），能把外部源拉成"带 source_id 的标准化 raw 文件 + _fetch_state.json 版本账本"。初始 {"schema_version":3,"docs":[]}。
• 输入 准备空产物骨架：建 docs/（index.md、overview.md、log.md + sources/entities/concepts/comparisons/syntheses 五目录）与初始 _compile_state.json、iwiki-mapping.json。
• 处理 装配处理器（最关键）：在 Knot 平台建 Agent，绑定仓库读写权限，把系统提示词全文设为 system prompt。没有它，LLM 只是聊天机器人。
• 处理 首次全量编译：调用 mode=rebuild operation=ingest，让 Agent 枚举全部源编译成 docs，末尾自动 lint 收敛。
• 输出 验证产物：检查双提交闭环（Commit A 产物 + Commit B 回填）、log.md 记录、lint 报告（断链/孤儿页为 0）。
• 发布 接发布管道：配置 iwiki-mapping.json 的 spaceid/parentid，CI 里跑 sync_to_iwiki.py（首次 --all）。
• 处理 建立增量循环：定时 fetch 检测源更新 → 有 stale 就 incremental ingest → 定期 lint 保健康。系统开始自我累积复利。

复现避坑（机制层面）