minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/src/controlFlow/branch.ts

@@ -0,0 +1,46 @@
+/**
+ * controlFlow/branch.ts —— 条件分支
+ *
+ * ⚠️ **branch 对 break 透明**：子块返回的 break/continue/halt 都原样上抛给
+ * 最近的循环或顶层。分支只决定「走哪一支」，不吞信号 —— 吞掉的话
+ * `break target:<loopId>` 就穿不过分支，而那正是它存在的意义。
+ */
+
+import type { LoopEvent } from '../../../../src/plugin-sdk.js';
+import { evalExpr } from '../expressions.js';
+import type { StepDef, VarStack, WorkflowEvent } from '../types.js';
+import type { ControlDeps, ControlOutcome } from './types.js';
+
+export async function* execBranchStep(
+  step: StepDef,
+  vars: VarStack,
+  deps: ControlDeps,
+): AsyncGenerator<WorkflowEvent | LoopEvent, ControlOutcome, void> {
+  const { state } = deps;
+  let cond = false;
+  try {
+    cond = Boolean(evalExpr(step.condition ?? 'false', vars));
+  } catch (e) {
+    const errMsg = `branch 条件错误: ${(e as Error).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 { kind: 'halted' };
+  }
+  const branch = cond ? step.then : step.else;
+  if (Array.isArray(branch) && branch.length > 0) {
+    // 子块不传 cp：更深嵌套不记 checkpoint（见 CpScope 注释）。
+    const r = yield* deps.runBlock(branch, vars);
+    if (r === 'halted') return { kind: 'halted' };
+    if (r !== 'completed') return { kind: 'flow', signal: 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}`,
+  };
+  return { kind: 'next' };
+}

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

@@ -0,0 +1,211 @@
+/**
+ * ============================================================
+ *  controlFlow/loop.ts —— 循环（while / for-each）
+ * ------------------------------------------------------------
+ *  从 `runner.ts::runSteps` 的内联块整体搬出（原 223 行，占 runSteps 的 29%）。
+ *  逐行忠实搬运，只把「递归执行子块」换成注入的 `deps.runBlock`（见 types.ts 头注）。
+ *
+ *  三形态共存，缺一不可：
+ *   · **while**（无 `over:`）—— `max_iterations` 支持 `${}` 模板；用于重做/重试
+ *   · **for-each**（有 `over:`）—— 逐元素迭代
+ *   · **resume** —— 中断在迭代中间时恢复到「该迭代 + 迭代内断点」
+ *
+ *  四条实测换来的不变量，改动时先读完再动：
+ *   ① `max_iterations` 模板解析失败**响亮 halt**：曾有模板字符串不插值直接参与
+ *      `<` 比较 → NaN → 静默 0 次迭代（工作流"跑完了"但什么都没做）
+ *   ② 迭代变量用 `pushIteration/setIteration`，循环体里 capture/set 的作者变量
+ *      必须**活到循环之外**（否则刚成功翻到目标页的运行会被判失败）
+ *   ③ while 模式第 2+ 轮发**持久 warning**：状态行 progress 会被首步 title 立即
+ *      覆盖，用户感知不到「循环重来了」—— 曾被误读成死循环。for-each 的逐元素
+ *      推进是正常的，不发
+ *   ④ 循环整体完成要记**自身 checkpoint**：否则中断在循环之后的步骤时，
+ *      resume 会误把整条循环从头重跑
+ * ============================================================
+ */
+import { evalExpr, interpolate } from '../expressions.js';
+import { collectCaptured } from '../stepPipeline.js';
+import { loopCheckpointName } from '../workflowState.js';
+const WF_PLUGIN_ID = 'workflow-runner';
+export async function* execLoopStep(step, vars, deps, 
+/** 顶层传入的循环恢复信息；匹配本循环 id 时消费一次。 */
+loopResume) {
+    const { ctx, state, cp } = deps;
+    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 { kind: '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;
+        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 { kind: 'halted' };
+            }
+            // 注入迭代变量：用 pushIteration/setIteration —— 只有这两个变量该随迭代消失，
+            // 循环体里 capture/set 出来的作者变量必须活到循环之外（见 VarStack 头注）。
+            vars.pushIteration();
+            vars.setIteration(asName, iterCount);
+            vars.setIteration(`${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* deps.runBlock(step.do ?? [], vars, innerCpFor(iterCount), innerStart);
+            vars.pop();
+            iterCount++;
+            // halt（error/interrupt/onError:halt）→ 真正向上中止整个工作流。
+            if (r === 'halted')
+                return { kind: 'halted' };
+            if (typeof r === 'object') {
+                // 带 target 且不是本循环 → 穿透上抛给外层循环
+                if (r.target !== undefined && r.target !== step.id) {
+                    return { kind: 'flow', signal: 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})`,
+        };
+        return { kind: 'next' };
+    }
+    // ===== 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 { kind: '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 { kind: '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 { kind: 'halted' };
+        }
+        vars.pushIteration();
+        vars.setIteration(asName, arr[idx]);
+        vars.setIteration(`${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* deps.runBlock(step.do ?? [], vars, innerCpFor(idx), innerStart);
+        vars.pop();
+        iterCount++;
+        if (r === 'halted')
+            return { kind: 'halted' };
+        if (typeof r === 'object') {
+            if (r.target !== undefined && r.target !== step.id) {
+                return { kind: 'flow', signal: 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} 次`,
+    };
+    return { kind: 'next' };
+}

package/plugins/workflow-runner/src/controlFlow/loop.ts

@@ -0,0 +1,248 @@
+/**
+ * ============================================================
+ *  controlFlow/loop.ts —— 循环（while / for-each）
+ * ------------------------------------------------------------
+ *  从 `runner.ts::runSteps` 的内联块整体搬出（原 223 行，占 runSteps 的 29%）。
+ *  逐行忠实搬运，只把「递归执行子块」换成注入的 `deps.runBlock`（见 types.ts 头注）。
+ *
+ *  三形态共存，缺一不可：
+ *   · **while**（无 `over:`）—— `max_iterations` 支持 `${}` 模板；用于重做/重试
+ *   · **for-each**（有 `over:`）—— 逐元素迭代
+ *   · **resume** —— 中断在迭代中间时恢复到「该迭代 + 迭代内断点」
+ *
+ *  四条实测换来的不变量，改动时先读完再动：
+ *   ① `max_iterations` 模板解析失败**响亮 halt**：曾有模板字符串不插值直接参与
+ *      `<` 比较 → NaN → 静默 0 次迭代（工作流"跑完了"但什么都没做）
+ *   ② 迭代变量用 `pushIteration/setIteration`，循环体里 capture/set 的作者变量
+ *      必须**活到循环之外**（否则刚成功翻到目标页的运行会被判失败）
+ *   ③ while 模式第 2+ 轮发**持久 warning**：状态行 progress 会被首步 title 立即
+ *      覆盖，用户感知不到「循环重来了」—— 曾被误读成死循环。for-each 的逐元素
+ *      推进是正常的，不发
+ *   ④ 循环整体完成要记**自身 checkpoint**：否则中断在循环之后的步骤时，
+ *      resume 会误把整条循环从头重跑
+ * ============================================================
+ */
+
+import type { LoopEvent } from '../../../../src/plugin-sdk.js';
+import type { Message } from '../../../../src/types.js';
+import { evalExpr, interpolate } from '../expressions.js';
+import { collectCaptured, type CpScope } from '../stepPipeline.js';
+import type { StepDef, VarStack, WorkflowEvent } from '../types.js';
+import { loopCheckpointName, type LoopResumeInfo } from '../workflowState.js';
+import type { ControlDeps, ControlOutcome } from './types.js';
+
+const WF_PLUGIN_ID = 'workflow-runner';
+
+export async function* execLoopStep(
+  step: StepDef,
+  vars: VarStack,
+  deps: ControlDeps,
+  /** 顶层传入的循环恢复信息；匹配本循环 id 时消费一次。 */
+  loopResume?: LoopResumeInfo,
+): AsyncGenerator<WorkflowEvent | LoopEvent, ControlOutcome, void> {
+  const { ctx, state, cp } = deps;
+  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 { kind: 'halted' };
+    }
+    maxIter = Math.floor(n);
+  }
+  const useFreshContext = step.fresh_context === true;
+
+  // fresh context：循环开始时 snapshot 当前 history
+  let baseHistorySnapshot: Message[] | null = 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;
+    yield {
+      type: 'warning',
+      message: `♻ 循环 ${step.id} 从第 ${resumeIterStart + 1} 轮迭代第 ${pendingInnerStart + 1} 步续跑。`,
+    };
+  }
+
+  // 顶层 loop 的 do[] 步记复合 checkpoint（loopId@@迭代号@@stepId），
+  // resume 可恢复到迭代中间；更深嵌套不再下钻（descendIntoLoop=false）。
+  const innerCpFor = (iter: number): CpScope | undefined =>
+    cp?.descendIntoLoop
+      ? {
+          name: (id: string) => 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 { kind: 'halted' };
+      }
+
+      // 注入迭代变量：用 pushIteration/setIteration —— 只有这两个变量该随迭代消失，
+      // 循环体里 capture/set 出来的作者变量必须活到循环之外（见 VarStack 头注）。
+      vars.pushIteration();
+      vars.setIteration(asName, iterCount);
+      vars.setIteration(`${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* deps.runBlock(
+        step.do ?? [],
+        vars,
+        innerCpFor(iterCount),
+        innerStart,
+      );
+      vars.pop();
+      iterCount++;
+
+      // halt（error/interrupt/onError:halt）→ 真正向上中止整个工作流。
+      if (r === 'halted') return { kind: 'halted' };
+      if (typeof r === 'object') {
+        // 带 target 且不是本循环 → 穿透上抛给外层循环
+        if (r.target !== undefined && r.target !== step.id) {
+          return { kind: 'flow', signal: 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})`,
+    };
+    return { kind: 'next' };
+  }
+
+  // ===== FOR-EACH 循环模式 =====
+  let arr: unknown;
+  try {
+    arr = evalExpr(step.over ?? '[]', vars);
+  } catch (e) {
+    const errMsg = `loop over 表达式错误: ${(e as Error).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 { kind: '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 { kind: '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 { kind: 'halted' };
+    }
+    vars.pushIteration();
+    vars.setIteration(asName, arr[idx]);
+    vars.setIteration(`${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* deps.runBlock(step.do ?? [], vars, innerCpFor(idx), innerStart);
+    vars.pop();
+    iterCount++;
+    if (r === 'halted') return { kind: 'halted' };
+    if (typeof r === 'object') {
+      if (r.target !== undefined && r.target !== step.id) {
+        return { kind: 'flow', signal: 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} 次`,
+  };
+  return { kind: 'next' };
+}

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

@@ -0,0 +1,129 @@
+/**
+ * ============================================================
+ *  controlFlow/pause.ts —— 真 HITL 审批闸门
+ * ------------------------------------------------------------
+ *  经 AskUserQuestion/askBridge 实现**真停等**：TUI 弹选择界面、用户拍板后继续；
+ *  非交互宿主（-p / gateway / 测试）askBridge 自动选推荐项（继续执行）且 stderr
+ *  注记，**绝不挂起** —— 与 `-p` 单行 JSON 契约兼容。「等用户」骑在既有
+ *  tool_call→tool_result 回路上（同 AskUserQuestion 工具），引擎零新通道。
+ *
+ *  两条踩过坑的判定规则，改动前先读：
+ *   ① **只解析【答案行】（`A1: …`）**。回执里 Q 行带着问题原文，而工作流的 pause
+ *      提示语常含「停止」字样（如 plan.yaml 的说明文字）—— 看整个 content 会把
+ *      用户选的「继续」误判成停止。**曾是真事故。**
+ *   ② **审批门上的含糊 = 不批准**。明确选「继续」才放行；选「停止」、取消提问（ESC）、
+ *      或自由输入其它内容（= 用户想先改点什么）一律不放行。只有**桥本身异常**才
+ *      兜底放行（保持可用性）并响亮警告。
+ * ============================================================
+ */
+import { executeTool } from '../../../../src/plugin-sdk.js';
+import { truncate } from '../agentCommon.js';
+import { interpolate } from '../expressions.js';
+import { commitStep } from '../stepPipeline.js';
+const WF_PLUGIN_ID = 'workflow-runner';
+export async function* execPauseStep(step, vars, deps) {
+    const { ctx, state, cp } = deps;
+    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: deps.index + 1,
+            max: deps.total,
+            message: `⏸ 审批闸门 ${step.id}：等待用户确认…`,
+        };
+    }
+    const exec = ctx.executeTool ?? executeTool;
+    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);
+        // ⚠️ 只解析【答案行】——见文件头注规则 ①。
+        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 { kind: 'halted' };
+    }
+    // 带补充要求的放行：自由输入并入贯穿目标（后续每步都看到，不止 capture 变量）
+    if (freeText)
+        await deps.addGoalSupplement(freeText);
+    const pauseResult = {
+        raw: { result: freeText, text: freeText, approved: true, free_text: freeText },
+        preview: freeText
+            ? `审批通过：继续执行；补充要求：${truncate(freeText, 120)}`
+            : '审批通过：继续执行',
+    };
+    yield* commitStep({
+        step,
+        result: pauseResult,
+        kind: 'pause',
+        vars,
+        ctx,
+        state,
+        ...(cp ? { cp } : {}),
+        progressLine: `✓ ${step.id} (pause: 已确认继续)`,
+        addGoalSupplement: deps.addGoalSupplement,
+    });
+    return { kind: 'next' };
+}