minimal-agent 0.1.8 → 0.2.0

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

@@ -0,0 +1,511 @@
+/**
+ * ============================================================
+ *  test/workflows/runner.test.ts
+ * ------------------------------------------------------------
+ *  runner P0 行为：
+ *    - tool / llm / assert step 成功路径
+ *    - capture 绑变量到 VarStack
+ *    - when=false → workflow_step_skipped
+ *    - onError=halt（默认）→ workflow halt + error
+ *    - onError=continue → 继续下一步
+ *    - 工作流完成 yield workflow_done
+ *
+ *  策略：
+ *    - tool 步骤用真实 Write 工具（写到 tmpdir，避免 mock executeTool）
+ *    - llm 步骤 mock.module('../../../src/llm/client.ts')
+ *    - assert / when 走纯表达式引擎，无需 mock
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.ts';
+import { runWorkflow } from '../src/runner.ts';
+import type {
+  LoopEvent,
+  Provider,
+} from '../../../src/types.ts';
+import type {
+  RunContext,
+  WorkflowDef,
+  WorkflowEvent,
+} from '../src/types.ts';
+
+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/runner', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-runner-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    // 抵抗 pluginRunner.test.ts 等遗留的 workingDir.ts mock 全局污染
+    mock.module('../../../src/bootstrap/workingDir.ts', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+    ctx = { provider: fakeProvider, history: [] };
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('线性 assert step 全通过 → workflow_done', async () => {
+    const def: WorkflowDef = {
+      name: 'pure-assert',
+      description: 'd',
+      steps: [
+        { id: 's1', type: 'assert', condition: '1 == 1' },
+        { id: 's2', type: 'assert', condition: '"a" != "b"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const types = events.map((e) => e.type);
+    expect(types[0]).toBe('workflow_start');
+    expect(types.filter((t) => t === 'workflow_step_end').length).toBe(2);
+    expect(types[types.length - 1]).toBe('workflow_done');
+  });
+
+  it('assert 失败 → halt + error 事件', async () => {
+    const def: WorkflowDef = {
+      name: 'assert-fail',
+      description: 'd',
+      steps: [
+        { id: 's1', type: 'assert', condition: '1 == 2', onFail: 'nope' },
+        { id: 's2', type: 'assert', condition: 'true' }, // 不应执行
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    // s2 不应有 step_start
+    const startedIds = events
+      .filter((e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> => e.type === 'workflow_step_start')
+      .map((e) => e.id);
+    expect(startedIds).toEqual(['s1']);
+    // 没 workflow_done
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+
+  it('onError=continue → 失败后继续下一步', async () => {
+    const def: WorkflowDef = {
+      name: 'continue',
+      description: 'd',
+      steps: [
+        { id: 's1', type: 'assert', condition: 'false', onError: 'continue' },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const ends = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> => e.type === 'workflow_step_end',
+    );
+    expect(ends.length).toBe(2);
+    expect(ends[0].ok).toBe(false);
+    expect(ends[1].ok).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('when=false → workflow_step_skipped 而不是 step_start', async () => {
+    const def: WorkflowDef = {
+      name: 'skip',
+      description: 'd',
+      inputs: [{ name: 'flag', type: 'string' }],
+      steps: [
+        {
+          id: 's1',
+          type: 'assert',
+          condition: 'true',
+          when: 'inputs.flag == "yes"',
+        },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { flag: 'no' }, ctx));
+    const skipped = events.find((e) => e.type === 'workflow_step_skipped');
+    expect(skipped).toBeDefined();
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('tool step 写文件 + ${var} 插值（用真实 Write 工具）', async () => {
+    const def: WorkflowDef = {
+      name: 'wr',
+      description: 'd',
+      inputs: [{ name: 'book', type: 'string' }],
+      steps: [
+        {
+          id: 'w',
+          tool: 'Write',
+          args: {
+            file_path: 'videos/${inputs.book}/x.txt',
+            content: 'hello ${inputs.book}',
+          },
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { book: '原则' }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+
+    const filePath = join(tmp, 'videos', '原则', 'x.txt');
+    expect(existsSync(filePath)).toBe(true);
+    expect(readFileSync(filePath, 'utf8')).toBe('hello 原则');
+  });
+
+  it('capture 把 tool 结果绑到变量，下一步 assert 能用', async () => {
+    const def: WorkflowDef = {
+      name: 'cap',
+      description: 'd',
+      steps: [
+        {
+          id: 'w',
+          tool: 'Write',
+          args: { file_path: 'a.txt', content: 'data' },
+          capture: { content: 'last_write_content' },
+        },
+        {
+          id: 'check',
+          type: 'assert',
+          condition: 'length(last_write_content) > 0',
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('未知 tool → halt + error', async () => {
+    const def: WorkflowDef = {
+      name: 'badtool',
+      description: 'd',
+      steps: [{ id: 'x', tool: 'NoSuchTool9999' }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+  });
+
+  it('llm step 拿 chat 累积文本 + capture text', async () => {
+    mock.module('../../../src/llm/client.ts', () => ({
+      chat: async function* () {
+        yield { type: 'text_delta', delta: 'Hello ' };
+        yield { type: 'text_delta', delta: 'world' };
+        yield { type: 'done', stopReason: 'stop' };
+      },
+    }));
+
+    const def: WorkflowDef = {
+      name: 'llm-cap',
+      description: 'd',
+      steps: [
+        {
+          id: 'g',
+          llm: 'irrelevant',
+          capture: { text: 'msg' },
+        },
+        {
+          id: 'check',
+          type: 'assert',
+          condition: 'msg == "Hello world"',
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('workflow_step_start 的 index 与 total 与 steps 长度一致', async () => {
+    const def: WorkflowDef = {
+      name: 'count',
+      description: 'd',
+      steps: [
+        { id: 'a', type: 'assert', condition: 'true' },
+        { id: 'b', type: 'assert', condition: 'true' },
+        { id: 'c', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const starts = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> => e.type === 'workflow_step_start',
+    );
+    expect(starts.length).toBe(3);
+    expect(starts.map((s) => s.index)).toEqual([0, 1, 2]);
+    expect(starts.every((s) => s.total === 3)).toBe(true);
+  });
+
+  it('signal.aborted → 立即 interrupted', async () => {
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const def: WorkflowDef = {
+      name: 'abort',
+      description: 'd',
+      steps: [{ id: 'a', type: 'assert', condition: 'true' }],
+    };
+    const events = await collect(
+      runWorkflow(def, {}, { provider: fakeProvider, history: [], signal: ctrl.signal }),
+    );
+    expect(events.some((e) => e.type === 'interrupted')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+
+  it('P1 branch step：condition=true → 走 then 分支，输出 branch=true', async () => {
+    const def: WorkflowDef = {
+      name: 'branch-true',
+      description: 'd',
+      inputs: [{ name: 'x', type: 'number' }],
+      steps: [
+        {
+          id: 'br',
+          type: 'branch',
+          condition: 'inputs.x > 0',
+          then: [
+            {
+              id: 'then_w',
+              tool: 'Write',
+              args: { file_path: 'pos.txt', content: 'positive' },
+            },
+          ],
+          else: [
+            {
+              id: 'else_w',
+              tool: 'Write',
+              args: { file_path: 'neg.txt', content: 'negative' },
+            },
+          ],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { x: 5 }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(existsSync(join(tmp, 'pos.txt'))).toBe(true);
+    expect(existsSync(join(tmp, 'neg.txt'))).toBe(false);
+    const ends = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> => e.type === 'workflow_step_end',
+    );
+    // 至少 then_w (1) + br (1) = 2 个 step_end，且都 ok
+    expect(ends.length).toBe(2);
+    expect(ends.every((e) => e.ok)).toBe(true);
+    const brEnd = ends.find((e) => e.id === 'br');
+    expect(brEnd?.output).toBe('branch=true');
+  });
+
+  it('P1 branch step：condition=false → 走 else 分支', async () => {
+    const def: WorkflowDef = {
+      name: 'branch-false',
+      description: 'd',
+      inputs: [{ name: 'x', type: 'number' }],
+      steps: [
+        {
+          id: 'br',
+          type: 'branch',
+          condition: 'inputs.x > 0',
+          then: [{ id: 'then_a', type: 'assert', condition: 'true' }],
+          else: [
+            {
+              id: 'else_w',
+              tool: 'Write',
+              args: { file_path: 'neg.txt', content: 'negative' },
+            },
+          ],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { x: -3 }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(existsSync(join(tmp, 'neg.txt'))).toBe(true);
+    const brEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'br',
+    );
+    expect(brEnd?.output).toBe('branch=false');
+  });
+
+  it('P1 branch step：缺 then/else 也合法（cond 求值后空跳过）', async () => {
+    const def: WorkflowDef = {
+      name: 'branch-empty',
+      description: 'd',
+      steps: [
+        { id: 'br', type: 'branch', condition: '1 == 1' },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const ids = events
+      .filter((e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> => e.type === 'workflow_step_end')
+      .map((e) => e.id);
+    expect(ids).toEqual(['br', 's2']);
+  });
+
+  it('P1 loop step：over=数组字面量，子步骤用 ${as} 和 ${as}_idx', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-lit',
+      description: 'd',
+      steps: [
+        {
+          id: 'lp',
+          type: 'loop',
+          over: '["a", "b", "c"]',
+          as: 'item',
+          do: [
+            {
+              id: 'w',
+              tool: 'Write',
+              args: {
+                file_path: 'items/${item_idx}-${item}.txt',
+                content: 'idx=${item_idx} val=${item}',
+              },
+            },
+          ],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    for (let i = 0; i < 3; i++) {
+      const val = ['a', 'b', 'c'][i];
+      const filePath = join(tmp, 'items', `${i}-${val}.txt`);
+      expect(existsSync(filePath)).toBe(true);
+      expect(readFileSync(filePath, 'utf8')).toBe(`idx=${i} val=${val}`);
+    }
+    const lpEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'lp',
+    );
+    expect(lpEnd?.output).toBe('loop 3 次');
+  });
+
+  it('P1 loop step：迭代变量在循环外不再可见（push/pop 帧）', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-scope',
+      description: 'd',
+      steps: [
+        {
+          id: 'lp',
+          type: 'loop',
+          over: '[1, 2]',
+          as: 'i',
+          do: [{ id: 'noop', type: 'assert', condition: 'i > 0' }],
+        },
+        // 循环外的 ${i} 已 pop —— 这里把它当字符串拿不到，length()=0
+        { id: 'check', type: 'assert', condition: 'length(i) == 0' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('P1 loop step：over 求值不是数组 → halt + error', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-bad-over',
+      description: 'd',
+      steps: [
+        {
+          id: 'lp',
+          type: 'loop',
+          over: '"not an array"',
+          as: 'i',
+          do: [{ id: 'inner', type: 'assert', condition: 'true' }],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+
+  it('P1 pause step：非交互模式直接 skipped + step_end ok', async () => {
+    const def: WorkflowDef = {
+      name: 'pause-skip',
+      description: 'd',
+      steps: [
+        { id: 'p1', type: 'pause', prompt: '等用户确认' },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const skipped = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_skipped' }> =>
+        e.type === 'workflow_step_skipped' && e.id === 'p1',
+    );
+    expect(skipped?.reason).toContain('等用户确认');
+  });
+
+  it('P1 skill step：加载 cwd/skills/<name>/SKILL.md，跑 runQuery 累计 text', async () => {
+    // 在 tmp 准备一个最小 SKILL.md
+    const skillDir = join(tmp, 'skills', 'echo-bot');
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, 'SKILL.md'),
+      '---\nname: echo-bot\ndescription: echo\n---\n\n按用户指示原样输出',
+      'utf8',
+    );
+
+    // skill executor 通过 plugin-sdk.runQuery 调子循环；直接 mock loop.ts
+    // 避开 chat 层（也免疫其它测试文件遗留的 loop.ts mock 污染）。
+    mock.module('../../../src/loop.ts', () => ({
+      runQuery: async function* () {
+        yield { type: 'text', delta: 'echoed-' };
+        yield { type: 'text', delta: 'OK' };
+        yield { type: 'turn_done' };
+      },
+    }));
+
+    const def: WorkflowDef = {
+      name: 'skill-test',
+      description: 'd',
+      steps: [
+        {
+          id: 'sk',
+          skill: 'echo-bot',
+          input: 'say hi',
+          capture: { text: 'msg' },
+        },
+        { id: 'check', type: 'assert', condition: 'msg == "echoed-OK"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('P1 skill step：未找到 skill → halt + error', async () => {
+    const def: WorkflowDef = {
+      name: 'skill-missing',
+      description: 'd',
+      steps: [{ id: 'sk', skill: 'definitely-not-exists' }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+});

package/skills/config/SKILL.md

@@ -38,7 +38,26 @@ Read({ file_path: "~/.minimal-agent/config.json" })
 | `apiKey` | ✅ | API key（敏感信息） |
 | `model` | ✅ | 模型 id，如 `MiniMax-M2.7` |
 | `provider` | ⬜ | 显示名（仅用于状态栏），默认 `env` |
-| `contextWindow` | ⬜ | 模型上下文窗口（token 数），默认 `128000` |
+| `contextWindow` | ⬜ | 模型上下文窗口（token 数），**推荐值见下方速查表**（按 provider+model 推断） |
+| `tavilyApiKey` | ⬜ | Tavily key（WebSearch 工具用）；可留空跳过，免费 key 申请见 https://tavily.com/ |
+
+### Provider 默认值速查表（contextWindow）
+
+权威值见 `src/cli/configWizard.tsx::PRESETS`；本表是它的镜像，发现不一致以代码为准。
+
+| Provider | Model | 推荐 contextWindow |
+|---|---|---|
+| minimax | MiniMax-M2.7 / MiniMax-M1 / abab6.5s-chat | 204800 |
+| deepseek | deepseek-chat / deepseek-reasoner | 128000 |
+| openai | gpt-4o / gpt-4o-mini | 128000 |
+| moonshot | moonshot-v1-8k | 8000 |
+| moonshot | moonshot-v1-32k | 32000 |
+| moonshot | moonshot-v1-128k | 128000 |
+| 其它 / custom | — | 128000 |
+
+⚠️ 询问 `contextWindow` 时，**先按上表给出推荐值并明确告诉用户**（例：「按你选的 `MiniMax-M2.7`，推荐 `contextWindow = 204800`，直接回车采纳」）。**不要让用户裸填 token 数**；用户主要关心 `baseURL` / `apiKey` / `model`，contextWindow 应优先按 provider+model 推断。
+
+如果用户改了 model 但没改 contextWindow，**主动重新计算推荐值**并提示；用户旧 contextWindow 与新 model 不匹配时（如把 model 从 `moonshot-v1-8k` 改成 `moonshot-v1-128k`），明确建议同步更新。
 
 **对话格式示例**（每次只问一个字段，等用户答完再问下一个）：
 
@@ -62,6 +81,7 @@ Write({
     model: <...>,
     provider: <...>,
     contextWindow: <...>,
+    tavilyApiKey: <... or 省略字段>,
     savedAt: Date.now()
   }, null, 2)
 })
@@ -69,6 +89,12 @@ Write({
 
 字段 `savedAt` 必须是当前的 unix 毫秒时间戳。
 
+`tavilyApiKey` 字段策略：
+- 用户没有 Tavily key → **从写入的 JSON 里删掉这个字段**（不要写空串，readSavedConfig 会拒空串）。
+- 用户提供了 key → 写入字符串。
+- 用户没主动改这个字段 → **保留旧值**（不要为了"格式整洁"删除）。
+- 写入后启动注入：下次启动 minimal-agent 时 `applyToolKeysToEnv()`（`src/config.ts`）会把它注入 `process.env.TAVILY_API_KEY`，WebSearch 工具就能用了。
+
 ### Step 4: 提示重启
 
 写入成功后，输出（中文）：

package/skills/image-gen-openrouter/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: image-gen-openrouter
+description: 当用户说"生成图片"、"画一张图"、"配图"、"OpenRouter 生图"、"nano banana"、"image-gen-openrouter"，或在 workflow 里要按提示词生成图片时使用。调用 OpenRouter 的 Chat Completions 接口（OpenAI 兼容 + image modalities），按提示词生成任意比例图片并落盘。
+---
+
+# image-gen-openrouter —— OpenRouter 文生图
+
+> 这是一个**通用 skill**，不绑定特定场景。任何需要文生图的 workflow / 用户对话都能调它。
+
+## 输入约定
+
+调用方传一行 `key=value` 字段串，**字段顺序无要求**，例：
+
+```
+prompt=A cat reading a book in cyberpunk neon city output=./assets/img_0.png aspect=9:16 size=4K model=google/gemini-3-pro-image-preview key=sk-or-...
+```
+
+字段定义：
+- **prompt**（必填）：图片提示词（建议英文，效果更好）。可包含空格 —— 用"剩余串"策略解析（先把其它已知字段抠出去，剩下的就是 prompt）
+- **output**（必填）：目标图片路径（相对 cwd 或绝对）
+- **aspect**（可选，默认 `1:1`）：宽高比；OpenRouter 支持 `1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` 等
+- **size**（可选，默认 `1K`）：分辨率；可选 `0.5K` / `1K` / `2K` / `4K`（部分模型不支持 4K，限流时自动降级）
+- **model**（可选，默认 `google/gemini-3-pro-image-preview`）—— Nano Banana Pro，质量最好；备选 `google/gemini-3.1-flash-image-preview`（便宜）、`google/gemini-2.5-flash-image`（兜底）
+- **key**（可选）：API key；不传则用环境变量 `OPENROUTER_API_KEY`
+
+## 标准执行流程
+
+### 1. 解析输入
+
+仔细从 step.input 里提取 4 个字段。注意 prompt 可能包含空格，所以按"先取 output= / model= / key= 之外的部分作为 prompt"的策略最稳妥。
+
+如果你拿不到 prompt 或 output，立刻报错并返回。
+
+### 2. 取 API key
+
+按优先级：
+1. step.input 里的 `key=` 字段
+2. 用 Bash 跑 `echo "$OPENROUTER_API_KEY"` 看环境变量
+
+两者都空 → 报错 "OpenRouter API key 未配置（既不在 step.input 也不在 OPENROUTER_API_KEY 环境变量）" 并退出。
+
+### 3. 调 OpenRouter API
+
+用 Bash 跑 curl（**注意把变量替换成实际值**）：
+
+```bash
+curl -sS https://openrouter.ai/api/v1/chat/completions \
+  -H "Authorization: Bearer <YOUR_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "<MODEL>",
+    "messages": [{"role": "user", "content": "<PROMPT>"}],
+    "modalities": ["image", "text"],
+    "image_config": {"aspect_ratio": "<ASPECT>", "image_size": "<SIZE>"}
+  }' \
+  -o /tmp/openrouter_resp.json
+```
+
+> 💡 prompt 里若含双引号/特殊字符，用 jq 拼 JSON（**推荐**）：
+> ```bash
+> jq -n --arg p "$PROMPT" --arg m "$MODEL" --arg a "$ASPECT" --arg s "$SIZE" \
+>   '{model:$m, messages:[{role:"user", content:$p}], modalities:["image","text"], image_config:{aspect_ratio:$a, image_size:$s}}' \
+>   | curl -sS https://openrouter.ai/api/v1/chat/completions \
+>       -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+>       --data-binary @- -o /tmp/openrouter_resp.json
+> ```
+
+### 4. 提取 base64 并解码到 PNG
+
+OpenRouter 返回结构（关键字段）：
+```
+.choices[0].message.images[0].image_url.url  →  "data:image/png;base64,iVBORw0KG..."
+```
+
+**Linux/macOS/git-bash on Windows：**
+```bash
+mkdir -p "$(dirname <OUTPUT>)"
+jq -r '.choices[0].message.images[0].image_url.url' /tmp/openrouter_resp.json \
+  | sed 's|^data:image/[a-z]*;base64,||' \
+  | base64 -d > <OUTPUT>
+```
+
+**Windows PowerShell（base64 -d 不存在时）：**
+```powershell
+powershell -NoProfile -Command "$resp = Get-Content /tmp/openrouter_resp.json -Raw | ConvertFrom-Json; $url = $resp.choices[0].message.images[0].image_url.url; $b64 = $url -replace '^data:image/[a-z]+;base64,',''; [IO.File]::WriteAllBytes('<OUTPUT>', [Convert]::FromBase64String($b64))"
+```
+
+### 5. 校验产物
+
+用 Read 工具读 `<OUTPUT>`（offset=0 limit=1）— 触发文件类型嗅探；如果工具报"二进制"或文件 size > 1KB 就视为成功，否则失败。
+
+或者更直接：用 Bash 跑 `ls -la <OUTPUT> | awk '{print $5}'`，size > 10000 字节算成功。
+
+### 6. 处理错误
+
+如果 curl 失败 / OpenRouter 返回 error / base64 解码失败 / 产物太小：
+- 打印 `/tmp/openrouter_resp.json` 头 500 字节（用 Bash `head -c 500`）帮助 debug
+- 如果是 429 限流，sleep 5s 重试一次
+- 仍然失败 → 输出 "image-gen-openrouter 失败：<原因>" 并返回（不要继续往下走）
+
+### 7. 收尾输出
+
+成功后输出**一行** summary（机器友好，方便上游 capture / regex 提取）：
+```
+saved: <OUTPUT> (model=<MODEL>, aspect=<ASPECT>, size=<BYTES>)
+```
+
+## 模型选型快速参考
+
+| 模型 ID | 代号 | 单图成本 | 备注 |
+|---|---|---|---|
+| `google/gemini-3-pro-image-preview` | Nano Banana Pro | 高 | 4K，质量最好，默认 |
+| `google/gemini-3.1-flash-image-preview` | Nano Banana 2 | 中 | 平衡，限流时降级 |
+| `google/gemini-2.5-flash-image` | Nano Banana | 低 | 兜底 |
+
+## 注意事项
+
+- **不要把 API key 打到日志或最终输出里**，curl 错误信息也要小心 grep 掉
+- **不要重试超过 1 次** — 429 / 5xx 各最多 1 次重试，避免烧钱
+- 中文提示词模型可以理解，但效果不如英文 —— 如果调用方给的是中文 prompt，可以保留，但**不要主动翻译**（让上游负责）
+- 调用方决定 `aspect` 和 `size`；本 skill 不做任何场景假设（不绑定竖屏/横屏）