minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,277 @@
+/**
+ * ============================================================
+ *  stepPipeline.ts —— 「一步算完成」的唯一实现
+ * ------------------------------------------------------------
+ *  ⚠️ 这个文件存在的理由是一次真实的架构事故。
+ *
+ *  重构前，「提交一步」这套动作（绑 capture → 累加目标补充 → 写 progress →
+ *  落 vars → 记 checkpoint → 发 step_end）**没有单一实现**，被 `runSteps` 里的
+ *  各个内联块各抄一份。抄到什么程度：
+ *
+ *      recordCheckpoint  × 7      appendProgress   × 17
+ *      writeVars         × 7      step_end 事件    × 19
+ *      bindCapture       × 3      collectCaptured  × 5
+ *
+ *  而且**已经漂移出真 bug**：7 处 checkpoint 里，`set` 传 `resolved`、
+ *  `echo` 传 `{}`、其余 5 处传 `collectCaptured(step.capture, vars)`。
+ *  顺着查下去发现 `echo` / `set` 从不调 `bindCapture` ——
+ *  **它们静默忽略 `capture:`**：yaml 作者写了既不报错也不生效，
+ *  resume 时那个变量也回放不出来。又一次「静默失效」。
+ *
+ *  所以这里的规则是硬的：**任何 step 完成后都必须经过 `commitStep`。**
+ *  新增 step 类型时不要再自己写这套 —— 抄一份就是又埋一颗漂移的种子。
+ *  `plugins/workflow-runner/test/stepPipeline.test.ts` 钉着这条。
+ * ============================================================
+ */
+import { isMaxTurnsCutoff } from './agentCommon.js';
+import { runRecovery } from './recovery.js';
+import { normalizeCapture } from './types.js';
+const WF_PLUGIN_ID = 'workflow-runner';
+/** 读 `a.b.c` 形式的嵌套字段。 */
+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;
+}
+/**
+ * 把本步产出绑到变量上，**并把「绑了个空」响亮说出来**。
+ *
+ * ⚠️ `capture` 的写法是 `{ 结果字段: 变量名 }`。写反了（`{ 变量名: 结果字段 }`）
+ * 语法完全合法、加载期查不出来，运行时只是安静地绑一个 undefined —— 然后：
+ *   · `${varName}` 插值发一条「模板变量未定义」的 warning，但那条指向的是**使用处**，
+ *     看着像是「后面那步写错了」，而真正错的是**几十行之前的 capture**
+ *   · 更糟的是 assert：条件直接判假，用户看到的是 onFail 里那段业务文案，
+ *     与真实原因毫无关系，排查方向被彻底带偏
+ *
+ * 实测踩过两次（`adaptive-research.yaml` 绑 `content` 而 agent 步只有 `text`；
+ * `wechat-reading-shots.yaml` 把 `text: pager` 写反成 `pager: text`）。
+ */
+export function bindCapture(captureMap, result, vars, stepId) {
+    const warnings = [];
+    for (const [resultField, varName] of Object.entries(normalizeCapture(captureMap))) {
+        const value = resultField.includes('.')
+            ? readPath(result.raw, resultField)
+            : result.raw[resultField];
+        if (value === undefined) {
+            const available = Object.keys(result.raw);
+            warnings.push(`step "${stepId ?? '?'}": capture 取不到字段 \`${resultField}\`，变量 `
+                + `\`${varName}\` 绑成了 undefined。本步实际可绑的字段：`
+                + `${available.length ? available.map((k) => `\`${k}\``).join('、') : '（无）'}。`
+                + `⚠️ 写法是 { 结果字段: 变量名 }，检查是否写反了。`);
+        }
+        vars.set(varName, value);
+    }
+    return warnings;
+}
+/** 取本步 capture 出的 { varName: value }，供 checkpoint 记录（resume 回放用）。 */
+export function collectCaptured(captureMap, vars) {
+    if (!captureMap)
+        return {};
+    const out = {};
+    for (const varName of Object.values(normalizeCapture(captureMap))) {
+        out[varName] = vars.get(varName);
+    }
+    return out;
+}
+/** 从 StepResult 里取「可当作用户补充要求」的那段文本。 */
+function supplementTextOf(result) {
+    return typeof result.raw.text === 'string' && result.raw.text.trim()
+        ? result.raw.text
+        : String(result.raw.result ?? result.preview ?? '');
+}
+/**
+ * 提交一步：capture → goal_supplement → progress → vars → checkpoint → step_end。
+ *
+ * **所有 step 类型的唯一收口。** 见文件头注：抄第二份就是埋漂移。
+ */
+export async function* commitStep(input) {
+    const { step, result, kind, vars, state, cp } = input;
+    if (step.capture) {
+        for (const message of bindCapture(step.capture, result, vars, step.id)) {
+            yield { type: 'warning', message };
+        }
+    }
+    // goal_supplement：本步产出作为用户补充要求贯穿后续每一步（如 stage0 澄清结论）
+    if (step.goal_supplement) {
+        await input.addGoalSupplement(supplementTextOf(result));
+    }
+    await state.appendProgress(input.progressLine ?? `✓ ${step.id} (${kind})`);
+    await state.writeVars(vars.snapshot());
+    // checkpoint：记录范围见 CpScope（顶层步 + 顶层 loop 的 do[] 一层）。
+    //
+    // 回放变量 = 本步**引入的**变量（`replayVars`，目前只有 set）
+    //          + 作者**显式声明**要捕获的变量（`capture`）。
+    // 两者不能互相替代：set 步通常没有 capture，只记 collectCaptured 会得到 {} ——
+    // resume 跳过它之后下游断言就查不到那个变量了（engineRobustness 抓过这个回归）。
+    if (cp) {
+        await state.recordCheckpoint(cp.name(step.id), result.preview, { ...(result.replayVars ?? {}), ...collectCaptured(step.capture, vars) }, vars.snapshot());
+    }
+    yield {
+        type: 'workflow_step_end',
+        id: step.id,
+        ok: true,
+        output: result.preview,
+    };
+}
+/** 可中断的 sleep：中断时立刻返回，不把整轮退避耗完。 */
+function sleepInterruptible(ms, signal) {
+    return new Promise((res) => {
+        if (signal?.aborted)
+            return res();
+        const t = setTimeout(done, ms);
+        function done() {
+            clearTimeout(t);
+            signal?.removeEventListener('abort', done);
+            res();
+        }
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+/**
+ * 执行一个动作步：in-run 重试 → onError 三态 → 统一提交。
+ *
+ * 三条语义原样保留（都是实测踩出来的）：
+ *   · `max_retries` 是**额外**重试次数，总尝试 = 1 + maxRetries
+ *   · 退避是**线性**的（delayBase × attempt）；maxTurns 截断走 `max_turns_retry_delay_ms`，
+ *     缺省 0 = 立即续跑（长文档类工作流才需要给模型端留恢复窗口）
+ *   · `onError:'recover'` 有**验证闸门**：只有恢复 agent 真正交付才绑 capture 走下去，
+ *     显式放弃 / 产出不可信一律带原因 honest halt，绝不盲绑脏值
+ */
+export async function* runStepWithRetry(input) {
+    const { step, kind, vars, ctx, state, cp } = input;
+    const maxRetries = step.max_retries ?? ctx.selfHealMaxRetries ?? 0;
+    let attempt = 0;
+    while (true) {
+        try {
+            const result = yield* input.execute();
+            yield* commitStep({
+                step,
+                result,
+                kind,
+                vars,
+                ctx,
+                state,
+                ...(cp ? { cp } : {}),
+                addGoalSupplement: input.addGoalSupplement,
+            });
+            return 'ok';
+        }
+        catch (e) {
+            const errMsg = e.message ?? String(e);
+            // in-run retry：还有重试额度且未中断 → 重跑同一步（不动 onError）。
+            if (attempt < maxRetries && !ctx.signal?.aborted) {
+                attempt++;
+                const isMaxTurns = isMaxTurnsCutoff(errMsg);
+                const delayBase = isMaxTurns
+                    ? (ctx.maxTurnsRetryDelayMs ?? 0)
+                    : (ctx.retryDelayMs ?? 0);
+                const delayMs = delayBase * attempt;
+                const retryKind = isMaxTurns ? '轮数预算用尽，可续跑截断' : '失败';
+                await state.appendProgress(isMaxTurns
+                    ? `↻ ${step.id}: 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}`
+                    : `↻ ${step.id}: ${retryKind}，重试 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}（${errMsg}）`);
+                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: input.index + 1,
+                    max: input.total,
+                    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: input.index + 1,
+                    max: input.total,
+                    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) {
+                    yield* commitStep({
+                        step,
+                        result: rec.value,
+                        kind,
+                        vars,
+                        ctx,
+                        state,
+                        ...(cp ? { cp } : {}),
+                        progressLine: `⚠→✓ ${step.id} recovered`,
+                        addGoalSupplement: input.addGoalSupplement,
+                    });
+                    return 'ok';
+                }
+                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 };
+                return 'degraded';
+            }
+            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';
+        }
+    }
+}

package/plugins/workflow-runner/src/stepPipeline.ts

@@ -0,0 +1,366 @@
+/**
+ * ============================================================
+ *  stepPipeline.ts —— 「一步算完成」的唯一实现
+ * ------------------------------------------------------------
+ *  ⚠️ 这个文件存在的理由是一次真实的架构事故。
+ *
+ *  重构前，「提交一步」这套动作（绑 capture → 累加目标补充 → 写 progress →
+ *  落 vars → 记 checkpoint → 发 step_end）**没有单一实现**，被 `runSteps` 里的
+ *  各个内联块各抄一份。抄到什么程度：
+ *
+ *      recordCheckpoint  × 7      appendProgress   × 17
+ *      writeVars         × 7      step_end 事件    × 19
+ *      bindCapture       × 3      collectCaptured  × 5
+ *
+ *  而且**已经漂移出真 bug**：7 处 checkpoint 里，`set` 传 `resolved`、
+ *  `echo` 传 `{}`、其余 5 处传 `collectCaptured(step.capture, vars)`。
+ *  顺着查下去发现 `echo` / `set` 从不调 `bindCapture` ——
+ *  **它们静默忽略 `capture:`**：yaml 作者写了既不报错也不生效，
+ *  resume 时那个变量也回放不出来。又一次「静默失效」。
+ *
+ *  所以这里的规则是硬的：**任何 step 完成后都必须经过 `commitStep`。**
+ *  新增 step 类型时不要再自己写这套 —— 抄一份就是又埋一颗漂移的种子。
+ *  `plugins/workflow-runner/test/stepPipeline.test.ts` 钉着这条。
+ * ============================================================
+ */
+
+import type { LoopEvent } from '../../../src/plugin-sdk.js';
+import { isMaxTurnsCutoff } from './agentCommon.js';
+import { runRecovery } from './recovery.js';
+import type {
+  RunContext,
+  StepDef,
+  StepKind,
+  StepResult,
+  WorkflowEvent,
+} from './types.js';
+import { normalizeCapture, VarStack } from './types.js';
+import type { WorkflowState } from './workflowState.js';
+
+const WF_PLUGIN_ID = 'workflow-runner';
+
+/**
+ * checkpoint 记录范围（替代旧 isTopLevel 布尔）：
+ *   - 顶层 runSteps：name = 原样 stepId，descendIntoLoop = true
+ *   - 顶层 loop 的 do[]：name = 复合名（loopId@@迭代号@@stepId），descendIntoLoop = false
+ *   - 更深嵌套（branch.then / loop 内 loop 的 do[]）：undefined，不记录
+ */
+export interface CpScope {
+  name: (stepId: string) => string;
+  descendIntoLoop: boolean;
+}
+
+/** 读 `a.b.c` 形式的嵌套字段。 */
+function readPath(root: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let cur: unknown = root;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[p];
+  }
+  return cur;
+}
+
+/**
+ * 把本步产出绑到变量上，**并把「绑了个空」响亮说出来**。
+ *
+ * ⚠️ `capture` 的写法是 `{ 结果字段: 变量名 }`。写反了（`{ 变量名: 结果字段 }`）
+ * 语法完全合法、加载期查不出来，运行时只是安静地绑一个 undefined —— 然后：
+ *   · `${varName}` 插值发一条「模板变量未定义」的 warning，但那条指向的是**使用处**，
+ *     看着像是「后面那步写错了」，而真正错的是**几十行之前的 capture**
+ *   · 更糟的是 assert：条件直接判假，用户看到的是 onFail 里那段业务文案，
+ *     与真实原因毫无关系，排查方向被彻底带偏
+ *
+ * 实测踩过两次（`adaptive-research.yaml` 绑 `content` 而 agent 步只有 `text`；
+ * `wechat-reading-shots.yaml` 把 `text: pager` 写反成 `pager: text`）。
+ */
+export function bindCapture(
+  captureMap: Record<string, string> | string,
+  result: StepResult,
+  vars: VarStack,
+  stepId?: string,
+): string[] {
+  const warnings: string[] = [];
+  for (const [resultField, varName] of Object.entries(normalizeCapture(captureMap))) {
+    const value = resultField.includes('.')
+      ? readPath(result.raw, resultField)
+      : result.raw[resultField];
+    if (value === undefined) {
+      const available = Object.keys(result.raw);
+      warnings.push(
+        `step "${stepId ?? '?'}": capture 取不到字段 \`${resultField}\`，变量 `
+          + `\`${varName}\` 绑成了 undefined。本步实际可绑的字段：`
+          + `${available.length ? available.map((k) => `\`${k}\``).join('、') : '（无）'}。`
+          + `⚠️ 写法是 { 结果字段: 变量名 }，检查是否写反了。`,
+      );
+    }
+    vars.set(varName, value);
+  }
+  return warnings;
+}
+
+/** 取本步 capture 出的 { varName: value }，供 checkpoint 记录（resume 回放用）。 */
+export function collectCaptured(
+  captureMap: Record<string, string> | string | undefined,
+  vars: VarStack,
+): Record<string, unknown> {
+  if (!captureMap) return {};
+  const out: Record<string, unknown> = {};
+  for (const varName of Object.values(normalizeCapture(captureMap))) {
+    out[varName] = vars.get(varName);
+  }
+  return out;
+}
+
+/** 从 StepResult 里取「可当作用户补充要求」的那段文本。 */
+function supplementTextOf(result: StepResult): string {
+  return typeof result.raw.text === 'string' && result.raw.text.trim()
+    ? result.raw.text
+    : String(result.raw.result ?? result.preview ?? '');
+}
+
+export interface CommitInput {
+  step: StepDef;
+  result: StepResult;
+  kind: StepKind;
+  vars: VarStack;
+  ctx: RunContext;
+  state: WorkflowState;
+  cp?: CpScope;
+  /**
+   * progress.md 的行首标记与后缀。缺省 `✓ <id> (<kind>)`；
+   * 恢复成功时传 `⚠→✓ <id> recovered`（保持旧文案逐字一致）。
+   */
+  progressLine?: string;
+  /** 累加用户补充要求的钩子（由 runner 注入，避免本模块反向依赖 runner）。 */
+  addGoalSupplement: (text: string) => Promise<void>;
+}
+
+/**
+ * 提交一步：capture → goal_supplement → progress → vars → checkpoint → step_end。
+ *
+ * **所有 step 类型的唯一收口。** 见文件头注：抄第二份就是埋漂移。
+ */
+export async function* commitStep(
+  input: CommitInput,
+): AsyncGenerator<WorkflowEvent | LoopEvent, void, void> {
+  const { step, result, kind, vars, state, cp } = input;
+
+  if (step.capture) {
+    for (const message of bindCapture(step.capture, result, vars, step.id)) {
+      yield { type: 'warning', message };
+    }
+  }
+
+  // goal_supplement：本步产出作为用户补充要求贯穿后续每一步（如 stage0 澄清结论）
+  if (step.goal_supplement) {
+    await input.addGoalSupplement(supplementTextOf(result));
+  }
+
+  await state.appendProgress(input.progressLine ?? `✓ ${step.id} (${kind})`);
+  await state.writeVars(vars.snapshot());
+
+  // checkpoint：记录范围见 CpScope（顶层步 + 顶层 loop 的 do[] 一层）。
+  //
+  // 回放变量 = 本步**引入的**变量（`replayVars`，目前只有 set）
+  //          + 作者**显式声明**要捕获的变量（`capture`）。
+  // 两者不能互相替代：set 步通常没有 capture，只记 collectCaptured 会得到 {} ——
+  // resume 跳过它之后下游断言就查不到那个变量了（engineRobustness 抓过这个回归）。
+  if (cp) {
+    await state.recordCheckpoint(
+      cp.name(step.id),
+      result.preview,
+      { ...(result.replayVars ?? {}), ...collectCaptured(step.capture, vars) },
+      vars.snapshot(),
+    );
+  }
+
+  yield {
+    type: 'workflow_step_end',
+    id: step.id,
+    ok: true,
+    output: result.preview,
+  };
+}
+
+/** 可中断的 sleep：中断时立刻返回，不把整轮退避耗完。 */
+function sleepInterruptible(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((res) => {
+    if (signal?.aborted) return res();
+    const t = setTimeout(done, ms);
+    function done(): void {
+      clearTimeout(t);
+      signal?.removeEventListener('abort', done);
+      res();
+    }
+    signal?.addEventListener('abort', done, { once: true });
+  });
+}
+
+export type StepOutcome = 'ok' | 'halted' | 'degraded';
+
+export interface RunStepInput {
+  step: StepDef;
+  kind: StepKind;
+  vars: VarStack;
+  ctx: RunContext;
+  state: WorkflowState;
+  cp?: CpScope;
+  /** 本步在当前 block 里的位置，仅用于 plugin_progress 的 current/max。 */
+  index: number;
+  total: number;
+  addGoalSupplement: (text: string) => Promise<void>;
+  /** 每次尝试都重新调用，拿到一个全新的执行生成器。 */
+  execute: () => AsyncGenerator<LoopEvent, StepResult, void>;
+}
+
+/**
+ * 执行一个动作步：in-run 重试 → onError 三态 → 统一提交。
+ *
+ * 三条语义原样保留（都是实测踩出来的）：
+ *   · `max_retries` 是**额外**重试次数，总尝试 = 1 + maxRetries
+ *   · 退避是**线性**的（delayBase × attempt）；maxTurns 截断走 `max_turns_retry_delay_ms`，
+ *     缺省 0 = 立即续跑（长文档类工作流才需要给模型端留恢复窗口）
+ *   · `onError:'recover'` 有**验证闸门**：只有恢复 agent 真正交付才绑 capture 走下去，
+ *     显式放弃 / 产出不可信一律带原因 honest halt，绝不盲绑脏值
+ */
+export async function* runStepWithRetry(
+  input: RunStepInput,
+): AsyncGenerator<WorkflowEvent | LoopEvent, StepOutcome, void> {
+  const { step, kind, vars, ctx, state, cp } = input;
+  const maxRetries = step.max_retries ?? ctx.selfHealMaxRetries ?? 0;
+  let attempt = 0;
+
+  while (true) {
+    try {
+      const result = yield* input.execute();
+      yield* commitStep({
+        step,
+        result,
+        kind,
+        vars,
+        ctx,
+        state,
+        ...(cp ? { cp } : {}),
+        addGoalSupplement: input.addGoalSupplement,
+      });
+      return 'ok';
+    } catch (e) {
+      const errMsg = (e as Error).message ?? String(e);
+
+      // in-run retry：还有重试额度且未中断 → 重跑同一步（不动 onError）。
+      if (attempt < maxRetries && !ctx.signal?.aborted) {
+        attempt++;
+        const isMaxTurns = isMaxTurnsCutoff(errMsg);
+        const delayBase = isMaxTurns
+          ? (ctx.maxTurnsRetryDelayMs ?? 0)
+          : (ctx.retryDelayMs ?? 0);
+        const delayMs = delayBase * attempt;
+        const retryKind = isMaxTurns ? '轮数预算用尽，可续跑截断' : '失败';
+        await state.appendProgress(
+          isMaxTurns
+            ? `↻ ${step.id}: 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}`
+            : `↻ ${step.id}: ${retryKind}，重试 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}（${errMsg}）`,
+        );
+        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: input.index + 1,
+          max: input.total,
+          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: input.index + 1,
+          max: input.total,
+          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) {
+          yield* commitStep({
+            step,
+            result: rec.value,
+            kind,
+            vars,
+            ctx,
+            state,
+            ...(cp ? { cp } : {}),
+            progressLine: `⚠→✓ ${step.id} recovered`,
+            addGoalSupplement: input.addGoalSupplement,
+          });
+          return 'ok';
+        }
+        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 };
+        return 'degraded';
+      }
+
+      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';
+    }
+  }
+}