claude-obsidian：Obsidian上的AI第二大脑

构建一个 Obsidian 知识库，每次使用都会变得更加实用。捕获来源、创建关联笔记、检索有据可查的回答，并保持保险库健康运行——无需放弃对文件的所有权。

See the workflow · Quick start · Explore the skills · Installation guide · Windows & WSL

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

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

从源到活的知识

大多数 AI 笔记工作流在保存文本后就停止了。claude-obsidian 围绕一个可重复的循环组织：保留来源、使声明有据可查、连接知识，然后让其重新发挥作用。

带上下文捕获。通过可见的收件箱引入本地源，并在综合处理前保留不可变的、内容寻址的副本。

为每个重要声明提供依据。来源和声明台账保留权威性、新鲜度、支持度、矛盾性、置信度和审核状态。

连接你所学的。构建链接页面、索引、内容地图、方法论感知的结构，以及 Obsidian Canvas 视图。

再次使用保险库。查询、研究、检索、整理和折叠已有知识，而不是每次对话都从零开始。

输出意味着无论是否有 agent 都能保持有用：用于可移植性的纯 Markdown，用于导航和可视化探索的 Obsidian。

Graph 视图中的链接知识 · Obsidian Canvas 中的可视化知识地图

为何感觉不同

默认本地化。保险库归用户所有，作为普通文件运作。网络出口是一个独立的、明确的决定。

来源超越摘要。笔记指向持久的来源证据；无依据的和矛盾的声明保持可见。

知识有意识地积累。摄取、查询、整理、检索、研究和汇总共享一个 provenance-aware 模型。

并行 agent 无法竞速保险库。Worker 返回草稿。一个编排器检查并应用一个可恢复的事务。

能力被如实声明。可选工具被检测，成熟度被声明，缺失的适配器会明确降级而不是被模拟。

这不是一个自动转录记录器、云同步服务、事实预言者，也不是备份和源代码控制的替代品。

最安全的第一轮运行使用源代码 checkout 和独立的用户保险库。每个变更性设置命令在应用前都会预览其确切操作。

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

checkout 包含产品。它不是你的知识保险库。

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，从产品 checkout 预览然后应用可移植的技能链接：

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

Cursor 和 Windsurf 使用工作区本地技能发现。市场设置、每个支持的主机、保险库 adopt、升级和卸载步骤均在完整安装指南中涵盖。

15 个技能，一个系统

这些技能小到可以直接调用，协调整到足以共享相同的证据、保险库选择和变更规则。

构建和使用 wiki

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

信任是架构的一部分

产品永远不会将源代码 checkout、插件缓存或贡献者状态视为默认保险库。保险库通过 CLAUDE_OBSIDIAN_VAULT、最近的 .claude-obsidian.json 或一个明确的初始化祖先目录明确选择。如果选择不确定，命令退出而不写入。

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

读取每个目标并记录其预期 SHA-256。

让并行 worker 只返回草稿和证据。

将完整变更合并到一个操作束中。

检查该束，然后一次性应用。

报告操作 ID 和确切变更的路径。

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

阅读事务契约、provenance 契约和 Compound Vault 架构以获取面向机器的详细信息。

诚实的能力边界

高风险的可接受声明需要两个独立来源。无依据或矛盾的证据保持可见，有据可查的拒绝优于虚构的引用。当嵌入或重排阶段无法被信任时，基于模型的检索会回退到确定性 BM25。

按你的思维方式塑造保险库

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

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

包装器

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

高级变更性规划器发出 approved_plan_sha256。固定 --generated-at 和 --operation-id，审核 JSON 操作，然后将那个确切哈希与 --apply 一起传递。文件系统或生成的 bundle 漂移在保险库写入前失败。

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

私有开发 checkout 故意没有市场目录。发布构建器仅将已审核的目录注入到分发干净的制品中。公共默认分支必须从该审计树填充，绝不能通过推送贡献者保险库状态来填充。

独立于保险库升级产品

对于较旧的保险库，首先预览添加剂、幂等迁移：

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

审核其哈希并使用 --approved-plan-sha256 HASH --apply 重新运行。迁移逐字节保留旧版 raw 清单，不会从散文中推断声明。

在中断的操作之后，运行：

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

移除插件或主机链接永远不会移除保险库。仅删除你安装的集成；用户笔记、源、台账和 Obsidian 设置仍然归你所有。

Python 3.11 或更高版本用于可移植核心

Obsidian 用于可视化保险库体验；纯 Markdown 无需它即可使用

Bash 用于设置、可选扩展和 shell 测试套件

Git 仅用于开发、发布或明确的知识检查点

CI 在 Linux 和 macOS 上运行练习，加上原生 Windows 烟雾作业用于可移植表面。在原生 Windows（包括 Git Bash）上，只读检查和 dry-run 命令可用；保险库写入需要 WSL，否则失败并关闭并返回 UNSUPPORTED_PLATFORM 错误。批准哈希绑定到审核环境，因此在 apply 将在那里发生时在 WSL 内审核。平台详情、支持矩阵和 WSL 故障排除（包括虚拟化冲突导致的挂起）位于 Windows 和 WSL 指南中。Bash 设置脚本和 shell 测试套件保持 POSIX 唯一。可选工具（如 Obsidian CLI、Ollama 和 defuddle）被能力检测，仅影响其依赖的工作流程。

开发和发布

make test

测试目标运行每个 hermetic 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。