minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/src/runner.js

@@ -23,10 +23,8 @@
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { dlog, executeTool, getWorkingDir } from '../../../src/plugin-sdk.js';
-import { isMaxTurnsCutoff, truncate } from './agentCommon.js';
-import { evalExpr, interpolate, interpolateDeep, interpolateTyped } from './expressions.js';
-import { runRecovery } from './recovery.js';
+import { dlog, getWorkingDir } from '../../../src/plugin-sdk.js';
+import { evalExpr, interpolate } from './expressions.js';
 import { buildTaskArbitrator, isContinuationPhrase } from './taskIdentity.js';
 import { execAgentStep } from './stepExecutors/agent.js';
 import { execAssertStep } from './stepExecutors/assert.js';
@@ -34,8 +32,15 @@ import { execVerifyStep } from './stepExecutors/verify.js';
 import { execLlmStep } from './stepExecutors/llm.js';
 import { execSkillStep } from './stepExecutors/skill.js';
 import { execToolStep } from './stepExecutors/tool.js';
-import { normalizeCapture, VarStack } from './types.js';
-import { loopCheckpointName, WorkflowState, } from './workflowState.js';
+import { execEchoStep } from './stepExecutors/echo.js';
+import { execSetStep } from './stepExecutors/set.js';
+import { execBranchStep } from './controlFlow/branch.js';
+import { execLoopStep } from './controlFlow/loop.js';
+import { execPauseStep } from './controlFlow/pause.js';
+import { execSignalStep } from './controlFlow/signal.js';
+import { runStepWithRetry } from './stepPipeline.js';
+import { VarStack } from './types.js';
+import { WorkflowState, } from './workflowState.js';
 /**
  * 插件 ID：把私有 workflow_* 事件镜像成框架通用 plugin_progress 时挂这个 id。
  * LiveArea 状态行会渲染成 "[plugin:workflow-runner] i/total <message>"
@@ -127,32 +132,6 @@ function stepKind(step) {
         return 'llm';
     return 'assert'; // 不会到这里（loader 已校验），兜底
 }
-function readPath(root, path) {
-    const parts = path.split('.');
-    let cur = root;
-    for (const p of parts) {
-        if (cur == null || typeof cur !== 'object')
-            return undefined;
-        cur = cur[p];
-    }
-    return cur;
-}
-function bindCapture(captureMap, result, vars) {
-    for (const [resultField, varName] of Object.entries(normalizeCapture(captureMap))) {
-        const value = resultField.includes('.')
-            ? readPath(result.raw, resultField)
-            : result.raw[resultField];
-        vars.set(varName, value);
-    }
-}
-/** 取本步 capture 出的 { varName: value }，供 checkpoint 记录（resume 回放用）。 */
-function collectCaptured(captureMap, vars) {
-    const out = {};
-    for (const varName of Object.values(normalizeCapture(captureMap))) {
-        out[varName] = vars.get(varName);
-    }
-    return out;
-}
 function resolvePositiveIterationLimit(raw, vars, defaultValue, label) {
     if (raw === undefined)
         return { ok: true, value: defaultValue };
@@ -175,6 +154,12 @@ async function* dispatchActionStep(step, vars, ctx) {
         return execAssertStep(step, vars, ctx);
     if (step.type === 'verify')
         return await execVerifyStep(step, vars);
+    // set / echo 从 runSteps 的内联块搬进执行器体系：它们不影响迭代、只产出 StepResult。
+    // 搬过来的直接收益是 `capture:` 自然生效（此前它们从不调 bindCapture —— 静默失效）。
+    if (step.type === 'set')
+        return yield* execSetStep(step, vars);
+    if (step.type === 'echo')
+        return yield* execEchoStep(step, vars);
     if (step.tool)
         return yield* execToolStep(step, vars, ctx);
     if (step.agent)
@@ -215,7 +200,9 @@ loopResume) {
             };
             continue;
         }
-        // when 条件
+        // when 条件：**所有** step 类型统一在这里判。控制流处理器里不要再判一次 ——
+        // 重构前 break/continue 块自带一份，而它恒为真（false 时这里已经 continue 掉了），
+        // 连它的 catch 分支都不可达。那是纯死代码，随本次重构删除。
         if (step.when) {
             let pass = false;
             try {
@@ -223,12 +210,7 @@ loopResume) {
             }
             catch (e) {
                 const errMsg = `when 表达式错误: ${e.message}`;
-                yield {
-                    type: 'workflow_step_end',
-                    id: step.id,
-                    ok: false,
-                    error: errMsg,
-                };
+                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
                 yield {
                     type: 'error',
                     error: `Workflow halted at step "${step.id}": ${errMsg}`,
@@ -236,11 +218,7 @@ loopResume) {
                 return 'halted';
             }
             if (!pass) {
-                yield {
-                    type: 'workflow_step_skipped',
-                    id: step.id,
-                    reason: 'when=false',
-                };
+                yield { type: 'workflow_step_skipped', id: step.id, reason: 'when=false' };
                 await state.appendProgress(`- ${step.id} skipped (when=false)`);
                 continue;
             }
@@ -249,9 +227,7 @@ loopResume) {
         dlog('wf', `step ${i + 1}/${steps.length} START ${step.id} (${kind})`);
         // 已插值的人话进度名随 start 事件带给 UI：scrollback 进度行显示它而非块内相对
         // 序号，与状态行（下方 plugin_progress）保持一致。未声明 title 的步省略此字段。
-        const interpolatedTitle = step.title
-            ? interpolate(step.title, vars)
-            : undefined;
+        const interpolatedTitle = step.title ? interpolate(step.title, vars) : undefined;
         yield {
             type: 'workflow_step_start',
             id: step.id,
@@ -264,627 +240,67 @@ loopResume) {
         // 有 title 的步显示人话阶段名（如「阶段2/6·起草实现计划」）且不带块内序号——
         // 嵌套块的 i/total（顶层 5、循环体 12…）会被用户误读成"跳步/结构乱"；
         // 未声明 title 的步保持 legacy 格式 "i/total step <id> (<kind>)"。
-        if (interpolatedTitle) {
-            yield {
-                type: 'plugin_progress',
-                pluginId: WF_PLUGIN_ID,
-                message: interpolatedTitle,
-            };
-        }
-        else {
-            yield {
-                type: 'plugin_progress',
-                pluginId: WF_PLUGIN_ID,
-                current: i + 1,
-                max: steps.length,
-                message: `step ${step.id} (${kind})`,
-            };
-        }
-        // ---------- 控制流：branch ----------
-        if (step.type === 'branch') {
-            let cond = false;
-            try {
-                cond = Boolean(evalExpr(step.condition ?? 'false', vars));
-            }
-            catch (e) {
-                const errMsg = `branch 条件错误: ${e.message}`;
-                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-                yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-                return 'halted';
-            }
-            const branch = cond ? step.then : step.else;
-            if (Array.isArray(branch) && branch.length > 0) {
-                // branch 对 break 透明：子块 break/halt 都原样上抛给最近的循环 / 顶层。
-                const r = yield* runSteps(branch, vars, ctx, state);
-                if (r !== 'completed')
-                    return r;
-            }
-            await state.appendProgress(`✓ ${step.id} (branch=${cond})`);
-            await state.writeVars(vars.snapshot());
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: true,
-                output: `branch=${cond}`,
-            };
-            continue;
-        }
-        // ---------- 控制流：set（确定性变量赋值） ----------
+        yield {
+            type: 'plugin_progress',
+            pluginId: WF_PLUGIN_ID,
+            current: i + 1,
+            max: steps.length,
+            message: interpolatedTitle ?? `step ${step.id} (${kind})`,
+        };
+        // ---------- 控制流：改变的是「循环怎么走」，不是产出一个 StepResult ----------
         //
-        // 状态机类工作流（如 ralph-loop 的 phase）必须用 set——曾有 yaml 用
-        // `llm: "PLAN"` 当赋值语句：真把 "PLAN" 发给模型、capture 模型自由回复，
-        // 变量值非确定，下游 phase == 'PLAN' 比较全部不可靠。
-        if (step.type === 'set') {
-            const missing = [];
-            // 顶层值若是单一 "${EXPR}" 模板走 interpolateTyped 保留类型（布尔/数字/数组
-            // 不再字符串化成 "true"，下游条件不必写 == true || == 'true' 防御）；
-            // 多片段模板与嵌套结构行为不变（interpolateDeep）。
-            const resolved = {};
-            for (const [k, v] of Object.entries(step.set ?? {})) {
-                resolved[k] =
-                    typeof v === 'string'
-                        ? interpolateTyped(v, vars, { onMissing: (e) => missing.push(e) })
-                        : interpolateDeep(v, vars, { onMissing: (e) => missing.push(e) });
-            }
-            if (missing.length > 0) {
-                yield {
-                    type: 'warning',
-                    message: `step "${step.id}": 模板变量未定义：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
-                };
-            }
-            for (const [k, v] of Object.entries(resolved)) {
-                vars.setGlobal(k, v);
-            }
-            const summary = Object.entries(resolved)
-                .map(([k, v]) => `${k}=${String(v).slice(0, 40)}`)
-                .join(', ');
-            await state.appendProgress(`✓ ${step.id} (set ${summary})`);
-            await state.writeVars(vars.snapshot());
-            // set 记 checkpoint（值入 captures）：resume 跳过它时变量仍能回放
-            if (cp) {
-                await state.recordCheckpoint(cp.name(step.id), `set: ${summary}`, resolved, vars.snapshot());
-            }
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: true,
-                output: `set: ${summary}`,
-            };
-            continue;
+        // 所以它们不塞进 stepExecutors 那套 (step,vars,ctx)→StepResult 的形状里，
+        // 各自住在 controlFlow/ 并共用出口 ControlOutcome —— 这里只需一个分派。
+        const controlDeps = {
+            ctx,
+            state,
+            ...(cp ? { cp } : {}),
+            runBlock: (blockSteps, blockVars, blockCp, blockStart, blockResume) => runSteps(blockSteps, blockVars, ctx, state, blockCp, blockStart, blockResume),
+            index: i,
+            total: steps.length,
+            addGoalSupplement: (text) => addGoalSupplement(ctx, state, text),
+        };
+        let outcome = null;
+        if (step.type === 'branch') {
+            outcome = yield* execBranchStep(step, vars, controlDeps);
         }
-        // ---------- 控制流：loop（for-each 或 while） ----------
-        if (step.type === 'loop') {
-            const isWhileMode = step.over === undefined;
-            // max_iterations 支持 ${} 模板（如 "${inputs.max_iterations}"）：插值 + coerce；
-            // 失败响亮 halt——曾有模板字符串不插值直接参与 < 比较 → NaN → 静默 0 次迭代。
-            let maxIter = 200; // while 模式安全上限（缺省）
-            if (step.max_iterations !== undefined) {
-                const raw = step.max_iterations;
-                const n = typeof raw === 'number'
-                    ? raw
-                    : Number(interpolate(String(raw), vars).trim());
-                if (!Number.isFinite(n) || n <= 0) {
-                    const errMsg = `loop "${step.id}" 的 max_iterations 解析失败：${JSON.stringify(raw)} → "${typeof raw === 'string' ? interpolate(String(raw), vars) : raw}" 不是正数（检查变量是否存在，裸名请用 inputs.<name>）`;
-                    yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-                    yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-                    return 'halted';
-                }
-                maxIter = Math.floor(n);
-            }
-            const useFreshContext = step.fresh_context === true;
-            // fresh context：循环开始时 snapshot 当前 history
-            let baseHistorySnapshot = null;
-            if (useFreshContext) {
-                baseHistorySnapshot = ctx.history.slice();
-            }
-            // loop resume：恢复信息匹配本循环时消费一次——从中断时的迭代号起跑，
-            // 该迭代内已完成的步经 innerStartFrom 跳过（变量已由 runWorkflow 回放快照）。
-            let resumeIterStart = 0;
-            let pendingInnerStart = 0;
-            if (loopResume && loopResume.loopId === step.id) {
-                resumeIterStart = loopResume.iteration;
-                pendingInnerStart = loopResume.innerStartFrom;
+        else if (step.type === 'loop') {
+            outcome = yield* execLoopStep(step, vars, controlDeps, loopResume);
+            // 恢复信息只消费一次：匹配到的那个 loop 用掉之后，后续 loop 不再套用。
+            if (loopResume && loopResume.loopId === step.id)
                 loopResume = undefined;
-                yield {
-                    type: 'warning',
-                    message: `♻ 循环 ${step.id} 从第 ${resumeIterStart + 1} 轮迭代第 ${pendingInnerStart + 1} 步续跑。`,
-                };
-            }
-            // 顶层 loop 的 do[] 步记复合 checkpoint（loopId@@迭代号@@stepId），
-            // resume 可恢复到迭代中间；更深嵌套不再下钻（descendIntoLoop=false）。
-            const innerCpFor = (iter) => cp?.descendIntoLoop
-                ? {
-                    name: (id) => loopCheckpointName(step.id, iter, id),
-                    descendIntoLoop: false,
-                }
-                : undefined;
-            if (isWhileMode) {
-                // ===== WHILE 循环模式 =====
-                const asName = step.as ?? '_iter';
-                let iterCount = resumeIterStart;
-                let shouldBreak = false;
-                while (iterCount < maxIter) {
-                    if (ctx.signal?.aborted) {
-                        yield { type: 'interrupted' };
-                        return 'halted';
-                    }
-                    // 注入迭代变量
-                    vars.push();
-                    vars.set(asName, iterCount);
-                    vars.set(`${asName}_idx`, iterCount);
-                    // fresh context：每轮重置 history 到循环入口快照
-                    if (useFreshContext && baseHistorySnapshot) {
-                        ctx.history.length = 0;
-                        ctx.history.push(...baseHistorySnapshot);
-                    }
-                    // 迭代序号对用户有真实意义（第几轮重做），title 步也保留，只换人话名。
-                    yield {
-                        type: 'plugin_progress',
-                        pluginId: WF_PLUGIN_ID,
-                        current: iterCount + 1,
-                        max: maxIter,
-                        message: step.title
-                            ? `${interpolate(step.title, vars)}·第 ${iterCount + 1}/${maxIter} 轮`
-                            : `while-loop ${step.id} 迭代 ${iterCount + 1}/${maxIter}`,
-                    };
-                    // 第 2+ 轮额外发持久 warning：上面的状态行 progress 会被首步 title 立即
-                    // 覆盖（驻留一瞬），用户感知不到「循环重来了」——曾有 plan 工作流验收
-                    // 打回静默重启，被用户误读成死循环。while 模式的多轮 = 重做/重试，
-                    // 值得进 MessageList 留痕；for-each 的逐元素迭代是正常推进，不发。
-                    if (iterCount > 0) {
-                        yield {
-                            type: 'warning',
-                            message: `♻ 循环「${step.title ? interpolate(step.title, vars) : step.id}」进入第 ${iterCount + 1}/${maxIter} 轮`,
-                        };
-                    }
-                    const innerStart = pendingInnerStart;
-                    pendingInnerStart = 0; // 仅 resume 后的首个迭代生效
-                    const r = yield* runSteps(step.do ?? [], vars, ctx, state, innerCpFor(iterCount), innerStart);
-                    vars.pop();
-                    iterCount++;
-                    // halt（error/interrupt/onError:halt）→ 真正向上中止整个工作流。
-                    if (r === 'halted')
-                        return 'halted';
-                    if (typeof r === 'object') {
-                        // 带 target 且不是本循环 → 穿透上抛给外层循环
-                        if (r.target !== undefined && r.target !== step.id)
-                            return r;
-                        if (r.signal === 'break') {
-                            shouldBreak = true;
-                            break;
-                        }
-                        // continue → 跳到下一轮迭代（什么都不做，自然进入下一轮）
-                    }
-                }
-                const whyEnd = shouldBreak ? 'break 退出' : `达到上限 ${maxIter}`;
-                await state.appendProgress(`✓ ${step.id} (while ×${iterCount}, ${whyEnd})`);
-                await state.writeVars(vars.snapshot());
-                // 循环完成记自身 checkpoint：resume 据此判定「循环已整体完成」（否则
-                // 中断在循环之后的步骤时，resume 会误把整条循环从头重跑）。
-                if (cp) {
-                    await state.recordCheckpoint(cp.name(step.id), `while loop ${iterCount} iterations (${whyEnd})`, collectCaptured(step.capture, vars), vars.snapshot());
-                }
-                yield {
-                    type: 'workflow_step_end',
-                    id: step.id,
-                    ok: true,
-                    output: `while loop ${iterCount} iterations (${whyEnd})`,
-                };
-                continue;
-            }
-            // ===== FOR-EACH 循环模式（原有逻辑） =====
-            let arr;
-            try {
-                arr = evalExpr(step.over ?? '[]', vars);
-            }
-            catch (e) {
-                const errMsg = `loop over 表达式错误: ${e.message}`;
-                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-                yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-                return 'halted';
-            }
-            if (!Array.isArray(arr)) {
-                const errMsg = `loop over 必须求值为数组，得到 ${typeof arr}`;
-                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-                yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-                return 'halted';
-            }
-            const asName = step.as ?? 'item';
-            let iterCount = 0;
-            for (let idx = resumeIterStart; idx < arr.length; idx++) {
-                if (ctx.signal?.aborted) {
-                    yield { type: 'interrupted' };
-                    return 'halted';
-                }
-                vars.push();
-                vars.set(asName, arr[idx]);
-                vars.set(`${asName}_idx`, idx);
-                // fresh context 也支持 for-each 模式
-                if (useFreshContext && baseHistorySnapshot) {
-                    ctx.history.length = 0;
-                    ctx.history.push(...baseHistorySnapshot);
-                }
-                const innerStart = pendingInnerStart;
-                pendingInnerStart = 0;
-                const r = yield* runSteps(step.do ?? [], vars, ctx, state, innerCpFor(idx), innerStart);
-                vars.pop();
-                iterCount++;
-                if (r === 'halted')
-                    return 'halted';
-                if (typeof r === 'object') {
-                    if (r.target !== undefined && r.target !== step.id)
-                        return r; // 穿透上抛
-                    if (r.signal === 'break')
-                        break; // 跳出 for-each，循环后兄弟步继续
-                    // continue → 下一个元素
-                }
-            }
-            await state.appendProgress(`✓ ${step.id} (loop ×${iterCount})`);
-            await state.writeVars(vars.snapshot());
-            if (cp) {
-                await state.recordCheckpoint(cp.name(step.id), `loop ${iterCount} 次`, collectCaptured(step.capture, vars), vars.snapshot());
-            }
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: true,
-                output: `loop ${iterCount} 次`,
-            };
-            continue;
         }
-        // ---------- 控制流：pause（真 HITL 审批闸门） ----------
-        //
-        // 经 AskUserQuestion/askBridge 实现真停等：TUI 弹选择界面、用户拍板后继续；
-        // 非交互宿主（-p/gateway/测试）askBridge 自动选推荐项（继续执行）且 stderr
-        // 注记，绝不挂起——与 -p 单行 JSON 契约兼容。「等用户」骑在既有
-        // tool_call→tool_result 回路上（同 AskUserQuestion 工具），引擎零新通道。
-        if (step.type === 'pause') {
-            const msg = step.prompt
-                ? interpolate(step.prompt, vars)
-                : '工作流暂停点：请确认是否继续执行后续步骤。';
-            await state.appendProgress(`- ${step.id} pause: 等待用户确认`);
-            // pause 会驻留状态行很久（等用户），title 步同样不带块内序号防误读。
-            if (step.title) {
-                yield {
-                    type: 'plugin_progress',
-                    pluginId: WF_PLUGIN_ID,
-                    message: `⏸ ${interpolate(step.title, vars)}：等待用户确认…`,
-                };
-            }
-            else {
-                yield {
-                    type: 'plugin_progress',
-                    pluginId: WF_PLUGIN_ID,
-                    current: i + 1,
-                    max: steps.length,
-                    message: `⏸ 审批闸门 ${step.id}：等待用户确认…`,
-                };
-            }
-            const exec = ctx.executeTool ?? executeTool;
-            // 审批语义：明确选「继续」才放行；选「停止」、取消提问（ESC）、或自由输入
-            // 其它内容（既非继续也非停止 = 用户想先改点什么）都不放行（审批门上的
-            // 含糊 = 不批准，保守处理）；桥本身异常才兜底放行（保持可用性）。
-            let approved = true;
-            let askFailed = false;
-            let freeText = '';
-            const freeTextMode = step.free_text ?? 'halt';
-            try {
-                const r = await exec('AskUserQuestion', JSON.stringify({
-                    questions: [
-                        {
-                            question: truncate(msg, 400),
-                            header: '审批闸门',
-                            options: [
-                                { label: '继续执行 (推荐)', description: '放行后续步骤' },
-                                {
-                                    label: '停止（保留现场）',
-                                    description: '中止本次运行；同任务重跑可从断点 resume',
-                                },
-                            ],
-                        },
-                    ],
-                }), ctx.signal);
-                // ⚠️ 只解析【答案行】（"A1: …"）——回执里 Q 行带着问题原文，
-                // 工作流的 pause 提示语若含「停止」字样（如 plan.yaml 的说明文字），
-                // 看整个 content 会把用户选的「继续」误判成停止（曾是真事故）。
-                const answerText = r.ok
-                    ? r.content
-                        .split('\n')
-                        .map((l) => l.trim())
-                        .filter((l) => /^A\d+[:：]/.test(l))
-                        .join('\n')
-                    : '';
-                if (!r.ok || answerText.includes('停止')) {
-                    approved = false;
-                }
-                else if (answerText.includes('继续')) {
-                    approved = true;
-                }
-                else {
-                    // 自由输入（「其他」逃生项）：用户想先调整 → 不放行，把原话带进 halt 文案
-                    freeText = answerText.replace(/^A\d+[:：]\s*/, '');
-                    approved = freeTextMode === 'approve';
-                }
-            }
-            catch {
-                askFailed = true; // 桥不可用 → 放行 + 响亮警告（保持旧"不挂起"行为）
-            }
-            if (askFailed) {
-                yield {
-                    type: 'warning',
-                    message: `⚠ pause "${step.id}" 审批闸门不可用（提问桥异常），已自动放行。提示：${msg}`,
-                };
-            }
-            if (!approved) {
-                const why = freeText
-                    ? `用户在审批闸门 "${step.id}" 给出指示「${truncate(freeText, 120)}」——未放行（现场已保留，按指示调整后重跑同目标可从断点续跑）`
-                    : `用户在审批闸门 "${step.id}" 选择停止（现场已保留，重跑同目标可从断点续跑）`;
-                await state.appendProgress(`■ ${step.id}: ${why}`);
-                if (cp)
-                    await state.recordFailure(step.id, why);
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: why };
-                yield { type: 'error', error: `Workflow halted at step "${step.id}": ${why}` };
-                return 'halted';
-            }
-            // 带补充要求的放行：自由输入并入贯穿目标（后续每步都看到，不止 capture 变量）
-            if (freeText)
-                await addGoalSupplement(ctx, state, freeText);
-            const pauseResult = {
-                raw: {
-                    result: freeText,
-                    text: freeText,
-                    approved: true,
-                    free_text: freeText,
-                },
-                preview: freeText
-                    ? `审批通过：继续执行；补充要求：${truncate(freeText, 120)}`
-                    : '审批通过：继续执行',
-            };
-            if (step.capture)
-                bindCapture(step.capture, pauseResult, vars);
-            await state.writeVars(vars.snapshot());
-            if (cp) {
-                await state.recordCheckpoint(cp.name(step.id), pauseResult.preview, collectCaptured(step.capture, vars), vars.snapshot());
-            }
-            await state.appendProgress(`✓ ${step.id} (pause: 已确认继续)`);
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: true,
-                output: pauseResult.preview,
-            };
-            continue;
+        else if (step.type === 'pause') {
+            outcome = yield* execPauseStep(step, vars, controlDeps);
         }
-        // ---------- 控制流：break / continue（循环信号） ----------
-        //
-        // 仅在 loop 的 do[] 内有意义。break = 跳出循环；continue = 跳到下一轮迭代。
-        // 缺省作用于最近一层循环；带 target 时穿透中间层循环直达指定 id 的 loop
-        //（如审批反馈是方向性变化时，从审批小循环 continue 到外层 plan_loop 重启规划）。
-        // 通常配合 when 条件使用；游离信号（无外层循环 / target 不存在）冒泡到顶层
-        // 按正常完成处理，绝不当 halt。
-        if (step.type === 'break' || step.type === 'continue') {
-            let shouldFire = true;
-            if (step.when) {
-                try {
-                    shouldFire = Boolean(evalExpr(step.when, vars));
-                }
-                catch (e) {
-                    // when 表达式错误 → 不触发，当 skipped 处理
-                    shouldFire = false;
-                }
-            }
-            if (shouldFire) {
-                const label = `${step.type}${step.target ? ` → ${step.target}` : ''}`;
-                await state.appendProgress(`↵ ${step.id}: ${label}`);
-                yield { type: 'workflow_step_end', id: step.id, ok: true, output: label };
-                return { signal: step.type, target: step.target };
-            }
-            // 条件不满足 → 当 skip 处理，继续下一步
-            yield {
-                type: 'workflow_step_skipped',
-                id: step.id,
-                reason: `${step.type} 条件不满足`,
-            };
-            continue;
+        else if (step.type === 'break' || step.type === 'continue') {
+            outcome = yield* execSignalStep(step, controlDeps);
         }
-        // ---------- 控制流：echo（确定性输出，不烧 LLM） ----------
-        //
-        // 把 message 插值后作为 text 事件输出给用户。适合工作流末尾的完成报告：
-        // 产物/裁决已在变量里时直接插值，省一次 LLM 调用且零幻觉。
-        if (step.type === 'echo') {
-            const missing = [];
-            const text = interpolate(step.message ?? '', vars, {
-                onMissing: (e) => missing.push(e),
-            });
-            if (missing.length > 0) {
-                yield {
-                    type: 'warning',
-                    message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}`,
-                };
-            }
-            yield { type: 'text', delta: text.endsWith('\n') ? text : `${text}\n` };
-            await state.appendProgress(`✓ ${step.id} (echo)`);
-            if (cp) {
-                await state.recordCheckpoint(cp.name(step.id), truncate(text, 200), {}, vars.snapshot());
-            }
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: true,
-                output: truncate(text, 200),
-            };
+        if (outcome) {
+            if (outcome.kind === 'halted')
+                return 'halted';
+            if (outcome.kind === 'flow')
+                return outcome.signal;
             continue;
         }
-        // ---------- 普通动作 step：tool / llm / skill / agent / assert / verify ----------
+        // ---------- 动作步：tool / llm / skill / agent / assert / verify / set / echo ----------
         //
-        // in-run retry（self_heal）：失败先确定性重跑同一步，至多 maxRetries 次（retry 先于
-        // onError:recover）。maxRetries = step.max_retries ?? def.self_heal.max_retries（runWorkflow
-        // 注入到 ctx.selfHealMaxRetries）?? 0。语义：max_retries 是「额外重试次数」，总尝试 = 1 + maxRetries。
-        const maxRetries = step.max_retries ?? ctx.selfHealMaxRetries ?? 0;
-        let attempt = 0;
-        while (true) {
-            try {
-                const result = yield* dispatchActionStep(step, vars, ctx);
-                if (step.capture)
-                    bindCapture(step.capture, result, vars);
-                // goal_supplement：本步产出作为用户补充要求贯穿后续每一步（如 stage0 澄清结论）
-                if (step.goal_supplement) {
-                    const t = typeof result.raw.text === 'string' && result.raw.text.trim()
-                        ? result.raw.text
-                        : String(result.raw.result ?? result.preview ?? '');
-                    await addGoalSupplement(ctx, state, t);
-                }
-                await state.appendProgress(`✓ ${step.id} (${kind})`);
-                await state.writeVars(vars.snapshot());
-                // checkpoint：记录范围见 CpScope（顶层步 + 顶层 loop 的 do[] 一层）。
-                if (cp) {
-                    await state.recordCheckpoint(cp.name(step.id), result.preview, collectCaptured(step.capture, vars), vars.snapshot());
-                }
-                yield {
-                    type: 'workflow_step_end',
-                    id: step.id,
-                    ok: true,
-                    output: result.preview,
-                };
-                break; // 成功 → 退出 retry 循环，进入下一步
-            }
-            catch (e) {
-                const errMsg = e.message ?? String(e);
-                // in-run retry：还有重试额度且未中断 → 重跑同一步（不动 onError）。
-                if (attempt < maxRetries && !ctx.signal?.aborted) {
-                    attempt++;
-                    // 退避等待（线性）：普通 LLM/网络类错误用 retry_delay_ms。
-                    // maxTurns 截断默认保持旧行为立即续跑；长文档/PPT 类工作流可显式配置
-                    // max_turns_retry_delay_ms，在模型端高峰期给下一次续作留出恢复窗口。
-                    const isMaxTurns = isMaxTurnsCutoff(errMsg);
-                    const delayBase = isMaxTurns
-                        ? (ctx.maxTurnsRetryDelayMs ?? 0)
-                        : (ctx.retryDelayMs ?? 0);
-                    const delayMs = delayBase * attempt;
-                    const retryKind = isMaxTurns ? '轮数预算用尽，可续跑截断' : '失败';
-                    const retryProgress = isMaxTurns
-                        ? `↻ ${step.id}: 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}`
-                        : `↻ ${step.id}: ${retryKind}，重试 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}（${errMsg}）`;
-                    await state.appendProgress(retryProgress);
-                    yield {
-                        type: 'warning',
-                        message: isMaxTurns
-                            ? `step "${step.id}" 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}…`
-                            : `step "${step.id}" 失败：${errMsg}；${delayMs > 0 ? `${delayMs}ms 后` : ''}重试 ${attempt}/${maxRetries}…`,
-                    };
-                    yield {
-                        type: 'plugin_progress',
-                        pluginId: WF_PLUGIN_ID,
-                        current: i + 1,
-                        max: steps.length,
-                        message: isMaxTurns
-                            ? `↻ ${step.id} 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}…`
-                            : `↻ 重试 ${step.id} ${attempt}/${maxRetries}…`,
-                    };
-                    if (delayMs > 0)
-                        await sleepInterruptible(delayMs, ctx.signal);
-                    continue; // 重跑同一步
-                }
-                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-                // onError:'recover' —— retry 用尽仍失败，交给有界恢复 agent 随机应变把这一步救回来。
-                // 「确定性工作流 × TAOR」的结合点：happy path 走刚性 DAG，撞上预料之外的就地
-                // 降级为 agent 自适应；救回则继续 happy path，救不回才 honest halt。
-                if (step.onError === 'recover') {
-                    yield {
-                        type: 'warning',
-                        message: `step "${step.id}" 失败：${errMsg}；尝试自适应恢复…`,
-                    };
-                    yield {
-                        type: 'plugin_progress',
-                        pluginId: WF_PLUGIN_ID,
-                        current: i + 1,
-                        max: steps.length,
-                        message: `↻ 恢复 ${step.id}…`,
-                    };
-                    const rec = yield* runRecovery(step, vars, ctx, errMsg);
-                    if (ctx.signal?.aborted) {
-                        yield { type: 'interrupted' };
-                        return 'halted';
-                    }
-                    // 验证闸门：只有恢复 agent 真正交付（rec.ok）才绑 capture 走下去；
-                    // 显式放弃 / 产出不可信（rec.ok=false）则带原因 honest halt，绝不盲绑脏值。
-                    if (rec.ok) {
-                        if (step.capture)
-                            bindCapture(step.capture, rec.value, vars);
-                        await state.appendProgress(`⚠→✓ ${step.id} recovered`);
-                        await state.writeVars(vars.snapshot());
-                        if (cp) {
-                            await state.recordCheckpoint(cp.name(step.id), rec.value.preview, collectCaptured(step.capture, vars), vars.snapshot());
-                        }
-                        yield {
-                            type: 'workflow_step_end',
-                            id: step.id,
-                            ok: true,
-                            output: rec.value.preview,
-                        };
-                        break; // 救回 → 进入下一步
-                    }
-                    const combined = `${errMsg}（自适应恢复未成功：${rec.reason}）`;
-                    if (cp)
-                        await state.recordFailure(step.id, combined);
-                    yield {
-                        type: 'workflow_step_end',
-                        id: step.id,
-                        ok: false,
-                        error: combined,
-                    };
-                    yield {
-                        type: 'error',
-                        error: `Workflow halted at step "${step.id}": ${combined}`,
-                    };
-                    return 'halted';
-                }
-                if (step.onError === 'continue') {
-                    // 降级时给 capture 变量绑【明确占位文本】而非留空：空串静默内插进下游
-                    // prompt（如「已知需求分析：\n\n」）是更大的最小惊讶违例——模型看到
-                    // 空段会困惑。占位前缀「（上游步骤 」机器可识别；continue 本就是作者
-                    // 显式选择「无此内容也继续」，需要严格闸门的步骤应配 onError:halt 或 assert。
-                    if (step.capture) {
-                        const placeholder = `（上游步骤 ${step.id} 失败已降级（onError:continue），无内容——` +
-                            `请基于用户原始目标自行推断。错误：${errMsg.length > 120 ? `${errMsg.slice(0, 120)}…` : errMsg}）`;
-                        for (const varName of Object.values(normalizeCapture(step.capture))) {
-                            vars.setGlobal(varName, placeholder);
-                        }
-                    }
-                    // 降级此前完全静默（仅 progress.md 有 ✗ 行）——补一条 warning 可见化
-                    yield {
-                        type: 'warning',
-                        message: `step "${step.id}" 失败已降级（onError:continue）：${errMsg}`,
-                    };
-                    yield {
-                        type: 'workflow_step_end',
-                        id: step.id,
-                        ok: false,
-                        error: errMsg,
-                    };
-                    break; // 跳过本步 → 进入下一步
-                }
-                const finalErrMsg = isMaxTurnsCutoff(errMsg)
-                    ? `${errMsg}；重试额度已用尽，请拆分该步骤或提高 maxTurns。`
-                    : errMsg;
-                if (cp)
-                    await state.recordFailure(step.id, finalErrMsg);
-                yield {
-                    type: 'workflow_step_end',
-                    id: step.id,
-                    ok: false,
-                    error: finalErrMsg,
-                };
-                yield {
-                    type: 'error',
-                    error: `Workflow halted at step "${step.id}": ${finalErrMsg}`,
-                };
-                return 'halted';
-            }
-        }
+        // 统一走 runStepWithRetry：in-run 重试 → onError 三态 → commitStep 提交。
+        // 「提交一步」只有 stepPipeline 那一份实现，这里不再自己写（见 stepPipeline 头注）。
+        const actionOutcome = yield* runStepWithRetry({
+            step,
+            kind,
+            vars,
+            ctx,
+            state,
+            ...(cp ? { cp } : {}),
+            index: i,
+            total: steps.length,
+            addGoalSupplement: (text) => addGoalSupplement(ctx, state, text),
+            execute: () => dispatchActionStep(step, vars, ctx),
+        });
+        if (actionOutcome === 'halted')
+            return 'halted';
     }
     return 'completed';
 }