vm0幂等交付设计：单调状态机与收据日志的3个技巧，让AI Agent交付不重复执行-开发者社区

vm0幂等交付设计：单调状态机与收据日志的3个技巧，让AI Agent交付不重复执行

【免费下载链接】okouOkou connects to the tools your team already uses and does the work — across marketing, sales, engineering, and operations, under your control.项目地址: https://gitcode.com/GitHub_Trending/vm/okou

本文以 Okou（vm0）——一个连接团队已有工具、跨营销/销售/工程/运维自动执行工作的 AI Agent 平台——为例，讲解保障幂等交付的两个核心机制：单调状态机与收据日志（Receipt Journal），回答一个工程常见痛点：任务重试、进程重启之后，如何保证工作"只执行一次"。

为什么幂等交付对 AI Agent 很重要

Okou 会把团队日常使用的工具接进来，自动完成跨领域的工作。这类任务天然带有大量"外部副作用"：调用外部 API、写文件、产生计费记录。而网络抖动、进程崩溃又让重试成为必然，于是最容易翻车的三件事随之而来：

🧾 重复计费、重复上报用量
📨 同一条消息/事件被消费两次
📁 同一份产物被重复写入

幂等交付的目标只有一句话：同一个请求被重复投递任意多次，结果必须与投递一次完全相同。

技巧一：单调状态机——执行状态只前进，不回头

把一次交付建模成一条只能向前的状态线：未投递 → 已送达 → 已入账。状态机遵守两条纪律：

状态不回退：已经进入"已入账"的投递身份（delivery id），后续任何重试都不会重新执行它；
集合只增不减：恢复流程读取的是"已接受集合"，新快照必须包含此前全部已接受的 id，而不是在旧状态上打补丁。

这意味着崩溃恢复后，系统不是"从头再来一遍"，而是先问一句：这些活，哪些我已经确认干完了？

技巧二：收据日志（Receipt Journal）——用 64KiB 小文件防重复执行

收据日志就是把上面那个"已接受集合"持久化到磁盘的一小段记录，结构极其克制：

约束	取值	目的
单轮最多保留投递身份	1,024 个	防止日志无限膨胀
编码后文件大小上限	64 KiB	越界立即拒绝，而不是截断
投递 id 格式	规范化 UUID	拒绝重复、拒绝畸形 id
文件权限	`0600`私有文件	拒绝符号链接与特殊文件

写日志的关键在 active_input_receipts.rs：先完整校验、再原子替换整个快照。读者任何时刻读到的要么是旧的完整日志、要么是新的完整日志，绝不会读到写了一半的内容。文件缺失则等价于空集合——冷启动天然安全。这套读写经由 runtime_paths.rs 的私有文件原子替换边界完成，安全细节（符号链接拒绝、FIFO 拒绝）在测试 active_input_receipts.rs 中逐条验证。