museav-cli 2.0.0 → 2.2.0

package/dist/local-vision.js

@@ -0,0 +1,126 @@
+/**
+ * 本地视觉模型（Ollama + qwen3-vl）—— reverse 的主路。
+ * 中台 API 逆向一次要十几秒到几十秒，本地 8b 量化模型在 Apple Silicon 上更快且零成本；
+ * API 降级为回落路（commands/reverse.ts 负责切换与提示）。
+ * 提示词与返回结构从中台 _reverse-core.js / reverse-template.js 移植，保证两条路产出同构。
+ */
+import { readFile } from 'node:fs/promises';
+import { compressForVision } from './compress.js';
+/** 本地读图模型。换档位用 MUSEAV_LOCAL_VLM 环境变量，不用改代码 */
+export const LOCAL_VLM_MODEL = process.env.MUSEAV_LOCAL_VLM || 'qwen3-vl:8b';
+const ALLOWED_RATIOS = ['3:4', '9:16', '1:1', '4:3', '16:9'];
+// OLLAMA_HOST 生态里带不带 scheme、带不带尾斜杠的写法都有
+function ollamaHost() {
+    let host = process.env.OLLAMA_HOST || 'http://localhost:11434';
+    if (!/^https?:\/\//.test(host))
+        host = `http://${host}`;
+    return host.replace(/\/+$/, '');
+}
+/** 探活 + 模型在位检查。3 秒探不通就是没起服务，不等推理超时才发现 */
+export async function checkLocalVlm() {
+    const host = ollamaHost();
+    try {
+        const resp = await fetch(`${host}/api/tags`, { signal: AbortSignal.timeout(3000) });
+        if (!resp.ok) {
+            return { running: false, modelPresent: false, host, reason: `Ollama 探活返回 HTTP ${resp.status}` };
+        }
+        const tags = (await resp.json());
+        const names = (tags.models || []).map((m) => m.name || '');
+        if (!names.includes(LOCAL_VLM_MODEL)) {
+            return { running: true, modelPresent: false, host, reason: `模型未拉取，执行: ollama pull ${LOCAL_VLM_MODEL}` };
+        }
+        return { running: true, modelPresent: true, host };
+    }
+    catch {
+        return { running: false, modelPresent: false, host, reason: `Ollama 未运行（${host}），启动: ollama serve 或 brew services start ollama` };
+    }
+}
+/** SCULPT 系统提示词 —— 从中台 reverse-template.js 移植。本地路只做纯读图，
+ *  中台提示词里的 genre / body_md（给 image-to-template 用的）在 ReverseResult 里
+ *  根本不消费，本地砍掉这两项省几百个输出 token——输出长度直接决定本地推理耗时 */
+function sculptSystemPrompt() {
+    return (`你是一位专业的 AI 图像逆向工程师。请分析这张图片，用 SCULPT 六要素框架逆推生成该图片所需的 prompt。` +
+        `严格输出 JSON，不要输出任何其他文字：\n` +
+        `{\n` +
+        `  "sculpt": {\n` +
+        `    "subject": "主体描述 — 画面中的人物/物体/场景，包括外貌、姿态、服饰",\n` +
+        `    "composition": "构图描述 — 视角、布局、留白、视觉引导线",\n` +
+        `    "universe": "世界观 — 时代背景、艺术风格、整体氛围",\n` +
+        `    "light": "光影描述 — 光源方向、色温、明暗对比、光影效果",\n` +
+        `    "print": "输出特性 — 比例、色调倾向、对比度、饱和度",\n` +
+        `    "texture": "质感描述 — 材质、表面纹理、细节精度"\n` +
+        `  },\n` +
+        `  "prompt": "整合 SCULPT 六要素后的完整英文 prompt（适合 AI 图像生成模型）",\n` +
+        `  "prompt_cn": "对应中文 prompt",\n` +
+        `  "style_tags": ["2-4 个关键风格标签"],\n` +
+        `  "aspect_ratio": "推荐比例，从 3:4|9:16|1:1|4:3|16:9 中按图片比例选一个",\n` +
+        `  "zh_name": "4-8 字风格名（供技能命名）",\n` +
+        `  "description": "一句话描述该风格"` +
+        `\n}\n要求：prompt 必须是英文，详细且精确，覆盖全部六个维度；prompt_cn 为对应中文；只输出 JSON。`);
+}
+/** 本地逆向一张图。任何失败都抛 Error，由调用方决定回落 */
+export async function reverseLocally(filePath) {
+    // 复用上传同款压缩：图小不仅传得快，本地 VLM 推理也快
+    const { buffer, note } = await compressForVision(filePath);
+    if (note)
+        process.stderr.write(`  ${note}\n`);
+    const bytes = buffer ?? (await readFile(filePath));
+    const b64 = Buffer.from(bytes).toString('base64');
+    const payload = {
+        model: LOCAL_VLM_MODEL,
+        messages: [
+            { role: 'system', content: sculptSystemPrompt() },
+            { role: 'user', content: '用 SCULPT 六要素分析这张图，逆推出图 prompt', images: [b64] },
+        ],
+        stream: false,
+    };
+    // 8b 视觉推理单张图几十秒量级，给足余量
+    const resp = await fetch(`${ollamaHost()}/api/chat`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(5 * 60 * 1000),
+    });
+    if (!resp.ok) {
+        throw new Error(`Ollama 返回 HTTP ${resp.status}: ${(await resp.text()).slice(0, 200)}`);
+    }
+    const out = (await resp.json());
+    const content = out.message?.content || '';
+    if (!content.trim())
+        throw new Error('本地模型返回空内容');
+    return normalizeSculpt(parseJsonLoose(content));
+}
+/** 视觉模型「只输出 JSON」的承诺不可信：剥 ```json 围栏、截首尾大括号 */
+function parseJsonLoose(text) {
+    let t = text.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+    const start = t.indexOf('{');
+    const end = t.lastIndexOf('}');
+    if (start >= 0 && end > start)
+        t = t.slice(start, end + 1);
+    return JSON.parse(t);
+}
+/** 与中台 basePayload 同构的归一化：超长截断、非法比例兜底 3:4 */
+function normalizeSculpt(parsed) {
+    const sculptIn = (parsed.sculpt || {});
+    const sculpt = {};
+    for (const key of ['subject', 'composition', 'universe', 'light', 'print', 'texture']) {
+        sculpt[key] = String(sculptIn[key] || '').slice(0, 500);
+    }
+    const ratio = ALLOWED_RATIOS.includes(parsed.aspect_ratio)
+        ? parsed.aspect_ratio
+        : ALLOWED_RATIOS.includes(parsed.ratio)
+            ? parsed.ratio
+            : '3:4';
+    return {
+        ok: true,
+        sculpt,
+        prompt: String(parsed.prompt || '').slice(0, 2000),
+        prompt_cn: String(parsed.prompt_cn || '').slice(0, 2000),
+        style_tags: Array.isArray(parsed.style_tags)
+            ? parsed.style_tags.slice(0, 6).map((t) => String(t).slice(0, 30))
+            : [],
+        aspect_ratio: ratio,
+        zh_name: String(parsed.zh_name || '裂变风格').slice(0, 24),
+        description: String(parsed.description || '').slice(0, 200),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "museav-cli",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "MUSE AV 出图中台官方 CLI —— 命令行调中台 API 出图、出视频、读图逆向、图生模板",
   "type": "module",
   "bin": {
@@ -51,5 +51,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "optionalDependencies": {
+    "sharp": "^0.35.3"
   }
 }

package/src/client.ts

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
+import { compressForVision } from './compress.js'
 
 /**
  * 客户端自报身份 —— 中台靠它把 gen_jobs.channel 记成 'cli'，报错告警也靠它定位调用方。
@@ -67,7 +68,18 @@ export interface GenerateOptions {
   ratio?: string
   model?: string
   reference_image?: string
+  /** 多张参考图，顺序即提示词里的「图片1、图片2…」；中台按序喂给模型 */
+  reference_images?: string[]
   quality?: 'low' | 'medium' | 'high'
+  /**
+   * 出图背景。transparent = 抠掉背景出带 alpha 通道的 PNG；opaque = 明确要不透明背景；
+   * 不传 = 沿用上游默认（白底）。
+   *
+   * 跟上游 gpt-image 的参数同名同值，中台不做翻译。两个约束由中台强制、CLI 不重复实现：
+   *   · 透明背景强制 PNG 输出（JPEG/有损 WebP 没有 alpha 通道）
+   *   · 只派给声明了该能力的上游；一家都没有时返回 400 说明原因，**不会静默出白底图**
+   */
+  background?: 'transparent' | 'opaque'
 }
 
 /** 图片/文字模板清单项（GET /api/templates，template_type=image|article） */
@@ -89,7 +101,12 @@ export interface TemplateOption {
     model: string
     prompt_template: string
     ref_slots?: string[]
+    /** 表单字段声明——现行契约放 config 顶层（服务端 validateConfig 读这里） */
+    fields?: Array<{ key: string; label: string }>
+    /** 旧存法：fields 曾在 params_json 里，老模板还这么存，读时两种都要兜 */
     params_json?: { fields?: Array<{ key: string; label: string; placeholder?: string }> }
+    duration?: number
+    aspect_ratio?: string
     is_default?: boolean
   }>
 }
@@ -120,6 +137,8 @@ export interface CreateTemplateInput {
  *  ratio/duration/model 放在 generation_configs 每项里。 */
 export interface CreateVideoTemplateInput {
   zh_name: string
+  /** 对外调用标识，视频模板硬必填（服务端 validateCore required=['zh_name','slug']），全局唯一 */
+  slug: string
   category?: string
   description?: string
   sample_video_url?: string | null
@@ -389,7 +408,10 @@ export class StudioClient {
     if (opts.ratio) body.ratio = opts.ratio
     if (opts.model) body.model = opts.model
     if (opts.reference_image) body.reference_image = opts.reference_image
+    // 单双字段一起发：中台优先取复数、为空才回落单数，两个都带着更稳
+    if (opts.reference_images?.length) body.reference_images = opts.reference_images
     if (opts.quality) body.quality = opts.quality
+    if (opts.background) body.background = opts.background
     const r = await this.request('generate', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -500,7 +522,7 @@ export class StudioClient {
    */
   async reverse(input: { file?: string; imageUrl?: string }): Promise<ReverseResult> {
     if (input.file) {
-      return this.request('reverse', { method: 'POST', body: fileForm(input.file) })
+      return this.request('reverse', { method: 'POST', body: await fileForm(input.file) })
     }
     return this.request('reverse', {
       method: 'POST',
@@ -516,8 +538,12 @@ export class StudioClient {
    * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
    * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
    */
+  /**
+   * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
+   * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
+   */
   async uploadRef(filePath: string): Promise<{ url: string; media_type?: string; mime?: string }> {
-    const r = await this.request('upload-ref', { method: 'POST', body: fileForm(filePath) })
+    const r = await this.request('upload-ref', { method: 'POST', body: await fileForm(filePath) })
     return { url: r.url, media_type: r.media_type, mime: r.mime }
   }
 
@@ -536,7 +562,7 @@ export class StudioClient {
     if (file) {
       // multipart 分支：中台 formOptions() 对这几个键做 JSON.parse（variables 还支持逗号分隔），
       // 所以对象/数组要自己序列化成字符串，不能直接塞进 FormData。
-      const fd = fileForm(file)
+      const fd = await fileForm(file)
       if (variables?.length) fd.append('variables', JSON.stringify(variables))
       if (variableLabels) fd.append('variable_labels', JSON.stringify(variableLabels))
       if (createTemplate) fd.append('create_template', 'true')
@@ -621,9 +647,18 @@ function sleep(ms: number): Promise<void> {
  * 带上原文件名：中台判类型靠字节魔数不靠这个，但文件名会进日志/对象存储的排查线索，
  * 匿名的 "blob" 出问题时谁也认不出是哪张图。故意不设 MIME——声明的 MIME 中台本来就不信。
  */
-function fileForm(filePath: string): FormData {
+/**
+ * 所有 multipart 上传的唯一入口，内置参考图压缩（见 compress.ts）。
+ * 压缩放这里而不是各调用点：uploadRef / reverse / image-to-template 都走它，
+ * 加在调用点就会漏——2026-08-16 就漏过 image-to-template，4.1MB 原图直传把任务拖挂了。
+ */
+async function fileForm(filePath: string): Promise<FormData> {
+  const { buffer, filename, note } = await compressForVision(filePath)
+  if (note) process.stderr.write(`  ${note}\n`)
   const fd = new FormData()
-  fd.append('file', new Blob([readFileSync(filePath)]), basename(filePath))
+  // Buffer → Uint8Array：Blob 的类型签名不收 Buffer（它可能背靠 SharedArrayBuffer）
+  const blob = buffer ? new Blob([new Uint8Array(buffer)]) : new Blob([new Uint8Array(readFileSync(filePath))])
+  fd.append('file', blob, buffer ? filename : basename(filePath))
   return fd
 }
 

package/src/commands/gen.ts

@@ -1,6 +1,9 @@
 /** museav gen —— 出图 / 出视频（核心命令） */
 import type { StudioClient } from '../client.js'
 
+/** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
+const MAX_REFS = 5
+
 export async function gen(client: StudioClient, opts: {
   prompt?: string
   skill?: string
@@ -10,7 +13,8 @@ export async function gen(client: StudioClient, opts: {
   ratio?: string
   model?: string
   quality?: string
-  ref?: string
+  ref?: string[]      // 可重复：--ref a.jpg --ref b.jpg，顺序即「图片1、图片2…」
+  transparent?: boolean   // 透明背景 PNG；能不能做由中台按上游能力判定，做不了会明确报错
   // 视频
   video?: boolean
   duration?: number
@@ -33,6 +37,10 @@ export async function gen(client: StudioClient, opts: {
   if (opts.video && opts.skill) {
     throw new Error('--video 暂不支持配合 --skill（视频模板走 --template 或直接 --prompt）')
   }
+  // 视频没有 alpha 通道这回事（mp4 不带透明），本地就拦掉，别让用户等一趟往返才知道
+  if (opts.video && opts.transparent) {
+    throw new Error('--transparent 仅图片出图支持：视频输出是 mp4，没有 alpha 通道')
+  }
   let templateFields: Record<string, string> | undefined
   if (opts.fields) {
     try {
@@ -42,14 +50,26 @@ export async function gen(client: StudioClient, opts: {
     }
   }
 
-  // 可选：先上传垫图（图片出图 --ref / 视频图生视频 --image 都走这里）
+  // 可选：先上传垫图（图片出图 --ref 可给多张 / 视频图生视频 --image 单张）
+  //
+  // 顺序有语义：中台把数组按序喂给模型，提示词里写「参考图片1的排版、用图片2当背景」
+  // 时，图片N 对应的就是这里的第 N 个 --ref。所以上传要顺序执行、不能并发抢跑。
   let referenceImage: string | undefined
-  const refPath = opts.ref || opts.image
-  if (refPath) {
-    process.stderr.write(`上传垫图 ${refPath} ...\n`)
-    const up = await client.uploadRef(refPath)
-    referenceImage = up.url
-    process.stderr.write(`垫图就绪: ${referenceImage}\n`)
+  let referenceImages: string[] | undefined
+  const refPaths = [...(opts.ref || []), ...(opts.image ? [opts.image] : [])]
+  if (refPaths.length > MAX_REFS) {
+    throw new Error(`参考图最多 ${MAX_REFS} 张，收到 ${refPaths.length} 张`)
+  }
+  if (refPaths.length) {
+    const urls: string[] = []
+    for (const [i, refPath] of refPaths.entries()) {
+      process.stderr.write(`上传垫图 [图片${i + 1}] ${refPath} ...\n`)
+      const up = await client.uploadRef(refPath)
+      urls.push(up.url)
+      process.stderr.write(`  图片${i + 1} 就绪: ${up.url}\n`)
+    }
+    referenceImage = urls[0]                       // 兼容：中台单数字段仍收
+    referenceImages = urls.length > 1 ? urls : undefined
   }
 
   // ── 视频模式：走 /api/videos 独立链路 ──
@@ -99,6 +119,10 @@ export async function gen(client: StudioClient, opts: {
       model: opts.model,
       quality: opts.quality as 'low' | 'medium' | 'high' | undefined,
       reference_image: referenceImage,
+      reference_images: referenceImages,
+      // 开关 → 枚举：CLI 这层用布尔开关最顺手，中台契约是 background: transparent|opaque
+      // （跟上游 gpt-image 的参数同名同值）。不传就不发，行为跟以前完全一样。
+      background: opts.transparent ? 'transparent' : undefined,
     },
     (status) => {
       if (status === 'processing') process.stderr.write('生成中...\r')

package/src/commands/reverse.ts

@@ -1,11 +1,43 @@
-/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt） */
-import type { StudioClient } from '../client.js'
+/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt）。
+ *  主路是本地 Ollama（qwen3-vl），快、零成本、无需登录；中台 API 是回落路，走回落时会明确提示较慢。
+ *  client 懒构造（getClient）：本地路成功就完全不碰中台凭证。
+ *  本地系统的 AI 能力统一收口在这个 CLI，reverse 是第一个本地化的能力。 */
+import type { StudioClient, ReverseResult } from '../client.js'
+import { checkLocalVlm, reverseLocally, LOCAL_VLM_MODEL } from '../local-vision.js'
 
-export async function reverse(client: StudioClient, input: string): Promise<void> {
-  // 输入是文件路径还是 URL
+export async function reverse(
+  getClient: () => StudioClient,
+  input: string,
+  opts: { api?: boolean } = {},
+): Promise<void> {
   const isUrl = /^https?:\/\//.test(input)
+
+  if (!opts.api && !isUrl) {
+    const status = await checkLocalVlm()
+    if (status.running && status.modelPresent) {
+      try {
+        const start = Date.now()
+        const result = await reverseLocally(input)
+        process.stderr.write(`✓ 本地 Ollama（${LOCAL_VLM_MODEL}）用时 ${((Date.now() - start) / 1000).toFixed(1)}s\n`)
+        renderReverse(result)
+        return
+      } catch (e) {
+        process.stderr.write(`⚠ 本地读图失败（${e instanceof Error ? e.message : e}），回落中台 API —— 速度较慢，请耐心等待\n`)
+      }
+    } else {
+      process.stderr.write(`⚠ 本地读图不可用（${status.reason}），回落中台 API —— 速度较慢，请耐心等待\n`)
+    }
+  } else if (!opts.api && isUrl) {
+    process.stderr.write(`ℹ URL 输入走中台 API（本地路只收文件路径）\n`)
+  }
+
+  const client = getClient()
   const result = await client.reverse(isUrl ? { imageUrl: input } : { file: input })
+  renderReverse(result)
+}
 
+/** 两条路产出同构，渲染只写一份 */
+function renderReverse(result: ReverseResult): void {
   process.stderr.write(`✅ 逆向完成\n\n`)
   process.stderr.write(`风格: ${result.zh_name || '-'}  比例: ${result.aspect_ratio}\n`)
   process.stderr.write(`标签: ${result.style_tags.join(', ')}\n\n`)

package/src/commands/templates.ts

@@ -19,7 +19,8 @@ export async function templates(client: StudioClient, opts: { category?: string;
   process.stderr.write(`可用模板（${list.length} 个）:\n`)
   for (const t of list) {
     const cfg = t.generation_configs?.find((c) => c.is_default) || t.generation_configs?.[0]
-    const fields = cfg?.params_json?.fields || []
+    // fields 新契约在 config 顶层（CLI 自己 create 就写顶层），老数据在 params_json 里——两种都兜
+    const fields = cfg?.fields || cfg?.params_json?.fields || []
     const fieldHint = fields.length ? `字段:${fields.map((f) => f.key).join(',')}` : ''
     process.stderr.write(
       `  ${t.id.padEnd(38)} ${(t.zh_name || '').padEnd(16)} ${(t.category || '').padEnd(10)} ${(t.ratio || '').padEnd(6)} ${typeTag(t).padEnd(8)} ${fieldHint.padEnd(20)} ${tag(t)}\n`,

package/src/commands/video-templates.ts

@@ -19,8 +19,9 @@ export async function videoTemplates(client: StudioClient, opts: { category?: st
     const cfg = t.generation_configs?.find((c) => c.is_default) || t.generation_configs?.[0]
     const modelHint = cfg?.model ? `模型:${cfg.model}` : ''
     const ratioHint = t.ratio || ''
-    const fieldCount = cfg?.params_json?.fields?.length || 0
-    const fieldHint = fieldCount ? `字段:${cfg!.params_json!.fields!.map((f) => f.key).join(',')}` : ''
+    // fields 新契约在 config 顶层，老数据在 params_json 里——两种都兜，否则自己建的模板自己列不出来
+    const fields = cfg?.fields || cfg?.params_json?.fields || []
+    const fieldHint = fields.length ? `字段:${fields.map((f) => f.key).join(',')}` : ''
     const sampleHint = t.sample_video_url ? '有参考视频' : ''
     process.stderr.write(
       `  ${t.id.padEnd(38)} ${(t.zh_name || '').padEnd(20)} ${(t.category || '').padEnd(10)} ${ratioHint.padEnd(6)} ${modelHint.padEnd(30)} ${fieldHint.padEnd(24)} ${sampleHint.padEnd(10)} ${tag(t)}\n`,
@@ -36,6 +37,8 @@ export async function videoTemplates(client: StudioClient, opts: { category?: st
 
 interface CreateVideoTemplateOpts {
   name: string
+  /** 对外调用标识，全局唯一。不给就自动生成一个（vt- 前缀） */
+  slug?: string
   prompt: string
   category?: string
   description?: string
@@ -53,25 +56,32 @@ export async function createVideoTemplate(client: StudioClient, opts: CreateVide
   if (!opts.name?.trim()) throw new Error('--name 必填')
   if (!opts.prompt?.trim()) throw new Error('--prompt 必填，占位符用 {key} 形式，如 "{product} 在 {scene} 中展示"')
 
+  // slug 是视频模板的硬必填（服务端 required=['zh_name','slug']），漏了必 400。
+  // 中文名大多是中文没法直接转 slug，不给 --slug 就生成一个 vt- 短标识，撞了让服务端报出来再换。
+  const slug = (opts.slug || `vt-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 5)}`).trim()
+  if (!/^[\w-]+$/.test(slug)) throw new Error('--slug 只能包含字母、数字、下划线和连字符')
+
   // 占位符必须声明 fields（中台 validateConfig 硬校验：prompt 里有 {key} 但没 fields 会被拒）
   const keys = Array.from(new Set(Array.from(opts.prompt.matchAll(/\{(\w+)\}/g), (m) => m[1])))
   const fields = keys.map((key) => ({ key, label: key }))
 
   const cfg: Record<string, unknown> = {
-    model: opts.model || 'seedance-2',
+    // 默认 auto：交给中台路由按 ratio/duration 挑档次。锁死具体模型得自己保证参数配得上它
+    model: opts.model || 'auto',
     prompt_template: opts.prompt,
     is_default: true,
   }
   if (fields.length) cfg.fields = fields
   if (opts.duration) {
     const d = Number(opts.duration)
-    if (!Number.isFinite(d) || d < 4 || d > 15) throw new Error('--duration 必须是 4-15 之间的数字（秒）')
+    if (!Number.isFinite(d) || d < 4 || d > 30) throw new Error('--duration 必须是 4-30 之间的数字（秒；Seedance 2.0 系上限 15，2.5 到 30，具体由中台按模型校验）')
     cfg.duration = d
   }
   if (opts.ratio) cfg.aspect_ratio = opts.ratio
 
   const row = await client.createVideoTemplate({
     zh_name: opts.name,
+    slug,
     category: opts.category,
     description: opts.description,
     sample_video_url: opts.sampleVideo || null,
@@ -80,6 +90,7 @@ export async function createVideoTemplate(client: StudioClient, opts: CreateVide
   })
 
   process.stderr.write(`✅ 视频模板已建：${row.id}\n`)
+  process.stderr.write(`slug: ${slug}\n`)
   process.stderr.write(`归属：${row.tenant_id ? '当前租户（其他租户看不到）' : '平台共享（所有租户可见）'}\n`)
   process.stderr.write(`模型: ${cfg.model} 时长: ${cfg.duration || '模板默认'} 比例: ${cfg.aspect_ratio || '模板默认'}\n`)
   if (fields.length) process.stderr.write(`占位符字段: ${fields.map((f) => f.key).join(', ')}\n`)

package/src/compress.ts

@@ -0,0 +1,110 @@
+/**
+ * 参考图压缩 —— 上传前把图缩到视觉模型够用的尺寸。
+ *
+ * 参考图的用途是「让模型看懂画面」，不是留档，不需要原始分辨率。实测 4.1MB 的海报
+ * 直接传上去，中台那次图生模板任务卡在「解析图片」再没回来（后台任务被 Cloudflare
+ * 掐掉，任务永远 pending）。50MB 的图更不用说。
+ *
+ * sharp 是 optionalDependency：原生模块在个别平台会装不上，装不上也不能让整个 CLI
+ * 用不了。取不到就原样上传并提示——压缩是优化，不是前置条件。
+ */
+import { stat } from 'node:fs/promises'
+import { basename } from 'node:path'
+
+/** 长边上限：主流视觉模型的有效输入分辨率都在 1.5k 上下，再大只是浪费带宽和解析时间 */
+const MAX_EDGE = 1568
+/** 小于这个体积且尺寸不超标就原样传，不折腾 */
+const SKIP_BELOW_BYTES = 900 * 1024
+/** 压完仍超过它就再降一档质量 */
+const TARGET_BYTES = 1.5 * 1024 * 1024
+
+export interface CompressResult {
+  /** 要上传的数据；未压缩时为 null，表示用原文件 */
+  buffer: Buffer | null
+  /** 上传时用的文件名（转了格式要换扩展名） */
+  filename: string
+  /** 给人看的一行说明，未压缩时为空 */
+  note: string
+}
+
+async function loadSharp(): Promise<any | null> {
+  try {
+    const m = await import('sharp')
+    return (m as any).default ?? m
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param filePath 本地图片路径
+ * @returns 压缩结果；非图片、体积已达标、或 sharp 不可用时 buffer 为 null
+ */
+export async function compressForVision(filePath: string): Promise<CompressResult> {
+  const name = basename(filePath)
+  const orig = (await stat(filePath)).size
+
+  const sharp = await loadSharp()
+  if (!sharp) {
+    return {
+      buffer: null,
+      filename: name,
+      note: orig > SKIP_BELOW_BYTES
+        ? `未安装 sharp，${(orig / 1024 / 1024).toFixed(1)}MB 原图直传（大图可能导致解析超时）`
+        : '',
+    }
+  }
+
+  let meta
+  try {
+    meta = await sharp(filePath).metadata()
+  } catch {
+    return { buffer: null, filename: name, note: '' }   // 不是 sharp 认识的图（视频/音频）→ 原样传
+  }
+
+  const longEdge = Math.max(meta.width || 0, meta.height || 0)
+  if (orig <= SKIP_BELOW_BYTES && longEdge <= MAX_EDGE) {
+    return { buffer: null, filename: name, note: '' }
+  }
+
+  // 有 alpha 的保持 PNG（贴图类素材的透明通道不能丢），其余一律转 JPEG——
+  // 同样画质下 JPEG 比 PNG 小一个数量级，而参考图不需要无损。
+  //
+  // 只看 meta.hasAlpha 不够：截图工具产出的 PNG 普遍带一条**全不透明**的 alpha 通道，
+  // 照着它走 PNG 分支等于白白多存几倍体积（实测 4.1MB 海报按 PNG 只压到 1.16MB，
+  // 按 JPEG 是 0.2MB）。用 stats().isOpaque 判断透明通道有没有被真正用到。
+  let hasAlpha = !!meta.hasAlpha
+  if (hasAlpha) {
+    try {
+      const st = await sharp(filePath).stats()
+      if (st.isOpaque) hasAlpha = false
+    } catch { /* 统计失败就按有 alpha 保守处理 */ }
+  }
+  const pipeline = sharp(filePath).rotate()   // rotate() 不带参数=按 EXIF 摆正，否则手机竖拍图会躺着
+    .resize({ width: MAX_EDGE, height: MAX_EDGE, fit: 'inside', withoutEnlargement: true })
+
+  let out: Buffer
+  let ext: string
+  if (hasAlpha) {
+    out = await pipeline.png({ compressionLevel: 9, palette: true }).toBuffer()
+    ext = 'png'
+  } else {
+    out = await pipeline.jpeg({ quality: 82, mozjpeg: true }).toBuffer()
+    ext = 'jpg'
+    if (out.byteLength > TARGET_BYTES) {
+      out = await sharp(filePath).rotate()
+        .resize({ width: MAX_EDGE, height: MAX_EDGE, fit: 'inside', withoutEnlargement: true })
+        .jpeg({ quality: 68, mozjpeg: true }).toBuffer()
+    }
+  }
+
+  // 压完反而更大（本来就是小图/高压缩率的 WebP 之类）就别换了
+  if (out.byteLength >= orig) return { buffer: null, filename: name, note: '' }
+
+  const pct = Math.round((1 - out.byteLength / orig) * 100)
+  return {
+    buffer: out,
+    filename: name.replace(/\.[^.]+$/, '') + '.' + ext,
+    note: `已压缩 ${(orig / 1024 / 1024).toFixed(1)}MB → ${(out.byteLength / 1024 / 1024).toFixed(2)}MB（-${pct}%，长边 ≤ ${MAX_EDGE}px）`,
+  }
+}

package/src/index.ts

@@ -93,6 +93,22 @@ function withClient<T extends (...args: any[]) => Promise<any>>(fn: T) {
   }
 }
 
+// reverse 的本地路（Ollama）不需要中台凭证，client 懒构造：只有真回落 API 才建，
+// 未登录的报错也只在那时候出现
+function withLazyClient(fn: (getClient: () => StudioClient, ...args: any[]) => Promise<any>) {
+  return async (...args: any[]) => {
+    try {
+      const opts = args[args.length - 2]
+      const positional = args.slice(0, -2)
+      const getClient = () => new StudioClient(loadConfig())
+      await fn(getClient, ...positional, opts)
+    } catch (e) {
+      process.stderr.write(`❌ ${(e as Error).message}\n`)
+      process.exit(1)
+    }
+  }
+}
+
 // products / assets 查的是租户自己后台的数据，不是 Studio 中台的，走独立的 TenantClient
 // （见 tenant-client.ts 顶部注释），只支持租户 apiKey 身份，不支持个人 login token。
 function withTenantClient<T extends (...args: any[]) => Promise<any>>(fn: T) {
@@ -127,18 +143,25 @@ program
   // 不设默认值：--skill / --template 场景下要让技能/模板自己的比例生效，
   // CLI 强填默认值会把它们覆盖掉（服务端在纯 --prompt 场景已有 3:4 兜底，这里不用重复兜底）
   .option('-r, --ratio <ratio>', '宽高比: 3:4 / 9:16 / 1:1 / 4:3 / 16:9（不指定则用技能/模板自己的比例，纯 prompt 模式兜底 3:4）')
-  .option('-m, --model <name>', '指定模型，如 gpt-image-2 / seedance-2-fast / artsdance-2-0-pro-260801')
+  .option('-m, --model <name>', '指定模型，如 gpt-image-2 / artsdance-2-0-pro-260801（视频不传则走 auto 路由）')
   .option('-q, --quality <level>', '质量: low / medium / high（仅 gpt-image）')
-  .option('--ref <file>', '垫图文件路径（图片图生图，自动上传）')
-  .option('--video', '生成视频（走 /api/videos 链路，模型如 seedance-2-fast / artsdance-2-0-pro）')
+  // 可重复：--ref 正面.jpg --ref 背景.jpg。顺序即语义——提示词里写「参考图片1的排版、
+  // 用图片2作为背景」时，图片N 对应第 N 个 --ref。commander 的 collect 保证顺序。
+  .option('--ref <file>', '垫图文件路径，可重复传多张（最多 5 张，顺序对应提示词里的「图片1、图片2…」）',
+    (v: string, acc: string[]) => [...acc, v], [] as string[])
+  // 透明背景是上游的 background 参数，不是提示词能表达的东西——提示词里写
+  // "transparent background" 只是在描述构图，模型照样铺一层白底。这个开关才是抠图开关。
+  .option('--transparent', '透明背景 PNG（抠掉背景，带 alpha 通道）。仅部分上游支持，不支持时中台明确报错、不会悄悄给白底图；服务端自动强制 PNG 输出（JPEG 没有 alpha 通道）')
+  .option('--video', '生成视频（走 /api/videos 链路；模型档次如 artsdance-2-0-pro-260801，不传 --model 走 auto 路由）')
   .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
   .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')
   .action(withClient((client: StudioClient, opts: any) => gen(client, opts)))
 
 program
   .command('reverse <input>')
-  .description('读图：上传图或图片 URL，反推 SCULPT prompt，stdout 输出英文 prompt（只读图；要做成模板用 image-to-template）')
-  .action(withClient((client: StudioClient, input: string) => reverse(client, input)))
+  .description('读图：反推 SCULPT prompt，stdout 输出英文 prompt。主路本地 Ollama（qwen3-vl，快，无需登录）；本地不可用回落中台 API（会提示较慢）。只读图；要做成模板用 image-to-template')
+  .option('--api', '跳过本地 Ollama，强制走中台 API（慢，需登录）')
+  .action(withLazyClient((getClient: () => StudioClient, input: string, opts: any) => reverse(getClient, input, opts)))
 
 program
   .command('image-to-template <input>')
@@ -188,10 +211,11 @@ videoTemplatesCmd
   )
   .requiredOption('--name <zh_name>', '模板中文名')
   .requiredOption('--prompt <template>', '提示词模板，占位符用 {key} 形式，如 "{product} 在 {scene} 中展示"')
+  .option('--slug <slug>', '对外调用标识（全局唯一，视频模板硬必填）；不传自动生成 vt- 前缀短标识')
   .option('--category <name>', '分类，默认「其他」')
   .option('--description <text>', '模板说明')
-  .option('--model <name>', '视频模型，默认 seedance-2（可选 seedance-2-fast / seedance-2-mini / artsdance-2-0-pro-260801）')
-  .option('--duration <sec>', '视频时长（秒，4-15，可选）')
+  .option('--model <name>', '视频模型档次，默认 auto（交给中台路由）；锁死可选 artsdance-2-0-pro-260801（Seedance 2.0）/ artsdance-2-0-fast-260801 / artsdance-2-0-mini-260801 / artsdance-2-5-pro-260801（Seedance 2.5）')
+  .option('--duration <sec>', '视频时长（秒，4-30：Seedance 2.0 系上限 15、2.5 到 30，可选）')
   .option('--ratio <ratio>', '画面比例: 9:16 / 16:9 / 1:1 / 3:4（可选）')
   .option('--sample-video <url>', '参考视频 URL（可选，展示给用户的示例片）')
   .option('--sample-cover <url>', '封面图 URL（可选）')