22-AI Skill 测评中断后如何续跑：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 → sessions_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.json2. 文件不存在 → 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 机制可以避免这种情况。