museav-cli 2.5.0 → 2.8.0

package/dist/local-bg.js

@@ -1,6 +1,6 @@
 /**
  * 本地抠图（去背景）—— remove-bg 的核心实现。
- * 模型走 ONNX（ISNet / U2Net，均 Apache-2.0），推理走 onnxruntime-node（MIT），
+ * 模型走 ONNX（ISNet / U2Net / BiRefNet-Lite，均 Apache-2.0），推理走 onnxruntime-node（MIT），
  * 前后处理走 sharp —— 整条链路许可证干净（imgly 那个 npm 包是 AGPL，不进依赖），
  * 且三个依赖在 macOS / Windows / Linux 都有预编译，无平台特化代码。
  * 模型文件首次使用时下载到 ~/.museav-models/ 缓存（一次性 ~170MB）。
@@ -8,21 +8,45 @@
 import { mkdir, writeFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+/**
+ * 每个模型的输入尺寸与归一化参数**都不一样**，必须随模型带着走。
+ * 取值对齐 rembg 的 session 定义（sessions/dis_general_use.py、sessions/u2net.py）：
+ *   isnet-general-use → resize 1024，mean (0.5,0.5,0.5)  std (1,1,1)
+ *   u2net             → resize  320，mean ImageNet        std ImageNet
+ * 用错任何一项都不会报错，只会安静地输出一张糊掉的 mask —— 这是最难查的那种 bug。
+ */
 export const BG_MODELS = {
     isnet: {
         file: 'isnet-general-use.onnx',
         // rembg 官方 release 托管的同一份模型（Apache-2.0，源自 xuebinqin/DIS）
         url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/isnet-general-use.onnx',
         label: 'ISNet（通用，质量优先）',
+        edge: 1024,
+        mean: [0.5, 0.5, 0.5],
+        std: [1.0, 1.0, 1.0],
     },
     u2net: {
         file: 'u2net.onnx',
         url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net.onnx',
         label: 'U2Net（经典通用）',
+        edge: 320,
+        mean: [0.485, 0.456, 0.406],
+        std: [0.229, 0.224, 0.225],
+    },
+    birefnet: {
+        file: 'birefnet-general-lite.onnx',
+        url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/BiRefNet-general-bb_swin_v1_tiny-epoch_232.onnx',
+        label: 'BiRefNet-Lite（细节最好，毛发/低对比度主体优先用它）',
+        edge: 1024,
+        mean: [0.485, 0.456, 0.406],
+        std: [0.229, 0.224, 0.225],
+        // BiRefNet 输出的是 logits，要先过 sigmoid 才是概率；ISNet/U2Net 的输出已经是 0-1 区间。
+        // 漏掉这步不会报错，只会得到一张几乎全是半透明的 mask。
+        sigmoid: true,
+        size: 214, // MB，下载提示用
     },
 };
 const MODEL_DIR = join(homedir(), '.museav-models');
-const INPUT_EDGE = 1024;
 function modelPath(key) {
     return join(MODEL_DIR, BG_MODELS[key].file);
 }
@@ -39,7 +63,8 @@ export async function ensureBgModel(key) {
     }
     await mkdir(MODEL_DIR, { recursive: true });
     const def = BG_MODELS[key];
-    process.stderr.write(`↓ 首次使用，下载 ${def.label}（~170MB，一次性，缓存到 ${MODEL_DIR}）...\n`);
+    const mb = 'size' in def ? `~${def.size}MB` : '~170MB';
+    process.stderr.write(`↓ 首次使用，下载 ${def.label}（${mb}，一次性，缓存到 ${MODEL_DIR}）...\n`);
     const resp = await fetch(def.url);
     if (!resp.ok || !resp.body)
         throw new Error(`模型下载失败 HTTP ${resp.status}：${def.url}`);
@@ -80,30 +105,44 @@ export async function removeBackgroundLocal(inputPath, modelKey) {
     const { data: rgb, info } = await sharp(inputPath).rotate().removeAlpha().raw().toBuffer({ resolveWithObject: true });
     if (info.channels !== 3)
         throw new Error(`预处理得到 ${info.channels} 通道（预期 3）`);
-    // ── 模型输入：拉伸到 1024×1024，(x/255 - 0.5)/0.5 归一化，HWC → CHW ──
+    // ── 模型输入：按该模型的 edge 拉伸，(x/max - mean)/std 归一化，HWC → CHW ──
+    const def = BG_MODELS[modelKey];
+    const edge = def.edge;
     const small = await sharp(rgb, { raw: { width: info.width, height: info.height, channels: 3 } })
-        .resize(INPUT_EDGE, INPUT_EDGE, { fit: 'fill' })
+        .resize(edge, edge, { fit: 'fill', kernel: 'lanczos3' })
         .raw()
         .toBuffer();
-    const f32 = new Float32Array(3 * INPUT_EDGE * INPUT_EDGE);
-    const N = INPUT_EDGE * INPUT_EDGE;
+    // 分母是「这张图的最大像素值」而不是固定 255 —— 对齐 rembg 的 im_ary / max(im_ary)。
+    // 整体偏暗的图用 255 归一化会让输入分布整体偏小，mask 跟着糊。
+    let peak = 0;
+    for (let i = 0; i < small.length; i++)
+        if (small[i] > peak)
+            peak = small[i];
+    const scale = Math.max(peak, 1e-6);
+    const N = edge * edge;
+    const f32 = new Float32Array(3 * N);
     for (let i = 0; i < N; i++) {
-        f32[i] = (small[i * 3] / 255 - 0.5) / 0.5;
-        f32[N + i] = (small[i * 3 + 1] / 255 - 0.5) / 0.5;
-        f32[2 * N + i] = (small[i * 3 + 2] / 255 - 0.5) / 0.5;
+        f32[i] = (small[i * 3] / scale - def.mean[0]) / def.std[0];
+        f32[N + i] = (small[i * 3 + 1] / scale - def.mean[1]) / def.std[1];
+        f32[2 * N + i] = (small[i * 3 + 2] / scale - def.mean[2]) / def.std[2];
     }
     const feeds = {};
-    feeds[session.inputNames[0]] = new ort.Tensor('float32', f32, [1, 3, INPUT_EDGE, INPUT_EDGE]);
+    feeds[session.inputNames[0]] = new ort.Tensor('float32', f32, [1, 3, edge, edge]);
     const results = await session.run(feeds);
     const out = results[session.outputNames[0]];
     const maskFlat = out.data;
     if (maskFlat.length < N)
         throw new Error(`模型输出尺寸异常（${maskFlat.length}）`);
-    // ── 后处理：min-max 归一化到 0-255，再缩回原图尺寸 ──
+    // ── 后处理：（按模型）sigmoid → min-max 归一化到 0-255 → 缩回原图尺寸 ──
+    const needSigmoid = 'sigmoid' in def && def.sigmoid;
+    const prob = new Float32Array(N);
+    for (let i = 0; i < N; i++) {
+        prob[i] = needSigmoid ? 1 / (1 + Math.exp(-maskFlat[i])) : maskFlat[i];
+    }
     let lo = Infinity;
     let hi = -Infinity;
     for (let i = 0; i < N; i++) {
-        const v = maskFlat[i];
+        const v = prob[i];
         if (v < lo)
             lo = v;
         if (v > hi)
@@ -111,12 +150,22 @@ export async function removeBackgroundLocal(inputPath, modelKey) {
     }
     const range = hi - lo || 1;
     const mask8 = Buffer.alloc(N);
-    for (let i = 0; i < N; i++)
-        mask8[i] = Math.round(((maskFlat[i] - lo) / range) * 255);
-    const maskFull = await sharp(mask8, { raw: { width: INPUT_EDGE, height: INPUT_EDGE, channels: 1 } })
-        .resize(info.width, info.height, { fit: 'fill' })
+    for (let i = 0; i < N; i++) {
+        const v = (prob[i] - lo) / range;
+        mask8[i] = Math.round(Math.min(1, Math.max(0, v)) * 255); // clip(0,1) 对齐 rembg
+    }
+    // ⚠️ sharp 对单通道 raw 做 resize 后会吐出 3 通道（灰度被展开成 RGB）。
+    // 按单通道去索引 maskFull[i] 就会以 1/3 的步长错位采样，输出一张隔行残影的图 ——
+    // 不报错、不崩，只是抠出来的东西是条纹状的。所以这里既强制灰度色彩空间，
+    // 又用实际返回的 channels 来索引，两道保险。
+    const { data: maskFull, info: maskInfo } = await sharp(mask8, {
+        raw: { width: edge, height: edge, channels: 1 },
+    })
+        .resize(info.width, info.height, { fit: 'fill', kernel: 'lanczos3' })
+        .toColourspace('b-w')
         .raw()
-        .toBuffer();
+        .toBuffer({ resolveWithObject: true });
+    const maskStride = maskInfo.channels || 1;
     // ── alpha 合成：直接构造 RGBA（alpha = mask），不依赖 composite 的混合语义 ──
     const w = info.width;
     const h = info.height;
@@ -125,7 +174,7 @@ export async function removeBackgroundLocal(inputPath, modelKey) {
         rgba[i * 4] = rgb[i * 3];
         rgba[i * 4 + 1] = rgb[i * 3 + 1];
         rgba[i * 4 + 2] = rgb[i * 3 + 2];
-        rgba[i * 4 + 3] = maskFull[i];
+        rgba[i * 4 + 3] = maskFull[i * maskStride];
     }
     return sharp(rgba, { raw: { width: w, height: h, channels: 4 } }).png().toBuffer();
 }

package/dist/mimo-speech.d.ts

@@ -0,0 +1,31 @@
+/** 默认预置音色。上游没有「列出音色」的接口，这个是文档给出且实测可用的 */
+export declare const DEFAULT_VOICE = "Chloe";
+export declare function mimoKey(): string;
+export interface SpeakOptions {
+    /** 预置音色名（默认 Chloe）。与 design / clonePath 互斥 */
+    voice?: string;
+    /** 一句话描述音色 → 走音色设计 */
+    design?: string;
+    /** 音色样本音频路径 → 走音色克隆 */
+    clonePath?: string;
+    /** 风格/语气指令。三种模式都能用 */
+    instruction?: string;
+}
+/** 合成的三种模式。asr 不在里面——它是识别，不由 speechMode 决定 */
+export type SpeechMode = 'tts' | 'design' | 'clone';
+/** 用哪种模式，取决于给了什么参数——克隆 > 设计 > 预置音色 */
+export declare function speechMode(opts: SpeakOptions): SpeechMode;
+/**
+ * 合成语音，返回 WAV 数据。
+ * @param text 要读出来的文本
+ */
+export declare function synthesize(text: string, opts?: SpeakOptions): Promise<Buffer>;
+/**
+ * 识别音频里的文字。
+ *
+ * ⚠️ 质量有波动：同一段合成音频两次实测，一次「声影成诗，一念成相」（同音字级别），
+ * 一次「上庸城失，一面呈象」（整句都错）。别把结果直接当可信文本用在计费或入库口径上。
+ */
+export declare function transcribe(audioPath: string): Promise<string>;
+/** WAV 时长（秒），用于给用户一个「出了多长」的反馈。头部损坏时返回 null 而不是抛错 */
+export declare function wavSeconds(buf: Buffer): number | null;

package/dist/mimo-speech.js

@@ -0,0 +1,127 @@
+/**
+ * 小米 MiMo 语音能力（合成 / 音色设计 / 音色克隆 / 识别）—— 直连上游，不经中台。
+ *
+ * 为什么直连：中台的出音链路还没接完（media_type=audio 的路由与落盘在做），而这批能力
+ * 目前只给内部用、不开放给租户。CLI 直连能立刻用上，也天然不会漏给租户——租户手里
+ * 没有这把 key。等中台接完再决定要不要把 CLI 切过去。
+ *
+ * ⚠️ 协议层的真源是 museav-manager 的 `shared/mimo-audio.js`（那边有 11 个单测钉着）。
+ * 这里是 TS 副本，**改协议要同步两边**。复制而不是共享的原因：CLI 是独立发布的 npm 包，
+ * 跨仓 import 会把中台仓变成它的构建依赖。
+ *
+ * ## 四个反直觉的点（实测踩出来的，写错不会报错，只是拿不到音频）
+ *
+ * 1. 合成**不走 /v1/audio/speech**。OpenAI 那套音频端点这边一个都没有（试了七个全 404），
+ *    四种能力共用 `/v1/chat/completions`，靠 model 区分。
+ * 2. **待合成文本放 assistant 角色**，user 放音色指令。反过来写会得到一段「回答」而不是朗读。
+ * 3. 音频是 **base64** 回在 `message.audio.data`，不是二进制流。
+ * 4. 识别的输入音频在 user 的 content **数组**里（`type: 'input_audio'`），且要裸 base64。
+ *
+ * key 走 MIMO_API_KEY 环境变量（跟 OLLAMA_HOST / MUSEAV_LOCAL_VLM 一个路子），不进
+ * ~/.museav.json —— 那个文件存的是中台身份，跟这个上游是两回事。
+ */
+import { readFile } from 'node:fs/promises';
+/** 专属 Base URL。换端点用 MIMO_BASE_URL，不用改代码 */
+const BASE = (process.env.MIMO_BASE_URL || 'https://token-plan-cn.xiaomimimo.com/v1').replace(/\/+$/, '');
+const MODELS = {
+    tts: 'mimo-v2.5-tts',
+    design: 'mimo-v2.5-tts-voicedesign',
+    clone: 'mimo-v2.5-tts-voiceclone',
+    asr: 'mimo-v2.5-asr',
+};
+/** 默认预置音色。上游没有「列出音色」的接口，这个是文档给出且实测可用的 */
+export const DEFAULT_VOICE = 'Chloe';
+export function mimoKey() {
+    const key = process.env.MIMO_API_KEY || '';
+    if (!key) {
+        throw new Error('缺少 MIMO_API_KEY。语音能力直连小米 MiMo，不走中台身份：\n'
+            + '  export MIMO_API_KEY=...        或\n'
+            + '  cs kyvault run --env MIMO_API_KEY=secret://mimo/api-key -- museav speak ...');
+    }
+    return key;
+}
+async function call(body) {
+    const res = await fetch(`${BASE}/chat/completions`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${mimoKey()}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`上游 HTTP ${res.status}：${text.slice(0, 200)}`);
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`上游返回不是 JSON：${text.slice(0, 200)}`);
+    }
+    if (data?.error)
+        throw new Error(data.error.message || String(data.error));
+    if (!Array.isArray(data?.choices) || !data.choices.length)
+        throw new Error('上游返回里没有 choices');
+    return data;
+}
+/** 用哪种模式，取决于给了什么参数——克隆 > 设计 > 预置音色 */
+export function speechMode(opts) {
+    if (opts.clonePath)
+        return 'clone';
+    if (opts.design)
+        return 'design';
+    return 'tts';
+}
+/**
+ * 合成语音，返回 WAV 数据。
+ * @param text 要读出来的文本
+ */
+export async function synthesize(text, opts = {}) {
+    const content = String(text || '').trim();
+    if (!content)
+        throw new Error('要合成的文本是空的');
+    const mode = speechMode(opts);
+    const messages = [];
+    // user 放指令：设计模式靠它定义音色，其余模式靠它调语气
+    const instruction = mode === 'design' ? opts.design : opts.instruction;
+    if (instruction)
+        messages.push({ role: 'user', content: instruction });
+    // 待合成文本必须是 assistant，见文件头第 2 条
+    messages.push({ role: 'assistant', content });
+    const audio = { format: 'wav' };
+    if (mode === 'clone') {
+        const buf = await readFile(opts.clonePath);
+        audio.voice = `data:audio/wav;base64,${buf.toString('base64')}`;
+    }
+    else if (mode === 'tts') {
+        audio.voice = opts.voice || DEFAULT_VOICE;
+    }
+    const data = await call({ model: MODELS[mode], messages, audio });
+    const b64 = data.choices[0]?.message?.audio?.data;
+    if (!b64)
+        throw new Error('上游没有返回音频（audio.data 为空）');
+    return Buffer.from(b64, 'base64');
+}
+/**
+ * 识别音频里的文字。
+ *
+ * ⚠️ 质量有波动：同一段合成音频两次实测，一次「声影成诗，一念成相」（同音字级别），
+ * 一次「上庸城失，一面呈象」（整句都错）。别把结果直接当可信文本用在计费或入库口径上。
+ */
+export async function transcribe(audioPath) {
+    const buf = await readFile(audioPath);
+    const format = /\.(wav|mp3|m4a|flac|ogg|pcm)$/i.exec(audioPath)?.[1]?.toLowerCase() || 'wav';
+    const data = await call({
+        model: MODELS.asr,
+        messages: [{ role: 'user', content: [{ type: 'input_audio', input_audio: { data: buf.toString('base64'), format } }] }],
+    });
+    const text = data.choices[0]?.message?.content;
+    if (typeof text !== 'string' || !text.trim())
+        throw new Error('上游没有返回识别文本');
+    return text.trim();
+}
+/** WAV 时长（秒），用于给用户一个「出了多长」的反馈。头部损坏时返回 null 而不是抛错 */
+export function wavSeconds(buf) {
+    if (buf.length < 44 || buf.subarray(0, 4).toString() !== 'RIFF')
+        return null;
+    const byteRate = buf.readUInt32LE(28);
+    return byteRate > 0 ? (buf.length - 44) / byteRate : null;
+}

package/package.json

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

package/src/client.ts

@@ -320,8 +320,13 @@ export interface ModelOption {
 }
 
 export interface Balance {
-  /** 数值单位是 ¥（人民币）。字段名带 usd 是历史遗留命名，不代表美元——中台侧不存在汇率换算 */
-  balance_usd: number
+  /** 余额（¥）。中台 2026-08-21 起发这个字段名 */
+  balance_cny?: number
+  /**
+   * 同一个数的旧字段名，中台仍在双发。字段名带 usd 纯属历史遗留，值一直是人民币——
+   * 中台侧不存在汇率换算。老版本 CLI 只认这个名字，所以中台不会立刻停发。
+   */
+  balance_usd?: number
   /** 租户加价率（0.2 = 加价 20%） */
   markup_pct: number
   checked_at: string
@@ -427,6 +432,47 @@ export class StudioClient {
     return r.row
   }
 
+  /** 贴图素材清单（租户级资产，服务端已按调用者权限过滤）。PNG 装饰图，叠加在海报/封面上 */
+  async stickers(): Promise<any[]> {
+    const r = await this.request('stickers')
+    return Array.isArray(r) ? r : []
+  }
+
+  /** 上传贴图素材（不压缩——透明 PNG 压缩会破坏透明通道） */
+  async createSticker(filePath: string, name: string): Promise<any> {
+    const blob = new Blob([new Uint8Array(readFileSync(filePath))])
+    const fd = new FormData()
+    fd.append('file', blob, basename(filePath))
+    fd.append('name', name)
+    return this.request('stickers', { method: 'POST', body: fd })
+  }
+
+  /** 删除贴图素材 */
+  async deleteSticker(id: string): Promise<void> {
+    await this.request(`stickers?id=${encodeURIComponent(id)}`, { method: 'DELETE' })
+  }
+
+  /** 版式模板清单（租户级资产）：封面底图 + 固定描述（{城市}{明星} 占位符） */
+  async posterTemplates(): Promise<any[]> {
+    const r = await this.request('poster-templates')
+    return Array.isArray(r) ? r : []
+  }
+
+  /** 上传版式模板（不压缩，保留封面底图原样） */
+  async createPosterTemplate(filePath: string, name: string, prompt: string): Promise<any> {
+    const blob = new Blob([new Uint8Array(readFileSync(filePath))])
+    const fd = new FormData()
+    fd.append('file', blob, basename(filePath))
+    fd.append('name', name)
+    fd.append('prompt', prompt)
+    return this.request('poster-templates', { method: 'POST', body: fd })
+  }
+
+  /** 删除版式模板 */
+  async deletePosterTemplate(id: string): Promise<void> {
+    await this.request(`poster-templates?id=${encodeURIComponent(id)}`, { method: 'DELETE' })
+  }
+
   /** 提交出图任务，立即返回 jobId */
   async generate(opts: GenerateOptions): Promise<{ jobId: string; trace_id?: string }> {
     // prompt / skill_slug / template_id 三选一：都传时服务端按 prompt > template_id > skill_slug
@@ -624,9 +670,22 @@ export class StudioClient {
    * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
    * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
    */
-  async uploadRef(filePath: string): Promise<{ url: string; media_type?: string; mime?: string }> {
-    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 }
+  /**
+   * 上传素材。默认只存文件、回直链（参考图/垫图就该这样）。
+   *
+   * asWork=true 时另外记一条作品：不落库的话文件只存在 R2 里，
+   * 作品页、后台画廊、项目归档全都看不见它 —— 「传到我的账户」就没发生。
+   * 只对账户身份生效（作品要归到具体某个人头上），租户 key 传了也会被中台忽略。
+   */
+  async uploadRef(
+    filePath: string,
+    opts: { asWork?: boolean; workspaceId?: string } = {},
+  ): Promise<{ url: string; media_type?: string; mime?: string; job_id?: string | null }> {
+    const form = await fileForm(filePath)
+    if (opts.asWork) form.append('as_work', '1')
+    if (opts.workspaceId) form.append('workspace_id', opts.workspaceId)
+    const r = await this.request('upload-ref', { method: 'POST', body: form })
+    return { url: r.url, media_type: r.media_type, mime: r.mime, job_id: r.job_id ?? null }
   }
 
   /**

package/src/commands/balance.ts

@@ -3,8 +3,11 @@ import type { StudioClient } from '../client.js'
 
 export async function balance(client: StudioClient): Promise<void> {
   const r = await client.balance()
-  // 单位 ¥ 人民币（后台 2026-08-09 起只返回租户自己的余额，不再下发上游供应商聚合数据）
-  process.stderr.write(`余额: ¥${r.balance_usd?.toFixed(2) ?? '?'}`)
+  // 单位 ¥ 人民币（后台 2026-08-09 起只返回租户自己的余额，不再下发上游供应商聚合数据）。
+  // 优先读 balance_cny：中台已改用这个名字，balance_usd 是双发过渡期的旧名，
+  // 两个值永远相等，但等中台停发旧名时这里不用再改一次。
+  const cny = r.balance_cny ?? r.balance_usd
+  process.stderr.write(`余额: ¥${cny?.toFixed(2) ?? '?'}`)
   if (r.markup_pct) process.stderr.write(`  加价率: ${(r.markup_pct * 100).toFixed(0)}%`)
   if (r.checked_at) process.stderr.write(`  校验时间: ${r.checked_at.slice(0, 19).replace('T', ' ')}`)
   process.stderr.write('\n')

package/src/commands/img-tools.ts

@@ -82,7 +82,8 @@ export interface RemoveBgOpts {
 
 export async function removeBgCmd(input: string, opts: RemoveBgOpts): Promise<void> {
   if (!(await fileExists(input))) throw new Error(`文件不存在: ${input}`)
-  const modelKey = (opts.model || 'isnet') as BgModelKey
+  // 默认 birefnet：实测对毛发、白色主体、低对比度背景的召回远好于 isnet/u2net
+  const modelKey = (opts.model || 'birefnet') as BgModelKey
   if (!(modelKey in BG_MODELS)) throw new Error(`--model 只支持 ${Object.keys(BG_MODELS).join(' / ')}`)
 
   const start = Date.now()

package/src/commands/poster-templates.ts

@@ -0,0 +1,33 @@
+/**
+ * museav poster-templates —— 版式模板库（租户级资产）。
+ *  封面底图 + 固定描述（{城市} {明星} 占位符），选版式时把城市/明星名填进底图。
+ *  学员做的封面版式保存后全租户共享。
+ */
+import type { StudioClient } from '../client.js'
+
+export async function posterTemplates(client: StudioClient): Promise<void> {
+  const list = await client.posterTemplates()
+  if (!list.length) {
+    process.stderr.write('没有版式模板（可用 museav poster-templates add <底图> --name <名称> --prompt <描述> 保存）\n')
+    return
+  }
+  process.stderr.write(`版式模板（${list.length} 个）:\n`)
+  for (const t of list) {
+    process.stderr.write(`  ${t.id.padEnd(38)} ${String(t.name || '').padEnd(18)} ${String(t.prompt || '').slice(0, 40)}\n`)
+  }
+  process.stderr.write(`\n保存: museav poster-templates add <底图路径> --name <名称> --prompt <描述>\n`)
+  console.log(list.map((t) => t.id).join('\n'))
+}
+
+export async function createPosterTemplate(
+  client: StudioClient,
+  filePath: string,
+  opts: { name: string; prompt: string },
+): Promise<void> {
+  if (!opts.name?.trim()) throw new Error('--name 必填')
+  if (!opts.prompt?.trim()) throw new Error('--prompt 必填，{城市} {明星} 占位符会被替换')
+  const row = await client.createPosterTemplate(filePath, opts.name, opts.prompt)
+  const id = row?.template?.id || row?.id || ''
+  process.stderr.write(`✅ 版式模板已保存：${id}\n`)
+  console.log(id)
+}

package/src/commands/speak.ts

@@ -0,0 +1,54 @@
+/**
+ * museav speak —— 文本转语音，stdout 输出生成的文件路径。
+ * museav transcribe —— 语音转文本，stdout 输出识别结果。
+ *
+ * 三种音色来源，给了什么参数就走哪条：
+ *   默认         预置音色（--voice Chloe）
+ *   --design     一句话描述音色，当场造一个
+ *   --clone      拿一段音频当样本，克隆它的音色
+ *
+ * 直连小米 MiMo，不经中台，需要 MIMO_API_KEY —— 原因见 src/mimo-speech.ts 的文件头。
+ */
+import { writeFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+import { synthesize, transcribe, speechMode, wavSeconds, DEFAULT_VOICE } from '../mimo-speech.js'
+
+const MODE_LABEL = { tts: '预置音色', design: '音色设计', clone: '音色克隆' } as const
+
+export interface SpeakCliOptions {
+  out?: string
+  voice?: string
+  design?: string
+  clone?: string
+  instruction?: string
+}
+
+export async function speak(text: string, opts: SpeakCliOptions = {}): Promise<void> {
+  const mode = speechMode({ clonePath: opts.clone, design: opts.design })
+  // 克隆模式下 opts.clone 是整条路径，进度行里只留文件名——绝对路径会把这行顶到换行
+  const detail = mode === 'tts' ? (opts.voice || DEFAULT_VOICE)
+    : mode === 'clone' ? basename(opts.clone || '') : (opts.design || '')
+  process.stderr.write(`合成中（${MODE_LABEL[mode]}${detail ? ` · ${detail}` : ''}）...\n`)
+
+  const buf = await synthesize(text, {
+    voice: opts.voice,
+    design: opts.design,
+    clonePath: opts.clone,
+    instruction: opts.instruction,
+  })
+
+  // 默认落在当前目录，文件名带时间戳避免连续合成互相覆盖
+  const out = resolve(opts.out || `speech-${Date.now()}.wav`)
+  await writeFile(out, buf)
+  const secs = wavSeconds(buf)
+  process.stderr.write(`✅ ${(buf.length / 1024).toFixed(0)}KB${secs ? ` · ${secs.toFixed(2)}s` : ''}\n`)
+  console.log(out)
+}
+
+export async function transcribeCmd(audioPath: string): Promise<void> {
+  process.stderr.write(`识别中 ${audioPath} ...\n`)
+  const text = await transcribe(audioPath)
+  // 质量有波动（见 mimo-speech.ts 的注释），提醒一句，但不影响 stdout 的机器可读性
+  process.stderr.write('✅ 识别完成（同音字可能有误，重要场景请核对）\n')
+  console.log(text)
+}

package/src/commands/stickers.ts

@@ -0,0 +1,29 @@
+/**
+ * museav stickers —— 贴图素材库（租户级资产）。
+ *  PNG 透明装饰图（logo/花纹/边框），叠加在海报/封面上。
+ *  列出的都是自己租户的贴图；上传用账户 Key 或租户 Key 均可（落到本租户）。
+ */
+import type { StudioClient } from '../client.js'
+
+export async function stickers(client: StudioClient): Promise<void> {
+  const list = await client.stickers()
+  if (!list.length) {
+    process.stderr.write('没有贴图素材（可用 museav stickers add <图片> --name <名称> 上传）\n')
+    return
+  }
+  process.stderr.write(`贴图素材（${list.length} 个）:\n`)
+  for (const s of list) {
+    process.stderr.write(`  ${s.id.padEnd(38)} ${String(s.name || '').padEnd(20)} ${s.url || ''}\n`)
+  }
+  process.stderr.write(`\n上传: museav stickers add <图片路径> --name <名称>\n`)
+  // stdout 只出 id，便于脚本与 agent 解析
+  console.log(list.map((s) => s.id).join('\n'))
+}
+
+export async function createSticker(client: StudioClient, filePath: string, opts: { name: string }): Promise<void> {
+  if (!opts.name?.trim()) throw new Error('--name 必填')
+  const row = await client.createSticker(filePath, opts.name)
+  const id = row?.sticker?.id || row?.id || ''
+  process.stderr.write(`✅ 贴图素材已上传：${id}\n`)
+  console.log(id)
+}

package/src/commands/upload.ts

@@ -9,10 +9,26 @@ import type { StudioClient } from '../client.js'
 
 const KIND_LABEL: Record<string, string> = { image: '图片', audio: '音频', video: '视频' }
 
-export async function upload(client: StudioClient, filePath: string): Promise<void> {
+export async function upload(
+  client: StudioClient,
+  filePath: string,
+  opts: { toWorks?: boolean; workspace?: string } = {},
+): Promise<void> {
   process.stderr.write(`上传 ${filePath} ...\n`)
-  const { url, media_type, mime } = await client.uploadRef(filePath)
+  const { url, media_type, mime, job_id } = await client.uploadRef(filePath, {
+    asWork: opts.toWorks,
+    workspaceId: opts.workspace,
+  })
   const kind = media_type ? `${KIND_LABEL[media_type] || media_type}${mime ? ` · ${mime}` : ''}` : ''
   process.stderr.write(`✅ 上传成功${kind ? `（${kind}）` : ''}\n`)
+  if (opts.toWorks) {
+    // 说清有没有真的进作品库：租户 key 调用时中台不记作品，只提示「已上传」会让人以为进去了
+    process.stderr.write(job_id
+      ? '📁 已收进你的作品库，在「我的作品」里能看到\n'
+      : '⚠️  文件已上传，但没能记进作品库（租户 Key 调用不记作品，作品要归到具体账户）\n')
+  } else if (media_type === 'video') {
+    // 传视频十有八九是想收成品，顺手提一句 —— 但不擅自替他决定
+    process.stderr.write('提示：加 --to-works 可以把它收进「我的作品」\n')
+  }
   console.log(url)
 }

package/src/compress.ts

@@ -59,6 +59,14 @@ export async function compressForVision(filePath: string): Promise<CompressResul
   try {
     meta = await sharp(filePath).metadata()
   } catch {
+    // HEIC 解码失败会走到这里（libheif 安全检查拒绝），但它不是「视频/音频」——
+    // 原样上传会被中台按魔数判成 image/heic，而 gpt-image-2 上游解码不了 HEIC
+    // 字节 → 400 invalid_image_input。与其等到出图时才炸，不如上传前就报清楚。
+    // 判断依据：文件名扩展名 .heic/.heif/.avif 最可靠（HEIC 与 MP4 共享 ftyp 容器头，
+    // 不能靠字节区分；sharp 读不了恰恰说明它是图不是视频——视频不喂 sharp 走这里）。
+    if (/\.(heic|heif|avif)$/i.test(name)) {
+      throw new Error(`HEIC 图片 ${name} 无法直接上传：上游模型认不得 HEIC 字节。请先转成 JPG/PNG 再上传（macOS 可用「预览」打开后另存为 JPEG，或用 museav img min 转换）`)
+    }
     return { buffer: null, filename: name, note: '' }   // 不是 sharp 认识的图（视频/音频）→ 原样传
   }