120 lines
3.2 KiB
Markdown
120 lines
3.2 KiB
Markdown
---
|
||
name: durable-execution
|
||
description: Checkpoint management and state persistence for long-running agents. Use when executing tasks that span multiple steps, need failure recovery, or require idempotent operations. Covers checkpoint strategy, state management layers, event sourcing, and recovery patterns.
|
||
---
|
||
|
||
# 持久化执行 — 检查点与状态管理
|
||
|
||
> 可靠是规模化的前提。每个长时任务都必须有可恢复的检查点。
|
||
|
||
## 🎯 何时使用
|
||
|
||
- 任务预计超过 5 个步骤
|
||
- 任务涉及文件修改（需要回滚能力）
|
||
- 任务依赖外部服务/API
|
||
- 任务需要在中断后恢复
|
||
|
||
## 📦 三层状态管理
|
||
|
||
| 层级 | 内容 | 本项目的实现 |
|
||
|---|---|---|
|
||
| **系统层** | 工作流 ID、超时、重试配置 | update_plan 记录任务 ID 和进度 |
|
||
| **执行层** | 当前活动、执行进度、等待事件 | checklist_write 分步骤记录 |
|
||
| **业务层** | 已完成工作、中间产物 | git diff + 编译结果作为验证 |
|
||
|
||
## 🔄 检查点策略
|
||
|
||
### 触发时机
|
||
```
|
||
时间触发：每完成 1 个关键步骤
|
||
事件触发：编译通过 / 失败后
|
||
状态变化：每次代码修改后（git diff 可见）
|
||
```
|
||
|
||
### 检查点内容
|
||
```yaml
|
||
checkpoint:
|
||
step_id: "string"
|
||
status: "pending | in_progress | completed | failed"
|
||
inputs: { } # 该步骤的输入参数
|
||
outputs: { } # 该步骤的产出
|
||
error_message: "" # 失败原因
|
||
timestamp: "ISO8601" # 时间戳
|
||
```
|
||
|
||
### 恢复流程
|
||
```
|
||
失败检测
|
||
→ 定位最新检查点（update_plan / checklist）
|
||
→ 分析失败原因（编译错误 / 测试失败 / 逻辑错误）
|
||
→ git restore 撤销本次修改
|
||
→ 从失败点修复（不从头开始）
|
||
→ 继续执行
|
||
→ 恢复验证（确认状态一致性）
|
||
```
|
||
|
||
## ♻️ 幂等性模式
|
||
|
||
### 模式 1：唯一标识
|
||
每个操作生成唯一 ID，已执行则跳过：
|
||
```
|
||
generate_code(task_id="abc123")
|
||
if executed(task_id="abc123"):
|
||
return cached_result # 已执行，跳过
|
||
```
|
||
|
||
### 模式 2：状态检查
|
||
执行前检查目标是否已达成：
|
||
```
|
||
if file_exists("src/utils/helper.js"):
|
||
return # 已生成，跳过
|
||
```
|
||
|
||
### 模式 3：补偿操作
|
||
不可逆操作提供回滚机制：
|
||
```
|
||
try:
|
||
modify_file(path)
|
||
except:
|
||
restore_from_git(path) # 补偿操作
|
||
```
|
||
|
||
## 📝 事件溯源（简化版）
|
||
|
||
每次操作产生不可变事件记录：
|
||
|
||
```
|
||
事件流（按时间顺序）:
|
||
① 人类提交任务 → ② Agent 制定计划
|
||
→ ③ 修改文件 → ④ 编译检查
|
||
→ ⑤ 数据流验证 → ⑥ 人类审查
|
||
→ ⑦ 提交代码
|
||
```
|
||
|
||
每次事件可通过 `git log` + `update_plan` 追溯。
|
||
|
||
## ⚡ 本项目的检查点命令速查
|
||
|
||
```bash
|
||
# 查看当前进度
|
||
grep -n "^[0-9]\+\." <(cat AGENTS.md | grep -A 100 "工作流程")
|
||
|
||
# 回滚最近的修改
|
||
git checkout -- <file>
|
||
|
||
# 查看修改历史
|
||
git log --oneline -10
|
||
|
||
# 查看未提交的变更
|
||
git diff --stat HEAD
|
||
```
|
||
|
||
## ⚠️ 常见陷阱
|
||
|
||
| 陷阱 | 表现 | 解决 |
|
||
|---|---|---|
|
||
| 不设检查点 | 失败后全部重来 | 步骤间自动 save_checkpoint |
|
||
| 幂等性缺失 | 重复执行导致错误 | 唯一 ID / 状态检查 |
|
||
| 状态不一致 | 检查点与实际不符 | git diff 验证后再恢复 |
|
||
| 检查点过大 | 保存和恢复慢 | 只保存增量状态 |
|