Stirrup缓存与断点恢复机制全解:长任务中断后如何秒级续跑
Stirrup缓存与断点恢复机制全解:长任务中断后如何秒级续跑
Stirrup 是一个轻量级 AI Agent 构建框架,内置的 Stirrup 缓存(Caching)与断点恢复(Resume)机制,能让长任务在中断后从上一轮状态"秒级续跑",而不用从零重新执行。本文带你搞懂它的工作原理、启用方式和缓存管理技巧,新手也能 5 分钟上手。
为什么需要 Stirrup 缓存与断点恢复?
让 Agent 执行"分析所有数据文件"这类长任务时,经常会遇到三种意外:
| 场景 | 后果 |
|---|---|
| 手动按 Ctrl+C 中断 | 已完成的几十轮对话直接丢失 |
| 运行中报错(网络抖动、工具异常) | 之前跑完的工具调用全部白费 |
| 达到 max_turns 上限 | 任务被迫终止,无法继续 |
如果每次都要从头跑,时间和 Token 成本都不可接受。Stirrup 的解法是:非正常退出时自动把 Agent 状态写盘,下次启动时从缓存恢复,从断点继续执行。
工作原理:三阶段自动续跑
整个机制由 cache.py 中的 CacheManager 驱动,分为三个阶段:
阶段一:中断时自动保存
当运行被 Ctrl+C、异常或 max_turns 上限终止时,Stirrup 会自动把状态写入 ~/.cache/stirrup/<task_hash>/ 目录,包含两个部分:
state.json:对话消息历史、按轮次(turn)归组的工具元数据、任务哈希与时间戳files/:执行环境(exec env)里的全部文件,比如 Agent 中途生成的数据、脚本
值得一提的是,保存 state.json 时采用了原子写入(先写临时文件再 rename),并在保存期间临时屏蔽 SIGINT 信号,避免"保存缓存本身被打断"导致的损坏文件。相关逻辑见 agent.py 中的缓存决策。
阶段二:再次启动时从断点恢复
以相同的提示词重新运行并开启 resume=True 后:
- Stirrup 用初始提示词计算 SHA256 哈希的前 12 位作为
task_hash(见 compute_task_hash) - 找到对应缓存后,还原消息历史和执行环境文件
- 从被中断的那一轮继续执行,日志会打印
Resuming from cached state at turn 15
效果大致如下:
# 第一次运行(在第 15 轮被中断)
$ python my_agent.py
^C
Cached state for task abc123...
# 第二次运行(自动从第 15 轮续跑)
$ python my_agent.py
Resuming from cached state at turn 15
阶段三:成功后自动清理
任务正常完成后(Agent 调用了 finish 工具),缓存会被自动删除,避免磁盘空间越积越多。完成清理的代码在 agent.py。
如何开启断点恢复:只需一个参数
在创建 session 时传入 resume=True 即可,完整的最小示例如下:
from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient
from stirrup.tools import default_tools
client = ChatCompletionsClient(model="gpt-5.6-luna", max_tokens=8_192, context_window_tokens=1_000_000)
agent = Agent(client=client, name="researcher", tools=default_tools(), max_turns=50)
async with agent.session(output_dir="./output", resume=True) as session:
await session.run("Analyze all datasets in the data folder")
session() 一共提供三个缓存相关参数(定义见 agent.py):
| 参数 | 默认值 | 作用 |
|---|---|---|
resume |
False |
为 True 时尝试从缓存恢复状态 |
clear_cache_on_success |
True |
成功后是否自动清理缓存;设为 False 可保留缓存用于检查调试 |
cache_on_interrupt |
True |
是否注册 SIGINT 处理器实现 Ctrl+C 优雅缓存;在线程/子进程中运行 Agent 时建议设为 False |
💡 小提示:缓存键来自初始提示词的哈希——相同的 prompt 对应同一份缓存,所以续跑时提示词必须保持一致,否则 Stirrup 会找不到缓存而从零开始。
缓存里到底存了什么?
一个缓存目录(~/.cache/stirrup/<task_hash>/)的完整内容是:
- 对话消息与历史:包括经过上下文摘要(summarization)分组后的全部消息;图片、视频、音频等二进制内容块会做 base64 编码后序列化
- 工具元数据:按已接受的 assistant 轮次 id 归组(
run_metadata_by_turn) - 执行环境文件:Agent 工作目录里的所有文件快照
轮次进度不是单独存储的,而是从恢复出来的消息历史中推导得出(见 _get_turn_count 调用处)。这样能确保与上下文溢出时的"回退轮次"机制保持一致——被撤销的轮次会同时从历史和元数据中移除。
如何管理缓存:查看与手动清理
除了依赖自动清理,你也可以用 CacheManager 手动管理所有缓存:
from stirrup.core.cache import CacheManager
cache_manager = CacheManager()
# 列出所有缓存
for task_hash in cache_manager.list_caches():
info = cache_manager.get_cache_info(task_hash)
print(f"{task_hash}: turn {info['turn']}")
# 手动清除某个缓存
cache_manager.clear_cache("abc123def456")
这些方法都定义在 CacheManager 类 中,官方文档 docs/guides/caching.md 有更完整的说明。
常见问题速答 📌
Q1:缓存存在哪里?会不会占很大空间?
默认存在本机 ~/.cache/stirrup/ 下,按 task_hash 分目录。由于会保存执行环境的全部文件,大文件任务缓存可能不小;成功完成后会自动清理,也可以用 clear_cache_on_success=False 反向控制。
Q2:子 Agent 也会缓存吗?
不会。缓存决策中要求 depth == 0(见 agent.py),只有根 Agent 的非成功退出才会触发保存,子 Agent 中断由父级统一管理。
Q3:想保留成功任务的缓存用于复盘怎么办?
把 clear_cache_on_success 设为 False 即可,成功后缓存会保留在磁盘上,方便用 get_cache_info 查看最终状态。
总结
Stirrup 的缓存与断点恢复机制可以概括为一句话:中断自动存档,重跑自动读档。只要给 session 加上 resume=True,Ctrl+C、报错、轮次耗尽都不会让长任务前功尽弃,下一次启动就能从断点继续,大幅节省 Token 与等待时间。
想深入了解,推荐阅读:
- 官方缓存指南:docs/guides/caching.md
- 缓存核心源码:src/stirrup/core/cache.py
- 会话与恢复逻辑:src/stirrup/core/agent.py
