museav-cli 2.0.0 → 2.2.0

package/AGENTS.md

@@ -19,8 +19,10 @@ Don't try both — whichever credential is present is what gets used (env var `S
 # Generate an image, wait for it, get the URL on stdout
 museav gen --prompt 'a poster, neon lights, cyberpunk' --ratio 9:16
 
-# Generate a video (文生视频/图生视频), wait, get the mp4 URL on stdout
-museav gen --video --prompt 'a cat stretching on a windowsill, cinematic' --model seedance-2-fast --ratio 9:16
+# Generate a video (文生视频/图生视频), wait, get the mp4 URL on stdout.
+# Omit --model to let the platform route automatically (auto); pinning a tier uses
+# artsdance-* ids like artsdance-2-0-pro-260801 (Seedance 2.0).
+museav gen --video --prompt 'a cat stretching on a windowsill, cinematic' --ratio 9:16
 museav gen --video --image logo.png --prompt 'logo glows slowly, background fades' --ratio 1:1
 
 # Generate from a pre-configured image template instead of a raw prompt (deterministic
@@ -37,6 +39,10 @@ museav gen --template <id> --fields '{"artist":"name","city":"place"}'
 museav templates create --name '演唱会海报' --prompt '{artist} 在 {city} 的演唱会海报' --ratio 9:16
 
 # Reverse-engineer a prompt from an existing image (stdout: English prompt only).
+# PRIMARY path is LOCAL: Ollama qwen3-vl — fast, free, NO login needed. Falls back to
+# the platform API (with a slowness warning) only if Ollama isn't running or the model
+# is missing. Image URLs always go to the API (local path takes file paths only);
+# --api forces the API path.
 # This READS the image and nothing else — it will NOT build a template. Passing any
 # template-ish flag to the underlying API is a hard 400 since 2026-08-16.
 museav reverse ./photo.png

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2.2.0 · 2026-08-17
+
+**`reverse` 主路改本地：Ollama + qwen3-vl。** 中台 API 读图要上传、排队、等云端推理；本地 8b 量化模型在自己机器上跑，免登录、零成本、离线可用。本地不可用（服务没起 / 模型没拉 / 推理出错）自动回落中台 API，回落时明确提示较慢，缺什么会告诉你补什么命令。
+
+- 一次性配置：`brew install ollama && brew services start ollama && ollama pull qwen3-vl:8b`（Intel Mac / Linux 用官方安装脚本同理）。换模型档位设 `MUSEAV_LOCAL_VLM`（如 `qwen3-vl:4b`，更快、识图质量略降），自定服务地址走标准 `OLLAMA_HOST`。
+- SCULPT 提示词从中台移植，砍掉本地不消费的 genre / body_md；返回归一化后与 API 路完全同构，`$(museav reverse x.png)` 管线用法不变，stdout 仍只出英文 prompt。
+- 读图前复用上传同款压缩（压到视觉模型够用的尺寸），本地推理也跟着快。
+- URL 输入固定走中台 API（本地路只收文件路径）；`--api` 强制走中台。
+- 本地路完全不需要中台凭证——未登录也能用，只有真回落 API 时才提示登录。
+
+**修复 `video-templates create` 必被 400 拒**：中台视频模板契约硬性要求 `slug`（required=['zh_name','slug']），且 toapis 2026-08-14 下线后 CLI 默认的 `seedance-2` 成了悬空引用——不带参数建视频模板必挂。现在 `--slug` 缺省自动生成 `vt-` 短标识并在 stderr 回显，默认模型改 `auto`（交给中台路由），`--duration` 放宽到 4-30（Seedance 2.5 支持到 30 秒）。
+
+- `templates` / `video-templates` 列表兼容读 config 顶层的 `fields`（现行契约存法——CLI 自己 create 写的就是顶层，之前自己建的模板自己都列不出字段）。
+- `gen` / `video-templates` 帮助文案与 README / AGENTS.md 示例里已下线的 `seedance-2-*` 代号全部清掉，照旧文案传参会 400。
+
 ## 2.0.0 · 2026-08-16
 
 **改名：npm 包 `museav-cli`，命令 `museav`。** 产品叫 MUSE AV，命令却叫另一个名字，同一个东西两个叫法——这次统一到产品名。

package/README.md

@@ -162,8 +162,18 @@ museav gen --prompt '...' --quality high
 # 图生图（自动上传垫图，保持人物面容）
 museav gen --prompt '保持面容，换成西装' --ref face.png
 
-# 文生视频（模型如 seedance-2-fast / artsdance-2-0-pro-260801，自动轮询直到完成）
-museav gen --video --prompt '一只橘猫在窗台上伸懒腰，阳光洒进来，电影感' --model seedance-2-fast --ratio 9:16
+# 透明背景 PNG（抠掉背景，出带 alpha 通道的图；可与 --ref 叠加）
+museav gen --prompt '一只橘猫，产品级抠图' --transparent
+museav gen --prompt '把这只鞋抠成透明底' --ref shoe.jpg --transparent
+# 注意三件事：
+#   · 只在提示词里写 "transparent background" 没用——那是构图描述，不是抠图开关，
+#     真正生效的是 --transparent（它对应上游的 background 参数）
+#   · 仅部分上游支持。没有可用上游时中台直接报错，不会悄悄给你一张白底图
+#     （白底图看起来完全正常，静默降级只会让你以为提示词没写对，反复重试）
+#   · 会强制 PNG 输出：JPEG / 有损 WebP 没有 alpha 通道，装不下透明
+
+# 文生视频（不传 --model 走 auto 路由；锁死档次用 artsdance-2-0-pro-260801 这类代号，自动轮询直到完成）
+museav gen --video --prompt '一只橘猫在窗台上伸懒腰，阳光洒进来，电影感' --ratio 9:16
 
 # 图生视频（--image 传首帧图，自动上传）
 museav gen --video --image logo.png --prompt 'logo 缓缓发光，背景渐暗' --ratio 1:1
@@ -227,17 +237,24 @@ museav gen --template "$ID" --fields '{"artist":"..."}'
 
 ### 图片逆向 `reverse`
 
-上传一张图，中台用 **SCULPT 六要素**（主体/构图/世界观/光影/输出/质感）逆推出图 prompt，可以直接拿去再出一张同风格的：
+逆推出图 prompt，可以直接拿去再出一张同风格的。**主路是本地 Ollama（qwen3-vl）**：快、零成本、无需登录；本地不可用时自动回落中台 API（SCULPT 六要素：主体/构图/世界观/光影/输出/质感），回落时会明确提示较慢：
 
 ```bash
-# 本地文件或图片 URL 都行
+# 本地文件走本地模型（推荐，无需登录）
 museav reverse photo.png
+
+# 图片 URL 没法喂本地模型，走中台 API（需登录）
 museav reverse https://example.com/photo.png
 
+# 强制走中台 API（跳过本地，慢，需登录）
+museav reverse photo.png --api
+
 # 逆向 + 出图，一条龙
 museav gen --prompt "$(museav reverse photo.png)"
 ```
 
+本地路依赖：Ollama 运行中（`brew services start ollama`）+ 模型在位（`ollama pull qwen3-vl:8b`，换档位设 `MUSEAV_LOCAL_VLM`，自定地址设 `OLLAMA_HOST`）。缺哪个都会提示对应命令并回落 API。
+
 分析详情打到 stderr（人看），**stdout 只输出英文 prompt**（机器用，方便管道）。
 
 `reverse` **只读图**，不会顺手帮你建模板。要把图做成模板看下一节——中台 2026-08-16 把这两件事

package/dist/client.d.ts

@@ -19,7 +19,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） */
 export interface TemplateOption {
@@ -40,6 +51,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;
@@ -47,6 +64,8 @@ export interface TemplateOption {
                 placeholder?: string;
             }>;
         };
+        duration?: number;
+        aspect_ratio?: string;
         is_default?: boolean;
     }>;
 }
@@ -78,6 +97,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;
@@ -347,6 +368,10 @@ export declare class StudioClient {
      * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
      * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
      */
+    /**
+     * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
+     * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
+     */
     uploadRef(filePath: string): Promise<{
         url: string;
         media_type?: string;

package/dist/client.js

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
+import { compressForVision } from './compress.js';
 /**
  * 客户端自报身份 —— 中台靠它把 gen_jobs.channel 记成 'cli'，报错告警也靠它定位调用方。
  *
@@ -141,8 +142,13 @@ export class StudioClient {
             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' },
@@ -240,7 +246,7 @@ export class StudioClient {
      */
     async reverse(input) {
         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',
@@ -255,8 +261,12 @@ export class StudioClient {
      * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
      * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
      */
+    /**
+     * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
+     * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
+     */
     async uploadRef(filePath) {
-        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 };
     }
     /**
@@ -274,7 +284,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)
@@ -358,9 +368,19 @@ function sleep(ms) {
  * 带上原文件名：中台判类型靠字节魔数不靠这个，但文件名会进日志/对象存储的排查线索，
  * 匿名的 "blob" 出问题时谁也认不出是哪张图。故意不设 MIME——声明的 MIME 中台本来就不信。
  */
-function fileForm(filePath) {
+/**
+ * 所有 multipart 上传的唯一入口，内置参考图压缩（见 compress.ts）。
+ * 压缩放这里而不是各调用点：uploadRef / reverse / image-to-template 都走它，
+ * 加在调用点就会漏——2026-08-16 就漏过 image-to-template，4.1MB 原图直传把任务拖挂了。
+ */
+async function fileForm(filePath) {
+    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/dist/commands/gen.d.ts

@@ -9,7 +9,8 @@ export declare function gen(client: StudioClient, opts: {
     ratio?: string;
     model?: string;
     quality?: string;
-    ref?: string;
+    ref?: string[];
+    transparent?: boolean;
     video?: boolean;
     duration?: number;
     image?: string;

package/dist/commands/gen.js

@@ -1,3 +1,5 @@
+/** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
+const MAX_REFS = 5;
 export async function gen(client, opts) {
     // prompt / skill / template 三选一。commander 不好表达互斥，在这里校验，报错要说清怎么改
     const picked = [opts.prompt, opts.skill, opts.template].filter(Boolean).length;
@@ -16,6 +18,10 @@ export async function gen(client, 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;
     if (opts.fields) {
         try {
@@ -25,14 +31,26 @@ export async function gen(client, opts) {
             throw new Error(`--fields 必须是合法 JSON 对象，如 '{"artist":"王嘉尔","city":"南京"}'，收到: ${opts.fields}`);
         }
     }
-    // 可选：先上传垫图（图片出图 --ref / 视频图生视频 --image 都走这里）
+    // 可选：先上传垫图（图片出图 --ref 可给多张 / 视频图生视频 --image 单张）
+    //
+    // 顺序有语义：中台把数组按序喂给模型，提示词里写「参考图片1的排版、用图片2当背景」
+    // 时，图片N 对应的就是这里的第 N 个 --ref。所以上传要顺序执行、不能并发抢跑。
     let referenceImage;
-    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;
+    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 = [];
+        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 独立链路 ──
     if (opts.video) {
@@ -78,6 +96,10 @@ export async function gen(client, opts) {
         model: opts.model,
         quality: opts.quality,
         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/dist/commands/reverse.d.ts

@@ -1,3 +1,8 @@
-/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt） */
+/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt）。
+ *  主路是本地 Ollama（qwen3-vl），快、零成本、无需登录；中台 API 是回落路，走回落时会明确提示较慢。
+ *  client 懒构造（getClient）：本地路成功就完全不碰中台凭证。
+ *  本地系统的 AI 能力统一收口在这个 CLI，reverse 是第一个本地化的能力。 */
 import type { StudioClient } from '../client.js';
-export declare function reverse(client: StudioClient, input: string): Promise<void>;
+export declare function reverse(getClient: () => StudioClient, input: string, opts?: {
+    api?: boolean;
+}): Promise<void>;

package/dist/commands/reverse.js

@@ -1,7 +1,33 @@
-export async function reverse(client, input) {
-    // 输入是文件路径还是 URL
+import { checkLocalVlm, reverseLocally, LOCAL_VLM_MODEL } from '../local-vision.js';
+export async function reverse(getClient, input, opts = {}) {
     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) {
     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/dist/commands/templates.js

@@ -13,7 +13,8 @@ export async function templates(client, opts = {}) {
     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/dist/commands/video-templates.d.ts

@@ -5,6 +5,8 @@ export declare function videoTemplates(client: StudioClient, opts?: {
 }): Promise<void>;
 interface CreateVideoTemplateOpts {
     name: string;
+    /** 对外调用标识，全局唯一。不给就自动生成一个（vt- 前缀） */
+    slug?: string;
     prompt: string;
     category?: string;
     description?: string;

package/dist/commands/video-templates.js

@@ -14,8 +14,9 @@ export async function videoTemplates(client, opts = {}) {
         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`);
         if (t.sample_video_url) {
@@ -34,11 +35,17 @@ export async function createVideoTemplate(client, opts) {
         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 = {
-        model: opts.model || 'seedance-2',
+        // 默认 auto：交给中台路由按 ratio/duration 挑档次。锁死具体模型得自己保证参数配得上它
+        model: opts.model || 'auto',
         prompt_template: opts.prompt,
         is_default: true,
     };
@@ -46,14 +53,15 @@ export async function createVideoTemplate(client, opts) {
         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,
@@ -61,6 +69,7 @@ export async function createVideoTemplate(client, opts) {
         generation_configs: [cfg],
     });
     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)

package/dist/compress.d.ts

@@ -0,0 +1,13 @@
+export interface CompressResult {
+    /** 要上传的数据；未压缩时为 null，表示用原文件 */
+    buffer: Buffer | null;
+    /** 上传时用的文件名（转了格式要换扩展名） */
+    filename: string;
+    /** 给人看的一行说明，未压缩时为空 */
+    note: string;
+}
+/**
+ * @param filePath 本地图片路径
+ * @returns 压缩结果；非图片、体积已达标、或 sharp 不可用时 buffer 为 null
+ */
+export declare function compressForVision(filePath: string): Promise<CompressResult>;

package/dist/compress.js

@@ -0,0 +1,97 @@
+/**
+ * 参考图压缩 —— 上传前把图缩到视觉模型够用的尺寸。
+ *
+ * 参考图的用途是「让模型看懂画面」，不是留档，不需要原始分辨率。实测 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;
+async function loadSharp() {
+    try {
+        const m = await import('sharp');
+        return m.default ?? m;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @param filePath 本地图片路径
+ * @returns 压缩结果；非图片、体积已达标、或 sharp 不可用时 buffer 为 null
+ */
+export async function compressForVision(filePath) {
+    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;
+    let ext;
+    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/dist/index.js

@@ -93,6 +93,22 @@ function withClient(fn) {
         }
     };
 }
+// reverse 的本地路（Ollama）不需要中台凭证，client 懒构造：只有真回落 API 才建，
+// 未登录的报错也只在那时候出现
+function withLazyClient(fn) {
+    return async (...args) => {
+        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.message}\n`);
+            process.exit(1);
+        }
+    };
+}
 // products / assets 查的是租户自己后台的数据，不是 Studio 中台的，走独立的 TenantClient
 // （见 tenant-client.ts 顶部注释），只支持租户 apiKey 身份，不支持个人 login token。
 function withTenantClient(fn) {
@@ -125,17 +141,23 @@ 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, acc) => [...acc, v], [])
+    // 透明背景是上游的 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, opts) => gen(client, opts)));
 program
     .command('reverse <input>')
-    .description('读图：上传图或图片 URL，反推 SCULPT prompt，stdout 输出英文 prompt（只读图；要做成模板用 image-to-template）')
-    .action(withClient((client, input) => reverse(client, input)));
+    .description('读图：反推 SCULPT prompt，stdout 输出英文 prompt。主路本地 Ollama（qwen3-vl，快，无需登录）；本地不可用回落中台 API（会提示较慢）。只读图；要做成模板用 image-to-template')
+    .option('--api', '跳过本地 Ollama，强制走中台 API（慢，需登录）')
+    .action(withLazyClient((getClient, input, opts) => reverse(getClient, input, opts)));
 program
     .command('image-to-template <input>')
     .description('图生模板：上传图或图片 URL → 读图 + 文字层逆向 + 变量化 → 建成可复用的图片模板（原图自动焊成参考图）')
@@ -176,10 +198,11 @@ videoTemplatesCmd
     .description('新建视频模板——归属由账号身份自动决定：租户 apiKey 建的自动归该租户，平台管理员建的是平台共享模板，个人账号不能建')
     .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（可选）')

package/dist/local-vision.d.ts

@@ -0,0 +1,14 @@
+import type { ReverseResult } from './client.js';
+/** 本地读图模型。换档位用 MUSEAV_LOCAL_VLM 环境变量，不用改代码 */
+export declare const LOCAL_VLM_MODEL: string;
+export interface LocalVlmStatus {
+    running: boolean;
+    modelPresent: boolean;
+    host: string;
+    /** running=false 时的原因（给用户看的行动指引） */
+    reason?: string;
+}
+/** 探活 + 模型在位检查。3 秒探不通就是没起服务，不等推理超时才发现 */
+export declare function checkLocalVlm(): Promise<LocalVlmStatus>;
+/** 本地逆向一张图。任何失败都抛 Error，由调用方决定回落 */
+export declare function reverseLocally(filePath: string): Promise<ReverseResult>;