Pomerado 写安全机制完整指南:幂等键、commit marks 与 outcome reviewer 如何防止重复提交
Pomerado 写安全机制完整指南:幂等键、commit marks 与 outcome reviewer 如何防止重复提交
Pomerado 是一个把任意网站变成 API / MCP 集成的开源项目,让 AI Agent 能直接操作网站。对下单、预订、提交表单这类"写"操作来说,最怕的就是重复提交:网络超时后重发,可能已经在网站上多下了一单。Pomerado 用三道防线解决它——幂等键(idempotency key)、**commit marks(提交标记)**和 outcome reviewer(结果审查员)。本文带你逐个拆解它们的工作原理。
为什么"写"操作最难:一次超时的重发可能是第二笔订单 🛡️
把网站集成给 Agent 用时,"读"操作天然安全:再查一次页面,数据不变。但"写"操作不同——点击 Submit 的那一刻,改变就已经发生或正在发生。经典事故场景是:
- 脚本点了"提交订单";
- 网络超时,脚本以为失败了;
- 重试逻辑重新提交一次——结果下了两单。
Pomerado 的官方文档把整套设计讲得很清楚,可先读 docs/how-it-works.md 了解全局。三道防线各司其职:
| 防线 | 解决什么问题 | 什么时候生效 |
|---|---|---|
幂等键 idempotency_key |
同一请求重发不能变成新的网站动作 | 调用入口(网关层) |
| commit marks | 失败后能否判断"到底提交没提交" | 运行过程中 |
| outcome reviewer | 事后裁定写入是否真的生效 | 写入返回之后 |
幂等键 idempotency_key:重试永远拿到原答案 🔑
只有"写"工具才会暴露 idempotency_key 参数(可选,1~200 位字母、数字、-、_),它的 schema 定义在 mcp-server.ts。工具描述会明确告诉调用方:"把它当作这次调用的钥匙,只在重试同一次调用时复用;不带钥匙的调用就是新的网站动作。"
三条规则(核心逻辑在 job-store.ts 的 submitJob 中):
| 场景 | 结果 |
|---|---|
| 同 key + 同输入 | 不启动新任务,直接并入原 job(结果里带 rejoined: true),网站零动作 |
| 同 key + 不同输入 | 拒绝并报错 retry_conflict:要么用原请求重发,要么换新 key |
| 不带 key | 启动一个全新 job,即新的网站动作 |
一条 key 如何变成唯一文件名
本地宿主把每个带 key 的 job 存成集成目录下 .jobs/ 里的一个 JSON 文件。key 会被指纹化,再经 SHA-256 派生出一个确定性 UUID 作为文件名(local-job-store.ts)——同一个 key 永远指向同一个文件。创建文件用"排他硬链接"实现:两个进程同时提交同一 key,只有一个链接成功,因此并发也只产生一个 job。
两个细节很贴心:
- 隐私:记录只存 key、输入摘要、job ID 和状态,永不存输入和输出(local-job-store.ts);
- 重启安全:服务器重启后,发现一个"还在 running 但宿主进程已死"的记录,会把它标记为失败(
lost: true)且永不重放——宁可报失败,也不冒重复提交的风险。
一次调用的最小示例:
{ "input": { "sku": "A-1", "qty": 2 }, "idempotency_key": "order-2026-0001" }
commit marks:脚本自己的"发送日志" 🧾
幂等键挡住了"调用方重复发起",但如果一次运行内部失败了,网站到底改没改?Pomerado 的答案是让脚本自己打点。
在可能把改动发往网站的那次调用(提交、保存、确认按钮)之前,脚本调用 enteringCommit("place-order") 打一个标记,并在契约里按顺序声明所有标记(write.commits)。完整示例见 write-session.ts 与编写规范 writes/SKILL.md。
运行结束后,脚本上报每个标记的状态:not_sent / sent / confirmed(run-outcome.ts)。宿主据此归成四种证据:
| 证据 | 含义 |
|---|---|
not_entered |
声明了标记但一个都没进入——唯一能证明"什么也没发送"的情况 |
entered |
已进入某个提交步骤,可能已发送 |
undeclared |
没声明任何标记,GET 链接这类宿主看不见的提交仍可能发生 |
unreported |
没有可读的上报(页面丢了),什么都不知道 |
设计原则是失败时倾向保守:只有 not_entered 才能让一次失败算"未变更网站",其余一律按"可能已提交"处理。
read-back first:失败后的铁律
write-session.ts 的 readBackFirst 规定了规则:一个被 Guardian 判为写的步骤如果没跑完,在再次写入之前,必须先跑一个只读步骤把网站状态读回来——除非 commit marks 显示根本没进入提交步骤。宿主还有一条硬限制:源代码没变、又刚发过状态变更请求的提交步骤,重发会被直接拒绝。
失败 job 因此带四个字段(mcp-jobs.ts):code、write_status(applied / not_applied / may_have_applied / not_attempted)、possible_commit 和 retry。retry 是四类重试策略(run-outcome.ts):
| retry | 意思 |
|---|---|
never |
别原样重发;先确认结果 |
fix_input |
修正输入或登录再调 |
same_key |
允许用同一 key 原样重发 |
new_key |
重发就是新运行;possible_commit 为 true 时先读回网站 |
记住一句话:只有 possible_commit: true 在叫你重试前先读回网站。
outcome reviewer:事后审查员,专门判"到底生效没" 🧑⚖️
Guardian 在 minting 阶段审查每个动作,但它在动作运行前判断,从来看不到结果。补上这块的是 outcome reviewer——一个独立的、持久的模型会话,只回答一个问题:Guardian 标记为 write 的每次执行,到底改没改网站?
结论只有三种(outcome-review-contracts.ts):
done:证据显示改动发生了;not_done:证据显示没发生,且证据覆盖了该改动的账号、范围和时间;unknown:证据不足以判断。
它的工作方式有两个关键设计:
- 只有只读工具:搜索和阅读 minter 的完整历史、宿主的执行/源码/捕获/发布记录、原始请求与任务状态;没有浏览器、shell 或网站访问权限。它唯一能"动手"的方式是向 minter 申请一次 read-back,而这次读取要走正常的 Guardian 审查通道(outcome-review.ts)。
- 拦住重复写入:minter 想再跑一个与之前 write 相同入口(或源码摘要相同、只是改了名字)的步骤时,宿主会拒绝——直到 reviewer 判定该写入
not_done。Guardian 的每次执行审查也会看到各写入的最新裁定,直接拒绝"把同一个变更再提交一次"的步骤。
注意它不会阻塞发布:未裁定的写入按 may_have_applied 处理(发布永远不等审查),保证系统永远诚实地暴露不确定性,而不是假装知道。
三道防线如何协同:一次下单的完整时间线
- 调用方带着
idempotency_key: "order-0001"发起下单 → 网关先查.jobs,若同 key 已有 job,直接并入原 job,网站零动作; - 运行中,脚本在点击"Place order"前打
enteringCommit("place-order"),然后请求发出、浏览器失联,步骤失败; - 失败分类器判定:标记已
entered→write_status: may_have_applied、possible_commit: true、retry: never——重发被幂等键挡住,盲目重试被 retry 类挡住; - minter 想重跑该步骤,被 outcome reviewer 机制拦下:先只读回页面;若确认没生效,才允许走"第一次真正的提交";
- reviewer 独立复核历史与宿主记录,落笔
done/not_done/unknown,并进入 Guardian 后续审查的视野。
每一层单独都有漏洞,叠在一起则没有"悄悄下两单"的缝隙。
新手速查清单 ✅
- 每次写调用都带
idempotency_key,重试时复用同一个 key; - 失败时先看
possible_commit与retry字段,再决定下一步; retry: never时绝不原样重发,先读回网站;- 脚本里把
enteringCommit放在真正发送改动的那次调用之前,并声明所有标记; - 失败 job 永远不会被自动重放——这是特性,不是缺陷。
关键源码位置
| 路径 | 内容 |
|---|---|
| typescript/src/runtime/job-store.ts | 幂等键重试规则 submitJob |
| typescript/src/runtime/local-job-store.ts | 本地 job 文件存储与记录结构 |
| typescript/src/runtime/run-outcome.ts | 提交标记证据与失败结果分类 |
| typescript/src/mint/write-session.ts | 写会话检查与 read-back first 规则 |
| typescript/src/mint/outcome-review-contracts.ts | outcome reviewer 的裁定与事件契约 |
| typescript/authoring/writes/SKILL.md | 写集成的完整编写规范 |