museav-cli 2.2.0 → 2.4.0

package/src/commands/jobs.ts

@@ -5,6 +5,7 @@
  * 不需要额外传租户/用户 id——你拿的是谁的凭证，就是谁的数据。
  */
 import type { StudioClient, Job } from '../client.js'
+import { resolveWorkspace } from './projects.js'
 
 const STATUS_MARK: Record<Job['status'], string> = {
   pending: '⏳',
@@ -13,9 +14,14 @@ const STATUS_MARK: Record<Job['status'], string> = {
   failed: '❌',
 }
 
-export async function jobs(client: StudioClient, opts: { limit?: string; status?: Job['status'] }): Promise<void> {
+export async function jobs(client: StudioClient, opts: { limit?: string; status?: Job['status']; project?: string }): Promise<void> {
   const limit = opts.limit ? Number(opts.limit) : 20
-  const list = await client.listJobs({ limit, status: opts.status })
+  let list = await client.listJobs({ limit, status: opts.status })
+  // --project 客户端过滤：服务端 jobs 不认 workspace 参数，在最近 50 条内筛
+  if (opts.project) {
+    const ws = await resolveWorkspace(client, opts.project)
+    list = list.filter((j) => (j as unknown as { workspace_id?: string | null }).workspace_id === ws.id)
+  }
 
   if (!list.length) {
     process.stderr.write('没有找到工作流记录\n')

package/src/commands/projects.ts

@@ -0,0 +1,80 @@
+/** museav projects —— 工作区（项目）与项目素材库。
+ *  层级：平台 → 账户 → 工作区；素材挂工作区，业务隔离互不污染。
+ *  「人像库的工作区出模特图、产品库的工作区出电商图」的载体就是这里。 */
+import type { StudioClient, Workspace } from '../client.js'
+
+/** --project <id|名> 的解析：id 精确命中，否则按名称匹配；找不到/歧义时把可选项列出来 */
+export async function resolveWorkspace(client: StudioClient, idOrName: string): Promise<Workspace> {
+  const list = await client.workspaces()
+  const key = String(idOrName || '').trim()
+  if (!key) throw new Error('缺少 --project（工作区 id 或名称）')
+  const byId = list.find((w) => w.id === key)
+  if (byId) return byId
+  const byName = list.filter((w) => w.name === key)
+  if (byName.length === 1) return byName[0]
+  if (byName.length > 1) throw new Error(`重名工作区「${key}」，请用 id 指定：\n${list.map((w) => `  ${w.id}  ${w.name}`).join('\n')}`)
+  throw new Error(`没有工作区「${key}」。现有：\n${list.map((w) => `  ${w.id}  ${w.name}`).join('\n')}\n（museav projects create --name 可新建）`)
+}
+
+export async function projects(client: StudioClient): Promise<void> {
+  const list = await client.workspaces()
+  if (!list.length) {
+    process.stderr.write('还没有工作区（museav projects create --name 新建）\n')
+    return
+  }
+  process.stderr.write(`工作区（${list.length} 个）:\n`)
+  for (const w of list) {
+    process.stderr.write(
+      `  ${w.id}  ${w.name.padEnd(16)} 出图 ${w.gen_done ?? 0}/${w.gen_total ?? 0}${w.brand ? `  brand:${w.brand}` : ''}\n`,
+    )
+  }
+  process.stderr.write(`\n素材库: museav projects assets --project <id|名>\n出图归档: museav gen --project <id|名> ...\n`)
+  // stdout 只出 id，便于脚本解析
+  console.log(list.map((w) => w.id).join('\n'))
+}
+
+export async function createProject(client: StudioClient, opts: { name: string }): Promise<void> {
+  const name = (opts.name || '').trim()
+  if (!name) throw new Error('--name 必填')
+  const row = await client.createWorkspace(name)
+  process.stderr.write(`✅ 工作区已建：${row.id}  ${row.name}\n`)
+  process.stderr.write(`传素材: museav projects assets add <file> --project ${row.id}\n`)
+  console.log(row.id)
+}
+
+export async function listAssets(client: StudioClient, opts: { project?: string }): Promise<void> {
+  const ws = await resolveWorkspace(client, opts.project || '')
+  const assets = await client.workspaceAssets(ws.id)
+  process.stderr.write(`「${ws.name}」素材库（${assets.length} 条）:\n`)
+  for (const a of assets) {
+    const tag = a.tags?.length ? `[${a.tags.join(',')}]` : ''
+    process.stderr.write(`  ${a.id}  ${(a.name || '(未命名)').padEnd(16)} ${a.media_type.padEnd(5)} ${tag}\n`)
+    process.stderr.write(`    ${a.cdn_url}\n`)
+  }
+  process.stderr.write(`\n垫图出图: museav gen --project ${ws.id} --ref <素材URL> --prompt '...'\n`)
+  // stdout：id<TAB>url 每行一条，agent 拿去直接当 --ref 用
+  console.log(assets.map((a) => `${a.id}\t${a.cdn_url}`).join('\n'))
+}
+
+export async function addAsset(
+  client: StudioClient,
+  file: string,
+  opts: { project?: string; name?: string; tag?: string[] },
+): Promise<void> {
+  const ws = await resolveWorkspace(client, opts.project || '')
+  const row = await client.addWorkspaceAsset({
+    file,
+    workspaceId: ws.id,
+    name: opts.name,
+    tags: opts.tag || [],
+  })
+  process.stderr.write(`✅ 已入「${ws.name}」素材库：${row.name || '(未命名)'}  ${row.media_type}\n`)
+  process.stderr.write(`${row.cdn_url}\n`)
+  console.log(row.cdn_url)
+}
+
+export async function removeAsset(client: StudioClient, opts: { id: string }): Promise<void> {
+  await client.deleteWorkspaceAsset(opts.id)
+  process.stderr.write(`✅ 素材已删：${opts.id}\n`)
+  console.log(opts.id)
+}

package/src/commands/reverse.ts

@@ -1,18 +1,19 @@
 /** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt）。
- *  主路是本地 Ollama（qwen3-vl），快、零成本、无需登录；中台 API 是回落路，走回落时会明确提示较慢。
- *  client 懒构造（getClient）：本地路成功就完全不碰中台凭证。
- *  本地系统的 AI 能力统一收口在这个 CLI，reverse 是第一个本地化的能力。 */
+ *  默认走中台 API（快、稳定、不需本地模型）；--local 可切本地 Ollama（需自备 qwen3-vl，
+ *  仅在用户显式要求时使用——本地大模型默认不拉起，不给用户的内存添负担）。
+ *  client 懒构造：本地路成功就完全不碰中台凭证。 */
 import type { StudioClient, ReverseResult } from '../client.js'
 import { checkLocalVlm, reverseLocally, LOCAL_VLM_MODEL } from '../local-vision.js'
 
 export async function reverse(
   getClient: () => StudioClient,
   input: string,
-  opts: { api?: boolean } = {},
+  opts: { api?: boolean; local?: boolean } = {},
 ): Promise<void> {
   const isUrl = /^https?:\/\//.test(input)
 
-  if (!opts.api && !isUrl) {
+  // 本地路只在用户显式 --local 且输入是本地文件时尝试；服务不可用给出指引后回落 API
+  if (opts.local && !isUrl) {
     const status = await checkLocalVlm()
     if (status.running && status.modelPresent) {
       try {
@@ -27,7 +28,7 @@ export async function reverse(
     } else {
       process.stderr.write(`⚠ 本地读图不可用（${status.reason}），回落中台 API —— 速度较慢，请耐心等待\n`)
     }
-  } else if (!opts.api && isUrl) {
+  } else if (opts.local && isUrl) {
     process.stderr.write(`ℹ URL 输入走中台 API（本地路只收文件路径）\n`)
   }
 

package/src/index.ts

@@ -15,6 +15,8 @@ import { bindFeishu } from './commands/bind-feishu.js'
 import { printWelcome } from './commands/welcome.js'
 import { gen } from './commands/gen.js'
 import { reverse } from './commands/reverse.js'
+import { compressCmd, removeBgCmd, upscaleCmd, removeWatermarkCmd } from './commands/img-tools.js'
+import { projects, createProject, listAssets, addAsset, removeAsset, resolveWorkspace } from './commands/projects.js'
 import { imageToTemplate } from './commands/image-to-template.js'
 import { upload } from './commands/upload.js'
 import { models } from './commands/models.js'
@@ -109,6 +111,18 @@ function withLazyClient(fn: (getClient: () => StudioClient, ...args: any[]) => P
   }
 }
 
+// 本地命令（compress / remove-bg 等）：不碰中台、不需要任何凭证，只包一层统一的错误出口
+function asyncRun(fn: (...args: any[]) => Promise<any>) {
+  return async (...args: any[]) => {
+    try {
+      await fn(...args)
+    } catch (e) {
+      process.stderr.write(`❌ ${(e as Error).message}\n`)
+      process.exit(1)
+    }
+  }
+}
+
 // products / assets 查的是租户自己后台的数据，不是 Studio 中台的，走独立的 TenantClient
 // （见 tenant-client.ts 顶部注释），只支持租户 apiKey 身份，不支持个人 login token。
 function withTenantClient<T extends (...args: any[]) => Promise<any>>(fn: T) {
@@ -155,12 +169,83 @@ program
   .option('--video', '生成视频（走 /api/videos 链路；模型档次如 artsdance-2-0-pro-260801，不传 --model 走 auto 路由）')
   .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
   .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')
+  .option('--project <id|名>', '归档进该工作区（museav projects 查；账户身份才生效）')
   .action(withClient((client: StudioClient, opts: any) => gen(client, opts)))
 
+program
+  .command('compress <file>')
+  .description('本地压缩图片（sharp，免登录）：默认同目录 <名>-min.<格式>，不覆写原文件')
+  .option('--out <path>', '输出路径（默认 <名>-min.<格式>）')
+  .option('--max-edge <px>', '最长边缩到该像素（等比，inside）')
+  .option('--quality <1-100>', 'jpg/webp 质量，默认 82')
+  .option('--format <fmt>', '输出格式 jpg / png / webp（默认跟随原格式）')
+  .option('--overwrite', '允许覆盖已存在的输出文件')
+  .action(asyncRun((input: string, opts: any) => compressCmd(input, opts)))
+
+program
+  .command('remove-bg <file>')
+  .description('本地抠图去背景（ISNet/U2Net + onnxruntime，免登录）：输出带 alpha 的 PNG。首次使用自动下载模型（~170MB，缓存 ~/.museav-models）')
+  .option('--out <path>', '输出路径（默认 <名>-nobg.png）')
+  .option('--model <name>', 'isnet（默认，质量优先）/ u2net')
+  .option('--overwrite', '允许覆盖已存在的输出文件')
+  .action(asyncRun((input: string, opts: any) => removeBgCmd(input, opts)))
+
+program
+  .command('upscale <file>')
+  .description('本地超分放大（Real-ESRGAN + Vulkan GPU，免登录）：默认 4x 输出 PNG。首次使用自动下载引擎与模型（~65MB，缓存 ~/.museav-bin 与 ~/.museav-models）')
+  .option('--out <path>', '输出路径（默认 <名>-<N>x.png）')
+  .option('--scale <n>', '放大倍数 2 / 3 / 4，默认 4')
+  .option('--model <name>', 'realesrgan-x4plus（通用照片，默认）/ realesrgan-x4plus-anime（插画动漫）')
+  .option('--overwrite', '允许覆盖已存在的输出文件')
+  .action(asyncRun((input: string, opts: any) => upscaleCmd(input, opts)))
+
+program
+  .command('remove-watermark <file>')
+  .description('本地去水印（免登录）：纯像素启发式自动定位水印 → LaMa 掩码修复，零模型依赖。首次使用自动下载修复模型（~200MB）；复杂画面用 --mask 手工指定（白=去除区）')
+  .option('--out <path>', '输出路径（默认 <名>-clean.png）')
+  .option('--mask <file>', '手工掩码图（白色=要去除的区域），跳过自动定位')
+  .option('--overwrite', '允许覆盖已存在的输出文件')
+  .action(asyncRun((input: string, opts: any) => removeWatermarkCmd(input, opts)))
+
+// 工作区（项目）与项目素材库：平台 → 账户 → 工作区三层归属，素材挂工作区
+const projectsCmd = program
+  .command('projects')
+  .description('工作区（项目）管理：一个账户多个工作区，每个工作区有自己的素材库（人像库/产品库各管各的业务）')
+  .action(withClient((client: StudioClient) => projects(client)))
+
+projectsCmd
+  .command('create')
+  .description('新建工作区（每账户最多 5 个）')
+  .requiredOption('--name <name>', '工作区名称（最多 20 字）')
+  .action(withClient((client: StudioClient, opts: any) => createProject(client, opts)))
+
+const assetsCmd = projectsCmd
+  .command('assets')
+  .description('项目素材库：列出 / 上传 / 删除该工作区的素材（垫图母版，不压缩）')
+
+assetsCmd
+  .description('列工作区素材库')
+  .option('--project <id|名>', '工作区 id 或名称（必填，不传会明确报错）')
+  .action(withClient((client: StudioClient, opts: any) => listAssets(client, opts)))
+
+assetsCmd
+  .command('add <file>')
+  .description('上传素材进工作区素材库（图片/音频/视频，按字节判型；母版不压缩）')
+  .requiredOption('--project <id|名>', '工作区 id 或名称')
+  .option('--name <name>', '素材名，如「白T正面」')
+  .option('--tag <tag>', '标签，可重复（产品 / 人像 / 场景…）', (v: string, acc: string[]) => [...acc, v], [] as string[])
+  .action(withClient((client: StudioClient, file: string, opts: any) => addAsset(client, file, opts)))
+
+assetsCmd
+  .command('rm <id>')
+  .description('删除素材（硬删：R2 对象 + 记录）')
+  .action(withClient((client: StudioClient, id: string) => removeAsset(client, { id })))
+
 program
   .command('reverse <input>')
-  .description('读图：反推 SCULPT prompt，stdout 输出英文 prompt。主路本地 Ollama（qwen3-vl，快，无需登录）；本地不可用回落中台 API（会提示较慢）。只读图；要做成模板用 image-to-template')
-  .option('--api', '跳过本地 Ollama，强制走中台 API（慢，需登录）')
+  .description('读图：反推 SCULPT prompt，stdout 输出英文 prompt。默认走中台 API（需登录）；--local 显式切本地 Ollama（需自备 qwen3-vl）。只读图；要做成模板用 image-to-template')
+  .option('--api', '强制走中台 API（默认路径）')
+  .option('--local', '改用本地 Ollama 读图（需先 ollama pull qwen3-vl:8b；本地不可用时回落 API）')
   .action(withLazyClient((getClient: () => StudioClient, input: string, opts: any) => reverse(getClient, input, opts)))
 
 program
@@ -255,9 +340,10 @@ program
 
 program
   .command('jobs')
-  .description('查自己名下的出图工作流（个人 login 看自己的；租户 apiKey 看业务下全部）——服务端固定返回最近 50 条，limit/status 是本地过滤')
+  .description('查自己名下的出图工作流（个人 login 看自己的；租户 apiKey 看业务下全部）——服务端固定返回最近 50 条，limit/status/project 是本地过滤')
   .option('--limit <n>', '最多显示几条（在最近 50 条以内截取），默认 20', '20')
   .option('--status <status>', '按状态过滤: pending / processing / done / failed（本地过滤，不是服务端查询）')
+  .option('--project <id|名>', '只看归档进该工作区的任务（本地过滤）')
   .action(withClient((client: StudioClient, opts: any) => jobs(client, opts)))
 
 program

package/src/local-bg.ts

@@ -0,0 +1,142 @@
+/**
+ * 本地抠图（去背景）—— remove-bg 的核心实现。
+ * 模型走 ONNX（ISNet / U2Net，均 Apache-2.0），推理走 onnxruntime-node（MIT），
+ * 前后处理走 sharp —— 整条链路许可证干净（imgly 那个 npm 包是 AGPL，不进依赖），
+ * 且三个依赖在 macOS / Windows / Linux 都有预编译，无平台特化代码。
+ * 模型文件首次使用时下载到 ~/.museav-models/ 缓存（一次性 ~170MB）。
+ */
+import { mkdir, writeFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+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（通用，质量优先）',
+  },
+  u2net: {
+    file: 'u2net.onnx',
+    url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net.onnx',
+    label: 'U2Net（经典通用）',
+  },
+} 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)
+}
+
+/** 模型在位返回路径；不在则下载（流式，进度打 stderr）。下载失败抛 Error */
+export async function ensureBgModel(key: BgModelKey): Promise<string> {
+  const dest = modelPath(key)
+  try {
+    const s = await stat(dest)
+    if (s.size > 10_000_000) return dest // 正常模型都是百 MB 级；太小的文件视为残缺重下
+  } catch {
+    // 不存在，走下载
+  }
+  await mkdir(MODEL_DIR, { recursive: true })
+  const def = BG_MODELS[key]
+  process.stderr.write(`↓ 首次使用，下载 ${def.label}（~170MB，一次性，缓存到 ${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)
+  const chunks: Buffer[] = []
+  let got = 0
+  const reader = resp.body.getReader()
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    chunks.push(Buffer.from(value))
+    got += value.length
+    if (total) process.stderr.write(`  ${((got / total) * 100).toFixed(0)}%\r`)
+  }
+  process.stderr.write('\n')
+  const buf = Buffer.concat(chunks)
+  if (buf.length < 10_000_000) throw new Error('模型下载不完整，请重试')
+  await writeFile(dest, buf)
+  return dest
+}
+
+/** 抠图主流程：输入图片路径 → 输出带 alpha 的 PNG Buffer */
+export async function removeBackgroundLocal(inputPath: string, modelKey: BgModelKey): Promise<Buffer> {
+  // 动态加载：onnxruntime-node 是 optionalDependency，缺失时给安装指引而不是崩
+  let ort: typeof import('onnxruntime-node')
+  try {
+    ort = await import('onnxruntime-node')
+  } catch {
+    throw new Error('onnxruntime-node 不可用。重装 CLI 即可补上：npm install -g museav-cli')
+  }
+  const sharp = await loadSharpOrThrow()
+  const modelFile = await ensureBgModel(modelKey)
+  const session = await ort.InferenceSession.create(modelFile)
+
+  // ── 预处理：EXIF 转正、去 alpha、RGB raw ──
+  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 ──
+  const small = await sharp(rgb, { raw: { width: info.width, height: info.height, channels: 3 } })
+    .resize(INPUT_EDGE, INPUT_EDGE, { fit: 'fill' })
+    .raw()
+    .toBuffer()
+  const f32 = new Float32Array(3 * INPUT_EDGE * INPUT_EDGE)
+  const N = INPUT_EDGE * INPUT_EDGE
+  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
+  }
+  const feeds: Record<string, import('onnxruntime-node').Tensor> = {}
+  feeds[session.inputNames[0]] = new ort.Tensor('float32', f32, [1, 3, INPUT_EDGE, INPUT_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，再缩回原图尺寸 ──
+  let lo = Infinity
+  let hi = -Infinity
+  for (let i = 0; i < N; i++) {
+    const v = maskFlat[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' })
+    .raw()
+    .toBuffer()
+
+  // ── alpha 合成：直接构造 RGBA（alpha = mask），不依赖 composite 的混合语义 ──
+  const w = info.width
+  const h = info.height
+  const rgba = Buffer.alloc(w * h * 4)
+  for (let i = 0; i < w * h; i++) {
+    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]
+  }
+  return sharp(rgba, { raw: { width: w, height: h, channels: 4 } }).png().toBuffer()
+}
+
+async function loadSharpOrThrow(): Promise<any> {
+  try {
+    const m = await import('sharp')
+    const sharp = (m as any).default ?? m
+    // 造 1px 图跑通全链路：native binding 坏了在第一次真用时才炸，这里提前暴露
+    await sharp({ create: { width: 1, height: 1, channels: 3, background: '#000' } }).raw().toBuffer()
+    return sharp
+  } catch {
+    throw new Error('sharp 不可用。重装 CLI 即可补上：npm install -g museav-cli')
+  }
+}

package/src/local-upscale.ts

@@ -0,0 +1,123 @@
+/**
+ * 本地超分（放大）—— upscale 的核心实现。
+ * 引擎：upscayl-ncnn（Real-ESRGAN 的 ncnn/Vulkan 后端，AGPL-3.0 —— 它是独立进程
+ * 二进制而非链接进 npm 包，CLI 与之分发解耦，不构成合并作品；这与把 AGPL 代码
+ * 编进依赖是两回事）。
+ * 跨平台：macOS（universal）/ Windows / Linux 二进制都在 upscayl 官方 release；
+ * 解压统一走 `tar -xf`（Win10+/macOS/Linux 都自带 libarchive 版 tar，不依赖 unzip）；
+ * 二进制落地后 chmod +x（Windows 不需要）。全程 node:child_process execFile，零 shell。
+ */
+import { mkdir, writeFile, stat, chmod } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+const run = promisify(execFile)
+
+// 锁定已实测的版本（20251207-174704，macOS universal 实测可用），升级要重新过测试
+const UPSCAYL_TAG = '20251207-174704'
+const UPSCAYL_BASE = `https://github.com/upscayl/upscayl-ncnn/releases/download/${UPSCAYL_TAG}/upscayl-bin-${UPSCAYL_TAG}`
+// 模型从 Real-ESRGAN 官方 release 的 zip 里取（只取需要的两个，别拖全量）
+const MODEL_ZIP = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesrgan-ncnn-vulkan-20220424-macos.zip'
+
+export const UPSCALE_MODELS = {
+  'realesrgan-x4plus': { label: '通用照片（默认）' },
+  'realesrgan-x4plus-anime': { label: '插画/动漫' },
+} as const
+export type UpscaleModel = keyof typeof UPSCALE_MODELS
+
+const BIN_DIR = join(homedir(), '.museav-bin', 'upscayl')
+const MODEL_DIR = join(homedir(), '.museav-models')
+
+function platformAsset(): { zip: string; exe: string } {
+  if (process.platform === 'win32') return { zip: `${UPSCAYL_BASE}-windows.zip`, exe: 'upscayl-bin.exe' }
+  if (process.platform === 'darwin') return { zip: `${UPSCAYL_BASE}-macos.zip`, exe: 'upscayl-bin' }
+  return { zip: `${UPSCAYL_BASE}-linux.zip`, exe: 'upscayl-bin' }
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function download(url: string, dest: string, label: string): Promise<void> {
+  const resp = await fetch(url)
+  if (!resp.ok || !resp.body) throw new Error(`${label} 下载失败 HTTP ${resp.status}`)
+  const total = Number(resp.headers.get('content-length') || 0)
+  const chunks: Buffer[] = []
+  let got = 0
+  const reader = resp.body.getReader()
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    chunks.push(Buffer.from(value))
+    got += value.length
+    if (total) process.stderr.write(`  ${label} ${(got / 1048576).toFixed(1)}/${(total / 1048576).toFixed(0)}MB\r`)
+  }
+  process.stderr.write('\n')
+  await writeFile(dest, Buffer.concat(chunks))
+}
+
+/** 首次使用时准备好二进制与模型，返回 { exe, modelDir }。之后直接走缓存 */
+export async function ensureUpscaleRuntime(): Promise<{ exe: string; modelDir: string }> {
+  const { zip, exe } = platformAsset()
+  const exePath = join(BIN_DIR, exe)
+  const modelDir = join(MODEL_DIR, 'realesrgan')
+  const paramPath = join(modelDir, 'realesrgan-x4plus.param')
+
+  if (!(await exists(exePath))) {
+    await mkdir(BIN_DIR, { recursive: true })
+    const zipPath = join(BIN_DIR, `dl-${process.platform}.zip`)
+    process.stderr.write(`↓ 首次使用，下载超分引擎（~15MB，一次性，缓存到 ${BIN_DIR}）...\n`)
+    await download(zip, zipPath, '引擎')
+    // tar -xf 解压：Win10+/macOS/Linux 自带，比依赖 unzip 稳
+    await run('tar', ['-xf', zipPath, '-C', BIN_DIR], { windowsHide: true })
+    // zip 里是 upscayl-bin-<tag>-<os>/upscayl-bin，拍平到 BIN_DIR
+    const { readdir } = await import('node:fs/promises')
+    for (const entry of await readdir(BIN_DIR, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        const { rename, readdir: rd } = await import('node:fs/promises')
+        for (const f of await rd(join(BIN_DIR, entry.name))) {
+          await rename(join(BIN_DIR, entry.name, f), join(BIN_DIR, f))
+        }
+      }
+    }
+    if (process.platform !== 'win32') await chmod(exePath, 0o755)
+    if (!(await exists(exePath))) throw new Error(`解压后未找到 ${exe}，请检查 ${BIN_DIR}`)
+    const { unlink } = await import('node:fs/promises')
+    await unlink(zipPath).catch(() => {})
+  }
+
+  if (!(await exists(paramPath))) {
+    await mkdir(modelDir, { recursive: true })
+    const zipPath = join(MODEL_DIR, 'dl-models.zip')
+    process.stderr.write('↓ 首次使用，下载超分模型（~50MB，一次性）...\n')
+    await download(MODEL_ZIP, zipPath, '模型')
+    await run('tar', ['-xf', zipPath, '-C', MODEL_DIR, 'models/realesrgan-x4plus.param', 'models/realesrgan-x4plus.bin', 'models/realesrgan-x4plus-anime.param', 'models/realesrgan-x4plus-anime.bin'], { windowsHide: true })
+    const { rename, rm } = await import('node:fs/promises')
+    for (const f of ['realesrgan-x4plus.param', 'realesrgan-x4plus.bin', 'realesrgan-x4plus-anime.param', 'realesrgan-x4plus-anime.bin']) {
+      await rename(join(MODEL_DIR, 'models', f), join(modelDir, f)).catch(() => {})
+    }
+    await rm(join(MODEL_DIR, 'models'), { recursive: true, force: true }).catch(() => {})
+    await rm(zipPath, { force: true }).catch(() => {})
+    if (!(await exists(paramPath))) throw new Error(`模型解压失败，请检查 ${modelDir}`)
+  }
+
+  return { exe: exePath, modelDir }
+}
+
+/** 超分主流程：返回输出文件的字节数组由引擎直写磁盘，这里只负责调度 */
+export async function upscaleLocal(opts: {
+  input: string
+  output: string
+  scale: number
+  model: UpscaleModel
+}): Promise<void> {
+  const { exe, modelDir } = await ensureUpscaleRuntime()
+  // 不走 shell 拼接；路径原样传参，空格/中文路径都安全
+  await run(exe, ['-i', opts.input, '-o', opts.output, '-s', String(opts.scale), '-n', opts.model, '-m', modelDir], { windowsHide: true })
+}

package/src/local-vision.ts

@@ -28,6 +28,13 @@ export interface LocalVlmStatus {
   reason?: string
 }
 
+// 各系统启动 Ollama 的正确姿势不同，提示语跟着平台走（Windows 没有 brew）
+function ollamaStartHint(): string {
+  if (process.platform === 'win32') return '启动 Ollama 应用（开始菜单 / Ollama.exe），或命令行运行 ollama serve'
+  if (process.platform === 'darwin') return 'brew services start ollama，或 ollama serve'
+  return 'systemctl --user start ollama，或 ollama serve'
+}
+
 /** 探活 + 模型在位检查。3 秒探不通就是没起服务，不等推理超时才发现 */
 export async function checkLocalVlm(): Promise<LocalVlmStatus> {
   const host = ollamaHost()
@@ -43,7 +50,7 @@ export async function checkLocalVlm(): Promise<LocalVlmStatus> {
     }
     return { running: true, modelPresent: true, host }
   } catch {
-    return { running: false, modelPresent: false, host, reason: `Ollama 未运行（${host}），启动: ollama serve 或 brew services start ollama` }
+    return { running: false, modelPresent: false, host, reason: `Ollama 未运行（${host}），${ollamaStartHint()}` }
   }
 }