minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,373 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/test/agentLlmError.test.ts
+ * ------------------------------------------------------------
+ *  agent 步的 llm_error 归因契约（P0-A 回归锚）：
+ *
+ *  runQuery 遇 LLM 超时/网络错是 yield error(code:'llm_error') 后 return（不 throw）。
+ *  曾经 agent.ts 只侦测 'aborted'，provider 失败被验证闸门误归因为
+ *  「agent 步骤放弃: 没有产出任何结果」——与 llm/skill 步的诚实归因
+ *  「LLM 调用失败且无产出（触发重试）」不一致（现场日志可见同一运行两种文案）。
+ *
+ *  本文件锁定三条语义：
+ *    1. LLM 失败且无产出 → 抛「可重试失败」→ runner in-run retry → 重试成功则 done
+ *    2. 重试耗尽 → halt 文案是「LLM 调用失败且无产出」，不是「步骤放弃」
+ *    3. 用户中断（signal.aborted）→ 不触发任何重试（红线：aborted 不重试）
+ *
+ *  约定：DI 注入 ctx.chat（不 mock.module client/loop/plugin-sdk），走真实 runQuery。
+ * ============================================================
+ */
+
+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 { 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('workflows/agent llm_error 归因（P0-A）', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-agent-llmerr-'));
+    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('LLM 第一次失败（超时类）→ in-run retry 重跑 → 第二次成功 → workflow done', async () => {
+    let call = 0;
+    ctx.chat = async function* () {
+      call++;
+      if (call === 1) throw new Error('socket timeout');
+      yield { type: 'text_delta', delta: 'real-result' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-llmerr-retry',
+      description: 'provider 抖动被 retry 救回',
+      steps: [
+        { id: 'a1', agent: '做点事', capture: { content: 'out' }, max_retries: 1 },
+        { id: 'check', type: 'assert', condition: 'out == "real-result"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // runQuery 的 error(llm_error) 事件会透传给 UI（红字照常显示），
+    // 但不应出现 workflow halt（重试已救回）
+    expect(
+      events.some(
+        (e) => e.type === 'error' && e.error.includes('Workflow halted'),
+      ),
+    ).toBe(false);
+    // 重试 warning 必须出现，且文案是诚实归因（LLM 失败），不是「步骤放弃」
+    const retryWarn = events.find(
+      (e): e is { type: 'warning'; message: string } =>
+        e.type === 'warning' && e.message.includes('重试 1/1'),
+    );
+    expect(retryWarn).toBeDefined();
+    expect(retryWarn!.message).toContain('LLM 调用失败且无产出');
+    expect(retryWarn!.message).not.toContain('步骤放弃');
+  });
+
+  it('LLM 持续失败 → 重试耗尽 → halt 文案为「LLM 调用失败且无产出」而非「步骤放弃」', async () => {
+    ctx.chat = async function* () {
+      throw new Error('connection refused');
+      // biome-ignore lint/correctness/noUnreachable: 让 TS 认出 generator 形状
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-llmerr-exhaust',
+      description: 'provider 持续故障',
+      steps: [{ id: 'a1', agent: '做点事', max_retries: 1 }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    // 看 halt 事件（runQuery 透传的 error(llm_error) 是另一回事）
+    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('LLM 调用失败且无产出');
+    expect(halt!.error).not.toContain('步骤放弃');
+  });
+
+  it('halt 文案附带 provider 真实报错细节（落 progress.md 的持久证据）', async () => {
+    ctx.chat = async function* () {
+      throw new Error('ECONNRESET api.minimax.chat 端口 443');
+      // biome-ignore lint/correctness/noUnreachable: stub
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-llmerr-detail',
+      description: '证据持久化',
+      steps: [{ id: 'a1', agent: '做点事', max_retries: 0 }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    const halt = events.find(
+      (e): e is { type: 'error'; error: string } =>
+        e.type === 'error' && e.error.includes('Workflow halted'),
+    );
+    expect(halt).toBeDefined();
+    // 不再只有「无产出」四个字——provider 报错原文可排障
+    expect(halt!.error).toContain('ECONNRESET');
+  });
+
+  it('self_heal.retry_delay_ms 退避生效（重试前等待，线性）', async () => {
+    let call = 0;
+    ctx.chat = async function* () {
+      call++;
+      if (call === 1) throw new Error('transient');
+      yield { type: 'text_delta', delta: 'ok' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-retry-delay',
+      description: '退避重试',
+      self_heal: { retry_delay_ms: 120 },
+      steps: [{ id: 'a1', agent: '做点事', max_retries: 1 }],
+    };
+    const t0 = Date.now();
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const elapsed = Date.now() - t0;
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(elapsed).toBeGreaterThanOrEqual(110); // 第 1 次重试应等 ~120ms
+    // warning 文案可见化退避
+    expect(
+      events.some((e) => e.type === 'warning' && e.message.includes('120ms 后')),
+    ).toBe(true);
+  });
+
+  it('agent 撞 maxTurns 截断 → 抛可重试失败 → 重试在共享 history 上续作成功（伪成功根除锚）', async () => {
+    // 真事故：execute_plan 撞 25 轮被截断，半截产出被验证闸门当成功放行 →
+    // 半成品 PPTX 被整条链当真交付。现在：截断 = 可重试失败，重试 = 续作。
+    let chatCalls = 0;
+    ctx.executeTool = async () => ({ ok: true, content: 'tool-ok' });
+    ctx.chat = async function* () {
+      chatCalls++;
+      if (chatCalls <= 2) {
+        // 前两次一直调工具 → 耗尽 maxTurns=2 被截断
+        yield {
+          type: 'tool_call_delta',
+          index: 0,
+          id: `t${chatCalls}`,
+          name: 'Glob',
+          argumentsDelta: '{"pattern":"*"}',
+        };
+        yield { type: 'done', stopReason: 'tool_calls' };
+        return;
+      }
+      // 重试（续作）：模型看到已有进度，直接给出最终交付
+      yield { type: 'text_delta', delta: 'final-deliverable' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-maxturns-cutoff',
+      description: '截断诚实化',
+      steps: [
+        { id: 'a1', agent: '干活', maxTurns: 2, max_retries: 1, capture: { content: 'out' } },
+        { id: 'chk', type: 'assert', condition: 'out == "final-deliverable"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 截断被诚实归因 + 触发了重试
+    const retryWarn = events.find(
+      (e): e is { type: 'warning'; message: string } =>
+        e.type === 'warning' &&
+        e.message.includes('轮数预算用尽') &&
+        e.message.includes('续跑 1/1'),
+    );
+    expect(retryWarn).toBeDefined();
+    expect(retryWarn!.message).not.toContain('提前结束');
+    expect(retryWarn!.message).not.toContain('截断时产出不可信');
+    expect(retryWarn!.message).not.toContain('__WF_MAX_TURNS_CUTOFF__');
+    const retryProgress = events.find(
+      (e): e is Extract<typeof e, { type: 'plugin_progress' }> & { message: string } =>
+        e.type === 'plugin_progress' &&
+        typeof e.message === 'string' &&
+        e.message.includes('阶段轮数预算用尽'),
+    );
+    expect(retryProgress).toBeDefined();
+    expect(retryProgress!.message).toContain('正在续跑 1/1');
+    expect(retryProgress!.message).not.toContain('截断时产出不可信');
+    expect(chatCalls).toBe(3);
+  });
+
+  it('self_heal.max_turns_retry_delay_ms 只影响 maxTurns 截断重试', async () => {
+    let chatCalls = 0;
+    ctx.executeTool = async () => ({ ok: true, content: 'tool-ok' });
+    ctx.chat = async function* () {
+      chatCalls++;
+      if (chatCalls <= 2) {
+        yield {
+          type: 'tool_call_delta',
+          index: 0,
+          id: `mt-${chatCalls}`,
+          name: 'Glob',
+          argumentsDelta: '{"pattern":"*"}',
+        };
+        yield { type: 'done', stopReason: 'tool_calls' };
+        return;
+      }
+      yield { type: 'text_delta', delta: 'done-after-delay' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-maxturns-delay',
+      description: '截断错峰续跑',
+      self_heal: { retry_delay_ms: 0, max_turns_retry_delay_ms: 80 },
+      steps: [{ id: 'a1', agent: '干活', maxTurns: 2, max_retries: 1 }],
+    };
+    const t0 = Date.now();
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const elapsed = Date.now() - t0;
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(elapsed).toBeGreaterThanOrEqual(70);
+    expect(
+      events.some(
+        (e) =>
+          e.type === 'warning' &&
+          e.message.includes('轮数预算用尽') &&
+          e.message.includes('80ms 后'),
+      ),
+    ).toBe(true);
+  });
+
+  it('agent 撞 maxTurns 且重试耗尽 → halt 文案带「被截断」而非伪成功', async () => {
+    ctx.executeTool = async () => ({ ok: true, content: 'tool-ok' });
+    ctx.chat = async function* () {
+      yield {
+        type: 'tool_call_delta',
+        index: 0,
+        id: 'loop-forever',
+        name: 'Glob',
+        argumentsDelta: '{"pattern":"*"}',
+      };
+      yield { type: 'done', stopReason: 'tool_calls' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-maxturns-exhaust',
+      description: 'd',
+      steps: [{ id: 'a1', agent: '干活', maxTurns: 2, max_retries: 0 }],
+    };
+    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('被截断');
+    expect(halt!.error).toContain('重试额度已用尽');
+    expect(halt!.error).not.toContain('截断时产出不可信');
+  });
+
+  it('provider finish_reason=length → workflow step 视为截断失败，不把半截文本当交付', async () => {
+    ctx.chat = async function* () {
+      yield { type: 'text_delta', delta: 'partial deliverable' };
+      yield { type: 'done', stopReason: 'length' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-provider-length',
+      description: 'provider max_tokens 截断',
+      steps: [
+        { id: 'a1', agent: '干活', max_retries: 0, capture: { content: 'out' } },
+        { id: 'should_not_run', type: 'assert', condition: 'false' },
+      ],
+    };
+    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('被截断');
+    const startedIds = events
+      .filter(
+        (e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> =>
+          e.type === 'workflow_step_start',
+      )
+      .map((e) => e.id);
+    expect(startedIds).not.toContain('should_not_run');
+  });
+
+  it('用户中断（signal.aborted）→ 不触发任何重试（aborted 不重试红线）', async () => {
+    const ac = new AbortController();
+    ctx.signal = ac.signal;
+    ctx.chat = async function* () {
+      // 模拟用户在 LLM 流式期间按 ESC：中断信号生效 + 流抛 AbortError
+      ac.abort();
+      const e = new Error('aborted');
+      e.name = 'AbortError';
+      throw e;
+      // biome-ignore lint/correctness/noUnreachable: 让 TS 认出 generator 形状
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'agent-aborted',
+      description: '中断不重试',
+      steps: [{ id: 'a1', agent: '做点事', max_retries: 2 }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'interrupted')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    // 关键：没有任何重试 warning（runner 的 !signal.aborted 守卫生效）
+    expect(
+      events.some((e) => e.type === 'warning' && e.message.includes('重试')),
+    ).toBe(false);
+  });
+});

package/plugins/workflow-runner/test/bashBlacklist.sweep.test.ts

@@ -0,0 +1,65 @@
+/**
+ * test/bashBlacklist.sweep.test.ts
+ * ------------------------------------------------------------
+ * 全库不变量：workflows/*.yaml 所有 tool:Bash 步的 command 文本
+ * 不得命中 Bash 工具安全黑名单（checkForbidden）。
+ *
+ * 事故背书（2026-07-02）：ppt.yaml stage_export 的 bash 注释「硬门 halt」
+ * 被旧版整段裸词扫描误杀——整步执行前被拒 → onError:halt → 确定性死端
+ * （resume 原样命令原样再拒），且要真机跑完前 21 阶段才暴露。
+ * 本测试把「yaml 命令 × Bash 黑名单」这条集成缝隙压进 CI：
+ * 任何 yaml 未来加注释/文案再撞任何黑名单模式，就地红灯。
+ *
+ * 说明：扫描的是 yaml 原文（含 ${} 插值占位）——作者手写的地雷都在原文里；
+ * 运行时插值进来的值属运行数据，不在本测试职责内。
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { checkForbidden } from '../../../src/tools/bash/bash.js';
+import { parseWorkflowFile } from '../src/loader.js';
+import type { StepDef } from '../src/types.js';
+
+const workflowsDir = join(
+  import.meta.dir.replace(/[/\\]test$/, ''), // plugins/workflow-runner
+  '..', // plugins
+  '..', // 仓库根
+  'workflows',
+);
+
+/** 递归收集所有嵌套步（loop.do / branch.then / branch.else）。 */
+function collectSteps(steps: StepDef[] | undefined): StepDef[] {
+  if (!steps) return [];
+  const out: StepDef[] = [];
+  for (const s of steps) {
+    out.push(s);
+    out.push(...collectSteps(s.do), ...collectSteps(s.then), ...collectSteps(s.else));
+  }
+  return out;
+}
+
+describe('workflows/*.yaml × Bash 安全黑名单 sweep', () => {
+  it('所有 tool:Bash 步的 command 不命中黑名单', async () => {
+    const files = (await readdir(workflowsDir)).filter((f) => /\.ya?ml$/.test(f));
+    expect(files.length).toBeGreaterThan(0);
+
+    let scanned = 0;
+    const hits: string[] = [];
+    for (const file of files) {
+      const def = await parseWorkflowFile(join(workflowsDir, file));
+      for (const step of collectSteps(def.steps)) {
+        if (step.tool?.toLowerCase() !== 'bash') continue;
+        const command = (step.args as Record<string, unknown> | undefined)?.command;
+        if (typeof command !== 'string') continue;
+        scanned++;
+        const reason = checkForbidden(command);
+        if (reason) hits.push(`${file}::${step.id} → ${reason}`);
+      }
+    }
+
+    expect(scanned).toBeGreaterThan(0); // 空扫描 = 收集逻辑坏了，别假绿
+    expect(hits).toEqual([]);
+  });
+});

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

@@ -0,0 +1,99 @@
+/**
+ * ============================================================
+ *  capture 绑空了必须响亮说出来
+ * ------------------------------------------------------------
+ *  `capture` 的写法是 `{ 结果字段: 变量名 }`。写反成 `{ 变量名: 结果字段 }`
+ *  语法完全合法、加载期查不出来，运行时只是安静地绑一个 undefined。
+ *
+ *  真实代价（wechat-reading-shots 实测）：`text: pager` 写反成 `pager: text` 后，
+ *  下游 assert 判假，用户看到的是 onFail 里那句业务文案「三种翻页方式都不奏效」
+ *  —— 与真实原因（capture 写反）毫无关系，排查方向被彻底带偏，白跑一整轮。
+ *  同一个坑 `adaptive-research.yaml` 也踩过一次（文件里留着注释
+ *  「曾绑 content 导致 notes 恒 undefined」）。两次 → 够格进引擎。
+ * ============================================================
+ */
+
+import { describe, expect, mock, test } from 'bun:test';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runWorkflow } from '../src/runner.js';
+import type { Provider } from '../../../src/types.js';
+import type { RunContext, WorkflowDef } from '../src/types.js';
+
+mock.module('../../../src/llm/client.js', () => ({
+  chat: async function* () {
+    yield { type: 'text_delta', delta: 'right' };
+    yield { type: 'done', stopReason: 'stop' };
+  },
+}));
+
+const provider: Provider = {
+  name: 'test',
+  baseURL: '',
+  apiKey: '',
+  model: 'm',
+  contextWindow: 128000,
+};
+
+/**
+ * ⚠️ **工作流名必须每次运行唯一。**
+ *
+ * 工作流状态目录锚的是 `getWorkingDir()`（进程级），**不是** `RunContext.cwd` ——
+ * 见 `runner.ts` 里 `new WorkflowState(getWorkingDir(), def.name)`。
+ * 所以给 ctx 传一个 mkdtemp 目录**隔离不了状态**：同名工作流第二次跑会命中
+ * 「同名任务此前已完成」而**整条短路**，`workflow_done` 照发、步骤一个不跑 ——
+ * 于是断言全部空过，测试在两种实现下都绿，什么都证明不了。
+ *
+ * 实测踩到：本文件的两条 capture 断言曾在「注入旧行为」时依然全绿，
+ * 查下去才发现根本没执行到被测代码。用唯一名根治。
+ */
+function uniqueName(base: string): string {
+  return `${base}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+async function collectWarnings(def: WorkflowDef): Promise<string[]> {
+  const ctx = {
+    provider,
+    history: [{ role: 'system', content: 'sys' }],
+    // ⚠️ 每个 case 一个全新目录：工作流状态（.minimal-agent-workflow/<name>/）会让
+    //    同名同 goal 的第二次运行走 resume 跳过已完成步 —— 那样 capture 根本不执行，
+    //    测试第二次跑就"莫名其妙"变红。共用 cwd 的测试不是测试，是掷骰子。
+    cwd: mkdtempSync(join(tmpdir(), 'wf-capture-')),
+  } as unknown as RunContext;
+  const warnings: string[] = [];
+  for await (const event of runWorkflow(def, {}, ctx)) {
+    if ((event as { type?: string }).type === 'warning') {
+      warnings.push((event as { message: string }).message);
+    }
+  }
+  return warnings;
+}
+
+describe('bindCapture 取不到字段时报 warning', () => {
+  test('写反的 capture（{变量名: 结果字段}）被抓住，并报出实际可绑字段', async () => {
+    const warnings = await collectWarnings({
+      name: uniqueName('misbind'),
+      steps: [
+        // ⚠️ 写反：想把 raw.text 绑给变量 pager，却写成了 pager: text
+        { id: 'probe', llm: '按哪个键翻页', capture: { pager: 'text' } },
+      ],
+    } as never);
+
+    const hit = warnings.find((w) => w.includes('capture 取不到字段'));
+    expect(hit).toBeDefined();
+    // 四条信息缺一不可：取不到哪个字段、哪个变量被绑空、是哪一步、实际有什么可绑
+    expect(hit).toContain('`pager`');
+    expect(hit).toContain('`text`');
+    expect(hit).toContain('probe');
+    expect(hit).toContain('写反');
+  });
+
+  test('写对的 capture 不产生 warning —— 不能变成噪声', async () => {
+    const warnings = await collectWarnings({
+      name: uniqueName('ok'),
+      steps: [{ id: 'probe', llm: '按哪个键翻页', capture: { text: 'pager' } }],
+    } as never);
+    expect(warnings.filter((w) => w.includes('capture 取不到字段'))).toHaveLength(0);
+  });
+});

package/plugins/workflow-runner/test/cli.e2e.test.ts

@@ -0,0 +1,147 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/test/cli.e2e.test.ts
+ * ------------------------------------------------------------
+ *  最外层 CLI 端到端：拉子进程跑 `bun src/main.tsx -p "/workflow ..."`,
+ *  验证 stdout / stderr / 退出码 / 文件副作用 全链路。
+ *
+ *  覆盖 3 个用例：
+ *    1. golden path：/workflow cli-e2e --input topic=world → exit 0 + 文件落盘
+ *    2. /workflows 列出 cli-e2e
+ *    3. 缺必填 input → exit 1 + 错误信息含 "topic"
+ *
+ *  fake provider env：workflow 是 tool-only，永不调 API；fake env 仅满足
+ *  main.tsx 的 provider 配置校验。
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const REPO_ROOT = resolve(import.meta.dir, '..', '..', '..');
+const FIXTURE = join(import.meta.dir, 'fixtures', 'cli-e2e.yaml');
+const FIXTURE_ASK = join(import.meta.dir, 'fixtures', 'cli-ask-e2e.yaml');
+const FIXTURE_GREEDY = join(import.meta.dir, 'fixtures', 'greedy-e2e.yaml');
+
+const SPAWN_TIMEOUT = 60_000;
+
+interface SpawnResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+async function spawnMain(promptArg: string, cwd: string): Promise<SpawnResult> {
+  const proc = Bun.spawn(
+    ['bun', 'src/main.tsx', '-d', cwd, '-p', promptArg],
+    {
+      cwd: REPO_ROOT,
+      env: {
+        ...process.env,
+        MINIMAL_AGENT_BASE_URL: 'http://fake.invalid',
+        MINIMAL_AGENT_API_KEY: 'fake-key',
+        MINIMAL_AGENT_MODEL: 'fake-model',
+        MINIMAL_AGENT_CONTEXT_WINDOW: '128000',
+      },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    },
+  );
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { exitCode, stdout, stderr };
+}
+
+describe('CLI 端到端 /workflow（拉子进程跑 main.tsx）', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cli-e2e-'));
+    mkdirSync(join(tmp, 'workflows'), { recursive: true });
+    copyFileSync(FIXTURE, join(tmp, 'workflows', 'cli-e2e.yaml'));
+    copyFileSync(FIXTURE_ASK, join(tmp, 'workflows', 'cli-ask-e2e.yaml'));
+    copyFileSync(FIXTURE_GREEDY, join(tmp, 'workflows', 'greedy-e2e.yaml'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it(
+    'golden path：跑完 + 文件落盘 + exit 0',
+    async () => {
+      const r = await spawnMain(
+        '/workflow cli-e2e --input topic=world',
+        tmp,
+      );
+      expect(r.exitCode).toBe(0);
+      const filePath = join(tmp, 'out', 'world', 'note.txt');
+      expect(existsSync(filePath)).toBe(true);
+      expect(readFileSync(filePath, 'utf8')).toBe('topic=world ok');
+    },
+    SPAWN_TIMEOUT,
+  );
+
+  it(
+    '/workflows 列出 cli-e2e',
+    async () => {
+      const r = await spawnMain('/workflows', tmp);
+      expect(r.exitCode).toBe(0);
+      expect(r.stdout).toContain('cli-e2e');
+    },
+    SPAWN_TIMEOUT,
+  );
+
+  it(
+    '缺必填 input → exit 1 + 错误信息含 "topic"',
+    async () => {
+      const r = await spawnMain('/workflow cli-e2e', tmp);
+      expect(r.exitCode).toBe(1);
+      expect(r.stderr).toContain('topic');
+    },
+    SPAWN_TIMEOUT,
+  );
+
+  // -p 非交互下「含 AskUserQuestion 的工作流」也能跑通：askBridge 自动选推荐项、不挂起。
+  // 这是 ppt 工作流 stage0「样式推荐」在 -p / 宿主 spawn 下自动兜底那条路径的最小复现。
+  it(
+    '含 AskUserQuestion 的工作流在 -p 下自动选推荐项、不挂起、跑完 exit 0',
+    async () => {
+      const r = await spawnMain('/workflow cli-ask-e2e', tmp);
+      expect(r.exitCode).toBe(0);
+      // askBridge 非交互兜底：自动选每题首项（推荐项），stderr 注记
+      expect(r.stderr).toContain('自动选推荐项');
+      // echo 文本经 text 事件 + 末尾 turn_done 正常回到 -p stdout
+      expect(r.stdout).toContain('ASK-E2E-DONE');
+    },
+    SPAWN_TIMEOUT,
+  );
+
+  // 贪婪首参：命令行里 workflow 名之后的整句（含空格分隔段）被 join 进首个 input，
+  // 不逐位拆映射、不撞后面的 number/enum 输入。这是 ppt「打一句话自然语言就能跑」
+  // 的根因修复——曾因严格 posN↔inputs[N] 把整句拆碎、pos2 撞 number 报「必须是数字」。
+  it(
+    'greedy 首参把整句位置参数 join 进首个 input（不拆碎、不撞类型）',
+    async () => {
+      const r = await spawnMain('/workflow greedy-e2e 收集 资料 浅色', tmp);
+      expect(r.exitCode).toBe(0);
+      // 三段位置参数被空格 join 还原成整句进 brief，echo 原样回显
+      expect(r.stdout).toContain('GREEDY-BRIEF=[收集 资料 浅色]');
+    },
+    SPAWN_TIMEOUT,
+  );
+});