企业官网建设流程全解析

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 Karpathy's 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 由两个互不依赖的部分组成：

1. 产品包——skills、可移植核心（portable core）、Claude 适配器与模板；
2. 用户自有的 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. 环境要求

当前仓库版本为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.py（scripts/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-obsidian@agricidaniel-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-run）：

bash 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 使用工作区本地发现，需要显式指定--workspace：

bash scripts/setup-multi-agent.sh --host cursor --host windsurf \ --workspace <workspace> --apply

ZCode 是 opt-in 的、用户级（无需--workspace）：

bash scripts/setup-multi-agent.sh --host zcode bash scripts/setup-multi-agent.sh --host zcode --apply

也可以手动创建等价的按技能符号链接。对产品skills/目录下的每个<name>：

Codex: ~/.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-L166），Cursor/Windsurf 则要求--workspace否则直接报错退出。

5. 创建新 Vault：先审计划，再应用

init是“两段式”操作：先打印初始化计划，人工确认目标路径与变更路径无误后，再带上审批哈希应用。

python3 scripts/claude-obsidian.py init <new-vault> \ --generated-at <ISO-UTC> --operation-id init-reviewed

python3 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 manifest；
• wiki/——索引、日志、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/vault（inbox/、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：

1. --vault <path>
2. CLAUDE_OBSIDIAN_VAULT
3. 最近的.claude-obsidian.json
4. 从当前目录向上找到的最近、无歧义的已初始化 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 <vault>

doctor检查 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> --apply

capture子命令组在 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-DD

checkpoint 使用临时 index、校验精确的 Git blob 字节、拒绝已存在的暂存状态，并能从 Vault 本地的 pending 记录续跑被中断的 ref/index 收尾。checkpoint子命令接受operation_id位置参数以及--message、--include-raw、--skip-lint（cli.py#L1229-L1235）——其中--include-raw控制是否纳入.raw/源载荷，--skip-lint可跳过提交前 lint。

11. 卸载

卸载时移除宿主集成，而不是 Vault：

claude plugin uninstall claude-obsidian@agricidaniel-claude-obsidian claude plugin marketplace remove agricidaniel-claude-obsidian

对可移植宿主，只删除安装器报告过的按技能链接。用户笔记、源材料、ledgers 与 Obsidian 设置均保持原样。

12. 排障速查表

UNSUPPORTED_PLATFORM错误在源码中有两处抛出点（transaction.py#L1388-L1417 与 capture.py#L213），源码注释特别说明：该错误码的判定刻意避免吞掉真正的EOPNOTSUPP。

13. 开发与打包验证

如果你是在开发或打包产品变更（而非仅安装使用），在产品仓库中运行：

make test

make 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 Karpathy's LLM Wiki pattern.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-obsidian