冪等：一次簽批，怎樣才不會變成兩次寫入

GembaOS 是企業 AI Agent 的治理執行平台：以政策判定權限、以綁定參數的單次放行令授權每一個動作、以可追責的簽署鏈記錄人的審批，部署於企業本地機房或私有 VPC。這篇講的是 Agent 造成實質損失之中最不起眼的一條路：把對的事做了兩次。

甚麼是冪等，Agent 為甚麼需要它

一個操作重複執行與只執行一次的結果相同，就叫冪等 (Idempotency)。Agent 需要它，是因為重試是日常而不是意外。呼叫逾時，用戶端重送；流量限制拒絕了這次嘗試，有東西把它重試；寫入已經送出、回應未到，程序就重啟了；模型收到含糊的工具結果，把同一步再規劃一次。

以上沒有一項是 Agent 行為不當，也沒有一項會被權限判定攔下。這個 Agent 本來就可以發出那個呼叫，它只是發了兩次。

冪等鍵應該從哪裡來

來自授權，不是來自這一次嘗試。整個設計決定就在這一句，而常見的錯誤是在呼叫之內產生這把鍵，例如用 UUID 或時間戳：重試時產生的是另一個值，目標系統當作新請求，於是寫下重複的一筆。這把鍵在兩次嘗試中必須相同，也就是說，它必須由比兩次嘗試都更早存在的東西推導出來。

GembaOS 採用第三種。這把鍵由 GembaOS 治理內核依審批單與工單組成，Agent 既不能選也不能改；而兩筆金額相同但批准不同的動作，因為批准不同，鍵也不同，不會互相吞掉。

受治理的執行實際保證了甚麼

「一次批准，最多一次寫入」這句話背後，是三個處於不同層次的機制。在 GembaOS 之內，放行令只能用一次：執行已批准的動作就會把它消耗掉，同一張放行令的第二次嘗試會被拒絕並記錄在案。在目標系統之內，冪等鍵令重送落地為同一筆寫入。至於兩者都沒有的系統，則由 Adapter 聲明自己的寫入靠甚麼保護：版本號、條件寫入，或在動作執行期間鎖住該筆記錄。

記錄上的那一行報告同時點名了兩樣東西：這次寫入是在哪一張放行令之下發生的，以及由審批單與工單推導出來的執行鍵是甚麼。日後讀這份記錄的審計人員，不需要相信「重送應該處理好了」——令它安全的那把鍵，就寫在記錄上。

批次處理呢

重複最貴的地方是批次，因為部分失敗之後，人的第一反應就是整批重跑。在 GembaOS 裡，一個批准可以覆蓋一張清單，但每一行在該批准之下仍然是自己的工單、自己的記錄。

三行成功，一行因為目標系統回覆該帳戶不存在而失敗，而該行明確寫著沒有執行任何動作。總數、逐行狀態與共用的批准都在記錄上，所以「到底哪幾行真的做了」這個問題，不必翻日誌就有答案。

小結

冪等不是 HTTP 用戶端的實作細節。對一個會寫入生產系統的 Agent 而言，它是授權的一部分：一個人簽了一次的決定，無論中間網絡發生甚麼，都應該變成一次寫入。判別任何 Agent 平台的實用問題很短——問它冪等鍵從哪裡來。如果答案是「由 Agent 產生」，那個平台沒有解決這個問題，只是把它移了位置。