museav-cli 2.5.0 → 2.7.0

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.7.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
@@ -624,9 +629,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/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/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 认识的图（视频/音频）→ 原样传
   }
 

package/src/index.ts

@@ -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')) as { name: string; version: string }
 // 每 12 小时最多查一次 npm registry，过期才提示，不拖慢日常调用
@@ -184,9 +185,9 @@ program
 
 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: string, opts: any) => removeBgCmd(input, opts)))
 
@@ -263,7 +264,25 @@ program
 program
   .command('upload <file>')
   .description('上传素材（图片/音频/视频，按字节内容判类型；图片 8MB / 音频 20MB / 视频 50MB），stdout 输出公网直链')
-  .action(withClient((client: StudioClient, file: string) => upload(client, file)))
+  .option('--to-works', '同时收进「我的作品」（在外面做好的成品视频/图片用这个；参考图不用）')
+  .option('--workspace <id>', '归档到指定项目')
+  .action(withClient((client: StudioClient, file: string, opts: { toWorks?: boolean; workspace?: string }) =>
+    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: string, opts: any) => speak(text, opts)))
+
+program
+  .command('transcribe <audio>')
+  .description('语音转文本（小米 MiMo，需 MIMO_API_KEY）：stdout 输出识别结果。同音字可能有误，重要场景请核对')
+  .action(asyncRun((audio: string) => transcribeCmd(audio)))
 
 program
   .command('models')

package/src/local-bg.ts

@@ -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）。
@@ -9,24 +9,48 @@ 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] as const,
+    std: [1.0, 1.0, 1.0] as const,
   },
   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] as const,
+    std: [0.229, 0.224, 0.225] as const,
+  },
+  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] as const,
+    std: [0.229, 0.224, 0.225] as const,
+    // BiRefNet 输出的是 logits，要先过 sigmoid 才是概率；ISNet/U2Net 的输出已经是 0-1 区间。
+    // 漏掉这步不会报错，只会得到一张几乎全是半透明的 mask。
+    sigmoid: true,
+    size: 214, // MB，下载提示用
   },
 } as const
 
 export type BgModelKey = keyof typeof BG_MODELS
 
 const MODEL_DIR = join(homedir(), '.museav-models')
-const INPUT_EDGE = 1024
 
 function modelPath(key: BgModelKey): string {
   return join(MODEL_DIR, BG_MODELS[key].file)
@@ -43,7 +67,8 @@ export async function ensureBgModel(key: BgModelKey): Promise<string> {
   }
   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}`)
   const total = Number(resp.headers.get('content-length') || 0)
@@ -81,40 +106,63 @@ export async function removeBackgroundLocal(inputPath: string, modelKey: BgModel
   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: Record<string, import('onnxruntime-node').Tensor> = {}
-  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 as Float32Array
   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) hi = v
   }
   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
@@ -124,7 +172,7 @@ export async function removeBackgroundLocal(inputPath: string, modelKey: BgModel
     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/src/mimo-speech.ts

@@ -0,0 +1,139 @@
+/**
+ * 小米 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',
+} as const
+
+/** 默认预置音色。上游没有「列出音色」的接口，这个是文档给出且实测可用的 */
+export const DEFAULT_VOICE = 'Chloe'
+
+export function mimoKey(): string {
+  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: unknown): Promise<any> {
+  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: any
+  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 interface SpeakOptions {
+  /** 预置音色名（默认 Chloe）。与 design / clonePath 互斥 */
+  voice?: string
+  /** 一句话描述音色 → 走音色设计 */
+  design?: string
+  /** 音色样本音频路径 → 走音色克隆 */
+  clonePath?: string
+  /** 风格/语气指令。三种模式都能用 */
+  instruction?: string
+}
+
+/** 合成的三种模式。asr 不在里面——它是识别，不由 speechMode 决定 */
+export type SpeechMode = 'tts' | 'design' | 'clone'
+
+/** 用哪种模式，取决于给了什么参数——克隆 > 设计 > 预置音色 */
+export function speechMode(opts: SpeakOptions): SpeechMode {
+  if (opts.clonePath) return 'clone'
+  if (opts.design) return 'design'
+  return 'tts'
+}
+
+/**
+ * 合成语音，返回 WAV 数据。
+ * @param text 要读出来的文本
+ */
+export async function synthesize(text: string, opts: SpeakOptions = {}): Promise<Buffer> {
+  const content = String(text || '').trim()
+  if (!content) throw new Error('要合成的文本是空的')
+
+  const mode = speechMode(opts)
+  const messages: Array<{ role: string; content: string }> = []
+  // 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: Record<string, string> = { format: 'wav' }
+  if (mode === 'clone') {
+    const buf = await readFile(opts.clonePath as string)
+    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: string): Promise<string> {
+  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: Buffer): number | null {
+  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
+}