museav-cli 2.5.0 → 2.8.0

package/AGENTS.md

@@ -56,6 +56,22 @@ museav gen --prompt "$(museav reverse ./photo.png)"
 museav image-to-template ./poster.jpg --name '暗金演唱会主视觉' --variables title,subject,location
 museav image-to-template ./poster.jpg --no-create      # dry run: draft JSON on stdout, nothing created
 
+# Text-to-speech / speech-to-text (Xiaomi MiMo). These talk DIRECTLY to the upstream,
+# NOT through the platform — so they need MIMO_API_KEY and ignore your login/apiKey entirely.
+# Reason: the platform's audio pipeline isn't wired up yet, and this capability is
+# internal-only for now (tenants don't have this key, so they can't reach it).
+#   export MIMO_API_KEY=...   or   cs kyvault run --env MIMO_API_KEY=secret://mimo/api-key -- museav ...
+# stdout: the written .wav path (speak) / the recognized text (transcribe).
+museav speak '声影成诗，一念成像。'                          # preset voice (Chloe)
+museav speak '欢迎收听' --design '低沉沙哑的中年男声'          # invent a voice from a description
+museav speak '这句换个音色' --clone ./sample.wav              # clone the voice in sample.wav
+museav speak '慢一点念' --instruction '语速放慢，温柔一些'      # style/tone instruction
+museav transcribe ./recording.wav
+
+# ⚠️ transcribe accuracy wobbles on homophones — the same synthesized line came back as
+# 「声影成诗，一念成相」 once and 「上庸城失，一面呈象」 another time. Don't feed its output
+# into anything that bills, stores, or branches on exact text without a human check.
+
 # Upload a file (image/audio/video; type is detected from the bytes, not the extension)
 museav upload ./face.png
 

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 2.8.0 (2026-08-27)
+
+### 新增：贴图素材 + 版式模板命令（租户级资产，给封面/海报工具用）
+
+两个新命令，底层调中台 `/api/stickers` 和 `/api/poster-templates`，账户 Key / 租户 Key 均可（落到本租户）。
+
+- `museav stickers`：列出本租户贴图素材（PNG 透明装饰图）
+- `museav stickers add <file> --name <名称>`：上传贴图（不压缩，保留透明通道）
+- `museav poster-templates`：列出版式模板（封面底图 + 固定描述）
+- `museav poster-templates add <file> --name <名称> --prompt <描述>`：保存版式（`{城市}` `{明星}` 占位符会被替换）
+
+背景：好易美（hym）的闲鱼封面工具此前版式存学员本机桌面、贴图只在后台本地，无法共享。
+现在贴图素材 + 版式模板收归中台，CLI 一条命令加载/保存，学员间共享。
+
+## 2.7.0 (2026-08-27)
+
+### 修复：`remove-bg` 抠不出主体（三个静默 bug）
+
+抠图一直输出条纹残影、主体几乎全被抠掉。排查出三个独立 bug，共同点是**全都不报错**，
+只是安静地输出一张糊掉的 mask —— 这类 bug 只能靠拿基准实现（rembg）逐项对齐才查得出来。
+
+1. **主因：`sharp` 对单通道 raw 做 `resize` 后会返回 3 通道**（灰度被展开成 RGB）。
+   代码仍按 `maskFull[i]` 索引，等于以 1/3 的步长错位采样，于是每隔几行错位一次 ——
+   这就是条纹残影的来源。现改为 `toColourspace('b-w')` + 按实际 `channels` 步长索引，两道保险。
+2. **输入尺寸与归一化参数被硬编码成一套**（1024 + `(x/255-0.5)/0.5`），而每个模型都不同：
+   `isnet` 是 1024 / mean .5 / **std 1.0**，`u2net` 是 **320** / ImageNet 参数。
+   于是 u2net 直接崩（`Got: 1024 Expected: 320`），isnet 因 std 用 0.5 而非 1.0
+   把输入值域放大一倍。参数已改为随模型定义。
+3. **归一化分母用固定 255**，而 rembg 用的是该图的最大像素值（`im_ary / max(im_ary)`）。
+   偏暗的图用 255 归一化会让输入分布整体偏小。
+
+### 新增：BiRefNet-Lite 模型，并设为 `remove-bg` 默认
+
+`--model birefnet`（214MB，首次自动下载）。实测同一张白猫照片，主体召回：
+**birefnet 57% / u2net 25% / isnet 10%** —— 毛发、白色主体、低对比度背景全面更好。
+
+注意 BiRefNet 输出的是 **logits，要先过 sigmoid** 才是概率（ISNet/U2Net 的输出已在 0-1 区间）。
+漏掉这步同样不报错，只会得到一张几乎全是半透明的 mask，所以 `sigmoid` 做成了模型属性。
+
+修完三个模型的输出与 rembg 基准逐一对齐（57.0/57.1、10.5/10.9、25.1/25.1）。
+
+
+## 2.6.0 (2026-08-21)
+
+### 新增：语音能力（`speak` / `transcribe`）
+
+接入小米 MiMo 的语音档，**直连上游、不走中台身份**，只认 `MIMO_API_KEY` 环境变量。
+中台的出音链路（`media_type=audio` 的路由与落盘）还没接完，而这批能力目前内部用——
+没有那把 key 的人（包括租户）用不了，所以不需要额外做权限控制。
+
+- `speak <text>`：文字转语音，输出 24kHz / 16bit 单声道 WAV，stdout 只打印文件路径。
+  三种音色来源，给哪个参数走哪条：默认预置音色（`--voice`，默认 Chloe）、
+  `--design` 一句话描述当场造一个、`--clone <file>` 拿一段音频克隆它的音色。
+  `--instruction` 可叠加语气/风格指令。
+- `transcribe <audio>`：语音转文字，stdout 只打印识别结果。
+
+协议上有四个反直觉的点，都写进了 `src/mimo-speech.ts` 的文件头（实测踩出来的，写错不报错、
+只是拿不到音频）：合成不走 `/v1/audio/speech`（OpenAI 那套音频端点全 404，四种能力共用
+`/v1/chat/completions`）；**待合成文本要放 assistant 角色**，放 user 会得到一段「回答」而不是朗读；
+音频是 base64 回在 `message.audio.data`；识别的输入音频在 user 的 content 数组里且要裸 base64。
+
+### 已知限制
+
+**识别结果的同音字会飘。** 同一段合成音频，一次识别成「声影成诗，一念成相」，另一次成
+「上庸城失，一面呈象」。CLI 会在 stderr 提醒，但不要把它的输出直接用在计费、入库或需要
+精确匹配的判断上。
+
 ## 2.5.0 (2026-08-17)
 
 ### 修复

package/README.md

@@ -102,9 +102,14 @@
 | | 抠图去背景（输出透明 PNG） | `remove-bg` |
 | | **放大清晰度**（2M → 10M+ 级） | `upscale` |
 | | 去水印 | `remove-watermark` |
+| **语音**（直连小米 MiMo，需 `MIMO_API_KEY`） | 文字转语音 / 音色设计 / 音色克隆 | `speak` |
+| | 语音转文字 | `transcribe` |
 | **素材与统计** | 上传素材 / 查任务 / 查余额 / 查模型 / 查身份 | `upload` / `jobs` / `balance` / `models` / `whoami` |
 
 > 本地工具（`compress` / `remove-bg` / `upscale` / `remove-watermark`）**不用登录、不花一分钱**，装了就能用；其余命令需要一个凭证（个人 `login` 或租户 apiKey）。
+>
+> 语音（`speak` / `transcribe`）是第三种情况：**不走中台身份**，直连小米 MiMo，只认 `MIMO_API_KEY` 环境变量。
+> 中台的出音链路还没接完，这批能力目前内部用，没有那把 key 的人（包括租户）用不了。
 
 ---
 
@@ -328,6 +333,48 @@ museav gen --template "$ID" --fields '{"title":"新的主标题"}'
 - **降级不是失败**：文字层逆向 / 变量化 / 建模板任一步出问题，读图结果（SCULPT、prompt）照常给你，
   只是没有模具。命令会明确告诉你卡在哪一步。
 
+### 文字转语音 `speak` / 语音转文字 `transcribe`
+
+直连小米 MiMo，**不用 `museav login`**，只要一个环境变量：
+
+```bash
+export MIMO_API_KEY=...
+# 或者不落盘，用密钥库注入一次性子进程
+cs kyvault run --env MIMO_API_KEY=secret://mimo/api-key -- museav speak '声影成诗'
+```
+
+三种音色来源，给了哪个参数就走哪条路：
+
+```bash
+# 预置音色（默认 Chloe）
+museav speak '声影成诗，一念成像。' --out hello.wav
+
+# 音色设计：一句话描述，当场造一个音色
+museav speak '欢迎收听山鬼电台' --design '低沉沙哑的中年男声，像深夜电台'
+
+# 音色克隆：拿一段音频当样本，复刻它的音色
+museav speak '这句换个音色来念' --clone ./sample.wav
+
+# 语气/风格指令，三种模式都能叠加
+museav speak '慢一点念这句' --instruction '语速放慢，温柔一些'
+```
+
+输出是 24kHz / 16bit 单声道 WAV，stdout 只打印文件路径（方便直接接管道）：
+
+```bash
+museav upload "$(museav speak '开场白')"      # 合成完直接上传到中台图库
+```
+
+语音转文字：
+
+```bash
+museav transcribe ./recording.wav             # stdout 只有识别出的文本
+```
+
+> ⚠️ **识别结果的同音字会飘。** 同一段合成音频，一次识别成「声影成诗，一念成相」，
+> 另一次成「上庸城失，一面呈象」。别把它的输出直接用在计费、入库或需要精确匹配的判断上，
+> 重要场景请人工核对一遍。
+
 ### 上传素材 `upload`
 
 图片、音频、视频都能传，中台按**文件字节内容**判类型（不看扩展名，也不信客户端声明的 MIME），
@@ -345,6 +392,20 @@ museav upload face.png
 > `gen --ref` / `gen --video --image` 内部已经自动帮你上传了，不需要先手动跑一次 `upload`。
 > 单独用 `upload` 的场景是：同一张垫图要复用多次，或者你想把 URL 存下来给别的系统用。
 
+**把外面做好的成品收进账户**：加 `--to-works`。
+
+```bash
+museav upload my-clip.mp4 --to-works                    # 收进「我的作品」
+museav upload my-clip.mp4 --to-works --workspace <id>   # 顺便归档到某个项目
+```
+
+区别在于**落不落库**：默认只把文件存进图库、回一个直链（参考图就该这样，它是原料不是成品）；
+加了 `--to-works` 会额外记一条作品，这样它才会出现在网页的「我的作品」、后台画廊和项目归档里。
+不加的话文件只存在存储桶里，界面上哪儿都找不到它。
+
+只对**账户身份**生效（`museav login` 或账户 Key）：作品要归到具体某个人头上，
+租户 Key 没有具体的人，中台会忽略这个参数，CLI 也会明确告诉你没记成作品。
+
 ### 本地图像工具 `compress` / `remove-bg`
 
 纯本地、免登录、不消耗中台额度，macOS / Windows / Linux 通用（依赖全走 npm 预编译，无平台特化代码）：

package/dist/client.d.ts

@@ -277,8 +277,13 @@ export interface ModelOption {
     description?: string;
 }
 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;
@@ -332,6 +337,18 @@ export declare class StudioClient {
     createTemplate(input: CreateTemplateInput): Promise<TemplateOption>;
     /** 新建视频模板。归属同图片模板：租户 apiKey 自动归租户，平台管理员归平台共享 */
     createVideoTemplate(input: CreateVideoTemplateInput): Promise<TemplateOption>;
+    /** 贴图素材清单（租户级资产，服务端已按调用者权限过滤）。PNG 装饰图，叠加在海报/封面上 */
+    stickers(): Promise<any[]>;
+    /** 上传贴图素材（不压缩——透明 PNG 压缩会破坏透明通道） */
+    createSticker(filePath: string, name: string): Promise<any>;
+    /** 删除贴图素材 */
+    deleteSticker(id: string): Promise<void>;
+    /** 版式模板清单（租户级资产）：封面底图 + 固定描述（{城市}{明星} 占位符） */
+    posterTemplates(): Promise<any[]>;
+    /** 上传版式模板（不压缩，保留封面底图原样） */
+    createPosterTemplate(filePath: string, name: string, prompt: string): Promise<any>;
+    /** 删除版式模板 */
+    deletePosterTemplate(id: string): Promise<void>;
     /** 提交出图任务，立即返回 jobId */
     generate(opts: GenerateOptions): Promise<{
         jobId: string;
@@ -418,10 +435,21 @@ export declare class StudioClient {
      * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
      * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
      */
-    uploadRef(filePath: string): Promise<{
+    /**
+     * 上传素材。默认只存文件、回直链（参考图/垫图就该这样）。
+     *
+     * asWork=true 时另外记一条作品：不落库的话文件只存在 R2 里，
+     * 作品页、后台画廊、项目归档全都看不见它 —— 「传到我的账户」就没发生。
+     * 只对账户身份生效（作品要归到具体某个人头上），租户 key 传了也会被中台忽略。
+     */
+    uploadRef(filePath: string, opts?: {
+        asWork?: boolean;
+        workspaceId?: string;
+    }): Promise<{
         url: string;
         media_type?: string;
         mime?: string;
+        job_id?: string | null;
     }>;
     /**
      * 图片转模板（POST /api/image-to-template）：一张图 → 一个可复用的图片模板。

package/dist/client.js

@@ -125,6 +125,41 @@ export class StudioClient {
         });
         return r.row;
     }
+    /** 贴图素材清单（租户级资产，服务端已按调用者权限过滤）。PNG 装饰图，叠加在海报/封面上 */
+    async stickers() {
+        const r = await this.request('stickers');
+        return Array.isArray(r) ? r : [];
+    }
+    /** 上传贴图素材（不压缩——透明 PNG 压缩会破坏透明通道） */
+    async createSticker(filePath, name) {
+        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) {
+        await this.request(`stickers?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
+    /** 版式模板清单（租户级资产）：封面底图 + 固定描述（{城市}{明星} 占位符） */
+    async posterTemplates() {
+        const r = await this.request('poster-templates');
+        return Array.isArray(r) ? r : [];
+    }
+    /** 上传版式模板（不压缩，保留封面底图原样） */
+    async createPosterTemplate(filePath, name, prompt) {
+        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) {
+        await this.request(`poster-templates?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
     /** 提交出图任务，立即返回 jobId */
     async generate(opts) {
         // prompt / skill_slug / template_id 三选一：都传时服务端按 prompt > template_id > skill_slug
@@ -310,9 +345,21 @@ export class StudioClient {
      * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
      * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
      */
-    async uploadRef(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 };
+    /**
+     * 上传素材。默认只存文件、回直链（参考图/垫图就该这样）。
+     *
+     * asWork=true 时另外记一条作品：不落库的话文件只存在 R2 里，
+     * 作品页、后台画廊、项目归档全都看不见它 —— 「传到我的账户」就没发生。
+     * 只对账户身份生效（作品要归到具体某个人头上），租户 key 传了也会被中台忽略。
+     */
+    async uploadRef(filePath, opts = {}) {
+        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 };
     }
     /**
      * 图片转模板（POST /api/image-to-template）：一张图 → 一个可复用的图片模板。

package/dist/commands/balance.js

@@ -1,7 +1,10 @@
 export async function balance(client) {
     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)

package/dist/commands/img-tools.js

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

package/dist/commands/poster-templates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * museav poster-templates —— 版式模板库（租户级资产）。
+ *  封面底图 + 固定描述（{城市} {明星} 占位符），选版式时把城市/明星名填进底图。
+ *  学员做的封面版式保存后全租户共享。
+ */
+import type { StudioClient } from '../client.js';
+export declare function posterTemplates(client: StudioClient): Promise<void>;
+export declare function createPosterTemplate(client: StudioClient, filePath: string, opts: {
+    name: string;
+    prompt: string;
+}): Promise<void>;

package/dist/commands/poster-templates.js

@@ -0,0 +1,23 @@
+export async function posterTemplates(client) {
+    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, filePath, opts) {
+    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/dist/commands/speak.d.ts

@@ -0,0 +1,9 @@
+export interface SpeakCliOptions {
+    out?: string;
+    voice?: string;
+    design?: string;
+    clone?: string;
+    instruction?: string;
+}
+export declare function speak(text: string, opts?: SpeakCliOptions): Promise<void>;
+export declare function transcribeCmd(audioPath: string): Promise<void>;

package/dist/commands/speak.js

@@ -0,0 +1,41 @@
+/**
+ * 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: '音色克隆' };
+export async function speak(text, opts = {}) {
+    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) {
+    process.stderr.write(`识别中 ${audioPath} ...\n`);
+    const text = await transcribe(audioPath);
+    // 质量有波动（见 mimo-speech.ts 的注释），提醒一句，但不影响 stdout 的机器可读性
+    process.stderr.write('✅ 识别完成（同音字可能有误，重要场景请核对）\n');
+    console.log(text);
+}

package/dist/commands/stickers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * museav stickers —— 贴图素材库（租户级资产）。
+ *  PNG 透明装饰图（logo/花纹/边框），叠加在海报/封面上。
+ *  列出的都是自己租户的贴图；上传用账户 Key 或租户 Key 均可（落到本租户）。
+ */
+import type { StudioClient } from '../client.js';
+export declare function stickers(client: StudioClient): Promise<void>;
+export declare function createSticker(client: StudioClient, filePath: string, opts: {
+    name: string;
+}): Promise<void>;

package/dist/commands/stickers.js

@@ -0,0 +1,22 @@
+export async function stickers(client) {
+    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, filePath, opts) {
+    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/dist/commands/upload.d.ts

@@ -6,4 +6,7 @@
  * 拿到的 URL 可以直接喂给 gen --ref / gen --video --image，也能给 reverse 当图片 URL。
  */
 import type { StudioClient } from '../client.js';
-export declare function upload(client: StudioClient, filePath: string): Promise<void>;
+export declare function upload(client: StudioClient, filePath: string, opts?: {
+    toWorks?: boolean;
+    workspace?: string;
+}): Promise<void>;

package/dist/commands/upload.js

@@ -1,8 +1,21 @@
 const KIND_LABEL = { image: '图片', audio: '音频', video: '视频' };
-export async function upload(client, filePath) {
+export async function upload(client, filePath, opts = {}) {
     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/dist/compress.js

@@ -47,6 +47,14 @@ export async function compressForVision(filePath) {
         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 认识的图（视频/音频）→ 原样传
     }
     const longEdge = Math.max(meta.width || 0, meta.height || 0);

package/dist/index.js

@@ -28,6 +28,9 @@ import { jobs } from './commands/jobs.js';
 import { whoami } from './commands/whoami.js';
 import { products } from './commands/products.js';
 import { assets } from './commands/assets.js';
+import { stickers, createSticker } from './commands/stickers.js';
+import { posterTemplates, createPosterTemplate } from './commands/poster-templates.js';
+import { speak, transcribeCmd } from './commands/speak.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 // 每 12 小时最多查一次 npm registry，过期才提示，不拖慢日常调用
 updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 12 }).notify({ defer: false });
@@ -179,9 +182,9 @@ program
     .action(asyncRun((input, opts) => compressCmd(input, opts)));
 program
     .command('remove-bg <file>')
-    .description('本地抠图去背景（ISNet/U2Net + onnxruntime，免登录）：输出带 alpha 的 PNG。首次使用自动下载模型（~170MB，缓存 ~/.museav-models）')
+    .description('本地抠图去背景（BiRefNet/ISNet/U2Net + onnxruntime，免登录）：输出带 alpha 的 PNG。首次使用自动下载模型（缓存 ~/.museav-models）')
     .option('--out <path>', '输出路径（默认 <名>-nobg.png）')
-    .option('--model <name>', 'isnet（默认，质量优先）/ u2net')
+    .option('--model <name>', 'birefnet（默认，细节最好，~214MB）/ isnet / u2net')
     .option('--overwrite', '允许覆盖已存在的输出文件')
     .action(asyncRun((input, opts) => removeBgCmd(input, opts)));
 program
@@ -247,7 +250,22 @@ program
 program
     .command('upload <file>')
     .description('上传素材（图片/音频/视频，按字节内容判类型；图片 8MB / 音频 20MB / 视频 50MB），stdout 输出公网直链')
-    .action(withClient((client, file) => upload(client, file)));
+    .option('--to-works', '同时收进「我的作品」（在外面做好的成品视频/图片用这个；参考图不用）')
+    .option('--workspace <id>', '归档到指定项目')
+    .action(withClient((client, file, opts) => upload(client, file, { toWorks: opts.toWorks, workspace: opts.workspace })));
+program
+    .command('speak <text>')
+    .description('文本转语音（小米 MiMo，直连上游需 MIMO_API_KEY，不走中台身份）：stdout 输出 wav 路径')
+    .option('--out <path>', '输出路径（默认 speech-<时间戳>.wav）')
+    .option('--voice <name>', '预置音色，默认 Chloe')
+    .option('--design <desc>', '一句话描述音色，当场造一个（如「低沉沙哑的中年男声」）')
+    .option('--clone <file>', '拿这段音频当样本，克隆它的音色')
+    .option('--instruction <text>', '语气/风格指令（三种模式都可用）')
+    .action(asyncRun((text, opts) => speak(text, opts)));
+program
+    .command('transcribe <audio>')
+    .description('语音转文本（小米 MiMo，需 MIMO_API_KEY）：stdout 输出识别结果。同音字可能有误，重要场景请核对')
+    .action(asyncRun((audio) => transcribeCmd(audio)));
 program
     .command('models')
     .description('查可用模型列表')
@@ -299,6 +317,25 @@ templatesCmd
     .option('--fields <json>', '占位符字段说明，JSON 数组，如 \'[{"key":"artist","label":"艺人名"}]\'；不传则自动从 --prompt 里的 {key} 提取')
     .option('--type <type>', '模板类型：image（图片，默认） / article（文字）')
     .action(withClient((client, opts) => createTemplate(client, opts)));
+const stickersCmd = program
+    .command('stickers')
+    .description('查贴图素材库（租户级资产：PNG 装饰图，叠加在海报/封面上）')
+    .action(withClient((client) => stickers(client)));
+stickersCmd
+    .command('add <file>')
+    .description('上传贴图素材（PNG 透明装饰图，不压缩保留透明通道）')
+    .requiredOption('--name <名称>', '贴图名称')
+    .action(withClient((client, file, opts) => createSticker(client, file, opts)));
+const posterTemplatesCmd = program
+    .command('poster-templates')
+    .description('查版式模板库（租户级资产：封面底图 + 固定描述，选版式把城市/明星名填进底图）')
+    .action(withClient((client) => posterTemplates(client)));
+posterTemplatesCmd
+    .command('add <file>')
+    .description('保存版式模板（封面底图 + 描述，描述里用 {城市} {明星} 占位）')
+    .requiredOption('--name <名称>', '版式名称')
+    .requiredOption('--prompt <描述>', '版式固定描述，{城市} {明星} 会自动替换')
+    .action(withClient((client, file, opts) => createPosterTemplate(client, file, opts)));
 program
     .command('products')
     .description('查所属租户自己的产品目录（数据在租户自己的后台，不在 Studio 中台；只支持已开通该接口的租户，仅租户 apiKey 身份可用）')

package/dist/local-bg.d.ts

@@ -1,13 +1,36 @@
+/**
+ * 每个模型的输入尺寸与归一化参数**都不一样**，必须随模型带着走。
+ * 取值对齐 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 declare const BG_MODELS: {
     readonly isnet: {
         readonly file: 'isnet-general-use.onnx';
         readonly url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/isnet-general-use.onnx';
         readonly label: 'ISNet（通用，质量优先）';
+        readonly edge: 1024;
+        readonly mean: readonly [0.5, 0.5, 0.5];
+        readonly std: readonly [1, 1, 1];
     };
     readonly u2net: {
         readonly file: 'u2net.onnx';
         readonly url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net.onnx';
         readonly label: 'U2Net（经典通用）';
+        readonly edge: 320;
+        readonly mean: readonly [0.485, 0.456, 0.406];
+        readonly std: readonly [0.229, 0.224, 0.225];
+    };
+    readonly birefnet: {
+        readonly file: 'birefnet-general-lite.onnx';
+        readonly url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/BiRefNet-general-bb_swin_v1_tiny-epoch_232.onnx';
+        readonly label: 'BiRefNet-Lite（细节最好，毛发/低对比度主体优先用它）';
+        readonly edge: 1024;
+        readonly mean: readonly [0.485, 0.456, 0.406];
+        readonly std: readonly [0.229, 0.224, 0.225];
+        readonly sigmoid: true;
+        readonly size: 214;
     };
 };
 export type BgModelKey = keyof typeof BG_MODELS;