minimal-agent 0.12.0 → 0.14.0

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

@@ -1,366 +0,0 @@
-/**
- * ============================================================
- *  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';
-    }
-  }
-}