Van's Wiki

HANDBOOK

14分钟阅读

📘 selfwiki 使用手册

这是给你（Van）看的操作手册。CLAUDE 是给 AI agent 看的规约。先通读一遍，然后把感兴趣的章节加书签。

第一部分 · 这套系统为什么存在

你每天在 抖音 / B 站 / 小红书 / YouTube / X / 微信公众号 上吸入大量内容。以前下载完就忘，要找的时候翻不到。这个 vault 解决三件事：

  1. 记忆 — 每条下载的内容都变成一篇永久可搜的笔记
  2. 综合 — AI 总结 + 互相关联，形成会复利的知识图（Karpathy 的 LLM Wiki 模式）
  3. 注意力 — 每天 5 分钟扫一眼 Dashboard，看真正值得花时间的，而不是原始信息洪流

vault 就是一堆 纯 Markdown 文件，自托管 LiveSync 同步——没有私有格式，所有权在你，AI 直接读不需要解析。核心路径不依赖向量数据库，wiki 本身就是索引（Karpathy 2026）。

第二部分 · 架构（三层）

第一层 · 原始素材               ← @vanswbot 下载，不可变
  /Volumes/GAMES/mediadownload/<platform>/

第二层 · WIKI（AI 维护，你阅读）
  00-Inbox/_processed/           候选笔记（自动）
  30-Resources/notes/            原子概念页
  30-Resources/MOCs/             主题地图
  30-Resources/atlas/            常青知识（Nick Milo）
  10-Projects/ / 20-Areas/       PARA 行动层
  40-Archive/ / 50-Digests/      存档 + 摘要
  60-Toolbox/                    自动安装的 CLI 工具

第三层 · SCHEMA（AI 和你都遵守）
  CLAUDE.md                      规则
  index.md                       目录
  log.md                         事件日志
  _meta/templates/               笔记模板
  _meta/skills/                  AI 可调用工作流

铁律：AI 永远不动第一层。AI 拥有第二层。两边都遵守第三层。完整规约见 CLAUDE。

第三部分 · 七大工作流

3.1 收集（你，10 秒）

往 @vanswbot 发链接，完事。

Bot 自动识别平台 → 调 douyin-downloader（YouTube/抖音/TikTok/小红书）或 yt-dlp（B 站）或 r.jina.ai（任意网页）→ 文件落 /Volumes/GAMES/mediadownload/<platform>/。

也可以直接编辑 00-Inbox/Inbox.md，一行一个 URL。

3.2 摄入（自动，约 2 分钟）

pkm-processor LaunchAgent 每 60 秒轮询一次：

  1. 发现新媒体 + manifest 条目
  2. 转写（faster-whisper large-v3-turbo）
  3. Claude Sonnet 总结（title / summary / key_points / tags / route / install_commands）
  4. 候选笔记写到 00-Inbox/_processed/<日期>/<slug>.md
  5. 复制附件（transcript.md、thumb.jpg、caption.md、图片）
  6. Compile — 提取实体，链已有概念页，append log.md（Karpathy 步骤）

3.3 分诊（你，每天 5 分钟）

打开 Dashboard，扫「🔥 今天该看」卡片墙。每条：

判断操作
没价值status: 改 skipped
有点意思status: 改 learning，留着继续
看完了status: 改 learned，加 learned_at:，写 your_notes:
值得蒸馏稍后跑 _meta/skills/distill.md

3.4 蒸馏（你触发，AI 执行，按需）

某个主题你已经 学完 了 ≥3 条笔记，跑蒸馏：

$ cd ~/Documents/selfwiki && claude
> 按 _meta/skills/distill.md 蒸馏主题 "agent-orchestration"

输出：30-Resources/notes/ 下一篇更新过的概念页 + 对应 MOC。源笔记归档。可选 Express 输出（LinkedIn 帖子 / Twitter 长串 / 博客草稿 / 抖音口播脚本）。

3.5 提问（你，按需）

三种模式：

  • A 模式 — Smart Connections（Cmd+P → “Smart Connections: Open chat”）：快速语义搜索，适合”找相似”
  • B 模式 — Claude Code + MCP：全功能 agent + vault 工具，适合”跨主题综合”
  • C 模式 — question-and-file：如果问题会重复出现，把答案落成永久笔记（复利）
> 按 _meta/skills/question-and-file.md 问问题 "什么时候该用 RAG，什么时候该用 LLM Wiki?"

3.6 体检（自动，每周一上午 9 点）

pkm-linter LaunchAgent 跑 _meta/scripts/linter.py：

  • 发现孤儿概念页（无入度且 > 30 天）
  • 发现陈旧 inbox（未读超过 7 天）
  • 自动补缺失的 frontmatter 字段
  • 标记 tag 漂移（低频 tag 建议合并）
  • 标记过时版本声明
  • 标记陈旧 MOC（>30 天没动）

报告 → 50-Digests/lint/<iso-周>.md，你看完决定。

3.7 复盘（你，每周）

每周一上午：

  1. 看本周 50-Digests/weekly/<iso-周>.md（pkm-reviewer 自动生成）
  2. 看本周 lint 报告 50-Digests/lint/<iso-周>.md
  3. 看 Dashboard 的「⚠️ Compile 候选」区，用 entity-extract.md 把成熟的实体晋升成概念页
  4. 把本周真正持久的洞察单独存到 30-Resources/notes/

第四部分 · 状态生命周期

unread  →  learning  →  learned  →  archived
              ↘
                skipped（终态）

每次状态变化，需要改的字段：

转换你要改的
→ learningstatus: learning
→ learnedstatus: learned，learned_at: <ISO>，your_notes: "..."
→ skippedstatus: skipped（终态，reviewer 不再骚扰你）
→ archived蒸馏后手动 move 到 40-Archive/<原路径>/

可以用 QuickAdd 配快捷宏（见第七部分）。

第五部分 · 笔记类型一览

type在哪生命周期模板
articleinbox → 路由后分诊 → learned / skippedliterature
tutorialinbox → 路由后+ 可能触发 installerliterature
toolinbox → 路由后+ 可能触发 installerliterature
newsinbox7 天自动归档literature
inspirationresources 或 archive很少持久literature
researchresources永久literature
conceptresources/notes永久、原子、常青concept
mocresources/MOCs永久、持续生长moc
（person）resources/notes（子类型）永久person
（project）10-Projectsactive → done → archivedproject

外加元类型：transcript、digest、log、dashboard、handbook、catalog、setup-doc。

第六部分 · Skills 目录（AI 能帮你做什么）

放在 _meta/skills/。每个 skill 是一个 markdown 文件，Claude Code 读完照着步骤执行。

Skill一句话
compile-noteKarpathy ingest 步骤——把新笔记链接到已有概念页
update-mocs用当前笔记集刷新所有 MOC
weekly-lint跑 7 项健康检查，出报告
distillTiago Forte CODE 蒸馏——把学过的某个主题晶化成常青知识
find-orphans找出无入度的概念页
merge-duplicates检测重叠的概念页，提合并方案
backlink-suggest找”应链未链”的笔记对
entity-extract把候选实体晋升成概念页
research-deep多源深度调研 + MOC + 概念页
question-and-fileKarpathy C 模式——问答 → 永久笔记（复利）

怎么调用

$ cd ~/Documents/selfwiki && claude
> 按 _meta/skills/<skill-name>.md 执行 [可选输入参数]

MCP 配置（让 Claude 拥有 vault 全工具）见 mcp-setup。

第七部分 · Obsidian 插件配置建议

已装：Dataview · DataCards · Smart Connections · QuickAdd · InsightA · Obsidian MCP。

推荐配的 QuickAdd 宏

Settings → QuickAdd → 添加新 choice：

宏 1：标记当前笔记为 Learned

  • 类型：Macro
  • 快捷键：Cmd+L
  • 步骤：
    1. Update YAML：status: learned
    2. Update YAML：learned_at: {{DATE:YYYY-MM-DDTHH:mm:ssZ}}

宏 2：标记当前笔记为 Skipped

  • 类型：Macro
  • 快捷键：Cmd+K
  • 步骤：
    1. Update YAML：status: skipped
    2. Update YAML：learned_at: {{DATE:YYYY-MM-DDTHH:mm:ssZ}}

宏 3：从当前笔记启动 Distill

  • 类型：Macro
  • 快捷键：Cmd+D
  • 步骤：
    1. Capture：打开终端，粘贴 prompt：按 _meta/skills/distill.md 蒸馏主题 "{{topic}}"

Smart Connections 配置

Settings → Smart Connections：

  • 嵌入模型：Ollama 的 nomic-embed-text（免费、本地、M4 Pro 上很快）—— 先 ollama pull nomic-embed-text
  • 对话模型：Claude API（最好）或本地 Ollama（如 llama3.2，免费）
  • 索引文件夹：包含 00-Inbox/_processed、30-Resources/、10-Projects/、20-Areas/；排除 40-Archive/、60-Toolbox/installed/、_meta/
  • 嵌入刷新：文件变更时

InsightA 配置

Settings → InsightA：

  • Provider：Anthropic 或 OpenAI（看你有哪个 key）
  • MOC 输出目录：30-Resources/MOCs/
  • 原子笔记目录：30-Resources/notes/
  • 默认语言：中文

第八部分 · 日 / 周 / 月节奏

每日（5 分钟）

  1. 打开 Dashboard
  2. 扫「🔥 今天该看」卡片（3-5 条高优）
  3. 每条：读 Summary → 决定 → 改 status:
  4. 扫「📖 学习中」——继续未完成的
  5. （可选）问 Smart Connections 一个问题

每周（30 分钟，周一上午）

  1. 看 50-Digests/weekly/<iso-周>.md
  2. 看 50-Digests/lint/<iso-周>.md
  3. 处理被标记的项（孤儿、陈旧、tag 漂移）
  4. Dashboard 显示有 ≥3 次提及的候选实体 → 跑 entity-extract
  5. 对积累了学习的 1-2 个主题跑 distill
  6. 更新活跃项目状态（10-Projects/<project>/）

每月（60 分钟，每月第一个周一）

  1. 回看过去 4 份周报
  2. 把持久洞察晋升到 30-Resources/atlas/（Nick Milo 常青层）
  3. 审计 10-Projects/ —— 哪些完了、暂停、放弃？
  4. 审计 20-Areas/ —— 还相关吗？
  5. 对你想深入理解的主题跑 research-deep
  6. 如果惯例需要演化，更新 CLAUDE

第九部分 · 哲学（规则背后的理由）

为什么用 Karpathy 的 LLM Wiki，不用 RAG？

RAG 每次查询都要从原始 chunk 里找。理解和检索的成本每次都付。Karpathy 的洞察：让 LLM 把语料一次性 compile 成 markdown wiki。之后查询只需便宜的 lookup + 小综合窗口。号称比 RAG 效率高 70 倍。而且随时间复利。

为什么 PARA + Zettelkasten + Atlas 三套并存？

  • PARA（Tiago Forte）：行动层。这条笔记在你当下生活里的位置是什么？
  • Zettelkasten（Niklas Luhmann）：思想层。原子想法是什么？跟谁对话？
  • Atlas（Nick Milo）：持久层。不管你当下在哪个项目里，这个知识都成立吗？

三层各司其职，合起来覆盖 Inbox → 行动 → 综合 → 智慧。

为什么人还在回路里？

Karpathy：人类负责选源 + 提问，LLM 负责 bookkeeping。没有你的编辑方向，wiki 会漂成噪声。没有 LLM 的 bookkeeping，你会被淹死。

为什么 CLAUDE.md 是”宪法”？

让所有 AI 工具（Claude Code、Codex CLI、Gemini CLI、MCP 客户端）按同一套规则操作。改 CLAUDE.md → 所有 agent 立刻按新规则执行。Schema 是版本化的，漂移可以恢复。

为什么要 log.md？

过去的动作变得可查询。“我上次碰这个概念是什么时候？” “上个月我问过 vault 什么问题？” log 是系统的记忆。Linter 用它检测活动间隙，Karpathy 用它做时间感知查询。

第十部分 · 排错

”我给 Telegram 发了链接，bot 不回”

launchctl list | grep pkm-bot          # 是否加载？
tail 00-Inbox/_state/logs/pkm_bot.log  # 它怎么说
curl -s "https://api.telegram.org/bot$TG_PKM_BOT_TOKEN/getMe"  # token 还有效吗

参考 _meta/mcp-setup.md 和早期会话记忆 13bf9eb2（Full Disk Access 坑）。

“下载了视频，但没出笔记"

ls -lt /Volumes/GAMES/mediadownload/<platform>/ | head     # 文件落了吗
tail 00-Inbox/_state/logs/processor.log                    # processor 视角
cat 00-Inbox/_state/seen.json | jq '. | length'           # seen 多少条

"Dashboard 表格全空”

  • Dataview 插件必须启用（Settings → Community plugins）
  • ”🔥 今天该看”卡片视图需要 DataCards 插件启用
  • 部分查询要求笔记有 priority: frontmatter，抽样看几篇笔记

”Compile 阶段不跑”

  • 检查 PKM_COMPILE_ENABLED 环境变量不要是 0
  • 检查 LaunchAgent 上下文里 claude CLI 在 PATH 中
  • python3.13 -m py_compile _meta/scripts/compile_stage.py 看能不能编译
  • processor.log 找 COMPILE-ERR 记录

”Linter 从不跑”

  • launchctl list | grep pkm-linter 看 status 是 0
  • 手动触发：python3.13 _meta/scripts/linter.py
  • LaunchAgent 只在周一 9 点触发

”MCP 看不到 vault”

  • Obsidian 必须正在运行且 selfwiki vault 已打开
  • 启用 “Obsidian MCP” 插件
  • 参考 _meta/mcp-setup.md

”想回滚一次坏的 compile”

Compile 阶段会改概念页。回滚方式：

# 如果已经 git init：
git diff HEAD -- 30-Resources/notes/
git checkout HEAD -- 30-Resources/notes/<page>.md
 
# 没 git：用 LiveSync 的 per-file 历史（每篇笔记 "View history"）

（强烈推荐：cd /Users/vanmiku/Documents/selfwiki && git init && git add -A && git commit -m "Karpathy 模式基线" —— 之后所有改动都能撤销。）

第十一部分 · 命令速查

收集            → Telegram 发链接给 @vanswbot
打开今天         → Cmd+O → Dashboard
标记 learned    → Cmd+L（配过 QuickAdd 宏后）
标记 skipped    → Cmd+K
AI 查询         → Cmd+P → "Smart Connections: Open chat"
蒸馏主题         → cd ~/Documents/selfwiki && claude
                  > 按 _meta/skills/distill.md 蒸馏 "<主题>"
编译笔记         → > 按 _meta/skills/compile-note.md 处理 <笔记路径>
问答 + 落档      → > 按 _meta/skills/question-and-file.md 问 "<问题>"
深度调研         → > 按 _meta/skills/research-deep.md 调研 "<主题>" --web true
刷新 MOC        → > 按 _meta/skills/update-mocs.md
找孤儿          → > 按 _meta/skills/find-orphans.md
手动跑 linter   → python3.13 _meta/scripts/linter.py
看日志          → tail -F 00-Inbox/_state/logs/{pkm_bot,processor,linter}.log
LaunchAgent     → bash _meta/launchd/install-launchd.sh {load|unload|status}

第十二部分 · 什么时候演化这份手册

这份手册是 版本化的。当工作流变化——新的 skill、新的自动化、哲学转向——同时更新 CLAUDE（规则）和 HANDBOOK（这个文件）。

最后更新：2026-05-28，Claude 初稿，Karpathy 模式落地后

Graph View

反向链接