museav-cli 3.0.0 → 3.0.2

package/AGENTS.md

@@ -6,6 +6,24 @@ This CLI is designed to be used directly by coding agents (Claude Code, Codex, e
 
 A command-line client for the "studio" image-generation platform (`https://manager.museav.top`). It generates images from a prompt, reverse-engineers a prompt from an existing image, and lists your own generation history. All output is designed for machine consumption: **stdout carries only the final result** (a URL, a prompt string, or JSON); progress and human-readable info goes to stderr.
 
+## Scope: this tool makes *assets*, not finished videos
+
+Know the boundary before you pick a tool:
+
+| You need | Use |
+|---|---|
+| An image, or a raw video clip from a model | `museav gen` (add `--video`) |
+| Cut out a background / upscale / de-watermark / compress | `museav remove-bg` / `upscale` / `remove-watermark` / `compress` |
+| **A finished vertical short video** (images + per-shot captions + BGM/voiceover, templated) | **[reel-kit](https://github.com/webkubor/reel-kit)** — `reel make` |
+
+`museav gen --video` gives you a **silent, caption-less clip** — that's raw material, not
+something you post. Assembling material into a publishable short is reel-kit's job: its
+layouts are HTML/CSS templates, it does voiceover, and **shot length follows the narration**.
+
+> `museav slideshow` existed in 2.9–2.10 and was **retired in 3.0.0** — it duplicated
+> reel-kit. The command still exists as a stub that prints migration instructions.
+> Don't try to bring it back; use reel-kit.
+
 ## Auth: pick one identity, not both
 
 - **You're acting as an individual user** (a person's own account): `museav login` — opens a device-authorization flow (prints a code + URL, polls until the user approves in a browser). Token cached in `~/.museav.json`, valid 7 days.

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 3.0.1 (2026-08-28)
+
+### 把 reel-kit 的推荐位做实
+
+3.0.0 只是下线了 slideshow，但没告诉人「那该用什么」——README 里只有一句藏在引用块里的
+说明，agent 读的 AGENTS.md 里一个字都没提。补三处：
+
+- **README** 加独立小节「🎬 要出成品视频？用 reel-kit」，带命令示例与分工对照表
+- **AGENTS.md** 加 "Scope: this tool makes *assets*, not finished videos" ——
+  agent 被要求「做个视频」时，第一眼就能看到该去哪
+- **`gen --video` 出片后提示一行**：模型出的是无声无字幕素材，不是成品。
+  这不是广告，是防止两种误解——以为「出完了」，或以为 museav 该管配音烧字幕
+
+典型链路写清楚了：`museav gen` 出图 → `museav remove-bg` 抠图 → `reel make` 出片。
+
 ## 3.0.0 (2026-08-28)
 
 ### 破坏性变更：`slideshow` / `slideshow-layouts` 下线，出片改用 reel-kit

package/README.md

@@ -108,12 +108,38 @@
 
 > 本地工具（`compress` / `remove-bg` / `upscale` / `remove-watermark`）**不用登录、不花一分钱**，装了就能用；其余命令需要一个凭证（个人 `login` 或租户 apiKey）。
 >
-> **出成品视频不在这里** —— 图集转竖版短视频、配音、烧字幕走 [reel-kit](https://github.com/webkubor/reel-kit)（`reel` 命令）。
-> museav 管的是**素材**（抠图/超分/去水印/AI 生成），reel-kit 管**成品合成**。曾经有过 `museav slideshow`，3.0.0 已下线，见 CHANGELOG。
->
 > 语音（`speak` / `transcribe`）是第三种情况：**不走中台身份**，直连小米 MiMo，只认 `MIMO_API_KEY` 环境变量。
 > 中台的出音链路还没接完，这批能力目前内部用，没有那把 key 的人（包括租户）用不了。
 
+### 🎬 要出成品视频？用 [reel-kit](https://github.com/webkubor/reel-kit)
+
+museav 出的是**素材**：`gen --video` 给你的是一段**无声、无字幕的片子**，
+那是原料，不是能直接发的成品。把素材装配成能发的竖版短片是
+**[reel-kit](https://github.com/webkubor/reel-kit)** 的活：
+
+```bash
+reel make --template sticker-promo \
+  --assets ./图片目录 --caps 文案.txt \
+  --title "标题" --bgm 儿童轻快 --out 成片.mp4
+```
+
+- 版式是 `templates/*.html`，**改 CSS 就是改版式**，丢一个 HTML 进去就是一个新模板
+- 支持配音，且**镜头时长跟着念白走**（念快的不干等，念慢的不被切）
+- 配音默认走本地 TTS，批量出片不花钱
+
+两边的分工是明确的，reel-kit 也在它的 README 里写了同一条边界：
+
+| 你要的 | 用谁 |
+|---|---|
+| 一张图 / 一段模型出的原始片子 | `museav gen`（加 `--video`） |
+| 抠图 / 超分 / 去水印 / 压缩 | `museav remove-bg` / `upscale` / `remove-watermark` / `compress` |
+| **一支能直接发的竖版短片** | **`reel make`** |
+
+典型链路：`museav gen` 出图 → `museav remove-bg` 抠图 → `reel make` 出片。
+
+> `museav slideshow` 在 2.9~2.10 存在过，**3.0.0 已下线** —— 它和 reel-kit 重复了。
+> 命令还在但只会打印迁移说明。详见 [CHANGELOG](./CHANGELOG.md)。
+
 ---
 
 ## 快速开始
@@ -443,27 +469,16 @@ museav remove-watermark photo.jpg --mask mask.png      # 复杂画面手工掩
 - 依赖红线：本地**绝不自动拉起开源大模型**——这些工具是轻量 CNN/传统算法，用完即释放内存。reverse 的本地路已翻回显式 `--local`（需自备 Ollama），默认走中台 API。
 - 二进制与模型缓存：`~/.museav-bin/upscayl`（引擎）、`~/.museav-models/`（模型），Windows 对应 `%USERPROFILE%` 下同名目录；删除即彻底清理。
 
-### 出成品视频请用 reel-kit（不在本 CLI）
+### 出成品视频：走 reel-kit
 
-图集转竖版短视频、配音、烧字幕这些**成品合成**能力在
-[reel-kit](https://github.com/webkubor/reel-kit)（`reel` 命令），不在 museav：
+不在本 CLI，见上面 [🎬 要出成品视频](#-要出成品视频用-reel-kit)。常用三条：
 
 ```bash
-reel make --template sticker-promo \
-  --assets ./图片目录 --caps 文案.txt \
-  --title "标题" --bgm 儿童轻快 --out 成片.mp4
-
-reel templates    # 看版式（模板是 templates/*.html，丢一个进去就是新版式）
-reel bgm          # 看配乐库（带授权信息）
+reel make --template sticker-promo --assets ./图 --caps 文案.txt --out 成片.mp4
+reel templates    # 看版式
+reel bgm          # 看配乐库（带授权）
 ```
 
-2.9.0 曾在 museav 做过一个 `slideshow`，当天就发现 reel-kit 早已做了同一件事而且更好
-（HTML/CSS 排版能换行、支持配音且镜头时长由念白决定、本地 TTS 零成本），
-**3.0.0 已下线**，命令留了存根打印迁移说明。
-
-职责边界：**museav 管素材**（`remove-bg` 抠图、`upscale` 超分、`gen` 出图出视频素材），
-**reel-kit 管成品合成**。同一件事没必要两套实现。
-
 
 ### 项目（工作区）与项目素材库 `projects`
 

package/dist/client.d.ts

@@ -356,6 +356,28 @@ export declare class StudioClient {
     }>;
     /** 查单个任务状态 */
     getJob(id: string): Promise<Job>;
+    /**
+     * 批量提交出图（POST /api/generate-batch）。
+     * items 每项与 generate 的请求体同构；defaults 是公共字段（skill/ratio 等），项内覆盖。
+     * 服务端逐项走与单张同一套流程；撞频控/积分不足时后续项 skipped 并带 retry_after_sec，
+     * 客户端睡够后只补提交 skipped 的部分即可（jobId 已拿到的不要重发）。
+     */
+    generateBatch(items: Array<Record<string, unknown>>, defaults?: Record<string, unknown>): Promise<{
+        ok: boolean;
+        accepted: number;
+        submitted: number;
+        results: Array<{
+            ok: boolean;
+            jobId?: string;
+            trace_id?: string;
+            status?: number;
+            error?: string;
+            skipped?: boolean;
+            reason?: string;
+            retry_after_sec?: number;
+        }>;
+        retry_after_sec?: number;
+    }>;
     /** 列当前账户的工作区（含生成统计） */
     workspaces(): Promise<Workspace[]>;
     /** 新建工作区（最多 5 个，超了服务端会 400） */

package/dist/client.js

@@ -210,6 +210,22 @@ export class StudioClient {
         const r = await this.request(`jobs?id=${encodeURIComponent(id)}`);
         return r;
     }
+    /**
+     * 批量提交出图（POST /api/generate-batch）。
+     * items 每项与 generate 的请求体同构；defaults 是公共字段（skill/ratio 等），项内覆盖。
+     * 服务端逐项走与单张同一套流程；撞频控/积分不足时后续项 skipped 并带 retry_after_sec，
+     * 客户端睡够后只补提交 skipped 的部分即可（jobId 已拿到的不要重发）。
+     */
+    async generateBatch(items, defaults) {
+        const body = { items };
+        if (defaults)
+            body.defaults = defaults;
+        return this.request('generate-batch', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
     // ── 工作区（项目）与项目素材库 ──
     // 平台 → 账户 → 工作区三层归属；素材挂工作区，换业务换工作区，互不污染。
     /** 列当前账户的工作区（含生成统计） */

package/dist/commands/gen.d.ts

@@ -1,4 +1,3 @@
-/** museav gen —— 出图 / 出视频（核心命令） */
 import type { StudioClient } from '../client.js';
 export declare function gen(client: StudioClient, opts: {
     prompt?: string;
@@ -12,6 +11,7 @@ export declare function gen(client: StudioClient, opts: {
     ref?: string[];
     transparent?: boolean;
     project?: string;
+    batch?: string;
     video?: boolean;
     duration?: number;
     image?: string;

package/dist/commands/gen.js

@@ -1,10 +1,73 @@
+/** museav gen —— 出图 / 出视频（核心命令） */
+import { readFileSync } from 'node:fs';
 import { resolveWorkspace } from './projects.js';
 /** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
 const MAX_REFS = 5;
+/** 中台 /api/generate-batch 的单批上限；更大批量 CLI 自动分批 */
+const BATCH_CHUNK = 32;
+/** 读批量文件：每行一条，空行和 # 注释行跳过。'-' 读 stdin。 */
+function readBatchLines(file) {
+    const raw = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8');
+    return raw.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+}
+/**
+ * 批量提交 + 撞频控自动补交：items 与返回的 jobId/错误数组等长（保持顺序）。
+ * 服务端对频控的处理是「后续项 skipped + retry_after_sec」，这里睡够后只把
+ * skipped 的行回池补交——已拿到 jobId 的绝不重发（重发就是重复扣费）。
+ */
+async function submitBatch(client, items, defaults) {
+    const out = items.map(() => ({}));
+    let pending = items.map((_, i) => i);
+    let rounds = 0;
+    while (pending.length && rounds++ < 20) {
+        const retryable = new Set();
+        let cooldown = 0;
+        for (let c = 0; c < pending.length; c += BATCH_CHUNK) {
+            const chunkIdx = pending.slice(c, c + BATCH_CHUNK);
+            const res = await client.generateBatch(chunkIdx.map((i) => items[i]), defaults);
+            chunkIdx.forEach((itemIdx, k) => {
+                const r = res.results[k];
+                if (r?.ok && r.jobId) {
+                    out[itemIdx] = { jobId: r.jobId };
+                    process.stderr.write(`  [${itemIdx + 1}/${items.length}] 已提交 ${r.jobId.slice(0, 8)}\n`);
+                }
+                else if (r?.skipped && res.retry_after_sec) {
+                    retryable.add(itemIdx);
+                }
+                else {
+                    out[itemIdx] = { error: r?.error || r?.reason || `HTTP ${r?.status}` };
+                    process.stderr.write(`  [${itemIdx + 1}/${items.length}] 失败: ${out[itemIdx].error}\n`);
+                }
+            });
+            if (res.retry_after_sec)
+                cooldown = Math.max(cooldown, res.retry_after_sec);
+        }
+        pending = [...retryable];
+        if (pending.length && cooldown) {
+            process.stderr.write(`  频控冷却 ${cooldown}s 后补交剩余 ${pending.length} 项...\n`);
+            await new Promise((resolve) => setTimeout(resolve, cooldown * 1000));
+        }
+    }
+    out.forEach((o) => { if (!o.jobId && !o.error)
+        o.error = '重试次数用尽仍未提交'; });
+    return out;
+}
 export async function gen(client, opts) {
     // prompt / skill / template 三选一。commander 不好表达互斥，在这里校验，报错要说清怎么改
     const picked = [opts.prompt, opts.skill, opts.template].filter(Boolean).length;
-    if (picked === 0) {
+    if (opts.batch) {
+        // 批量有自己的入口语义：每行一条。--skill/--template 时行内容当 input/prompt 用，
+        // 所以 --prompt / --input / --fields 这些「单条内容」参数与它互斥。
+        if (opts.video)
+            throw new Error('--batch 仅图片出图支持（视频走单条 gen --video）');
+        if (opts.prompt)
+            throw new Error('--batch 与 --prompt 互斥：批量时每行就是一条提示词');
+        if (opts.input)
+            throw new Error('--batch 与 --input 互斥：批量时每行就是一条描述');
+        if (opts.fields)
+            throw new Error('--batch 与 --fields 互斥：批量场景模板占位符无法逐行区分');
+    }
+    if (!opts.batch && picked === 0) {
         throw new Error('需要 --prompt "完整提示词" 或 --skill <技能名>（museav skills 查）或 --template <模板id>（museav templates 查）');
     }
     if (picked > 1) {
@@ -62,6 +125,67 @@ export async function gen(client, opts) {
     }
     // 项目归档：--project 解析成 workspace_id（名字/ id 都行），租户身份时中台会忽略
     const workspaceId = opts.project ? (await resolveWorkspace(client, opts.project)).id : undefined;
+    // ── 批量模式：走 /api/generate-batch，中台逐项消化，本端不 pacing ──
+    if (opts.batch) {
+        const lines = readBatchLines(opts.batch);
+        if (!lines.length)
+            throw new Error(`批量文件里没有可用行（每行一条，# 开头的注释和空行会跳过）: ${opts.batch}`);
+        process.stderr.write(`批量出图: ${lines.length} 条${opts.skill ? ` · 技能 ${opts.skill}` : ''}${opts.template ? ` · 模板 ${opts.template}` : ''}\n`);
+        // 每行内容按 skill/template 有无决定语义：有 → 行是 input（业务描述），
+        // 没有 → 行是完整 prompt。其余选项全部作为公共 defaults 下发。
+        const defaults = {};
+        if (opts.skill)
+            defaults.skill_slug = opts.skill;
+        if (opts.template)
+            defaults.template_id = opts.template;
+        if (opts.ratio)
+            defaults.ratio = opts.ratio;
+        if (opts.model)
+            defaults.model = opts.model;
+        if (opts.quality)
+            defaults.quality = opts.quality;
+        if (referenceImage)
+            defaults.reference_image = referenceImage;
+        if (referenceImages)
+            defaults.reference_images = referenceImages;
+        if (opts.transparent)
+            defaults.background = 'transparent';
+        if (workspaceId)
+            defaults.workspace_id = workspaceId;
+        const lineKey = (opts.skill || opts.template) ? 'input' : 'prompt';
+        const submitted = await submitBatch(client, lines.map((line) => ({ [lineKey]: line })), defaults);
+        // 等待全部完成：轮询所有 jobId，按行序输出 URL（stdout 每行一个，方便管道续接）
+        const waiters = submitted.map((s) => s.jobId).filter(Boolean);
+        process.stderr.write(`已提交 ${waiters.length}/${lines.length}，等待生成...\n`);
+        const urls = await Promise.all(submitted.map(async (s) => {
+            if (!s.jobId)
+                return null;
+            for (let i = 0; i < 200; i++) {
+                await new Promise((r) => setTimeout(r, 3000));
+                const job = await client.getJob(s.jobId);
+                if (job.status === 'done')
+                    return job.cdn_url || null;
+                if (job.status === 'failed') {
+                    process.stderr.write(`  ${s.jobId.slice(0, 8)} 失败: ${job.error || '未知原因'}\n`);
+                    return null;
+                }
+            }
+            return null;
+        }));
+        let okCount = 0;
+        for (const [i, url] of urls.entries()) {
+            if (url) {
+                okCount++;
+                console.log(url);
+            }
+            else if (submitted[i].error)
+                process.stderr.write(`第 ${i + 1} 行未提交: ${submitted[i].error}\n`);
+        }
+        process.stderr.write(`✅ 批量完成: ${okCount}/${lines.length} 张\n`);
+        if (okCount === 0)
+            throw new Error('批量出图全部失败');
+        return;
+    }
     // ── 视频模式：走 /api/videos 独立链路 ──
     if (opts.video) {
         if (opts.quality)
@@ -88,6 +212,12 @@ export async function gen(client, opts) {
             throw new Error(`视频生成失败: ${result.error || '未知原因'}`);
         }
         process.stderr.write(`✅ 视频完成\n`);
+        // 模型出的是**无声、无字幕的素材**，不是能直接发的成品。这一行是为了让人在拿到
+        // URL 的那一刻就知道下一步去哪 —— 而不是以为「出完了」，或者反过来以为
+        // museav 该管配音烧字幕（那是 reel-kit 的活，两边边界见 AGENTS.md）。
+        // 只在视频模式提示，且走 stderr 不污染 stdout。
+        process.stderr.write(`   这是无声无字幕的素材。要装配成能发的成品（配文案/配乐/配音）：\n` +
+            `   reel make --assets <图目录> --caps 文案.txt   → github.com/webkubor/reel-kit\n`);
         console.log(result.cdn_url);
         return;
     }

package/dist/index.js

@@ -171,6 +171,7 @@ program
     .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
     .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')
     .option('--project <id|名>', '归档进该工作区（museav projects 查；账户身份才生效）')
+    .option('--batch <file>', '批量出图：文件每行一条（\'#\' 注释与空行跳过，\'-\' 读 stdin），走 /api/generate-batch 中台排队消化；配合 --skill/--template 时每行是业务描述，否则是完整提示词；其余选项作为公共参数')
     .action(withClient((client, opts) => gen(client, opts)));
 program
     .command('compress <file>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "museav-cli",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "MUSE AV 出图中台官方 CLI —— 命令行调中台 API 出图、出视频、读图逆向、图生模板",
   "type": "module",
   "bin": {

package/src/client.ts

@@ -514,6 +514,40 @@ export class StudioClient {
     return r
   }
 
+  /**
+   * 批量提交出图（POST /api/generate-batch）。
+   * items 每项与 generate 的请求体同构；defaults 是公共字段（skill/ratio 等），项内覆盖。
+   * 服务端逐项走与单张同一套流程；撞频控/积分不足时后续项 skipped 并带 retry_after_sec，
+   * 客户端睡够后只补提交 skipped 的部分即可（jobId 已拿到的不要重发）。
+   */
+  async generateBatch(
+    items: Array<Record<string, unknown>>,
+    defaults?: Record<string, unknown>,
+  ): Promise<{
+    ok: boolean
+    accepted: number
+    submitted: number
+    results: Array<{
+      ok: boolean
+      jobId?: string
+      trace_id?: string
+      status?: number
+      error?: string
+      skipped?: boolean
+      reason?: string
+      retry_after_sec?: number
+    }>
+    retry_after_sec?: number
+  }> {
+    const body: Record<string, unknown> = { items }
+    if (defaults) body.defaults = defaults
+    return this.request('generate-batch', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+  }
+
   // ── 工作区（项目）与项目素材库 ──
   // 平台 → 账户 → 工作区三层归属；素材挂工作区，换业务换工作区，互不污染。
 

package/src/commands/gen.ts

@@ -1,10 +1,66 @@
 /** museav gen —— 出图 / 出视频（核心命令） */
+import { readFileSync } from 'node:fs'
 import type { StudioClient } from '../client.js'
 import { resolveWorkspace } from './projects.js'
 
 /** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
 const MAX_REFS = 5
 
+/** 中台 /api/generate-batch 的单批上限；更大批量 CLI 自动分批 */
+const BATCH_CHUNK = 32
+
+/** 读批量文件：每行一条，空行和 # 注释行跳过。'-' 读 stdin。 */
+function readBatchLines(file: string): string[] {
+  const raw = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8')
+  return raw.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
+}
+
+/**
+ * 批量提交 + 撞频控自动补交：items 与返回的 jobId/错误数组等长（保持顺序）。
+ * 服务端对频控的处理是「后续项 skipped + retry_after_sec」，这里睡够后只把
+ * skipped 的行回池补交——已拿到 jobId 的绝不重发（重发就是重复扣费）。
+ */
+async function submitBatch(
+  client: StudioClient,
+  items: Array<Record<string, unknown>>,
+  defaults: Record<string, unknown>,
+): Promise<Array<{ jobId?: string; error?: string }>> {
+  const out: Array<{ jobId?: string; error?: string }> = items.map(() => ({}))
+  let pending = items.map((_, i) => i)
+  let rounds = 0
+  while (pending.length && rounds++ < 20) {
+    const retryable = new Set<number>()
+    let cooldown = 0
+    for (let c = 0; c < pending.length; c += BATCH_CHUNK) {
+      const chunkIdx = pending.slice(c, c + BATCH_CHUNK)
+      const res = await client.generateBatch(
+        chunkIdx.map((i) => items[i]),
+        defaults,
+      )
+      chunkIdx.forEach((itemIdx, k) => {
+        const r = res.results[k]
+        if (r?.ok && r.jobId) {
+          out[itemIdx] = { jobId: r.jobId }
+          process.stderr.write(`  [${itemIdx + 1}/${items.length}] 已提交 ${r.jobId.slice(0, 8)}\n`)
+        } else if (r?.skipped && res.retry_after_sec) {
+          retryable.add(itemIdx)
+        } else {
+          out[itemIdx] = { error: r?.error || r?.reason || `HTTP ${r?.status}` }
+          process.stderr.write(`  [${itemIdx + 1}/${items.length}] 失败: ${out[itemIdx].error}\n`)
+        }
+      })
+      if (res.retry_after_sec) cooldown = Math.max(cooldown, res.retry_after_sec)
+    }
+    pending = [...retryable]
+    if (pending.length && cooldown) {
+      process.stderr.write(`  频控冷却 ${cooldown}s 后补交剩余 ${pending.length} 项...\n`)
+      await new Promise((resolve) => setTimeout(resolve, cooldown * 1000))
+    }
+  }
+  out.forEach((o) => { if (!o.jobId && !o.error) o.error = '重试次数用尽仍未提交' })
+  return out
+}
+
 export async function gen(client: StudioClient, opts: {
   prompt?: string
   skill?: string
@@ -17,6 +73,8 @@ export async function gen(client: StudioClient, opts: {
   ref?: string[]      // 可重复：--ref a.jpg --ref b.jpg，顺序即「图片1、图片2…」
   transparent?: boolean   // 透明背景 PNG；能不能做由中台按上游能力判定，做不了会明确报错
   project?: string    // 工作区 id|名：生成结果归档进该项目（账户身份才生效）
+  // 批量：文件每行一条（'- 读 stdin'），走 /api/generate-batch，只支持图片
+  batch?: string
   // 视频
   video?: boolean
   duration?: number
@@ -24,7 +82,15 @@ export async function gen(client: StudioClient, opts: {
 }): Promise<void> {
   // prompt / skill / template 三选一。commander 不好表达互斥，在这里校验，报错要说清怎么改
   const picked = [opts.prompt, opts.skill, opts.template].filter(Boolean).length
-  if (picked === 0) {
+  if (opts.batch) {
+    // 批量有自己的入口语义：每行一条。--skill/--template 时行内容当 input/prompt 用，
+    // 所以 --prompt / --input / --fields 这些「单条内容」参数与它互斥。
+    if (opts.video) throw new Error('--batch 仅图片出图支持（视频走单条 gen --video）')
+    if (opts.prompt) throw new Error('--batch 与 --prompt 互斥：批量时每行就是一条提示词')
+    if (opts.input) throw new Error('--batch 与 --input 互斥：批量时每行就是一条描述')
+    if (opts.fields) throw new Error('--batch 与 --fields 互斥：批量场景模板占位符无法逐行区分')
+  }
+  if (!opts.batch && picked === 0) {
     throw new Error('需要 --prompt "完整提示词" 或 --skill <技能名>（museav skills 查）或 --template <模板id>（museav templates 查）')
   }
   if (picked > 1) {
@@ -84,6 +150,57 @@ export async function gen(client: StudioClient, opts: {
   // 项目归档：--project 解析成 workspace_id（名字/ id 都行），租户身份时中台会忽略
   const workspaceId = opts.project ? (await resolveWorkspace(client, opts.project)).id : undefined
 
+  // ── 批量模式：走 /api/generate-batch，中台逐项消化，本端不 pacing ──
+  if (opts.batch) {
+    const lines = readBatchLines(opts.batch)
+    if (!lines.length) throw new Error(`批量文件里没有可用行（每行一条，# 开头的注释和空行会跳过）: ${opts.batch}`)
+    process.stderr.write(`批量出图: ${lines.length} 条${opts.skill ? ` · 技能 ${opts.skill}` : ''}${opts.template ? ` · 模板 ${opts.template}` : ''}\n`)
+    // 每行内容按 skill/template 有无决定语义：有 → 行是 input（业务描述），
+    // 没有 → 行是完整 prompt。其余选项全部作为公共 defaults 下发。
+    const defaults: Record<string, unknown> = {}
+    if (opts.skill) defaults.skill_slug = opts.skill
+    if (opts.template) defaults.template_id = opts.template
+    if (opts.ratio) defaults.ratio = opts.ratio
+    if (opts.model) defaults.model = opts.model
+    if (opts.quality) defaults.quality = opts.quality
+    if (referenceImage) defaults.reference_image = referenceImage
+    if (referenceImages) defaults.reference_images = referenceImages
+    if (opts.transparent) defaults.background = 'transparent'
+    if (workspaceId) defaults.workspace_id = workspaceId
+    const lineKey = (opts.skill || opts.template) ? 'input' : 'prompt'
+    const submitted = await submitBatch(
+      client,
+      lines.map((line) => ({ [lineKey]: line })),
+      defaults,
+    )
+    // 等待全部完成：轮询所有 jobId，按行序输出 URL（stdout 每行一个，方便管道续接）
+    const waiters = submitted.map((s) => s.jobId).filter(Boolean) as string[]
+    process.stderr.write(`已提交 ${waiters.length}/${lines.length}，等待生成...\n`)
+    const urls = await Promise.all(
+      submitted.map(async (s) => {
+        if (!s.jobId) return null
+        for (let i = 0; i < 200; i++) {
+          await new Promise((r) => setTimeout(r, 3000))
+          const job = await client.getJob(s.jobId!)
+          if (job.status === 'done') return job.cdn_url || null
+          if (job.status === 'failed') {
+            process.stderr.write(`  ${s.jobId!.slice(0, 8)} 失败: ${job.error || '未知原因'}\n`)
+            return null
+          }
+        }
+        return null
+      }),
+    )
+    let okCount = 0
+    for (const [i, url] of urls.entries()) {
+      if (url) { okCount++; console.log(url) }
+      else if (submitted[i].error) process.stderr.write(`第 ${i + 1} 行未提交: ${submitted[i].error}\n`)
+    }
+    process.stderr.write(`✅ 批量完成: ${okCount}/${lines.length} 张\n`)
+    if (okCount === 0) throw new Error('批量出图全部失败')
+    return
+  }
+
   // ── 视频模式：走 /api/videos 独立链路 ──
   if (opts.video) {
     if (opts.quality) throw new Error('--quality 仅图片出图支持')
@@ -109,6 +226,14 @@ export async function gen(client: StudioClient, opts: {
       throw new Error(`视频生成失败: ${result.error || '未知原因'}`)
     }
     process.stderr.write(`✅ 视频完成\n`)
+    // 模型出的是**无声、无字幕的素材**，不是能直接发的成品。这一行是为了让人在拿到
+    // URL 的那一刻就知道下一步去哪 —— 而不是以为「出完了」，或者反过来以为
+    // museav 该管配音烧字幕（那是 reel-kit 的活，两边边界见 AGENTS.md）。
+    // 只在视频模式提示，且走 stderr 不污染 stdout。
+    process.stderr.write(
+      `   这是无声无字幕的素材。要装配成能发的成品（配文案/配乐/配音）：\n` +
+      `   reel make --assets <图目录> --caps 文案.txt   → github.com/webkubor/reel-kit\n`,
+    )
     console.log(result.cdn_url)
     return
   }

package/src/index.ts

@@ -174,6 +174,7 @@ program
   .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
   .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')
   .option('--project <id|名>', '归档进该工作区（museav projects 查；账户身份才生效）')
+  .option('--batch <file>', '批量出图：文件每行一条（\'#\' 注释与空行跳过，\'-\' 读 stdin），走 /api/generate-batch 中台排队消化；配合 --skill/--template 时每行是业务描述，否则是完整提示词；其余选项作为公共参数')
   .action(withClient((client: StudioClient, opts: any) => gen(client, opts)))
 
 program