oh-my-openagent ULW Loop checkpoint 自动推进（auto-advance）机制全解析

oh-my-openagent ULW Loop checkpoint 自动推进auto-advance机制全解析【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本文围绕 oh-my-openagent 项目中 ULW Loop 的 checkpoint 自动推进auto-advance功能展开完整还原了该功能从 RED 失败、GREEN 通过到真实环境 QA 验证的落地证据并结合源码剖析checkpoint --status complete如何自动启动下一个目标、--no-advance如何保留旧式双调用状态、failed检查点为何绝不推进的底层逻辑。读完本文你将掌握 ULW Loop 检查点命令的完整参数语义、自动推进调度算法以及如何用测试与构建产物在全新仓库中验证该行为。一、背景ULW Loop 与 checkpoint 在流水线中的位置oh-my-openagentOmO的 ULW Loop 是面向图工程任务编排的一种多目标循环协议把一次大任务拆解为多个goal如 G001、G002每个 goal 带有若干 success criteria由 Agent 逐一执行、记录证据、通过检查点收尾。其 CLI 入口为omo-agent-toolkit ulw-loop包含create-goals、record-evidence、checkpoint、status、complete-goals等子命令用法见 cli-output.ts。checkpoint是其中一个 goal 收尾的关键动作Agent 完成某个 goal 后提交证据并声明其状态complete / failed / blocked系统在校验通过后写入台账ledger并更新计划文件。而**自动推进auto-advance**则是在一个非最终 goal 标记为 complete 后由同一命令顺带启动下一个 pending 目标从而把收尾上一个 启动下一个从两次调用合并为一次减少 Agent 与 CLI 的往返。本篇文章对应的原始证据文档为 .omo/evidence/20260721-ulw-loop-gajae-adoption/task-1.md。二、checkpoint 命令完整用法与参数语义checkpoint 的完整 CLI 形态如下与 cli-output.ts 一致# 打印质量门 JSON 模板构建最终质量门时使用 omo-agent-toolkit ulw-loop checkpoint --print-template [--goal-id id] [--json] # 对指定 goal 做检查点status 支持 complete|failed|blocked omo-agent-toolkit ulw-loop checkpoint \ --goal-id id \ --status complete|failed|blocked \ --evidence proof \ --codex-goal-json get_goal JSON 或文件路径 \ [--quality-gate-json 质量门 JSON 或文件路径] \ [--no-advance] \ [--json]各参数语义依据 checkpoint-continuation.ts 与 checkpoint.ts 的实现参数是否必填取值/行为--goal-id必填目标 ID缺失时报ULW_LOOP_ARGUMENT_MISSING查不到时报ulw_loop_goal_not_found--status必填complete、failed或blocked其余值报ULW_LOOP_STATUS_INVALID--evidence必填非空字符串trim()后为空报ulw_loop_evidence_required--codex-goal-json视模式而定Codex goal 的快照 JSON 或指向仓库内文件的路径提交后写入 ledger--quality-gate-json最终/收尾批次必填质量门 JSON或其路径缺失时最终检查点报ULW_LOOP_VALIDATION_BATCH_GATE_REQUIRED--no-advance可选存在时advancefalse禁止自动推进下一个目标--json可选输出结构化 JSON含summary而非人类可读文本--print-template可选不执行检查点只输出质量门模板配合--json可被$(...)捕获其中--codex-goal-json的解析逻辑比较特别见 checkpoint.ts先尝试把值当作 JSON 字符串直接解析若解析失败则把它当作相对于仓库根的路径读取文件内容再解析两者都失败时报ulw_loop_json_input_invalid。这意味着你既可以直接内联 JSON也可以传--codex-goal-json $(cat goal.json)或文件路径。三、核心机制checkpointAndContinue 如何决定是否推进自动推进并非在 checkpoint 内部完成而是由 checkpoint-continuation.ts 中的checkpointAndContinue在checkpointUlwLoop之后追加的一步。其核心逻辑只有短短几行却精确表达了三条铁律const result await checkpointUlwLoop(repoRoot, args, scope); if (args.status ! complete || result.aggregateCompletion ! undefined || !args.advance) return result; const next await startNextUlwLoop(repoRoot, {}, scope); if (done in next) return { ...result, plan: next.plan, next: doneNext(next.plan) }; const instruction buildCodexGoalInstruction({ plan: next.plan, goal: next.goal }); return { ...result, plan: next.plan, next: { resumed: next.resumed, goal: next.goal, instruction } };逐条拆解只有--status complete才可能推进。failed/blocked检查点直接原样返回result.next为undefined对应的 JSON 输出中不存在next字段aggregate 收尾aggregateCompletion已产生不再推进。当目标是整个 run 的最终目标、整批计划全部完成时计划已经结束不存在下一个目标--no-advance关闭推进。advance: !hasFlag(argv, --no-advance)见 checkpoint-continuation.ts此时保持收尾与启动分离的旧式两调用状态推进成功时携带交接指令。若startNextUlwLoop返回了下一个 goalbuildCodexGoalInstruction会生成一段面向 Agent 的 handoff 文本含模式、计划路径、台账路径、目标信息、成功标准与 Codex goal 集成约束见 codex-goal-instruction.ts文本模式输出会直接打印该指令JSON 模式则放在next.instruction中全部完成时返回 done 语义。doneNext调用blockedDecisionHandoff判断是否有遗留的 blocked 决策需要人工接手输出blocked标记与handoff文本默认ulw-loop: all goals complete。四、推进调度startNextUlwLoop 的 resume 与 next 规则真正执行启动下一个的是 plan-crud.ts 中的startNextUlwLoop其调度顺序体现了三个优先级优先恢复进行中的目标resume如果计划中存在status in_progress且未被调度排除的 goalsteeringStatus不是superseded或blocked见isScheduleEligible则直接返回该 goal并标记resumed: true——此时推进不会把 attempt 加一只是继续既有工作其次启动下一个 pending 目标按计划中的顺序找到第一个pending且可调度的 goal执行启动动作status in_progress、attempt 1、写入startedAt、清理旧 blocker 字段、把plan.activeGoalId指向它并在台账中追加goal_started条目消息为Attempt N可选重试 failed 目标args.retryFailed为真且没有 pending 目标时会寻找failed、nonRetriable为假且可调度的目标先追加goal_retried台账条目再启动。若既无可恢复、也无 pending、也无待重试目标则返回{ done: true, plan }。在自动推进场景下checkpointAndContinue调用startNextUlwLoop(repoRoot, {}, scope)时未传retryFailed因此推进只会发生在恢复 in_progress 或启动 pending这两种情况下。注意一个细节startNextUlwLoop的调度始终在withUlwLoopMutationLock的互斥锁内执行plan-crud.tscheckpoint 的写入同样持锁checkpoint.ts保证收尾上一个 启动下一个在并发场景下也是原子的。五、complete 检查点的前置校验链checkpointAndContinue只在checkpointUlwLoop完全成功后才推进因此自动推进的可靠性建立在 checkpoint 自身的严格校验之上。对于--status completecheckpoint.ts 会依次执行成功标准校验最终目标isFinalRunCompletionCandidate要求该 goal 全部 criteria pass、整份计划全部 criteria pass、所有 validation batch 关闭requireAllCriteriaPassrequireAllPlanCriteriaPassrequireAllValidationBatchesClosed非最终目标在 aggregate 模式下要求 essential criteria passrequireEssentialCriteriaPass否则要求全部 passCodex goal 快照校验validateCheckpointCodexGoal核对--codex-goal-json的目标与计划中的 aggregate payload 一致并产出nextActions与warnings质量门校验当目标是最终目标或关闭某个 validation batch 时强制要求--quality-gate-json经validateQualityGate校验支持lazycodex表面codeQualityStatus WATCH时会把 WATCH 备注并入 ledger evidence并执行requireBatchGate状态落盘校验全部通过后goal 置为complete、写入completedAt、evidence清理失败与 blocker 字段追加goal_completed或batch_closed台账条目并commit。对于failed/blocked走applyBlockedOrFailedcheckpoint.ts会通过classifyExternalAuthorizationBlocker对 evidence 做 blocker 特征分类同一签名出现满 3 次会把 goal 置为needs_user_decision并标记nonRetriable同时清理plan.activeGoalId。六、证据文档还原RED → GREEN → Real-surface QA关联文档 task-1.md 记录了该功能以测试驱动 真实环境复验方式落地的完整过程这正是最贴近工程实践的验证路径RED先看到失败命令npm test -- checkpoint-continuation cli-checkpoint观察到的失败test/checkpoint-continuation.test.ts无法导入尚不存在的../src/checkpoint-continuation.jsCLI 的 JSON continuation 断言失败——checkpoint 输出缺少next字段G002-goal-beta仍停留在pending。GREEN组件级门禁通过命令npm test -- checkpoint-continuation cli-checkpoint-continuation与npm run typecheck观察结果2 个测试文件、5 个测试全部通过TypeScript 严格检查通过。对应测试文件为 checkpoint-continuation.test.ts三个用例恰好覆盖自动推进的三条核心路径// 用例 1完成的非最终 goal advance 开启 → 启动下一个 pending goal expect(result.next).toMatchObject({ resumed: false, goal: { id: G002, status: in_progress } }); expect((await readUlwLoopPlan(repo)).activeGoalId).toBe(G002); // 用例 2advance 关闭 → 保留旧式两调用状态 expect(result.next).toBeUndefined(); expect((await readUlwLoopPlan(repo)).activeGoalId).toBeUndefined(); // 用例 3failed checkpoint advance 开启 → 不启动下一个 expect(result.next).toBeUndefined(); expect((await readUlwLoopPlan(repo)).activeGoalId).toBeUndefined();Real-surface QA构建产物 全新仓库复验命令npm run build然后在 freshmktempgit 仓库中运行构建出的dist/cli.js验证真实命令行行为而非仅单元函数。七、真实环境下的五步验证脚本将证据文档中的 QA 场景整理为可直接复现的完整流程对应 task-1.md 的五个场景场景 1创建规范计划dist/cli.js ulw-loop create-goals --brief $- Goal alpha\n- Goal beta生成包含G001-goal-alpha进行中与G002-goal-betapending两个目标的计划。场景 2为 G001 的关键标准记录证据为G001-goal-alpha的 essential criteriaC001/C002逐条record-evidence --status pass使后续 complete 校验通过。场景 3complete 检查点触发自动推进dist/cli.js ulw-loop checkpoint \ --goal-id G001-goal-alpha \ --status complete \ --codex-goal-json aggregate active 的 get_goal JSON \ --json观察结果与文档记录一致next.goal.id G002-goal-betanext.goal.status in_progress紧接的status --json显示plan.activeGoalId G002-goal-beta。场景 4--no-advance关闭推进在相同输入上追加--no-advance重跑JSON 中不存在next属性计划中不存在plan.activeGoalIdG001 完成即止G002 仍 pending等待显式启动。场景 5failed 检查点绝不推进对一份全新计划直接执行checkpoint --goal-id G001-goal-alpha --status failed无next属性G002-goal-beta保持pending。证据文档末尾记录的断言脚本输出三条摘要恰好一一对应上述行为auto-advance ok G002-goal-beta G002-goal-beta推进成功plan.activeGoalId 与 next.goal.id 一致no-advance ok关闭推进后无 nextfailed-no-advance ok失败不推进。八、设计取舍与使用建议从源码与证据可以看出 auto-advance 的几个设计取舍理解它们有助于正确使用推进是一次性动作不做重试编排。checkpointAndContinue只调用一次startNextUlwLoop是否retryFailed由后续complete-goals --retry-failed单独负责职责分离清晰见 codex-goal-instruction.ts 中对失败恢复路径的指引自动推进仅发生在当前目标是下一个进行中/pending 目标时。如果检查点时已有其他 in_progress 目标推进结果是 resume 该目标resumed: true不会抢占最终目标必须显式携带质量门。--print-template可用于生成--quality-gate-json的骨架--quality-gate-json $(omo-agent-toolkit ulw-loop checkpoint --print-template)再填充manualQa、gateReview、iteration、criteriaCoverage字段JSON 模式是 Agent 友好的接口。--json输出{ ok, plan, goal, ledgerEntry, next, summary, ... }summary由summarizeUlwLoopPlan生成plan-crud.ts包含各状态 goal 计数与 criteria 的 pass/pending/fail/blocked 统计适合让 Agent 判断整体进度。如需查看命令帮助文本与更多子命令status、complete-goals、record-review-blockers等可阅读 cli-output.ts 与 codex-goal-instruction.ts或直接在仓库中运行omo-agent-toolkit ulw-loop --help查看当前版本的实际输出。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考