OpenRig workflow工作流引擎教程：spec缓存、步骤追踪与看门狗策略三大机制-育师

OpenRig workflow工作流引擎教程：spec缓存、步骤追踪与看门狗策略三大机制

【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址: https://gitcode.com/GitHub_Trending/op/openrig

OpenRig 是一个多智能体协作框架（Multi-agent harness），让 Claude Code 和 Codex 作为同一个系统协同工作。它的workflow 工作流引擎负责把"谁在哪一步做什么"变成可追踪的持久状态：spec 缓存让规范文件秒级读取，步骤追踪把每一步闭环写入只增日志，看门狗策略则在流程停顿时分级唤醒，让长时运行的智能体团队不卡死、不漂移。

一、工作流引擎在 OpenRig 中的位置

在 OpenRig 里，一个"rig"（机架）由多个 agent 席位组成，workflow 则定义了这些席位之间的步骤流转：从哪个步骤出发、由谁执行、完成后流向哪里。

引擎由三个核心机制支撑，对应 packages/daemon/src/domain/ 下的三类模块：

机制	解决的问题	核心实现
spec 缓存	规范文件频繁解析慢、口径不一致	workflow-spec-cache.ts
步骤追踪	步骤闭环状态丢失、无法审计	workflow-step-trail-log.ts
看门狗策略	工作流停摆、owner 失联	watchdog-policy-engine.ts

二、spec 缓存：文件是唯一事实，SQLite 只负责快

工作流规范（workflow spec）由操作者用 markdown/YAML 文件编写，存放在工作区里。OpenRig 的读透缓存（read-through cache）设计要点是：

懒加载 + 哈希失效：daemon 首次读取时把 spec 解析进 SQLite 的workflow_specs表，并记录文件内容的source_hash；下次读取时哈希不一致就重新解析，因此你修改文件后改动在下次读取时自然生效
文件永远赢：缓存注释里明确写着 "the cache is never the source of truth"——缓存只为快速查询服务，不会反过来篡改文件内容
统一查询入口：内置 starter 规范与用户自定义规范走同一张表，spec-library-workflow-scanner.ts 直接读缓存行生成拓扑图投影，保证rig workflow specs命令看到的与库界面完全一致

相关数据库迁移：033_workflow_specs.ts、034_workflow_instances.ts、035_workflow_step_trails.ts。

三、步骤追踪：append-only 的闭环日志

每次一个步骤结束（done / failed / waiting 等），引擎都会向workflow_step_trails表追加一条记录，包括：

步骤 ID 与角色（step_id、step_role）
闭环时间与闭环原因（closure_reason）
附带的闭环证据（closure_evidence）
执行者会话（actor_session）与前后队列项 ID

workflow-step-trail-log.ts 的 API 层只暴露record()方法——没有 UPDATE、没有 DELETE，从接口层面杜绝篡改。实例当前执行到哪个步骤，则记录在workflow_instances表的current_step_id与current_frontier_json（前沿步骤集合，支持并行分支）中。这套"实例状态 + 只增轨迹"的组合，让审计、恢复和回放都有了确定性依据。

四、看门狗策略：三级干预栈，而不是无脑定时提醒

长时运行的工作流最怕"owner 席位卡住，后面全等"。OpenRig 的看门狗（watchdog）不追求"每 tick 都做同样的事"，而是按证据选择干预级别，形成三级栈：

级别	目标	触发场景
Wake（唤醒）	重启动作	owner 空闲、失联、缺少下一步交接
Refocus（重聚焦）	纠正漂移	输出出现模式漂移、审批倒退、停止条件推理弱化
Alignment checkpoint（对齐检查点）	重建共享地图	阶段边界、生命周期变更、产品意图决策

几个对新手很实用的设计原则（完整规范见 watchdog/SKILL.md）：

扫描频率与唤醒频率分离：可以每 30 秒扫描一次状态，但唤醒至少间隔 600 秒，避免"提醒轰炸"污染工作流
安静跳过不记账：调度轮询中大量的"无事发生"不会写入历史，只有真正发出（sent）或终结（terminal）的评估才留痕
keepalive 策略只读 SQLite：workflow-keepalive.ts 直接从workflow_instances表读状态，只在前锋步骤逾期时才向 owner 席位发送提醒，正常路径上零噪音
七种失败模式清单：技能文档里逐条列出"唤醒错席位""refocus 被误读成新任务""提醒变成官僚化表演"等常见坑，帮你避开

CLI 侧对应 workflow.ts 与 watchdog.ts 两组命令，配合rig workflow查看实例状态、rig watchdog管理策略。