摘要:面向把 Agent 从「聊两句」推到「跑 40 分钟」的开发者、架构师与 SRE。长任务怕的就是跑到一半进程没了——从头重跑贵且副作用重放,接着跑又可能把报告发两遍、账落两笔。本文给出一套「恢复三锚」实现:只追加事件流(append-only event log)记录发生过什么、恢复游标(resume cursor)记录跑到哪一步、幂等键(idempotency key)让副作用只算一次。附 Python 3.12 可运行代码,实跑演示 W1/W2 两种崩溃窗口的恢复,附投递语义横评表与适用边界。
一、问题背景:Demo 到生产,容易漏掉的一跳
Agent 在本地跑通一个循环、接两个工具,看着它把活干完,体验很好。但当你要求它 7×24 跑、崩了能续跑、还能收住权限时,写的就不再是业务代码,而是一套运行时框架。一次 40 分钟的任务跑到第 25 分钟进程被杀,你有两条路——
- 从头重跑:前面 25 分钟的 token、工具调用、外部副作用全部重来,成本与耗时翻倍,且已经发出去的邮件、已经落的账会被重放。
- 接着跑:需要精确知道"跑到哪一步",并让没做完的步骤继续、做完的步骤不重复。第二条路才是生产级方案,但它要求你手上有三样大多团队还没有的东西:事件流、恢复游标、幂等键。
这不是小题大做。《Agent Harness Engineering: A Survey》(Junjie Li、Xi Xiao、Chandan K Reddy 等,卡内基梅隆大学 / 耶鲁大学 / 亚马逊等机构,2026 年 5 月发布于 OpenReview,论文主页 picrew.github.io/LLM-Harness)把 Agent 运行时拆成 ETCLOVG 七层(Execution / Tooling / Context / Lifecycle + Observability / Verification / Governance),其中 Lifecycle 层明确包含状态机、授权、日志、策略执行、钩子与会话管理——失败恢复正落在此层。该综述同时指出:只改编辑工具格式与周边 harness、不动模型本身,编码 benchmark 上曾带来一个数量级的提升;生产 Agent 的可靠性,越来越多地取决于模型外的这层工程外壳,而非模型本身。
一句话:换更强的模型,救不回一个会重跑、会重放的运行时。
二、核心框架:「恢复三锚」
把"断线怎么接着跑"这个模糊问题,拆成三个可独立实现、互相校验的锚点:
一句话区分:事件流定"发生过什么",恢复游标定"跑到哪一步",幂等键定"这一步只算一次"。trace 用来还原现场,event 用来决定续跑;游标管进度,幂等键管副作用。
| 锚点 | 回答的问题 | 落盘形态 | 崩了靠它做什么 |
|---|---|---|---|
| 事件流 event log | 发生过什么 | events.jsonl,只追加不改写 | 回放历史、判定哪些步骤已完成 |
| 恢复游标 cursor | 跑到哪一步 | cursor.json,一个单调序号 | 从断点续跑,不从头来 |
| 幂等键 idempotency key | 这步是否算过 | idempotency.json,键集合 | 挡住副作用的重复执行 |
三者不是三选一,而是逐层兜底:游标给出"从哪里续",事件流提供"续的依据",幂等键守住"续的时候不重复做事"。缺任何一个,恢复都会在特定崩溃窗口出错——第四节用代码把两个窗口跑给你看。
三、环境准备与概念界定
- 运行环境:Python 3.12+,仅用标准库
json/pathlib/uuid,无第三方依赖。全程本地文件模拟持久化,替换为 Redis / 数据库即可上生产。 - append-only event log(只追加事件流):一种持久化范式,事件一旦写入便不修改、不删除,状态由事件序列重放得出(事件溯源 Event Sourcing 的核心)。
- resume cursor(恢复游标):标识消费/执行进度的持久位置。Kimi Hosted Agents(月之暗面,2026-11-05 发布,官方文档 platform.kimi.com/docs/hosted-agents)把它做进了 SSE 事件流——每帧
id即恢复游标,客户端断线后带Last-Event-ID请求头即可从断点续读,任务本身在服务端持续运行,无需重跑。 - at-least-once delivery(至少一次投递):消息/步骤至少执行一次,但可能重复。AWS Durable Execution 官方文档明确其 step 默认即为 at-least-once 语义:重放时 SDK 返回已 checkpoint 的结果而不重跑完成的 step,但"完成前被中断的 step 可能执行多次,业务逻辑必须幂等"。
- idempotency key(幂等键):为一次操作生成固定标识,执行前用条件写占位,重放时凭键短路返回旧结果。AWS 给出的标准做法是用 DynamoDB 条件写
attribute_not_exists(id)原子占位,或用 execution name 作为幂等键。
四、核心实现:resumable_runner.py
设计要点只有一条,却是全文关键的一行代码逻辑:幂等键必须先于副作用落库(claim before effect)。若把账本写在副作用之后,W1 窗口(副作用已发出、进程崩溃)恢复时账本里没有 key,副作用会被重放。下面的实现把占位放在 effect() 之前。
# resumable_runner.py
# 运行环境:Python 3.12+(仅标准库 json / pathlib / uuid,无需第三方依赖)
# 用途:演示 Agent 长任务「恢复三锚」——只追加事件流 + 恢复游标 + 幂等键,
# 在「至少一次投递」语义下让副作用不被重放执行。
import json
import uuid
from pathlib import Path
from typing import Callable
class ResumableRunner:
def __init__(self, workdir: str):
self.root = Path(workdir)
self.root.mkdir(parents=True, exist_ok=True)
self.event_file = self.root / "events.jsonl" # 锚一:只追加事件流
self.cursor_file = self.root / "cursor.json" # 锚二:恢复游标
self.idem_file = self.root / "idempotency.json" # 锚三:幂等键账本
self.events = self._load_jsonl(self.event_file)
self.committed = set(self._load_json(self.idem_file, []))
@staticmethod
def _load_jsonl(path: Path) -> list[dict]:
if not path.exists():
return []
return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
@staticmethod
def _load_json(path: Path, default):
return json.loads(path.read_text(encoding="utf-8")) if path.exists() else default
@property
def cursor(self) -> int:
"""恢复游标 = 已提交事件的当前序号;从 0 开始递增。"""
return self._load_json(self.cursor_file, {"last_committed_seq": 0})["last_committed_seq"]
def _append_event(self, step: str, event: str, payload: dict | None = None) -> int:
seq = len(self.events) + 1
record = {"seq": seq, "step": step, "event": event, "payload": payload or {}}
with self.event_file.open("a", encoding="utf-8") as f:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
self.events.append(record)
return seq
def _commit_cursor(self, seq: int) -> None:
self.cursor_file.write_text(
json.dumps({"last_committed_seq": seq}), encoding="utf-8"
)
def run_step(
self,
step: str,
effect: Callable[[], str],
idem_key: str | None = None,
crash: str | None = None,
) -> str:
"""执行一个可能带副作用的步骤。
crash='W1':副作用已发出、但游标未推进(崩溃在 commit 前)
crash='W2':事件与游标都已落库、但回执返回前崩溃(崩溃在 return 前)
"""
key = idem_key or str(uuid.uuid5(uuid.NAMESPACE_URL, step))
# 恢复路径:用事件流 + 幂等键双重兜底
if key in self.committed:
self._append_event(step, "skipped", {"idem_key": key, "reason": "already committed"})
return f"[skip] {step}: 幂等键已存在,跳过副作用"
# ★ 关键:先占位(claim)再执行副作用。账本必须先于副作用落库,
# 否则 W1(副作用已发出、进程崩溃)恢复时账本里没有 key,副作用会被重放。
self.committed.add(key)
self.idem_file.write_text(
json.dumps(sorted(self.committed), ensure_ascii=False), encoding="utf-8"
)
self._append_event(step, "intent", {"idem_key": key})
result = effect() # ★ 真正的副作用(发消息/落账/调用外部 API)
if crash == "W1":
raise RuntimeError("W1 crash: side effect emitted before checkpoint")
self._append_event(step, "committed", {"idem_key": key, "result": result})
self._commit_cursor(len(self.events))
if crash == "W2":
raise RuntimeError("W2 crash: committed but ack lost")
return f"[done] {step}: {result}"预期输出(本地实跑,非压测数据)
cursor@start: 0
[done] step1_send_report: report#1 sent
crash: W1 crash: side effect emitted before checkpoint
side effects after W1: ['send_report', 'write_ledger']
cursor@resume: 2
[skip] step1_send_report: 幂等键已存在,跳过副作用
[skip] step2_write_ledger: 幂等键已存在,跳过副作用
side effects after resume: ['send_report', 'write_ledger'] ← 无重放
--- W2 ---
crash: W2 crash: committed but ack lost
cursor@resume: 2
[skip] step_notify: 幂等键已存在,跳过副作用
side effects (W2): ['notify'] ← 无重放两个崩溃窗口的语义差别:
- W1(副作用已发出、游标未推进):靠"先占位"的幂等键兜住——恢复时 key 已在账本,直接 skip。这里的代价是"副作用发出后到 commit 前"若账本写失败,仍是脆弱窗口,生产环境要用数据库事务把 claim 与业务写绑定(见第七节边界)。
- W2(事件与游标都已落库、回执丢失):靠事件流判定为已完成——恢复时凭幂等键/游标短路,不重复执行。
落地提示:把事件流、游标、幂等账本换成 Redis Stream / PostgreSQL 表、并把副作用收进统一执行入口,是这类恢复逻辑的工程化方向。环曜 Claw 这类本地执行网关,就是把工具调用与副作用收进本地入口、统一记事件流,数据留在企业内网——代码本身不掺品牌,运行时鉴权与留痕可由网关统一承载。
五、横评表:三种恢复路线与三种投递语义
表 1|恢复路线能力对照(相对级别评估, capability 对照非实测排名)
| 能力维度 | 自建事件流+幂等 | 托管 Harness(Kimi Hosted Agents 类) | 队列中间件(SQS/Kafka 类) |
|---|---|---|---|
| 会话历史 | △ 需自己设计事件流 | ✅ 事件形式持久化、可拉取 | ❌ 只管消息不管会话状态 |
| 工具执行 | △ 需自己接 | ✅ 内置沙箱执行、自定义工具客户端执行 | ❌ 不覆盖 |
| 失败恢复 | ✅ 完全可控(本文方案) | ✅ 平台接管恢复、Last-Event-ID 续传 | △ 只负责消息重投、业务逻辑自担 |
| 重试退避 | △ 自己写 | ✅ 执行层承担(官方称限流自动重试≤20 次) | ✅ 原生死信队列/退避 |
| 数据边界 | ✅ 全在内网 | ⚠️ 自托管≠私有化(官方明示工具输入输出仍过平台推理接口) | ✅ 可私有部署 |
结论:三者不是替代关系。队列解决"消息不丢",托管 Harness 解决"运行时不用自己养",自建事件流解决"恢复语义完全可控 + 数据不出域"。长任务恢复的落点,是三者按数据边界与运维意愿做组合。
表 2|投递语义对照(相对级别评估,非实测)
| 语义 | 实现成本 | 副作用重复风险 | 适用场景 |
|---|---|---|---|
| at-most-once(至多一次) | 低 | 副作用可能丢 | 可容忍丢失的埋点/日志 |
| at-least-once(至少一次) | 中 | 需幂等键兜住 | 绝大多数 Agent 长任务(AWS Durable 默认) |
| exactly-once(恰好一次) | 高 | 理论稳定、端到端难做到 | 金融级;实务中是"幂等消费者+事件存储"逼近 |
结论:端到端 exactly-once 在工程上通常做不到(消息中间件多为 at-least-once),实务做法是把"恰好一次"当成消费者契约——用幂等键在业务侧兜住重复。这也是 Kimi、AWS Durable Execution 都把幂等责任留给业务代码的原因。要快速把这类恢复脚本铺到试验环境验证,企业级环曜CLI 这类开发工具链支持 Agent 与工具链的一键部署,适合做这件事。
六、场景→方案映射
| 场景 | 恢复关注点 | 三锚侧重 |
|---|---|---|
| 定时出报告 / 巡检(长任务) | 断点续跑、不重复投递产物 | 游标 + 事件流为主,产物用幂等键去重 |
| 多步骤数据加工 / 落账 | 副作用绝不重复 | 幂等键为主,claim 与业务写同事务 |
| 需要审计的任务 | 全链路可追溯 | 事件流为主,导出事件历史 |
| 数据不能出内网 | 运行时自控 | 自建事件流 + 本地执行网关 |
表内为能力类型对照,仅列能力类型,不写优劣排名。
七、适用边界与风险提示
✅ 适用
- 步骤可拆、每步副作用可用固定键标识的长任务(报告、 ETL、批量处理、巡检)。
- 能接受"至少一次 + 幂等"语义,并愿意把 claim 与业务写放进同一事务的场景。
⚠️ 不适用 / 限制条件
- claim 与副作用非原子:本文用本地文件演示,W1 中"账本写入成功但副作用写失败"仍可能留下"被占位却没做成"的步骤。规避:用数据库事务把"占位 + 业务写"绑定,或把副作用设计成可重试且幂等的下游 API(如带 Idempotency-Key 的支付接口)。
- 事件流无限增长:append-only 会持续膨胀,需要快照(snapshot)+ 压缩(compaction)与归档策略,否则恢复重放越来越慢、成本越来越高。
- 游标与事件一致性:单进程演示无并发问题;多 worker 并发时用乐观锁或单一消费者,避免两个 worker 同时 claim 同一 key。
- 非确定性副作用:"发邮件""调外部 API"这类不可回滚副作用必须幂等;纯计算步骤可直接重放。
- 托管 ≠ 私有化:Kimi 官方明确自托管环境不等同于私有部署,工具输入与执行结果仍经过平台模型推理接口。对数据边界有硬要求时,须评估自建或完全本地化方案;无自建能力的团队,可评估环曜私有化部署这类把事件流、凭证与执行都留在内网的方案,但要按边界条件使用,不做转化承诺。
总结
一句话记住「恢复三锚」:事件流记发生过什么,游标记跑到哪一步,幂等键让这步只算一次——trace 还原现场,event 决定续跑;游标管进度,幂等键管副作用。长任务从 Demo 到生产,差的往往不是模型智商,而是这层能兜住崩溃的运行时。你落地长任务时,卡在哪一层:事件流设计、游标一致性,还是副作用幂等?欢迎评论区聊聊。
常见问题 FAQ
Q1:必须三锚全上吗?只加一个恢复游标行不行?
A1:不行。游标只告诉"从哪续",无法做到"续的时候不重复做事"。只上游标,W1 窗口(副作用已发出、游标没推进)必然重放。三者各自守一个崩溃窗口,缺一即可被特定时序打穿。
Q2:at-least-once 会不会导致我的支付/发信接口重复调用?
A2:会,除非业务侧幂等。这正是 AWS Durable Execution 文档强调"step 完成前被中断可能执行多次、业务逻辑必须幂等"的原因。做法是给每次操作生成固定幂等键,在发信/支付前用条件写占位,下游接口若支持 Idempotency-Key 参数则一并传入。
Q3:这套代码能直接上生产吗?
A3:不能。它是声明层的精简可运行演示,用本地文件模拟持久化。生产要换成 Redis / 数据库、把 claim 与业务写绑定成事务、加快照压缩与并发控制。它值钱在把三锚的协作关系和两个崩溃窗口跑清楚,不在开箱即用。
Q4:托管 Harness(如 Kimi Hosted Agents)已经做了恢复,我还需要自己写吗?
A4:看数据边界。托管把事件流、断点恢复、重试退避都接管了,省掉自建运维(Kimi 用 SSE + Last-Event-ID 续传);但官方明示自托管不等于私有化、工具输入输出仍过平台推理接口。数据能出边界、接受托管,直接用;不能出,就自建或选本地执行网关。
Q5:事件流和 trace 有什么区别?
A5:trace(链路追踪)用于观测与还原现场,回答"发生了什么、为什么慢/错";event log 是持久化的事实账本,用于重放与恢复,回答"哪些步骤已完成、下一步从哪续"。ETCLOVG 综述把可观测性(O)与生命周期(L)列为独立层,正是这个道理——能看见不等于能恢复。
Q6:幂等键怎么生成才可靠?
A6:用业务上稳定的标识(订单号、任务 ID + 步骤序号),而非每次重试都变的随机 UUID。本文演示用 uuid.uuid5(NAMESPACE_URL, step) 这种确定性 UUID;生产环境建议直接用业务主键派生,让同一逻辑步骤跨重试得到同一个 key。
给长任务运行时兜住崩溃的那一层
企业级环曜 Agent 本地化部署把工具调用、副作用与事件流收进本地执行网关,配合恢复游标与幂等键,让长任务崩了能续跑、副作用不重放,事件记录与凭证留在企业内网;如需把分散文档与老员工经验沉淀成可检索、答带出处的私域资产,可再叠加企业级环曜 RAG 知识库本地化部署。两条线分段建设、互为前提。
联系环曜Agent团队