claude-obsidian 使用文档

面向 Claude Code / Cursor / Codex / OpenCode / Gemini 的本地优先知识系统 · 把你丢进去的素材整理成有关联、可溯源的 Obsidian Markdown 知识库 · 基于 Karpathy 的 LLM Wiki 模式

来源：AgriciDaniel/claude-obsidian ↗ 适用：Cursor CLI / Claude Code vault 始终是普通 Markdown MIT 许可

1它是什么

claude-obsidian 是一个本地优先（local-first）的知识系统，把编码代理（Claude Code、Cursor 等）和 Obsidian 连起来，形成一个「AI 第二大脑」。你丢进去任何素材（文档、笔记、代码片段、链接），它读取、关联、归档成一张你完全拥有的、纯 Markdown 知识图谱。

✅ 它做的事

把零散源整理成互相链接的 Obsidian 页面
每条重要主张都带溯源账本（来源/权威度/置信度）
基于已有证据作答，可生成 MOC、Canvas 图谱
vault 永远是普通文件，不锁云端、不上传模型

❌ 它不是

自动转录记录器
云同步服务 / 事实神谕
备份与版本控制的替代品（Git 只用于显式检查点）
编码代理——它不写 Kotlin / 不造 App

2解决什么问题

多数 AI 笔记流程在「存下文本」后就停了。它专门补这几块：

知识不连贯：笔记彼此孤立，不成可导航的图谱 → 建成关联页面 + 索引 + Canvas
来源丢失：摘要后原始证据消失 → 笔记指回持久源证据，矛盾证据也保留
重复劳动：每次对话从零开始 → ingest/query/lint/retrieve 共享同一溯源模型，折叠已知
所有权担忧：数据锁在云端或私有格式 → vault 是普通 Markdown/JSON/源文件目录
代理冲突：并行 AI 竞争写同一 vault 会损坏 → worker 只返回草稿，单一编排器一次性可恢复事务写入

3安装（Cursor CLI 优先）

你用 Cursor CLI 开发，所以下面以 Cursor 为主线。核心两步：克隆产品（不是你的 vault）→ 在 Cursor 工作区里装 workspace-local skill 链接 → 初始化一个独立的 vault。

🔧 Cursor 工作区安装（推荐）

1. 克隆产品

git clone https://github.com/AgriciDaniel/claude-obsidian.git
# 这是「产品源码」，不是你的知识库

2. 装到工作区

cd /path/to/your-project
bash /path/to/claude-obsidian/bin/setup-multi-agent.sh \
  --host cursor --workspace "$PWD"
bash /path/to/claude-obsidian/bin/setup-multi-agent.sh \
  --host cursor --workspace "$PWD" --apply

3. 初始化 vault

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"
python3 /path/to/claude-obsidian/scripts/claude-obsidian.py \
  init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"
# 审查输出的 approved_plan_sha256，再：
python3 .../claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha>" --apply

⚠️ vault 与产品目录严格分离：脚本默认不会把插件目录当 vault，不确定就退出不写。已有 Obsidian vault 用 adopt 工作流接管（见 docs/install-guide.md）。

4其它主机怎么装

🔧 Claude Code / Codex / OpenCode / Gemini

Claude Code

claude --plugin-dir /path/to/claude-obsidian
# 进入 vault 目录后 /claude-obsidian:wiki

Codex 等

bash /path/to/claude-obsidian/bin/setup-multi-agent.sh --host codex
bash /path/to/claude-obsidian/bin/setup-multi-agent.sh --host codex --apply

要求：Python 3.11+ · Obsidian（可选，纯 Markdown 也行）· Bash · Git（仅开发/显式检查点）。 Windows 原生只支持只读检查与 dry-run，写入需 WSL，否则报 UNSUPPORTED_PLATFORM。

核心技能（5 个）

建库 + 用库的主循环

扩展技能（10 个）

研究 / 检索 / 可视化 / 参考

7工作原理：为什么「安全」

核心是一套事务 + 溯源模型，保证 AI 不会静默写坏你的知识库。

显式选 vault：通过 CLAUDE_OBSIDIAN_VAULT 环境变量、最近的 .claude-obsidian.json 或明确初始化的祖先目录选择；不确定就退出、不写。
一个逻辑知识操作 = 一个可恢复事务：① 读每个目标并记预期 SHA-256 → ② 并行 worker 只返回草稿+证据 → ③ 合并成操作 bundle → ④ 检查后应用一次 → ⑤ 报告操作 ID 与确切变更路径。
并行不竞态：核心持有进程级 vault 锁、日志备份、原子替换、失败还原；变更目标即冲突，绝不静默覆盖。
能力诚实声明：可选工具被探测、成熟度被声明，缺失适配器清晰降级而非假装能办。

每条主张的溯源账本记录：权威度、新鲜度、支持/矛盾、置信度、审阅状态。高风险的已接受主张需两个独立来源；不支持或矛盾的证据保持可见。

8使用场景

个人知识管理（PKM）：研究笔记、开源版 Notion 替代，内容互相链接、可溯源、跨会话复用。
架构决策存档（ADR）：把「Compose vs XML」「CloudBase 部署路径」「Play App Signing 指纹」等权衡写成带溯源的结论，下次秒接上下文。
多项目活文档：映目云影App / Cocos 小游戏 / PhotoKit / 3D 试穿各建分区，沉淀部署 runbook（如 tcb hosting deploy 命令、envId）。
踩坑知识库：把反复出现的问题（Cocos 炸弹重置 bug 根因、协程泄漏 ANR）记成证据链，避免重复调研。

9对你（Cursor CLI + App 开发）合适吗

定位先说清：它是「知识库系统」，不是「编码代理」，不写 Kotlin。它是 Cursor 的补充，专门管「知识沉淀」，Cursor 继续干「编码」。三者的分工：

工具	角色	在你的工作流里
Cursor CLI	编码代理	写代码、跑 Gradle、改 Kotlin/Compose/Swift/ArkTS
WorkBuddy	主助手	规划、多项目统筹、周报、部署、生成文档
claude-obsidian	知识库	沉淀架构决策、踩坑、部署 runbook，跨会话复用

✅ 适合用的地方

结构化、可追溯的决策记录（ADR）——契合你「工程化、可追溯」偏好
6 个并行项目的活文档与部署 runbook
反复问题的证据链，避免重复调研
Cursor CLI 集成就一条命令，门槛低

⚠️ 不适合 / 注意

❌ 不能替代 Cursor 写代码
🔧 多一套维护：要单独 init vault、跑 ingest/query
🚧 能力边界见下（PDF 无语义提取、URL/OCR 需外部 runner）
💡 如果你当前没在沉淀知识的需求，可以先不装

结论：你这种多项目、强追溯诉求的作战方式，它值得当第二大脑用——只存架构决策与跨项目知识，编码继续交给 Cursor。集成对你很简单。

10能力边界与注意

输入 / 能力	当前支持
本地文件系统源	有界、内容寻址字节捕获（已实现）
图片	元数据、哈希、尺寸（可用时）
PDF / EPUB	元数据、哈希、尺寸；无内置语义提取
URL / YouTube	已验证同意计划；需配置外部 runner
OCR	本地文件同意计划；需外部 runner
BM25 检索	本地确定性（非向量语义）
Obsidian CLI	可选读/搜；文件系统传输仍可用
远程模型 / 上下文前缀	可选，受显式出口同意限制（默认不联网）

高风险已接受主张需两个独立来源；不支持/矛盾证据保持可见。升级用 migrate 预览再 --apply；中断操作可用 transaction recover --vault 还原；移除插件/主机链接不会删你的 vault。