claude-obsidian

claude-obsidian

构建一个每次使用都会变得更有用的 Obsidian 知识库。
捕获来源、创建关联笔记、获取有据可依的答案，并保持 vault 健康——同时无需放弃对文件的所有权。

查看工作流 · 快速开始 · 探索技能 · 安装指南 · Windows 与 WSL

claude-obsidian 是一个面向 Claude Code 及兼容 Agent Skills 主机的本地优先知识系统。它将原始材料转化为带有链接和来源引用的 Obsidian 页面；基于 vault 中已有的证据进行回答；并提供研究、检索、维护和可视化映射的明确工作流。

你的 vault 仍然是一个普通的 Markdown、JSON 和源文件目录。它不会被隐藏在插件缓存中、锁定在云端数据库中，也不会被静默上传到模型。

从来源到活的知识

大多数 AI 笔记工作流在保存文本后就结束了。claude-obsidian 围绕一个可重复的循环组织：保留来源、落实主张、连接知识，然后将其重新投入使用。

• 带着上下文捕获。 将本地来源引入可见的收件箱，并在综合前保留不可变、内容寻址的副本。
• 落实每一项重要主张。 来源与主张台账保留权威性、新鲜度、支持、矛盾、置信度和审阅状态。
• 连接你所学的知识。 构建关联页面、索引、内容地图（Maps of Content）、方法论感知结构以及 Obsidian Canvas 视图。
• 再次使用 vault。 查询、研究、检索、lint，并将已知信息整理归并，而不是每次对话都从零开始。

查看 vault

其输出在有无 agent 的情况下都保持有用：纯 Markdown 保证可移植性，Obsidian 提供导航和可视化探索。

Graph 视图中的关联知识 · Obsidian Canvas 中的可视化知识地图

为什么它与众不同

• 默认本地化。 vault 归用户所有，并以普通文件的形式工作。网络出站是独立的、明确决定的操作。
• 来源在总结之后依然存在。 笔记指向持久化的源证据；未支持和矛盾的主张依然可见。
• 知识有意识地复合。 摄取、查询、lint、检索、研究和汇总共享同一个 provenance-aware（来源感知）模型。
• 并行 agent 不会与 vault 竞争。 Worker 只返回草稿。一个 orchestrator 检查并应用一个可恢复的事务。
• 能力被如实声明。 可选工具会被检测，成熟度会被声明，缺失的适配器会清晰降级，而不是被模拟。

这不是自动转录记录器、云同步服务、事实预言机，也不是备份和版本控制的替代品。

快速开始

最安全的首运行方式是使用源码检出和一个独立的用户 vault。每个变更性设置命令在应用前都会预览其确切操作。

1. 获取产品

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

检出目录包含产品本身，不是你的知识 vault。

2. 初始化一个独立 vault

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，然后应用该精确操作：

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256-from-the-plan>" --apply

对于已有的 Obsidian vault，请使用 安装指南 中描述的非破坏性 adopt 工作流。

3. 从 vault 开始

在 Obsidian 中打开新目录，然后从该目录运行带有本地插件的 Claude Code：

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

从以下命令开始：

/claude-obsidian:wiki

然后将源文件放入 inbox/ 并调用 /claude-obsidian:wiki-ingest。使用 /claude-obsidian:save 显式保存答案；使用 /claude-obsidian:wiki-query 向 vault 提问。

对于 Codex、OpenCode 或 Gemini，请先从产品检出目录预览并应用可移植的技能链接：

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

Cursor 和 Windsurf 使用工作区本地技能发现。Marketplace 设置、所有受支持的主机、vault 采用、升级和卸载步骤均包含在完整安装指南中。

15 个技能，一个系统

这些技能足够小，可以直接调用，并且足够协调，共享相同的证据、vault 选择和变更规则。

构建并使用 wiki

技能	作用
wiki	初始化或采用 vault，诊断就绪状态，并分流工作
save	保存一个限定的答案或洞察——绝不是自动转录
wiki-ingest	将捕获的来源转化为关联页面和来源记录
wiki-query	只读地根据相关 vault 证据进行回答
wiki-lint	报告死链、孤立笔记、元数据缺口、过期索引和空章节

扩展工作流

技能	新增内容
autoresearch	有边界的网络研究，具有明确的出站和一个独立的规范合并
canvas	Wiki 范围内的 Obsidian Canvas 创建和维护
defuddle	在摄取前清理出干净、可读的网页内容
wiki-fold	操作日志的抽取式、可追溯汇总
wiki-mode	通用、LYT、PARA 或 Zettelkasten 归档约定
wiki-retrieve	上下文前缀、BM25 和可选的余弦重排序
wiki-cli	Obsidian CLI 读取和搜索，支持事务安全写入

参考技能

技能	提供内容
obsidian-markdown	正确的 Obsidian Flavor 的 Markdown、链接、嵌入和 callout
obsidian-bases	原生 .base 表格、卡片、筛选器、公式和摘要
think	结构化的观察、倾听、连接、创造和成长复习循环

Claude Code 暴露带有命名空间的调用，如 /claude-obsidian:wiki-lint；其他主机使用其原生的 Agent Skills 调用。触发短语和精确约定位于各自的 skills/<name>/SKILL.md 中。

信任是架构的一部分

产品绝不会将源码检出、插件缓存或贡献者状态视为默认 vault。vault 必须被显式选择，通过 CLAUDE_OBSIDIAN_VAULT、最近的 .claude-obsidian.json，或一个明确的已初始化祖先目录。如果选择不明确，命令会不写入直接退出。

一个逻辑知识操作就是一个可恢复的事务：

1. 读取每个目标并记录其预期 SHA-256。
2. 只允许并行 worker 返回草稿和证据。
3. 将完整变更合并为一个操作包。
4. 检查该包，然后只应用一次。
5. 报告操作 ID 和确切变更的路径。

核心持有进程生命周期内的 vault 锁，记录日志备份，使用原子替换，并在应用无法完成时恢复先前状态。变更的目标是冲突，绝不是静默覆盖。Git 检查点、破坏性修复、网络出站和规范化研究合并仍是显式操作。

请阅读事务契约、来源契约和Compound Vault 架构以获取机器可读的细节。

诚实的能力边界

输入或能力	当前支持
本地文件系统来源	已实现有边界、内容寻址的字节捕获
图片	可用时的元数据、哈希、大小和有界尺寸
PDF 和 EPUB	元数据、哈希和大小；无内置语义抽取
URL 和 YouTube	经过验证的同意计划；需要配置外部运行器
OCR	本地文件同意计划；需要配置外部运行器
BM25 检索	本地且确定性
上下文前缀或远程模型	可选，并通过显式出站同意门控
Obsidian CLI	可选用于读取/搜索；文件系统传输仍然可用

高风险接受的主张需要两个独立来源。未支持或矛盾证据保持可见，并且有根据的拒绝优于编造的引用。当 embedding 或重排序阶段不可信时，基于模型的检索会回退到确定性 BM25。

将 vault 塑造成适合你的思考方式

wiki-mode 可以使用四种方法论为新笔记分配路由，而不会批量移动现有知识：

模式	归档原则
Generic	来源、概念、实体和会话
LYT	内容地图和链接的原子笔记
PARA	项目、领域、资源和归档
Zettelkasten	稳定标识符、原子笔记和密集链接

当没有配置模式时，Generic 是默认值。切换模式只会改变新笔记的路由，不会静默重新组织旧笔记。参见方法论模式指南。

操作员参考

可移植 CLI

包装器是 python3 scripts/claude-obsidian.py。

命令	效果
doctor --vault PATH	显示 vault 选择和就绪状态
init PATH [--approved-plan-sha256 HASH --apply]	计划或创建独立 vault
adopt PATH [--approved-plan-sha256 HASH --apply]	计划或采用现有 Obsidian vault
migrate --vault PATH [--approved-plan-sha256 HASH --apply]	添加 v1 台账和配置，不重写旧数据
transaction inspect BUNDLE --vault PATH	无变更地验证写入包
transaction apply BUNDLE --vault PATH --approved-plan-sha256 HASH	应用一个已检查、可恢复的操作
transaction recover --vault PATH [--force-stale-lock]	恢复中断的操作
lint --vault PATH [--as-of YYYY-MM-DD]	针对声明的 UTC 日期生成确定性发现
contracts --verify --vault PATH	执行能力就绪契约
capture plan --vault PATH [SOURCE ...]	运行本地捕获预检而不写入
capture apply --vault PATH [SOURCE ...]	计划或创建不可变的内容寻址副本
checkpoint OPERATION_ID --vault PATH	显式提交一个已完成的操作
package validate	检查技能、hooks、清单和文档一致性
release build --output FILE.zip	构建并自我审计一个确定性公共工件
release audit FILE.zip	审计工件而不解压或发布

高级变更性规划器会输出 approved_plan_sha256。固定 --generated-at 和 --operation-id，检查 JSON 操作，然后通过 --apply 传递该精确哈希。文件系统或生成包的漂移会在 vault 写入前失败。

仓库与 vault 布局

product repository/                user vault/
├── claude_obsidian/               ├── .gitignore
├── skills/                        ├── .claude-obsidian.json
├── hooks/                         ├── inbox/
├── scripts/                       ├── .raw/
├── templates/vault/               ├── wiki/
├── config/                        ├── .obsidian/
├── assets/                        └── .vault-meta/   # ignored runtime state
└── tests/

公共工件包含产品代码、确定性模板和经过审阅的 README 资源。它们拒绝贡献者的热/日志状态、原始根来源、运行时元数据、私有路径、可识别的个人电子邮件地址、密钥、符号链接、不安全的归档条目和未经审阅的二进制文件。

私有开发检出刻意不包含 marketplace 目录。发布构建器只将审阅后的目录注入到发行干净的工件中。公共默认分支必须从该审计树填充，绝不能推送贡献者 vault 状态。

升级、回滚与卸载

将产品与 vault 独立升级。对于较旧的 vault，首先预览增量的、幂等的迁移：

python3 scripts/claude-obsidian.py migrate --vault /path/to/vault \
  --generated-at "$GENERATED_AT" --operation-id migrate-reviewed

检查其哈希，并使用 --approved-plan-sha256 HASH --apply 重新运行。迁移逐字节保留旧原始清单，并且不会从文本中推断主张。

中断操作后，运行：

python3 scripts/claude-obsidian.py transaction recover --vault /path/to/vault

移除插件或主机链接绝不会删除 vault。只删除你安装的集成；用户笔记、来源、台账和 Obsidian 设置仍然归你所有。

要求

• Python 3.11 或更新版本（用于可移植核心）
• Obsidian（用于可视化 vault 体验；纯 Markdown 在没有它的情况下依然可用）
• Bash（用于设置、可选扩展和 shell 测试套件）
• Git（仅用于开发、发布或显式知识检查点）

CI 在 Linux 和 macOS 上运行，并为可移植表面增加了原生 Windows 冒烟任务。在原生 Windows（包括 Git Bash）上，只读检查和干运行命令可用；vault 写入需要 WSL，否则将以 UNSUPPORTED_PLATFORM 错误失败关闭。批准哈希绑定到审查环境，因此当 apply 将在 WSL 中发生时，请在 WSL 内审查。平台细节、支持矩阵和 WSL 故障排除（包括虚拟化冲突导致的挂起）位于 Windows 与 WSL 指南 中。Bash 设置脚本和 shell 测试套件保持 POSIX-only。Obsidian CLI、Ollama 和 defuddle 等可选工具会进行能力检测，并且只影响其相关的工作流。

开发与发布

make test

测试目标运行每个封闭的 Python 和 shell 套件、产品和能力契约、技能与 hook 验证、清单检查以及包边界。CI 在受支持的 Linux 和 macOS/Python 组合上重复该套件，并验证字节可复现的发布构建。

在本地构建和审计而不发布：

python3 scripts/claude-obsidian.py release build --output dist/claude-obsidian.zip
python3 scripts/claude-obsidian.py release audit dist/claude-obsidian.zip

没有任何命令会自动推送、打标签、发布、开 issue 或创建 release。参见 CONTRIBUTING.md、SECURITY.md 和 CODE_OF_CONDUCT.md。

血统、许可证与致谢

该设计遵循 Andrej Karpathy 的 LLM Wiki 模式，并使用 kepano/obsidian-skills 作为 Obsidian Markdown、Bases 和 JSON Canvas 语法的参考基础。

MIT 许可。参见 ATTRIBUTION.md 和 CITATION.cff。