尧图网站建设 
一次操作要改多个文件如何保证知识库永远不半截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-obsidian本文拆解 claude-obsidian 的 Obsidian Markdown 知识库可恢复 vault 事务机制它如何用一个持久日志、一份预检哈希和一把带所有权令牌的锁把一次改好几个笔记的操作变成要么全成、要么全退的诚实承诺。claude-obsidian 是一个开源的 AI 第二大脑工具你把资料丢进inbox/它自动阅读、提炼、归档最后变成 Obsidian 里互相链接的 Markdown 知识图谱。听起来很美但底层藏着一个朴素却致命的问题——它的每次保存从来不是改一个文件。看官方文档 operation-transactions.md 里的耦合写入清单一次 Save 要同时更新笔记本身、索引index.md、日志log.md和热缓存hot.md四个文件一次 Ingest归档入库要动源文件、新笔记、证据记录、索引、日志……十来个。普通文件系统不保证多文件写入是原子的写到第三个文件时进程崩了、断电了你的知识库就停在笔记写了、索引没更的半截状态而且没人知道它到底写到了哪。源码开头 transaction.py 的第一段注释毫不客气地承认了这一点多文件文件系统更新在常见文件系统上无法做到真正的原子。然后它给出的答案是更强、更诚实的承诺a stronger, honest contract一把进程持有的变更锁、预检哈希、一份持久日志、逐文件的原子替换外加确定性的回滚与恢复。下面按一个操作的生命周期走一遍动作之前它怎么立字据动作当下它怎么拿锁和落笔动作失败之后它怎么收拾残局。动笔之前先立一份书面变更计划这套机制的起点是一份叫transaction bundle事务包的 JSON 文档schema 名为claude-obsidian.transaction.v1。它不是我要写这些文件的模糊声明而是一份极其具体的字据核心字段有四个operation_type操作类型比如save、ingest、capturewrites每个目标路径、写入模式create或replace、以及新内容的 SHA-256expected_hashes每个目标路径此刻应该长什么样的预期哈希——文件不存在就填nullread_preconditions只读依赖的文件的预期哈希比如 Ingest 要读原始源文件就顺手把它的指纹也钉死。expected_hashes是整个机制的枢纽。它意味着你在起草计划时看到的每个文件都必须在执行时保持原样否则直接拒绝。这就像二手房交易前的标的物状态确认——合同里写明了墙面颜色签约时墙被刷了交易不成立。执行阶段的对应错误码是EXPECTED_HASH_MISMATCH语义是这个文件在你起草之后被人改过。计划立好还不能直接执行。CLI 提供transaction inspect子命令做纯只读预演并计算一个approval_sha256审批哈希。这个哈希由plan_approval_sha256生成它把四样东西绞在一起规范化后的 vault 根路径、vault 目录自身的身份证号st_dev设备号 st_inoinode 号、扩展后 bundle 的规范 JSON 哈希、每个写入的旧哈希、新哈希、权限模式投影。这带来了两个实用性质改一个字节哈希就变所以审批的是精确到字节的内容换一座 vault哈希就废所以别人没法拿这座库审批过的令牌去操作另一座库。真正执行时transaction apply要求把这个哈希原样传回——你批准的那个字节级计划一个字节都不能差。变更锁先拿到唯一一支笔计划通过预演接下来MutationLock登场。它要解决的问题是两个进程比如你手动跑了一次归档同时后台 agent 也在存笔记同时改同一座库。锁的物理形态有点反直觉不是锁文件而是一个目录.vault-meta/mutation.lock。目录的创建在 POSIX 上是原子的——mkdir成功就是拿到锁FileExistsError说明别人先到了。抢到锁的进程会在里面写入一份owner.json记录 pid、主机名、开始时间和一个随机 token。细节里最有意思的是三点锁是钉在描述符上的不是钉在路径上的。整个操作期间进程持有 vault 根目录、.vault-meta目录、锁目录各自的目录描述符dirfd后续所有打开、创建、删除都相对这些描述符进行全程O_NOFOLLOW绝不跟随符号链接。这意味着即使有人趁操作进行到一半把 vault 里的某个目录偷偷替换成指向/etc的符号链接读写也不会被拐跑——路径在拿到那一刻就被物理固定了。_open_lock_parent_from_root_fd这类函数就是干这件事的。释放锁之前要回读 token。MutationLock.release在拆锁前会重新读一次owner.json用hmac.compare_digest比对 token 是否还是自己的。对不上就抛LOCK_OWNERSHIP_LOST——宁可不释放也绝不拆掉可能已经不是我的锁。这是防止并发偷换锁的最后一道保险。过期锁的回收极其保守。进程挂了锁目录会一直留着。回收的条件是同一主机、持有进程确认已死os.kill(pid, 0)探测、锁龄超过 1 小时stale_after三者同时满足才动手——而且删除前先改名隔离成mutation.lock.reaping-pid-uuid改完名还要复查这个目录还是我认定的那个目录才允许删除。文档里明确写着绝不允许仅凭锁变老了就偷锁--force-stale-lock是留给运维的显式覆盖开关不要自动化它。等锁超时默认 10 秒拿不到进程退出码 75 并报错——75 在这套体系里是约定俗成的冲突信号上层 agent 看到 75 就知道重读、重起草、重来。日志与原子替换每个文件是换上去的不是写上去的锁到手真正动笔。这里有两件并行的事。写日志journal。在每个文件动之前先在.vault-meta/transactions/operation_id/下原子写入一份journal.json初始状态prepared逐条记录每个写入的路径、模式、新哈希、旧哈希、旧权限、新权限、以及备份文件名。每完成一个文件applied列表就补一条。这份日志是如果我在第 3/7 个文件时死了下一个人该怎么救场的完整说明书。逐文件原子替换。具体写入由_atomic_vault_write执行套路是经典的临时文件 rename在目标目录里创建.{文件名}.txn-{pid}-{uuid}临时文件O_EXCL保证不覆盖任何已存在的东西写完fsync落盘、fchmod设好权限然后os.replace一步原子地顶掉目标文件最后连父目录也fsync一次。读者永远只看到旧文件或新文件两种状态看不到写了一半的东西。被覆盖的旧内容不是丢进回收站就完事而是存成backups/0001.original、0002.original……备份同样有预算整个操作的备份总量和新增内容总量各自封顶 128 MiB。这个封顶不是抠门而是恢复能力的边界——引擎只接受它自己兜得起底的操作超了就拒绝而不是赌。失败之后连回滚都要证明文件没被动过半截状态被日志堵住了但收拾残局本身也可能出事。回滚要删掉新文件create 模式或恢复备份replace 模式可万一恢复执行时那个新文件已经被别人换掉了呢删它等于误伤不删又回滚不干净。_confined_vault_unlink的解法是把删文件变成一场审讯先按目录描述符打开目标确认是普通文件算 SHA-256 与日志里的预期值比对然后再做一次 stat核对设备号 inode 号与刚才打开的是同一个对象——两次身份核验都通过才允许unlink。任何一步对不上抛ROLLBACK_TARGET_CHANGED停止一切动作。宁可留下一份没删干净的现场让人类处理也不会在错误的位置下手。恢复的入口有两处下一次transaction apply会先扫描未完成的日志recover_incomplete自动决定补做还是回滚也可以显式跑transaction recover。恢复逻辑只认日志和备份里记的哈希不信任任何看起来差不多的状态。所有恢复路径共享同一个哲学不确定就失败关闭fail closed——CORRUPT_RUNTIME_STATE、RUNTIME_NAMESPACE_CHANGED、VAULT_NAMESPACE_CHANGED这些错误码对应的都是我认不出现场了停下而不是我猜一个继续。顺带一提连读一个 64 KB 的配置文件比如 workspace 配置都要做读前 stat → 打开后 fstat → 读完再 fstat三连比对任何时刻文件身份变了就报错。这套读也要防掉包的执念在 paths.py 里贯彻得很彻底。谁能动哪里操作类型是一道权限边界还有一层容易被忽略的设计operation_type不只是审计标签而是权限边界。每个操作类型都被写死了可触碰的内容域capture只能创建.raw/captured/*下的原始载荷内容寻址仓库只进不改save、markdown、lint-fix、generic被圈死在wiki/之内fold只能写一个 fold 页加index.md、log.mdcanvas只能动画布目录。同时存在一份保留路径黑名单.git、.vault-meta/transactions、.vault-meta/mutation.lock等任何用户侧 bundle 都无权写入——哪怕它用的是最宽泛的generic类型。也就是说一个精心构造的事务包既越不了操作类型的围栏也碰不了系统自己的运行时状态。配套的资源预算同样写死在 transaction.py 顶部单文件 64 MiB、单操作总内容 128 MiB、单操作最多 1024 个写入、路径最长 1024 字节、运行时 JSON 8 MiB。它们和归档入口 capture.py 里那套 100 文件 / 256 MB 的批预算一样都是失败即中止的硬限不是建议值。这些保证花掉了什么诚实承诺的另一面是代价值得摊开说性能。每个目标文件要读两遍一遍算哈希、一遍存备份每次写入要fsync文件加目录锁的获取是 50 毫秒间隔的轮询。在一座几千页的库里连续操作这是实打实的开销。换来的是崩溃恢复的确定性——这笔账在个人知识库、分钟级写入频率的场景下明显划算。平台。描述符钉死dirfd 封装依赖 POSIX 的openat家族原语和fcntl.flockpaths.py 里的supports_confined_dirfd()会逐项检查。原生 Windows 没有这套原语于是_require_write_platform在任何副作用发生之前就拒绝写入报UNSUPPORTED_PLATFORM——只读检查和干跑可以原生跑写入必须走 WSL见 docs/windows-wsl.md。同理FAT/exFAT 这类不暴露稳定 inode 的文件系统也会被UNSAFE_VAULT_IDENTITY拦下因为身份核验的地基不存在了。可恢复性的半径。128 MiB 的总预算意味着超大迁移要按逻辑边界拆成多笔操作。这是设计者主动选择的不保证任何操作都可恢复只保证我接受的操作都可恢复。错误码与关键文件速查错误码 / 退出码含义典型出处LOCK_TIMEOUT退出 75变更锁被别的操作持有等满超时MutationLock.acquireLOCK_OWNERSHIP_LOST锁的归属在持有期间变了拒绝拆除MutationLock.releaseEXPECTED_HASH_MISMATCH退出 75目标文件在起草后被改过_prepare_writesROLLBACK_TARGET_CHANGED退出 3回滚目标在验证期间被换过_confined_vault_unlinkRAW_IS_CREATE_ONLY试图替换原始源载荷写入范围校验CASEFOLD_PATH_ALIAS库里已存在 NFC大小写折叠后的别名路径可移植别名审计UNSAFE_VAULT_PATH/SYMLINK_WRITE_PATH目标路径越界或穿过了符号链接_safe_vault_pathUNSUPPORTED_PLATFORM平台缺少 dirfd 封装原语拒绝写入_require_write_platform文件职责claude_obsidian/transaction.py事务引擎主体锁、预检、日志、原子写、回滚与恢复claude_obsidian/paths.pyvault 根选择、路径包含性检查assert_within、符号链接识别claude_obsidian/capture.py归档入口的独立预算与队列锁与事务层分头设防skills/wiki/references/operation-transactions.md事务契约、bundle 形状与失败行为的官方说明SECURITY.md安全边界与防御性不变量的声明下次你在终端看到退出码 75或者日志里蹦出一句ROLLBACK_TARGET_CHANGED现在可以知道发生了什么那不是 bug而是这套机制在按剧本演出它最核心的承诺——知识库的每一处变更要么完整成立要么被证明地完整撤销而它说不出话的每一种情况它都会选择停下来。【免费下载链接】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），仅供参考 一次操作要改多个文件，如何保证知识库永远不“半截“：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-obsidian本文拆解 claude-obsidian 的 Obsidian Markdown 知识库可恢复 vault 事务机制它如何用一个持久日志、一份预检哈希和一把带所有权令牌的锁把一次改好几个笔记的操作变成要么全成、要么全退的诚实承诺。claude-obsidian 是一个开源的 AI 第二大脑工具你把资料丢进inbox/它自动阅读、提炼、归档最后变成 Obsidian 里互相链接的 Markdown 知识图谱。听起来很美但底层藏着一个朴素却致命的问题——它的每次保存从来不是改一个文件。看官方文档 operation-transactions.md 里的耦合写入清单一次 Save 要同时更新笔记本身、索引index.md、日志log.md和热缓存hot.md四个文件一次 Ingest归档入库要动源文件、新笔记、证据记录、索引、日志……十来个。普通文件系统不保证多文件写入是原子的写到第三个文件时进程崩了、断电了你的知识库就停在笔记写了、索引没更的半截状态而且没人知道它到底写到了哪。源码开头 transaction.py 的第一段注释毫不客气地承认了这一点多文件文件系统更新在常见文件系统上无法做到真正的原子。然后它给出的答案是更强、更诚实的承诺a stronger, honest contract一把进程持有的变更锁、预检哈希、一份持久日志、逐文件的原子替换外加确定性的回滚与恢复。下面按一个操作的生命周期走一遍动作之前它怎么立字据动作当下它怎么拿锁和落笔动作失败之后它怎么收拾残局。动笔之前先立一份书面变更计划这套机制的起点是一份叫transaction bundle事务包的 JSON 文档schema 名为claude-obsidian.transaction.v1。它不是我要写这些文件的模糊声明而是一份极其具体的字据核心字段有四个operation_type操作类型比如save、ingest、capturewrites每个目标路径、写入模式create或replace、以及新内容的 SHA-256expected_hashes每个目标路径此刻应该长什么样的预期哈希——文件不存在就填nullread_preconditions只读依赖的文件的预期哈希比如 Ingest 要读原始源文件就顺手把它的指纹也钉死。expected_hashes是整个机制的枢纽。它意味着你在起草计划时看到的每个文件都必须在执行时保持原样否则直接拒绝。这就像二手房交易前的标的物状态确认——合同里写明了墙面颜色签约时墙被刷了交易不成立。执行阶段的对应错误码是EXPECTED_HASH_MISMATCH语义是这个文件在你起草之后被人改过。计划立好还不能直接执行。CLI 提供transaction inspect子命令做纯只读预演并计算一个approval_sha256审批哈希。这个哈希由plan_approval_sha256生成它把四样东西绞在一起规范化后的 vault 根路径、vault 目录自身的身份证号st_dev设备号 st_inoinode 号、扩展后 bundle 的规范 JSON 哈希、每个写入的旧哈希、新哈希、权限模式投影。这带来了两个实用性质改一个字节哈希就变所以审批的是精确到字节的内容换一座 vault哈希就废所以别人没法拿这座库审批过的令牌去操作另一座库。真正执行时transaction apply要求把这个哈希原样传回——你批准的那个字节级计划一个字节都不能差。变更锁先拿到唯一一支笔计划通过预演接下来MutationLock登场。它要解决的问题是两个进程比如你手动跑了一次归档同时后台 agent 也在存笔记同时改同一座库。锁的物理形态有点反直觉不是锁文件而是一个目录.vault-meta/mutation.lock。目录的创建在 POSIX 上是原子的——mkdir成功就是拿到锁FileExistsError说明别人先到了。抢到锁的进程会在里面写入一份owner.json记录 pid、主机名、开始时间和一个随机 token。细节里最有意思的是三点锁是钉在描述符上的不是钉在路径上的。整个操作期间进程持有 vault 根目录、.vault-meta目录、锁目录各自的目录描述符dirfd后续所有打开、创建、删除都相对这些描述符进行全程O_NOFOLLOW绝不跟随符号链接。这意味着即使有人趁操作进行到一半把 vault 里的某个目录偷偷替换成指向/etc的符号链接读写也不会被拐跑——路径在拿到那一刻就被物理固定了。_open_lock_parent_from_root_fd这类函数就是干这件事的。释放锁之前要回读 token。MutationLock.release在拆锁前会重新读一次owner.json用hmac.compare_digest比对 token 是否还是自己的。对不上就抛LOCK_OWNERSHIP_LOST——宁可不释放也绝不拆掉可能已经不是我的锁。这是防止并发偷换锁的最后一道保险。过期锁的回收极其保守。进程挂了锁目录会一直留着。回收的条件是同一主机、持有进程确认已死os.kill(pid, 0)探测、锁龄超过 1 小时stale_after三者同时满足才动手——而且删除前先改名隔离成mutation.lock.reaping-pid-uuid改完名还要复查这个目录还是我认定的那个目录才允许删除。文档里明确写着绝不允许仅凭锁变老了就偷锁--force-stale-lock是留给运维的显式覆盖开关不要自动化它。等锁超时默认 10 秒拿不到进程退出码 75 并报错——75 在这套体系里是约定俗成的冲突信号上层 agent 看到 75 就知道重读、重起草、重来。日志与原子替换每个文件是换上去的不是写上去的锁到手真正动笔。这里有两件并行的事。写日志journal。在每个文件动之前先在.vault-meta/transactions/operation_id/下原子写入一份journal.json初始状态prepared逐条记录每个写入的路径、模式、新哈希、旧哈希、旧权限、新权限、以及备份文件名。每完成一个文件applied列表就补一条。这份日志是如果我在第 3/7 个文件时死了下一个人该怎么救场的完整说明书。逐文件原子替换。具体写入由_atomic_vault_write执行套路是经典的临时文件 rename在目标目录里创建.{文件名}.txn-{pid}-{uuid}临时文件O_EXCL保证不覆盖任何已存在的东西写完fsync落盘、fchmod设好权限然后os.replace一步原子地顶掉目标文件最后连父目录也fsync一次。读者永远只看到旧文件或新文件两种状态看不到写了一半的东西。被覆盖的旧内容不是丢进回收站就完事而是存成backups/0001.original、0002.original……备份同样有预算整个操作的备份总量和新增内容总量各自封顶 128 MiB。这个封顶不是抠门而是恢复能力的边界——引擎只接受它自己兜得起底的操作超了就拒绝而不是赌。失败之后连回滚都要证明文件没被动过半截状态被日志堵住了但收拾残局本身也可能出事。回滚要删掉新文件create 模式或恢复备份replace 模式可万一恢复执行时那个新文件已经被别人换掉了呢删它等于误伤不删又回滚不干净。_confined_vault_unlink的解法是把删文件变成一场审讯先按目录描述符打开目标确认是普通文件算 SHA-256 与日志里的预期值比对然后再做一次 stat核对设备号 inode 号与刚才打开的是同一个对象——两次身份核验都通过才允许unlink。任何一步对不上抛ROLLBACK_TARGET_CHANGED停止一切动作。宁可留下一份没删干净的现场让人类处理也不会在错误的位置下手。恢复的入口有两处下一次transaction apply会先扫描未完成的日志recover_incomplete自动决定补做还是回滚也可以显式跑transaction recover。恢复逻辑只认日志和备份里记的哈希不信任任何看起来差不多的状态。所有恢复路径共享同一个哲学不确定就失败关闭fail closed——CORRUPT_RUNTIME_STATE、RUNTIME_NAMESPACE_CHANGED、VAULT_NAMESPACE_CHANGED这些错误码对应的都是我认不出现场了停下而不是我猜一个继续。顺带一提连读一个 64 KB 的配置文件比如 workspace 配置都要做读前 stat → 打开后 fstat → 读完再 fstat三连比对任何时刻文件身份变了就报错。这套读也要防掉包的执念在 paths.py 里贯彻得很彻底。谁能动哪里操作类型是一道权限边界还有一层容易被忽略的设计operation_type不只是审计标签而是权限边界。每个操作类型都被写死了可触碰的内容域capture只能创建.raw/captured/*下的原始载荷内容寻址仓库只进不改save、markdown、lint-fix、generic被圈死在wiki/之内fold只能写一个 fold 页加index.md、log.mdcanvas只能动画布目录。同时存在一份保留路径黑名单.git、.vault-meta/transactions、.vault-meta/mutation.lock等任何用户侧 bundle 都无权写入——哪怕它用的是最宽泛的generic类型。也就是说一个精心构造的事务包既越不了操作类型的围栏也碰不了系统自己的运行时状态。配套的资源预算同样写死在 transaction.py 顶部单文件 64 MiB、单操作总内容 128 MiB、单操作最多 1024 个写入、路径最长 1024 字节、运行时 JSON 8 MiB。它们和归档入口 capture.py 里那套 100 文件 / 256 MB 的批预算一样都是失败即中止的硬限不是建议值。这些保证花掉了什么诚实承诺的另一面是代价值得摊开说性能。每个目标文件要读两遍一遍算哈希、一遍存备份每次写入要fsync文件加目录锁的获取是 50 毫秒间隔的轮询。在一座几千页的库里连续操作这是实打实的开销。换来的是崩溃恢复的确定性——这笔账在个人知识库、分钟级写入频率的场景下明显划算。平台。描述符钉死dirfd 封装依赖 POSIX 的openat家族原语和fcntl.flockpaths.py 里的supports_confined_dirfd()会逐项检查。原生 Windows 没有这套原语于是_require_write_platform在任何副作用发生之前就拒绝写入报UNSUPPORTED_PLATFORM——只读检查和干跑可以原生跑写入必须走 WSL见 docs/windows-wsl.md。同理FAT/exFAT 这类不暴露稳定 inode 的文件系统也会被UNSAFE_VAULT_IDENTITY拦下因为身份核验的地基不存在了。可恢复性的半径。128 MiB 的总预算意味着超大迁移要按逻辑边界拆成多笔操作。这是设计者主动选择的不保证任何操作都可恢复只保证我接受的操作都可恢复。错误码与关键文件速查错误码 / 退出码含义典型出处LOCK_TIMEOUT退出 75变更锁被别的操作持有等满超时MutationLock.acquireLOCK_OWNERSHIP_LOST锁的归属在持有期间变了拒绝拆除MutationLock.releaseEXPECTED_HASH_MISMATCH退出 75目标文件在起草后被改过_prepare_writesROLLBACK_TARGET_CHANGED退出 3回滚目标在验证期间被换过_confined_vault_unlinkRAW_IS_CREATE_ONLY试图替换原始源载荷写入范围校验CASEFOLD_PATH_ALIAS库里已存在 NFC大小写折叠后的别名路径可移植别名审计UNSAFE_VAULT_PATH/SYMLINK_WRITE_PATH目标路径越界或穿过了符号链接_safe_vault_pathUNSUPPORTED_PLATFORM平台缺少 dirfd 封装原语拒绝写入_require_write_platform文件职责claude_obsidian/transaction.py事务引擎主体锁、预检、日志、原子写、回滚与恢复claude_obsidian/paths.pyvault 根选择、路径包含性检查assert_within、符号链接识别claude_obsidian/capture.py归档入口的独立预算与队列锁与事务层分头设防skills/wiki/references/operation-transactions.md事务契约、bundle 形状与失败行为的官方说明SECURITY.md安全边界与防御性不变量的声明下次你在终端看到退出码 75或者日志里蹦出一句ROLLBACK_TARGET_CHANGED现在可以知道发生了什么那不是 bug而是这套机制在按剧本演出它最核心的承诺——知识库的每一处变更要么完整成立要么被证明地完整撤销而它说不出话的每一种情况它都会选择停下来。【免费下载链接】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），仅供参考