AI技能测评中断后续跑 active-pipeline.json断点恢复方法

上一篇将 SkillSentry 的流程收敛成 Pipeline 状态机，解决了“系统应该按什么顺序走”的问题。本文继续处理另一个可靠性难题：长流程跑到一半断了，如何从正确位置恢复，而不是从头重跑或跳步。

设想一个典型场景：standard 模式运行到 executor 刚完成，正要进入 grader-report 时，主会话却因超时而断裂。33 个用例的 transcript 已全部写入磁盘，但没有任何机制能让流程从“executor 已完成、grader 未开始”这个中间位置继续——只能从头重跑，重新消耗 33 次 executor 调用。

这并非增加一个临时文件就能解决的问题，而是长流程 Agent 系统必须面对的可靠性挑战：已经完成的步骤不能丢失，未完成的步骤不能假装完成，恢复过程不能跳步，重复执行不能导致开销和结论失真。

active-pipeline.json 只是这个可靠性约束的落地文件。真正重要的是它背后的规则：每次将执行权交给 subagent 之前，先把当前步骤、下一步骤、pending subagents 以及工作目录记录下来，让 watchdog 有能力在主会话断裂后继续推进。

问题：测评跑到一半中断

SkillSentry 的 standard / full 模式需要 30 至 50 分钟。在这段时间内，主编排器（一个 LLM session）可能因以下原因中断：

1. LLM 超时：主 session 在 yield 等待 subagent 时超过平台限制
2. 网络中断：OpenClaw 的飞书连接断开
3. 用户误操作：关闭了终端窗口
4. 平台重启：OpenClaw 容器重新部署

早期行为非常脆弱：Pipeline 会静默断裂。subagent 可能已经完成了 executor，但主编排器再也不会回来推进到 grader-report。用户下次触发“测评”时会从头开始，之前的所有工作全部浪费。

设计目标

Checkpoint 文件：active-pipeline.json

路径：<本地工作目录>/data/skill-eval/active-pipeline.json

{
  "skill": "finance-doc-query-prod",
  "mode": "standard",
  "session_dir": "2026-05-07_003",
  "current_step": "executor-with",
  "next_step": "grader-report",
  "pending_subagents": ["executor-run1-all", "executor-run2-all", "executor-run3-all"],
  "started_at": "2026-05-07T15:03:00+08:00",
  "timeout_minutes": 60,
  "workspace_dir": "~/.openclaw/data/skill-eval/sessions/finance-doc-query-prod/2026-05-07_003/"
}

字段说明：

与 session.json 的协作

active-pipeline.json 和 session.json 各有明确的分工：

两者之间不会产生冲突：

• session.json 在验收通过后更新（last_step = 刚完成的步骤）
• active-pipeline.json 在验收通过后删除

铁律：spawn → write → yield

spawn subagent → 写入 active-pipeline.json → session_yield

违规情况：

• spawn 后不写入 checkpoint 就 yield = 违规（Pipeline 断裂后无法恢复）
• spawn 后不 yield 直接 stop = 严重违规（Pipeline 必然断裂）

这是 Pipeline 持久化机制中最重要的行为约束。

违规的后果：用户下次触发测评时，watchdog 无法识别当前处于哪个步骤，会从 pipeline 起点重新推断状态，导致已完成的步骤被重复执行，或者更糟糕——跳过某些步骤直接进入后续流程。

清理时机

以下任一条件满足时，系统会删除 active-pipeline.json：

1. subagent 完成 + 验收通过 + session.json.last_step 已更新
2. Pipeline 最终步骤（publish）完成
3. 用户手动取消测评

正常执行时，checkpoint 文件的生命周期很短：spawn 后写入，resume 后验收通过即删除。它只在“主会话意外断裂”这个窗口期内发挥作用。

Watchdog 自动恢复

系统 cron 每 10 分钟发送 PIPELINE_CHECK systemEvent 到主 session。收到后执行以下逻辑：

1. 读取 active-pipeline.json
2. 文件不存在 → HEARTBEAT_OK（无活跃 Pipeline，跳过）
3. 文件存在 → 
   a. 查询 pending_subagents 的状态 
   b. 全部完成 → 读 SKILL.md → 从 next_step 继续执行 
   c. 仍在运行且未超时 → HEARTBEAT_OK（正常等待） 
   d. 超时 → 通知用户 "⚠️ Pipeline 超时: {skill} 的 {current_step} 已运行超过 {timeout_minutes}min"

恢复后的行为

Resume 时的第一步不是展示恢复进度，而是验证当前 checkpoint 对应的产物是否完整：

• 如果缺失率 ≤ 20%，视为完整，继续推进到 next_step
• 如果缺失率 > 20%，触发 L2 降级重试，而非直接跳过（见下方“边界情况处理”）

验证通过后，主编排器从 checkpoint 的 next_step 开始正常流程：

1. 读取 session.json 确认上下文
2. 验收上一步产物（检查文件是否存在）
3. 推进到 next_step
4. 继续正常调度循环

无需重跑 Step 0/1/2，直接从 Pipeline 断点处续接。

用户手动恢复

当用户说“继续”/“resume”/“从断点继续”时，直接触发恢复逻辑：

读取 session.json.last_step + pipeline 数组
→ 从 pipeline[indexOf(last_step) + 1] 开始
→ 跳过 Step 0/1/2

Resume 展示铁律

跳过执行 ≠ 跳过展示。

Resume 时必须按顺序逐步输出已完成步骤的摘要，每步一条独立消息：

⏭️ static (1/12) [Resume]: L1=4.5 L2=PASS L3=23 L4=轻微 L5=良好 | TP=95% TN=100%
⏭️ cases (2/12) [Resume]: 32 用例 (HP:10 EC:6 NEG:5 ROB:3 SEC:3 E2E:3 AL:2)
⏭️ sync-pull (3/12) [Resume]: skipped_no_config
⏭️ sync-push-cases (4/12) [Resume]: skipped_no_config
✅ executor-with (5/12) [Resume]: Run-1 32/32 | Run-2 31/32 | Run-3 32/32
→ 当前步骤: grader-report (6/12)...

为什么这样设计？用户看到“5/12”但不知道前 4 步是什么结果，就会产生黑箱感，从而不信任系统。Resume 的目的是减少执行时间，而不是减少展示时间。

边界情况处理

checkpoint 文件存在但 session.json 已标记完成

可能原因：验收通过、session.json 更新成功，但删除 checkpoint 之前系统崩溃了。

处理方式：检测到 session.json.last_step >= active-pipeline.current_step → 直接删除 checkpoint，继续下一步。

多个 active-pipeline.json 文件

设计上不会发生——同一时间只有一个 Pipeline 在运行。如果发现多个，取 started_at 最新的那个。

subagent 产物不完整

恢复后验收产物时发现缺失率 > 20% → 触发 L2 降级重试，而非直接跳过。

效果对比

FAQ

Q：active-pipeline.json 文件有多大？写入频率高吗？

通常小于 500 字节。只在 spawn 长时间 subagent（executor、grader-report、comparator、analyzer）时写入，一次测评最多写入 4 到 6 次。属于普通文件 I/O，无性能影响。

Q：如果用户在 resume 之前修改了 SKILL.md 怎么办？

Resume 时检测 SKILL.md 的 hash 是否与 session.json 中记录的一致。如果不一致 → 提示“Skill 已变更，建议从头测评”，让用户选择继续还是重来。

Q：CLI 模式下有 watchdog 吗？

CLI 模式（如本地编码助手）没有 systemEvent cron，主会话断开后无法自动恢复。恢复方式：

1. 重新启动本地编码助手，进入同一个项目目录
2. 输入“继续上次测评”或“resume”
3. SkillSentry 会读取 active-pipeline.json，从 last_completed_step 的下一步继续
4. 如果 active-pipeline.json 不存在（主会话崩溃前未写入），则只能从头重跑

这是当前 CLI 模式的已知限制，OpenClaw 环境有 watchdog 机制可以避免这种情况。