minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/test/context-files.test.ts

@@ -0,0 +1,320 @@
+/**
+ * ============================================================
+ *  test/context-files.test.ts —— ADR-05 阶段 4 miniReAct 验证
+ * ------------------------------------------------------------
+ *  覆盖 execLlmStep + miniReAct 子循环（context_files 路径）：
+ *    case 1: 基本 Read 引用 — 第一轮 tool_call，第二轮纯文本收敛
+ *    case 2: maxTurns 上限 — 永不收敛 → 抛错
+ *    case 3: output_schema + tools 组合 — 走 [json+tools] 前缀
+ *
+ *  策略：
+ *    - mock '../../../src/llm/client.js' → 按调用次数依次返回不同流
+ *    - mock '../../../src/tools/index.js' → executeTool 返回固定内容；
+ *      同时透传 ALL_TOOLS / getToolByName（llm.ts 还要靠 ALL_TOOLS 过滤白名单）
+ *    - 不真跑 Read，避免文件系统耦合
+ * ============================================================
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  mock,
+} from 'bun:test';
+
+import type { Provider, Tool } from '../../../src/types.js';
+import { execLlmStep } from '../src/stepExecutors/llm.js';
+import { VarStack } from '../src/types.js';
+import type { RunContext, StepDef } from '../src/types.js';
+
+const fakeProvider: Provider = {
+  name: 'test',
+  baseURL: '',
+  apiKey: '',
+  model: 'm',
+  contextWindow: 128000,
+};
+
+/** execLlmStep 现为 AsyncGenerator：drain 取最终 return 值（yield 的事件直接丢弃）。 */
+async function drainLlm<R>(gen: AsyncGenerator<unknown, R, void>): Promise<R> {
+  let r = await gen.next();
+  while (!r.done) r = await gen.next();
+  return r.value;
+}
+
+// ---------------- mock 基础设施 ----------------
+
+interface ChatCallRecord {
+  messages: unknown[];
+  tools: unknown[];
+  responseFormat?: unknown;
+}
+
+/** 每次 chat() 调用记录的参数 */
+const capturedChatArgs: ChatCallRecord[] = [];
+/** mock 流脚本：每轮一个；用尽后报错（避免无限循环） */
+type MockTurn =
+  | { kind: 'text'; text: string }
+  | {
+      kind: 'tool_call';
+      callId: string;
+      name: string;
+      argsJson: string;
+      /** 该轮 assistant 同时附带的可选文本 */
+      text?: string;
+    };
+let mockTurns: MockTurn[] = [];
+let mockTurnIdx = 0;
+
+interface ExecuteToolCall {
+  name: string;
+  rawArguments: string;
+}
+const capturedExecuteToolCalls: ExecuteToolCall[] = [];
+/** mock executeTool 返回值脚本（按调用顺序）；用尽则回退到 { ok:true, content:'OK' } */
+let mockToolResults: Array<
+  { ok: true; content: string } | { ok: false; error: string }
+> = [];
+
+import { chat as realChatImport } from '../../../src/llm/client.js';
+// 复用真实的 ALL_TOOLS / getToolByName（llm.ts 的白名单过滤要用），
+// 只把 executeTool 替换成 mock 版本。
+//
+// 注：bun 的 mock.module 是 process-global 且无内建 restore。即便其它文件的
+// 测试 case 没被本文件触发，只要 top-level 执行了 mock.module，整个进程的
+// 模块解析就被替换了。所以放在 beforeAll/afterAll 内成对挂钩，确保最小作用域。
+import {
+  ALL_TOOLS as REAL_ALL_TOOLS,
+  executeTool as realExecuteTool,
+  getToolByName as realGetToolByName,
+} from '../../../src/tools/index.js';
+
+// 在 mock 安装前把真实 chat 函数引用拷到值变量，避免 ESM live binding
+// 在 mock.module 后跟着变成 mock 版本（afterAll 复原才能拿到真函数）
+const ORIGINAL_CHAT = realChatImport;
+const ORIGINAL_EXECUTE_TOOL = realExecuteTool;
+
+beforeAll(() => {
+  installChatMock();
+  mock.module('../../../src/tools/index.js', () => ({
+    ALL_TOOLS: REAL_ALL_TOOLS,
+    getToolByName: realGetToolByName,
+    executeTool: async (name: string, rawArguments: string) => {
+      capturedExecuteToolCalls.push({ name, rawArguments });
+      const next = mockToolResults.shift();
+      return next ?? { ok: true, content: 'OK' };
+    },
+  }));
+});
+
+afterAll(() => {
+  // 复原 chat 为真实实现，避免污染下游 e2e / runner 等不 mock chat 的测试文件
+  // 必须用 ORIGINAL_CHAT（mock 前抓到的值快照），不能用 realChatImport（已被 mock 替换的 live binding）
+  mock.module('../../../src/llm/client.js', () => ({ chat: ORIGINAL_CHAT }));
+  // 复原 executeTool 为真实实现
+  mock.module('../../../src/tools/index.js', () => ({
+    ALL_TOOLS: REAL_ALL_TOOLS,
+    getToolByName: realGetToolByName,
+    executeTool: ORIGINAL_EXECUTE_TOOL,
+  }));
+});
+
+// chat mock 也放进 beforeAll，避免 top-level 副作用污染其它文件
+function installChatMock(): void {
+  mock.module('../../../src/llm/client.js', () => ({
+    chat: async function* (args: ChatCallRecord) {
+      capturedChatArgs.push({
+        messages: args.messages,
+        tools: args.tools,
+        responseFormat: args.responseFormat,
+      });
+      const turn = mockTurns[mockTurnIdx];
+      mockTurnIdx++;
+      if (!turn) {
+        throw new Error(
+          `mock chat: 用尽脚本（共 ${mockTurns.length} 轮，调用第 ${mockTurnIdx} 次）`,
+        );
+      }
+      if (turn.kind === 'text') {
+        yield { type: 'text_delta', delta: turn.text };
+      } else {
+        if (turn.text) yield { type: 'text_delta', delta: turn.text };
+        yield {
+          type: 'tool_call_delta',
+          index: 0,
+          id: turn.callId,
+          name: turn.name,
+          argumentsDelta: turn.argsJson,
+        };
+      }
+      yield {
+        type: 'done',
+        stopReason: turn.kind === 'tool_call' ? 'tool_calls' : 'stop',
+      };
+    },
+  }));
+}
+
+// ---------------- 测试 ----------------
+
+describe('workflow-runner context_files (ADR-05 阶段 4)', () => {
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    capturedChatArgs.length = 0;
+    capturedExecuteToolCalls.length = 0;
+    mockTurns = [];
+    mockTurnIdx = 0;
+    mockToolResults = [];
+    ctx = {
+      provider: fakeProvider,
+      history: [],
+      cwd: process.cwd(),
+      tools: [],
+    };
+  });
+
+  it('pure llm 不下发工具，避免单轮设计类步骤误调工具后撞 maxTurns=1', async () => {
+    mockTurns = [{ kind: 'text', text: 'design doc' }];
+
+    const step: StepDef = {
+      id: 'pure-design',
+      llm: 'please design',
+    };
+
+    const result = await drainLlm(execLlmStep(step, new VarStack(), ctx));
+
+    expect(result.raw).toEqual({ text: 'design doc', result: 'design doc' });
+    expect(capturedChatArgs.length).toBe(1);
+    expect(capturedChatArgs[0].tools).toEqual([]);
+  });
+
+  it('case 1: 基本 Read 引用 — tool_call 一轮 + 纯文本一轮', async () => {
+    ctx.tools = [{ name: 'Read' } as Tool];
+    mockTurns = [
+      {
+        kind: 'tool_call',
+        callId: 'call_1',
+        name: 'Read',
+        argsJson: '{"file_path":"/tmp/x.txt"}',
+      },
+      { kind: 'text', text: 'got it' },
+    ];
+    mockToolResults = [{ ok: true, content: 'file content here' }];
+
+    const step: StepDef = {
+      id: 'read-and-answer',
+      llm: 'please summarize',
+      context_files: [{ path: '/tmp/x.txt', hint: 'source data' }],
+      // context_files 经 runQuery(TAOR) 执行；步骤白名单与宿主有效工具集取交集。
+      allowed_tools: ['Read'],
+    };
+
+    const result = await drainLlm(execLlmStep(step, new VarStack(), ctx));
+
+    // 返回值断言
+    expect(result.raw).toEqual({ text: 'got it', result: 'got it' });
+    expect(result.preview).toBe('got it');
+
+    // chat 被调了 2 次
+    expect(capturedChatArgs.length).toBe(2);
+    // executeTool 被调了 1 次，参数透传正确
+    expect(capturedExecuteToolCalls.length).toBe(1);
+    expect(capturedExecuteToolCalls[0].name).toBe('Read');
+    const parsedArgs = JSON.parse(capturedExecuteToolCalls[0].rawArguments) as {
+      file_path: string;
+    };
+    expect(parsedArgs.file_path).toBe('/tmp/x.txt');
+
+    // 第一轮 user message 包含路径和 hint
+    const firstUserMsg = (
+      capturedChatArgs[0].messages as Array<{ role: string; content: string }>
+    ).find((m) => m.role === 'user');
+    expect(firstUserMsg).toBeDefined();
+    expect(firstUserMsg!.content).toContain('/tmp/x.txt');
+    expect(firstUserMsg!.content).toContain('source data');
+
+    // tools 数组只含 Read（白名单生效）
+    const tools0 = capturedChatArgs[0].tools as Array<{ name: string }>;
+    expect(tools0.length).toBe(1);
+    expect(tools0[0].name).toBe('Read');
+  });
+
+  it('case 2: 永不收敛（每轮都调工具）→ 被 maxTurns 严格兜住，不无限循环', async () => {
+    ctx.tools = [{ name: 'Read' } as Tool];
+    // v0.9 重构移除了 miniReAct 的"重复工具调用早停"，改由主 TAOR 引擎(runQuery)的
+    // maxTurns 硬上限兜底。本用例验证安全属性：模型每轮都调工具、永不收敛时，chat 调用
+    // 次数被 maxTurns 严格限制（不会无限循环），不再依赖已移除的重复检测。
+    mockTurns = [
+      {
+        kind: 'tool_call',
+        callId: 'c1',
+        name: 'Read',
+        argsJson: '{"file_path":"/a"}',
+      },
+      {
+        kind: 'tool_call',
+        callId: 'c2',
+        name: 'Read',
+        argsJson: '{"file_path":"/a"}',
+      },
+    ];
+    mockToolResults = [
+      { ok: true, content: 'A' },
+      { ok: true, content: 'A' },
+    ];
+
+    const step: StepDef = {
+      id: 'never-converge',
+      llm: 'go',
+      context_files: [{ path: '/a' }],
+      maxTurns: 2,
+    };
+
+    // 不无限循环：chat 调用次数被 maxTurns(=2) 严格兜住。
+    // 撞顶后的半截产出不可信，execLlmStep 必须抛错触发 runner retry/halt。
+    await expect(
+      drainLlm(execLlmStep(step, new VarStack(), ctx)),
+    ).rejects.toThrow('达到最大轮数 2 被截断');
+    expect(capturedChatArgs.length).toBe(2);
+  });
+
+  it('case 3: output_schema + tools — 走 [json+tools] 前缀', async () => {
+    ctx.tools = [{ name: 'Read' } as Tool];
+    mockTurns = [
+      {
+        kind: 'tool_call',
+        callId: 'call_1',
+        name: 'Read',
+        argsJson: '{"file_path":"/tmp/y.txt"}',
+      },
+      { kind: 'text', text: '{"findings":["a","b"]}' },
+    ];
+    mockToolResults = [{ ok: true, content: 'raw content' }];
+
+    const step: StepDef = {
+      id: 'structured-with-tools',
+      llm: 'find',
+      context_files: [{ path: '/tmp/y.txt' }],
+      output_schema: {
+        type: 'object',
+        properties: { findings: { type: 'array', items: { type: 'string' } } },
+        required: ['findings'],
+      },
+    };
+
+    const result = await drainLlm(execLlmStep(step, new VarStack(), ctx));
+
+    // raw 是 parsed JSON
+    expect(result.raw).toEqual({ findings: ['a', 'b'] });
+    // v0.9：output_schema 走 prompt 内嵌 + extractJsonPayload 解析，preview 统一 [json] 前缀
+    // （不再有独立的 [json+tools] 路径，也不再走 provider-native responseFormat）。
+    expect(result.preview.startsWith('[json] ')).toBe(true);
+
+    // chat 被调两轮（读文件一轮 + 出 JSON 一轮）
+    expect(capturedChatArgs.length).toBe(2);
+  });
+});

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

@@ -0,0 +1,370 @@
+/**
+ * ============================================================
+ *  test/workflows/e2e.test.ts —— /workflow 端到端测试
+ * ------------------------------------------------------------
+ *  从用户敲 `/workflow hello-workflow --input ...` 这一最外层入口开始，
+ *  穿过：
+ *
+ *    runWithPlugins
+ *      → discoverPlugins (扫到真实 workflow-runner 插件)
+ *      → resolveCommand  (识别 /workflow)
+ *      → cmd.executionMode === 'workflow' 路径
+ *      → lazy import workflows/index.ts
+ *      → parseWorkflowArgs + coerceInputs
+ *      → findWorkflowByName (从 tmp/workflows/ 加载 fixture)
+ *      → runWorkflow → step executors (真实 executeTool('Write'))
+ *
+ *  断言：
+ *    - 整个事件序列形态合理（workflow_start → step_start/end ×N → workflow_done → turn_done）
+ *      注：经命令路径（runWithPlugins→runWorkflowFromCommand）成功后补发通用 turn_done 收口，
+ *      故终结事件是 turn_done（workflow_done 在其前一条）；直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾
+ *    - 文件真的落盘到正确路径，内容正确
+ *    - 缺必填 input 时不写任何文件
+ *    - assert 失败时整个 workflow halt
+ *
+ *  不 mock chat / runQuery —— fixture 不依赖 LLM。
+ *  只 mock workingDir.ts，因为其它测试文件留下的全局 mock 会污染。
+ * ============================================================
+ */
+
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  mock,
+} from 'bun:test';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { _resetPluginCache } from '../../../src/plugins/commandRouter.js';
+import type { LoopEvent, Provider } from '../../../src/types.js';
+import type { PluginEvent } from '../../../src/plugins/pluginApi.js';
+import type { WorkflowEvent } from '../src/types.js';
+
+type WfOrLoop = LoopEvent | PluginEvent | WorkflowEvent;
+
+const FIXTURE_SRC = join(import.meta.dir, 'fixtures', 'hello-workflow.yaml');
+
+const provider: 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 as WfOrLoop);
+  return out;
+}
+
+describe('workflow E2E（/workflow → 路由 → runner → 文件落盘）', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-e2e-'));
+    mkdirSync(join(tmp, 'workflows'), { recursive: true });
+    copyFileSync(FIXTURE_SRC, join(tmp, 'workflows', 'hello-workflow.yaml'));
+
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    _resetPluginCache();
+
+    // 抵抗其它测试文件留下的 workingDir.ts 全局 mock 污染。
+    // 注：这一行让 getWorkingDir 跟着 tmp 走，相对路径锚点 + workflows/ 双源扫描都受益。
+    mock.module('../../../src/bootstrap/workingDir.js', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    _resetPluginCache();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  async function runCmd(input: string): Promise<WfOrLoop[]> {
+    const { runWithPlugins } = await import('../../../src/plugins/pluginRunner.js');
+    return collect(
+      runWithPlugins(input, { provider, history: [] }) as AsyncGenerator<WfOrLoop, void, void>,
+    );
+  }
+
+  it('golden path：/workflow hello-workflow --input name=alice --input lang=zh 跑完且文件落盘', async () => {
+    const events = await runCmd('/workflow hello-workflow --input name=alice --input lang=zh');
+
+    // 整体形态
+    expect(events[0]?.type).toBe('workflow_start');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+
+    // 每个 step 都跑完且 ok=true
+    const ends = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> => e.type === 'workflow_step_end',
+    );
+    expect(ends.length).toBe(4);
+    expect(ends.every((e) => e.ok)).toBe(true);
+    expect(ends.map((e) => e.id)).toEqual([
+      'write_greeting',
+      'write_meta',
+      'verify_files',
+      'verify_capture',
+    ]);
+
+    // 文件实际写盘
+    const helloPath = join(tmp, 'greetings', 'alice', 'hello.txt');
+    const metaPath = join(tmp, 'greetings', 'alice', 'meta.json');
+    expect(existsSync(helloPath)).toBe(true);
+    expect(existsSync(metaPath)).toBe(true);
+
+    // hello.txt 内容验证（${var} 插值确实工作了）
+    expect(readFileSync(helloPath, 'utf8')).toBe('Hello, alice! (lang=zh)');
+
+    // meta.json 是合法 JSON，字段对得上
+    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+    expect(meta.name).toBe('alice');
+    expect(meta.lang).toBe('zh');
+    // length() 内置函数 + capture 链路：greeting_text="Hello, alice! (lang=zh)" → 长度 23
+    expect(meta.greeting_length).toBe('Hello, alice! (lang=zh)'.length);
+  });
+
+  it('lang 使用默认值 en（input enum default 路径）', async () => {
+    const events = await runCmd('/workflow hello-workflow --input name=bob');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    expect(readFileSync(join(tmp, 'greetings', 'bob', 'hello.txt'), 'utf8'))
+      .toBe('Hello, bob! (lang=en)');
+  });
+
+  it('workflow_step_start 事件 index/total 单调且与 yaml 一致', async () => {
+    const events = await runCmd('/workflow hello-workflow --input name=carol');
+    const starts = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> => e.type === 'workflow_step_start',
+    );
+    expect(starts.length).toBe(4);
+    expect(starts.map((s) => s.index)).toEqual([0, 1, 2, 3]);
+    expect(starts.every((s) => s.total === 4)).toBe(true);
+    expect(starts.map((s) => s.kind)).toEqual(['tool', 'tool', 'assert', 'assert']);
+  });
+
+  it('缺必填 input name → yield error，且没写任何文件', async () => {
+    const events = await runCmd('/workflow hello-workflow');
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_start')).toBe(false);
+    // tmp/greetings/ 不应被创建
+    expect(existsSync(join(tmp, 'greetings'))).toBe(false);
+  });
+
+  it('lang 传非法值 → yield enum 校验 error，且不进入 runWorkflow', async () => {
+    const events = await runCmd('/workflow hello-workflow --input name=dave --input lang=fr');
+    const err = events.find(
+      (e): e is Extract<LoopEvent, { type: 'error' }> => e.type === 'error',
+    );
+    expect(err).toBeDefined();
+    expect(err!.error).toContain('lang');
+    expect(events.some((e) => e.type === 'workflow_start')).toBe(false);
+  });
+
+  it('未知 workflow 名 → yield error，不污染文件系统', async () => {
+    const events = await runCmd('/workflow definitely-not-exists --input name=eve');
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_start')).toBe(false);
+    expect(existsSync(join(tmp, 'greetings'))).toBe(false);
+  });
+
+  it('L2：位置参数等价 --input —— /workflow hello-workflow alice 同效', async () => {
+    const events = await runCmd('/workflow hello-workflow alice');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    // lang 走 default=en
+    expect(readFileSync(join(tmp, 'greetings', 'alice', 'hello.txt'), 'utf8'))
+      .toBe('Hello, alice! (lang=en)');
+  });
+
+  it('L2：多个位置参数按 inputs 声明顺序映射 —— alice zh → name=alice, lang=zh', async () => {
+    const events = await runCmd('/workflow hello-workflow alice zh');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    expect(readFileSync(join(tmp, 'greetings', 'alice', 'hello.txt'), 'utf8'))
+      .toBe('Hello, alice! (lang=zh)');
+  });
+
+  it('L2：.yaml / .yml 后缀自动剥离 —— hello-workflow.yaml alice 与 hello-workflow alice 等价', async () => {
+    const events = await runCmd('/workflow hello-workflow.yaml alice');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    expect(existsSync(join(tmp, 'greetings', 'alice', 'hello.txt'))).toBe(true);
+  });
+
+  it('L2：--input 优先级高于位置参数 —— 同槽位的位置参数被丢弃但会 yield warning', async () => {
+    // rawInputs={name:'bob'} (来自 --input)；positional=['alice'] 对应 inputs[0]=name (已占) → 丢弃 + warn
+    // 最终 name=bob, lang=default(en)
+    const events = await runCmd('/workflow hello-workflow alice --input name=bob');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    expect(existsSync(join(tmp, 'greetings', 'bob'))).toBe(true);
+    expect(existsSync(join(tmp, 'greetings', 'alice'))).toBe(false);
+    expect(readFileSync(join(tmp, 'greetings', 'bob', 'hello.txt'), 'utf8'))
+      .toBe('Hello, bob! (lang=en)');
+
+    // 必须有一条 warning 提示位置参数被覆盖
+    const warn = events.find(
+      (e): e is { type: 'warning'; message: string } => e.type === 'warning',
+    );
+    expect(warn).toBeDefined();
+    expect(warn!.message).toContain('被覆盖');
+    expect(warn!.message).toContain('alice');
+    expect(warn!.message).toContain('name');
+  });
+
+  it('L2：位置 + --input 混用 —— 位置填 name，--input 填 lang', async () => {
+    // 位置 alice 填 name；--input lang=zh 填 lang（不冲突）
+    const events = await runCmd('/workflow hello-workflow alice --input lang=zh');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    expect(readFileSync(join(tmp, 'greetings', 'alice', 'hello.txt'), 'utf8'))
+      .toBe('Hello, alice! (lang=zh)');
+  });
+
+  it('L2：多余的位置参数被丢弃但会 yield warning（不影响执行）', async () => {
+    // 第 3、4 个位置参数 extra1/extra2 没有 input 槽位 → 丢弃 + warn
+    const events = await runCmd('/workflow hello-workflow alice zh extra1 extra2');
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+    expect(readFileSync(join(tmp, 'greetings', 'alice', 'hello.txt'), 'utf8'))
+      .toBe('Hello, alice! (lang=zh)');
+
+    // 必须有一条 warning 提示多余参数被忽略，且列出具体值
+    const warn = events.find(
+      (e): e is { type: 'warning'; message: string } => e.type === 'warning',
+    );
+    expect(warn).toBeDefined();
+    expect(warn!.message).toContain('忽略了 2 个');
+    expect(warn!.message).toContain('extra1');
+    expect(warn!.message).toContain('extra2');
+  });
+
+  it('L2：位置参数刚好等于 inputs 数量 —— 无 warning', async () => {
+    // alice zh 正好填满 name + lang，无超量、无覆盖 → 不应有 warning
+    const events = await runCmd('/workflow hello-workflow alice zh');
+    expect(events.some((e) => e.type === 'warning')).toBe(false);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 命令路径（runWorkflowFromCommand）成功后补发通用 turn_done 作终结事件（对外协议收口），
+    // 故 turn_done 是最后一条、workflow_done 在其前一条。直测 runWorkflow 的 runner.test.ts 仍以 workflow_done 收尾。
+    expect(events[events.length - 1]?.type).toBe('turn_done');
+  });
+
+  it('/workflows 列表能看到 hello-workflow（cwd 优先双源加载）', async () => {
+    const events = await runCmd('/workflows');
+    const text = events
+      .filter((e): e is Extract<LoopEvent, { type: 'text' }> => e.type === 'text')
+      .map((e) => e.delta)
+      .join('');
+    expect(text).toContain('hello-workflow');
+  });
+});
+
+describe('workflow E2E：assert 失败 → halt（用变体 fixture）', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-e2e-fail-'));
+    mkdirSync(join(tmp, 'workflows'), { recursive: true });
+    // 写一个故意 assert 不通过的 yaml
+    const failYaml = `name: assert-fail-fixture
+description: assert 必失败的端到端 fixture
+steps:
+  - id: write_a
+    tool: Write
+    args:
+      file_path: "a.txt"
+      content: "hi"
+  - id: bad_assert
+    type: assert
+    condition: '1 == 2'
+    onFail: "故意失败"
+  - id: should_not_run
+    tool: Write
+    args:
+      file_path: "b.txt"
+      content: "should not exist"
+`;
+    require('node:fs').writeFileSync(
+      join(tmp, 'workflows', 'assert-fail-fixture.yaml'),
+      failYaml,
+      'utf8',
+    );
+
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    _resetPluginCache();
+    mock.module('../../../src/bootstrap/workingDir.js', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    _resetPluginCache();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('assert 失败 → 后续 step 不执行 + yield error + 没 workflow_done', async () => {
+    const { runWithPlugins } = await import('../../../src/plugins/pluginRunner.js');
+    const events = await collect(
+      runWithPlugins('/workflow assert-fail-fixture', { provider, history: [] }),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+
+    // a.txt 在 assert 前就写盘，应存在
+    expect(existsSync(join(tmp, 'a.txt'))).toBe(true);
+    // b.txt 在 assert 后，不应被写
+    expect(existsSync(join(tmp, 'b.txt'))).toBe(false);
+
+    // 错误信息含 onFail 自定义文案
+    const errs = events
+      .filter((e): e is Extract<LoopEvent, { type: 'error' }> => e.type === 'error')
+      .map((e) => e.error)
+      .join('\n');
+    expect(errs).toContain('故意失败');
+  });
+});