基于 Karpathy LLM Wiki 模式的个人知识库系统。Claude Code 做知识管家，Obsidian 做可视化前端。
两大场景：
- 📚 知识整理：喂文章/PDF/剪藏，AI 编译成 wiki 概念网络
- 🧑🏫 代码仓库教学：给 AI 一个开源项目，它陪你从 L0 全景一路到 L5 踩坑，对话自动沉淀进对应章节
- Node.js (v18+)
- Claude Code (
npm install -g @anthropic-ai/claude-code) - Python 3.8+
- Obsidian
- 推荐安装 Obsidian Web Clipper 浏览器插件
在上手之前先记住三方谁干什么，后面所有操作都是这三者在配合。
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ 你（用户） │ │ Claude Code │ │ Obsidian │
│ │ │ (AI 管家) │ │ (可视化前端) │
│ 1. 扔素材 │──────▶│ 读 raw/ │ │ │
│ 2. 打字提问 │ │ 写 wiki/ │──────▶│ 展示 + 导航 │
│ 3. 用 Obsidian │ │ 写 outputs/ │ │ (你在这里看) │
│ 阅读 wiki/ │◀──────┼─ 修 CLAUDE.md ──┘ │ │
└─────────────────┘ │ 为准绳 │ └─────────────────┘
└──────────────────┘
- 你只动三种文件：往
raw/扔素材、在终端跟 Claude 对话、在 Obsidian 里阅读wiki/ - AI 只动两种文件：读
raw/、写wiki/+outputs/ raw/永远不变：AI 绝不修改你丢进来的原始文件
只需要做一次。打开 Obsidian → Open folder as vault → 选择 obsimind 文件夹。
建议固定打开下面三个文件在侧边栏，作为"导航入口"：
wiki/index.md— 总索引（最新添加、统计、主题领域）wiki/log.md— 操作日志（AI 每次都写，看这个就知道它动了什么）wiki/QUESTIONS.md— 待探索问题（你说"先到这"时 AI 会把问题存进来）
打开一个终端：
cd ~/Desktop/obsimind # 或你放 obsimind 的路径
claude关键：
claude命令必须在obsimind/目录下启动，它才会自动读取同目录的CLAUDE.md（AI 的操作手册）。
启动后你会进入 Claude Code 的对话界面。
根据你的场景二选一（或同时都做）：
| 场景 | 怎么做 |
|---|---|
| 📄 整理一篇文章 | 把 .md / .pdf / .txt 文件复制到 raw/articles/（或 raw/pdfs/），然后在 Claude 对话里说"处理下 raw 里的新文章" |
| 💻 分析一个代码仓库 | 在终端跑 ./scripts/init-codebase.sh /项目绝对路径（软链进来），然后在 Claude 对话里说"分析仓库 X" |
| ❓ 直接问问题 | 不需要扔素材，直接在 Claude 对话里提问，AI 会查 wiki + 联网补充 |
AI 回答你之后，会在 Obsidian 侧的 wiki/ 下产生新文件。你在 Obsidian 里有几种阅读路径：
- 最新添加：看
wiki/index.md的"最近添加"表格，从最新一行点进去 - 按类型：
wiki/sources/— 每篇文章的来源摘要（每篇一页）wiki/concepts/— 文章里抽出来的通识概念wiki/codebases/<repo>/00-overview.md— 某个代码仓库的学习入口wiki/topics/— 按领域做的金字塔导航页（文章/代码攒多了之后 AI 会自动建）
- 跟着链接跳：任何一个 wiki 页都有
[[相关概念]]双链，点开就能串着看 - 关系图：Obsidian 左下角的"图谱视图"（Graph view）能看到整个知识网络
| 你说的话 | AI 做什么 |
|---|---|
继续 / 上次没看完的 |
列出所有进行中的章节 + QUESTIONS.md 里待探索问题 |
健康检查 |
跑 scripts/lint.py，汇报断链、孤儿、缺 frontmatter、代码仓软链失效等 |
先到这 |
把没答完的问题存到 QUESTIONS.md，章节进度保存，下次接着来 |
适用：看到一篇好文章、下载了一份 PDF、用 Web Clipper 剪藏了一个博客页。
流程：
1. 把文件放进 raw/articles/ 或 raw/pdfs/ 或 raw/clippings/
2. 终端里跟 Claude 说："处理下 raw 里的新文章"
3. AI 做 INGEST：
- 读原文
- 在 wiki/sources/<文章名>.md 写来源摘要（含原文核心观点）
- 从原文抽概念，每个概念写到 wiki/concepts/<concept>.md
- 抽关键实体（人/公司/产品），写到 wiki/entities/
- 建立 [[Wikilink]] 交叉引用
- 更新 wiki/index.md 的"最近添加"
- 在 wiki/log.md 记一笔
4. 在 Obsidian 里阅读：
- 入口选 wiki/index.md，找到刚加的那条，点进去
- 或直接打开 wiki/sources/<文章名>.md
- 沿着 [[链接]] 往下跳看每个概念
适用：想吃透一个开源项目（vllm / langchain / 你同事的代码仓）。
类似 zread.ai 的"小白陪学"体验：给 AI 一个代码仓库，它分层 L0~L5 陪你吃透，对话自动沉淀到 wiki。
cd ~/Desktop/obsimind
./scripts/init-codebase.sh /绝对路径/到/你的/项目
# 例：./scripts/init-codebase.sh ~/Desktop/vllm
# 可选指定别名：./scripts/init-codebase.sh ~/Desktop/vllm my-vllm脚本会在 raw/codebases/<项目名>/ 创建软链，不复制源码（节省空间，且源码更新自动同步）。
在 Claude 对话里说：
分析仓库 vllm
AI 会执行 CODEBASE_INIT，三轮扫描（结构/架构/流程）后生成：
wiki/codebases/vllm/00-overview.md— L0 全景入口（含金字塔图）wiki/codebases/vllm/curriculum.md— 六章学习大纲（L0~L5）wiki/codebases/vllm/glossary.md— 项目专有术语表wiki/codebases/vllm/qa-log.md— 追问索引
AI 初始化完成后，你要去 Obsidian 里打开两个文件作为学习起点：
wiki/codebases/<项目名>/00-overview.md— 先看全景，建立宏观印象wiki/codebases/<项目名>/curriculum.md— 再看大纲，知道整条学习路径
看过大纲后回到 Claude Code，说：
开始学 vllm 第 1 章
AI 执行 CODE_TUTOR，每章按：
- 预读（列出本章要理解的 3 件事 + 对应源码文件）
- 讲解（类比 → 代码片段 → 原理拆解）
- 自测题（2~3 个）
- 推荐拓展方向（3~5 个）
结果写入对应章节页：
- L1 架构 →
01-architecture.md - L2 核心模块 →
02-modules/<模块名>.md（每模块一页） - L3 关键流程 →
03-flows/<流程名>.md - L4 设计模式 →
04-patterns/<模式名>.md - L5 踩坑 →
05-pitfalls.md
在 Obsidian 里跟着节奏读：AI 每写完一个章节页，你就在 Obsidian 里打开它看，不懂的回到 Claude 追问即可。
学习中任何不懂的都可以直接问，例如：
这个 scheduler.schedule() 具体怎么做的？
AI 执行 CODE_DIVE：
- 给出
raw/codebases/vllm/vllm/core/scheduler.py:123这种精确定位 - 画出调用链（谁调它、它调谁）
- 答案追加到当前章节页的
## FAQ段（不会散到其他地方） - 通识概念（如 PagedAttention）同时写到
wiki/concepts/，建立双向 Wikilink
先到这
→ 当前章节进度保存到 curriculum.md（状态改为"进行中"），未答完的问题进 QUESTIONS.md
继续
→ 下次说这个，AI 会合并列出所有进行中的章节 + 待探索问题，供你选择从哪恢复
当你学完 2+ 个相关仓库后：
vllm 和 sglang 在调度策略上有什么区别？
AI 生成 wiki/synthesis/comparison-scheduling.md 对比分析页。
当某个领域累积了 2+ 仓库 + 5+ 概念后：
整理一下 AI Infra 领域的入口
AI 在 wiki/topics/ai-infra.md 自动编排金字塔导航页，版式对齐你手写的分层知识入口（定义 → 为什么重要 → N 层金字塔 → 学习路径 A/B/C/D）。
这就是你最终的"有逻辑有层次感"的个人知识库入口页。
obsimind/
├── CLAUDE.md # 系统配置（Claude Code 的操作手册）
├── README.md # 本文件
├── raw/ # 原始素材（不可变）
│ ├── articles/ # 文章
│ ├── clippings/ # Web Clipper 剪藏
│ ├── conversations/ # 对话提取的知识
│ ├── codebases/ # 代码仓库软链（由 init-codebase.sh 创建）
│ ├── images/ # 本地图片
│ ├── pdfs/ # PDF 文件
│ └── notes/ # 随手笔记
├── wiki/ # LLM 编译层（自动维护）
│ ├── index.md # 总索引
│ ├── log.md # 操作日志
│ ├── QUESTIONS.md # 待探索问题
│ ├── concepts/ # 通识概念页
│ ├── entities/ # 实体页
│ ├── sources/ # 来源摘要
│ ├── synthesis/ # 综合分析（含跨仓库对比）
│ ├── topics/ # 主题聚合金字塔入口
│ ├── codebases/ # 代码仓库教学子库（L0~L5 分层）
│ │ └── <repo>/
│ │ ├── 00-overview.md
│ │ ├── 01-architecture.md
│ │ ├── 02-modules/
│ │ ├── 03-flows/
│ │ ├── 04-patterns/
│ │ ├── 05-pitfalls.md
│ │ ├── curriculum.md
│ │ ├── glossary.md
│ │ └── qa-log.md
│ └── templates/ # 页面模板
├── outputs/ # 输出层
│ ├── qa/ # 问答记录
│ ├── reports/ # 研究报告
│ └── learning/ # 代码仓库陪学会话归档
└── scripts/
├── lint.py # 健康检查脚本
└── init-codebase.sh # 代码仓库软链脚本
| 你说的话 | Claude 做的事 |
|---|---|
| "处理下 raw 里的新文章" | 读取、分类、提取、编译到 wiki |
| "XX 是什么" / "XX 和 YY 的区别" | 搜索 wiki + 联网搜索 + 知识拓扑拓展 |
| "帮我查下 XX" | 先查 wiki，不够再联网 |
| "健康检查" / "lint" | 运行检查脚本，汇报问题 |
| "总结下 XX 领域" | 跨来源综合分析 |
| "上次没看完的" / "继续" | 从 QUESTIONS.md + 进行中章节恢复 |
| "1 3"（数字编号） | 继续深挖推荐拓展方向 |
| "先到这" | 保存待探索列表与章节进度 |
| 你说的话 | Claude 做的事 |
|---|---|
| "分析仓库 vllm" / "吃透 vllm" | CODEBASE_INIT：扫描 + 生成 curriculum + overview |
| "开始学 vllm 第 1 章" / "继续学" | CODE_TUTOR：按预读/讲解/自测章节化推进 |
| 学习中追问具体函数、类、机制 | CODE_DIVE：path:line 定位 + 调用链 + 通识概念双写 |
| "vllm 和 sglang 在 X 上的区别" | CODE_REFLECT：跨仓库对比分析 |
| "整理 AI Infra 领域入口" | TOPIC_COMPILE：生成金字塔主题入口页 |
安装 Obsidian Web Clipper 浏览器插件后，设置保存路径为：
obsimind/raw/clippings/
这样浏览器中看到好文章一键剪藏，然后让 Claude 处理即可。
场景：朋友发给你一篇讲 FlashAttention 原理的文章（.md 或 .pdf），你想吃透它，并让它的知识点永久沉淀。
# 假设文章在 ~/Downloads/flashattention-explained.md
cp ~/Downloads/flashattention-explained.md ~/Desktop/obsimind/raw/articles/或者用 Finder 直接拖拽到 raw/articles/ 也行。
cd ~/Desktop/obsimind
claude你：处理下 raw/articles 里的新文章
Claude：我读完了 flashattention-explained.md，这是一篇讲 FlashAttention 原理的文章。
我生成了以下内容：
- 来源摘要：wiki/sources/flashattention-explained.md
- 新概念：
- wiki/concepts/flash-attention.md
- wiki/concepts/tiling.md
- wiki/concepts/online-softmax.md
- wiki/concepts/io-aware-algorithm.md
- 更新了 wiki/index.md 的最近添加列表
建议你从 wiki/sources/flashattention-explained.md 开始看，
那里有原文的核心观点摘要和到各概念页的链接。
在 Obsidian 侧边栏导航：
obsimind/
└── wiki/
├── sources/flashattention-explained.md ← 从这里开始读
└── concepts/
├── flash-attention.md ← 原文的核心概念
├── tiling.md ← 相关技术
├── online-softmax.md
└── io-aware-algorithm.md
每个页面都有 [[双向链接]]，点任何一个 [[xxx]] 都能跳到对应概念页继续读。
读 wiki 时遇到不懂的，回到 Claude 继续问：
你：tiling 这个概念我还是不太懂，它和传统的 attention 计算有什么区别？
Claude：[详细解释 + 画图 + 代码示例]
我把这个解释补充到 wiki/concepts/tiling.md 的"详细说明"段了，
并且在 wiki/concepts/flash-attention.md 里也加了一段对 tiling 的说明。
📌 推荐继续探索：
1. memory-hierarchy — 理解 GPU 显存层次（SRAM vs HBM）
2. recomputation — FlashAttention 如何用重算换显存
3. fused-kernel — 算子融合的工程价值
4. flashattention-v2 — V2 做了什么优化
5. flash-decoding — 推理阶段的 FlashAttention 变种
你：1 3
Claude：好，我继续深挖 memory-hierarchy 和 fused-kernel……
你：先到这，晚上接着看
Claude：好的。已经把以下问题存到 wiki/QUESTIONS.md：
- recomputation 在 FlashAttention 里的具体实现
- flashattention-v2 的改进点
- flash-decoding 与推理的关系
晚上你回来说"继续"就行。
wiki/
├── sources/flashattention-explained.md ← 原文摘要（入口）
├── concepts/
│ ├── flash-attention.md ← 主概念（含 tiling 细节）
│ ├── tiling.md ← 含你追问后补充的解释
│ ├── online-softmax.md
│ ├── io-aware-algorithm.md
│ ├── memory-hierarchy.md ← 追问 1 衍生
│ └── fused-kernel.md ← 追问 3 衍生
├── QUESTIONS.md ← 存着待探索问题
└── log.md ← 每次操作都有记录
你此时 Obsidian 的 Graph View 会看到一张由 FlashAttention 串起来的概念网络，点任何一个节点都能追溯到原文和追问链路。
场景：你想从零理解 vLLM 这个项目，已经把它 clone 到本地 ~/Desktop/vllm。
cd ~/Desktop/obsimind
./scripts/init-codebase.sh ~/Desktop/vllm脚本输出：
✅ 软链已创建：
/Users/you/Desktop/obsimind/raw/codebases/vllm
→ /Users/you/Desktop/vllm
下一步：在 Claude Code 里对 ObsiMind 说：
分析仓库 vllm
cd ~/Desktop/obsimind
claude对话：
你：分析仓库 vllm
Claude：我正在扫描 raw/codebases/vllm……
【结构扫描】
- 主语言：Python（96%）
- 入口：vllm/entrypoints/api_server.py, vllm/engine/llm_engine.py
- 依赖：torch, ray, xformers, pydantic, fastapi
【架构扫描】识别出 5 层：
- entrypoints/ — HTTP/CLI 接口
- engine/ — 核心调度引擎
- core/ — 调度器、块管理
- worker/ — 执行器（GPU 上跑的进程）
- model_executor/ — 模型加载与前向
【流程扫描】识别出 4 条主线：
- 请求生命周期（请求进入 → 返回 token 流）
- 服务启动流程
- 调度循环（scheduler 每步做什么）
- KV Cache 块管理
我生成了：
- wiki/codebases/vllm/00-overview.md — 全景入口（含金字塔图）
- wiki/codebases/vllm/curriculum.md — L0~L5 学习大纲
- wiki/codebases/vllm/glossary.md — 项目术语表
- wiki/codebases/vllm/qa-log.md — 追问索引
建议你先去 Obsidian 里打开 00-overview 和 curriculum 看一遍，
然后回来说"开始学 vllm 第 1 章"。
打开顺序：
1. wiki/codebases/vllm/00-overview.md ← 看金字塔图，建立宏观印象
2. wiki/codebases/vllm/curriculum.md ← 看学习路线
你：开始学 vllm 第 1 章
Claude：好，进入 L1 架构章节。
【预读】本章你要理解的 3 件事：
1. vLLM 的分层结构：entrypoints → engine → core → worker
2. engine 和 worker 如何协作（Ray 进程模型）
3. 一次请求的数据流向
【讲解】
类比：想象一个餐厅……
- entrypoints = 前台接待
- engine = 大堂经理（负责排队、派菜）
- core.scheduler = 菜单调度员（决定先做哪道菜）
- worker = 厨师（真正做菜 = GPU 前向）
代码片段（raw/codebases/vllm/vllm/engine/llm_engine.py:132）：
[贴 20 行关键代码]
原理拆解：
1. 请求进入 → entrypoints 的 FastAPI 路由
2. engine.add_request() 把请求入队
3. engine.step() 循环：scheduler.schedule() → worker.execute_model()
4. 每个 step 吐一批 token 回给客户端
【自测题】
1. engine.step() 为什么是"每步吐一批"而不是"一次吐完整个回答"？
2. 如果把 scheduler 换成 FIFO，会发生什么？
3. worker 放在独立进程的价值是什么？
📌 推荐继续探索：
1. 调度器内部逻辑（L2 scheduler 模块）
2. Ray 进程模型（L2 worker 模块）
3. KV Cache 块分配（L3 kv-cache 流程）
4. 请求生命周期（L3 request-lifecycle 流程）
5. Continuous Batching（L3 batching 流程）
已更新：
- wiki/codebases/vllm/01-architecture.md（新建）
- wiki/codebases/vllm/curriculum.md（L1 状态：进行中）
打开 wiki/codebases/vllm/01-architecture.md，读完后不懂的回到 Claude：
你：scheduler 内部到底是怎么选下一步处理哪些请求的？
Claude：[CODE_DIVE 模式]
定位：raw/codebases/vllm/vllm/core/scheduler.py:234 的 _schedule() 方法
调用链：
engine.step()
└─ scheduler.schedule()
└─ scheduler._schedule()
├─ _schedule_prefills()
└─ _schedule_running()
核心逻辑：[详细讲解]
这里涉及到的"连续批处理（Continuous Batching）"是一个通识概念，
我已经把通识解释写到 wiki/concepts/continuous-batching.md，
同时在 wiki/codebases/vllm/01-architecture.md 的 ## FAQ 段
加了一条针对 vllm 的具体实现说明。
对话归档到：outputs/learning/vllm/01-architecture-20260417-1530.md
你：先到这，明天接着学 L2
Claude：好的。curriculum.md 里 L1 状态已改为"进行中"，
明天你说"继续"就会看到恢复选项。
你：继续
Claude：你当前有 1 个进行中的学习和 2 个待探索问题：
进行中：
- [vllm] L1 架构（已读完基础，待追问：scheduler 细节）
待探索（QUESTIONS.md）：
- vLLM 和 SGLang 在 KV Cache 上有什么设计差异？
- Ray 在 vLLM 里具体怎么用的？
想从哪个继续？
等你同样把 SGLang 吃透（重复 Step 1~6），就可以说：
你：vllm 和 sglang 在 KV Cache 管理上有什么区别？
Claude：[CODE_REFLECT] 我对比了：
- wiki/codebases/vllm/03-flows/kv-cache.md
- wiki/codebases/sglang/03-flows/kv-cache.md
生成对比分析到：wiki/synthesis/comparison-kv-cache.md
主要差异：
| 维度 | vLLM | SGLang |
|------|------|--------|
| 核心机制 | PagedAttention | RadixAttention |
| ...
wiki/
├── topics/
│ └── ai-infra.md ← 金字塔总入口（TOPIC_COMPILE 生成）
├── codebases/
│ ├── vllm/
│ │ ├── 00-overview.md ← 全景
│ │ ├── 01-architecture.md ← L1
│ │ ├── 02-modules/{scheduler,worker,engine}.md ← L2
│ │ ├── 03-flows/{request-lifecycle,kv-cache,batching}.md ← L3
│ │ ├── 04-patterns/{ray-actor-model,async-step}.md ← L4
│ │ ├── 05-pitfalls.md ← L5
│ │ ├── curriculum.md ← 进度表
│ │ ├── glossary.md ← 术语
│ │ └── qa-log.md ← 追问索引
│ └── sglang/{...}
├── concepts/
│ ├── continuous-batching.md ← 从 vllm 学习中沉淀
│ ├── paged-attention.md
│ ├── radix-attention.md
│ └── ...
└── synthesis/
└── comparison-kv-cache.md ← 两个仓库的对比
最终你点开 wiki/topics/ai-infra.md，能看到一张类似 AI 知识整理 那样的分层金字塔，入口页 → 概念 → 代码仓库全部串起来，每一项都可以追溯到它最初来自哪篇文章或哪段源码。
Q: 我已经扔文章进 raw/articles/ 了，但 Claude 不知道？
A: 确认你是在 obsimind/ 目录下启动的 claude 命令。如果还不行，直接说：读 raw/articles/<文件名>.md 并处理它。
Q: init-codebase.sh: permission denied？
A: 加执行权限：chmod +x scripts/init-codebase.sh
Q: Obsidian 里看不到新文件？
A: Obsidian 默认会自动同步，如果没刷新按 Cmd+R（macOS）重新载入 vault。
Q: 我想换个不同的仓库分析，之前那个要删掉吗？
A: 不用。直接 ./scripts/init-codebase.sh <新仓库路径>，多个项目在 raw/codebases/ 和 wiki/codebases/ 下并存互不影响。要删只需 rm raw/codebases/<old-repo>（删软链）+ rm -rf wiki/codebases/<old-repo>（删教学子库）。
Q: 怎么知道 AI 到底改了哪些文件？
A: 打开 wiki/log.md，每次操作都有详细记录（操作类型 / 触发 / 变更清单 / 摘要）。