22—AI Skill 测评中断后怎么续跑：active-pipeline.json 断点恢复设计

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

standard 模式跑到 executor 刚完成、准备进入 grader-report 时，主会话超时断裂了。33 个用例的 transcript 全在磁盘上，但没有任何机制能让流程从"executor 已完成、grader 未开始"这个位置继续------只能从头重跑，重新消耗 33 次 executor 调用。

这不是一个"加个临时文件"的问题，而是长流程 Agent 系统必须解决的可靠性问题：

text 复制代码

已经完成的步骤不能丢。
未完成的步骤不能假装完成。
恢复后不能跳步。
重复执行不能导致开销和结论失真。

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

问题：测评跑到一半断了

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

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

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

设计目标

即使主 session 意外终止，Pipeline 也能在下次心跳时自动恢复，不会静默断裂。

Checkpoint 文件：active-pipeline.json

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

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/"
}

字段说明：

字段	用途
skill	当前测评的 Skill 名
mode	测评模式
current_step	当前正在执行的步骤
next_step	current_step 完成后应推进到的步骤
pending_subagents	还在运行的 subagent ID 列表
started_at	当前步骤开始时间（用于超时判断）
timeout_minutes	超时阈值
workspace_dir	本次测评的完整工作目录

与 session.json 的协作

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

文件	角色	生命周期
session.json	持久状态记录（last_step、verdict、cost）	整个测评期间
active-pipeline.json	临时断点保护（当前步骤、pending subagents）	仅 spawn→验收窗口期

两者不会冲突：

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：

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

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

Watchdog 自动恢复

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

css 复制代码

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 开始正常流程：

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

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

用户手动恢复

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

css 复制代码

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

Resume 展示铁律

跳过执行 ≠ 跳过展示。

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

less 复制代码

⏭️ 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 降级重试，而非直接跳过。

效果对比

场景	早期行为	当前行为
主会话断裂	Pipeline 静默丢失，下次从头来	10 分钟内自动恢复
用户说「继续」	无法恢复，报错	从断点续接 + 展示前置摘要
subagent 超时	主会话一直等，用户不知道	超时告警 + 降级机制
重复触发	从头开始，浪费 token	检测到幂等条件，提示复用

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，主会话断开后无法自动恢复。恢复方式：

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

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