LLM Wiki 知识库
基于 Karpathy LLM Wiki 思想，将非结构化聊天记录编译为结构化、可被 LLM 消费的知识碎片系统。
概述
LLM Wiki 是 OpenClaw 项目的内部知识库系统，将 Mattermost/Clawline 等渠道的原始聊天记录（约 8MB）经过 LLM 编译，转化为结构化的 wiki 文章。系统遵循 Karpathy 提出的 LLM Wiki 核心思想——LLM 需要的不是文档，而是结构化的知识碎片 + 链接。
系统架构
Wiki 数据直接存储在本地文件系统 ~/.openclaw/wiki/，Agent Portal 通过 server.cjs 的 /api/wiki/pages API 实时读取 markdown 文件，不经过数据库。
~/.openclaw/wiki/
├── raw/mattermost/ ← 原始聊天记录（27个bot，~8MB）
├── raw/topics-v1/ ← v1 编译产物归档（43篇）
├── topics/ ← v1 主题编译（12大主题 + 31细分）
├── pages/ ← v2 Karpathy 风格文章（235篇）
├── bots/ ← bot 档案（15个）
├── projects/ ← 项目概览（8个）
├── concepts/ ← 概念文档
└── archive/ ← 旧版 GPT-4o 产出
Wiki Portal 展示修复（2026-04-07）
问题
Agent Portal 前端的 WikiTab 组件硬编码了 4 种 type 分组：
const GROUPS = [
{ key: "project", label: "项目", icon: FolderKanban, emoji: "📁" },
{ key: "bot", label: "Bot", icon: Bot, emoji: "🤖" },
{ key: "concept", label: "概念", icon: Lightbulb, emoji: "💡" },
{ key: "synthesis", label: "综合分析", icon: FileText, emoji: "📊" },
]新编译的 43 篇 topic 文件 frontmatter 都是 type: topic，加上 23 篇无 type 的页面，总共 66 篇从未在侧边栏显示过。
修复方案
改为动态分组——API 返回什么 type 就显示什么分组，不再按预定义列表过滤。已知 type 有预设图标和中文名，未知 type 自动用文件名 humanize 做标签。
修复后 Portal 侧边栏显示全部 97 篇页面，分为 6 组：项目(8)、Bot(15)、概念(1)、综合分析(7)、主题(43)、其他(23)。
Karpathy Wiki 组织方式（2026-04-07）
讨论了如何按照 Karpathy 的 LLM Wiki 核心思想重新组织已有的 43 篇巨型 topic 文件。
采纳的核心原则
| Karpathy 原则 | 实现方式 |
|---|---|
| 颗粒化：一个概念一篇文章 | 从 43 篇巨型 topic 拆成 235 条独立条目 |
| 分类法：concept / decision / pattern 等 | 5 种类型：concept(76), decision(32), pattern(39), incident(18), guide(70) |
互链：wikilinks 构建知识图谱 | 每篇文章底部有 相关条目 用 slug 链接 |
| 面向 LLM 消费：token 友好，结构化 | 每篇 6-8KB，有 YAML frontmatter + 结构化段落 |
| 不可变源：原始数据保留 | raw/topics-v1/ 保存 43 篇原始 topic，永不修改 |
务实调整
| Karpathy 理想 | 实际取舍 | 原因 |
|---|---|---|
| 人工策展每条 | LLM 批量提取 + 全局去重 | 766 条手动不现实，用两轮去重压到 235 |
| 极致颗粒（每个 API 参数一篇） | 适度合并（同主题收束） | 太碎反而不好检索，decision 从 193 合到 32 |
| 双向链接自动维护 | 单向引用，生成时写入 | 暂无 wiki 引擎，后续可加 |
主题批量生成流程（2026-04-07）
第一阶段：v1 主题编译
使用 GPT-5.4 对原始聊天记录进行主题编译：
- 12 个大主题全部完成（infrastructure 275KB, clawcraft 208KB 等）
- 31 个细分主题生成，其中 5 个失败（<500 bytes，只有 frontmatter 无内容）
- 失败主题重跑后全部成功：
- channel-agent-isolation-and-resilience: 239B → 52KB ✅
- clawline-web-client-ui-optimization: 219B → 46KB ✅
- codex-assisted-development: 262B → 142KB ✅
- openclaw-skill-installation-and-loading: 251B → 33KB ✅
- prism-hackathon-openclaw-setup: 217B → 17KB ✅
- 最终产出：43 篇，总计 2.3MB，零空壳
第二阶段：Karpathy 风格重编译
- Phase 1（提取）：从 43 篇 v1 topic 文件提取 766 个知识条目
- 去重：766 → 591（slug+title 去重）→ 235（LLM 全局语义去重）
去重压缩效果：
| 类型 | 原始 | 去重后 | 压缩率 |
|---|---|---|---|
| Decision | 228 | 32 | -86% |
| Incident | 171 | 18 | -89% |
| Pattern | 155 | 39 | -75% |
| Concept | 110 | 76 | -31% |
| Guide | 102 | 70 | -31% |
| 总计 | 766 | 235 | -69% |
- Phase 2（生成文章）：235 篇文章，每篇 6-8KB，~40s/篇
- Token 消耗估算：约 3.3M tokens（Phase 2），使用 GPT-5.4
去重保留/删除原则
保留标准：
- 独立可操作——读完就能解决具体问题
- 上位原则——覆盖多个具体场景的通用模式
- 不可归入其他条目——确实独立
- 高复用——不是一次性特殊案例
删除标准：
- 一次性调试记录——改个端口/变量名级别
- 被上位条目覆盖——具体实例已被通用模式包含
- 颗粒度过细——一句话能说清的不独立成条
- 因果链合并——“X 导致 Y” + “Y 的解决” 合为一条完整故事
技术细节
- 数据来源：Mattermost 聊天记录（27 个 bot），约 8MB 原始文本
- 编译引擎：GPT-5.4（Azure
sweden-ext/us2endpoint） - Portal 集成：
server.cjs通过/api/wiki/pagesAPI 直接读取本地文件系统，跳过raw/目录 - 文章格式：YAML frontmatter + 摘要 + 背景 + 核心内容（含代码示例）+ 要点 + wikilinks 交叉链接
大规模 Wiki 内容生成与质量反思（2026-04-08）
增量更新脚本 wiki-incremental.js
完成了第三项 Wiki Pipeline 任务：增量更新脚本。该脚本将 daily digest 接入 Karpathy pipeline，实现提取→去重→更新/创建 pages→更新 index/log 的完整流程。
- 处理 11 个 daily digest，提取 34 条知识条目
- 去重后新增 31 条，Wiki 总页面达到 268 篇
- 质量问题暴露：增量页面平均仅 500 bytes（如
local-repo-status.md只有一段话），与 Karpathy 编译的 8KB 深度文章差距巨大。原因是增量脚本直接从 digest 摘要生成，缺少 phase2 的”回溯 raw 源、LLM 深度展开”步骤
Pipeline 碎片化问题
审计发现 wiki 脚本已膨胀至 13 个（compile、compile-v2、v2.1、retry、karpathy-compile、dedup、dedup-global、phase2、index、auto-link、fix-links、ingest、incremental），多数是一次性迭代工具。
Karpathy 核心思想重新审视
重新回顾 Karpathy LLM Wiki 原文后，识别出四个关键偏差：
- 过度工程化：Karpathy 说的是”LLM 读资料，更新页面”，我们搞了 13 个脚本像在写编译器
- 批量编译 vs 增量维护：应是每次一点增量融入，而非批量产出后断裂式增量
- 只有 Ingest，没有 Query 和 Lint：切断了”ingest 让 wiki 更丰富→query 答案更好→好答案存回 wiki”的复利循环
- 增量不是”新建页面”，是”更新已有页面”：一次 ingest 应触动 10-15 个已有页面，而非新建碎片页
重编译测试：Agent Portal 案例
以 Agent Portal 为实验对象，测试了知识页面的合并精简方案：
| 原版 (pages/) | 新版 (pages-v2/) | |
|---|---|---|
| 文件数 | 9 个 | 1 个 |
| 总大小 | 72.7 KB | 4.6 KB |
| 信息密度 | 每篇 8KB 八股文 | 长度由内容决定 |
核心结论：
- 235 篇 Karpathy 页面是”看起来像知识库的文章集”，不是”活的笔记本”
- 正确目标：50-80 个精品页面 > 235 个灌水页面
- 页面长度应由内容决定，不按固定模板灌水
- 采用主页+详细页两层结构：主页作精简索引，详细页按时间线叙事展开，通过
wikilink互相引用
主题组织方式定型
经过多轮反思，确定了知识页面的组织原则：
- 按时间线叙事而非按抽象主题拆分——“03-10 那天做了什么”比”SSE 决策”更有价值
- 主页包含所有内容概览，详细页可点击深入
- 保留详细页作为引用，不是删掉它们
- 长度由内容决定——事故排查清单 2KB，项目主页 4.5KB，简单决策 1.2KB