GitHub 上的 AgriciDaniel/claude-obsidian 在四个多月里积累了超过 1.3 万 star、1393 次 fork，MIT 协议开源。它给自己的定位是「local-first 知识系统」：把 Claude Code（以及兼容 Agent Skills 规范的其他宿主）变成 Obsidian 知识库的维护者，负责抓取来源、建立笔记链接、基于库内证据回答问题，同时把文件的完整所有权留在用户手里。
这个项目的设计沿袭了 Andrej Karpathy 的 LLM Wiki 模式（作者在致谢中明确标注），底层复用 kepano/obsidian-skills 作为 Obsidian Markdown、Bases 和 JSON Canvas 语法的参考基座。当前版本 v2.1.1，便携核心要求 Python 3.11 及以上。
产品与知识库严格分离
claude-obsidian 在目录结构上把「产品仓库」和「用户库」拆成两个独立空间：产品仓库包含 skills/、hooks/、scripts/、templates/、config/ 等代码目录；用户库则是普通文件夹，包含 inbox/、.raw/、wiki/、.obsidian/ 和被 gitignore 的运行时状态 .vault-meta/。
这套分离不是形式主义的。项目明确承诺：库永远是普通的 Markdown、JSON 和源文件目录，不会被藏进插件缓存、锁进云端数据库，也不会被静默上传给模型。网络出口（egress）在架构里是一个需要显式同意的独立决策，涉及联网的检索和重排功能默认关闭。
从来源到活知识：一个四步循环
大多数 AI 笔记工作流停在「把文本存下来」这一步。claude-obsidian 围绕一个可重复的循环组织全部能力：
- 带上下文捕获：本地来源通过可见的 inbox 进入，合成之前先做不可变的内容寻址副本（content-addressed copy）；
- 为每个重要断言找依据：来源账本和断言账本记录权威性、新鲜度、支持度、矛盾、置信度和复核状态；
- 连接所学：构建链接页面、索引、Maps of Content、方法论感知的结构和 Obsidian Canvas 视图；
- 让库重新投入使用：查询、研究、检索、lint、折叠已有知识，替代每次对话从零开始。
15 个 Skill，三层结构
claude-obsidian 的功能被切成 15 个可以单独调用的 skill，共享同一套证据、库选择和变更规则：
| 分层 | Skill | 职责 |
|---|---|---|
| 建库与用库 | wiki | 初始化或收养库、诊断就绪状态、分发任务 |
save | 保存一条有作用域的答案或洞见，不做自动转录 | |
wiki-ingest | 把捕获的来源转成链接页面和溯源记录 | |
wiki-query | 只从库内相关证据回答（只读） | |
wiki-lint | 报告死链、孤儿笔记、元数据缺口、过期索引和空章节 | |
| 扩展工作流 | autoresearch | 有边界的网络研究，需显式出口同意，规范化合并独立进行 |
canvas | 库作用域内的 Obsidian Canvas 创建与维护 | |
defuddle | 摄入前清洗网页内容为可读文本 | |
wiki-fold | 对操作日志做可追溯的抽取式汇总 | |
wiki-mode | Generic、LYT、PARA 或 Zettelkasten 四种归档约定 | |
wiki-retrieve | 上下文前缀、BM25 和可选的余弦重排 | |
wiki-cli | Obsidian CLI 读取与搜索，事务安全写入 | |
| 参考技能 | obsidian-markdown | 正确的 Obsidian 方言 Markdown、链接、嵌入和标注 |
obsidian-bases | 原生 .base 表格、卡片、过滤器、公式和汇总 | |
think | 结构化的观察、倾听、连接、创造、成长复盘循环 |
在 Claude Code 里以 /claude-obsidian:wiki-lint 这样的命名空间方式调用；Codex、OpenCode、Gemini 宿主通过 bin/setup-multi-agent.sh --host codex 安装可移植的 skill 链接；Cursor 和 Windsurf 走工作区本地的 skill 发现机制。
上手流程：计划审批制安装
安装的第一个动作是克隆代码仓库，第二个动作是初始化一个独立的库目录。所有会改动文件系统的初始化命令都要求先预览、后应用：
export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"
python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
--generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"第一条命令输出一份 JSON 计划。人工审阅后复制其中的 approved_plan_sha256 哈希值，再带着这个哈希执行 --apply。哈希绑定了审阅时的环境，文件系统或计划文件在两步之间发生过任何漂移，应用都会在写入库之前失败。已有 Obsidian 库的用户走非破坏性的 adopt 流程。
初始化完成后，在库目录里启动 Claude Code：
cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian从 /claude-obsidian:wiki 开始，往 inbox/ 放一个来源，调用 wiki-ingest；用 save 显式保存答案；用 wiki-query 向库提问。
事务模型：并行代理不能竞写知识库
这是整个项目里工程密度最高的部分。一次逻辑上的知识操作被定义为一个可恢复的事务，分五步执行：
- 读取全部目标文件并记录各自的 SHA-256；
- 并行 worker 只返回草稿和证据，不直接写库；
- 把完整变更合并进一个操作包（bundle）；
- 审阅操作包，一次性应用；
- 报告操作 ID 和确切变更路径。
核心进程持有一个进程生命周期的库锁，写入走日志备份加原子替换，应用中途失败会恢复先前状态。如果应用时发现目标文件已经被改过，判定为冲突并中止，绝不静默覆盖。Git 检查点、破坏性修复、网络出口和规范化研究合并都保持为显式操作。
库的选择同样有防呆设计：产品代码永远不会把源码检出目录、插件缓存或贡献者状态当作默认库。库的定位只能通过三种方式：环境变量 CLAUDE_OBSIDIAN_VAULT、最近的 .claude-obsidian.json 配置文件、或唯一明确的已初始化祖先目录。三者都无法确定时，命令直接退出，不写任何东西。
诚实的能力边界
README 用一张表逐项声明当前能力：
| 输入或能力 | 当前支持 |
|---|---|
| 本地文件系统来源 | 已实现有边界的、内容寻址的字节捕获 |
| 图片 | 元数据、哈希、尺寸（可用时有界） |
| PDF 和 EPUB | 元数据、哈希和大小，无内置语义抽取 |
| URL 和 YouTube | 已验证的同意计划，需配置外部执行器 |
| OCR | 本地文件同意计划，需配置外部执行器 |
| BM25 检索 | 本地、确定性 |
| 上下文前缀与远程模型 | 可选，需显式出口同意 |
| Obsidian CLI | 可选，用于读和搜索，文件系统通道始终可用 |
证据规则同样写进了架构：高风险的已接受断言要求两个独立来源；无依据或互相矛盾的证据保持可见；宁可直接拒绝也不编造引用。当嵌入或重排阶段不可信时，基于模型的检索会降级到确定性的 BM25。
四种归档方法论
wiki-mode 支持在不批量搬移已有知识的前提下切换新笔记的归档方式：Generic 模式按来源、概念、实体和会话分类；LYT 用 Maps of Content 和原子链接笔记；PARA 按 Projects、Areas、Resources、Archives 组织；Zettelkasten 用稳定标识符、原子笔记和密集链接。默认 Generic，切换只影响新笔记的路由，旧笔记原地不动。
平台支持与运维命令
便携 CLI 提供完整的运维面：doctor 诊断库选择和就绪状态；transaction inspect 在不改动的情况下校验写入包；transaction recover 恢复中断的操作；lint --as-of 输出对声明 UTC 日期确定性的检查结果；contracts --verify 执行能力就绪契约；capture plan/apply 做本地捕获的预检和内容寻址复制；checkpoint 显式提交一次完成的操作；package validate 和 release build/audit 负责技能、钩子、清单和文档的一致性校验及可复现的发布构建。
平台方面，CI 同时跑 Linux 和 macOS，外加一个原生 Windows 冒烟任务。原生 Windows（包括 Git Bash）上只读检查和 dry-run 可用，写库操作要求 WSL 环境，否则以 UNSUPPORTED_PLATFORM 错误关闭。审批哈希绑定审阅环境，因此在哪里应用就要在哪里审阅。
对开发者的参考价值
claude-obsidian 处理的三个问题具有超出笔记工具的通用性：AI 代理如何安全地并发读写用户文件（答案：草稿加单事务合并，SHA-256 锁定前置状态）；如何让 AI 生成的内容可追溯（答案：来源和断言双层账本，矛盾保持可见）；如何在能力不足时体面降级（答案：能力表逐项声明，缺适配器就明确说缺，不模拟）。
对想搭建个人知识库的开发者，它给出的组合是：Claude Code 做执行层，Obsidian 做浏览层，纯 Markdown 做存储层，Git 做可选检查点。四个组件都可以单独替换，任何一个被拿走，剩下的部分仍然是可用的普通文件。
来源：AgriciDaniel/claude-obsidian（GitHub，MIT），版本 v2.1.1