minimal-agent 0.1.8 → 0.2.0

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

@@ -0,0 +1,194 @@
+/**
+ * ============================================================
+ *  src/workflows/index.ts —— /workflow 与 /workflows 命令的胶水层
+ * ------------------------------------------------------------
+ *  作为 pluginRunner 与 runner 之间的桥：
+ *    - runWorkflowFromCommand：解析 /workflow <name> --input k=v args 调度
+ *    - runWorkflowsList：处理 /workflows 列表展示（yield "text" 事件让 UI 显示）
+ *
+ *  R1 红线：本文件只在 pluginRunner 命中 workflow 模式时才被 import。
+ *  不污染默认 T-A-O-R 路径。
+ * ============================================================
+ */
+
+import { findWorkflowByName, listWorkflows } from './loader.ts';
+import { runWorkflow } from './runner.ts';
+import type { InputDef, RunContext, WorkflowEvent } from './types.ts';
+import type { LoopEvent, Message, Provider } from '../../../src/plugin-sdk.ts';
+
+export interface RunWorkflowFromCommandOptions {
+  provider: Provider;
+  history: Message[];
+  signal?: AbortSignal;
+}
+
+/**
+ * 把 "/workflow <name> --input k=v --input k2=v2" 拆成 name + inputs。
+ * 简单解析器（不依赖第三方）：
+ *   - 第一个非 flag token = name
+ *   - --input k=v 重复
+ *   - 不识别其他 flag（P0 不报错，仅 console.warn）
+ */
+export function parseWorkflowArgs(rawArgs: string): {
+  name: string | null;
+  inputs: Record<string, string>;
+} {
+  const tokens = tokenizeArgs(rawArgs);
+  const inputs: Record<string, string> = {};
+  let name: string | null = null;
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === '--input') {
+      const kv = tokens[i + 1];
+      if (!kv) break;
+      const eq = kv.indexOf('=');
+      if (eq > 0) {
+        inputs[kv.slice(0, eq)] = kv.slice(eq + 1);
+      }
+      i++;
+      continue;
+    }
+    if (t.startsWith('--')) {
+      // 未知 flag：跳过其后一个 token（保守地认为它带值）
+      i++;
+      continue;
+    }
+    if (name === null) {
+      name = t;
+    }
+  }
+  return { name, inputs };
+}
+
+/** 简单 token 化：双引号包裹的整体当一个 token；其它按空白切。 */
+function tokenizeArgs(s: string): string[] {
+  const out: string[] = [];
+  let i = 0;
+  while (i < s.length) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) break;
+    if (s[i] === '"' || s[i] === "'") {
+      const q = s[i];
+      i++;
+      let acc = '';
+      while (i < s.length && s[i] !== q) {
+        acc += s[i++];
+      }
+      if (i < s.length) i++;
+      out.push(acc);
+    } else {
+      let acc = '';
+      while (i < s.length && !/\s/.test(s[i])) {
+        acc += s[i++];
+      }
+      out.push(acc);
+    }
+  }
+  return out;
+}
+
+/**
+ * 把字符串形态的 input 值按 InputDef.type 转成合适的 JS 类型 + 校验。
+ * 校验失败抛 Error，pluginRunner 会把它转成 error event。
+ */
+function coerceInputs(
+  raw: Record<string, string>,
+  defs: InputDef[] | undefined,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!defs) return { ...raw };
+
+  for (const def of defs) {
+    const rawVal = raw[def.name];
+    if (rawVal === undefined) {
+      if (def.required) {
+        throw new Error(`缺少必填 input: ${def.name}`);
+      }
+      if (def.default !== undefined) {
+        out[def.name] = def.default;
+      }
+      continue;
+    }
+    if (def.type === 'number') {
+      const n = parseFloat(rawVal);
+      if (Number.isNaN(n)) throw new Error(`input ${def.name} 必须是数字，收到 "${rawVal}"`);
+      out[def.name] = n;
+    } else if (def.type === 'enum') {
+      if (!def.values?.includes(rawVal)) {
+        throw new Error(
+          `input ${def.name} 必须是 [${def.values?.join(', ')}] 之一，收到 "${rawVal}"`,
+        );
+      }
+      out[def.name] = rawVal;
+    } else {
+      out[def.name] = rawVal;
+    }
+  }
+  // 未声明的 input 也透传（让 yaml 里可以引用 ad-hoc 变量）
+  for (const k of Object.keys(raw)) {
+    if (!(k in out)) out[k] = raw[k];
+  }
+  return out;
+}
+
+/** /workflow <name> [--input k=v] —— 主入口，由 pluginRunner 调用。 */
+export async function* runWorkflowFromCommand(
+  rawArgs: string,
+  opts: RunWorkflowFromCommandOptions,
+): AsyncGenerator<WorkflowEvent | LoopEvent, void, void> {
+  const { name, inputs: rawInputs } = parseWorkflowArgs(rawArgs);
+  if (!name) {
+    yield {
+      type: 'error',
+      error:
+        '/workflow 用法: /workflow <name> [--input key=val ...]\n输入 /workflows 查看可用工作流。',
+    };
+    return;
+  }
+  const def = await findWorkflowByName(name);
+  if (!def) {
+    yield {
+      type: 'error',
+      error: `未找到 workflow "${name}"。输入 /workflows 查看可用列表。`,
+    };
+    return;
+  }
+
+  let coerced: Record<string, unknown>;
+  try {
+    coerced = coerceInputs(rawInputs, def.inputs);
+  } catch (e) {
+    yield { type: 'error', error: (e as Error).message };
+    return;
+  }
+
+  const ctx: RunContext = {
+    provider: opts.provider,
+    signal: opts.signal,
+    history: opts.history,
+  };
+
+  yield* runWorkflow(def, coerced, ctx);
+}
+
+/** /workflows —— 列出可用 workflow。yield 一条 text 事件让 UI 显示。 */
+export async function* runWorkflowsList(): AsyncGenerator<LoopEvent, void, void> {
+  const list = await listWorkflows();
+  if (list.length === 0) {
+    yield {
+      type: 'text',
+      delta:
+        '当前没有可用工作流。在 cwd/workflows/ 下放 *.yaml 即可（参考 workflows/schema.json 或 docs/workflow-design.md）。\n',
+    };
+    yield { type: 'turn_done' };
+    return;
+  }
+  const lines = ['可用工作流：'];
+  for (const w of list) {
+    lines.push(`  /workflow ${w.name}  —  ${w.description.split('\n')[0].trim()}`);
+  }
+  lines.push('');
+  lines.push('运行示例: /workflow <name> --input key=val');
+  yield { type: 'text', delta: lines.join('\n') + '\n' };
+  yield { type: 'turn_done' };
+}

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

@@ -0,0 +1,193 @@
+/**
+ * ============================================================
+ *  src/workflows/loader.ts —— workflow yaml 双源加载 + 最小校验
+ * ------------------------------------------------------------
+ *  - 扫描 cwd/workflows/ 与 packageRoot/workflows/（cwd 优先，复用
+ *    getResourceSearchPaths 契约）
+ *  - 一个坏 yaml 不应拖累其它工作流（catch 单文件错误，继续扫描）
+ *  - 目录不存在 / 为空 → 静默返回 []（默认 T-A-O-R 不受影响）
+ *
+ *  P0 不引 AJV；下面手写 ≤80 行的最小校验器，只挡死硬性错误：
+ *    - name / description / steps 必填且类型正确
+ *    - steps 非空
+ *    - 每个 step 必须有且只有一个动作字段（tool / skill / llm / type）
+ *
+ *  P1 切 AJV 做完整 schema。
+ * ============================================================
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { parse as parseYamlLib } from 'yaml';
+
+import { getResourceSearchPaths } from '../../../src/plugin-sdk.ts';
+import type { StepDef, WorkflowDef } from './types.ts';
+
+export class WorkflowLoadError extends Error {
+  constructor(message: string, public readonly file?: string) {
+    super(message);
+    this.name = 'WorkflowLoadError';
+  }
+}
+
+/**
+ * 扫描双源目录，返回所有 *.yaml / *.yml 解析后的 workflow。
+ * 永远不抛；坏文件 console.warn 并跳过。
+ */
+export async function listWorkflows(): Promise<WorkflowDef[]> {
+  const out: WorkflowDef[] = [];
+  const seen = new Set<string>();
+  const roots = getResourceSearchPaths('workflows', import.meta.url);
+
+  for (const root of roots) {
+    let entries: string[];
+    try {
+      entries = await readdir(root);
+    } catch {
+      continue;
+    }
+    for (const f of entries) {
+      if (!f.endsWith('.yaml') && !f.endsWith('.yml')) continue;
+      const full = join(root, f);
+      try {
+        const def = await parseWorkflowFile(full);
+        if (!seen.has(def.name)) {
+          seen.add(def.name);
+          out.push(def);
+        }
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        console.warn(`[workflows] 忽略损坏的 yaml ${full}: ${(e as Error).message}`);
+      }
+    }
+  }
+  return out;
+}
+
+/** 按 name 查找。找不到返回 null —— 调用方决定如何提示用户。 */
+export async function findWorkflowByName(name: string): Promise<WorkflowDef | null> {
+  const all = await listWorkflows();
+  return all.find((w) => w.name === name) ?? null;
+}
+
+/** 读单个 yaml 文件 → 解析 → 校验。失败抛 WorkflowLoadError。 */
+export async function parseWorkflowFile(file: string): Promise<WorkflowDef> {
+  let raw: string;
+  try {
+    raw = await readFile(file, 'utf8');
+  } catch (e) {
+    throw new WorkflowLoadError(`无法读取 ${file}: ${(e as Error).message}`, file);
+  }
+  let data: unknown;
+  try {
+    data = parseYamlLib(raw);
+  } catch (e) {
+    throw new WorkflowLoadError(`yaml 语法错误: ${(e as Error).message}`, file);
+  }
+  if (!data || typeof data !== 'object') {
+    throw new WorkflowLoadError('yaml 根节点必须是对象', file);
+  }
+  validate(data as Record<string, unknown>, file);
+  const def = data as WorkflowDef;
+  def.__source = file;
+  return def;
+}
+
+// ---------------- 手写最小校验 ----------------
+
+function validate(obj: Record<string, unknown>, file: string): void {
+  if (typeof obj.name !== 'string' || obj.name.length === 0) {
+    throw new WorkflowLoadError("缺少必填字段 'name'（string）", file);
+  }
+  if (typeof obj.description !== 'string' || obj.description.length === 0) {
+    throw new WorkflowLoadError("缺少必填字段 'description'（string）", file);
+  }
+  if (!Array.isArray(obj.steps) || obj.steps.length === 0) {
+    throw new WorkflowLoadError("缺少必填字段 'steps' 或为空数组", file);
+  }
+  validateSteps(obj.steps as unknown[], file, '');
+  if (obj.inputs !== undefined) {
+    if (!Array.isArray(obj.inputs)) {
+      throw new WorkflowLoadError("'inputs' 必须是数组", file);
+    }
+    for (const [i, item] of (obj.inputs as unknown[]).entries()) {
+      if (!item || typeof item !== 'object') {
+        throw new WorkflowLoadError(`inputs[${i}] 必须是对象`, file);
+      }
+      const r = item as Record<string, unknown>;
+      if (typeof r.name !== 'string' || r.name.length === 0) {
+        throw new WorkflowLoadError(`inputs[${i}].name 必填`, file);
+      }
+      if (r.type !== undefined && r.type !== 'string' && r.type !== 'number' && r.type !== 'enum') {
+        throw new WorkflowLoadError(`inputs[${i}].type 必须是 string/number/enum`, file);
+      }
+      if (r.type === 'enum' && (!Array.isArray(r.values) || r.values.length === 0)) {
+        throw new WorkflowLoadError(`inputs[${i}].values 必填（type=enum 时）`, file);
+      }
+    }
+  }
+}
+
+function validateSteps(steps: unknown[], file: string, pathPrefix: string): void {
+  const seenIds = new Set<string>();
+  for (const [i, item] of steps.entries()) {
+    const p = pathPrefix ? `${pathPrefix}.steps[${i}]` : `steps[${i}]`;
+    if (!item || typeof item !== 'object') {
+      throw new WorkflowLoadError(`${p} 必须是对象`, file);
+    }
+    const s = item as Record<string, unknown>;
+    if (typeof s.id !== 'string' || s.id.length === 0) {
+      throw new WorkflowLoadError(`${p}.id 必填`, file);
+    }
+    // id 唯一仅在同级 steps 数组内强制
+    if (seenIds.has(s.id)) {
+      throw new WorkflowLoadError(`${p}.id "${s.id}" 在当前 steps 列表中重复`, file);
+    }
+    seenIds.add(s.id);
+
+    // 动作字段恰好一个
+    const actionFields: (keyof StepDef)[] = ['tool', 'skill', 'llm', 'type'];
+    const present = actionFields.filter((k) => s[k] !== undefined);
+    if (present.length === 0) {
+      throw new WorkflowLoadError(
+        `${p} 必须有以下字段之一: tool / skill / llm / type`,
+        file,
+      );
+    }
+    if (present.length > 1) {
+      throw new WorkflowLoadError(
+        `${p} 同时设置了 ${present.join(', ')}；只允许其中一个`,
+        file,
+      );
+    }
+
+    // 控制流字段一致性
+    if (s.type === 'branch' && s.condition === undefined) {
+      throw new WorkflowLoadError(`${p} type=branch 必须带 'condition'`, file);
+    }
+    if (s.type === 'loop') {
+      if (s.over === undefined) throw new WorkflowLoadError(`${p} type=loop 必须带 'over'`, file);
+      if (typeof s.as !== 'string' || s.as.length === 0) {
+        throw new WorkflowLoadError(`${p} type=loop 必须带 'as'`, file);
+      }
+      if (!Array.isArray(s.do)) {
+        throw new WorkflowLoadError(`${p} type=loop 必须带 'do' 数组`, file);
+      }
+      validateSteps(s.do as unknown[], file, `${p}.do`);
+    }
+    if (s.type === 'assert' && s.condition === undefined) {
+      throw new WorkflowLoadError(`${p} type=assert 必须带 'condition'`, file);
+    }
+    if (s.type === 'branch') {
+      if (s.then !== undefined && !Array.isArray(s.then)) {
+        throw new WorkflowLoadError(`${p}.then 必须是数组`, file);
+      }
+      if (s.else !== undefined && !Array.isArray(s.else)) {
+        throw new WorkflowLoadError(`${p}.else 必须是数组`, file);
+      }
+      if (Array.isArray(s.then)) validateSteps(s.then as unknown[], file, `${p}.then`);
+      if (Array.isArray(s.else)) validateSteps(s.else as unknown[], file, `${p}.else`);
+    }
+  }
+}

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

@@ -0,0 +1,313 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/runner.ts —— workflow 顺序执行器
+ * ------------------------------------------------------------
+ *  AsyncGenerator，按 yaml.steps[] 顺序执行：
+ *    - when: 不满足 → yield workflow_step_skipped
+ *    - 命中动作字段 → 调对应 step executor
+ *    - capture: 把 result.raw 上的字段绑到 VarStack
+ *    - onError: halt（默认）→ yield error 后 return；continue → 记录后跳过
+ *    - 信号 abort → yield interrupted 后 return
+ *
+ *  支持的 step kind（loader 已校验）：
+ *    - tool / llm / assert    —— 原子动作（execXxxStep 返回 StepResult）
+ *    - skill                  —— 迷你 ReAct 子循环（透传子事件 + 累计 text）
+ *    - branch / loop / pause  —— 控制流，直接在 runSteps 内处理（不走 executor）
+ *
+ *  控制流嵌套通过 runSteps 递归实现：branch.then/else / loop.do 子数组
+ *  是 StepDef[]，调用方语义与顶层 def.steps 一致；变量栈用 VarStack.push/pop
+ *  在 loop 迭代间隔离 `${as}` / `${as}_idx`。
+ * ============================================================
+ */
+
+import { getWorkingDir, type LoopEvent } from '../../../src/plugin-sdk.ts';
+import { evalExpr, interpolate } from './expressions.ts';
+import { execAssertStep } from './stepExecutors/assert.ts';
+import { execLlmStep } from './stepExecutors/llm.ts';
+import { execSkillStep } from './stepExecutors/skill.ts';
+import { execToolStep } from './stepExecutors/tool.ts';
+import type {
+  RunContext,
+  StepDef,
+  StepKind,
+  StepResult,
+  WorkflowDef,
+  WorkflowEvent,
+} from './types.ts';
+import { VarStack } from './types.ts';
+import { WorkflowState } from './workflowState.ts';
+
+function stepKind(step: StepDef): StepKind {
+  if (step.type) return step.type;
+  if (step.tool) return 'tool';
+  if (step.skill) return 'skill';
+  if (step.llm) return 'llm';
+  return 'assert'; // 不会到这里（loader 已校验），兜底
+}
+
+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;
+}
+
+function bindCapture(
+  captureMap: Record<string, string>,
+  result: StepResult,
+  vars: VarStack,
+): void {
+  for (const [resultField, varName] of Object.entries(captureMap)) {
+    const value = resultField.includes('.')
+      ? readPath(result.raw, resultField)
+      : result.raw[resultField];
+    vars.set(varName, value);
+  }
+}
+
+/**
+ * 分发"动作"型 step（tool / llm / skill / assert）到对应 executor。
+ * 控制流 step（branch / loop / pause）由 runSteps 直接处理，不走这里。
+ */
+async function* dispatchActionStep(
+  step: StepDef,
+  vars: VarStack,
+  ctx: RunContext,
+): AsyncGenerator<LoopEvent, StepResult, void> {
+  if (step.type === 'assert') return execAssertStep(step, vars);
+  if (step.tool) return await execToolStep(step, vars, ctx);
+  if (step.llm) return await execLlmStep(step, vars, ctx);
+  if (step.skill) return yield* execSkillStep(step, vars, ctx);
+  throw new Error(`step ${step.id}: 无可执行字段（tool/llm/skill/assert）`);
+}
+
+/**
+ * 递归执行 steps[]。返回 true 表示该 block 已 halt（上游应中止）。
+ *
+ * yields 混合事件：WorkflowEvent + LoopEvent（skill 子循环转发 / error / interrupted）。
+ * index/total 字段相对**当前 block**，嵌套 block 自有计数（branch.then 内 3 步就报 total=3）。
+ */
+async function* runSteps(
+  steps: StepDef[],
+  vars: VarStack,
+  ctx: RunContext,
+  state: WorkflowState,
+): AsyncGenerator<WorkflowEvent | LoopEvent, boolean, void> {
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (ctx.signal?.aborted) {
+      yield { type: 'interrupted' };
+      return true;
+    }
+
+    // when 条件
+    if (step.when) {
+      let pass = false;
+      try {
+        pass = Boolean(evalExpr(interpolate(step.when, vars), vars));
+      } catch (e) {
+        const errMsg = `when 表达式错误: ${(e as Error).message}`;
+        yield {
+          type: 'workflow_step_end',
+          id: step.id,
+          ok: false,
+          error: errMsg,
+        };
+        yield {
+          type: 'error',
+          error: `Workflow halted at step "${step.id}": ${errMsg}`,
+        };
+        return true;
+      }
+      if (!pass) {
+        yield {
+          type: 'workflow_step_skipped',
+          id: step.id,
+          reason: 'when=false',
+        };
+        await state.appendProgress(`- ${step.id} skipped (when=false)`);
+        continue;
+      }
+    }
+
+    const kind = stepKind(step);
+    yield {
+      type: 'workflow_step_start',
+      id: step.id,
+      kind,
+      index: i,
+      total: steps.length,
+    };
+
+    // ---------- 控制流：branch ----------
+    if (step.type === 'branch') {
+      let cond = false;
+      try {
+        cond = Boolean(evalExpr(interpolate(step.condition ?? 'false', vars), 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 true;
+      }
+      const branch = cond ? step.then : step.else;
+      if (Array.isArray(branch) && branch.length > 0) {
+        const childHalted = yield* runSteps(branch, vars, ctx, state);
+        if (childHalted) return true;
+      }
+      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;
+    }
+
+    // ---------- 控制流：loop ----------
+    if (step.type === 'loop') {
+      let arr: unknown;
+      try {
+        arr = evalExpr(interpolate(step.over ?? '[]', vars), 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 true;
+      }
+      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 true;
+      }
+      const asName = step.as ?? 'item';
+      let iterCount = 0;
+      for (let idx = 0; idx < arr.length; idx++) {
+        if (ctx.signal?.aborted) {
+          yield { type: 'interrupted' };
+          return true;
+        }
+        vars.push();
+        vars.set(asName, arr[idx]);
+        vars.set(`${asName}_idx`, idx);
+        const childHalted = yield* runSteps(step.do ?? [], vars, ctx, state);
+        vars.pop();
+        if (childHalted) return true;
+        iterCount++;
+      }
+      await state.appendProgress(`✓ ${step.id} (loop ×${iterCount})`);
+      await state.writeVars(vars.snapshot());
+      yield {
+        type: 'workflow_step_end',
+        id: step.id,
+        ok: true,
+        output: `loop ${iterCount} 次`,
+      };
+      continue;
+    }
+
+    // ---------- 控制流：pause ----------
+    //
+    // 非交互模式（CLI -p / 测试）下无法真的暂停等待人工，直接当成 skipped。
+    // 交互模式（TUI）需要 UI 层接住 step_skipped 把 reason 渲染出来 —— P0 已
+    // 走通这条 UI 路径。step.prompt 用于把"暂停理由"传给上层呈现。
+    if (step.type === 'pause') {
+      const msg = step.prompt
+        ? interpolate(step.prompt, vars)
+        : 'pause（非交互模式直接跳过）';
+      await state.appendProgress(`- ${step.id} pause: ${msg}`);
+      yield {
+        type: 'workflow_step_skipped',
+        id: step.id,
+        reason: `pause: ${msg}`,
+      };
+      yield {
+        type: 'workflow_step_end',
+        id: step.id,
+        ok: true,
+        output: 'paused (skipped in non-interactive mode)',
+      };
+      continue;
+    }
+
+    // ---------- 普通动作 step：tool / llm / skill / assert ----------
+    try {
+      const result = yield* dispatchActionStep(step, vars, ctx);
+      if (step.capture) bindCapture(step.capture, result, vars);
+      await state.appendProgress(`✓ ${step.id} (${kind})`);
+      await state.writeVars(vars.snapshot());
+      yield {
+        type: 'workflow_step_end',
+        id: step.id,
+        ok: true,
+        output: result.preview,
+      };
+    } catch (e) {
+      const errMsg = (e as Error).message ?? String(e);
+      await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
+      if (step.onError === 'continue') {
+        yield {
+          type: 'workflow_step_end',
+          id: step.id,
+          ok: false,
+          error: errMsg,
+        };
+        continue;
+      }
+      yield {
+        type: 'workflow_step_end',
+        id: step.id,
+        ok: false,
+        error: errMsg,
+      };
+      yield {
+        type: 'error',
+        error: `Workflow halted at step "${step.id}": ${errMsg}`,
+      };
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * 运行一个 workflow。
+ *
+ * yields 混合事件：本地 WorkflowEvent（workflow_* 系列，UI 静默忽略不渲染）
+ * + 通用 LoopEvent（error / interrupted 等，UI 识别并渲染）。
+ * 经 plugin.ts -> pluginRunner 透传给 UI；workflow_* 由 PluginEvent 开放契约承载。
+ */
+export async function* runWorkflow(
+  def: WorkflowDef,
+  inputs: Record<string, unknown>,
+  ctx: RunContext,
+): AsyncGenerator<WorkflowEvent | LoopEvent, void, void> {
+  const vars = new VarStack();
+  vars.setGlobal('inputs', inputs);
+
+  const state = new WorkflowState(getWorkingDir());
+  await state.init(def.name, inputs);
+
+  yield {
+    type: 'workflow_start',
+    name: def.name,
+    totalSteps: def.steps.length,
+  };
+
+  try {
+    const halted = yield* runSteps(def.steps, vars, ctx, state);
+    if (halted) return;
+    yield { type: 'workflow_done', name: def.name, vars: vars.snapshot() };
+  } finally {
+    await state.cleanup();
+  }
+}