@yswgaicx/yswg-img-cli 0.1.2 → 0.1.4

package/README.md

@@ -30,13 +30,45 @@ yswg-img auth login --email zhangsan --code 123456
 
 The token is saved to `~/.yswg-img-cli/config.json`.
 
+## Agent Usage
+
+Use these rules when an AI agent calls the CLI:
+
+- Prefer `--json` for every command so downstream tools can parse stable output.
+- Use defaults unless the user explicitly asks otherwise: `groupId=6`, model
+  `gemini-3.1-flash-image-preview`, ratio `1:1`, count `1`.
+- For one-shot generation, call:
+
+```bash
+yswg-img generate --prompt "一只可爱的白色兔子，粉色背景" --json
+```
+
+- For up to 4 parallel images in one backend request, call:
+
+```bash
+yswg-img generate --prompt "四张电商产品场景图" --count 4 --json
+```
+
+- For long-running jobs, avoid duplicate submissions:
+
+```bash
+yswg-img generate --prompt "复杂场景图" --no-wait --json
+yswg-img tasks recover --task-id <task-id-from-json> --out outputs/recovered --json
+```
+
+- If sync waiting times out, run `tasks recover` with the returned task ID before
+  submitting the same prompt again.
+- For generated images, keep only local file paths and short summaries in agent
+  context. Do not paste image bytes, base64, `data:image/...`, or full tool
+  output into the conversation.
+
 ## Generate
 
 Supported Monkey Genius options mirrored by the CLI:
 
 - Model/group selection: `--group-id`, `--model`
 - Aspect ratio: `--ratio 1:1|3:2|2:3|4:3|3:4|16:9|9:16|5:4|4:5|21:9`
-- Single/double image output: `--count 1` or `--count 2` when the selected model supports it
+- Concurrent image output: `--count 1` through `--count 4` when the selected model supports it
 - Reference images: `--ref ./a.png,https://example.com/b.jpg`
 - Night/off-peak queue submission: `--night`
 - AI tool/template payloads: `--template-code`, `--template-vars-json`
@@ -59,8 +91,6 @@ Dry-run the backend payload:
 ```bash
 yswg-img generate \
   --prompt "一张白底产品图，柔和自然光，高级电商摄影" \
-  --group-id 5 \
-  --model gemini-2.5-flash-image \
   --ratio 1:1 \
   --count 1 \
   --dry-run \
@@ -72,20 +102,25 @@ Submit and wait for output images:
 ```bash
 yswg-img generate \
   --prompt "一张白底产品图，柔和自然光，高级电商摄影" \
-  --group-id 5 \
-  --model gemini-2.5-flash-image \
   --ratio 1:1 \
-  --count 1 \
+  --count 4 \
   --out outputs \
   --json
 ```
 
+The CLI caps one generation request at 4 images. When the backend returns
+multiple task IDs, the CLI waits for those tasks concurrently and downloads the
+result files by path.
+
+For image-heavy workflows, keep local file paths and short summaries in agent
+context. Do not paste high-resolution image data, base64, `data:image/...`, or
+full tool output into the conversation.
+
 Use reference images:
 
 ```bash
 yswg-img generate \
   --prompt "参考产品主体，生成室内生活方式场景图" \
-  --group-id 5 \
   --ref ./product.png,https://example.com/ref.jpg \
   --out outputs \
   --json
@@ -95,7 +130,7 @@ Use an AI tool/template payload:
 
 ```bash
 yswg-img generate \
-  --group-id 1 \
+  --group-id 6 \
   --template-code tool_code \
   --template-vars-json '{"color":"red"}' \
   --display-prompt "AI 工具生成" \
@@ -106,7 +141,7 @@ yswg-img generate \
 Submit only and return task IDs:
 
 ```bash
-yswg-img generate --prompt "..." --group-id 5 --no-wait --json
+yswg-img generate --prompt "..." --no-wait --json
 ```
 
 If a long generation times out or the WebSocket disconnects, the CLI now checks
@@ -116,7 +151,7 @@ submitting the same prompt again when the image was already produced.
 Tune the wait timeout:
 
 ```bash
-yswg-img generate --prompt "..." --group-id 5 --timeout 900 --json
+yswg-img generate --prompt "..." --timeout 900 --json
 ```
 
 Query recent task history without creating a new generation task:
@@ -163,3 +198,15 @@ Flags override environment variables, which override the saved config.
 - `YSWG_WS_PATH`
 
 Default app ID: `2014153035982319618`.
+Default ratio: `1:1`.
+Default generation model: `gemini-3.1-flash-image-preview` (`groupId=6`, 三代).
+
+## Code Structure
+
+- `bin/yswg-img.js`: executable entrypoint only.
+- `src/cli.js`: command dispatch, dependency injection, JSON output, and agent help text.
+- `src/generate.js`: generation payloads, validation, history recovery, WebSocket wait, uploads, downloads.
+- `src/api.js`: YSWG HTTP API client.
+- `src/config.js`: config loading, env/flag precedence, email normalization.
+- `src/args.js`: minimal CLI argument parsing.
+- `src/image-compress.js`: frontend-compatible reference image compression.

package/bin/yswg-img.js

@@ -1,257 +1,7 @@
 #!/usr/bin/env node
-import { parseArgs, readFlag, splitCsv } from "../src/args.js";
-import { loadConfig, normalizeEmail, resolveConfig, saveConfig, DEFAULT_CONFIG_PATH } from "../src/config.js";
-import { YswgApi } from "../src/api.js";
-import {
-  buildGeneratePayload,
-  downloadImages,
-  extractImageUrls,
-  findModelByGroupId,
-  findRecordsByInvokeTaskIds,
-  isTimeoutLikeError,
-  normalizeHistoryLimit,
-  normalizeTaskSearchParams,
-  parseTemplateInput,
-  taskImageUrlsFromRecord,
-  uploadReferences,
-  validateGenerateOptions,
-  waitForTask,
-} from "../src/generate.js";
+import { runCli } from "../src/cli.js";
 
-function printHelp() {
-  console.log(`yswg-img
-
-Commands:
-  auth send-code --email <name|email>
-  auth login --email <name|email> --code <6 digits>
-  models [--app-id <id>]
-  templates [--app-id <id>] [--json]
-  tasks search [--size 10] [--keyword <text>] [--tab all|expiring1d|expiring2d|nightQueue] [--json]
-  tasks get --id <record-id> [--json]
-  tasks recover --task-id <invoke-task-id>[,<id>] [--out outputs] [--json]
-  tasks delete --id <record-id> [--json]
-  tasks cancel-night --id <record-id> [--json]
-  generate --prompt <text> --group-id <id> [--model <name>] [--ratio 1:1] [--count 1] [--ref a.png,b.jpg] [--template-code <code>] [--template-vars-json '{}'] [--no-compress] [--out outputs]
-
-Environment:
-  YSWG_TOKEN, YSWG_REFRESH_TOKEN, YSWG_APP_ID, YSWG_BASE_URL, YSWG_WS_PATH
-
-Config:
-  ${DEFAULT_CONFIG_PATH}
-`);
-}
-
-function output(data, json = false) {
-  if (json) console.log(JSON.stringify(data, null, 2));
-  else if (typeof data === "string") console.log(data);
-  else console.log(JSON.stringify(data, null, 2));
-}
-
-async function main() {
-  const parsed = parseArgs(process.argv.slice(2));
-  const { command, subcommand, flags } = parsed;
-  const json = Boolean(flags.json);
-  if (command === "help" || flags.help) return printHelp();
-
-  const config = await loadConfig();
-  const resolved = resolveConfig(config, flags);
-  const api = new YswgApi(resolved);
-
-  if (command === "auth" && subcommand === "send-code") {
-    const email = normalizeEmail(readFlag(flags, ["email", "e"]));
-    const check = await api.checkEmail(email);
-    if (check?.registered === false) throw new Error(check.message || "email is not registered");
-    await api.sendCode(email);
-    output({ ok: true, email, message: "验证码已发送，请在企业微信中查收" }, json);
-    return;
-  }
-
-  if (command === "auth" && subcommand === "login") {
-    const email = normalizeEmail(readFlag(flags, ["email", "e"]));
-    const code = String(readFlag(flags, ["code", "c"], "")).trim();
-    if (!code) throw new Error("missing --code");
-    const session = await api.login(email, code);
-    const next = {
-      ...config,
-      baseUrl: resolved.baseUrl,
-      appId: resolved.appId,
-      wsPath: resolved.wsPath,
-      token: session.token,
-      refreshToken: session.refreshToken,
-      user: session,
-      email,
-    };
-    await saveConfig(next);
-    output({ ok: true, email, configPath: DEFAULT_CONFIG_PATH }, json);
-    return;
-  }
-
-  if (command === "models") {
-    const models = await api.models(resolved.appId);
-    output(models, json);
-    return;
-  }
-
-  if (command === "templates") {
-    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
-    const templates = await api.templates(String(readFlag(flags, ["appId"], resolved.appId)));
-    output(templates, json);
-    return;
-  }
-
-  if (command === "tasks" && subcommand === "search") {
-    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
-    const result = await api.searchGenTasks(normalizeTaskSearchParams({
-      tab: String(readFlag(flags, ["tab"], "all")),
-      keyword: String(readFlag(flags, ["keyword", "q"], "")),
-      userId: config.user?.userId || config.user?.id,
-      appId: String(readFlag(flags, ["appId"], resolved.appId)),
-      size: readFlag(flags, ["size"], 10),
-    }));
-    output(result, json);
-    return;
-  }
-
-  if (command === "tasks" && subcommand === "get") {
-    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
-    const id = String(readFlag(flags, ["id"], "")).trim();
-    if (!id) throw new Error("missing --id");
-    const record = await api.genTask(id);
-    output(record, json);
-    return;
-  }
-
-  if (command === "tasks" && subcommand === "delete") {
-    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
-    const id = String(readFlag(flags, ["id"], "")).trim();
-    if (!id) throw new Error("missing --id");
-    await api.deleteGenTask(id);
-    output({ ok: true, id }, json);
-    return;
-  }
-
-  if (command === "tasks" && subcommand === "cancel-night") {
-    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
-    const id = String(readFlag(flags, ["id"], "")).trim();
-    if (!id) throw new Error("missing --id");
-    await api.cancelNightTask(id);
-    output({ ok: true, id }, json);
-    return;
-  }
-
-  if (command === "tasks" && subcommand === "recover") {
-    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
-    const taskIds = splitCsv(readFlag(flags, ["taskId", "taskIds", "id"], ""));
-    if (!taskIds.length) throw new Error("missing --task-id");
-    const records = await findRecordsByInvokeTaskIds(api, {
-      taskIds,
-      appId: String(readFlag(flags, ["appId"], resolved.appId)),
-      userId: config.user?.userId || config.user?.id,
-      pageSize: normalizeHistoryLimit(readFlag(flags, ["size"], 10)),
-      maxPages: 1,
-    });
-    const imageUrls = records.flatMap((record) => taskImageUrlsFromRecord(record));
-    if (!imageUrls.length) throw new Error("最近 10 条生成记录里还没有找到该任务结果；如果需要查看更多，请去导航站「天才猴子」页面查询。");
-    const files = flags.out === "none" ? [] : await downloadImages(imageUrls, String(readFlag(flags, ["out"], "outputs")));
-    output({ ok: true, taskIds, recordIds: records.map((record) => record.id), imageUrls, files }, json);
-    return;
-  }
-
-  if (command === "generate") {
-    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
-    const prompt = String(readFlag(flags, ["prompt", "p"], "")).trim();
-    const refs = splitCsv(readFlag(flags, ["ref", "refs"], ""));
-    const refImages = await uploadReferences(api, refs, { compress: !flags.noCompress });
-    const groupId = String(readFlag(flags, ["groupId", "group"], ""));
-    const model = String(readFlag(flags, ["model", "m"], "gemini-2.5-flash-image"));
-    const ratio = String(readFlag(flags, ["ratio", "r"], "1:1"));
-    const imageCount = Number(readFlag(flags, ["count", "imageCount"], 1));
-    const templateInput = parseTemplateInput({
-      code: String(readFlag(flags, ["templateCode", "template"], "")),
-      varsJson: String(readFlag(flags, ["templateVarsJson", "varsJson"], "")),
-      displayPrompt: String(readFlag(flags, ["displayPrompt"], "")),
-    });
-
-    if (!flags.skipValidate) {
-      const modelGroups = await api.models(resolved.appId);
-      validateGenerateOptions({
-        model: findModelByGroupId(modelGroups, groupId),
-        ratio,
-        imageCount,
-      });
-    }
-
-    const payload = buildGeneratePayload({
-      appId: resolved.appId,
-      groupId,
-      prompt,
-      model,
-      ratio,
-      imageCount,
-      refImages,
-      size: String(readFlag(flags, ["size"], "")),
-      night: Boolean(flags.night),
-      templates: templateInput.templates,
-      displayPrompt: templateInput.displayPrompt,
-    });
-
-    if (flags.dryRun) {
-      output({ payload }, json);
-      return;
-    }
-
-    const taskIds = await api.createTasks(payload);
-    const ids = Array.isArray(taskIds) ? taskIds : [taskIds?.taskId || taskIds?.id].filter(Boolean);
-    if (!ids.length) throw new Error("create task did not return task ids");
-
-    if (flags.noWait || flags.night) {
-      output({ ok: true, taskIds: ids, payload }, json);
-      return;
-    }
-
-    const timeoutMs = Number(readFlag(flags, ["timeoutMs"], Number(readFlag(flags, ["timeout"], 3600)) * 1000));
-    let imageUrls = [];
-    let waitError;
-    try {
-      const messages = await Promise.all(ids.map((taskId) => waitForTask({
-        baseUrl: resolved.baseUrl,
-        token: resolved.token,
-        wsPath: resolved.wsPath,
-        taskId,
-        timeoutMs,
-      })));
-      imageUrls = messages.flatMap((message) => extractImageUrls(message.responseJson));
-    } catch (error) {
-      if (!isTimeoutLikeError(error)) throw error;
-      waitError = error;
-    }
-
-    if (!imageUrls.length) {
-      const records = await findRecordsByInvokeTaskIds(api, {
-        taskIds: ids,
-        appId: resolved.appId,
-        userId: config.user?.userId || config.user?.id,
-        pageSize: 10,
-        maxPages: 1,
-      });
-      imageUrls = records.flatMap((record) => taskImageUrlsFromRecord(record));
-    }
-
-    if (!imageUrls.length && waitError) {
-      const error = new Error(`${waitError.message}; 最近 10 条生成记录里还没有找到该任务结果。请稍后用 tasks recover --task-id <id> 查询；如果需要查看更多，请去导航站「天才猴子」页面查询，避免重复提交同一任务。`);
-      error.cause = waitError;
-      throw error;
-    }
-
-    const files = flags.out === "none" ? [] : await downloadImages(imageUrls, String(readFlag(flags, ["out"], "outputs")));
-    output({ ok: true, taskIds: ids, imageUrls, files }, json);
-    return;
-  }
-
-  printHelp();
-}
-
-main().catch((error) => {
+runCli(process.argv.slice(2)).catch((error) => {
   console.error(`yswg-img: ${error.message}`);
   process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yswgaicx/yswg-img-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI wrapper for YSWG Monkey Genius image generation.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -0,0 +1,288 @@
+import { parseArgs, readFlag, splitCsv } from "./args.js";
+import { loadConfig, normalizeEmail, resolveConfig, saveConfig, DEFAULT_CONFIG_PATH } from "./config.js";
+import { YswgApi } from "./api.js";
+import {
+  buildGeneratePayload,
+  DEFAULT_GENERATE_OPTIONS,
+  downloadImages,
+  extractImageUrls,
+  findModelByGroupId,
+  findRecordsByInvokeTaskIds,
+  isTimeoutLikeError,
+  normalizeImageCount,
+  normalizeHistoryLimit,
+  normalizeTaskSearchParams,
+  parseTemplateInput,
+  taskImageUrlsFromRecord,
+  uploadReferences,
+  validateGenerateOptions,
+  waitForTask,
+} from "./generate.js";
+
+export function buildHelpText() {
+  return `yswg-img
+
+Commands:
+  auth send-code --email <name|email>
+  auth login --email <name|email> --code <6 digits>
+  models [--app-id <id>]
+  templates [--app-id <id>] [--json]
+  tasks search [--size 10] [--keyword <text>] [--tab all|expiring1d|expiring2d|nightQueue] [--json]
+  tasks get --id <record-id> [--json]
+  tasks recover --task-id <invoke-task-id>[,<id>] [--out outputs] [--json]
+  tasks delete --id <record-id> [--json]
+  tasks cancel-night --id <record-id> [--json]
+  generate --prompt <text> [--group-id 6] [--model gemini-3.1-flash-image-preview] [--ratio 1:1] [--count 1-4] [--ref a.png,b.jpg] [--template-code <code>] [--template-vars-json '{}'] [--no-compress] [--out outputs]
+
+Agent usage:
+  Always prefer --json for machine-readable output.
+  Defaults: group-id=6, model=gemini-3.1-flash-image-preview, ratio=1:1, count=1.
+  One generate request supports count 1-4. For larger batches, split calls.
+  For long tasks, use --no-wait first, then tasks recover --task-id <id>.
+  Keep generated image file paths and short summaries in agent context; do not paste image bytes or base64.
+
+Environment:
+  YSWG_TOKEN, YSWG_REFRESH_TOKEN, YSWG_APP_ID, YSWG_BASE_URL, YSWG_WS_PATH
+
+Config:
+  ${DEFAULT_CONFIG_PATH}
+`;
+}
+
+function writeOutput(write, data, json = false) {
+  const text = json || typeof data !== "string"
+    ? JSON.stringify(data, null, 2)
+    : data;
+  write(`${text}\n`);
+}
+
+function assertAuthenticated(resolved) {
+  if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
+}
+
+function getUserId(config) {
+  return config.user?.userId || config.user?.id;
+}
+
+function normalizeTaskIds(taskIds) {
+  if (Array.isArray(taskIds)) return taskIds;
+  return [taskIds?.taskId || taskIds?.id].filter(Boolean);
+}
+
+async function recoverImageUrlsFromHistory(api, { taskIds, appId, userId }) {
+  const records = await findRecordsByInvokeTaskIds(api, {
+    taskIds,
+    appId,
+    userId,
+    pageSize: 10,
+    maxPages: 1,
+  });
+  return records.flatMap((record) => taskImageUrlsFromRecord(record));
+}
+
+async function waitForImageUrls({ ids, resolved, timeoutMs }) {
+  const messages = await Promise.all(ids.map((taskId) => waitForTask({
+    baseUrl: resolved.baseUrl,
+    token: resolved.token,
+    wsPath: resolved.wsPath,
+    taskId,
+    timeoutMs,
+  })));
+  return messages.flatMap((message) => extractImageUrls(message.responseJson));
+}
+
+async function handleGenerate({ api, config, flags, resolved, json, write }) {
+  assertAuthenticated(resolved);
+  const prompt = String(readFlag(flags, ["prompt", "p"], "")).trim();
+  const refs = splitCsv(readFlag(flags, ["ref", "refs"], ""));
+  const refImages = await uploadReferences(api, refs, { compress: !flags.noCompress });
+  const groupId = String(readFlag(flags, ["groupId", "group"], DEFAULT_GENERATE_OPTIONS.groupId));
+  const model = String(readFlag(flags, ["model", "m"], DEFAULT_GENERATE_OPTIONS.model));
+  const ratio = String(readFlag(flags, ["ratio", "r"], DEFAULT_GENERATE_OPTIONS.ratio));
+  const imageCount = normalizeImageCount(readFlag(flags, ["count", "imageCount"], DEFAULT_GENERATE_OPTIONS.imageCount));
+  const templateInput = parseTemplateInput({
+    code: String(readFlag(flags, ["templateCode", "template"], "")),
+    varsJson: String(readFlag(flags, ["templateVarsJson", "varsJson"], "")),
+    displayPrompt: String(readFlag(flags, ["displayPrompt"], "")),
+  });
+
+  if (!flags.skipValidate) {
+    const modelGroups = await api.models(resolved.appId);
+    validateGenerateOptions({
+      model: findModelByGroupId(modelGroups, groupId),
+      ratio,
+      imageCount,
+    });
+  }
+
+  const payload = buildGeneratePayload({
+    appId: resolved.appId,
+    groupId,
+    prompt,
+    model,
+    ratio,
+    imageCount,
+    refImages,
+    size: String(readFlag(flags, ["size"], "")),
+    night: Boolean(flags.night),
+    templates: templateInput.templates,
+    displayPrompt: templateInput.displayPrompt,
+  });
+
+  if (flags.dryRun) {
+    writeOutput(write, { payload }, json);
+    return;
+  }
+
+  const ids = normalizeTaskIds(await api.createTasks(payload));
+  if (!ids.length) throw new Error("create task did not return task ids");
+
+  if (flags.noWait || flags.night) {
+    writeOutput(write, { ok: true, taskIds: ids, payload }, json);
+    return;
+  }
+
+  const timeoutMs = Number(readFlag(flags, ["timeoutMs"], Number(readFlag(flags, ["timeout"], 3600)) * 1000));
+  let imageUrls = [];
+  let waitError;
+  try {
+    imageUrls = await waitForImageUrls({ ids, resolved, timeoutMs });
+  } catch (error) {
+    if (!isTimeoutLikeError(error)) throw error;
+    waitError = error;
+  }
+
+  if (!imageUrls.length) {
+    imageUrls = await recoverImageUrlsFromHistory(api, {
+      taskIds: ids,
+      appId: resolved.appId,
+      userId: getUserId(config),
+    });
+  }
+
+  if (!imageUrls.length && waitError) {
+    const error = new Error(`${waitError.message}; 最近 10 条生成记录里还没有找到该任务结果。请稍后用 tasks recover --task-id <id> 查询；如果需要查看更多，请去导航站「天才猴子」页面查询，避免重复提交同一任务。`);
+    error.cause = waitError;
+    throw error;
+  }
+
+  const files = flags.out === "none" ? [] : await downloadImages(imageUrls, String(readFlag(flags, ["out"], "outputs")));
+  writeOutput(write, { ok: true, taskIds: ids, imageUrls, files }, json);
+}
+
+async function handleTaskCommand({ api, config, flags, resolved, subcommand, json, write }) {
+  if (!["search", "get", "delete", "cancel-night", "recover"].includes(subcommand)) return false;
+  assertAuthenticated(resolved);
+  if (subcommand === "search") {
+    const result = await api.searchGenTasks(normalizeTaskSearchParams({
+      tab: String(readFlag(flags, ["tab"], "all")),
+      keyword: String(readFlag(flags, ["keyword", "q"], "")),
+      userId: getUserId(config),
+      appId: String(readFlag(flags, ["appId"], resolved.appId)),
+      size: readFlag(flags, ["size"], 10),
+    }));
+    writeOutput(write, result, json);
+    return true;
+  }
+
+  const id = String(readFlag(flags, ["id"], "")).trim();
+  if (subcommand === "get") {
+    if (!id) throw new Error("missing --id");
+    writeOutput(write, await api.genTask(id), json);
+    return true;
+  }
+  if (subcommand === "delete") {
+    if (!id) throw new Error("missing --id");
+    await api.deleteGenTask(id);
+    writeOutput(write, { ok: true, id }, json);
+    return true;
+  }
+  if (subcommand === "cancel-night") {
+    if (!id) throw new Error("missing --id");
+    await api.cancelNightTask(id);
+    writeOutput(write, { ok: true, id }, json);
+    return true;
+  }
+  if (subcommand === "recover") {
+    const taskIds = splitCsv(readFlag(flags, ["taskId", "taskIds", "id"], ""));
+    if (!taskIds.length) throw new Error("missing --task-id");
+    const records = await findRecordsByInvokeTaskIds(api, {
+      taskIds,
+      appId: String(readFlag(flags, ["appId"], resolved.appId)),
+      userId: getUserId(config),
+      pageSize: normalizeHistoryLimit(readFlag(flags, ["size"], 10)),
+      maxPages: 1,
+    });
+    const imageUrls = records.flatMap((record) => taskImageUrlsFromRecord(record));
+    if (!imageUrls.length) throw new Error("最近 10 条生成记录里还没有找到该任务结果；如果需要查看更多，请去导航站「天才猴子」页面查询。");
+    const files = flags.out === "none" ? [] : await downloadImages(imageUrls, String(readFlag(flags, ["out"], "outputs")));
+    writeOutput(write, { ok: true, taskIds, recordIds: records.map((record) => record.id), imageUrls, files }, json);
+    return true;
+  }
+}
+
+export async function runCli(argv, {
+  loadConfigFn = loadConfig,
+  saveConfigFn = saveConfig,
+  createApi = (resolved) => new YswgApi(resolved),
+  write = (text) => process.stdout.write(text),
+} = {}) {
+  const parsed = parseArgs(argv);
+  const { command, subcommand, flags } = parsed;
+  const json = Boolean(flags.json);
+  if (command === "help" || flags.help) {
+    write(buildHelpText());
+    return;
+  }
+
+  const config = await loadConfigFn();
+  const resolved = resolveConfig(config, flags);
+  const api = createApi(resolved);
+
+  if (command === "auth" && subcommand === "send-code") {
+    const email = normalizeEmail(readFlag(flags, ["email", "e"]));
+    const check = await api.checkEmail(email);
+    if (check?.registered === false) throw new Error(check.message || "email is not registered");
+    await api.sendCode(email);
+    writeOutput(write, { ok: true, email, message: "验证码已发送，请在企业微信中查收" }, json);
+    return;
+  }
+
+  if (command === "auth" && subcommand === "login") {
+    const email = normalizeEmail(readFlag(flags, ["email", "e"]));
+    const code = String(readFlag(flags, ["code", "c"], "")).trim();
+    if (!code) throw new Error("missing --code");
+    const session = await api.login(email, code);
+    await saveConfigFn({
+      ...config,
+      baseUrl: resolved.baseUrl,
+      appId: resolved.appId,
+      wsPath: resolved.wsPath,
+      token: session.token,
+      refreshToken: session.refreshToken,
+      user: session,
+      email,
+    });
+    writeOutput(write, { ok: true, email, configPath: DEFAULT_CONFIG_PATH }, json);
+    return;
+  }
+
+  if (command === "models") {
+    writeOutput(write, await api.models(resolved.appId), json);
+    return;
+  }
+
+  if (command === "templates") {
+    assertAuthenticated(resolved);
+    writeOutput(write, await api.templates(String(readFlag(flags, ["appId"], resolved.appId))), json);
+    return;
+  }
+
+  if (command === "tasks" && await handleTaskCommand({ api, config, flags, resolved, subcommand, json, write })) return;
+  if (command === "generate") {
+    await handleGenerate({ api, config, flags, resolved, json, write });
+    return;
+  }
+
+  write(buildHelpText());
+}

package/src/generate.js

@@ -2,6 +2,26 @@ import { basename } from "node:path";
 import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { compressImageBuffer } from "./image-compress.js";
 
+export const DEFAULT_GENERATE_OPTIONS = {
+  groupId: "6",
+  model: "gemini-3.1-flash-image-preview",
+  ratio: "1:1",
+  imageCount: 1,
+};
+
+export const MAX_IMAGE_GENERATION_CONCURRENCY = 4;
+
+export function normalizeImageCount(value, fallback = DEFAULT_GENERATE_OPTIONS.imageCount) {
+  const count = Number(value ?? fallback);
+  if (!Number.isFinite(count)) return fallback;
+  const normalized = Math.floor(count);
+  if (normalized < 1) throw new Error(`图片数量必须是 1 到 ${MAX_IMAGE_GENERATION_CONCURRENCY}`);
+  if (normalized > MAX_IMAGE_GENERATION_CONCURRENCY) {
+    throw new Error(`CLI 单次生图最多支持 ${MAX_IMAGE_GENERATION_CONCURRENCY} 张，请拆分多次调用。`);
+  }
+  return normalized;
+}
+
 export function buildGeneratePayload({
   appId,
   groupId,