minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,140 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill 步骤执行器
+ * ------------------------------------------------------------
+ *  v0.9 重构：不再使用独立 subHistory 隔离子循环，而是委托主 TAOR 引擎
+ *  （runQuery / src/loop.ts）在共享 ctx.history 上执行。
+ *
+ *  实现要点：
+ *    - 双源查找：cwd/skills/<name>/SKILL.md 优先，packageRoot/skills/ fallback
+ *    - SKILL.md body 作为用户提示的一部分（系统提示词已在 history[0]）
+ *    - 执行结果直接写入共享 ctx.history，上下文自然积累
+ *    - 流式转发：runQuery yield 的事件直接透传给 UI
+ *    - maxTurns 可在 step 里覆盖（默认 25）
+ *
+ *  capture：{ text: var_name } / { result: var_name }
+ * ============================================================
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import {
+  type LoopEvent,
+  getResourceSearchPaths,
+} from '../../../../src/plugin-sdk.js';
+import {
+  describeLlmFailure,
+  describeMaxTurnsCutoff,
+  effectiveGoalAnchor,
+  runStepQuery,
+} from '../agentCommon.js';
+import { interpolate } from '../expressions.js';
+import { effectiveWorkflowCwd } from '../toolRuntime.js';
+import type { RunContext, StepDef, StepResult, VarStack } from '../types.js';
+
+function stripFrontmatter(content: string): string {
+  return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+}
+
+function parseFrontmatterName(content: string): string | null {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const nm = m[1].match(/^name:\s*(.+)$/m);
+  if (!nm) return null;
+  return nm[1].trim().replace(/^["']|["']$/g, '');
+}
+
+async function findSkillFile(
+  skillName: string,
+  cwd: string,
+): Promise<string | null> {
+  const roots = getResourceSearchPaths('skills', import.meta.url, cwd);
+
+  for (const root of roots) {
+    let entries: { name: string; isDirectory: () => boolean }[];
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const skillFile = join(root, e.name, 'SKILL.md');
+      if (e.name === skillName) return skillFile;
+      try {
+        const md = await readFile(skillFile, 'utf8');
+        if (parseFrontmatterName(md) === skillName) return skillFile;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+export async function* execSkillStep(
+  step: StepDef,
+  vars: VarStack,
+  ctx: RunContext,
+): AsyncGenerator<LoopEvent, StepResult, void> {
+  if (!step.skill) throw new Error(`step ${step.id}: 缺少 skill 字段`);
+  const skillName = interpolate(step.skill, vars);
+
+  const skillFile = await findSkillFile(skillName, effectiveWorkflowCwd(ctx));
+  if (!skillFile) {
+    throw new Error(
+      `step ${step.id}: 未找到 skill "${skillName}"（cwd/skills/ 与 packageRoot/skills/ 双源均未命中）`,
+    );
+  }
+  const md = await readFile(skillFile, 'utf8');
+  const body = stripFrontmatter(md).trim();
+
+  // 构造用户提示：skill 指令 + 步骤 input
+  // 系统提示词已在 history[0] 中（含完整 skill 列表和描述），
+  // 这里不需要再拼 system message——把 SKILL.md body 作为操作指令即可
+  const missing: string[] = [];
+  const userInput = step.input
+    ? interpolate(step.input, vars, { onMissing: (e) => missing.push(e) })
+    : `请按以下 SKILL "${skillName}" 的指示完成任务。`;
+
+  const fullPrompt = `【执行 Skill：${skillName}】\n\n${body}\n\n---\n\n当前任务：\n${userInput}`;
+
+  // 通用目标锚定（原始目标 + 补充要求）：确保 skill 执行时也不偏离
+  const anchor = effectiveGoalAnchor(ctx);
+  const effectivePrompt = anchor ? `${anchor}\n\n${fullPrompt}` : fullPrompt;
+
+  const maxTurns = step.maxTurns ?? 25;
+
+  if (missing.length > 0) {
+    yield {
+      type: 'warning',
+      message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
+    };
+  }
+
+  // 委托 TAOR 引擎在共享 history 上执行（共享消费层 runStepQuery）。
+  // suppressTurnDone：turn_done 是 runQuery 单次调用的终结标记，不是 workflow 终结，
+  // 外泄会导致 gateway broker / -p json 模式误判 workflow 中途结束。
+  const { rawText, aborted, sawLlmError, sawMaxTurns, llmErrorDetail } =
+    yield* runStepQuery(effectivePrompt, step, ctx, {
+      maxTurns,
+      suppressTurnDone: true,
+    });
+
+  const trimmed = rawText.trim();
+
+  // P0-1：LLM 失败（超时/网络错）且本步无任何产出 → 抛异常，触发 runner 的 max_retries 重跑。
+  // 用户中断（aborted）不该被当成可重试失败，按现状返回空结果即可。
+  if (!trimmed && sawLlmError && !aborted) {
+    throw new Error(describeLlmFailure(step.id, llmErrorDetail));
+  }
+
+  // 撞 maxTurns 截断 → 截断时产出不可信，抛可重试失败（续作语义，同 agent.ts）
+  if (sawMaxTurns && !aborted) {
+    throw new Error(describeMaxTurnsCutoff(step.id, maxTurns));
+  }
+
+  return {
+    raw: { text: trimmed, result: trimmed },
+    preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}...` : trimmed,
+  };
+}

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

@@ -25,12 +25,16 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { executeTool, getToolByName, recordRead, } from '../../../../src/plugin-sdk.js';
 import { interpolateDeep } from '../expressions.js';
+import { buildWorkflowToolContext, effectiveWorkflowCwd, } from '../toolRuntime.js';
 export async function* execToolStep(step, vars, ctx) {
     if (!step.tool)
         throw new Error(`step ${step.id}: 缺少 tool 字段`);
     const tool = getToolByName(step.tool);
     if (!tool)
         throw new Error(`step ${step.id}: 未知工具 "${step.tool}"`);
+    if (!ctx.tools.some((available) => available.name === tool.name)) {
+        throw new Error(`step ${step.id}: 工具 "${tool.name}" 不在当前宿主授权的 Workflow 工具集中`);
+    }
     // 未定义变量插值可见化（args 里静默空串会让工具拿到空路径/空内容）
     const missing = [];
     const args = interpolateDeep(step.args ?? {}, vars, {
@@ -53,20 +57,69 @@ export async function* execToolStep(step, vars, ctx) {
         argsFriendly: friendlyToolDesc(tool.name, args),
     };
     // ════ 声明产物覆盖判定（解 Write/Edit 的 pre-read 守卫） ════
-    // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 进程级 Map，
-    // 跨进程 / resume / 残留旧产物时必空）。确定性 tool 步的 args 是 yaml 作者
+    // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 按会话隔离，
+    // 跨进程 / resume / 残留旧产物时可能为空）。确定性 tool 步的 args 是 yaml 作者
     // 写死的，模型没有机会先 Read —— 目标文件若是工作流**声明的产物**
     // （def 级 + step 级 artifacts:，= 工作流自己拥有、本就要覆盖的文件），
     // 这里自动 pre-Read 一次解除守卫（管线动作，不 yield 事件、结果丢弃）。
     // 非声明产物的盲写保护原样生效；pre-Read 失败也不拦，让写工具自己报错。
     await preReadDeclaredArtifact(tool, args, step, ctx);
-    const result = await executeTool(tool.name, argsJson, ctx.signal);
+    // 宿主能力按 `uses:` 切片后转发。`executeTool` 的第四参此前从未传过 ——
+    // 这正是「workflow 里 ComputerUse 恒失败」的末端表现。
+    const pendingProgress = [];
+    let wakeProgress;
+    const toolContext = buildWorkflowToolContext(step, ctx, toolCallId, (message, detail) => {
+        pendingProgress.push({
+            type: 'tool_progress',
+            toolName: tool.name,
+            toolCallId,
+            message,
+            detail,
+        });
+        wakeProgress?.();
+    });
+    if ('error' in toolContext) {
+        throw new Error(`step ${step.id}: ${toolContext.error}`);
+    }
+    const dispatch = ctx.executeTool ?? executeTool;
+    let settled = false;
+    let result;
+    void dispatch(tool.name, argsJson, ctx.signal, toolContext)
+        .then((value) => {
+        result = value;
+    })
+        .catch((error) => {
+        result = {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    })
+        .finally(() => {
+        settled = true;
+        wakeProgress?.();
+    });
+    while (!settled || pendingProgress.length > 0) {
+        const progress = pendingProgress.shift();
+        if (progress) {
+            yield progress;
+            continue;
+        }
+        await new Promise((resolveWake) => {
+            wakeProgress = resolveWake;
+            if (settled || pendingProgress.length > 0)
+                resolveWake();
+        });
+        wakeProgress = undefined;
+    }
+    if (!result)
+        throw new Error(`step ${step.id}: 工具执行未返回结果`);
     yield {
         type: 'tool_end',
         toolName: tool.name,
         toolCallId,
         ok: result.ok,
         content: result.ok ? result.content : result.error,
+        metadata: result.metadata,
     };
     if (!result.ok) {
         throw new Error(result.error);
@@ -85,8 +138,24 @@ export async function* execToolStep(step, vars, ctx) {
         timestamp: Date.now(),
         id: crypto.randomUUID(),
     });
+    // ⚠️ 工具返回的图片**不能丢**。此前这里只取 content，`visionImages` 被静默丢弃 ——
+    // 于是任何「截图/看图」类工作流都拿不到产物，而且不会报错，只是后面的评估步没图可看。
+    // 取路径而不是整个 ImageInputSpec：yaml 侧要的是能 capture、能传给 llm 步 `images:`
+    // 的字符串；结构体传下去反而要每个消费方各自解包。
+    const images = (result.visionImages ?? [])
+        .map((image) => (typeof image.source === 'string' ? image.source : ''))
+        .filter((path) => path.length > 0);
     return {
-        raw: { content, result: content, args },
+        raw: {
+            content,
+            result: content,
+            args,
+            images,
+            metadata: result.metadata,
+            recovery: result.recovery,
+            sensitivity: result.sensitivity,
+            visionNote: result.visionNote,
+        },
         preview: content.length > 200 ? `${content.slice(0, 200)}...` : content,
     };
 }
@@ -103,14 +172,17 @@ async function preReadDeclaredArtifact(tool, args, step, ctx) {
     if (typeof args.file_path !== 'string')
         return;
     const norm = (p) => {
-        const abs = resolve(ctx.cwd, p);
+        const abs = resolve(effectiveWorkflowCwd(ctx), p);
         return process.platform === 'win32' ? abs.toLowerCase() : abs;
     };
     const target = norm(args.file_path);
-    const declared = [...(ctx.declaredArtifacts ?? []), ...(step.artifacts ?? [])];
+    const declared = [
+        ...(ctx.declaredArtifacts ?? []),
+        ...(step.artifacts ?? []),
+    ];
     if (!declared.some((a) => norm(a) === target))
         return;
-    const abs = resolve(ctx.cwd, args.file_path);
+    const abs = resolve(effectiveWorkflowCwd(ctx), args.file_path);
     if (!existsSync(abs))
         return; // 新建文件不需要解守卫
     // 直接登记一次「完整已读」状态解除内核 pre-read 守卫——不真正 Read 内容：
@@ -121,7 +193,7 @@ async function preReadDeclaredArtifact(tool, args, step, ctx) {
     //      （首轮新建 PLAN.md 不存在直接放行，审批反馈后回写已存在的大 PLAN.md 被挡死）。
     //   两道守卫（never-read + truncated）必须一并解除，声明产物的整体覆盖才算真正授权。
     // recordRead 内部自带 statSync 失败兜底（返回 1、不抛），无需再包 try/catch。
-    recordRead(abs, { truncated: false });
+    recordRead(abs, { truncated: false }, ctx.sessionState?.fileReads);
 }
 /**
  * 给 tool_start 生成人话描述（LiveArea spinner 行用）。

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

@@ -0,0 +1,256 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/stepExecutors/tool.ts —— tool step 执行
+ * ------------------------------------------------------------
+ *  把 step.args 递归 ${var} 插值后 JSON.stringify，转发到 executeTool。
+ *  失败（ok=false）抛 Error，让 runner 走 onError 处理。
+ *
+ *  v2（P1 TUI 可见）：本执行器改为 AsyncGenerator，在调 executeTool 前后
+ *  yield 通用 tool_start / tool_end LoopEvent —— 这样 workflow 的 tool 步骤
+ *  在 TUI 里像普通 ReAct 工具调用一样显示（runningTools spinner + 人话描述）。
+ *
+ *  v0.9.3（上下文统一修复）：tool 步骤执行后把工具调用摘要写入 ctx.history，
+ *  让后续 agent/llm/skill 步骤（走 runQuery → LLM）能自然看到前面步骤的工作成果，
+ *  不再依赖 VarStack 变量插值作为唯一的信息传递通道。
+ *  这实现了"一套上下文"架构：workflow 的每一步都在共享的 TAOR history 中留痕。
+ *
+ *  capture 字段（支持点路径）：
+ *    - `{ content: var_name }`      绑 ToolResult.content（工具回执文本）
+ *    - `{ result: var_name }`       同义，给"无结构化字段"工具用
+ *    - `{ args.content: var_name }` 绑插值后传给工具的入参（如真正写入的内容）
+ *    - `{ args.<任意字段>: var_name }` 绑入参的具名字段
+ * ============================================================
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  type LoopEvent,
+  type ToolResult,
+  executeTool,
+  getToolByName,
+  recordRead,
+} from '../../../../src/plugin-sdk.js';
+import { interpolateDeep } from '../expressions.js';
+import {
+  buildWorkflowToolContext,
+  effectiveWorkflowCwd,
+} from '../toolRuntime.js';
+import type { RunContext, StepDef, StepResult, VarStack } from '../types.js';
+
+export async function* execToolStep(
+  step: StepDef,
+  vars: VarStack,
+  ctx: RunContext,
+): AsyncGenerator<LoopEvent, StepResult, void> {
+  if (!step.tool) throw new Error(`step ${step.id}: 缺少 tool 字段`);
+  const tool = getToolByName(step.tool);
+  if (!tool) throw new Error(`step ${step.id}: 未知工具 "${step.tool}"`);
+  if (!ctx.tools.some((available) => available.name === tool.name)) {
+    throw new Error(
+      `step ${step.id}: 工具 "${tool.name}" 不在当前宿主授权的 Workflow 工具集中`,
+    );
+  }
+
+  // 未定义变量插值可见化（args 里静默空串会让工具拿到空路径/空内容）
+  const missing: string[] = [];
+  const args = interpolateDeep(step.args ?? {}, 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）`,
+    };
+  }
+  const argsJson = JSON.stringify(args);
+  const toolCallId = `wf_${step.id}`;
+  const argsPreview =
+    argsJson.length > 80 ? `${argsJson.slice(0, 80)}…` : argsJson;
+
+  yield {
+    type: 'tool_start',
+    toolName: tool.name,
+    toolCallId,
+    argsPreview,
+    argsFriendly: friendlyToolDesc(tool.name, args as Record<string, unknown>),
+  };
+
+  // ════ 声明产物覆盖判定（解 Write/Edit 的 pre-read 守卫） ════
+  // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 按会话隔离，
+  // 跨进程 / resume / 残留旧产物时可能为空）。确定性 tool 步的 args 是 yaml 作者
+  // 写死的，模型没有机会先 Read —— 目标文件若是工作流**声明的产物**
+  // （def 级 + step 级 artifacts:，= 工作流自己拥有、本就要覆盖的文件），
+  // 这里自动 pre-Read 一次解除守卫（管线动作，不 yield 事件、结果丢弃）。
+  // 非声明产物的盲写保护原样生效；pre-Read 失败也不拦，让写工具自己报错。
+  await preReadDeclaredArtifact(
+    tool,
+    args as Record<string, unknown>,
+    step,
+    ctx,
+  );
+
+  // 宿主能力按 `uses:` 切片后转发。`executeTool` 的第四参此前从未传过 ——
+  // 这正是「workflow 里 ComputerUse 恒失败」的末端表现。
+  const pendingProgress: LoopEvent[] = [];
+  let wakeProgress: (() => void) | undefined;
+  const toolContext = buildWorkflowToolContext(
+    step,
+    ctx,
+    toolCallId,
+    (message, detail) => {
+      pendingProgress.push({
+        type: 'tool_progress',
+        toolName: tool.name,
+        toolCallId,
+        message,
+        detail,
+      });
+      wakeProgress?.();
+    },
+  );
+  if ('error' in toolContext) {
+    throw new Error(`step ${step.id}: ${toolContext.error}`);
+  }
+
+  const dispatch = ctx.executeTool ?? executeTool;
+  let settled = false;
+  let result: ToolResult | undefined;
+  void dispatch(tool.name, argsJson, ctx.signal, toolContext)
+    .then((value) => {
+      result = value;
+    })
+    .catch((error: unknown) => {
+      result = {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    })
+    .finally(() => {
+      settled = true;
+      wakeProgress?.();
+    });
+
+  while (!settled || pendingProgress.length > 0) {
+    const progress = pendingProgress.shift();
+    if (progress) {
+      yield progress;
+      continue;
+    }
+    await new Promise<void>((resolveWake) => {
+      wakeProgress = resolveWake;
+      if (settled || pendingProgress.length > 0) resolveWake();
+    });
+    wakeProgress = undefined;
+  }
+  if (!result) throw new Error(`step ${step.id}: 工具执行未返回结果`);
+
+  yield {
+    type: 'tool_end',
+    toolName: tool.name,
+    toolCallId,
+    ok: result.ok,
+    content: result.ok ? result.content : result.error,
+    metadata: result.metadata,
+  };
+
+  if (!result.ok) {
+    throw new Error(result.error);
+  }
+  const content = result.content;
+
+  // ════ v0.9.3：上下文统一 —— 把工具调用写入共享 history ════
+  // 后续 agent/llm/skill 步骤走 runQuery() 时，LLM 能在上下文中看到
+  // 这步做了什么（与正常 TAOR 循环中 tool_call → tool_result 的记录方式一致）。
+  // 只记录精简摘要（不把完整工具回执塞入 history，避免 token 浪费）。
+  const summary =
+    content.length > 500
+      ? `${content.slice(0, 500)}…（已截断，共 ${content.length} 字符）`
+      : content;
+  ctx.history.push({
+    role: 'assistant',
+    content: `[workflow:${step.id}] ✅ ${tool.name} 执行完成：${summary}`,
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  });
+
+  // ⚠️ 工具返回的图片**不能丢**。此前这里只取 content，`visionImages` 被静默丢弃 ——
+  // 于是任何「截图/看图」类工作流都拿不到产物，而且不会报错，只是后面的评估步没图可看。
+  // 取路径而不是整个 ImageInputSpec：yaml 侧要的是能 capture、能传给 llm 步 `images:`
+  // 的字符串；结构体传下去反而要每个消费方各自解包。
+  const images = (result.visionImages ?? [])
+    .map((image) => (typeof image.source === 'string' ? image.source : ''))
+    .filter((path) => path.length > 0);
+
+  return {
+    raw: {
+      content,
+      result: content,
+      args,
+      images,
+      metadata: result.metadata,
+      recovery: result.recovery,
+      sensitivity: result.sensitivity,
+      visionNote: result.visionNote,
+    },
+    preview: content.length > 200 ? `${content.slice(0, 200)}...` : content,
+  };
+}
+
+/**
+ * 写类 tool 步的目标文件若命中声明产物且已存在 → pre-Read 解除内核守卫。
+ *
+ * 路径归一化：artifacts 声明相对 cwd；args.file_path 可能是 ./相对 或 绝对，
+ * 双方都 resolve(cwd, …) 后比较（win32 文件系统大小写不敏感 → lowercase 比较；
+ * 其余平台保持大小写敏感，避免 Plan.md / plan.md 误判同文件）。
+ */
+async function preReadDeclaredArtifact(
+  tool: { name: string; isReadOnly?: boolean },
+  args: Record<string, unknown>,
+  step: StepDef,
+  ctx: RunContext,
+): Promise<void> {
+  if (tool.isReadOnly !== false) return; // 只对写类工具生效
+  if (typeof args.file_path !== 'string') return;
+
+  const norm = (p: string): string => {
+    const abs = resolve(effectiveWorkflowCwd(ctx), p);
+    return process.platform === 'win32' ? abs.toLowerCase() : abs;
+  };
+  const target = norm(args.file_path);
+  const declared = [
+    ...(ctx.declaredArtifacts ?? []),
+    ...(step.artifacts ?? []),
+  ];
+  if (!declared.some((a) => norm(a) === target)) return;
+
+  const abs = resolve(effectiveWorkflowCwd(ctx), args.file_path);
+  if (!existsSync(abs)) return; // 新建文件不需要解守卫
+
+  // 直接登记一次「完整已读」状态解除内核 pre-read 守卫——不真正 Read 内容：
+  //   1. 声明产物本就要被本步整体覆盖，旧内容无需进上下文/烧 token；
+  //   2. 真 Read 大文件会触发字符上限截断（read.ts → recordRead({truncated:true})），
+  //      反而踩中 Write 的「截断禁写」硬守卫（write.ts: existsSync && wasTruncated → 拒绝），
+  //      正是本步要解除的同一道墙——曾导致 plan.yaml 回写变长的 PLAN.md 时 halt
+  //      （首轮新建 PLAN.md 不存在直接放行，审批反馈后回写已存在的大 PLAN.md 被挡死）。
+  //   两道守卫（never-read + truncated）必须一并解除，声明产物的整体覆盖才算真正授权。
+  // recordRead 内部自带 statSync 失败兜底（返回 1、不抛），无需再包 try/catch。
+  recordRead(abs, { truncated: false }, ctx.sessionState?.fileReads);
+}
+
+/**
+ * 给 tool_start 生成人话描述（LiveArea spinner 行用）。
+ */
+function friendlyToolDesc(
+  toolName: string,
+  args: Record<string, unknown>,
+): string {
+  const key = ['file_path', 'command', 'query', 'pattern', 'path', 'url'].find(
+    (k) => typeof args[k] === 'string',
+  );
+  if (!key) return toolName;
+  const val = String(args[key]);
+  const short = val.length > 60 ? `${val.slice(0, 60)}…` : val;
+  return `${toolName} ${short}`;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/stepExecutors/verify.ts —— verify step 执行
+ * ------------------------------------------------------------
+ *  复用内核共享验证基础设施（经 plugin-sdk 门面取 runVerification/parseCheckString），
+ *  支持 shell / file_exists / file_contains / test_count 四种检查。
+ *
+ *  与 assert 的区别：
+ *    - assert: evalExpr 表达式（轻量，适合简单文件存在判断）
+ *    - verify: 完整检查器（重量，支持命令执行/正则匹配/测试计数）
+ * ============================================================
+ */
+
+import { parseCheckString, runVerification, type Check } from '../../../../src/plugin-sdk.js';
+import { interpolate } from '../expressions.js';
+import type { StepDef, StepResult, VarStack } from '../types.js';
+
+export async function execVerifyStep(
+  step: StepDef,
+  vars: VarStack,
+): Promise<StepResult> {
+  // 兼容两种格式：YAML 数组 或逗号分隔字符串。
+  // 关键：【先插值再按逗号分割】。checks 可能是 "${verify_checks}" 这类模板，插值后才
+  // 展开成逗号分隔的多项（如 "shell:bun test,file_exists:x"）。若先分割再插值，整段模板
+  // 会被当成一项，解析时 value 混入逗号、多项检查失效（ralph-loop 的 run_verify 即如此）。
+  let rawChecks: string[];
+  if (Array.isArray(step.checks) && step.checks.length > 0) {
+    rawChecks = (step.checks as string[])
+      .flatMap((s) => interpolate(s, vars).split(','))
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } else if (typeof step.checks === 'string' && step.checks.trim() !== '') {
+    rawChecks = interpolate(step.checks as string, vars)
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } else {
+    throw new Error(`step ${step.id}: verify 缺少 checks（需要数组或逗号分隔字符串）`);
+  }
+
+  // 解析每条已插值的 check 字符串（插值后若整体为空——如 ${verify_checks} 取到空串——
+  // 则 checks 为空，runVerification 视为"无检查项"通过；ralph-loop 另有 when 守卫不会走到这）
+  const checks: Check[] = [];
+  for (const raw of rawChecks) {
+    const check = parseCheckString(raw);
+    if (!check) {
+      throw new Error(
+        `step ${step.id}: 无法解析 check "${raw}"，格式应为 "type:value"`,
+      );
+    }
+    checks.push(check);
+  }
+
+  // 执行所有检查
+  const result = await runVerification(checks);
+
+  if (!result.passed) {
+    const msg = step.onFail
+      ? interpolate(step.onFail, vars)
+      : `verify 失败: ${result.summary}`;
+    throw new Error(msg);
+  }
+
+  return {
+    raw: { passed: true, summary: result.summary, details: result.details },
+    preview: result.summary,
+  };
+}