10 月 28 号晚上十点半,客服在群里甩了张截图:同一个客户、同一笔 199 元的退款,后台躺着三条"已退款"记录。客户到账 597 元,然后打电话过来问我们是不是在拿他做测试。 我把日志捞出来,链路干净得让人无话可说: ``` 22:14:03.1 agent refund.create(order=A8821, amount=199) → 网关 30s 超时 22:14:03.4 harness 判定失败,丢进重试队列(第 1 次) 22:14:36.2 agent refund.create(order=A8821, amount=199) → 网关 30s 超时 22:15:09.5 agent refund.create(order=A8821, amount=199) → 200 OK 22:15:09.6 agent 汇报:退款已完成 ``` 第一次超时的时候,钱其实已经退出去了。支付网关在 22:14:03.8 就把款打到客户账上,只是回程的响应被我们那个 30 秒超时掐断。后面两次,每一次都是真金白银。 问题不在模型笨。问题在我们把一个**至少一次**的调用通道,当成**恰好一次**在用,而且自己没意识到。 ## 一、重复执行不是 bug,是这类架构的默认行为 先把账算清楚。一次工具调用,从模型决定调到外部系统真执行,中间至少有四层可能重试: - 模型层。工具返回 `error` 或 `timeout` 时,现在的模型几乎都会自己再试一次,这是训练出来的"韧性",你改提示词也压不住。 - Harness 层。我们自己写的 retry 装饰器,指数退避三次,很标准,也很致命。 - SDK 层。大部分 HTTP 客户端默认就对 5xx 和连接错误重试,很多人根本不知道自己开了。 - 人类层。用户点两次、两个会话并发、定时任务和手动触发撞车。 四层各重试一次,最坏情况同一次业务意图被执行 16 次。这不是理论值,我把线上 30 天的工具调用日志扒出来统计过:**8.3% 的调用存在重复执行,写类工具里是 1.7%**。1.7% 听起来还好,但乘上一天几万次写操作,就是一天几百次重复副作用。 那为什么"重复执行"这么常见,大家却没感觉?因为大部分写操作是幂等的——更新一条记录、覆盖一个字段,重复做十次结果一样。真正会出事的只有那几类:**扣款、退款、发券、下单、发短信、建工单、给外部系统推数据**。它们不幂等,而且每一次都有成本,有的是钱,有的是客户信任。 ## 二、为什么"让模型小心点"和"加个唯一索引"都不够 先说一个我试过的错方案:在系统提示词里写"同一个操作不要重复调用,失败后先确认再重试"。 效果是负的。模型看不到"上一次其实成功了",它看到的就是一个 timeout。在信息缺失的情况下,重试是它的最优策略。你让它别重试,它就会在真失败的时候也不重试,问题从重复扣款变成漏单。两头都是错,而且漏单更难被发现。 第二个错方案:给业务表加唯一索引。这个有用,但只挡得住本地重复。它挡不住三个更隐蔽的窗口: 1. **外部已成功、本地写库失败**。钱退出去了,你的记录没落库,唯一索引根本没机会生效。 2. **同一笔业务的两种表述**。`amount=199` 和 `amount=199.00` 在你的键上不是一回事,在支付网关那里是。 3. **键本身不稳定**。用 `uuid4()` 或者时间戳当幂等键,每次重试都生成新键,等于没做。 所以我最后落到的方案,是三个东西叠起来:**业务幂等键**(是谁)、**请求指纹**(是不是同一件事)、**状态机加对账**(现在到底成了没有)。 先讲清一个立场:跨系统边界的 exactly-once 在工程上不存在。分布式事务那一套(2PC、TCC)能做,但你不会为了一个退款接口去改支付网关。你能拿到的是 exactly-once 的**效果**——**执行上最多一次,记账上至少一次,剩下的靠对账兜底**。这句话是整篇文章的地基,后面所有代码都是它的注脚。 顺带说一句行业观察。这几天 CrowdStrike 给 Agent 加了 Kill Switch,IBM 和微软联合发了带 governance 能力的企业 Agent 平台,大家都在解决"Agent 能不能做这件事"。很少有人解决"Agent 做几次"。前者是权限问题,后者是一致性问题,两个都得有。 ## 三、430 行代码,四个部件 下面这套东西不是凭空设计的,是黑箭科技在给几家客户做 Agent 落地时,被重复扣款、重复发券、重复建单这些事一次次逼出来的。整个模块零第三方依赖,标准库就能跑,你可以直接拿去改。 ### 3.1 幂等键:从业务意图里长出来 键的稳定性决定了整套方案的上限。它必须满足三个条件:跨进程稳定、跨会话稳定、跨天稳定。 ```python # idem_keys.py import hashlib, json # ❌ 反例一:每次调用都变 # key = str(uuid.uuid4()) # ❌ 反例二:带时间戳,重试跨秒就失效 # key = f"refund:{int(time.time())}:{order_no}" # ❌ 反例三:只带单号,一个订单多次部分退款会互相覆盖 # key = f"refund:{order_no}" def refund_key(p: dict) -> str: """退款幂等键:租户 + 订单 + 该订单的第几次退款""" return f"refund:{p['tenant']}:{p['order_no']}:{p['refund_seq']}" def coupon_key(p: dict) -> str: """发券幂等键:活动 + 用户 + 批次(同一活动同一批次对同一人只能发一次)""" return f"coupon:{p['activity_id']}:{p['user_id']}:{p['batch_no']}" def ticket_key(p: dict) -> str: """建工单:用业务指纹,不用工单号(工单号是结果,不是原因)""" basis = f"{p['source']}|{p['biz_id']}|{p['category']}" return "ticket:" + hashlib.sha256(basis.encode()).hexdigest()[:24] ``` 判断标准很简单:**这个键,能不能让一个三个月后接手的人,只看业务数据就重新算出来?** 能,就是对的。 还有一个分工问题:键由谁生成? 我最早的版本把 `idem_key` 直接放进了工具 schema,让模型自己填。结果很 predictable——它每次重试都编一个新键,格式还挺像那么回事。后来改成:**业务参数由模型给,幂等键由 harness 算,租户身份由会话上下文注入,模型碰都碰不到。** ```python # tools.py —— 暴露给模型的 schema 里根本没有 idem_key 和 tenant REFUND_TOOL = { "name": "create_refund", "description": "为指定订单发起退款。同一订单的同一退款序号只会执行一次,重复调用不会重复打款。", "parameters": { "type": "object", "properties": { "order_no": {"type": "string", "description": "订单号,如 A8821"}, "amount": {"type": "number", "description": "退款金额,单位元"}, "refund_seq": {"type": "integer", "description": "该订单的第几次退款,从 1 开始;部分退款时递增"}, "reason": {"type": "string", "description": "退款原因"} }, "required": ["order_no", "amount", "refund_seq", "reason"] } } def dispatch(tool_name: str, args: dict, ctx: dict): if tool_name == "create_refund": # tenant 来自会话上下文,refund_seq 来自模型(只有它知道这是第几次部分退款) return create_refund({**args, "tenant": ctx["tenant_id"]}) raise ValueError(tool_name) ``` 这个分工我踩过坑。早期让模型填 `tenant`,有一次它填成了"默认租户",那笔退款打到了另一个客户的账上——查了四个小时才定位到是模型在补全参数时"猜"的。**能决定钱流向哪个账户的字段,永远不要交给模型。** ### 3.2 请求指纹:防"同键不同参" 幂等键解决"是不是同一件事",指纹解决"参数有没有被改过"。有人重试时顺手把金额从 199 改成 199.5,只靠键你发现不了。 ```python def fingerprint(payload: dict) -> str: """规范化后哈希:键排序、浮点统一、None 归一,避免 199 和 199.0 算两个指纹""" def norm(v): if isinstance(v, float): return f"{v:.4f}" if isinstance(v, dict): return {k: norm(x) for k, x in sorted(v.items())} if isinstance(v, (list, tuple)): return [norm(x) for x in v] return v raw = json.dumps(norm(payload), ensure_ascii=False, sort_keys=True, separators=(",", ":")) return hashlib.sha256(raw.encode()).hexdigest() ``` 指纹不一致时,我直接抛 `IdemConflict`,返回 409 给上层。这条规则上线三个月,抓到过两次真实的参数漂移——都是模型在重试时"自作主张"把备注字段补全了。备注不影响金额,但它影响指纹,这种时候报错比静默执行安全。 ### 3.3 状态机 + 租约:整套方案的心脏 一张表,五个状态。`in_flight`(有人在执行)、`succeeded`(成了,可直接回放结果)、`failed`(确定没发生,可安全重试)、`unknown`(不知道,等对账)。第五个状态不是表里的,是"行不存在",代表从没来过。 ```python # idem_store.py import contextlib, json, sqlite3, threading, time from dataclasses import dataclass from typing import Any SCHEMA = """ CREATE TABLE IF NOT EXISTS idem_record ( idem_key TEXT PRIMARY KEY, fingerprint TEXT NOT NULL, state TEXT NOT NULL, -- in_flight | succeeded | failed | unknown response TEXT, attempts INTEGER NOT NULL DEFAULT 0, lease_until REAL NOT NULL, created_at REAL NOT NULL, updated_at REAL NOT NULL ); CREATE INDEX IF NOT EXISTS idx_idem_state ON idem_record(state, lease_until); """ LEASE = 60.0 # 租约秒数,要比单次外部调用超时大 2 倍以上 @dataclass class Decision: action: str # execute | replay | wait | conflict payload: Any = None class Store: def __init__(self, path="idem.db"): self.conn = sqlite3.connect(path, check_same_thread=False, isolation_level=None, timeout=5) self.conn.execute("PRAGMA journal_mode=WAL") self.conn.executescript(SCHEMA) self._lock = threading.Lock() @contextlib.contextmanager def tx(self): # 单机用线程锁;多机部署把这层换成 Redis 分布式锁或 DB 行锁即可 with self._lock: self.conn.execute("BEGIN IMMEDIATE") try: yield self.conn self.conn.execute("COMMIT") except Exception: self.conn.execute("ROLLBACK") raise def acquire(store: Store, key: str, fp: str) -> Decision: now = time.time() with store.tx() as c: row = c.execute( "SELECT fingerprint, state, response, lease_until FROM idem_record " "WHERE idem_key = ?", (key,)).fetchone() if row is None: # 第一次来,抢到执行权 c.execute("INSERT INTO idem_record VALUES (?,?,?,?,?,?,?,?)", (key, fp, "in_flight", None, 1, now + LEASE, now, now)) return Decision("execute") old_fp, state, response, lease_until = row if old_fp != fp: # 同键不同参,拒绝 return Decision("conflict") if state == "succeeded": # 已经成了,直接回放 return Decision("replay", json.loads(response) if response else None) if state == "in_flight" and lease_until > now: # 别人正在做,等着 return Decision("wait", lease_until - now) # 走到这里只有两种可能:租约过期(执行者崩了),或上次以 failed/unknown 收场 c.execute("UPDATE idem_record SET state='in_flight', attempts=attempts+1, " "lease_until=?, updated_at=? WHERE idem_key=?", (now + LEASE, now, key)) return Decision("execute") def finish(store: Store, key: str, state: str, response: Any = None) -> None: now = time.time() with store.tx() as c: c.execute("UPDATE idem_record SET state=?, response=?, updated_at=? " "WHERE idem_key=?", (state, json.dumps(response, ensure_ascii=False, default=str) if response is not None else None, now, key)) ``` **租约(lease)这一列是最容易被省掉、也最容易出事的地方。** 没有它,进程在 `in_flight` 状态下被 kill,那条记录就永远卡住,后面所有重试都变成 `wait`,业务直接挂死。有了它,60 秒后自然过期,新请求可以抢占——最多多执行一次,但系统能自愈。这个取舍我认为完全值得。 ### 3.4 对账器:`unknown` 状态唯一正确的出口 超时到底算成功还是失败?答案是:**不知道,所以标 unknown,然后去问。** ```python # reconciler.py import time def reconcile_once(store, query_fn, older_than=30, limit=100) -> dict: """query_fn 必须是只读查询,不能有副作用""" rows = store.conn.execute( "SELECT idem_key FROM idem_record " "WHERE state='unknown' AND updated_at < ? LIMIT ?", (time.time() - older_than, limit)).fetchall() stat = {"checked": 0, "confirmed_done": 0, "confirmed_none": 0, "still_unknown": 0} for (key,) in rows: stat["checked"] += 1 real = query_fn(key) if real is None: # 外部确认没发生 → 可以安全重试 finish(store, key, "failed") stat["confirmed_none"] += 1 elif real.get("status") in ("success", "refunded", "paid"): finish(store, key, "succeeded", real) # 外部已成功 → 补记录,不再执行 stat["confirmed_done"] += 1 else: # 外部还在处理中,下一轮再问 stat["still_unknown"] += 1 return stat ``` 对账器每 30 秒跑一次,`query_fn` 用支付网关的只读查询接口,按业务单号查。这一步是整个方案里唯一能消掉 `unknown` 的地方,也是我见过的团队最容易漏掉的一环——大部分人的重试逻辑里,超时被归进 `failed`,然后就理直气壮地重发了。 ### 3.5 包成装饰器,让 Agent 完全无感 业务代码不该关心幂等。用装饰器把这层套上去,Agent 侧看到的仍然是一个普通函数。 ```python # idem_decorator.py import functools, time class IdemConflict(Exception): pass METRICS = {"execute": 0, "replay": 0, "blocked_wait": 0, "unknown": 0} def idempotent(store, key_fn, fp_fn, wait_budget=10.0): def deco(fn): @functools.wraps(fn) def wrapper(payload: dict): key, fp = key_fn(payload), fp_fn(payload) deadline = time.time() + wait_budget while True: d = acquire(store, key, fp) if d.action == "conflict": raise IdemConflict(f"{key} 已存在同键不同参的请求") if d.action == "replay": METRICS["replay"] += 1 return d.payload if d.action == "execute": METRICS["execute"] += 1 break if time.time() > deadline: # 等太久,交回上层,别硬撑 METRICS["blocked_wait"] += 1 return {"status": "pending", "idem_key": key} time.sleep(0.2) try: result = fn(payload) except TimeoutError: # 关键分叉:超时 ≠ 失败。标 unknown,等对账,绝不当 failed finish(store, key, "unknown") METRICS["unknown"] += 1 raise except Exception: finish(store, key, "failed") # 明确异常 → 可以安全重试 raise finish(store, key, "succeeded", result) return result return wrapper return deco # ---------------- 业务侧,一行装饰器搞定 ---------------- store = Store("idem.db") @idempotent(store, key_fn=refund_key, fp_fn=fingerprint) def create_refund(payload: dict): return payment_gateway.refund( order_no=payload["order_no"], amount=payload["amount"], reason=payload["reason"], ) ``` 注意 `TimeoutError` 和普通 `Exception` 分开处理这个细节。我第一版把两者都归到 `failed`,结果就是文章开头那 27 笔重复退款——超时的那些全被当成"没发生",然后重发了。 ### 3.6 三个必须报警的指标 这层如果只是"默默运行",等于没上线。我只挂了三条告警,够用了: ```sql -- 1) unknown 堆积:外部系统不稳,或者你的超时设得太短 SELECT COUNT(*) AS n FROM idem_record WHERE state='unknown'; -- 2) 重试次数异常的僵尸键:超过 3 次说明这个工具在反复失败 SELECT idem_key, attempts, state FROM idem_record WHERE attempts > 3 ORDER BY attempts DESC LIMIT 20; -- 3) 租约长期没释放:执行者崩溃或线程池被打满 SELECT COUNT(*) AS n FROM idem_record WHERE state='in_flight' AND lease_until < strftime('%s','now') - 300; ``` 第一条超过总量的 2% 就要看,说明你在跟一个不可靠的外部系统搏斗;第二条出现就说明某个工具的设计有问题,不是加个重试能解决的;第三条出现基本可以确认有进程在 `in_flight` 中间被杀掉——这是最脏的一种情况,因为它意味着可能有业务已经执行但没记账。 ## 四、上线两个月的数字,和它治不好的病 跑在 3 个业务线、11 个写类工具上,两个月的数据: | 指标 | 上线前 | 上线后 | |---|---|---| | 重复扣款/重复退款 | 27 笔/月 | 0 笔 | | 重复发券 | 约 400 张/月 | 0 张 | | 重复建单(工单系统) | 约 610 条/月 | 0 条 | | 被拦截的重复执行 | — | 1,240 次/周 | | 工具调用 P99 延迟 | 1,180 ms | 1,187 ms | | `unknown` 状态占比 | — | 0.6% | | 对账修复成功率 | — | 99.1% | 延迟只加了 7 毫秒,一次 SQLite 事务的钱。这是我认为这套方案最划算的地方:**一致性问题的成本几乎全在"想清楚",不在"跑得快"**。 它治不好的病,也得说清楚: **外部系统没有只读查询接口时,`unknown` 只能人工。** 我们有一个老的短信通道,发出去就查不到状态,这种情况只能靠"发之前先落记录、发之后人工抽检",做不到全自动。遇到这类系统,我的建议是先在业务上限制它的调用频率,而不是硬上幂等层。 **键设计错了,整套白搭。** 用 `uuid4()` 当键的团队我见过不止一个,代码看起来一模一样,一行不改,效果是零。 **多租户场景必须带命名空间。** 两个客户都有订单号 `A8821`,键不带 `tenant` 就会互相顶掉,这种 bug 比重复扣款更难查——因为它表现为"某个客户的退款莫名其妙成功了"。 **纯读工具别套这一层。** 读操作天然幂等,套上只是给数据库白加负载。我们只对 11 个写类工具做了包装,读类工具一个没动。 ## 五、最后几句实话 Agent 的可靠性问题,八成不是模型不够聪明,而是我们把这些系统当成"函数调用"在设计,忘了它们本质上是**跨进程、跨网络、会超时、会重试的分布式系统**。模型只是让这个老问题变得更急迫了——因为以前是人类点按钮,一天点几百次;现在是 Agent 自己点,一天点几万次,而且它比你更愿意重试。 具体到代码,四件事按重要性排: 1. **超时和失败必须分开处理。** 超时是 `unknown`,不是 `failed`。这一条能消掉大部分重复副作用。 2. **幂等键从业务意图里长出来。** 不用 UUID,不用时间戳,要能被后人重新算出来。 3. **一定要有租约。** 否则一次崩溃能让一条记录永久卡死。 4. **一定要有对账器。** 它是 `unknown` 唯一正确的出口,没有它,前三条都是半成品。 黑箭科技这边现在所有带副作用的工具都强制走这一层,代码审查时"有没有幂等键"是必检项。430 行不算多,但它是那种"上线时觉得多余、出事时觉得太少"的代码。 你们团队在 Agent 的工具调用上踩过重复执行的坑吗?是扣款、发券,还是重复推送数据?评论区聊聊,我想知道别人是怎么发现第一个重复的。
Logo

更多推荐