Stirrup缓存与断点恢复机制全解:长任务中断后如何秒级续跑

原创2026-11-03 19:28:181,819 阅读

Stirrup缓存与断点恢复机制全解:长任务中断后如何秒级续跑

Stirrup 是一个轻量级 AI Agent 构建框架,内置的 Stirrup 缓存(Caching)与断点恢复(Resume)机制,能让长任务在中断后从上一轮状态"秒级续跑",而不用从零重新执行。本文带你搞懂它的工作原理、启用方式和缓存管理技巧,新手也能 5 分钟上手。

Stirrup 项目横幅:轻量级 AI Agent 构建框架 Stirrup

为什么需要 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 后:

  1. Stirrup 用初始提示词计算 SHA256 哈希的前 12 位作为 task_hash(见 compute_task_hash)
  2. 找到对应缓存后,还原消息历史和执行环境文件
  3. 从被中断的那一轮继续执行,日志会打印 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 与等待时间。

想深入了解,推荐阅读:

登录后查看全文
Stirrup