minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/test/foundation.test.ts

@@ -0,0 +1,126 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/test/foundation.test.ts
+ * ------------------------------------------------------------
+ *  锁定 workflow-runner 的两条【地基保证】——yaml 作者不用每步重写：
+ *    B1 目标锚定：引擎在每个 agent/llm/skill 步前自动注入"用户原始目标"
+ *       （buildGoalAnchor → ctx.goalAnchor），即使 yaml 的步 prompt 没手写 ${goal}。
+ *    B2 系统提示（含技能清单）跨 fresh_context 存活：新版 plan.yaml 把 6 阶段套进
+ *       fresh_context while-loop，每轮重置 history——必须保证重置到的是"含技能的入口
+ *       快照"，否则重来轮的步就看不到 skills，正是上次 pptx 翻车的同类病根。
+ *
+ *  方法：DI 注入 ctx.chat（真实 runWorkflow/runQuery 跑起来，仅替换最底层 chat），
+ *  抓每次 chat 调用的完整 messages 快照，断言每轮迭代里 system[0]（技能标记）与
+ *  步 prompt（目标原文）都在。禁用 mock.module（全局泄漏），用 env+reset 隔离 cwd。
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { ALL_TOOLS } from '../../../src/tools/index.js';
+import type { LoopEvent, Message, Provider } from '../../../src/types.js';
+import { runWorkflow } from '../src/runner.js';
+import type { RunContext, WorkflowDef, WorkflowEvent } from '../src/types.js';
+
+type WfOrLoop = WorkflowEvent | LoopEvent;
+
+const fakeProvider: Provider = {
+  name: 'test',
+  baseURL: '',
+  apiKey: '',
+  model: 'm',
+  contextWindow: 128000,
+};
+
+async function collect(
+  gen: AsyncGenerator<WfOrLoop, void, void>,
+): Promise<WfOrLoop[]> {
+  const out: WfOrLoop[] = [];
+  for await (const ev of gen) out.push(ev);
+  return out;
+}
+
+describe('workflow-runner 地基保证：目标锚定 + 技能清单跨 fresh_context 存活', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-found-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    // 预置一个"含技能清单标记"的系统提示——模拟 refreshWorkflowSystemPrompt 注入后的
+    // history[0]（真注入由 pluginRunner.isolation.test.ts 单独锁定，这里只测"重置后仍在"）。
+    ctx = {
+      provider: fakeProvider,
+      history: [
+        {
+          role: 'system',
+          content: '系统提示\n\n## pptx\n- **功能**: 生成 PPT\n- **技能目录**: `skills/pptx`',
+        },
+      ],
+      cwd: tmp,
+      tools: ALL_TOOLS,
+    };
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('fresh_context while-loop 每轮：技能清单仍在 system[0]，原始目标经锚定仍在步 prompt（步未手写 goal）', async () => {
+    const GOAL = '实现哨兵目标_SENTINEL_XYZ';
+
+    // 步 prompt 故意【不】提目标——这样若目标仍出现在消息里，必是 goalAnchor 注入的（B1）。
+    const def: WorkflowDef = {
+      name: 'foundcheck',
+      description: '地基回归',
+      inputs: [{ name: 'goal', type: 'string', required: true }],
+      self_heal: { retry_delay_ms: 0 },
+      steps: [
+        {
+          type: 'loop',
+          id: 'lp',
+          max_iterations: 2,
+          fresh_context: true,
+          as: '_iter',
+          do: [{ id: 'only_step', llm: '请只输出 OK，不要解释。', max_retries: 0 }],
+        },
+      ],
+    };
+
+    const snapshots: Array<Array<{ role: string; content: string }>> = [];
+    ctx.chat = async function* (args: { messages: Message[] }) {
+      // messages 是 runQuery 原地 mutate 的共享引用，必须当场快照成文本
+      snapshots.push(
+        args.messages.map((m) => ({ role: m.role, content: String(m.content ?? '') })),
+      );
+      yield { type: 'text_delta', delta: 'OK' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const events = await collect(runWorkflow(def, { goal: GOAL }, ctx));
+
+    // 整链正常收尾（达上限 2 退出，非 halt）
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(
+      events.some((e) => e.type === 'error' && e.error.includes('Workflow halted')),
+    ).toBe(false);
+
+    // 2 轮迭代 → 2 次 chat 调用
+    expect(snapshots.length).toBe(2);
+    for (const msgs of snapshots) {
+      // B2：每轮 system[0] 仍含技能清单（fresh_context 重置到的是"含技能的入口快照"）
+      expect(msgs[0].role).toBe('system');
+      expect(msgs[0].content).toContain('## pptx');
+      expect(msgs[0].content).toContain('技能目录');
+      // B1：步 prompt 没手写 ${inputs.goal}，但原始目标经 goalAnchor 注入仍在末条消息里
+      expect(msgs[msgs.length - 1].content).toContain(GOAL);
+    }
+  }, 30000);
+});

package/plugins/workflow-runner/test/graceful.test.ts

@@ -0,0 +1,139 @@
+/**
+ * ============================================================
+ *  test/workflows/graceful.test.ts
+ * ------------------------------------------------------------
+ *  降级契约（R1）：
+ *    - workflows/ 不存在 → listWorkflows() 返回包内自带 [包内 yaml]，绝不抛错
+ *    - 全是坏 yaml → 跳过坏的，列出好的
+ *    - findWorkflowByName 未命中 → 返回 null（让调用方 yield 友好 error）
+ *    - runWorkflowFromCommand 对未知 name → yield error，不污染 history
+ *    - runWorkflowsList 在空列表时 yield 友好提示
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { listWorkflows } from '../src/loader.js';
+import {
+  runWorkflowFromCommand,
+  runWorkflowsList,
+} from '../src/index.js';
+import type { LoopEvent, Provider } from '../../../src/types.js';
+import type { WorkflowEvent } from '../src/types.js';
+
+type WfOrLoop = WorkflowEvent | LoopEvent;
+
+const fakeProvider: Provider = {
+  name: 'test',
+  baseURL: '',
+  apiKey: '',
+  model: 'm',
+  contextWindow: 128000,
+};
+
+async function collect(
+  gen: AsyncGenerator<WfOrLoop, void, void>,
+): Promise<WfOrLoop[]> {
+  const out: WfOrLoop[] = [];
+  for await (const ev of gen) out.push(ev);
+  return out;
+}
+
+describe('workflows/graceful', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-graceful-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    mock.module('../../../src/bootstrap/workingDir.js', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('cwd 下无 workflows/ 目录 → listWorkflows() 仍返回（packageRoot fallback 也只是空降级，不抛）', async () => {
+    const list = await listWorkflows();
+    // 至少应该包含包内自带的 book-review-short
+    expect(Array.isArray(list)).toBe(true);
+  });
+
+  it('cwd 下 workflows/ 全空 → 不抛，不增加任何条目', async () => {
+    mkdirSync(join(tmp, 'workflows'), { recursive: true });
+    const list = await listWorkflows();
+    expect(Array.isArray(list)).toBe(true);
+  });
+
+  it('cwd 下全是坏 yaml → 不抛，只跳过坏的', async () => {
+    mkdirSync(join(tmp, 'workflows'), { recursive: true });
+    writeYamlIn(tmp, 'bad1.yaml', 'name: x\n  : weird:::\n');
+    writeYamlIn(tmp, 'bad2.yaml', '@@@@@@\n');
+    const list = await listWorkflows();
+    // 不抛错，至少包内自带的仍然可见
+    expect(Array.isArray(list)).toBe(true);
+  });
+
+  it('/workflow unknown-name → yield error，无 workflow_start', async () => {
+    const events = await collect(
+      runWorkflowFromCommand('definitely-not-a-real-wf-xyz', {
+        provider: fakeProvider,
+        history: [],
+      }),
+    );
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_start')).toBe(false);
+  });
+
+  it('/workflow（不带 name）→ yield 用法提示 error', async () => {
+    const events = await collect(
+      runWorkflowFromCommand('', {
+        provider: fakeProvider,
+        history: [],
+      }),
+    );
+    const err = events.find(
+      (e): e is Extract<LoopEvent, { type: 'error' }> => e.type === 'error',
+    );
+    expect(err).toBeDefined();
+    expect(err!.error).toContain('/workflow');
+  });
+
+  it('/workflows 列表 yield text 事件 + turn_done', async () => {
+    const events = await collect(runWorkflowsList());
+    expect(events.some((e) => e.type === 'text')).toBe(true);
+    expect(events[events.length - 1].type).toBe('turn_done');
+  });
+
+  it('缺必填 input → yield error，不进入 runWorkflow', async () => {
+    // book-review-short 要求 book 必填
+    const events = await collect(
+      runWorkflowFromCommand('book-review-short', {
+        provider: fakeProvider,
+        history: [],
+      }),
+    );
+    const err = events.find(
+      (e): e is Extract<LoopEvent, { type: 'error' }> => e.type === 'error',
+    );
+    expect(err).toBeDefined();
+    expect(err!.error).toContain('book');
+    // 没有 workflow_start
+    expect(events.some((e) => e.type === 'workflow_start')).toBe(false);
+  });
+});
+
+function writeYamlIn(root: string, name: string, body: string) {
+  mkdirSync(join(root, 'workflows'), { recursive: true });
+  writeFileSync(join(root, 'workflows', name), body, 'utf8');
+}

package/plugins/workflow-runner/test/greedyInputs.load.test.ts

@@ -0,0 +1,47 @@
+/**
+ * test/greedyInputs.load.test.ts
+ * ------------------------------------------------------------
+ * 锁定「自然语言首参」工作流的首个 input 标了 greedy:true——这样命令行里
+ * workflow 名之后的整句（含空格分隔段）会被 join 进首参、不逐位拆映射、不撞
+ * 后面的 number/enum 类型。根治「打一句话自然语言 → pos2 撞 number/enum 报错
+ * 或单输入被静默截断」那一类 footgun（ppt 的 `input pages 必须是数字` 即此类）。
+ *
+ * 同时校验 loader 红线：greedy 只能标在第 0 个 input（防误标）。
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { join } from 'node:path';
+
+import { parseWorkflowFile } from '../src/loader.js';
+
+const WF_DIR = join(
+  import.meta.dir.replace(/[/\\]test$/, ''), // plugins/workflow-runner
+  '..', // plugins
+  '..', // 仓库根
+  'workflows',
+);
+
+// 所有「首参是自然语言 brief」的工作流——都应让首参 greedy 吸收整句。
+const GREEDY_FIRST = [
+  'webppt',
+  'plan',
+  'ralph-loop',
+  'youtube-shorts',
+  'adaptive-research',
+  'book-review-short',
+];
+
+describe('自然语言首参工作流：首个 input 标 greedy', () => {
+  for (const name of GREEDY_FIRST) {
+    it(`${name}.yaml 的首个 input greedy===true`, async () => {
+      const def = await parseWorkflowFile(join(WF_DIR, `${name}.yaml`));
+      const first = (def.inputs ?? [])[0];
+      expect(first).toBeDefined();
+      expect(first?.greedy).toBe(true);
+      // greedy 只许标在第 0 位（loader 红线）——后续 input 不得再标。
+      for (const inp of (def.inputs ?? []).slice(1)) {
+        expect(inp.greedy).not.toBe(true);
+      }
+    });
+  }
+});

package/plugins/workflow-runner/test/hostCapability.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from 'bun:test';
+import { VALID_HOST_CAPABILITIES } from '../src/loader.js';
+
+/**
+ * 宿主能力上下文：从框架 → 插件 → workflow → 工具 的四层透传。
+ *
+ * ⚠️ 这条链路此前**断在第一层**：`pluginRunner` 有三处把宿主能力往下传，两条 runQuery
+ * 路径都带了 browserRun/computerRun，**唯独 `api.runCommand(...)` 那一处漏了**。
+ * 于是 `PluginContext` 比 `RunQueryOptions` 窄，富插件（workflow-runner）永远拿不到
+ * 宿主授权 —— 表现是 workflow 里调 ComputerUse 恒返回「当前宿主未启用 Computer Use」，
+ * 而同一个工具在主循环里好好的。症状完全指不向那个漏掉的字段。
+ *
+ * 所以这组测试的第一条守的就是那处遗漏本身。
+ */
+
+describe('框架侧：runCommand 必须带上 host', () => {
+  test('★ 回归守卫：pluginRunner 给富插件传 host', async () => {
+    const source = await Bun.file(
+      new URL('../../../src/plugins/pluginRunner.ts', import.meta.url),
+    ).text();
+    // 定位 api.runCommand(...) 那次调用，确认 host 在它的参数对象里
+    const at = source.indexOf('api.runCommand(');
+    expect(at).toBeGreaterThan(-1);
+    const call = source.slice(at, at + 900);
+    expect(call).toContain('host:');
+    expect(call).toContain('computerRun');
+    expect(call).toContain('browserRun');
+    expect(call).toContain('executeTool: options.executeTool');
+  });
+
+  test('PluginContext 用 Pick<ToolCallContext> 绑定，而不是重新声明', async () => {
+    // 重新声明会和 ToolCallContext 各自漂移；Pick 保证改一处两处同步。
+    const source = await Bun.file(
+      new URL('../../../src/plugins/pluginApi.ts', import.meta.url),
+    ).text();
+    expect(source).toMatch(/host\?:\s*Pick<\s*ToolCallContext/);
+  });
+});
+
+describe('能力常量单一来源', () => {
+  test('loader 的白名单与 types 的 HostCapability 一致', async () => {
+    // 两处不一致的表现是：yaml 写了某个能力、loader 放行、运行时却识别不了，
+    // 或反过来 loader 拦掉一个其实支持的能力。都属于静默错。
+    const types = await Bun.file(
+      new URL('../src/types.ts', import.meta.url),
+    ).text();
+    const declared =
+      /export type HostCapability =([^;]+);/.exec(types)?.[1] ?? '';
+    const fromTypes = [...declared.matchAll(/'([a-z]+)'/g)]
+      .map((m) => m[1])
+      .sort();
+    expect(fromTypes).toEqual([...VALID_HOST_CAPABILITIES].sort());
+  });
+});
+
+describe('loader 对 uses 的加载期校验', () => {
+  const load = async (stepYaml: string) => {
+    const { parseWorkflowFile } = await import('../src/loader.js');
+    const { mkdtemp, writeFile } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    const { tmpdir } = await import('node:os');
+    const dir = await mkdtemp(join(tmpdir(), 'wf-uses-'));
+    const file = join(dir, 't.yaml');
+    await writeFile(
+      file,
+      `name: t\ndescription: d\nversion: "0.1"\nsteps:\n${stepYaml}\n`,
+    );
+    return parseWorkflowFile(file);
+  };
+
+  test('合法声明通过', async () => {
+    await expect(
+      load(`  - id: a
+    tool: ComputerUse
+    uses: [computer]
+    args: { action: observe }`),
+    ).resolves.toBeDefined();
+  });
+
+  test('★ 拼错的能力名在**加载期**就拦掉', async () => {
+    // 不拦的话：yaml 安静地拿不到能力，而工具报的是「当前宿主未启用 Computer Use」——
+    // 那句话完全指不向拼错的这一行，作者会去查宿主配置而不是查 yaml。
+    await expect(
+      load(`  - id: a
+    tool: ComputerUse
+    uses: [compute]
+    args: { action: observe }`),
+    ).rejects.toThrow(/uses 含非法能力/);
+  });
+
+  test('uses 必须是数组', async () => {
+    await expect(
+      load(`  - id: a
+    tool: ComputerUse
+    uses: computer
+    args: { action: observe }`),
+    ).rejects.toThrow(/必须是数组/);
+  });
+
+  test('uses 只能用在 tool 步 —— 写在 agent/llm 步上是作者的误解', async () => {
+    // agent/llm/skill 走 runQuery，工具上下文由主循环提供；在这些步上声明既无效也误导。
+    await expect(
+      load(`  - id: a
+    agent: "做点事"
+    uses: [computer]`),
+    ).rejects.toThrow(/只能用在 tool 步/);
+  });
+});

package/plugins/workflow-runner/test/illustrate.load.test.ts

@@ -0,0 +1,183 @@
+/**
+ * test/illustrate.load.test.ts
+ * ------------------------------------------------------------
+ * 锁定 workflows/illustrate.yaml（网上抓图配图：Google→Bing→Baidu 有序降级 → 下载 →
+ * 逐图识图打分跳广告 → 选 count 张）的「可解析 + 关键骨架」：
+ *   - name=illustrate；inputs: topic(greedy 首位) + count + min_candidates
+ *   - 纯 YAML：WebBrowser(navigate/eval) 抓 URL + parseJson 成数组 + Download 落盘 + llm images: 打分
+ *   - 有序降级：Bing/Baidu 步 when 受 min_candidates 守门；各家 set 用 asArray(parseJson(...))
+ *   - download/score 两个 loop over asArray(urls)；select agent done_when illustrations.json
+ *   - 用到本轮新增的两个通用件：parseJson 表达式 + Download 工具
+ *   - 所有 ${} 表达式可被引擎解析
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { join } from 'node:path';
+
+import { interpolate } from '../src/expressions.js';
+import { parseWorkflowFile } from '../src/loader.js';
+import { VarStack } from '../src/types.js';
+import type { StepDef } from '../src/types.js';
+
+const wfPath = join(
+  import.meta.dir.replace(/[/\\]test$/, ''),
+  '..',
+  '..',
+  'workflows',
+  'illustrate.yaml',
+);
+
+function allStrings(def: unknown): string[] {
+  const out: string[] = [];
+  const walk = (v: unknown): void => {
+    if (typeof v === 'string') out.push(v);
+    else if (Array.isArray(v)) for (const x of v) walk(x);
+    else if (v && typeof v === 'object')
+      for (const x of Object.values(v as Record<string, unknown>)) walk(x);
+  };
+  walk(def);
+  return out;
+}
+
+describe('workflows/illustrate.yaml（网上抓图配图）', () => {
+  it('解析通过、name=illustrate、inputs 正确', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    expect(def.name).toBe('illustrate');
+    expect(typeof def.description).toBe('string');
+
+    const inputs = def.inputs ?? [];
+    const names = inputs.map((i) => i.name);
+    expect(names).toEqual(expect.arrayContaining(['topic', 'count', 'min_candidates']));
+    expect(names[0]).toBe('topic');
+    expect(inputs.find((i) => i.name === 'topic')?.greedy).toBe(true);
+    expect(inputs.find((i) => i.name === 'count')?.default).toBe(3);
+    expect(inputs.find((i) => i.name === 'min_candidates')?.default).toBe(6);
+    expect(def.artifacts).toContain('./build/illustrations.json');
+  });
+
+  it('关键步齐全且顺序正确：三家图搜 → 守门 → 下载 → 打分 → 选优 → 报告', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const ids = def.steps.map((s) => s.id);
+    for (const id of [
+      'init',
+      'g_nav',
+      'g_eval',
+      'g_set',
+      'b_nav',
+      'b_eval',
+      'b_set',
+      'd_nav',
+      'd_eval',
+      'd_set',
+      'assert_candidates',
+      'download_loop',
+      'score_loop',
+      'select',
+      'report',
+    ]) {
+      expect(ids).toContain(id);
+    }
+    expect(ids.indexOf('g_eval')).toBeLessThan(ids.indexOf('b_eval'));
+    expect(ids.indexOf('b_eval')).toBeLessThan(ids.indexOf('d_eval'));
+    expect(ids.indexOf('assert_candidates')).toBeLessThan(ids.indexOf('download_loop'));
+    expect(ids.indexOf('download_loop')).toBeLessThan(ids.indexOf('score_loop'));
+    expect(ids.indexOf('score_loop')).toBeLessThan(ids.indexOf('select'));
+    expect(ids.indexOf('select')).toBeLessThan(ids.indexOf('report'));
+  });
+
+  it('有序降级：Google 首选无 when；Bing/Baidu 受 min_candidates 守门；各家 set 用 asArray(parseJson)', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const byId = (id: string) => def.steps.find((s) => s.id === id);
+
+    expect(byId('g_nav')?.when).toBeUndefined(); // 首选无条件跑
+    expect(String(byId('b_nav')?.when)).toContain('min_candidates');
+    expect(String(byId('d_nav')?.when)).toContain('min_candidates');
+
+    for (const sid of ['g_set', 'b_set', 'd_set']) {
+      const s = byId(sid);
+      expect(s?.type).toBe('set');
+      const urlsVal = String((s?.set ?? {}).urls);
+      expect(urlsVal).toContain('asArray');
+      expect(urlsVal).toContain('parseJson');
+    }
+    expect((byId('g_set')?.set ?? {}).engine_used).toBe('google');
+    expect((byId('b_set')?.set ?? {}).engine_used).toBe('bing');
+    expect((byId('d_set')?.set ?? {}).engine_used).toBe('baidu');
+
+    // eval 步用 WebBrowser eval 抽 URL、capture 原始输出
+    const ge = byId('g_eval');
+    expect(ge?.tool).toBe('WebBrowser');
+    expect((ge?.args ?? {}).action).toBe('eval');
+    expect((ge?.capture ?? {})).toHaveProperty('content', 'g_raw');
+    expect(ge?.onError).toBe('continue');
+  });
+
+  it('下载 loop：over asArray(urls)、Download 工具落盘 cand_${u_idx}', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const loop = def.steps.find((s) => s.id === 'download_loop');
+    expect(loop?.type).toBe('loop');
+    expect(String(loop?.over)).toContain('asArray');
+    expect(String(loop?.over)).toContain('urls');
+    expect(loop?.as).toBe('u');
+    const dl = ((loop?.do ?? []) as StepDef[]).find((s) => s.id === 'dl_one');
+    expect(dl?.tool).toBe('Download'); // ← 本轮新增的通用工具
+    expect(String((dl?.args ?? {}).path)).toContain('${u_idx}');
+    expect(String((dl?.args ?? {}).url)).toContain('${u}');
+    expect(dl?.onError).toBe('continue'); // 死链跳过
+  });
+
+  it('打分 loop：逐图 llm images: + 识广告，写 score 分文件', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const loop = def.steps.find((s) => s.id === 'score_loop');
+    expect(loop?.type).toBe('loop');
+    const dos = (loop?.do ?? []) as StepDef[];
+    const score = dos.find((s) => s.id === 'score_one');
+    expect(Array.isArray(score?.images)).toBe(true);
+    expect(String((score?.images ?? []).join(','))).toContain('${u_idx}');
+    expect(score?.image_detail).toBe('high');
+    const llm = String(score?.llm);
+    expect(llm).toContain('is_ad'); // 识别广告
+    expect(llm).toContain('relevance');
+    const write = dos.find((s) => s.id === 'write_score');
+    expect(write?.tool).toBe('Write');
+    expect(String((write?.args ?? {}).content)).toContain('score_text');
+  });
+
+  it('选优 select：剔广告排序取 count，agent 确定性落盘 illustrations.json', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const sel = def.steps.find((s) => s.id === 'select');
+    const a = String(sel?.agent);
+    expect(a).toContain('is_ad'); // 剔除广告
+    expect(a).toContain('relevance'); // 排序依据
+    expect(a).toContain('illustrations.json');
+    expect(String(sel?.done_when)).toContain('illustrations.json');
+    for (const t of ['Glob', 'Read', 'Write']) expect(sel?.allowed_tools).toContain(t);
+    expect(sel?.artifacts).toContain('./build/illustrations.json');
+  });
+
+  it('用到本轮新增通用件：parseJson 表达式 + Download 工具', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const strings = allStrings(def);
+    expect(strings.some((s) => s.includes('parseJson('))).toBe(true);
+    expect(def.steps.flatMap((s) => [s, ...((s.do ?? []) as StepDef[])]).some((s) => s.tool === 'Download')).toBe(true);
+  });
+
+  it('所有 ${} 表达式都能被引擎解析（不含畸形语法）', async () => {
+    const def = await parseWorkflowFile(wfPath);
+    const vars = new VarStack();
+    const inputsObj: Record<string, unknown> = {};
+    for (const inp of def.inputs ?? []) inputsObj[inp.name] = inp.default ?? '';
+    vars.setGlobal('inputs', inputsObj);
+    // 循环变量 u / u_idx（download/score loop 的 as）+ 捕获变量占位
+    vars.set('u', 'http://x/1.jpg');
+    vars.set('u_idx', 0);
+    vars.setGlobal('urls', []);
+    vars.setGlobal('engine_used', 'google');
+    vars.setGlobal('score_text', '{}');
+
+    for (const s of allStrings(def)) {
+      if (!s.includes('${')) continue;
+      expect(() => interpolate(s, vars)).not.toThrow();
+    }
+  });
+});