claude-obsidian：本地优先的 AI 第二大脑（Obsidian + Claude Code）

相关：Claudian：把 AI 编程代理嵌入 Obsidian 的插件 · obsidian-skills 使用指南

一句话定位

claude-obsidian（github.com/AgriciDaniel/claude-obsidian）不是「又一个 AI 笔记插件」，而是一套给 Claude Code（及兼容 Agent Skills 宿主）用的知识管理系统：它把来源材料变成互相链接、带溯源（provenance）的 Obsidian 页面，并用显式的工作流支撑检索、维护和可视化。产品仓库和你自己的 vault 是两个分离的东西——你克隆的是产品，另外 init 一个 vault 才是你的知识库。

指标	数值
Stars	10,965
Forks	1,270
Open Issues	132
Commits	243
License	MIT
最新版本	v2.1.0
主语言	Python（可移植核心）
定位来源	Andrej Karpathy 的「LLM Wiki」模式

四个反直觉的设计选择

这套系统真正的辨识度不在功能列表，而在几处「拒绝默认」的取舍：

1. 本地优先，出口显式：vault 是用户目录里的普通文件，网络出站（web research、远程模型）是单独的、需要同意的决定，不是默认行为。
2. 来源比总结活得更久：笔记始终指回可复现的 source 证据；未被支持 / 相互矛盾的论断保持可见，不被悄悄抹掉。
3. 事务化写入，而非「直接写文件」：一次逻辑操作 = 一次可恢复的事务，见下文协议。
4. 诚实的边界：能力矩阵如实标注「已实现 / 需外部 runner / 需同意」；模型检索不可信时回退到确定性的 BM25；「有根据的拒绝，好过编造一条引用」。

知识循环：捕获 → 求证 → 连接 → 复用

这是理解整个系统的心理模型：

1. 带上下文地捕获——来源先进入可见的 inbox/，不可变的、内容寻址（content-addressed）的副本在合成之前就被保留进 .raw/。
2. 给每条重要论断留底——source 与 claim 两层台账记录权威性、新鲜度、支持度、矛盾、置信度与审阅状态。
3. 把学到的东西连起来——链接页、索引、MOC、方法论相关的结构、Obsidian Canvas 视图。
4. 让 vault 被再次使用——查询、研究、检索、lint，把已知内容折回新知识。

明确不做的事：不是自动转写录音机、不是云同步服务、不是事实预言机、不是备份/版本控制的替代品。

事务化写入协议（5 步）

这是「为什么它敢让 agent 写文件」的答案——每一次写操作都可审阅、可回滚：

1. 读目标文件，记录期望的 SHA-256；
2. 并行 worker 只返回草稿和证据，不做任何写操作；
3. 合并成一个 claude-obsidian.transaction.v1 bundle；
4. 人工审阅 bundle 后，一次性应用；
5. 报告操作 ID 与确切的改动路径。

配套机制：单一编排器负责「审阅 + 应用」，进程生命周期内持有 vault 锁、日志化备份、原子替换、应用失败即恢复先前状态。禁止直接共享写、废弃的 wiki-lock.sh、以及泛化的生命周期自动提交。

15 个 Skill 的分工

组	Skill	一句话职责
构建 wiki	wiki	初始化/采纳 vault、诊断就绪度、路由工作
	save	保存一条有边界的答案/洞察（绝非自动转写）
	wiki-ingest	把捕获来源转成带溯源记录的链接页
	wiki-query	从 vault 证据中做只读问答
	wiki-lint	报告死链、孤儿页、元数据缺口、过期索引、空节
扩展工作流	autoresearch	有边界的联网研究 + 显式出口 + 规范合并
	canvas	wiki 范围内的 Obsidian Canvas 创建/维护
	defuddle	摄取前把网页清洗成干净 Markdown
	wiki-fold	对操作日志做抽取式、可追溯的总结
	wiki-mode	Generic / LYT / PARA / Zettelkasten 归档约定
	wiki-retrieve	上下文前缀 + BM25 + 可选余弦重排
	wiki-cli	Obsidian CLI 读写/搜索 + 事务化写入
参考	obsidian-markdown	正确的 OFM：wikilink、嵌入、callout
	obsidian-bases	原生 .base 表格、卡片、过滤、公式、汇总
	think	observe/listen/connect/create/grow 回顾循环

归档模式（wiki-mode）

模式	归档原则
Generic（默认）	来源、概念、实体、会话四类
LYT	MOC + 链接的原子笔记
PARA	项目、领域、资源、归档
Zettelkasten	稳定 ID、原子笔记、密集链接

切换模式只影响新笔记的路由，绝不会静默搬动旧笔记。

环境要求与平台边界

• Python 3.11+（可移植核心）；Obsidian 可选（纯 Markdown 也能用）；Bash 用于 setup/扩展/测试。
• 原生 Windows（含 Git Bash）：只读/演练可跑，写 vault 需要 WSL，否则 fail-closed（UNSUPPORTED_PLATFORM）。审批哈希绑定审阅环境，故在 WSL 里应用就要在 WSL 里审阅。

与本库的关联与启示

• 同源技能：claude-obsidian 以 kepano/obsidian-skills 为 Markdown/Bases/Canvas 语法的参考基底——本库也启用了同名技能（见 obsidian-skills 使用指南），所以它的 OFM 约定与本库天然兼容。
• 「来源可见性」是同一诉求的不同力度：本库刚确立的 ai: true 标记（标「全文 AI 生成」）是轻量版；claude-obsidian 把它做成 source/claim 双重台账——需要比「标记」更强的溯源时，可借鉴其思路，但不必照搬整套协议。
• 与 Claudian：把 AI 编程代理嵌入 Obsidian 的插件 定位互补：Claudian 是「在 Obsidian 里聊代码」——把 Claude Code/Codex 等代理塞进 Obsidian 侧边栏；claude-obsidian 是「让代码代理经营知识库」——把 Obsidian 变成 Claude Code 的知识管理后端。一个偏交互，一个偏可复现的知识工程。

来源

• AgriciDaniel/claude-obsidian - GitHub
• 项目博客：claude-obsidian AI second brain