minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,226 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/test/engineRobustness.test.ts
+ * ------------------------------------------------------------
+ *  引擎健壮性包（v0.9.x 全面评审产出）回归锚，对应四个曾被实证的缺口：
+ *
+ *  E3 type:set —— 曾有 yaml 用 `llm:"PLAN"` 当赋值语句（模型自由回复非确定）；
+ *     set 是确定性赋值，状态机类工作流（ralph-loop phase）的根治。
+ *  E2 数字字段模板 —— max_iterations:"${inputs.n}" 曾不插值直接参与 < 比较
+ *     → NaN → 静默 0 次迭代；现在插值+coerce，失败响亮 halt。
+ *  E1 裸变量告警 —— 未定义变量插值为空串曾完全静默（裸 ${goal} 渲染为空的病根）；
+ *     现在 yield warning 列出表达式原文。
+ *  E4 括号内三元 —— (a ? b : c) 曾报「缺少 ')'」。
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } 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 type { LoopEvent, Provider } from '../../../src/types.js';
+import { evalExpr, interpolate } from '../src/expressions.js';
+import { runWorkflow } from '../src/runner.js';
+import { VarStack } from '../src/types.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('E4/E1 表达式层（纯单元，无文件系统）', () => {
+  it('括号内三元可用（E4）', () => {
+    const vars = new VarStack();
+    expect(evalExpr('(1 == 1 ? "a" : "b")', vars)).toBe('a');
+    // 函数实参内三元
+    vars.setGlobal('phase', 'PLAN');
+    expect(evalExpr('upper(phase == "PLAN" ? "go" : "stop")', vars)).toBe('GO');
+    // 数组元素内三元
+    expect(evalExpr('[true ? 1 : 2, false ? 3 : 4]', vars)).toEqual([1, 4]);
+  });
+
+  it('onMissing 钩子：未定义变量插值回调（E1），已定义不回调', () => {
+    const vars = new VarStack();
+    vars.setGlobal('inputs', { goal: '真目标' });
+    const missing: string[] = [];
+    const out = interpolate('A${goal}B${inputs.goal}C', vars, {
+      onMissing: (e) => missing.push(e),
+    });
+    expect(out).toBe('AB真目标C');
+    expect(missing).toEqual(['goal']); // 裸 goal 漏，inputs.goal 不漏
+  });
+});
+
+describe('E3/E2/E1 引擎层（runWorkflow 集成）', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-robust-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    mock.module('../../../src/bootstrap/workingDir.js', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: [] };
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('type:set 确定性赋值 + 插值 + 下游条件可靠（E3，零 LLM）', async () => {
+    const def: WorkflowDef = {
+      name: 'set-basic',
+      description: 'd',
+      inputs: [{ name: 'goal', type: 'string', required: true }],
+      steps: [
+        { id: 'init', type: 'set', set: { phase: 'PLAN', tag: 'g=${inputs.goal}' } },
+        { id: 'c1', type: 'assert', condition: 'phase == "PLAN"' },
+        { id: 'c2', type: 'assert', condition: 'tag == "g=目标X"' },
+        { id: 'adv', type: 'set', set: { phase: 'BUILD' } },
+        { id: 'c3', type: 'assert', condition: 'phase == "BUILD"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { goal: '目标X' }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    const start = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> =>
+        e.type === 'workflow_step_start' && e.id === 'init',
+    );
+    expect(start?.kind).toBe('set');
+  });
+
+  it('while loop 的 max_iterations 支持 ${inputs.n} 模板（E2 正路径）', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-template-n',
+      description: 'd',
+      inputs: [{ name: 'n', type: 'number', required: true }],
+      steps: [
+        { id: 'init', type: 'set', set: { count: 0 } },
+        {
+          id: 'lp',
+          type: 'loop',
+          max_iterations: '${inputs.n}',
+          do: [
+            // 用 set + _iter 累计：纯确定性，零 LLM
+            { id: 'bump', type: 'set', set: { count: '${_iter}' } },
+          ],
+        },
+        // 跑满 3 轮：最后一轮 _iter=2
+        { id: 'check', type: 'assert', condition: 'count == "2"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { n: 3 }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const lpEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'lp',
+    );
+    expect(lpEnd?.output).toContain('3 iterations');
+  });
+
+  it('max_iterations 模板解析失败（裸名未定义）→ 响亮 halt 而非静默 0 次（E2 反路径）', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-bad-n',
+      description: 'd',
+      steps: [
+        {
+          id: 'lp',
+          type: 'loop',
+          // 裸名 max_iterations（R1 事故原型）：插值为空串 → Number('')=0 → 必须响亮报错
+          max_iterations: '${max_iterations}',
+          do: [{ id: 'noop', type: 'assert', condition: 'true' }],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    const halt = events.find(
+      (e): e is { type: 'error'; error: string } =>
+        e.type === 'error' && e.error.includes('Workflow halted'),
+    );
+    expect(halt).toBeDefined();
+    expect(halt!.error).toContain('max_iterations 解析失败');
+  });
+
+  it('llm 步 prompt 含未定义裸变量 → yield warning 列出表达式（E1）', async () => {
+    ctx.chat = async function* () {
+      yield { type: 'text_delta', delta: 'ok' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+    const def: WorkflowDef = {
+      name: 'missing-var-warn',
+      description: 'd',
+      inputs: [{ name: 'goal', type: 'string', required: true }],
+      steps: [{ id: 'g', llm: '目标是 ${goal}（裸名，应告警）' }],
+    };
+    const events = await collect(runWorkflow(def, { goal: 'X' }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const warn = events.find(
+      (e): e is { type: 'warning'; message: string } =>
+        e.type === 'warning' && e.message.includes('模板变量未定义'),
+    );
+    expect(warn).toBeDefined();
+    expect(warn!.message).toContain('${goal}');
+    expect(warn!.message).toContain('inputs.<name>');
+  });
+
+  it('顶层 set 记 checkpoint：resume 跳过 set 步时变量仍回放', async () => {
+    const def: WorkflowDef = {
+      name: 'set-resume',
+      description: 'd',
+      inputs: [{ name: 'goal', type: 'string', required: true }],
+      self_heal: { backoff: 0 },
+      steps: [
+        { id: 'init', type: 'set', set: { phase: 'PLAN' } },
+        { id: 'boom', llm: '会失败的步' },
+        { id: 'check', type: 'assert', condition: 'phase == "PLAN"' },
+      ],
+    };
+    // 第一次：init 成功，boom 失败 halt（chat 永远抛）
+    ctx.chat = async function* () {
+      throw new Error('down');
+      // biome-ignore lint/correctness/noUnreachable: stub
+      yield { type: 'done', stopReason: 'stop' };
+    };
+    const ev1 = await collect(runWorkflow(def, { goal: 'G' }, ctx));
+    expect(ev1.some((e) => e.type === 'workflow_done')).toBe(false);
+
+    // 第二次：同 goal resume（backoff 0 → 从 boom 起跑，init 被跳过）——
+    // phase 必须经 checkpoint 回放，check 步才能过
+    ctx.history = [];
+    ctx.chat = async function* () {
+      yield { type: 'text_delta', delta: 'fine' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+    const ev2 = await collect(runWorkflow(def, { goal: 'G' }, ctx));
+    expect(ev2.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(
+      ev2.some(
+        (e) => e.type === 'workflow_step_skipped' && e.id === 'init',
+      ),
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,397 @@
+/**
+ * ============================================================
+ *  test/workflows/expressions.test.ts
+ * ------------------------------------------------------------
+ *  workflow 表达式引擎单测：tokenizer / evalExpr / interpolate /
+ *  interpolateDeep。重点覆盖：
+ *    - 变量点路径（inputs.book）
+ *    - 比较 + 布尔运算
+ *    - 白名单内置函数（fileExists / length / lower / upper）
+ *    - ${} 插值（包括括号匹配 + 转义 + 对象 JSON 化）
+ *    - 安全：禁止 eval/Function 等被插入
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import {
+  evalExpr,
+  interpolate,
+  interpolateDeep,
+} from '../src/expressions.js';
+import { VarStack } from '../src/types.js';
+
+describe('workflows/expressions', () => {
+  let vars: VarStack;
+
+  beforeEach(() => {
+    vars = new VarStack();
+    vars.setGlobal('inputs', { book: '原则', angle: 'insight', n: 3 });
+    vars.set('thumb_prompt', 'a book and a lamp');
+  });
+
+  it('字面量数字 / 字符串 / 布尔', () => {
+    expect(evalExpr('42', vars)).toBe(42);
+    expect(evalExpr('"hello"', vars)).toBe('hello');
+    expect(evalExpr("'x'", vars)).toBe('x');
+    expect(evalExpr('true', vars)).toBe(true);
+    expect(evalExpr('false', vars)).toBe(false);
+    expect(evalExpr('null', vars)).toBe(null);
+  });
+
+  it('变量 + 点路径', () => {
+    expect(evalExpr('thumb_prompt', vars)).toBe('a book and a lamp');
+    expect(evalExpr('inputs.book', vars)).toBe('原则');
+    expect(evalExpr('inputs.n', vars)).toBe(3);
+    expect(evalExpr('inputs.missing', vars)).toBeUndefined();
+  });
+
+  it('点路径禁止访问原型链（__proto__ / constructor / prototype）→ undefined（S1）', () => {
+    expect(evalExpr('inputs.__proto__', vars)).toBeUndefined();
+    expect(evalExpr('inputs.constructor', vars)).toBeUndefined();
+    expect(evalExpr('inputs.prototype', vars)).toBeUndefined();
+    // 链式也挡住：constructor 返回 undefined 后，后续 .name 不可达
+    expect(evalExpr('inputs.constructor.name', vars)).toBeUndefined();
+  });
+
+  it('比较运算 ==/!=/>/<', () => {
+    expect(evalExpr('inputs.n == 3', vars)).toBe(true);
+    expect(evalExpr('inputs.n != 4', vars)).toBe(true);
+    expect(evalExpr('inputs.n > 2', vars)).toBe(true);
+    expect(evalExpr('inputs.n < 2', vars)).toBe(false);
+    expect(evalExpr('"a" == "a"', vars)).toBe(true);
+  });
+
+  it('布尔运算 && / || / !', () => {
+    expect(evalExpr('true && false', vars)).toBe(false);
+    expect(evalExpr('true || false', vars)).toBe(true);
+    expect(evalExpr('!false', vars)).toBe(true);
+    expect(evalExpr('inputs.n > 0 && inputs.book == "原则"', vars)).toBe(true);
+  });
+
+  it('白名单函数 length / lower / upper', () => {
+    expect(evalExpr('length("abcd")', vars)).toBe(4);
+    expect(evalExpr('length(inputs.book)', vars)).toBe(2);
+    expect(evalExpr('lower("HELLO")', vars)).toBe('hello');
+    expect(evalExpr('upper("hi")', vars)).toBe('HI');
+  });
+
+  it('未知函数被拒绝（白名单外）', () => {
+    expect(() => evalExpr('eval("1+1")', vars)).toThrow();
+    expect(() => evalExpr('require("fs")', vars)).toThrow();
+    expect(() => evalExpr('Function("x")', vars)).toThrow();
+  });
+
+  it('interpolate ${EXPR} 替换变量', () => {
+    expect(interpolate('book=${inputs.book}', vars)).toBe('book=原则');
+    expect(interpolate('${inputs.n} times', vars)).toBe('3 times');
+  });
+
+  it('interpolate 处理对象 → JSON.stringify', () => {
+    const out = interpolate('${inputs}', vars);
+    expect(out).toContain('原则');
+    expect(out).toContain('insight');
+  });
+
+  it('interpolate 支持 \\$ 转义', () => {
+    expect(interpolate('price=\\${inputs.n}', vars)).toBe('price=${inputs.n}');
+  });
+
+  it('interpolate 未闭合 ${ 原样保留', () => {
+    expect(interpolate('hello ${unclosed', vars)).toBe('hello ${unclosed');
+  });
+
+  it('interpolateDeep 递归处理对象/数组', () => {
+    const input = {
+      file_path: 'videos/${inputs.book}/script.txt',
+      content: '${thumb_prompt}',
+      nested: { list: ['${inputs.angle}', 'static'] },
+    };
+    const out = interpolateDeep(input, vars);
+    expect(out.file_path).toBe('videos/原则/script.txt');
+    expect(out.content).toBe('a book and a lamp');
+    expect(out.nested.list[0]).toBe('insight');
+    expect(out.nested.list[1]).toBe('static');
+  });
+
+  // ===== P2：表达式上下文原生 ${} + 字符串字面量插值 + 拼接 =====
+
+  it('P2 独立 ${EXPR} 取值（任意类型，不字符串化）', () => {
+    expect(evalExpr('${inputs.book}', vars)).toBe('原则');
+    expect(evalExpr('${inputs.n}', vars)).toBe(3);
+  });
+
+  it('P2 footgun 修复：裸 ${x} == 字面量 能正常比较（旧实现会当成变量名→报错/undefined）', () => {
+    expect(evalExpr("${inputs.angle} == 'insight'", vars)).toBe(true);
+    expect(evalExpr('${inputs.n} == 3', vars)).toBe(true);
+    expect(evalExpr("${inputs.book} != '原则'", vars)).toBe(false);
+  });
+
+  it('P2 字符串字面量内嵌 ${} 插值（拼路径，向后兼容旧 fileExists("…${x}…") 写法）', () => {
+    expect(evalExpr('"book=${inputs.book}"', vars)).toBe('book=原则');
+    expect(evalExpr('"x/${inputs.book}/y"', vars)).toBe('x/原则/y');
+    // 引号内插值 == 字面量（文档 §0.3 对法二）
+    expect(evalExpr("'${inputs.angle}' == 'insight'", vars)).toBe(true);
+  });
+
+  it('P2 + 拼接：number 相加 / 否则两边 stringify 后字符串拼接', () => {
+    expect(evalExpr('inputs.n + 1', vars)).toBe(4);
+    expect(evalExpr('"a/" + inputs.book + "/b"', vars)).toBe('a/原则/b');
+    expect(evalExpr('inputs.book + "-" + inputs.angle', vars)).toBe('原则-insight');
+  });
+});
+
+describe('workflows/expressions::三元表达式 ? :', () => {
+  let vars: VarStack;
+
+  beforeEach(() => {
+    vars = new VarStack();
+    vars.setGlobal('inputs', { book: '原则', n: 3 });
+    vars.set('phase', 'PLAN');
+    vars.set('learnings_text', 'some lesson here');
+  });
+
+  it('基本三元：true 分支', () => {
+    expect(evalExpr("true ? 'yes' : 'no'", vars)).toBe('yes');
+  });
+
+  it('基本三元：false 分支', () => {
+    expect(evalExpr("false ? 'yes' : 'no'", vars)).toBe('no');
+  });
+
+  it('条件为比较表达式', () => {
+    expect(evalExpr("inputs.n > 2 ? 'big' : 'small'", vars)).toBe('big');
+    expect(evalExpr("inputs.n < 2 ? 'big' : 'small'", vars)).toBe('small');
+  });
+
+  it('条件为相等比较（ralph-loop.yaml 模式）', () => {
+    // ralph-loop.yaml 第59行模式：phase == 'PLAN' ? '...' : ...
+    expect(evalExpr("phase == 'PLAN' ? '分析任务、拆解步骤' : '其他阶段'", vars)).toBe(
+      '分析任务、拆解步骤',
+    );
+    expect(evalExpr("phase == 'BUILD' ? '按计划实现' : '其他阶段'", vars)).toBe('其他阶段');
+  });
+
+  it('嵌套三元（右结合）：多路分支', () => {
+    // ralph-loop.yaml 第59-63行的嵌套模式
+    const result = evalExpr(
+      "phase == 'PLAN' ? 'PLAN文本' : phase == 'BUILD' ? 'BUILD文本' : phase == 'VERIFY' ? 'VERIFY文本' : 'DONE文本'",
+      vars,
+    );
+    expect(result).toBe('PLAN文本');
+
+    vars.set('phase', 'BUILD');
+    const result2 = evalExpr(
+      "phase == 'PLAN' ? 'PLAN文本' : phase == 'BUILD' ? 'BUILD文本' : phase == 'VERIFY' ? 'VERIFY文本' : 'DONE文本'",
+      vars,
+    );
+    expect(result2).toBe('BUILD文本');
+  });
+
+  it('条件含 && 复合布尔表达式（ralph-loop.yaml 第72行模式）', () => {
+    // ${learnings_text && learnings_text != '' ? '# 关键教训\n' + learnings_text : ''}
+    const result = evalExpr(
+      "learnings_text && learnings_text != '' ? '# 关键教训\\n' + learnings_text : ''",
+      vars,
+    );
+    expect(result).toBe('# 关键教训\nsome lesson here');
+  });
+
+  it('条件为 falsy 空字符串时走 else 分支', () => {
+    vars.set('learnings_text', '');
+    const result = evalExpr(
+      "learnings_text && learnings_text != '' ? '# 有教训' : ''",
+      vars,
+    );
+    expect(result).toBe('');
+  });
+
+  it('变量 undefined 时走 else 分支', () => {
+    const v = new VarStack(); // 不设 phase
+    expect(evalExpr("phase == 'PLAN' ? 'plan' : 'default'", v)).toBe('default');
+  });
+
+  it('无 ? 时正常降级（不影响已有表达式解析）—— 回归保护', () => {
+    expect(evalExpr('inputs.n + 1', vars)).toBe(4);
+    expect(evalExpr('"hello" + " world"', vars)).toBe('hello world');
+    expect(evalExpr('inputs.book == "原则"', vars)).toBe(true);
+  });
+
+  it('缺少 : 报错', () => {
+    expect(() => evalExpr("true ? 'yes'", vars)).toThrow(/缺少 ':'/);
+  });
+
+  it('三元表达式的值可以是任意类型（数字、布尔、null）', () => {
+    expect(evalExpr('true ? 42 : 0', vars)).toBe(42);
+    expect(evalExpr('false ? 42 : 0', vars)).toBe(0);
+    expect(evalExpr('true ? true : false', vars)).toBe(true);
+    expect(evalExpr('true ? null : "x"', vars)).toBe(null);
+  });
+});
+
+describe('workflows/expressions::fileExists', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-expr-'));
+    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('fileExists 命中真实文件', () => {
+    writeFileSync(join(tmp, 'a.txt'), 'x');
+    const vars = new VarStack();
+    expect(evalExpr('fileExists("a.txt")', vars)).toBe(true);
+    expect(evalExpr('fileExists("missing.txt")', vars)).toBe(false);
+  });
+
+  it('P2 fileExists 用字符串内插值 / + 拼接定位文件（无预插值也命中）', () => {
+    writeFileSync(join(tmp, 'b.txt'), 'y');
+    const vars = new VarStack();
+    vars.setGlobal('inputs', { name: 'b' });
+    // 字符串字面量内插值
+    expect(evalExpr('fileExists("${inputs.name}.txt")', vars)).toBe(true);
+    // + 拼接
+    expect(evalExpr('fileExists(inputs.name + ".txt")', vars)).toBe(true);
+    expect(evalExpr('fileExists("videos/" + inputs.name + ".txt")', vars)).toBe(false);
+  });
+});
+
+describe('workflows/expressions::readJson', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-expr-rj-'));
+    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('读对象 JSON（整值 / 取键）', () => {
+    writeFileSync(
+      join(tmp, 'm.json'),
+      JSON.stringify({ has_source: true, images: [{ file: 'src_1.png' }, { file: 'src_2.png' }] }),
+    );
+    const vars = new VarStack();
+    // 整值
+    const whole = evalExpr('readJson("m.json")', vars) as Record<string, unknown>;
+    expect(whole.has_source).toBe(true);
+    // 取顶层键 → 数组（驱动 for-each 的核心用法）
+    const imgs = evalExpr('readJson("m.json", "images")', vars) as unknown[];
+    expect(Array.isArray(imgs)).toBe(true);
+    expect(imgs).toHaveLength(2);
+    expect((imgs[0] as Record<string, unknown>).file).toBe('src_1.png');
+    // length(readJson(...)) 组合可用
+    expect(evalExpr('length(readJson("m.json", "images"))', vars)).toBe(2);
+  });
+
+  it('读顶层数组 JSON', () => {
+    writeFileSync(join(tmp, 'arr.json'), JSON.stringify([1, 2, 3]));
+    const vars = new VarStack();
+    expect(evalExpr('readJson("arr.json")', vars)).toEqual([1, 2, 3]);
+  });
+
+  it('asArray 标准化可选 JSON 数组，供 loop over 安全消费', () => {
+    writeFileSync(join(tmp, 'arr.json'), JSON.stringify([1, 2, 3]));
+    writeFileSync(join(tmp, 'm.json'), JSON.stringify({ images: [{ file: 'src_1.png' }] }));
+    const vars = new VarStack();
+    expect(evalExpr('asArray(readJson("arr.json"))', vars)).toEqual([1, 2, 3]);
+    expect(evalExpr('asArray(readJson("m.json", "images"))', vars)).toEqual([
+      { file: 'src_1.png' },
+    ]);
+    expect(evalExpr('asArray(readJson("missing.json", "images"))', vars)).toEqual([]);
+    expect(evalExpr('asArray(null)', vars)).toEqual([]);
+    expect(evalExpr('asArray(inputs.missing)', vars)).toEqual([]);
+  });
+
+  it('asArray 遇到非数组结构响亮报错，避免坏 manifest 被静默吞掉', () => {
+    writeFileSync(join(tmp, 'bad-shape.json'), JSON.stringify({ images: { file: 'src_1.png' } }));
+    const vars = new VarStack();
+    expect(() => evalExpr('asArray(readJson("bad-shape.json", "images"))', vars)).toThrow(
+      /asArray 期望数组/,
+    );
+  });
+
+  it('缺文件 / 坏 JSON / 缺键 → null（不抛）', () => {
+    writeFileSync(join(tmp, 'bad.json'), '{not valid json');
+    const vars = new VarStack();
+    expect(evalExpr('readJson("missing.json")', vars)).toBe(null);
+    expect(evalExpr('readJson("missing.json", "images")', vars)).toBe(null);
+    expect(evalExpr('readJson("bad.json")', vars)).toBe(null);
+    writeFileSync(join(tmp, 'm.json'), JSON.stringify({ a: 1 }));
+    expect(evalExpr('readJson("m.json", "nope")', vars)).toBe(null);
+  });
+
+  it('相对路径锚定 getWorkingDir + 字符串插值定位', () => {
+    writeFileSync(join(tmp, 'build.json'), JSON.stringify({ k: 'v' }));
+    const vars = new VarStack();
+    vars.setGlobal('inputs', { name: 'build' });
+    expect(evalExpr('readJson("${inputs.name}.json", "k")', vars)).toBe('v');
+  });
+
+  it('容忍前导 BOM（某些工具/重定向写出带 BOM 的 JSON）', () => {
+    writeFileSync(join(tmp, 'bom.json'), `${JSON.stringify({ images: [1, 2] })}`);
+    const vars = new VarStack();
+    expect(evalExpr('readJson("bom.json", "images")', vars)).toEqual([1, 2]);
+  });
+});
+
+describe('workflows/expressions::parseJson（字符串→值，源是 capture 文本）', () => {
+  it('解析数组 / 对象字符串', () => {
+    const vars = new VarStack();
+    vars.setGlobal('arr', '[1,2,3]');
+    vars.setGlobal('obj', '{"a":1,"b":[2]}');
+    expect(evalExpr('parseJson(arr)', vars)).toEqual([1, 2, 3]);
+    expect(evalExpr('parseJson(obj)', vars)).toEqual({ a: 1, b: [2] });
+  });
+
+  it('配 asArray 驱动 loop over（eval 抓的 URL JSON 串）', () => {
+    const vars = new VarStack();
+    vars.setGlobal('urls', '["http://a/1.jpg","http://a/2.jpg"]');
+    expect(evalExpr('asArray(parseJson(urls))', vars)).toEqual([
+      'http://a/1.jpg',
+      'http://a/2.jpg',
+    ]);
+  });
+
+  it('非字符串 / 空 / 坏 JSON → null（不抛）', () => {
+    const vars = new VarStack();
+    vars.setGlobal('bad', '{not valid json');
+    vars.setGlobal('blank', '   ');
+    vars.setGlobal('num', 42);
+    expect(evalExpr('parseJson(bad)', vars)).toBe(null);
+    expect(evalExpr('parseJson(blank)', vars)).toBe(null);
+    expect(evalExpr('parseJson(num)', vars)).toBe(null);
+  });
+
+  it('容忍前导 BOM', () => {
+    const vars = new VarStack();
+    vars.setGlobal('bom', '[1,2]');
+    expect(evalExpr('parseJson(bom)', vars)).toEqual([1, 2]);
+  });
+});