Karpathy's LLM Wiki
Harness-agent tools#
本技能从 Octop 移植。使用以下 harness/deepagents 工具:
| 概念 | 工具 |
|---|---|
| Shell | execute |
| 读/写/编辑文件 | read_file, write_file, edit_file |
| 查找文件/搜索内容 | glob, grep |
| 获取 URL | web_fetch |
| 浏览器自动化 | browser_use |
| 子代理工作 | task |
| 记忆 | memory_store, memory_recall, memory_search |
内置技能文件位于 /_builtin_skills/<name>/。用户安装的技能位于 /skills/<name>/。
构建和维护一个持久的、复合的知识库,以互联的 markdown 文件形式。 基于 Andrej Karpathy's LLM Wiki pattern。
与传统 RAG(每次查询都重新发现知识)不同,wiki 一次性编译知识并保持最新。交叉引用已经存在。 矛盾已经标记。综合反映了所有摄取的内容。
劳动分工: 人类策划来源并指导分析。代理 总结、交叉引用、文件和维护一致性。
何时此技能激活#
当用户:
- 要求创建、构建或启动 wiki 或知识库
- 要求摄取、添加或处理来源到他们的 wiki
- 询问问题且配置的路径处存在现有 wiki
- 要求 lint、审计或健康检查他们的 wiki
- 在研究中引用他们的 wiki、知识库或"笔记"
Wiki 位置#
位置: 通过 WIKI_PATH 环境变量设置(例如,在 {workspace}/.env 中)。
如果未设置,默认为 ~/wiki。
WIKI="${WIKI_PATH:-$HOME/wiki}"
wiki 只是一个 markdown 文件目录——在 Obsidian、VS Code 或 任何编辑器中打开它。无需数据库,无需特殊工具。
架构:三层#
wiki/
├── SCHEMA.md # 约定、结构规则、领域配置
├── index.md # 带一行摘要的分段内容目录
├── log.md # 按时间顺序的操作日志(仅追加,每年轮换)
├── raw/ # 第 1 层:不可变来源材料
│ ├── articles/ # Web 文章、剪报
│ ├── papers/ # PDF、arxiv 论文
│ ├── transcripts/ # 会议笔记、访谈
│ └── assets/ # 来源引用的图像、图表
├── entities/ # 第 2 层:实体页面(人物、组织、产品、模型)
├── concepts/ # 第 2 层:概念/主题页面
├── comparisons/ # 第 2 层:并排分析
└── queries/ # 第 2 层:值得保留的已归档查询结果
第 1 层 — 原始来源: 不可变。代理读取但从不修改这些。
第 2 层 — Wiki: 代理拥有的 markdown 文件。由代理创建、更新和 交叉引用。
第 3 层 — 模式: SCHEMA.md 定义结构、约定和标签分类法。
恢复现有 Wiki(关键——每会话都执行此操作)#
当用户有现有 wiki 时,在执行任何操作之前始终先让自己定向:
① 读取 SCHEMA.md — 理解领域、约定和标签分类法。
② 读取 index.md — 了解存在哪些页面及其摘要。
③ 扫描最近的 log.md — 读取最后 20-30 个条目以理解最近活动。
WIKI="${WIKI_PATH:-$HOME/wiki}"
# 会话开始时的定向读取
read_file "$WIKI/SCHEMA.md"
read_file "$WIKI/index.md"
read_file "$WIKI/log.md" offset=<最后 30 行>
只有定向后,你才应该摄取、查询或 lint。这可以防止:
- 为已存在的实体创建重复页面
- 缺少与现有内容的交叉引用
- 与模式的约定矛盾
- 重复已在日志中记录的工作
对于大型 wikis(100+ 页面),在创建任何新内容之前,还要对当前主题运行快速 glob。
初始化新 Wiki#
当用户要求创建或启动 wiki 时:
- 确定 wiki 路径(来自
$WIKI_PATH环境变量,或询问用户;默认为~/wiki) - 创建上方的目录结构
- 询问用户 wiki 涵盖什么领域——要具体
- 编写针对该领域定制的
SCHEMA.md(见下方模板) - 编写带分段标题的初始
index.md - 编写带创建条目的初始
log.md - 确认 wiki 已就绪并建议第一个要摄取的来源
SCHEMA.md 模板#
针对用户的领域调整。模式约束代理行为并确保一致性:
# Wiki Schema
## Domain
[此 wiki 涵盖的内容——例如,"AI/ML research", "personal health", "startup intelligence"]
## Conventions
- 文件名:小写、连字符、无空格(例如,`transformer-architecture.md`)
- 每个 wiki 页面以 YAML frontmatter 开头(见下方)
- 使用 `[[wikilinks]]` 在页面之间链接(每页至少 2 个出站链接)
- 更新页面时,始终更新 `updated` 日期
- 每个新页面必须添加到正确分段下的 `index.md`
- 每个操作必须追加到 `log.md`
- **来源标记:** 在综合 3+ 来源的页面上,在声明来自特定来源的段落末尾附加 `^[raw/articles/source-file.md]`
这让读者可以在不重新读取整个原始文件的情况下追溯每个声明。在单来源页面上可选,其中
`sources:` frontmatter 已足够。
## Frontmatter
```yaml
---
title: Page Title
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity | concept | comparison | query | summary
tags: [from taxonomy below]
sources: [raw/articles/source-name.md]
# Optional quality signals:
confidence: high | medium | low # 声明支持得有多好
contested: true # 当页面有未解决矛盾时设置
contradictions: [other-page-slug] # 此页面与哪些页面冲突
---
confidence 和 contested 是可选的,但建议用于意见重度或快速移动的
主题。Lint 会显示 contested: true 和 confidence: low 页面以供审查,以便弱声明
不会静默强化为已接受的 wiki 事实。
raw/ Frontmatter#
原始来源也获得一个小的 frontmatter 块,以便重新摄取可以检测漂移:
---
source_url: https://example.com/article # 原始 URL(如果适用)
ingested: YYYY-MM-DD
sha256: <hex digest of the raw content below the frontmatter>
---
sha256: 让未来的相同 URL 重新摄取跳过处理(当内容未更改时),
并在内容已更改时标记漂移。仅在正文(frontmatter 之后的所有内容)上计算,而不是 frontmatter 本身。
Tag Taxonomy
[为领域定义 10-20 个顶级标签。在首先使用它们之前在此处添加新标签。]
示例用于 AI/ML:
- Models: model, architecture, benchmark, training
- People/Orgs: person, company, lab, open-source
- Techniques: optimization, fine-tuning, inference, alignment, data
- Meta: comparison, timeline, controversy, prediction
规则:页面上的每个标签必须出现在此分类法中。如果需要新标签, 首先在此处添加它,然后使用它。这可以防止标签扩散。
Page Thresholds#
- 创建页面 当实体/概念出现在 2+ 来源中或对一个来源至关重要时
- 添加到现有页面 当来源提到已涵盖的内容时
- 不要创建页面 用于路过提及、次要细节或领域之外的事物
- 拆分页面 当它超过 ~200 行时——用交叉链接拆分为子主题
- 归档页面 当其内容完全被取代时——移动到
_archive/,从索引中移除
Entity Pages#
每篇 notable 实体一页。包括:
- 概述 / 它是什么
- 关键事实和日期
- 与其他实体的关系([[wikilinks]])
- 来源引用
Concept Pages#
每个概念或主题一页。包括:
- 定义 / 解释
- 知识的当前状态
- 开放问题或辩论
- 相关概念([[wikilinks]])
Comparison Pages#
并排分析。包括:
- 正在比较什么以及为什么
- 比较维度(首选表格格式)
- verdict 或综合
- 来源
Update Policy#
当新信息与现有内容冲突时:
- 检查日期——较新的来源通常取代较旧的
- 如果确实矛盾,用日期和来源记录两个位置
- 在 frontmatter 中标记矛盾:
contradictions: [page-name] - 在 lint 报告中标记供用户审查
index.md 模板#
索引按类型分段。每个条目一行:wikilink + 摘要。
# Wiki Index
> Content catalog. Every wiki page listed under its type with a one-line summary.
> Read this first to find relevant pages for any query.
> Last updated: YYYY-MM-DD | Total pages: N
## Entities
<!-- Alphabetical within section -->
## Concepts#
## Comparisons#
## Queries#
缩放规则: 当任何分段超过 50 个条目时,按首字母或子域拆分为子分段。当索引总数超过 200 个条目时,创建一个 _meta/topic-map.md,按主题分组页面以便更快导航。
log.md 模板#
# Wiki Log
> Chronological record of all wiki actions. Append-only.
> Format: `## [YYYY-MM-DD] action | subject`
> Actions: ingest, update, query, lint, create, archive, delete
> When this file exceeds 500 entries, rotate: rename to log-YYYY.md, start fresh.
## [YYYY-MM-DD] create | Wiki initialized
- Domain: [domain]
- Structure created with SCHEMA.md, index.md, log.md
核心操作#
1. 摄取#
当用户提供来源(URL、文件、粘贴)时,将其集成到 wiki 中:
① 捕获原始来源:
- URL → 使用
web_fetch获取 markdown,保存到raw/articles/ - PDF → 使用
web_fetch(处理 PDF),保存到raw/papers/ - 粘贴的文本 → 保存到适当的
raw/子目录 - 描述性地命名文件:
raw/articles/karpathy-llm-wiki-2026.md - 添加原始 frontmatter(
source_url、ingested、sha256正文)。 在重新摄取相同 URL 时:重新计算 sha256,与存储的值比较—— 如果相同则跳过,如果不同则标记漂移并更新。这足够便宜,可以在每次重新摄取时执行并捕获静默来源更改。
② 与用户讨论要点 — 什么有趣,什么对此领域重要。 (在自动化/cron 上下文中跳过此操作——直接进行。)
③ 检查已存在的内容 — 搜索 index.md 并使用 glob 查找
已提及实体/概念的现有页面。这是不断增长的 wiki 和一堆重复项之间的区别。
④ 编写或更新 wiki 页面:
- 新实体/概念: 仅当它们满足 SCHEMA.md 中的页面阈值时才创建页面 (2+ 来源提及,或对一个来源至关重要)
- 现有页面: 添加新信息,更新事实,更新
updated日期。 当新信息与现有内容矛盾时,遵循更新策略。 - 交叉引用: 每个新页面或更新的页面必须通过
[[wikilinks]]链接到至少 2 个其他 页面。检查现有页面是否链接回来。 - 标签: 仅使用 SCHEMA.md 分类法中的标签
- 来源: 在综合 3+ 来源的页面上,附加
^[raw/articles/source.md]标记到声明来自特定来源的段落。这允许读者追溯每个 声明回到其来源,而无需重新读取整个原始文件。可选在单来源页面上,其中sources:frontmatter 已足够。 - 置信度: 对于意见重度、快速移动或单来源声明,在 frontmatter 中设置
confidence: medium或low。除非 声明在多个来源中得到充分支持,否则不要标记high。
⑤ 更新导航:
- 将新页面添加到
index.md下的正确分段,按字母顺序 - 更新索引标题中的"Total pages"计数和"Last updated"日期
- 追加到
log.md:## [YYYY-MM-DD] ingest | Source Title - 在日志条目中列出每个创建或更新的文件
⑥ 报告更改的内容 — 向用户列出创建或更新的每个文件。
单个来源可以触发跨 5-15 个 wiki 页面的更新。这很正常 并且是期望的——它是复合效应。
2. 查询#
当用户询问有关 wiki 领域的问题时:
① 读取 index.md 以识别相关页面。
② 对于 100+ 页面的 wikis,还要跨所有 .md 文件
glob 以查找关键术语——仅索引可能会错过相关内容。
③ 使用 read_file 读取相关页面。
④ 从编译的知识中综合答案。 引用你从中抽取的 wiki 页面:
"Based on [[page-a]] and [[page-b]]..."
⑤ 将有价值的答案反馈回来 — 如果答案是实质性的比较、
深度潜水或新颖的综合,请在 queries/ 或 comparisons/ 中创建一个页面。
不要归档平凡的查找——仅归档重新派生会痛苦的回答。
⑥ 使用查询和是否已归档更新 log.md。
3. Lint#
当用户要求 lint、健康检查或审计 wiki 时:
① 孤立页面: 查找没有其他页面 [[wikilinks]] 的页面。
# 使用 execute_code 执行此操作 — 跨所有 wiki 页面进行程序化扫描
import os, re
from collections import defaultdict
wiki = "<WIKI_PATH>"
# 扫描 entities/、concepts/、comparisons/、queries/ 中的所有 .md 文件
# 提取所有 [[wikilinks]] — 构建入站链接映射
# 零入站链接的页面是孤立的
② 断开的 wikilinks: 查找指向不存在的页面的 [[links]]。
③ 索引完整性: 每个 wiki 页面都应出现在 index.md 中。比较
文件系统与索引条目。
④ Frontmatter 验证: 每个 wiki 页面必须具有所有必需字段 (title、created、updated、type、tags、sources)。标签必须出现在分类法中。
⑤ 过期内容: 其 updated 日期比提及相同实体的最新
来源旧 >90 天的页面。
⑥ 矛盾: 关于同一主题但声称不同的页面。查找
共享标签/实体但陈述不同事实的页面。显示所有带有
contested: true 或 contradictions: frontmatter 的页面以供用户审查。
⑦ 质量信号: 列出带有 confidence: low 的页面以及任何仅引用
单个来源但没有设置置信度字段的页面——这些是候选
用于查找 corroboration 或降级为 confidence: medium。
⑧ 来源漂移: 对于 raw/ 中每个带有 sha256: frontmatter 的文件,重新计算
哈希并标记不匹配。不匹配表示原始文件被编辑过
(不应发生——raw/ 是不可变的)或从已更改的 URL 重新摄取。不是硬错误,但值得报告。
⑨ 页面大小: 标记超过 200 行的页面——用于拆分的候选。
⑩ 标签审计: 列出使用中的所有标签,标记任何不在 SCHEMA.md 分类法中的标签。
⑪ 日志轮换: 如果 log.md 超过 500 个条目,轮换它。
⑫ 报告发现 并按严重性分组(断开的链接 > 孤立 > 来源漂移 > 矛盾页面 > 过期内容 > 样式问题)。
⑬ 追加到 log.md: ## [YYYY-MM-DD] lint | N issues found。
使用 Wiki 工作#
搜索#
# 按内容查找页面
grep(pattern="transformer", path="$WIKI")
# 按文件名查找页面
glob(pattern="**/*.md", path="$WIKI")
# 按标签查找页面
grep(pattern="tags:.*alignment", path="$WIKI")
# 最近活动
read_file "$WIKI/log.md" offset=<最后 20 行>
批量摄取#
一次摄取多个来源时,批量更新:
- 首先读取所有来源
- 跨所有来源识别所有实体和概念
- 检查它们所有(一次搜索,而不是 N 次)的现有页面
- 在一次传递中创建/更新页面(避免冗余更新)
- 最后更新 index.md
- 写入覆盖批次的单个日志条目
归档#
当内容完全被取代或领域范围更改时:
- 如果不存在,创建
_archive/目录 - 将页面移动到
_archive/及其原始路径(例如,_archive/entities/old-page.md) - 从
index.md中移除 - 更新链接到它的页面——用纯文本 + "(archived)" 替换 wikilink
- 记录归档操作
- 日志归档操作
Obsidian 集成#
wiki 目录开箱即用作 Obsidian 保管库:
[[wikilinks]]渲染为可点击的链接- 图形视图可视化知识网络
- YAML frontmatter 支持 Dataview 查询
raw/assets/文件夹保存通过![[image.png]]引用的图像
为了获得最佳结果:
- 将 Obsidian 的附件文件夹设置为
raw/assets/ - 在 Obsidian 设置中启用"Wikilinks"(默认通常开启)
- 安装 Dataview 插件以进行查询,如
TABLE tags FROM "entities" WHERE contains(tags, "company")
如果将 Obsidian 技能与此技能一起使用,请将 OBSIDIAN_VAULT_PATH 设置为
与 wiki 路径相同的目录。
Obsidian Headless(服务器和无头机器)#
在没有显示器的机器上,使用 obsidian-headless 而不是桌面应用程序。
它通过 Obsidian Sync 同步保管库而无需 GUI——非常适合
在服务器上运行并写入 wiki 而 Obsidian 桌面在另一台设备上读取它的代理。
设置:
# 需要 Node.js 22+
npm install -g obsidian-headless
# 登录(需要带有 Sync 订阅的 Obsidian 帐户)
ob login --email <email> --password '<password>'
# 为 wiki 创建远程保管库
ob sync-create-remote --name "LLM Wiki"
# 将 wiki 目录连接到保管库
cd ~/wiki
ob sync-setup --vault "<vault-id>"
# 初始同步
ob sync
# 持续同步(前台——对后台使用 systemd)
ob sync --continuous
通过 systemd 持续后台同步:
# ~/.config/systemd/user/obsidian-wiki-sync.service
[Unit]
Description=Obsidian LLM Wiki Sync
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=/path/to/ob sync --continuous
WorkingDirectory=/home/user/wiki
Restart=on-failure
RestartSec=10
[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now obsidian-wiki-sync
# 启用 linger 以便同步在注销后继续:
sudo loginctl enable-linger $USER
这让代理可以在服务器上写入 ~/wiki,而你在笔记本电脑/手机上的 Obsidian 中浏览相同的
保管库——更改在几秒钟内出现。
陷阱#
- 永远不要修改
raw/中的文件 — 来源是不可变的。更正转到 wiki 页面。 - 始终首先定向 — 在新会话中执行任何操作之前,读取 SCHEMA + 索引 + 最近日志。 跳过此操作会导致重复和错过交叉引用。
- 始终更新 index.md 和 log.md — 跳过此操作会使 wiki 降级。它们是 导航骨干。
- 不要为路过提及创建页面 — 遵循 SCHEMA.md 中的页面阈值。仅在 脚注中出现一次的名称不保证实体页面。
- 不要创建没有交叉引用的页面 — 孤立页面是不可见的。每个页面必须 链接到至少 2 个其他页面。
- Frontmatter 是必需的 — 它启用搜索、过滤和过期检测。
- 标签必须来自分类法 — 自由格式标签衰减为噪音。首先向 SCHEMA.md 添加新标签,然后使用它们。
- 保持页面可扫描 — wiki 页面应可在 30 秒内阅读。将页面拆分为 超过 200 行的页面。将详细分析移至专用的深度潜水页面。
- 在大规模更新之前询问 — 如果摄取会触及 10+ 现有页面,请首先与用户确认 范围。
- 轮换日志 — 当 log.md 超过 500 个条目时,将其重命名为
log-YYYY.md并从头开始。 代理应在 lint 期间检查日志大小。 - 显式处理矛盾 — 不要静默覆盖。用日期记录两个声明, 在 frontmatter 中标记,并标记供用户审查。
相关工具#
llm-wiki-compiler 是一个 Node.js CLI, 它使用相同的 Karpathy 灵感将来源编译为概念 wiki。它是 Obsidian 兼容的, 因此想要预定/CLI 驱动的编译管道的用户可以将其指向此技能维护的相同保管库。 权衡:它拥有页面生成(替换此技能的页面 创建上的判断)并为早期 设置和大量来源批量摄取进行调整。使用此技能当你想要代理在循环中策划时; 使用 llmwiki 当你想要批量编译来源目录时。