🌿 LanShu Wiki Skill

让 LLM 当 Wiki 园丁——人类策展和提问，LLM 做摘要、链接、维护。

一个 Claude Code skill，把 Karpathy 的 LLM Wiki 模式变成 5 分钟开张的工作流。
既适合个人知识库，也适合给开源项目做架构文档。

💡 本项目完全基于 Andrej Karpathy 的 LLM Wiki gist（2026）

Karpathy 那篇 75 行的 gist 提出了"让 LLM 增量维护持久 wiki"的范式——核心思想、三层架构（raw / wiki / schema）、三大操作（Ingest / Query / Lint）、index.md + log.md 的设计、Why this works 的论证，全部来自他那篇文章。

本仓库做的事是把那个"抽象 idea"工程化：写成可被 Claude Code 自动执行的 Skill + 两套生产验证过的 schema 模板。没有 Karpathy 的 gist 就没有这个项目，致以最高敬意。 强烈建议先读 原文 理解思想，再用本 skill 落地。

为什么需要这个

传统知识管理的死结：维护成本随规模超线性增长，人最终都会放弃。RAG 看起来解决了，但每次查询都重新检索 + 合成，知识不积累、不复利。

LLM Wiki 模式换了个思路：把 wiki 编译好，而不是每次解释执行——交叉引用预建好、矛盾预标注、合成预完成。人类负责策展和提问，LLM 负责所有摘要、链接、归档。

这个 skill 把这套思路工程化：

• ✅ 声明式触发——说 "添加到 wiki"、"查一下 wiki"、"/wiki ingest"，自动激活
• ✅ 两套范式开箱即用——个人知识库 + 代码仓库 wiki
• ✅ schema 即真理——所有页面格式、标签体系、工作流都由 schema 文件定义，避免 LLM 自由发挥
• ✅ 跨会话连续——新会话自动读 index.md + log.md，无缝接续
• ✅ 可追溯——硬规则：结论必须来自已核验源码或原文

看起来像什么

随便说一句"把这个 Karpathy 的 gist 加到 wiki"——

我：把这个 Karpathy 的 gist 加到 wiki：
    https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

Claude：好，我先看下当前 wiki 状态...
    ✓ 读了 ~/wiki/CLAUDE.md（schema 规则）
    ✓ 读了 ~/wiki/index.md（当前 12 个页面）
    ✓ 抓取 gist 内容（2,300 字）

    分析后我打算创建这些页面：
    - sources/llm-wiki-pattern.md（含 reliability: expert-opinion）
    - entities/andrej-karpathy.md（更新已有页面，加 source-id）
    - concepts/llm-wiki-pattern.md（新建概念页）
    - concepts/knowledge-management.md（更新：加入 LLM Wiki 行）
    - syntheses/rag-vs-llm-wiki.md（新建合成页：你之前有 3 篇关于 RAG 的来源）

    要继续吗？

我：继续

Claude：[执行]
    ✓ 原文存到 raw/ai/llm-wiki-pattern.md（不可变）
    ✓ 5 个 wiki 页面创建/更新完成
    ✓ index.md 更新（新增 3 页 / 更新 2 页）
    ✓ log.md 追加本次操作记录

    本次 ingest 触及 5 个页面，未解决问题 2 个（已记入相关页面）。

下次问 "wiki 里有关于知识管理的内容吗"——它会读相关页面、综合答案，并引用 [[wikilinks]]。

下次跑 /wiki lint —— 它会扫所有页面、找悬空链接和矛盾点、生成报告。

实战案例

这个 skill 已经在以下项目上验证：

配套：lanshu-wiki-web 把任意 GitHub wiki 仓库渲染成带知识图谱、全文搜索、Mermaid 渲染的高级阅读站。

→ 在线 Demo

快速开始

1. 安装 skill

# Clone 本仓库
git clone https://github.com/cclank/lanshu-wiki-skill.git ~/code/lanshu-wiki-skill

# 软链 SKILL.md 到 Claude Code 的 skills 目录
mkdir -p ~/.claude/skills/wiki
ln -sf ~/code/lanshu-wiki-skill/SKILL.md ~/.claude/skills/wiki/SKILL.md

2. 选择你的 wiki 模式

场景 A：个人知识库

# 建五层目录骨架
mkdir -p ~/wiki/{raw,sources,entities,concepts,syntheses,reports,assets}

# 把权威 schema 放进去
cp ~/code/lanshu-wiki-skill/schema/wiki-personal-CLAUDE.md ~/wiki/CLAUDE.md

# 初始化必备文件
cd ~/wiki && echo "# Wiki Index" > index.md && echo "# Wiki Log" > log.md && echo "# Wiki Inbox" > inbox.md

打开 Claude Code，说一句"添加到 wiki <文章 URL>"或"/wiki ingest "即可开始。

场景 B：给开源项目做架构 wiki

# 在你的项目附近新建 wiki 仓库
mkdir ~/code/<project>-wiki && cd ~/code/<project>-wiki

# 复制代码仓库 wiki 的 schema 模板
cp ~/code/lanshu-wiki-skill/schema/wiki-code-repo-SCHEMA.md ./SCHEMA.md

# 创建必要骨架
mkdir concepts entities changelog
echo "# Wiki Index" > index.md
echo "# Wiki Log" > log.md

# 编辑 SCHEMA.md，填入你项目的 Domain 描述与 Tag Taxonomy（搜索 ⚠️ 标记）

然后在 Claude Code 里说："读 SCHEMA.md，按它的规则给 <repo> 源码做架构 wiki，从最核心的 5 个模块开始"。

3. 日常使用

仓库结构

lanshu-wiki-skill/
├── SKILL.md                       # Claude Code skill 入口（触发词 + 命令路由）
├── schema/
│   ├── wiki-personal-CLAUDE.md    # 个人知识库 schema（基于 Karpathy 模式，五层目录）
│   └── wiki-code-repo-SCHEMA.md   # 代码仓库 wiki schema（三层目录 + 双层导览）
├── LICENSE                        # MIT
├── README.md                      # 中文（你正在看的）
└── README.en.md                   # English

两种范式对比

核心原则

• 结论必须可追溯——这是硬规则。源码 文件:行号 或原文 URL，做不到宁可不写
• schema 是权威——所有页面格式、标签、工作流都由 schema 文件定义，不允许 LLM 自由发挥
• 先读后写——更新页面前必须读全文，禁止只看 index 摘要就改
• 去重优先——创建新页面前必须搜 index 是否已有同概念
• 追加而非覆盖——raw/ 不可变，log.md 只追加，矛盾要标注不要消解

进阶：双层 wiki（白话导览 + 技术页）

代码仓库 wiki 模式支持"双受众"的双层结构：

• guide/（白话导览）：零代码、多类比、面向产品/运营/学习者
• concepts/ + entities/（技术页）：源码级、含 文件:行号 锚点、面向工程师

两层之间通过出处链接绑定——白话页核心结论必须能追到技术页与源码。

这个模式最早在 x-algorithm-wiki 跑通：11 页白话 + 23 页技术，同一份 wiki 服务两类受众，是从"工程师内部文档"突破到"对外宣传材料"的关键升级。

想做在线预览？

配套项目 lanshu-wiki-web：

• 输入任意 GitHub wiki 仓库 URL → 渲染成带侧栏、搜索、知识图谱的阅读站
• Next.js 16 + React 19 + TS 5 + Tailwind 4
• 部署一份到 Vercel 或 Cloudflare Workers，几分钟搞定

Demo：把 https://github.com/cclank/x-algorithm-wiki 喂给 lanshu-wiki-web.lank.workers.dev 看效果。

与现有方案对比

关键差异：

• vs Obsidian：用 Obsidian 文件格式，但 LLM 替你做维护。可以直接拿这个 wiki 在 Obsidian 里浏览（甚至用 Dataview 查询）。
• vs Notion：Notion 是给团队的工作流工具，wiki 是给单人/小团队的知识库。
• vs RAG：RAG 不积累、不复利，每次重新合成；wiki 一次合成，反复使用。两者可以共存（用 wiki 作为高质量语料喂 RAG）。
• vs Zettelkasten：思想内核一致（卡片化、强交叉引用），但 LLM 解决了"人会放弃维护"的根本痛点。

FAQ

Q：跟直接喂源码给 RAG 比有什么优势？

A：RAG 每次查询都要重新检索 + 合成，回答质量受检索召回率影响，且无法跨查询积累。这个 skill 是"编译型"——交叉引用、对比、矛盾点在 ingest 时一次性建好，后续查询直接读结果。两者不冲突：可以把 wiki 当作高质量精炼语料喂给 RAG。

Q：规模上限在哪？2000 页是硬限制吗？

A：这是经验数字，来自 Karpathy 原文。瓶颈在 index.md 容量——它要装下所有页面的一行摘要供 LLM 一次性读完。我目前最大的 wiki 是 Hermes-Wiki（73 页 + 26 个 changelog），index.md 还很从容。超过 1000 页后可以分多个子 wiki（按领域拆）。

Q：多人协作怎么办？

A：当前 skill 优化的是单人/小团队场景。多人协作要解决：

1. 冲突合并——多人同时 ingest 同一来源会创建多份 source 页面，需要事后 /wiki merge
2. schema 共识——必须先就 CLAUDE.md / SCHEMA.md 达成共识，否则各写各的
3. Git 工作流——推荐每人独立分支 ingest，定期合并 + lint

实战中，Hermes-Wiki 用过"定时任务每天产生一个 daily-sync 分支，定期人工合并"的工作流，可参考。

Q：个人 wiki 里含敏感信息怎么办？

A：

• ~/wiki/ 默认不上 git（不开 git init）；想备份就用 私有 git repo 或 iCloud/Dropbox
• 如果一定要上公开 git，建议把含敏感信息的页面打 tags: [private]，写个 .gitignore 模式按 frontmatter 排除（需要自己写 pre-commit hook）
• 代码仓库 wiki 默认是为开源准备的，不该放敏感信息

Q：可以离开 Claude Code 用吗？比如换成 Codex / Cursor？

A：核心是 CLAUDE.md / SCHEMA.md 这套 schema，不绑定具体 IDE。只是 Claude Code 的 Skill 系统让"用自然语言触发"变得很丝滑。如果用其他工具，把 schema 文件粘到系统提示里也能用，只是体验差一些。

Q：LLM 出错了怎么办？比如理解错源码、写错结论？

A：这就是为什么 schema 里有「硬规则：结论必须可追溯」。每个论点都带 文件:行号，所以 /wiki lint 时人工抽查很容易发现问题（"这页说 X 在文件 A 第 100 行，但实际打开看不是" → 立即定位）。我们做 Hermes-Wiki 时跑过全量 lint，482 个源码锚点逐个核验，发现 ~3 处偏差，全部修正后入 changelog。

Q：这个 skill 算不算重新发明轮子？已经有 Obsidian Copilot、Notion AI 这些了。

A：那些是"在已有笔记软件里加 AI"——AI 是助手。这个 skill 是"让 AI 当主维护者"——人是策展和提问的角色。换的是分工，不是工具。

相关工具

Karpathy 原文推荐的搭配工具，可按需引入：

• Obsidian —— 浏览 wiki 的首选 IDE，graph view 看连接关系，Dataview 插件按 frontmatter 查询
• Obsidian Web Clipper —— 浏览器扩展，把网页一键转 markdown 入 raw/
• qmd —— 本地 markdown 搜索引擎（hybrid BM25 + vector + LLM re-rank），有 CLI + MCP server。wiki 大到 index.md 装不下时考虑接入
• Marp —— markdown slide deck，把 wiki 内容直接渲染成幻灯片（Obsidian 有插件）
• 图片本地化技巧：Obsidian Settings → Files and links 把 "Attachment folder path" 指到 raw/assets/，再绑 "Download attachments for current file" 到快捷键。clip 文章后一键把图片全下载到本地，避免外链失效

致谢

• Andrej Karpathy —— 提出 LLM Wiki 模式，把 Memex 中"由谁来做维护"这一未解问题交给了 LLM。本项目是他那篇 gist 的工程化实现，所有核心思想都来自他
• Vannevar Bush —— 1945 年提出 Memex：私有、人工策展、文档间关联链接的知识库构想，是 Karpathy 模式背后的思想源头
• Claude Code Skill 系统 —— 让 schema 驱动的工作流变得可行

贡献

欢迎 PR、issue，特别是：

• 新领域的 schema 模板（如：游戏开发、生信、嵌入式）
• 工具脚本（lint 增强、auto-archive 等）
• 你自己用这个 skill 做的 wiki 案例（合并到 README 的"实战案例"区）

License

MIT