claude-obsidian

打造一个越用越好用的 Obsidian 知识库。
轻松捕获资料来源、创建互联笔记、获取基于事实的答案，同时保持库的健康状态——全程无需放弃文件所有权。

查看工作流程 · 快速开始 · 探索功能 · 安装指南

claude-obsidian 是一个面向 Claude Code 及兼容 Agent Skills 宿主的本地优先知识系统。它能将原始资料转化为带链接和来源引用的 Obsidian 页面；基于库中已有的证据提供答案；并为研究、检索、维护和可视化图谱提供清晰的工作流程。

您的库始终是一个包含 Markdown、JSON 和源文件的普通目录。它不会隐藏在插件缓存中、锁定在云数据库里，也不会被静默上传到模型。

From source to living knowledge

大多数 AI 笔记工作流程在保存文本后就止步不前。claude-obsidian 围绕一个可重复的循环构建：保留来源、夯实观点、连接知识，然后让知识发挥作用。

• 带上下文捕获。 通过可视化的收件箱处理本地来源，并在进行内容合成前保留不可变的、基于内容寻址的副本。
• 为每个重要观点提供依据。 来源和观点台账记录权威性、时效性、支持证据、矛盾信息、可信度和审核状态。
• 连接所学知识。 构建链接页面、索引、内容地图（Maps of Content）、方法感知结构和 Obsidian Canvas 视图。
• 重复利用知识库。 查询、研究、检索、整理和整合已知内容，无需每次从头开始。

查看知识库

无论是否使用智能代理，输出内容都保持实用性：采用通用的 Markdown 格式确保可移植性，借助 Obsidian 实现导航与可视化探索。

_{图谱视图中的关联知识 · Obsidian Canvas 中的可视化知识地图}

为何与众不同

• 默认本地优先：知识库归用户所有，作为普通文件运行。网络数据传输是独立且需明确操作的步骤。
• 源文件与摘要共存：笔记可回溯至可靠的原始依据；未经证实及相互矛盾的观点均清晰可见。
• 知识有序积累：信息摄入、查询、整理、检索、研究及汇总均采用同一溯源模型。
• 多代理协同无冲突：工作代理返回草稿，由单一协调器检查并执行可恢复的事务操作。
• 功能如实呈现：自动检测可选工具，明确标注功能成熟度，适配缺失时清晰降级而非模拟实现。

本工具并非自动转录记录器、云同步服务、事实查询引擎，亦不能替代备份与版本控制工具。

快速开始

首次运行的最安全方式是使用源码检出及独立的用户知识库。所有可能修改数据的设置命令在执行前都会先展示具体操作内容。

1. 获取产品

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

检出的内容包含产品本身，并非您的知识库。

2. 初始化一个独立的知识库

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 库，请使用安装指南中描述的非破坏性 adopt 工作流程。

3. 从库开始

在 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 向知识库提问。

对于 Codex、OpenCode 或 Gemini，请先预览，然后从产品结账页面应用可移植技能链接：

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

Cursor 和 Windsurf 采用工作区本地技能发现机制。市场设置、所有支持的宿主、库采用、升级和卸载步骤均在完整安装指南中涵盖。

15 项技能，一个系统

各项技能小巧到可直接调用，又能协同工作，共享相同的证据、库选择和变更规则。

构建和使用 wiki

扩展工作流

参考技能

Claude Code 公开命名空间调用，例如/claude-obsidian:wiki-lint；其他宿主则使用其原生的 Agent Skills 调用方式。触发短语和确切约定详见每个skills/<name>/SKILL.md文件。

信任是架构的一部分

产品从不将源代码检出、插件缓存或贡献者状态视为默认库。库是通过CLAUDE_OBSIDIAN_VAULT、最近的.claude-obsidian.json或一个明确初始化的上级目录显式选择的。如果选择存在不确定性，命令将退出且不执行写入操作。

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

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

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

有关面向机器的详细信息，请阅读事务约定、出处约定和复合库架构。

诚实的能力边界

高风险的可接受声明需要两个独立来源。不支持或矛盾的证据保持可见，相比于虚构引用，更倾向于基于事实的拒绝。当嵌入或重排序阶段不可信时，基于模型的检索会回退到确定性的 BM25。

让知识库符合你的思维方式

wiki-mode 可以使用四种方法路由新笔记，而无需批量移动现有知识：

未配置任何模式时，默认使用 Generic 模式。切换模式会改变新笔记的路由方式，但不会静默重组旧笔记。请参阅 方法论模式指南。

操作指南

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 资源。它们会排除贡献者的热状态/日志状态、根目录原始源文件、运行时元数据、私有路径、可识别的个人电子邮件地址、密钥、符号链接、不安全的归档条目以及未经审核的二进制文件。

专用开发检出版本特意不包含市场目录。发布构建器仅会将经过审核的目录注入到分发清洁的制品中。公共默认分支必须从该经过审计的树中填充，绝不能通过推送贡献者库状态来实现。

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

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

要求

• 用于可移植核心的 Python 3.11 或更高版本
• 用于可视化库体验的 Obsidian；纯 Markdown 无需 Obsidian 也可使用
• 用于设置、可选扩展和 shell 测试套件的 Bash
• 仅用于开发、发布或显式知识检查点的 Git

CI 适用于 Linux 和 macOS。在 Windows 上，请使用 WSL；原生 Windows 和 Git Bash 目前不保证兼容性。Obsidian CLI、Ollama 和 defuddle 等可选工具会进行功能检测，且仅影响其相关工作流。

开发与发布

make test

测试目标会运行所有隔离的 Python 和 shell 套件、产品与功能契约、技能和钩子验证、清单检查以及包边界检查。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

不会自动执行命令推送、标记、发布、创建问题或生成版本。请参阅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。