Sep 22, 2026

claude-obsidian 把你的 vault 变成带出处引用的知识库

一套 15k-star、含 15 个 skill 的系统，配合 Claude Code 把资料吸收进 Obsidian vault：出处台账、有据可查的回答、可恢复的事务——本地 Markdown，不依赖云端。

#tutorial#obsidian#productivity

大多数 AI 笔记工作流止步于"把文字存下来"。claude-obsidian 是一套 15k-star、面向 Claude Code 及兼容 Agent Skills 宿主的本地优先知识系统，它围绕一个更长的闭环构建：捕获来源、给每个论断找到依据、把笔记连成网，再让 vault 重新为你所用。你的知识始终是一份由 Markdown、JSON 和源文件组成的普通目录——不是插件缓存，也不是云数据库。

为什么这个 Skill 重要

整套系统自带 15 个 skill，共享同一个证据模型。五个用来搭建和使用 wiki：wiki（初始化或收编 vault 并分发任务）、save（保存一条有范围限定的回答，绝不自动转录）、wiki-ingest（把来源变成带出处记录的关联页面）、wiki-query（只依据 vault 内证据做只读回答）、wiki-lint（死链、孤儿笔记、过期索引）。七个扩展工作流，包括带显式出网许可的有界网络调研 autoresearch、做 BM25 检索的 wiki-retrieve、管理归档约定的 wiki-mode。另有三个参考类：obsidian-markdown、obsidian-bases、think。

两个设计让它区别于聊天套壳工具。每条会改动状态的安装命令都分两阶段执行——先打印一份带 approved_plan_sha256 的 JSON 计划，只有当你把同一个哈希传回去才真正应用；并行 worker 只返回草稿，由一个编排者应用单个可恢复事务。README 也把边界写得很清楚：PDF 和 EPUB 捕获只存元数据、哈希和大小，没有内置的语义抽取；URL 或 YouTube 捕获需要配置外部 runner。

安装

需要 Python 3.11 或更新版本。先克隆产品本身，再初始化一个独立的 vault：

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "2026-09-22T00:00:00Z" --operation-id "init-reviewed"

命令会打印一份计划。复制其中的 approved_plan_sha256，带上 --approved-plan-sha256 <sha256-from-the-plan> --apply 重新执行即可创建 vault。想用现有的 Obsidian vault，README 指向其安装指南中的非破坏性 adopt 工作流。

然后在 Obsidian 里打开这个目录，并从该目录以本地插件方式启动 Claude Code：

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian

实战：吸收一份资料，再向 vault 提问

从 /claude-obsidian:wiki 起步，然后把一份源文件放进 vault 的 inbox/ 目录。
把它变成带出处引用的关联页面：

/claude-obsidian:wiki-ingest

提一个问题，回答只依据 vault 内的证据：

/claude-obsidian:wiki-query

把值得保留的回答存下来：

/claude-obsidian:save

每条保存都有明确的范围——save 这个 skill 存在的意义，就是不让对话悄悄变成笔记。

实战：接入非 Claude 的 agent 宿主

对于 Codex、OpenCode、Gemini 或 ZCode，先预览再应用可移植的 skill 链接：

bash scripts/setup-multi-agent.sh --host codex
bash scripts/setup-multi-agent.sh --host codex --apply

Cursor 和 Windsurf 走工作区本地的 skill 发现机制。

技巧

大量吸收资料的日子过后跑一次 /claude-obsidian:wiki-lint——它会报告死链、孤儿笔记、元数据缺失和空段落。
wiki-mode 支持 Generic（默认）、LYT、PARA、Zettelkasten 四种归档方式；切换模式只改变新笔记的路由，绝不会批量搬动旧笔记。
在原生 Windows 上，只读与试运行命令可用，但写 vault 必须走 WSL——否则命令以 UNSUPPORTED_PLATFORM 错误直接失败。
其设计沿用 Andrej Karpathy 的 LLM Wiki 模式，并以 kepano/obsidian-skills 作为 Obsidian 语法的参考基底。

何时不用这个 Skill

README 自己划定了边界：它不是自动转录记录器，不是云同步服务，不是事实神谕，也不能替代备份和版本控制。如果你的资料以 PDF 和 EPUB 为主并期待开箱即用的语义抽取，能力表写得很清楚——只存元数据、哈希和大小，没有内置语义抽取。另外，如果你想要零仪式感，"先出计划再批准应用"的流程会给每个改动操作加一步——这份摩擦就是它的安全模型，不会为你关掉。

查看排行榜了解更多 skill。