Claude Obsidian 集成

项目概述

claude-obsidian 是一个本地优先的知识管理系统，面向 Claude Code 以及兼容 Agent Skills 协议的主机。它将原始素材转化为带有出处引用的 Obsidian 链接笔记，从知识库中已有证据检索答案，并提供明确的研究、检索、维护和可视化映射工作流。

知识库始终是普通的 Markdown、JSON 与源文件目录，不隐藏在插件缓存中，也不锁在云端数据库里，更不会静默上传到模型。

核心循环

系统围绕一个可重复的闭环组织：

• 带上下文捕获：通过可见的收件箱引入本地源文件，在合成之前保留不可变、内容寻址的副本。
• 为关键声明提供依据：来源与声明账本记录权威性、新鲜度、支持度、矛盾、置信度与审核状态。
• 建立知识连接：构建链接页面、索引、内容地图、方法论感知的结构以及 Obsidian Canvas 视图。
• 复用知识库：查询、研究、检索、检查并折叠已有知识，避免每次对话都从零开始。

设计差异

• 默认本地：用户拥有 vault，按普通文件工作；网络外发是单独且明确的决策。
• 来源在摘要中存活：笔记指回持久性来源证据；缺乏支持或存在矛盾的声明保持可见。
• 知识刻意复利：摄取、查询、检查、检索、研究与汇总共享同一个来源感知模型。
• 并行代理无法竞态 vault：工作器只返回草稿，由一个编排器检查并应用单一可恢复事务。
• 能力描述诚实：可选工具会被自动检测，成熟度被显式声明，缺失的适配器清晰降级而非伪造。

快速开始

最安全的首次运行方式：源代码检出与用户 vault 分开存放。

# 1. 拉取产品代码
git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

# 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，再带 --apply 真正执行
python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256>" --apply

# 3. 在 vault 目录中启动 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 进行查询。

技能集合

15 个技能分为三组：

• 构建与使用 wiki：wiki、save、wiki-ingest、wiki-query、wiki-lint
• 扩展工作流：autoresearch、canvas、defuddle、wiki-fold、wiki-mode、wiki-retrieve、wiki-cli
• 参考技能：obsidian-markdown、obsidian-bases、think

wiki-mode 支持 Generic、LYT、PARA、Zettelkasten 四种归档模式，切换模式只影响新笔记的路由，不重排已有内容。

信任架构

vault 必须通过 CLAUDE_OBSIDIAN_VAULT 环境变量、最近的 .claude-obsidian.json，或明确初始化的祖先目录显式选择；选择不确定时命令直接退出而不写入。

一次逻辑知识操作对应一次可恢复事务：

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

核心持有一个进程生命周期的 vault 锁，备份写入日志，使用原子替换，应用失败时回滚到先前状态。任何被变更的目标都被视为冲突而非静默覆盖。

能力边界

输入或能力	当前支持
本地文件系统源	已实现有界、内容寻址的字节捕获
图片	元数据、哈希、尺寸与有界维度
PDF 与 EPUB	仅元数据、哈希与大小，无内建语义提取
URL 与 YouTube	验证过的同意计划，需配置外部运行器
OCR	本地文件同意计划，需配置外部运行器
BM25 检索	本地且确定性
上下文前缀或远程模型	可选且受显式外发同意约束
Obsidian CLI	读与搜索可选；文件系统传输始终可用

高风险被接受的声明需要两个独立来源；缺乏支持或矛盾的证据保持可见，无法确认时优先给出有依据的拒绝。

CLI 操作参考

包装器为 python3 scripts/claude-obsidian.py，主要命令包括：

• doctor --vault PATH：显示 vault 选择与就绪状态
• init PATH [--apply]：计划或创建独立 vault
• adopt PATH [--apply]：计划或采纳已有 Obsidian vault
• migrate --vault PATH [--apply]：添加 v1 账本与配置，不重写遗留数据
• transaction inspect|apply|recover --vault PATH：检查、应用或恢复一次操作
• lint --vault PATH [--as-of DATE]：基于声明 UTC 日期输出确定性检查结果
• capture plan|apply --vault PATH：本地捕获的预飞与执行
• release build|audit：构建并自审计确定性发布产物

所有高层变更命令都返回 approved_plan_sha256，需要传入 --apply 才会真正写入。

仓库与 vault 布局

产品仓库（claude_obsidian/、skills/、hooks/、scripts/、templates/vault/、config/、assets/、tests/）与用户 vault（.claude-obsidian.json、inbox/、.raw/、wiki/、.obsidian/、.vault-meta/）完全分离。

环境要求

• Python 3.11 或更高版本
• Obsidian 用于可视化体验；纯 Markdown 仍然可用
• Bash 用于设置与测试
• Git 仅用于开发、发布或显式知识检查点

CI 在 Linux 与 macOS 上运行，另有原生 Windows 烟雾测试。原生 Windows 上只读与预演可用，写入操作要求 WSL 环境。

升级与卸载

# 预览迁移计划
python3 scripts/claude-obsidian.py migrate --vault /path/to/vault \
  --generated-at "$GENERATED_AT" --operation-id migrate-reviewed
# 审核后带哈希与 --apply 应用

# 中断后恢复
python3 scripts/claude-obsidian.py transaction recover --vault /path/to/vault

移除插件或主机链接不会删除 vault，笔记、源文件、账本与 Obsidian 设置保持原样。

开发与发布

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

make test 运行所有隔离的 Python 与 Shell 测试套件、产品与能力契约、技能与钩子验证、清单检查与包边界。发布构建经字节级复现性校验。系统不会自动推送、标签、发布或创建 issue。

设计来源与许可

设计遵循 Andrej Karpathy 提出的 LLM Wiki 模式，并以 kepano/obsidian-skills 作为 Obsidian Markdown、Bases 与 JSON Canvas 语法的参考底座。项目使用 MIT 许可。