claude-obsidian 安装与 Vault 初始化指南从 Agent Skills 接入到内容寻址写入的完整落地路径【免费下载链接】claude-obsidianSelf-organizing AI second brain for Obsidian Claude Code. Drop any source and Claude reads, links, and files it into one connected knowledge graph of plain Markdown you own. AI note-taking, personal knowledge management (PKM), and an open-source Notion alternative. Based on Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian本文基于当前仓库的官方安装文档 docs/install-guide.md 编写覆盖 claude-obsidian 的两部分产品边界产品包与用户 Vault、三种接入方式Claude Code 市场插件、本地插件目录、可移植 Agent Skills 宿主、Vault 的创建/接管/迁移、选择优先级、可选扩展配置、首次 capture 写入、升级回滚与卸载排障。读完并跟随操作后你应能在自己的机器上完成一次从“装 Skill”到“完成首个内容寻址写入并可用事务恢复”的完整安装闭环。1. 产品边界两部分必须分离claude-obsidian 由两个互不依赖的部分组成产品包——skills、可移植核心portable core、Claude 适配器与模板用户自有的 Obsidian Vault——存放可变知识内容的目录。官方文档明确警告不要把已安装插件的缓存目录当作 Vault 使用。源码克隆目录适合开发调试但普通用户的 Vault 必须是独立的另一个目录。这一约束在源码中是硬执行的claude_obsidian/paths.py 中的assert_not_plugin_tree会在任何可变状态被写进插件树含templates/、examples/等子路径时抛出PLUGIN_ROOT_IS_NOT_VAULT/PLUGIN_TREE_IS_NOT_VAULT错误。从源码结构看这解释了安装文档中“plugin cache contains read-only product assets”一句的底层原因产品树只读可变数据必须落在用户 Vault。2. 环境要求依赖要求说明Python3.11 或更新可移植核心的运行环境Agent Skills 兼容宿主任意一个或 Claude Code用于插件适配器如 Codex、OpenCode、Gemini、ZCode、Cursor、WindsurfObsidian可选仅当需要其可视化编辑器时Bash必需安装脚本与可选的 legacy 扩展脚本Git可选仅源码开发、release 构建或显式 checkpoint 时需要WindowsWSL 用于 Vault 写入原生 Windows 仅支持只读检查与 dry-run详见 Windows 与 WSL 指南当前仓库版本为2.1.1见 claude_obsidian/init.py可通过python3 scripts/claude-obsidian.py --version确认cli.py 中注册了--version参数。scripts/claude-obsidian.py本身只是一个兼容入口用于插件 hook 和旧脚本调用方它把main()委托给 claude_obsidian/cli.pyscripts/claude-obsidian.py#L14所以文档中所有python3 scripts/claude-obsidian.py ...命令实际执行的是claude_obsidian/cli.py里的子命令分发。3. 安装路径一Claude Code 市场插件添加 artifact-clean 的公开目录catalog并安装带命名空间的插件claude plugin marketplace add AgriciDaniel/claude-obsidian claude plugin install claude-obsidianagricidaniel-claude-obsidian claude plugin list文档对发布流程有一条重要约束私有开发树刻意不包含.claude-plugin/marketplace.json因为它可能含有贡献者 Vault 的状态不能作为 marketplace 被添加确定性的 release 构建器只把该 manifest 注入到它审计过的输出产物中。公开默认分支必须先从提取的审计产物提升promote之后才会对外宣传新版本的市场命令。技能以命名空间方式调用/claude-obsidian:wiki、/claude-obsidian:wiki-ingest、/claude-obsidian:save。由于插件缓存中的产品资产是只读的实际使用时有三种指定 Vault 的方式从用户 Vault 目录启动 Claude、设置CLAUDE_OBSIDIAN_VAULT环境变量、或对可移植命令显式传--vault。3.1 本地 Claude 插件开发模式在产品克隆中直接加载未安装的改动进行测试claude --plugin-dir product-repository该模式用于测试未安装的变更技能仍保持命名空间它不会把产品仓库变成用户 Vault。4. 安装路径二可移植 Agent Skills 宿主对 Codex、OpenCode、Gemini安装器默认为无写入的预览dry-runbash scripts/setup-multi-agent.sh # 预览不写盘 bash scripts/setup-multi-agent.sh --apply # 执行计划中的链接 bash scripts/setup-multi-agent.sh --check # 只读检查就绪状态脚本把产品仓库中每个规范的skills/name/目录链接到宿主的直连发现布局skill-root/name/SKILL.md。从 scripts/setup-multi-agent.sh 的冲突检查逻辑约 L107-L135可以看到目标只在不存在时创建已存在的技能或链接绝不会被替换父目录若是符号链接或安装期间发生变化会报CONFLICT。Cursor 和 Windsurf 使用工作区本地发现需要显式指定--workspacebash scripts/setup-multi-agent.sh --host cursor --host windsurf \ --workspace workspace --applyZCode 是 opt-in 的、用户级无需--workspacebash scripts/setup-multi-agent.sh --host zcode bash scripts/setup-multi-agent.sh --host zcode --apply也可以手动创建等价的按技能符号链接。对产品skills/目录下的每个nameCodex: ~/.agents/skills/name - product-repository/skills/name OpenCode: ~/.config/opencode/skills/name - product-repository/skills/name Gemini: ~/.gemini/skills/name - product-repository/skills/name ZCode: ~/.zcode/skills/name - product-repository/skills/name Cursor: workspace/.cursor/skills/name - product-repository/skills/name Windsurf: workspace/.windsurf/skills/name - product-repository/skills/name这些宿主根目录与脚本源码中的destination_root分支一一对应setup-multi-agent.sh#L162-L166Cursor/Windsurf 则要求--workspace否则直接报错退出。5. 创建新 Vault先审计划再应用init是“两段式”操作先打印初始化计划人工确认目标路径与变更路径无误后再带上审批哈希应用。python3 scripts/claude-obsidian.py init new-vault \ --generated-at ISO-UTC --operation-id init-reviewedpython3 scripts/claude-obsidian.py init new-vault \ --generated-at ISO-UTC --operation-id init-reviewed \ --approved-plan-sha256 reviewed-sha256 --apply生成的 Vault 包含.gitignore——隐私安全的默认排除项排除.vault-meta/运行时状态、Obsidian 工作区状态与实时的.mcp.json启动配置.claude-obsidian.json——工作区身份与 Vault 选择inbox/——可见的源材料入口.raw/——不可变的源载荷与旧式 delta manifestwiki/——索引、日志、hot 缓存、overview 与生成的笔记.obsidian/——最小化、非破坏性的 Obsidian 默认配置.vault-meta/——按需创建的、被忽略的运行时状态。初始化不会添加上游 Git remote也不安装社区插件在 Obsidian 的 Vault 选择器中打开新目录即可。源码印证cli.py 的command_init在没有变更时输出status: noop的claude-obsidian.initialization-plan.v1文档dry-run 阶段输出变更路径清单与审批字段--apply阶段先_require_write_platform()在创建目录前就拒绝不支持写入的平台例如原生 Windows再校验审批哈希。若审批时目标尚不存在而 apply 时目录已被创建会抛出PLAN_CHANGED——这是一个防止“审的是一份计划、落的是另一份状态”的一致性检查。此外源码中注释明确失败时从不按路径删除失败的初始化根目录事务本身回滚内容空目录可能留下供人工检查。基础文件模板可对照 templates/vaultinbox/、wiki/hot.md、wiki/index.md、wiki/log.md、wiki/overview.md完整示例见 examples/sample-vault。6. 接管已有 Vault 与增量迁移6.1 adopt只补缺失的产品元数据adopt扫描现有 Obsidian 目录只提议缺失的产品元数据与基础文件python3 scripts/claude-obsidian.py adopt existing-vault \ --generated-at ISO-UTC --operation-id adopt-reviewed python3 scripts/claude-obsidian.py adopt existing-vault \ --generated-at ISO-UTC --operation-id adopt-reviewed \ --approved-plan-sha256 reviewed-sha256 --apply它会保留现有笔记和 Obsidian JSON。--force被刻意做成独立开关只应在人工检查过替换目标之后使用。对应实现command_adopt输出claude-obsidian.adoption-plan.v1计划文档cli.py#L864-L903。6.2 migrate旧布局的增量升级对旧版 claude-obsidian 布局用增量式迁移补上 provenance ledgers 与工作区配置python3 scripts/claude-obsidian.py migrate --vault existing-vault \ --generated-at ISO-UTC --operation-id migrate-reviewed python3 scripts/claude-obsidian.py migrate --vault existing-vault \ --generated-at ISO-UTC --operation-id migrate-reviewed \ --approved-plan-sha256 reviewed-sha256 --apply迁移是幂等的、不从散文推断断言claims、且保证旧式.raw/.manifest.json逐字节不变。migrate子命令在 cli.py#L1175-L1193 注册复用与 init/adopt 相同的审批参数体系。7. Vault 选择优先级与校验可变命令按如下优先级选择 Vault--vault pathCLAUDE_OBSIDIAN_VAULT最近的.claude-obsidian.json从当前目录向上找到的最近、无歧义的已初始化 Vault选择失败时命令无变更退出产品/插件根目录被拒绝作为隐式 Vault。这段优先级在 claude_obsidian/paths.py#L361-L413 的resolve_vault_root中逐条实现且是 fail-closed 设计第 3 级读取的工作区配置必须声明schema: claude-obsidian.workspace.v1、不超过 64 KiB并用严格 JSON 解析拒绝重复键与非有限数值——见同文件_read_workspace_config第 4 级的“已初始化”判定是wiki/目录存在且.obsidian/或.raw/存在之一is_initialized_vault找不到 Vault 时报VAULT_NOT_FOUND提示你传--vault或设置CLAUDE_OBSIDIAN_VAULT——这正对应排障表中的“Command says no vault selected”。校验选中 Vault 的两条命令python3 scripts/claude-obsidian.py doctor --vault vault python3 scripts/claude-obsidian.py contracts --verify --vault vaultdoctor检查 Vault 选择与核心就绪状态contracts --verify执行产品/能力契约校验Makefile 的test-contracts目标同时跑--check-only与--verify两种模式。8. 可选配置传输检测与扩展可移植的文件系统传输永远可用无需任何配置。若希望使用 Obsidian CLI 作为传输层用只读探测检测一个“活跃且受支持”的 Obsidian CLI不落地任何快照bash scripts/detect-transport.sh --peek --vault vault从 scripts/detect-transport.sh 的头部注释可确认--peek对 Vault 严格只读既不创建.vault-meta也不刷新transport.json检测器不把“二进制存在”“旧式--version响应”或“退出码为 0”单独当作能力证明。可选扩展都是显式的、按 Vault 作用域安装的bash scripts/setup-mode.sh --vault vault bash scripts/setup-retrieve.sh --vault vault bash scripts/setup-dragonscale.sh --vault vault应用前务必阅读每个脚本的预览输出。检索可以只用本地 BM25基于模型的上下文前缀或远程端点需要显式的出站egress同意。Ollama、defuddle 这类可选工具走能力检测capability-detected。这三个脚本也注册为make setup-mode/make setup-retrieve/make setup-dragonscale见 Makefile#L43-L50。9. 第一次写入操作capture 计划与应用把源材料放入inbox/先检查字节捕获byte-capture计划python3 scripts/claude-obsidian.py capture plan --vault vault只有计划正确时才创建不可变的、内容寻址的副本python3 scripts/claude-obsidian.py capture apply --vault vault \ --generated-at ISO-UTC --operation-id capture-reviewed python3 scripts/claude-obsidian.py capture apply --vault vault \ --generated-at ISO-UTC --operation-id capture-reviewed \ --approved-plan-sha256 reviewed-sha256 --applycapture子命令组在 cli.py#L1042-L1070 定义adapters展示诚实的适配器成熟度、plan写入前预检默认不写、apply默认 dry-run--apply才真正复制、external-plan针对url | image | pdf | youtube | epub | ocr生成惰性的、需同意门控的外部适配器计划。文档对能力边界有一句关键说明图片、PDF、EPUB 的语义抽取并未内置在核心中这些格式目前只获得有界的元数据除非有单独配置的适配器被显式批准。之后调用宿主侧的wiki-ingest技能继续知识入库流程。10. 升级、回滚与 checkpoint产品代码与用户 Vault独立升级。在迁移或大批量入库前做一次常规备份或快照。知识写入是带日志的journaled操作中断后运行恢复python3 scripts/claude-obsidian.py transaction recover --vault vault恢复逻辑保守地保留过期的或外来的锁身份只有在确认没有活跃写者之后操作者才可以追加--force-stale-lock。从源码看recover子命令还提供--timeout默认 10 秒与--stale-after默认 3600 秒两个可调参数cli.py#L947-L965--force-stale-lock在同段参数区注册。Git 历史是可选的、从不自动产生。要恰好 checkpoint 一个已完成的事务python3 scripts/claude-obsidian.py checkpoint operation-id --vault vault \ --as-of YYYY-MM-DDcheckpoint 使用临时 index、校验精确的 Git blob 字节、拒绝已存在的暂存状态并能从 Vault 本地的 pending 记录续跑被中断的 ref/index 收尾。checkpoint子命令接受operation_id位置参数以及--message、--include-raw、--skip-lintcli.py#L1229-L1235——其中--include-raw控制是否纳入.raw/源载荷--skip-lint可跳过提交前 lint。11. 卸载卸载时移除宿主集成而不是 Vaultclaude plugin uninstall claude-obsidianagricidaniel-claude-obsidian claude plugin marketplace remove agricidaniel-claude-obsidian对可移植宿主只删除安装器报告过的按技能链接。用户笔记、源材料、ledgers 与 Obsidian 设置均保持原样。12. 排障速查表症状检查Skill 未被发现确认host-skill-root/name/SKILL.md能解析到对应的产品技能重跑安装器--check。命令提示 no vault selected从 Vault 内运行、传--vault、或设置CLAUDE_OBSIDIAN_VAULT对应resolve_vault_root的VAULT_NOT_FOUND。Plugin-root refusal选择一个独立的用户 Vault插件缓存写入不受支持对应PLUGIN_ROOT_IS_NOT_VAULT。Transaction conflict / exit 75有另一操作正在进行或目标已变化重新读取、重建计划并检查新的 bundle退出码 75 定义于 claude_obsidian/transaction.py#L163。Obsidian CLI 不可用退回文件系统读取在重试 CLI 传输前先启动/更新 Obsidian。Capture adapter 未实现检查capture adapters仅在显式同意下配置独立 runner。Windows 上写入被拒并报UNSUPPORTED_PLATFORMVault 变更需要 WSL见 Windows 与 WSL 指南。WSL 已装但wsl --status挂起按微软的诊断与上报流程走Windows 与 WSL 指南没有证据不要臆断原因。原生 WSL 中 dry-run 审批失败报PLAN_CHANGED审批哈希绑定了审查环境需在 WSL 内重做 dry-run详细说明。UNSUPPORTED_PLATFORM错误在源码中有两处抛出点transaction.py#L1388-L1417 与 capture.py#L213源码注释特别说明该错误码的判定刻意避免吞掉真正的EOPNOTSUPP。13. 开发与打包验证如果你是在开发或打包产品变更而非仅安装使用在产品仓库中运行make testmake test依次执行 Makefile 定义的四个阶段逐个隔离运行tests/test_*.py、tests/test_*.sh然后contracts --check-only与contracts --verify最后package validate校验可移植技能、hook 与 manifest 元数据。安装相关的测试用例包括 tests/test_setup_multi_agent.py、tests/test_setup_vault.py、tests/test_paths.py覆盖 Vault 选择与插件树拒绝、tests/test_transaction.py 与 tests/test_wiki_lock.sh。14. 小结claude-obsidian 的安装模型可以归纳为一句话产品只读、数据归用户、写入需审批。三种接入方式最终都指向同一个可移植核心init/adopt/migrate/capture/transaction recover共享“dry-run 计划 → 人工审批 sha256 →--apply”的两段式事务协议Vault 选择按--vault→ 环境变量 → 工作区配置 → 向上发现的固定优先级 fail-closed 解析。掌握这条主线后安装文档里的每一条命令——包括退出码 75、PLAN_CHANGED与UNSUPPORTED_PLATFORM这些“失败信号”——都能对应到 claude_obsidian/paths.py、claude_obsidian/cli.py 与 claude_obsidian/transaction.py 中的具体实现便于在排障时直接定位。【免费下载链接】claude-obsidianSelf-organizing AI second brain for Obsidian Claude Code. Drop any source and Claude reads, links, and files it into one connected knowledge graph of plain Markdown you own. AI note-taking, personal knowledge management (PKM), and an open-source Notion alternative. Based on Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考