claude-obsidian操作五步协议：从记录目标哈希到精确报告变更路径的快速指南

claude-obsidian操作五步协议从记录目标哈希到精确报告变更路径的快速指南【免费下载链接】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-obsidianclaude-obsidian 是一个本地优先的「AI 第二大脑」把任意来源丢进收件箱Claude 读取、链接、归档成一张由纯 Markdown 组成的 Obsidian 知识图谱。而这套系统最核心的安全机制就是它的「操作五步协议」——从记录目标文件的 SHA-256 哈希到最终精确报告每一个变更路径。本文带你完整读懂这 5 步看懂 AI 是如何安全修改你的知识库的。为什么需要「五步协议」️多数 AI 笔记工具的痛点是AI 直接往你的笔记里写东西写坏了不知道、覆盖了没法查、多个 AI 并行时互相踩踏。claude-obsidian 的设计原则只有一句话一个逻辑知识操作 一个可恢复的事务。并行的工作代理只能返回草稿唯一的编排者检查并应用一次可回滚的事务。这不是功能细节而是架构的一部分。想深入了解这套「产品与库的信任边界」可以阅读官方文档 docs/compound-vault-guide.md。五步协议全景一张表看懂步骤名称核心动作1️⃣记录目标哈希读取所有目标文件记下 SHA-256 指纹或期望它不存在2️⃣并行起草工作代理只返回草稿与证据不碰共享库状态3️⃣合并事务包把全部变更合并成一个claude-obsidian.transaction.v1包4️⃣检查后应用先 inspect 校验再凭审批哈希 apply 一次5️⃣报告变更报告操作 ID 和精确的变更路径清单第一步锁定目标文件记下「指纹」写入前引擎会先读取每一个预期目标文件记录它的 SHA-256 哈希如果该文件按设计还不存在就记录一个空值null。这份指纹清单expected_hashes是整个事务的基准线应用时任何目标文件与指纹不符 → 判定为冲突直接拒绝绝不静默覆盖冲突的退出码是75提示你重新读取、重新构建、重新检查同时还会先解析你要操作的 vault依次看--vault参数、环境变量、配置文件一旦指向不明确就直接退出、不写任何东西一句话先拍照存档再动笔修改。第二步并行起草谁都不直接落笔多代理协作最大的风险是「抢写」。claude-obsidian 的解法很干脆并行工作代理只允许读和起草产出「草稿 证据」谁也不能编辑共享的库状态。写入权集中在编排者手里由事务引擎统一执行并在整个操作期间持有一把进程级 vault 锁。这也是为什么官方文档反复强调Obsidian CLI 只能用来读任何写操作都必须走事务核心没有第二条写入通道。第三步合并成一个事务包所有变更被合并进一个claude-obsidian.transaction.v1的 JSON 包里面包含operation_id本次操作的唯一编号expected_hashes第一步记下的指纹清单writes每个写入目标的路径、模式和内容哈希操作类型是「被强制执行的权限」不是标签——比如canvas只能写画布目录capture只能创建原始副本越界路径直接拒绝同时有硬性上限单文件 64 MiB、总内容 128 MiB、单次最多 1024 个写入。目的只有一个保证任何被接受的操作都能完整回滚。第四步先 inspect 检查再凭审批哈希应用这是五步协议里最体现「信任」的一步先跑inspect完整校验事务包但不产生任何写入。校验失败 什么都没发生涉及破坏性、外部或合并类变更时先展示给用户确认再跑apply必须带上检查阶段输出的审批哈希approval_sha256。它把「你批准的计划」和「解析出的 vault 根目录」绑定在一起换个库就不能复用引擎在应用时会备份原件日志化、校验内容哈希、用原子替换落盘中途失败或中断自动恢复原状对应命令入口在 scripts/claude-obsidian.pytransaction inspect/transaction apply/transaction recover完整契约见 skills/wiki/references/operation-transactions.md。第五步报告操作 ID 与精确变更路径应用成功后协议要求主动报告两样东西操作 IDoperation_id和精确的变更路径清单changed_paths。你可以逐条核对「AI 这次到底动了哪些文件」而不是盲信一句「已完成」。如果你还想把这次操作沉淀为 Git 历史运行单独的checkpoint 命令即可——它验证精确的 blob 字节、拒绝已有暂存内容且永远不会自动触发。出错了怎么办冲突、恢复与检查点 场景系统行为你该做什么目标文件已被改动 / 锁被占用退出码 75不写任何东西重新读取 → 重建事务包 → 重新检查校验失败无任何写入发生修正计划后重跑 dry-run应用中途被中断下次应用时自动回滚或恢复也可手动运行transaction recover崩溃后残留陈旧锁不会仅凭「锁太老」就抢占人工确认无写入者后才用--force-stale-lock还有一条铁律绝不允许用|| true之类的方式掩盖事务失败。想深入源码这些路径值得收藏 事务引擎核心实现claude_obsidian/transaction.py显式检查点逻辑claude_obsidian/checkpoint.py五步协议完整契约skills/wiki/references/operation-transactions.md证据与溯源契约skills/wiki/references/provenance.mdCompound Vault 架构说明docs/compound-vault-guide.md官方入口与命令速查README.md小结一份五步安全清单 ✅指纹——记录每个目标文件的 SHA-256起草——并行代理只产草稿不落笔合并——所有变更装进一个可回滚事务包审批——inspect 通过后凭哈希 apply 一次报告——拿到操作 ID 和逐条变更路径不用背任何命令只要记住原则一次操作、一个事务、先验后写、改完必报。你的知识库始终是一堆普通 Markdown 文件而每一次 AI 修改都经得起逐字节核对。【免费下载链接】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），仅供参考