his/.qoder/skills/durable-execution/SKILL.md

name, description

name	description
durable-execution	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 可见）

检查点内容

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 追溯。

⚡ 本项目的检查点命令速查

# 查看当前进度
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 验证后再恢复
检查点过大	保存和恢复慢	只保存增量状态