museav-cli 3.0.1 → 3.0.2

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)

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.1",
+  "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 仅图片出图支持')

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