Karpathy 的 LLM Wiki 调研报告

调研时间：2025-06-20
核心来源：Karpathy Gist (karpathy/442a6bf555914893e9891c11519de94f)、balukosuri/llm-wiki-karpathy、MindStudio 博客

一、核心概念

1.1 什么是 LLM Wiki

LLM Wiki 是 Andrej Karpathy 提出的一种个人知识库构建模式，核心理念是：

不用每次查询时从原始文档重新检索（RAG 模式），LLM 增量构建并维护一个持久的 wiki—— 一个结构化的、带交叉链接的 markdown 文件集合，介于你和原始来源之间。

RAG vs LLM Wiki 的本质区别：

Karpathy 的原话：

“Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up.”

“The wiki is a persistent, compounding artifact. The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you’ve read.”

二、三层架构

LLM Wiki 包含三个层次：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

┌─────────────────────────────────────────────────────────┐
│                    THE SCHEMA                           │
│  CLAUDE.md / AGENTS.md                                  │
│  定义 wiki 结构、约定俗成、工作流程                      │
│  (LLM 的操作手册，决定它是有纪律的 wiki 维护者            │
│   而非通用聊天机器人)                                    │
├─────────────────────────────────────────────────────────┤
│                      THE WIKI                           │
│  wiki/ 目录                                             │
│  LLM 生成和维护的 markdown 文件集合                      │
│  - 摘要页、实体页、概念页、对比页、概述页                 │
│  LLM 完全拥有这一层，人类只读不写                         │
├─────────────────────────────────────────────────────────┤
│                   RAW SOURCES                            │
│  sources/ 目录                                          │
│  原始文档的精选集合                                      │
│  不可变 — LLM 只读，从不修改                             │
│  这是你的信任源（source of truth）                       │
└─────────────────────────────────────────────────────────┘

各层职责

三、核心操作（CRUD）

3.1 Ingest（摄取）

当你向原始集合放入新来源并告诉 LLM 处理时，典型流程：

1. LLM 读取来源，与你讨论关键收获
2. 在 wiki 中撰写摘要页
3. 更新 index
4. 更新相关的实体页和概念页
5. 记录新数据与旧 claims 矛盾的地方
6. 向 log.md 追加条目

一个来源可能触及 10-15 个 wiki 页面。

Karpathy 个人偏好逐个摄取来源并保持参与 —— 读摘要、检查更新、指导 LLM 强调什么。但也可以批量摄取。

3.2 Query（查询）

你针对 wiki 提问。LLM 搜索相关页面，读它们，综合出带引用的答案。

答案可以是不同形式 ——markdown 页面、对比表格、幻灯片（Marp）、图表（matplotlib）、canvas。重要洞察：好的答案可以被归档回 wiki 成为新页面。这样你的探索就像摄取来源一样在知识库中积累。

3.3 Lint（健康检查）

定期让 LLM 对 wiki 做健康检查：

• 页面间的矛盾
• 被新来源取代的陈旧 claims
• 没有入站链接的孤立页面
• 被提及但没有自己页面的重要概念
• 缺失的交叉引用
• 可以通过网络搜索填补的数据空白

四、两个特殊文件

4.1 index.md（内容导向）

wiki 的目录 —— 每个页面列出，带链接、一行摘要、可选元数据（如日期或来源数量）。按类别组织（实体、概念、来源等）。

LLM 在每次摄取时更新它。在回答查询时，LLM 先读 index 找到相关页面，再深入阅读。

在中等规模（~100 个来源，数百页面）下，这种方式出奇地有效，避免了 embedding-based RAG 基础设施的必要性。

4.2 log.md（时间导向）

append-only 的操作记录 —— 摄取、查询、lint 过程。格式：## [2026-04-02] ingest | Article Title。

实用技巧：每条以一致前缀开头，log 就可以用简单 unix 工具解析 ——grep "^## \[" log.md | tail -5 给你最近 5 条。log 给出 wiki 演化的时间线，并帮助 LLM 理解最近做了什么。

五、工作界面：Obsidian + AI Agent

Karpathy 的实际工作方式：

“In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.”

1
2
3
4
5
6
7
8
9

┌─────────────────────┬─────────────────────┐
│   AI Agent (Cursor / │   Obsidian           │
│   Claude Code)       │   (浏览 wiki)          │
│                       │                       │
│  • 读取源文档          │  • 实时查看页面更新     │
│  • 撰写/更新 wiki     │  • Graph View 查看    │
│  • 回答问题            │    连接结构           │
│  • 执行 lint           │  • 跟随链接探索        │
└─────────────────────┴─────────────────────┘

Obsidian 的关键插件

图片处理

LLM 不能原生在一个 Pass 中读取带内联图片的 markdown。解决方案：

1. 在 Obsidian 设置中将附件文件夹路径设为固定目录（如 raw/assets/）
2. 用热键绑定” 下载当前文件的所有附件”（Ctrl+Shift+D）
3. 让 LLM 先读文本，再单独查看引用的一些图片以获得额外上下文

六、balukosuri 实现的完整目录结构

这是社区实现 balukosuri/llm-wiki-karpathy 的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

llm-wiki-karpathy/
├── CLAUDE.md              # Schema — AI 的操作手册
├── llm-wiki.md            # Karpathy 原始 idea 文档
├── article.md             # 阐述本项目的文章
│
├── raw/                   # 源文档（AI 读取，从不写入）
│   └── .gitkeep
│
├── wiki/                  # AI 生成的 knowledge base（AI 拥有此层）
│   ├── index.md          # 主目录 — AI 每次查询先读它
│   ├── overview.md       # 大局综合（随每次摄取演化）
│   ├── glossary.md        # 术语、定义和风格约定
│   ├── log.md            # 所有活动的 chronological 记录
│   ├── sources/          # 源文档摘要页
│   ├── features/         # 产品功能页
│   ├── products/         # 产品/工具页
│   ├── personas/         # 用户类型页
│   ├── concepts/         # 领域概念页
│   ├── style/            # 写作约定页
│   └── analyses/         # 综合输出页（对比表、gap 分析等）
│
└── .obsidian/            # 预配置的 Obsidian vault 设置

Wiki 页面类型详解

七、典型工作流示例

场景：产品经理构建竞争分析知识库

步骤 1：初始化

1
2
3

在 Cursor 中打开项目文件夹
在 Obsidian 中打开同一文件夹作为 vault
两个窗口并排放置

步骤 2：摄取来源

1
2
3
4

将某竞品的 PRD PDF 放入 raw/ 文件夹
在 Cursor 中输入：ingest raw/competitor-prd.pdf
LLM 读取文档，讨论关键收获，创建摘要页，更新相关功能/概念页
在 Obsidian 中实时观察页面出现

步骤 3：提问

1
2
3

在 Cursor 中输入：What are the main risks identified across all my sources?
LLM 读 wiki，综合出带引用的答案，并问："Should I save this as a wiki page?"
你说"是"，答案成为永久的分析页面

步骤 4：定期 lint

1
2
3

每 10 次摄取左右，在 Cursor 中输入：lint the wiki
LLM 检查矛盾、陈旧 claims、孤立页面、缺失链接
报告发现，问你哪些修复要应用

八、适用场景

九、为什么维护负担接近零

Karpathy 的核心洞察：

“The tedious part of maintaining a knowledge base is not the reading or the thinking — it’s the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass.”

人类放弃 wiki 是因为维护负担增长快于价值。LLM 不会厌倦、不会忘记更新交叉引用、可以一次触及 15 个文件。维护成本接近零，wiki 就能保持更新。

人类 vs LLM 的分工

十、与 Memex 的思想联系

Karpathy 指出这个想法在精神上与 Vannevar Bush’s Memex (1945) 相关 —— 一种个人策划的知识存储，带有文档间的关联轨迹。

Bush 的愿景比 Web 更接近此：私人的、积极策划的，文档间的连接与文档本身一样有价值。他无法解决的是谁来维护。LLM 解决了这个问题。

十一、行业实现

社区实现

levelup.gitconnected 详细架构

文章提供了完整的 Python 实现架构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

LLM_wiki/
├── main.py                 # 入口: python main.py <command>
├── pyproject.toml
├── requirements.txt
├── .env                    # API keys
├── llm_wiki/
│   ├── cli.py             # Click CLI: init/ingest/query/lint/status/prompts
│   ├── config.py          # WikiSchema, PageSpec dataclasses
│   ├── prompts.py         # 所有 Claude prompts + 24 QUERY_TEMPLATES
│   ├── embeddings.py      # OpenAI text-embedding-3-small wrapper
│   ├── index.py           # EmbeddingIndex: cosine similarity search
│   ├── wiki.py            # WikiPage CRUD (markdown + YAML front matter)
│   ├── ingest.py          # Route → Synthesize → Embed → Index pipeline
│   ├── query.py           # Embed → Search → Assemble → Stream pipeline
│   └── lint.py            # Health checks: orphans/broken xrefs/stale embeddings
├── sources/               # Raw input documents (immutable)
├── wiki/                  # LLM-maintained knowledge base
│   ├── index.md           # Auto-updated page catalog
│   ├── log.md             # Append-only operation history
│   ├── neural_networks.md
│   ├── backpropagation.md
│   ├── attention_mechanism.md
│   ├── transformers.md
│   └── applications.md
└── .meta/
    ├── schema.json        # Page universe definition (PageSpec list)
    └── embeddings.json    # Vector index (OpenAI 1536-dim per page)

十二、与 RAG 的对比总结

十三、引用来源

本报告数据来源：Karpathy Gist (llm-wiki.md)、balukosuri/llm-wiki-karpathy (GitHub README)、MindStudio 博客 (2026-04-06)。

测试文章

这是一篇测试文章，用于验证 Hexo 文章发布流程。

测试内容

• 测试 front-matter 自动添加
• 测试 GitHub Actions 自动部署
• 测试博客页面显示

结语

如果能看到这篇文章，说明发布流程正常。

Superpowers 用户手册

面向 AI 编程代理的完整软件开发方法论

目录

1. 产品简介
2. 安装指南
3. 核心工作流程
4. 技能库详解
5. 方法论哲学
6. 故障排除
7. 附录

一、产品简介

1.1 什么是 Superpowers

Superpowers 是一套完整的软件开发方法论，专为 AI 编程代理（coding agents）设计，基于一组可组合的技能（skills）和初始化指令构建。它让 AI 代理从” 直接写代码” 转变为” 先理解需求、再规划、最后执行” 的专业开发流程。

1.2 核心能力

1.3 工作原理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

你启动编程代理
    ↓
代理感知到你在构建项目
    ↓
【brainstorming】激活 — 追问真实需求，分段展示设计
    ↓
你审核并签署设计
    ↓
【writing-plans】激活 — 制定可执行的小任务计划
    ↓
你说"开始"
    ↓
【subagent-driven-development】激活 — 子代理逐任务执行
    ↓
每个任务经过：RED → GREEN → REFACTOR → 提交
    ↓
【finishing-a-development-branch】激活 — 测试验证、合并决策

二、安装指南

2.1 支持平台总览

2.2 各平台详细步骤

Claude Code（官方市场）

1

/plugin install superpowers@claude-plugins-official

Claude Code（Superpowers 市场）

1
2
3
4
5

# 1. 注册市场
/plugin marketplace add obra/superpowers-marketplace

# 2. 从该市场安装
/plugin install superpowers@superpowers-marketplace

OpenAI Codex CLI

1
2
3
4
5
6

# 打开插件搜索
/plugins

# 搜索并安装
superpowers
# 选择 "Install Plugin"

OpenAI Codex App

1. 点击侧边栏 Plugins
2. 在 Coding 分区找到 Superpowers
3. 点击旁边的 + 并跟随提示操作

Cursor

在 Cursor Agent 聊天中执行：

1

/add-plugin superpowers

或直接在插件市场搜索 “superpowers”。

OpenCode

在 opencode.json（全局或项目级）的 plugin 数组中添加：

1
2
3

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

重启 OpenCode 后生效。验证方法：询问 “Tell me about your superpowers”。

详细文档： docs/README.opencode.md

GitHub Copilot CLI

1
2
3
4
5

# 添加市场
copilot plugin marketplace add obra/superpowers-marketplace

# 安装插件
copilot plugin install superpowers@superpowers-marketplace

Gemini CLI

1
2
3
4
5

# 安装
gemini extensions install https://github.com/obra/superpowers

# 更新
gemini extensions update superpowers

2.3 验证安装

安装完成后，向代理发送：

1

Tell me about your superpowers

代理应返回 Superpowers 技能系统介绍。

三、核心工作流程

3.1 七阶段开发流程

Superpowers 定义了 7 个严格按顺序执行的阶段，代理在每个阶段自动触发对应技能：

阶段 1：brainstorming（头脑风暴）

触发时机：代理感知到你正在构建某个项目，尚未开始写代码

执行内容：

• 通过苏格拉底式提问澄清模糊想法
• 探索替代方案
• 分段向用户展示设计（每段足够短，便于阅读和消化）
• 保存设计文档

产出：经用户签署同意的设计文档

阶段 2：using-git-worktrees（Git 工作树）

触发时机：设计获得批准后

执行内容：

• 在新分支上创建隔离的工作空间
• 运行项目初始化
• 验证干净的测试基线

产出：隔离的开发环境，测试通过

阶段 3：writing-plans（编写计划）

触发时机：设计获批后，启动实现前

执行内容：

• 将工作拆解为 2-5 分钟的小任务
• 每个任务包含：精确文件路径、完整代码、验证步骤

产出：可执行的任务清单

阶段 4：subagent-driven-development / executing-plans（子代理驱动开发 / 执行计划）

触发时机：计划制定完毕，用户说” 开始”

执行内容：

• 每个任务派发一个全新子代理
• 两阶段审查：规范合规性 → 代码质量
• 或批量执行，设置人工检查点

特殊能力：Claude 可自主工作数小时而不偏离计划

阶段 5：test-driven-development（测试驱动开发）

触发时机：实现过程中

执行内容：
严格 RED - GREEN - REFACTOR 循环：

1. RED — 写一个会失败的测试
2. GREEN — 写最少代码让它通过
3. REFACTOR — 重构优化
4. 提交

⚠️ 强制规则：测试通过前的代码一律删除

阶段 6：requesting-code-review（请求代码审查）

触发时机：任务之间

执行内容：

• 根据计划审查代码
• 按严重级别报告问题
• 严重问题阻塞进度

阶段 7：finishing-a-development-branch（完成开发分支）

触发时机：任务全部完成

执行内容：

• 验证测试全部通过
• 提供选项：合并 / 创建 PR / 保留 / 丢弃
• 清理工作树

3.2 流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

启动代理
    ↓
brainstorming ← 你说"帮我做个 XX"
    ↓
你审核设计（分段展示）
    ↓
using-git-worktrees（创建隔离分支）
    ↓
writing-plans（拆解任务清单）
    ↓
你说"go"或"开始"
    ↓
subagent-driven-development
    ↓
每个任务：TDD 循环 → 代码审查
    ↓
finishing-a-development-branch
    ↓
你选择：合并 / PR / 保留 / 丢弃

四、技能库详解

4.1 测试类

4.2 调试类

4.3 协作类

4.4 元技能类

五、方法论哲学

5.1 四大核心原则

5.2 设计理念

• YAGNI（You Aren’t Gonna Need It）— 不提前实现不需要的功能
• DRY（Don’t Repeat Yourself）— 避免重复
• 真 TDD — 严格遵循红→绿→重构，而非” 测试后写”
• 纵深防御 — 调试时追根溯源，不治标不治本

六、故障排除

Q1：安装后代理没有响应 Superpowers 技能

现象：发送 “Tell me about your superpowers” 无反应

可能原因：

• 插件未成功加载
• 平台不支持自动技能触发

解决：

1. 重启代理会话
2. 确认安装命令执行无报错
3. 检查平台是否需要手动加载技能

Q2：brainstorming 阶段代理跳过直接写代码

现象：代理收到任务后立即开始写代码

可能原因：代理未感知到” 这是一个需要澄清的项目”

解决：明确告诉代理” 请先帮我澄清需求”，或主动说” 我想做一个 XX，先讨论下设计”

Q3：TDD 循环中测试写在了实现代码之后

现象：代码已经写完，测试才补上

可能原因：TDD 技能未被正确触发

解决：直接指令” 请用 TDD 方式，先写测试再看它失败”

Q4：子代理执行时间过长无法跟踪

现象：代理自主运行数小时，无法判断当前状态

解决：Superpowers 设计为可安全长时间自主运行。如需中断，直接 Ctrl + C，代理会在当前任务完成后停止

Q5：设计文档丢失或未保存

现象：brainstorming 后的设计内容没有持久化

可能原因：会话上下文窗口耗尽

解决：在 brainstorming 开始前说” 请将设计保存到 design.md”，代理会自动持久化

Q6：多平台安装，技能行为不一致

现象：同一仓库在不同平台表现不同

可能原因：各平台对 Superpowers 技能的支持程度不同

解决：参考 Platform Support，优先在 Claude Code 和 OpenCode 上使用完整功能

七、附录

7.1 项目信息

7.2 资源链接

7.3 CLI 速查表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Claude Code - 官方市场安装
/plugin install superpowers@claude-plugins-official

# Claude Code - Superpowers 市场安装
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# GitHub Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers
gemini extensions update superpowers

# Cursor
/add-plugin superpowers

7.4 七阶段速查

本文档基于 Superpowers v1.0 README 编制，如有更新请以 GitHub 仓库 最新内容为准。

AGENTS.md 开源项目调研报告

调研时间：2025-06-20
信息来源：GitHub、Web Search、Raw Content 抓取

一、AGENTS.md 是什么

AGENTS.md 是一个开放的 Markdown 格式，旨在为 AI 编程代理提供项目级上下文和指令，定位为”AI 代理的 README“（README for agents）。

它解决的核心问题：团队没有统一机制告诉 AI 代理” 如何构建、测试、部署本项目”，导致 AI 代理每次都需要从代码库中自行推断规则，容易出错且效率低下。

二、核心项目生态

2.1 官方规范与网站

这是整个生态的核心源头项目，定义了 AGENTS.md 格式规范。

2.2 生产级示例

Apache Airflow 的 AGENTS.md 是最知名的生产级参考，包含：

• Breeze 容器环境使用规范
• prek 提交钩子配置
• 多 providers 包测试规范
• Monorepo 下的包选择逻辑

2.3 生态工具

Ruler — 多代理指令分发工具

支持的代理格式对照（部分）

2.4 相关规范项目

Agent-Specification

定义了智能体的标准属性：Identity、Ownership、Business Context、Technical Configuration、Dependencies、Security 等。

SPEC-AGENTS.md

三、格式规范

3.1 标准结构

AGENTS.md 本身是 Markdown 文件，无强制 schema，典型结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 项目名称

## Dev environment tips
- 环境搭建技巧
- 包管理器命令

## Testing instructions
- 测试运行方式
- 覆盖率要求

## Build instructions
- 构建步骤
- 产物路径

## Conventions
- 代码风格
- 提交流程

3.2 各平台读取优先级

OpenAI Codex 读取顺序：

1
2
3
4
5

1. ~/.codex/AGENTS.override.md（最高优先级）
2. ~/.codex/AGENTS.md
3. 仓库根目录 AGENTS.md
4. 仓库根目录 TEAM_GUIDE.md
5. 仓库根目录 .agents.md

Ruler 优先级：

1
2
3
4

1. 仓库根 AGENTS.md（最高）
2. .ruler/AGENTS.md（新默认）
3. .ruler/instructions.md（仅旧版兼容）
4. .ruler/*.md（递归，按字母序）

四、竞争格式

这些格式都与 AGENTS.md 目标相同，但工具锁定。AGENTS.md 的优势在于通用性 —— 一个格式，多工具兼容（通过 Ruler 等工具分发）。

五、采用情况

• ⭐ 20.4k+ stars（agentsmd / agents.md 官方仓库）
• Apache Airflow、Apache TVM 等顶级开源项目已采用
• OpenAI Codex、GitHub Copilot、Google Gemini CLI 等主流代理均原生支持
• 微软 VS Code 官方文档已收录 AGENTS.md 说明
• 生态工具 Ruler 支持 30+ 代理，覆盖主流开发环境

六、关键洞察

1. AGENTS.md 已成事实标准 — 20.4k stars 和 Apache 顶级项目的采用，确立了其行业地位
2. 工具碎片化是最大痛点 — 30+ 代理各有专用格式，Ruler 等工具提供” 一个源、分发多端” 的桥接层
3. 格式本身极度简单 — 就是 Markdown，无强制 schema，门槛极低；但也因此缺乏约束，不同项目的 AGENTS.md 质量差异大
4. 与 Superpowers 高度互补 — Superpowers 是 AI 代理的工作流程方法论（如何执行），AGENTS.md 是项目上下文定义（做什么），两者可叠加使用

七、资源链接

本报告数据来源：GitHub API / Raw Content、Web Search，star 数据基于 2025-06-20 抓取。

Karpathy 的 LLM Wiki 调研报告

调研时间：2025-06-20
核心来源：Karpathy Gist (karpathy/442a6bf555914893e9891c11519de94f)、balukosuri/llm-wiki-karpathy、MindStudio 博客

一、核心概念

1.1 什么是 LLM Wiki

LLM Wiki 是 Andrej Karpathy 提出的一种个人知识库构建模式，核心理念是：

不用每次查询时从原始文档重新检索（RAG 模式），LLM 增量构建并维护一个持久的 wiki—— 一个结构化的、带交叉链接的 markdown 文件集合，介于你和原始来源之间。

RAG vs LLM Wiki 的本质区别：

Karpathy 的原话：

“Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up.”

“The wiki is a persistent, compounding artifact. The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you’ve read.”

二、三层架构

LLM Wiki 包含三个层次：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

┌─────────────────────────────────────────────────────────┐
│                    THE SCHEMA                           │
│  CLAUDE.md / AGENTS.md                                  │
│  定义 wiki 结构、约定俗成，工作流程                      │
│  (LLM 的操作手册，决定它是有纪律的 wiki 维护者            │
│   而非通用聊天机器人)                                    │
├─────────────────────────────────────────────────────────┤
│                      THE WIKI                           │
│  wiki/ 目录                                             │
│  LLM 生成和维护的 markdown 文件集合                      │
│  - 摘要页、实体页、概念页、对比页、概述页                 │
│  LLM 完全拥有这一层，人类只读不写                         │
├─────────────────────────────────────────────────────────┤
│                   RAW SOURCES                            │
│  sources/ 目录                                          │
│  原始文档的精选集合                                      │
│  不可变 — LLM 只读，从不修改                             │
│  这是你的信任源（source of truth）                       │
└─────────────────────────────────────────────────────────┘

各层职责

三、核心操作（CRUD）

3.1 Ingest（摄取）

当你向原始集合放入新来源并告诉 LLM 处理时，典型流程：

1. LLM 读取来源，与你讨论关键收获
2. 在 wiki 中撰写摘要页
3. 更新 index
4. 更新相关的实体页和概念页
5. 记录新数据与旧 claims 矛盾的地方
6. 向 log.md 追加条目

一个来源可能触及 10-15 个 wiki 页面。

Karpathy 个人偏好逐个摄取来源并保持参与 —— 读摘要、检查更新、指导 LLM 强调什么。但也可以批量摄取。

3.2 Query（查询）

你针对 wiki 提问。LLM 搜索相关页面，读它们，综合出带引用的答案。

答案可以是不同形式 ——markdown 页面、对比表格、幻灯片（Marp）、图表（matplotlib）、canvas。重要洞察：好的答案可以被归档回 wiki 成为新页面。这样你的探索就像摄取来源一样在知识库中积累。

3.3 Lint（健康检查）

定期让 LLM 对 wiki 做健康检查：

• 页面间的矛盾
• 被新来源取代的陈旧 claims
• 没有入站链接的孤立页面
• 被提及但没有自己页面的重要概念
• 缺失的交叉引用
• 可以通过网络搜索填补的数据空白

四、两个特殊文件

4.1 index.md（内容导向）

wiki 的目录 —— 每个页面列出，带链接、一行摘要、可选元数据（如日期或来源数量）。按类别组织（实体、概念、来源等）。

LLM 在每次摄取时更新它。在回答查询时，LLM 先读 index 找到相关页面，再深入阅读。

在中等规模（~100 个来源，数百页面）下，这种方式出奇地有效，避免了 embedding-based RAG 基础设施的必要性。

4.2 log.md（时间导向）

append-only 的操作记录 —— 摄取、查询、lint 过程。格式：## [2026-04-02] ingest | Article Title。

实用技巧：每条以一致前缀开头，log 就可以用简单 unix 工具解析 ——grep "^## \[" log.md | tail -5 给你最近 5 条。log 给出 wiki 演化的时间线，并帮助 LLM 理解最近做了什么。

五，工作界面：Obsidian + AI Agent

Karpathy 的实际工作方式：

“In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.”

1
2
3
4
5
6
7
8
9

┌─────────────────────┬─────────────────────┐
│   AI Agent (Cursor / │   Obsidian           │
│   Claude Code)       │   (浏览 wiki)          │
│                       │                       │
│  • 读取源文档          │  • 实时查看页面更新     │
│  • 撰写/更新 wiki     │  • Graph View 查看    │
│  • 回答问题            │    连接结构           │
│  • 执行 lint           │  • 跟随链接探索        │
└─────────────────────┴─────────────────────┘

Obsidian 的关键插件

图片处理

LLM 不能原生在一个 Pass 中读取带内联图片的 markdown。解决方案：

1. 在 Obsidian 设置中将附件文件夹路径设为固定目录（如 raw/assets/）
2. 用热键绑定” 下载当前文件的所有附件”（Ctrl+Shift+D）
3. 让 LLM 先读文本，再单独查看引用的一些图片以获得额外上下文

六、balukosuri 实现的完整目录结构

这是社区实现 balukosuri/llm-wiki-karpathy 的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

llm-wiki-karpathy/
├── CLAUDE.md              # Schema — AI 的操作手册
├── llm-wiki.md            # Karpathy 原始 idea 文档
├── article.md             # 阐述本项目的文章
│
├── raw/                   # 源文档（AI 读取，从不写入）
│   └── .gitkeep
│
├── wiki/                  # AI 生成的 knowledge base（AI 拥有此层）
│   ├── index.md          # 主目录 — AI 每次查询先读它
│   ├── overview.md       # 大局综合（随每次摄取演化）
│   ├── glossary.md        # 术语、定义和风格约定
│   ├── log.md            # 所有活动的 chronological 记录
│   ├── sources/          # 源文档摘要页
│   ├── features/         # 产品功能页
│   ├── products/         # 产品/工具页
│   ├── personas/         # 用户类型页
│   ├── concepts/         # 领域概念页
│   ├── style/            # 写作约定页
│   └── analyses/         # 综合输出页（对比表、gap 分析等）
│
└── .obsidian/            # 预配置的 Obsidian vault 设置

Wiki 页面类型详解

七、典型工作流示例

场景：产品经理构建竞争分析知识库

步骤 1：初始化

1
2
3

在 Cursor 中打开项目文件夹
在 Obsidian 中打开同一文件夹作为 vault
两个窗口并排放置

步骤 2：摄取来源

1
2
3
4

将某竞品的 PRD PDF 放入 raw/ 文件夹
在 Cursor 中输入：ingest raw/competitor-prd.pdf
LLM 读取文档，讨论关键收获，创建摘要页，更新相关功能/概念页
在 Obsidian 中实时观察页面出现

步骤 3：提问

1
2
3

在 Cursor 中输入：What are the main risks identified across all my sources?
LLM 读 wiki，综合出带引用的答案，并问："Should I save this as a wiki page?"
你说"是"，答案成为永久的分析页面

步骤 4：定期 lint

1
2
3

每 10 次摄取左右，在 Cursor 中输入：lint the wiki
LLM 检查矛盾、陈旧 claims、孤立页面、缺失链接
报告发现，问你哪些修复要应用

八、适用场景

九、为什么维护负担接近零

Karpathy 的核心洞察：

“The tedious part of maintaining a knowledge base is not the reading or the thinking — it’s the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass.”

人类放弃 wiki 是因为维护负担增长快于价值。LLM 不会厌倦、不会忘记更新交叉引用、可以一次触及 15 个文件。维护成本接近零，wiki 就能保持更新。

人类 vs LLM 的分工

十、与 Memex 的思想联系

Karpathy 指出这个想法在精神上与 Vannevar Bush’s Memex (1945) 相关 —— 一种个人策划的知识存储，带有文档间的关联轨迹。

Bush 的愿景比 Web 更接近此：私人的、积极策划的，文档间的连接与文档本身一样有价值。他无法解决的是谁来维护。LLM 解决了这个问题。

十一、行业实现

社区实现

levelup.gitconnected 详细架构

文章提供了完整的 Python 实现架构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

LLM_wiki/
├── main.py                 # 入口: python main.py <command>
├── pyproject.toml
├── requirements.txt
├── .env                    # API keys
├── llm_wiki/
│   ├── cli.py             # Click CLI: init/ingest/query/lint/status/prompts
│   ├── config.py          # WikiSchema, PageSpec dataclasses
│   ├── prompts.py         # 所有 Claude prompts + 24 QUERY_TEMPLATES
│   ├── embeddings.py      # OpenAI text-embedding-3-small wrapper
│   ├── index.py           # EmbeddingIndex: cosine similarity search
│   ├── wiki.py            # WikiPage CRUD (markdown + YAML front matter)
│   ├── ingest.py          # Route → Synthesize → Embed → Index pipeline
│   ├── query.py           # Embed → Search → Assemble → Stream pipeline
│   └── lint.py            # Health checks: orphans/broken xrefs/stale embeddings
├── sources/               # Raw input documents (immutable)
├── wiki/                  # LLM-maintained knowledge base
│   ├── index.md           # Auto-updated page catalog
│   ├── log.md             # Append-only operation history
│   ├── neural_networks.md
│   ├── backpropagation.md
│   ├── attention_mechanism.md
│   ├── transformers.md
│   └── applications.md
└── .meta/
    ├── schema.json        # Page universe definition (PageSpec list)
    └── embeddings.json    # Vector index (OpenAI 1536-dim per page)

十二、与 RAG 的对比总结

十三、引用来源

本报告数据来源：Karpathy Gist (llm-wiki.md)、balukosuri/llm-wiki-karpathy (GitHub README)、MindStudio 博客 (2026-04-06)。

Prompt Engineering、Context Engineering 与 Harness Engineering 详细说明

调研时间：2025-06-20
信息来源：Prompt Engineering Guide、BigData Boutique、Medium、DailyDev、YouTube 视频描述等

一、Prompt Engineering（提示词工程）

1.1 定义

Prompt Engineering 是通过设计清晰、有针对性的输入文本，引导大语言模型（LLM）产生准确、符合预期的输出。它是 LLM 应用的第一层门槛，也是其他一切工程层的基础。

“Prompt engineering is the practice of writing clear, purposeful inputs that guide AI models to deliver accurate and context-aware outputs.”
— GitHub

1.2 核心原则

1.3 核心技术分类

A. 基础提示技术

零样本提示（Zero-shot Prompting）

• 无需示例，直接给出指令
• 适用于简单任务
• 依赖模型本身的泛化能力

少样本提示（Few-shot Prompting）

• 在提示中加入 1~N 个示例
• 模型通过示例学习输出模式
• 适用于有明确输出格式的任务
• 论文：Brown et al., 2020 (GPT-3)

链式思考提示（Chain-of-Thought, CoT）

• 在提示中加入中间推理步骤
• 引导模型” 一步一步思考”
• 显著提升复杂推理任务准确率
• 论文：Wei et al., 2022 (Google)
• 变体：自洽性（Self-Consistency）：多路径推理，取多数票答案

生成知识提示（Generated Knowledge Prompting）

• 先让模型生成相关知识或事实
• 再基于生成内容回答问题
• 减少幻觉（hallucination）

B. 高级提示框架

Prompt Chaining（提示链）

• 将复杂任务分解为多个提示串联
• 每个提示处理一个子任务，输出作为下一级输入
• 适用于长流程任务

思维树（Tree of Thoughts, ToT）

• 在 CoT 基础上探索多分支推理树
• 系统性评估不同推理路径
• 适用于需要探索和规划的任务

检索增强生成（RAG, Retrieval-Augmented Generation）

• 从外部知识库检索相关文档
• 将检索结果注入上下文
• 解决模型知识过时和幻觉问题
• 核心挑战：检索质量 > 提示词优化

自动推理并使用工具（ART, Automatic Reasoning and Tool-use）

• 自动选择合适工具并执行
• 融合推理与行动
• 论文：Paranjape et al., 2023

ReAct 框架（Reason + Act）

• 交替进行推理和行动
• 推理步骤触发行动，行动结果反哺推理
• 已成为 Agent 架构的标准范式
• 论文：Yao et al., 2023

Reflexion

• 在 ReAct 基础上加入自我反思
• 失败后根据反馈修正策略
• 适用于需要迭代优化的任务

Active-Prompt

• 动态选择最有效的示例
• 根据任务特征自适应调整提示

方向性刺激提示（Directional Stimulus Prompting）

• 提供方向性线索引导模型输出
• 适用于风格控制、倾向性任务

Program-Aided Language Models (PAL)

• 将推理过程用代码表达
• 模型生成代码作为推理中间步骤

多模态思维链（Multimodal CoT）

• 在 CoT 中融入图像、音频等多媒体输入
• 适用于多模态推理场景

基于图的提示（Graph Prompting）

• 将图结构（知识图谱、关系网络）融入提示
• 适用于关联推理任务

Meta-Prompting

• 让模型自己生成最优提示
• 递归优化提示本身

1.4 典型应用场景

1.5 局限性

正如 BigData Boutique 所述：“You can have a perfect prompt and still get terrible results if the surrounding context is wrong.”

二、Context Engineering（上下文工程）

2.1 定义

Context Engineering 是设计和管理 LLM 在整个交互生命周期中接收的完整信息环境的学科，涵盖系统指令、检索知识、工具结果、对话历史等所有上下文来源。

“Context engineering is the delicate art and science of filling the context window with just the right information for the next step.”
— Andrej Karpathy

“The art of providing all the context for the task to be plausibly solvable by the LLM.”
— Tobi Lütke (Shopify CEO)

“Context engineering covers all four bullets [system instructions, retrieved knowledge, tool results, conversation history] — and the dynamic orchestration between them.”
— Simon Willison

2.2 核心定位

Prompt Engineering vs Context Engineering 的本质区别：

关系：Prompt Engineering ⊂ Context Engineering。Prompt Engineering 是 Context Engineering 的子集，所有好的 prompt 仍然需要，但它只是 Context Engineering 的四个组件之一。

2.3 LLM 上下文的四大组件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

┌─────────────────────────────────────────────┐
│           LLM 推理时的完整上下文              │
├─────────────────────────────────────────────┤
│  1. System Instructions（系统指令）           │
│     → Prompt Engineering 覆盖的区域           │
│     → 行为规则、输出格式约束                  │
├─────────────────────────────────────────────┤
│  2. Retrieved Knowledge（检索知识）           │
│     → RAG、搜索、文档注入                     │
│     → 知识图谱、向量数据库                    │
├─────────────────────────────────────────────┤
│  3. Tool Results（工具结果）                 │
│     → 函数调用、API 响应、数据库查询          │
│     → 外部世界状态                            │
├─────────────────────────────────────────────┤
│  4. Conversation History（对话历史）          │
│     → 历史轮次、长期记忆、摘要                │
└─────────────────────────────────────────────┘

2.4 Context Engineering 四大策略

LangChain 框架将 Context Engineering 分解为四个核心策略：

2.5 生产级实践

RAG as Context Engineering

RAG 本质上是 Context Engineering 的最纯粹实现 —— 不改变提示词本身，而是改变模型在推理时能访问的知识。工程挑战的核心不在于查询语句，而在于构建高质量的检索管道：检索正确文档 → 排序 → 过滤噪声 → 在 token 预算内组装。

工具调用中的上下文工程

当 LLM 调用工具（数据库查询、API、代码解释器）时，工具输出成为下一步推理的上下文。A / B 选择错误或格式错误都会导致” 自信的错误答案”。

LangChain 研究发现：动态选择工具描述（基于任务决定向模型展示哪些工具）比将所有工具一股脑注入，上下文准确率提升 3 倍。

记忆与上下文窗口管理

长运行 Agent 上下文积累极快：

• Anthropic 多 Agent 研究系统使用的 token 是标准聊天的 15 倍
• 无主动管理：要么超出上下文窗口，要么被无关历史淹没

生产策略：

• Auto-compaction：Claude Code 在上下文使用率达 95% 时自动压缩，将早期对话压缩为关键要点
• Context Isolation：Anthropic 多 Agent 系统中，每个子 Agent 有独立上下文窗口，独立探索后再将结果压缩汇报给主 Agent，这种方式比单 Agent 提升超过 90%
• Selective Memory：跨会话选择持久化什么、丢弃什么（如 ChatGPT、Cursor 的长期记忆功能）

2.6 Context Engineering 失败模式

Drew Breunig 识别出生产系统中四大上下文失败模式：

这些都是 Context Engineering 问题，而非 Prompt Engineering 问题。

2.7 行业数据

• 57% 的组织已在生产环境中部署 AI Agent（LangChain, 2025）
• 32% 的组织将质量列为首要障碍
• 大多数质量失败追溯至糟糕的上下文管理，而非模型能力不足 ——“模型有了错误的信息，而非错误的指令”

2.8 从 Prompt 工程师到上下文架构师

迁移路径：

1. Map your context（映射上下文）：追踪 LLM 每一步收到的所有信息片段，绘制完整上下文图谱，你会发现自己从未意识到的上下文和本应存在的上下文缺口
2. Instrument and observe（仪表化与观察）：构建可观测性工具，追踪哪些上下文输入与好的 / 坏的结果相关。问题很少是” 模型太笨”，通常是” 模型看到了错误的东西”
3. Design context pipelines（设计上下文管道）：将上下文组装视为软件工程问题，构建动态检索、排序、过滤、格式化的管道
4. Budget your tokens（Token 预算管理）：将上下文窗口视为嵌入式系统的内存 —— 有限资源，设计优先级
5. Test context, not just prompts（测试上下文而非提示词）：当出问题时，不要只改 prompt，要检查模型收到的完整上下文

三、Harness Engineering（驾驭工程）

3.1 定义

Harness Engineering 是在 AI Agent 时代让人来” 掌舵方向（steer）”、AI 代理来” 执行完成（execute）” 的软件工程实践。其核心是构建让 AI 代理能够可靠完成完整软件工程工作的环境、文档和流程。

“Think of an agent as a new grad. It has a very smart brain (the LLM), it has almost all the human knowledge and it knows how to reason. It can use tools like reading files and browsing the internet. It can write scripts and run commands on your computer. But it doesn’t know what you want. It can’t guess what you want it to do, what you value, or what your goals are. The complete environment you create for the agent: the workflows you define, the goals you set, that’s Harness Engineering.”
— AnyTech

提出者：Ryan Lopopolo（OpenAI Technical Staff Member）
来源：OpenAI 内部实践 —— 用 AI 代理完全自主开发 9 个月，产出 1M LOC、日均 1B tokens，0% 人类编写代码或 review

3.2 核心洞察

传统软件工程：人类是执行者 + 审核者
Harness Engineering：人类是方向掌舵者 + 质量守门人，代理负责完整执行

1
2
3
4
5
6
7

传统模式：
Human → Write Code → Review → Merge

Harness Engineering 模式：
Human → Steer Direction → Agent Executes → Human Quality Gate
         ↑                                    ↓
         ←←←←←←←← Feedback Loop ←←←←←←←←←←←

3.3 Ralph Wiggum Loop

OpenAI 内部使用的核心迭代循环：

1. 代理对变更进行本地 Review
2. 请求特定的人工 / 代理 Review（本地 + 云端）
3. 响应反馈
4. 循环迭代，直到所有代理 Review 都满意

这一机制被称为 Ralph Wiggum Loop—— 一个不断追求代理自洽的反馈循环。

3.4 核心工程实践

让代码库对 Agent 直接可理解

OpenAI 团队的核心经验：代码库本身必须让代理能直接从仓库中推理完整业务领域，而不依赖人类解释。这包括：

• 应用 UI 本身对代理可读
• Logs 对代理可读
• App Metrics 对代理可读

就像团队为新工程师改善代码可读性一样，Human Engineers 的目标是让代理能够直接推理完整的业务领域。

Harness 的三层结构（与 Context Engineering 的演进关系）

1
2
3
4
5
6

Prompt Engineering（提示词工程）
  ↓ 覆盖单次输入
Context Engineering（上下文工程）
  ↓ 覆盖信息管道
Harness Engineering（驾驭工程）
  ↓ 覆盖完整工程执行环境

• Context Engineering 解决” 给 AI 正确的信息”
• Harness Engineering 解决” 让人能够可靠地驾驭 AI 完成整个工程”

3.5 从写代码到脚手架工程

Harness Engineering 带来的核心转变：

3.6 三者关系全景图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

┌─────────────────────────────────────────────────────────────┐
│              AI 时代软件工程方法论演进                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Prompt Engineering（提示词工程）                             │
│  ├── 层次：单次输入优化                                     │
│  ├── 工具：CoT、Few-shot、ReAct 等提示技术                  │
│  ├── 定位：LLM 应用入门层                                   │
│  └── 局限：无法支撑生产级 Agent 系统                        │
│                                                             │
│            ↓ 叠加                                           │
│                                                             │
│  Context Engineering（上下文工程）                           │
│  ├── 层次：信息管道设计                                     │
│  ├── 工具：RAG、Knowledge Graph、Memory Management          │
│  ├── 定位：生产级 AI 系统的信息架构                         │
│  ├── 核心：Write/Select/Compress/Isolate 四大策略          │
│  └── 局限：仍聚焦于"AI 看到什么"，未覆盖完整工程执行        │
│                                                             │
│            ↓ 叠加                                           │
│                                                             │
│  Harness Engineering（驾驭工程）                             │
│  ├── 层次：完整工程执行环境                                  │
│  ├── 工具：工作流定义、目标规范、反馈闭环、Guardrail         │
│  ├── 定位：让人"驾驭"AI代理完成全流程软件工程               │
│  ├── 核心：Human Steer + Agent Execute + Ralph Wiggum Loop  │
│  └── 代表：OpenAI 9个月实践（1M LOC，0%人类代码）           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

三者不是替代关系，而是递进叠加：
- Prompt Engineering 是入口（所有方法论的最底层）
- Context Engineering 是生产级 AI 系统的必经之路
- Harness Engineering 是 AI Agent 时代的完整工程范式

3.7 前沿数据

• OpenAI 用 AI 代理完全自主开发达到 1M LOC 规模
• 日均 1B tokens 处理量
• 0% 人类编写代码或 Review
• 代理可自主工作数小时不偏离计划

四、关键术语对照表

五、核心引用来源

六、对电力行业 AI 应用的启示

结合用户当前研究的电网企业语义层建设背景，三个工程方法论的应用价值：

本报告数据来源：Prompt Engineering Guide、BigData Boutique（March 2026）、Medium（AnyTech, March 2026）、DailyDev、YouTube (Ryan Lopopolo @ OpenAI)。