
最近在维护一个每天定时跑的自动化任务:它会打开网站、采集状态、再按结果去写内容。跑得久了会发现,真正让人紧张的从来不是「这次有没有做对」,而是「重试一次会不会做两遍」。读操作重跑基本无害,写操作重跑一次就可能发出两篇文章、提交两次表单、覆盖一份别人刚改过的文件。
Agent 接的工具越多,这个问题越突出。模型侧的推理可以重来,外部世界的副作用不能。这篇文章把我在这个场景里沉淀下来的一套边界拆开讲:怎么给工具标副作用、怎么让计划和执行分离、幂等键怎么设计、审计日志最少要记什么、以及失败之后怎么回滚。不涉及任何具体产品的性能数字,命令和结构都可以直接照着改。
很多团队的工具清单只有「名字 + 参数 + 描述」,这不够。至少补一个 effect 字段,把工具分成四类:
等级 | 含义 | 典型例子 | 重试策略 |
|---|---|---|---|
| 无副作用,可任意重放 | 查询、读取页面、列目录 | 直接重试 |
| 只产出计划,不落地 | 生成 diff、构造待提交对象 | 直接重试,计划可丢弃 |
| 有副作用但带幂等键,重放收敛 | 按 key 写入、带唯一约束的创建 | 可重试,必须带同一 key |
| 有副作用且无法去重 | 发消息、发布内容、转账、删除 | 禁止自动重试,只能人工确认 |
关键是最后两类要分开。如果把它们混成「写操作」,要么你会因为怕重复而什么都不敢重试,要么会因为统一重试而制造事故。
一个可以直接用的最小结构:
tools:
- name: fetch_page
effect: read
timeout_s: 20
- name: build_diff
effect: plan
- name: upsert_record
effect: write_idempotent
idempotency_key: "task_id + target_id + content_sha256"
- name: publish_post
effect: write_unsafe
requires: human_confirmrequires: human_confirm 不是一句注释,要在执行器里真的拦一道:到达这个工具时暂停、把计划打印出来、等显式确认再放行。我在自己的自动化里,所有对外发布的动作都归在这一类;采集和草稿生成则全在前三类,所以掉登录、超时这些失败可以随便重跑,不会污染外部状态。
常见的假 dry-run 是这样:
def publish(title, body, dry_run=False):
if dry_run:
print(f"will publish: {title}") # 只打印了标题
return
api.publish(title, body)这没有价值,因为你验不了真正要写出去的内容。有效的做法是把「生成计划」和「执行计划」拆成两个独立函数,让 dry-run 和真实执行走同一个计划对象:
from dataclasses import dataclass
import hashlib, json
@dataclass(frozen=True)
class Action:
tool: str
effect: str
args: dict
key: str # 幂等键
def digest(self) -> str:
raw = json.dumps(self.args, sort_keys=True, ensure_ascii=False)
return hashlib.sha256(raw.encode()).hexdigest()[:16]
def plan(tasks) -> list[Action]:
"""纯函数:只读输入,不碰外部世界,可反复调用。"""
actions = []
for t in tasks:
args = {"title": t["title"], "body": t["body"]}
actions.append(Action(
tool="publish_post",
effect="write_unsafe",
args=args,
key=f"{t['task_id']}:{hashlib.sha256(t['body'].encode()).hexdigest()[:12]}",
))
return actions
def apply(actions, ledger, confirm=lambda a: True) -> list[dict]:
results = []
for a in actions:
if ledger.done(a.key): # 幂等闸门
results.append({"key": a.key, "status": "skipped_duplicate"})
continue
if a.effect in ("write_unsafe",) and not confirm(a):
results.append({"key": a.key, "status": "awaiting_confirm"})
continue
ledger.begin(a.key) # 先落"进行中"
try:
out = dispatch(a.tool, a.args)
ledger.commit(a.key, out) # 再落"完成"
results.append({"key": a.key, "status": "committed"})
except Exception as e:
ledger.fail(a.key, str(e)) # 不能留悬空状态
results.append({"key": a.key, "status": "failed", "error": str(e)})
return results这里有三个容易被忽略的点:
plan() 必须是纯函数。它不读时钟、不发请求、不改全局变量,否则 dry-run 和真实执行会算出不同的计划,你验的就不是你发的。apply() 里先 begin 再执行。崩溃在中间时,账本里留的是「进行中」而不是「什么都没发生」,重启后能明确知道要人工核对哪一条。Action 上,而不是整批任务。这样「前三个自动放行、第四个需要确认」这种混合策略才做得出来。dry-run 阶段就直接调用 plan(),把每个 Action 的 tool / effect / key / digest 打印或落盘比对。真实执行前再 plan() 一次,比较两次 digest 是否一致;不一致说明外部状态在中间变了,应该重新走一遍计划。
幂等键最常见的错误是用「当前时间」或「随机 UUID」——每次重跑都不同,等于没有。另一个极端是用「任务名」——同一任务第二天再跑会被误判成重复。
可用的组合是:key = 业务标识 + 目标标识 + 内容指纹
指纹前一定要做规范化:JSON 用 sort_keys=True、统一换行符、去掉尾部空白、把 Markdown 里的临时时间戳剔除。否则同一份内容因为一个空格就换了键,去重形同虚设。
还要区分「去重」和「幂等」:
客户端超时是最麻烦的情形:请求发出去了,响应没回来,你不知道对方写没写。这时不要盲目重试,正确姿势是带同一个 key 重试一次,并让服务端按 key 收敛。如果服务端不支持,就退回到查询:先查目标状态,再决定是否补发。我的自动化里对「发布」这类动作就是这么做的——提交后先去详情页确认是否已存在,确认没有才补,绝不因为「没看到成功提示」就再发一遍。
出问题后能不能复盘,全看日志记了什么。下面这几个字段是我认为不能再砍的下限:
{"ts":"2026-11-16T09:12:03+08:00","run_id":"2026-11-16","step":4,"tool":"publish_post","effect":"write_unsafe","key":"2026-11-16:article:9c1a42","args_digest":"9c1a428a","status":"committed","attempt":1,"elapsed_ms":812,"result_ref":"article/2784475","error":null}字段 | 为什么必须有 |
|---|---|
| 能把一次运行的全部动作串起来,定位「第几步开始不对」 |
| 判断是否重复、是否内容被中途改过 |
| 事后统计「这次到底碰了几个不可重试的写操作」 |
| 只允许 |
| 区分首次失败和重试失败 |
| 外部产生的实体 ID 或链接,回滚和补录都要靠它 |
| 只记错误类型和消息,不记 token、cookie、正文全文 |
两个纪律:
args_digest 回查本地草稿。有了这份日志,「今天到底发了什么」不再靠猜:把 status=committed 且 effect=write_unsafe 的行过滤出来就是当日对外动作清单;和站点实际列表比对,差集就是需要人工核对的部分。这也顺带解决了另一个常见困扰——按周结算的平台,提交和到账之间有时延,只要日志里明确记了「已提交」和「结果链接」,就不会因为分数没立刻变化而重复去发一遍。
层级 | 能回滚什么 | 做法 |
|---|---|---|
计划层 | 还没执行的动作 | 直接丢弃 |
本地层 | 文件、草稿、账本状态 | 改动落在独立工作区,一次提交, |
外部层 | 已发布的内容、已发出的消息 | 通常无法撤回,只能删除/更正 + 留痕说明 |
所以工程上的重点不是「怎么撤」,而是把不可逆动作尽量往后推:采集、生成、校验、写草稿全放在本地层,只有最后一步跨到外部层。跨出去之前做一次完整校验——内容长度、关键段落、指纹与草稿一致、当日是否已提交过。我在发文场景里会做正文的逐字节比对,就是为了防止编辑器把内容改写后还照发。
对确实跨出去的动作,把 result_ref 记牢,需要更正时能直接定位,不用靠标题去搜。
plan() 两次,断言两次 digest 完全一致。Action 连续 apply() 两次,断言第二次全部返回 skipped_duplicate,且外部实体数量不变。commit 前抛异常,断言账本状态是 failed 而不是悬空的 begun。write_unsafe 的确认回调设为恒 False,断言日志里是 awaiting_confirm,且外部零变更。plan(),断言 key 和 args_digest 都变了。这七条跑通,才敢让任务进入无人值守。
Agent 工程化里,模型能力决定上限,边界设计决定下限。把工具按副作用分级、计划与执行分离、幂等键由业务语义生成、审计记指纹不记正文、不可逆动作尽量后置,这套东西不复杂,但能让你在定时任务跑第 30 天的时候还敢让它自己继续跑。
顺便留一个开放问题:如果规则文件(AGENTS.md)或工具清单本身被改了,怎么自动发现 Agent 的行为悄悄回退了?这比单次执行的幂等更难,欢迎在评论区聊聊做法。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。