museav-cli 2.5.0 → 2.7.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,58 @@
 # Changelog
 
+## 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;
@@ -418,10 +423,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

@@ -310,9 +310,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/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/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,7 @@ 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 { 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 +180,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 +248,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('查可用模型列表')

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;

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;