上一篇将 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/"
}

字段说明

字段	用途
skill	当前测评的 Skill 名
mode	测评模式
session_dir	本次会话目录
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 → session_yield

违规情况：

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

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

违规的后果：

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

清理时机：何时删除 checkpoint

以下任一条件满足时删除 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 降级重试，而非直接跳过。

效果对比

场景	早期行为	当前行为
主会话断裂	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，主会话断开后无法自动恢复。

恢复方式：

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

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