Sage-Wiki 深度解析：当知识管理从「手动整理」变成「LLM自动编译」

引言：Karpathy 的一个想法，变成了 319 stars 的现实

2026年4月，Andrej Karpathy 在 X 上抛出了一个想法：能否让 LLM 像编译器一样，把散乱的文档「编译」成结构化的知识库？

"想象一个 LLM-compiled personal knowledge base —— 你丢进去论文、文章、笔记，LLM 读取、总结、提取概念，写出互相关联的文章。"

这不是幻想。两周内，xoai 团队把它变成了现实：sage-wiki，一个用 Go 写成的知识库编译器，支持 Markdown、PDF、Word、Excel、PPT、图片、代码等 15 种格式，输出可直接在 Obsidian 打开的互链 Wiki，还能通过 MCP 让任何 LLM Agent 访问你的知识。

这不是又一个「AI 笔记工具」。这是一次知识管理范式的根本性转变：从「手动整理」到「自动编译」。

一、核心概念：什么是「LLM-compiled」？

1.1 传统知识管理的困境

如果你用过 Obsidian、Notion、Roam Research，你一定熟悉这个流程：

1. 读一篇论文 → 手动摘录要点 → 创建笔记
2. 读一篇文章 → 手动摘录要点 → 创建笔记
3. 手动创建双向链接 → 手动整理标签 → 手动归档
4. 三个月后，你忘记了自己写过什么

问题在哪？知识整理是劳动密集型工作。每个人都知道「知识复利」的好处，但大多数人坚持不下来，因为维护成本太高。

1.2 sage-wiki 的答案：编译器思维

sage-wiki 借用了编程语言的「编译器」概念：

源代码（你丢进去的文档）
    ↓ 编译器（LLM）
目标代码（结构化 Wiki）

输入：raw/ 文件夹里的任意文档
输出：wiki/ 文件夹里的互链 Markdown 文章

区别在于：

• 编译器检查语法错误 → sage-wiki 提取概念和主题
• 编译器生成可执行文件 → sage-wiki 生成可搜索的知识网络
• 编译器增量编译 → sage-wiki 只处理新增或修改的源文件

1.3 核心特性一览

二、架构分析：一个知识编译器是如何工作的

2.1 编译流水线

sage-wiki 的编译流程分为 5 个阶段：

┌─────────────────────────────────────────────────────────────────┐
│                      sage-wiki 编译流水线                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [源文件] → [解析器] → [摘要器] → [概念提取] → [文章生成] → [Lint] │
│     ↓          ↓          ↓           ↓           ↓         ↓   │
│  raw/*.md   纯文本     2000字摘要   概念列表    Wiki文章   质量检查  │
│  raw/*.pdf  + 元数据   (LLM调用)   (LLM调用)   (LLM调用)  (LLM调用) │
│  ...                                                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

阶段 1：解析（Parsing）

• 根据文件扩展名选择解析器
• PDF 用纯 Go 提取（无需外部依赖）
• Word/Excel/PPT 从 XML 中提取文本
• 图片调用视觉 LLM（Gemini/Claude/GPT-4o）生成描述

阶段 2：摘要（Summarization）

• 每个文档生成约 2000 字的摘要
• 保留核心论点、关键数据、方法论
• 根据文档类型使用不同 prompt（论文 vs 文章 vs 代码）

阶段 3：概念提取（Concept Extraction）

• LLM 识别文档中的核心概念
• 每个概念生成简短描述
• 记录概念之间的关联关系

阶段 4：文章生成（Article Writing）

• 为每个概念生成独立的 Wiki 文章
• 自动创建 [[wikilink]] 交叉引用
• 文章长度约 4000 tokens

阶段 5：Lint（质量检查）

• 检查断裂链接
• 验证文章结构
• 修复格式问题

2.2 数据结构

编译后的 Wiki 目录结构：

wiki/
├── _index.md              # Wiki 首页
├── concepts/              # 概念文章（LLM 生成）
│   ├── attention-mechanism.md
│   ├── transformer-architecture.md
│   └── knowledge-distillation.md
├── summaries/             # 源文档摘要
│   ├── papers/
│   │   └── attention-is-all-you-need.md
│   └── articles/
│       └── understanding-transformers.md
└── outputs/               # Q&A 保存的答案
    └── saved-answer-2026-04-10.md

2.3 配置文件设计

sage-wiki init 生成的 config.yaml：

version: 1
project: my-research
description: "Personal research wiki"

sources:
  - path: raw
    type: auto      # 自动检测格式
    watch: true     # 监听文件变化

output: wiki

api:
  provider: gemini
  api_key: ${GEMINI_API_KEY}  # 支持环境变量

models:
  summarize: gemini-3-flash-preview  # 摘要用便宜模型
  extract: gemini-3-flash-preview    # 概念提取
  write: gemini-3-flash-preview      # 文章生成
  lint: gemini-3-flash-preview       # 质量检查
  query: gemini-3-flash-preview      # Q&A

compiler:
  max_parallel: 4           # 并发 LLM 调用
  debounce_seconds: 2       # watch 模式防抖
  summary_max_tokens: 2000
  article_max_tokens: 4000
  auto_commit: true         # 编译后自动 git commit
  auto_lint: true

search:
  hybrid_weight_bm25: 0.7   # BM25 权重
  hybrid_weight_vector: 0.3 # 向量权重
  default_limit: 10

关键设计点：

• 不同任务用不同模型：摘要/提取用 Flash（便宜），写作可以升级到 Pro（质量）
• 支持多种 LLM 提供商：Anthropic、OpenAI、Gemini、Ollama、OpenRouter
• 环境变量展开：敏感信息不硬编码

2.4 MCP 服务器

sage-wiki 可以作为 MCP 服务器运行：

sage-wiki serve --transport stdio

这让任何支持 MCP 的 LLM Agent（如 Claude Desktop、Cursor）都能：

• 搜索你的 Wiki
• 读取文章内容
• 基于 Wiki 回答问题

MCP 配置示例（Claude Desktop）：

{
  "mcpServers": {
    "sage-wiki": {
      "command": "sage-wiki",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/your/wiki"
    }
  }
}

三、代码实战：从零搭建一个研究 Wiki

3.1 安装

# 纯 CLI 版本（无 Web UI）
go install github.com/xoai/sage-wiki/cmd/sage-wiki@latest

# 带 Web UI 版本
git clone https://github.com/xoai/sage-wiki.git
cd sage-wiki
cd web && npm install && npm run build && cd ..
go build -tags webui -o sage-wiki ./cmd/sage-wiki/

3.2 初始化项目

mkdir my-wiki && cd my-wiki
sage-wiki init

# 输出：
# Created config.yaml
# Created raw/ (source folder)
# Created wiki/ (output folder)

3.3 添加源文档

# 复制你的论文
cp ~/papers/*.pdf raw/papers/

# 复制你的文章收藏
cp ~/articles/*.md raw/articles/

# 甚至可以加代码
cp ~/projects/my-project/*.go raw/code/

3.4 配置 API Key

编辑 config.yaml：

api:
  provider: gemini
  api_key: ${GEMINI_API_KEY}

# 或者直接写 key（不推荐）
# api_key: "your-api-key-here"

3.5 首次编译

sage-wiki compile

# 输出示例：
# Scanning raw/...
# Found 47 sources (12 PDFs, 28 Markdown, 7 code files)
# Compiling...
# [1/47] Summarizing papers/attention-is-all-you-need.pdf...
# [2/47] Summarizing articles/transformer-explained.md...
# ...
# Extracting concepts...
# Writing articles...
# Linting...
# Done! Generated 156 concept articles in wiki/
# 
# Token usage: 1,234,567 input, 234,567 output
# Estimated cost: $0.12 (using gemini-3-flash)

3.6 搜索与问答

# 混合搜索
sage-wiki search "attention mechanism"

# 输出：
# [0.89] concepts/attention-mechanism.md
#   > Attention mechanism allows the model to focus on relevant parts...
# [0.82] summaries/papers/attention-is-all-you-need.md
#   > We propose a new simple network architecture, the Transformer...

# 自然语言问答
sage-wiki query "How does flash attention optimize memory usage?"

# 输出（带引用）：
# Flash Attention optimizes memory by computing attention in blocks
# rather than materializing the full N×N attention matrix...
# 
# Sources:
# - [summaries/papers/flash-attention.pdf]
# - [concepts/memory-efficient-attention.md]

3.7 监听模式

# 自动增量编译
sage-wiki compile --watch

# 现在，每次你往 raw/ 添加文件，sage-wiki 自动编译

3.8 与 Obsidian 配合

sage-wiki 的输出格式完全兼容 Obsidian：

# 在 Obsidian 中打开 wiki/ 文件夹即可
# 所有 [[wikilink]] 都能正常跳转

你甚至可以直接在现有 Obsidian Vault 上运行 sage-wiki：

cd ~/Documents/MyVault
sage-wiki init --vault
# 这会创建 _wiki/ 输出目录，不影响现有笔记

四、性能优化：如何低成本运行大规模编译

4.1 成本估算

假设你有 100 篇论文，每篇平均 10 页：

用 Gemini Flash，100 篇论文编译成 Wiki 只要 17 美分。

4.2 Prompt Caching

sage-wiki 默认启用 Prompt Caching：

compiler:
  prompt_cache: true  # 默认开启

效果：

• Anthropic/Gemini：显式缓存 system prompt
• OpenAI：自动缓存

节省 50-90% 输入 Token。

4.3 Batch API

对于大批量编译，可以用 Batch API 省 50%：

# 提交批处理任务
sage-wiki compile --batch

# 轮询状态，完成后自动获取结果
sage-wiki compile

支持的提供商：Anthropic、OpenAI

4.4 预估成本

sage-wiki compile --estimate

# 输出：
# Sources: 47 files
# Estimated tokens: 1,234,567 input, 234,567 output
# Estimated cost: $0.12 (gemini-3-flash)
# 
# Proceed? [y/N]

或在配置中启用每次预估：

compiler:
  estimate_before: true  # 每次编译前提示

4.5 自动模式

compiler:
  mode: auto
  batch_threshold: 10  # 10+ 源文件自动用 Batch API

五、进阶用法

5.1 自定义 Prompt

sage-wiki init --prompts

生成可编辑的 prompt 文件：

prompts/
├── summarize-article.md   # 文章摘要 prompt
├── summarize-paper.md     # 论文摘要 prompt
├── write-article.md       # 概念文章 prompt
├── extract-concepts.md    # 概念提取 prompt
└── caption-image.md       # 图片描述 prompt

你可以调整：

• 文章风格（学术 vs 通俗）
• 概念粒度（粗粒度 vs 细粒度）
• 输出格式（标准 Markdown vs 带自定义字段）

5.2 Web UI

如果你编译时带了 -tags webui：

sage-wiki serve --ui
# 打开 http://127.0.0.1:3333

功能：

• 文章浏览（Markdown 渲染 + 语法高亮）
• 混合搜索（实时结果 + 片段预览）
• 知识图谱（力导向可视化）
• 流式 Q&A（带来源引用）
• 深色/浅色主题

5.3 Terminal UI

纯命令行也有完整的 TUI：

sage-wiki tui

4 个标签页：

• F1 Browse：按分类浏览文章，Glamour 渲染 Markdown
• F2 Search：模糊搜索，分屏预览
• F3 Q&A：对话式问答，Ctrl+S 保存答案
• F4 Compile：实时编译仪表板

5.4 图片处理

sage-wiki 支持图片，但需要视觉 LLM：

api:
  provider: gemini  # 或 anthropic、openai

处理流程：

1. 调用视觉 LLM（如 GPT-4o）生成图片描述
2. 描述存为 Markdown
3. 参与后续概念提取

适用场景：

• 论文中的图表
• 架构图
• UI 截图

5.5 代码作为知识源

# 把项目代码也纳入 Wiki
cp ~/projects/my-project/*.go raw/code/
sage-wiki compile

sage-wiki 会：

• 提取代码中的函数、类型定义
• 理解代码逻辑
• 生成「代码概念」文章

六、与其他工具对比

sage-wiki 的独特价值：

1. 编译器思维：知识管理变成「丢文件→编译→出 Wiki」
2. Agent 就绪：MCP 接口让任何 AI 都能访问你的知识
3. 增量复利：新文档自动丰富现有概念文章

七、最佳实践

7.1 组织源文件

raw/
├── papers/        # 学术论文
├── articles/      # 技术文章
├── notes/         # 个人笔记
├── code/          # 项目代码
└── images/        # 图表截图

7.2 定期增量编译

# 用 cron 或 systemd 定时任务
# 每小时编译一次
0 * * * * cd ~/my-wiki && sage-wiki compile --batch

7.3 版本控制 Wiki

compiler:
  auto_commit: true  # 自动 git commit

这样你可以：

• 回溯知识演变
• 对比不同时间点的理解
• 用 git blame 追踪概念来源

7.4 多项目管理

~/wikis/
├── research/      # 研究笔记
├── work/          # 工作文档
└── personal/      # 个人学习

每个项目独立配置，独立 LLM 提供商。

八、局限与未来

8.1 当前局限

1. 无实时协作：本地文件系统，多用户需手动同步
2. 无原生移动端：Web UI 可在手机浏览器访问
3. 概念质量依赖 LLM：低质量模型可能提取无关概念
4. 语言支持：目前主要优化英文，中文需调整 prompt

8.2 Roadmap（基于代码推断）

• 更多解析器（视频转录、音频转文字）
• 向量数据库后端（ChromaDB、Pinecone）
• 协作模式（多用户同步）
• 可视化编辑器
• 插件系统

总结：知识管理的新范式

sage-wiki 不是一个「更好的笔记工具」，而是一次范式转变：

旧范式：手动整理 → 高维护成本 → 知识碎片化 → 放弃整理
新范式：自动编译 → 零维护成本 → 知识网络化 → 复利增长

Karpathy 的想法被实现了，而且比想象中更好：

• 15 种格式支持，不只是 Markdown
• MCP 接口，让 AI Agent 也能访问你的知识
• 增量编译，新文档自动丰富旧知识
• 成本极低，100 篇论文只要 17 美分

如果你有大量 PDF 论文、Markdown 文章、代码项目，不妨试试：

go install github.com/xoai/sage-wiki/cmd/sage-wiki@latest
mkdir my-wiki && cd my-wiki
sage-wiki init
cp ~/papers/*.pdf raw/
sage-wiki compile

三分钟后，你就有了一个结构化的、可搜索的、AI 可访问的知识 Wiki。

知识管理，终于可以「编译」了。

项目地址：https://github.com/xoai/sage-wiki
Stars：319（截至 2026-04-10）
License：MIT
语言：Go
作者：xoai 团队（基于 Andrej Karpathy 的想法）