按以下任一条件OR 触发 CMDC.checkpoint!/2，自动持久化会话快照。

触发条件（OR 语义，任一命中即存）

• every_n_turns: N（默认 10）— 每 N 个完成的 turn 后存档（hook：:after_turn）
• on_tools: ["shell", "edit_file"]（默认 []）— 指定工具执行完后存档（hook：:after_tool）
• on_events: [:approval_required, :session_end, ...]（默认 [:approval_required, :session_end]）— 指定事件后存档；事件名为 atom（与 EventBus 事件首元 atom 对齐）

自动 GC

避免 backend 无限堆积（PG 表 / DETS 文件爆炸）:

• max_checkpoints: N（默认 50）— 同 session 超过 N 份后，删除最老
• ttl_seconds: N（默认 30 天 = 2_592_000）— 老于此时间的 snapshot 自动删除

GC 在每次成功 save 后异步执行，不阻塞主流程。

异步保存

Plugin handle_event 内不会同步调 Checkpoint.save/3(那会阻塞 Agent gen_statem callback)。save + GC 都通过 CMDC.AsyncTaskSupervisor 起独立 Task 执行， 失败仅 Logger.warning 不影响主路径。

配置示例

# 基础：每 5 turn 自动存档到 ETS（开发期）
{CMDC.Plugin.Builtin.AutoCheckpoint, backend: CMDC.Checkpoint.Backend.ETS, every_n_turns: 5}

# 生产推荐：cmdc_memory_pg PG backend + 关键事件 + 关键工具
{CMDC.Plugin.Builtin.AutoCheckpoint,
 backend: CMDCMemoryPg.CheckpointBackend,
 every_n_turns: 10,
 on_tools: ["shell", "edit_file", "write_file"],
 on_events: [:approval_required, :session_end, :agent_abort],
 max_checkpoints: 100,
 ttl_seconds: 7 * 86_400}

与 Checkpoint.Backend 关系

• Plugin 自身不依赖任何特定 backend；通过 :backend opt 注入
• 默认与 CMDC.Checkpoint.Backend.ETS 兼容；生产换 CMDCMemoryPg.CheckpointBackend
• snapshot 走 CMDC.checkpoint!/2 facade,所以与 CMDC.resume_session!/2 全套自动兼容

事件

每次成功 save 后 emit {:auto_checkpoint_saved, %{checkpoint_id, trigger, ...}}, 供 UI / 审计订阅。失败时仅 Logger.warning（避免事件流噪音）。