museav-cli 2.3.0 → 2.4.1

package/dist/local-watermark.js

@@ -0,0 +1,312 @@
+/**
+ * 本地去水印 —— remove-watermark 的核心实现。
+ * 链路：纯像素启发式定位水印（零模型依赖，不占内存）→ LaMa 掩码修复 →
+ * 输出干净图。也可 --mask 手工给掩码（白=要去除的区域），跳过自动定位。
+ * 全本地、免登录、零成本；许可证均兼容（LaMa 模型 Apache-2.0，onnxruntime MIT）。
+ */
+import { mkdir, writeFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const LAMA_URLS = [
+    'https://huggingface.co/Carve/LaMa-ONNX/resolve/main/lama_fp32.onnx',
+    // 国内网络拉不动 HF 时的镜像（同一文件；镜像没缓存会回落直链，所以放第二位）
+    'https://hf-mirror.com/Carve/LaMa-ONNX/resolve/main/lama_fp32.onnx',
+];
+const LAMA_PATH = join(homedir(), '.museav-models', 'lama', 'lama_fp32.onnx');
+async function ensureLamaModel() {
+    try {
+        if ((await stat(LAMA_PATH)).size > 50_000_000)
+            return LAMA_PATH;
+    }
+    catch { /* 未下载 */ }
+    await mkdir(join(homedir(), '.museav-models', 'lama'), { recursive: true });
+    process.stderr.write('↓ 首次使用，下载 LaMa 修复模型（~200MB，一次性，缓存到 ~/.museav-models/lama）...\n');
+    let lastErr = null;
+    for (const url of LAMA_URLS) {
+        try {
+            const resp = await fetch(url, { redirect: 'follow' });
+            if (!resp.ok || !resp.body)
+                throw new Error(`HTTP ${resp.status}`);
+            const total = Number(resp.headers.get('content-length') || 0);
+            const chunks = [];
+            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 / 1048576).toFixed(0)}/${(total / 1048576).toFixed(0)}MB\r`);
+            }
+            process.stderr.write('\n');
+            const buf = Buffer.concat(chunks);
+            if (buf.length < 50_000_000)
+                throw new Error('下载不完整');
+            await writeFile(LAMA_PATH, buf);
+            return LAMA_PATH;
+        }
+        catch (e) {
+            lastErr = e;
+        }
+    }
+    throw new Error(`LaMa 模型下载失败（${lastErr instanceof Error ? lastErr.message : lastErr}），也可手动放到 ${LAMA_PATH}`);
+}
+/** LaMa 要求边长被 8 整除：右/下边缘复制填充，修完再裁回 */
+const pad8 = (n) => Math.ceil(n / 8) * 8;
+/**
+ * 纯像素启发式水印定位（零模型依赖）。
+ * 原理：半透明水印（角标/文字）是「低对比、高频、铺在大片区域的细碎纹理」，
+ * 把四角区域做中值模糊后与原图差分，叠字区会出现稳定的高差值像素团。
+ * 判定保守：角区差分像素占比在 [0.3%, 8%] 才算水印（太少=没叠字，
+ * 太多=画面本身纹理复杂，不硬修）；坐标 0-1000 归一化输出。
+ * 误检最坏是 LaMa 重绘一块（轻微损伤），另有 --mask 手工精确兜底。
+ */
+export async function detectWatermarkBoxes(imagePath) {
+    const sharpMod = await import('sharp');
+    const sharp = sharpMod.default ?? sharpMod;
+    const meta = await sharp(imagePath).rotate().metadata();
+    const W = meta.width || 0;
+    const H = meta.height || 0;
+    if (!W || !H)
+        throw new Error('读不到图片尺寸');
+    const corners = [
+        { x: 0, y: 0 },
+        { x: 1, y: 0 },
+        { x: 0, y: 1 },
+        { x: 1, y: 1 },
+    ];
+    const cw = Math.round(W * 0.35);
+    const ch = Math.round(H * 0.35);
+    const boxes = [];
+    for (const { x, y } of corners) {
+        const left = x ? W - cw : 0;
+        const top = y ? H - ch : 0;
+        const { data: orig } = await sharp(imagePath).rotate()
+            .extract({ left, top, width: cw, height: ch }).raw().toBuffer({ resolveWithObject: true });
+        const { data: blurred } = await sharp(imagePath).rotate()
+            .extract({ left, top, width: cw, height: ch })
+            .median(7)
+            .raw().toBuffer({ resolveWithObject: true });
+        // 差分 + 阈值；记录超阈值像素的 bbox
+        let cnt = 0;
+        let minX = Infinity, minY = Infinity, maxX = -1, maxY = -1;
+        for (let i = 0; i < cw * ch; i++) {
+            const dr = Math.abs(orig[i * 3] - blurred[i * 3]);
+            const dg = Math.abs(orig[i * 3 + 1] - blurred[i * 3 + 1]);
+            const db = Math.abs(orig[i * 3 + 2] - blurred[i * 3 + 2]);
+            if (dr + dg + db > 90) { // 每通道均值 >30
+                cnt++;
+                const px = i % cw;
+                const py = Math.floor(i / cw);
+                if (px < minX)
+                    minX = px;
+                if (px > maxX)
+                    maxX = px;
+                if (py < minY)
+                    minY = py;
+                if (py > maxY)
+                    maxY = py;
+            }
+        }
+        const ratio = cnt / (cw * ch);
+        if (ratio >= 0.003 && ratio <= 0.08 && maxX >= 0) {
+            // 像素 → 0-1000 归一化（带 2% 外扩）
+            const pad = 0.02;
+            const box = {
+                x1: Math.max(0, ((left + minX) / W) * 1000 - pad * 1000),
+                y1: Math.max(0, ((top + minY) / H) * 1000 - pad * 1000),
+                x2: Math.min(1000, ((left + maxX) / W) * 1000 + pad * 1000),
+                y2: Math.min(1000, ((top + maxY) / H) * 1000 + pad * 1000),
+            };
+            // 贴角锚定：水印通常贴着所在角的边沿（5% 容差）。背景装饰/纹理也常被差分命中，
+            // 但它们离角远——角标类水印的判据就是「贴角」，否则宁可不修。
+            const anchored = (x === 0 && y === 0 && box.x1 <= 50 && box.y1 <= 50) ||
+                (x === 1 && y === 0 && box.x2 >= 950 && box.y1 <= 50) ||
+                (x === 0 && y === 1 && box.x1 <= 50 && box.y2 >= 950) ||
+                (x === 1 && y === 1 && box.x2 >= 950 && box.y2 >= 950);
+            if (anchored)
+                boxes.push(box);
+        }
+    }
+    return boxes;
+}
+/** 掩码修复主流程：mask 白色=要去除（Buffer 或文件路径）；输出 PNG Buffer。
+ *  模型是固定 512×512 输入——整图缩进去会毁分辨率，所以按掩码连通域逐块处理：
+ *  裁出带边距的局部 → letterbox 进 512 修复 → 只把掩码内的像素贴回原图。 */
+export async function inpaintLocal(imagePath, mask) {
+    const ort = await import('onnxruntime-node');
+    const sharpMod = await import('sharp');
+    const sharp = sharpMod.default ?? sharpMod;
+    const modelFile = await ensureLamaModel();
+    const session = await ort.InferenceSession.create(modelFile);
+    const S = 512;
+    const { data: rgb, info } = await sharp(imagePath).rotate().removeAlpha().raw().toBuffer({ resolveWithObject: true });
+    const W = info.width;
+    const H = info.height;
+    const maskRaw = await sharp(mask).rotate().resize(W, H, { fit: 'fill' }).greyscale().raw().toBuffer();
+    // 连通域（在 1/4 采样上 BFS，够用）：返回像素坐标 bbox 列表
+    const boxes = connectedBoxes(maskRaw, W, H);
+    // 工作底图：逐块修复后叠回去
+    let out = rgb;
+    for (const box of boxes) {
+        // 边距：给修复模型一点上下文
+        const margin = Math.round(Math.max(box.w, box.h) * 0.35) + 16;
+        const x0 = Math.max(0, box.x - margin);
+        const y0 = Math.max(0, box.y - margin);
+        const x1 = Math.min(W, box.x + box.w + margin);
+        const y1 = Math.min(H, box.y + box.h + margin);
+        const cw = x1 - x0;
+        const ch = y1 - y0;
+        // letterbox 进 512×512（等比缩放居中，四周留黑）
+        const scale = Math.min(S / cw, S / ch);
+        const iw = Math.max(8, Math.round(cw * scale));
+        const ih = Math.max(8, Math.round(ch * scale));
+        const ox = Math.floor((S - iw) / 2);
+        const oy = Math.floor((S - ih) / 2);
+        const cropImg = await sharp(out, { raw: { width: W, height: H, channels: 3 } })
+            .extract({ left: x0, top: y0, width: cw, height: ch })
+            .resize(iw, ih, { fit: 'fill' })
+            .raw().toBuffer();
+        // ⚠ sharp 的坑：raw 1 通道经 extract→resize 会悄悄变 3 通道（长度×3），
+        // 后面按 1 通道读全是错位数据。掩码管线一律 toColourspace('b-w') 强制单通道。
+        const cropMask = await sharp(maskRaw, { raw: { width: W, height: H, channels: 1 } })
+            .extract({ left: x0, top: y0, width: cw, height: ch })
+            .resize(iw, ih, { fit: 'fill' })
+            .toColourspace('b-w')
+            .raw().toBuffer();
+        const imgC = Buffer.alloc(S * S * 3, 0);
+        const maskC = Buffer.alloc(S * S, 0);
+        for (let y = 0; y < ih; y++) {
+            for (let x = 0; x < iw; x++) {
+                const si = (y * iw + x) * 3;
+                const di = ((oy + y) * S + (ox + x)) * 3;
+                imgC[di] = cropImg[si];
+                imgC[di + 1] = cropImg[si + 1];
+                imgC[di + 2] = cropImg[si + 2];
+                maskC[(oy + y) * S + (ox + x)] = cropMask[y * iw + x] > 127 ? 1 : 0;
+            }
+        }
+        const N = S * S;
+        const imgF = new Float32Array(3 * N);
+        for (let i = 0; i < N; i++) {
+            imgF[i] = imgC[i * 3] / 255;
+            imgF[N + i] = imgC[i * 3 + 1] / 255;
+            imgF[2 * N + i] = imgC[i * 3 + 2] / 255;
+        }
+        const results = await session.run({
+            image: new ort.Tensor('float32', imgF, [1, 3, S, S]),
+            mask: new ort.Tensor('float32', new Float32Array(maskC), [1, 1, S, S]),
+        });
+        const o = results[session.outputNames[0]].data;
+        // 取回中心区域，缩回原尺寸
+        const back = Buffer.alloc(iw * ih * 3);
+        for (let y = 0; y < ih; y++) {
+            for (let x = 0; x < iw; x++) {
+                const so = ((oy + y) * S + (ox + x));
+                const di = (y * iw + x) * 3;
+                back[di] = clamp255(o[so]);
+                back[di + 1] = clamp255(o[N + so]);
+                back[di + 2] = clamp255(o[2 * N + so]);
+            }
+        }
+        const restoredFull = await sharp(back, { raw: { width: iw, height: ih, channels: 3 } })
+            .resize(cw, ch, { fit: 'fill' }).raw().toBuffer();
+        const maskFull = await sharp(cropMask, { raw: { width: iw, height: ih, channels: 1 } })
+            .resize(cw, ch, { fit: 'fill' })
+            .toColourspace('b-w')
+            .raw().toBuffer();
+        // 只把掩码内的像素贴回，其余保持原图（缩放往返会损伤未掩码区，不能整块覆盖）
+        const next = Buffer.from(out);
+        for (let i = 0; i < cw * ch; i++) {
+            if (maskFull[i] > 127) {
+                next[((y0 + Math.floor(i / cw)) * W + (x0 + (i % cw))) * 3] = restoredFull[i * 3];
+                next[(((y0 + Math.floor(i / cw)) * W + (x0 + (i % cw))) * 3) + 1] = restoredFull[i * 3 + 1];
+                next[(((y0 + Math.floor(i / cw)) * W + (x0 + (i % cw))) * 3) + 2] = restoredFull[i * 3 + 2];
+            }
+        }
+        out = next;
+        process.stderr.write(`  修复块 ${cw}x${ch} @(${x0},${y0}) 完成\n`);
+    }
+    return sharp(out, { raw: { width: W, height: H, channels: 3 } }).png().toBuffer();
+}
+const clamp255 = (v) => Math.max(0, Math.min(255, Math.round(v)));
+/** 掩码连通域 → 像素 bbox 列表。在 1/4 采样上网格 BFS，快且够准 */
+function connectedBoxes(mask, W, H) {
+    const step = 4;
+    const gw = Math.ceil(W / step);
+    const gh = Math.ceil(H / step);
+    const grid = new Uint8Array(gw * gh);
+    for (let gy = 0; gy < gh; gy++) {
+        for (let gx = 0; gx < gw; gx++) {
+            let hit = false;
+            for (let dy = 0; dy < step && !hit; dy++) {
+                for (let dx = 0; dx < step && !hit; dx++) {
+                    const x = gx * step + dx;
+                    const y = gy * step + dy;
+                    if (x < W && y < H && mask[y * W + x] > 127)
+                        hit = true;
+                }
+            }
+            grid[gy * gw + gx] = hit ? 1 : 0;
+        }
+    }
+    const seen = new Uint8Array(gw * gh);
+    const boxes = [];
+    const q = [];
+    for (let g = 0; g < grid.length; g++) {
+        if (!grid[g] || seen[g])
+            continue;
+        q.length = 0;
+        q.push(g);
+        seen[g] = 1;
+        let minx = gw, miny = gh, maxx = -1, maxy = -1;
+        while (q.length) {
+            const cur = q.pop();
+            const cx = cur % gw;
+            const cy = Math.floor(cur / gw);
+            minx = Math.min(minx, cx);
+            maxx = Math.max(maxx, cx);
+            miny = Math.min(miny, cy);
+            maxy = Math.max(maxy, cy);
+            for (const [dx, dy] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+                const nx = cx + dx, ny = cy + dy;
+                if (nx < 0 || ny < 0 || nx >= gw || ny >= gh)
+                    continue;
+                const ni = ny * gw + nx;
+                if (grid[ni] && !seen[ni]) {
+                    seen[ni] = 1;
+                    q.push(ni);
+                }
+            }
+        }
+        boxes.push({ x: minx * step, y: miny * step, w: (maxx - minx + 1) * step, h: (maxy - miny + 1) * step });
+    }
+    return boxes;
+}
+/** 从检测框生成掩码 Buffer（框外扩 2%，白=去除区） */
+export async function maskFromBoxes(imagePath, boxes) {
+    const sharpMod = await import('sharp');
+    const sharp = sharpMod.default ?? sharpMod;
+    const meta = await sharp(imagePath).metadata();
+    const w = meta.width || 0;
+    const h = meta.height || 0;
+    if (!w || !h)
+        throw new Error('读不到图片尺寸');
+    // 坐标体系一次判清：全部 ≤1.5 视为 0-1 归一化，否则按 qwen 惯例的 0-1000
+    const all = boxes.flatMap((b) => [b.x1, b.y1, b.x2, b.y2]);
+    const denom = Math.max(...all) <= 1.5 ? 1 : 1000;
+    const svg = boxes
+        .map((b) => {
+        const pad = 0.02;
+        const x1 = Math.max(0, (b.x1 / denom) * w - w * pad);
+        const y1 = Math.max(0, (b.y1 / denom) * h - h * pad);
+        const x2 = Math.min(w, (b.x2 / denom) * w + w * pad);
+        const y2 = Math.min(h, (b.y2 / denom) * h + h * pad);
+        return `<rect x="${x1}" y="${y1}" width="${Math.max(1, x2 - x1)}" height="${Math.max(1, y2 - y1)}" fill="#fff"/>`;
+    })
+        .join('');
+    const maskSvg = Buffer.from(`<svg width="${w}" height="${h}"><rect width="${w}" height="${h}" fill="#000"/>${svg}</svg>`);
+    return sharp(maskSvg).png().toBuffer();
+}

package/package.json

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

package/src/commands/img-tools.ts

@@ -4,6 +4,8 @@
 import { stat, writeFile } from 'node:fs/promises'
 import { basename, dirname, extname, join } from 'node:path'
 import { removeBackgroundLocal, BG_MODELS, type BgModelKey } from '../local-bg.js'
+import { upscaleLocal, UPSCALE_MODELS, type UpscaleModel } from '../local-upscale.js'
+import { detectWatermarkBoxes, inpaintLocal, maskFromBoxes } from '../local-watermark.js'
 
 async function fileExists(path: string): Promise<boolean> {
   try {
@@ -93,3 +95,62 @@ export async function removeBgCmd(input: string, opts: RemoveBgOpts): Promise<vo
   process.stderr.write(`✅ 抠图完成（${BG_MODELS[modelKey].label}，用时 ${((Date.now() - start) / 1000).toFixed(1)}s，${fmtBytes(png.length)}）\n`)
   console.log(outPath)
 }
+
+export interface RemoveWatermarkOpts {
+  out?: string
+  mask?: string
+  overwrite?: boolean
+}
+
+export async function removeWatermarkCmd(input: string, opts: RemoveWatermarkOpts): Promise<void> {
+  if (!(await fileExists(input))) throw new Error(`文件不存在: ${input}`)
+  const outPath = opts.out || defaultOut(input, 'clean', 'png')
+  if ((await fileExists(outPath)) && !opts.overwrite) {
+    throw new Error(`输出已存在（用 --overwrite 覆盖或 --out 换路径）: ${outPath}`)
+  }
+
+  const start = Date.now()
+  let mask: Buffer | string
+  if (opts.mask) {
+    if (!(await fileExists(opts.mask))) throw new Error(`掩码文件不存在: ${opts.mask}`)
+    mask = opts.mask
+    process.stderr.write('使用手工掩码，跳过自动定位\n')
+  } else {
+    // 纯像素启发式定位水印（零模型依赖），失败时明确指引改用 --mask
+    const boxes = await detectWatermarkBoxes(input)
+    if (!boxes.length) throw new Error('自动定位没找到水印（角标式半透明水印通常可识别；复杂画面请用 --mask 手工指定）')
+    process.stderr.write(`定位到 ${boxes.length} 处水印：${boxes.map((b) => `(${b.x1},${b.y1})-(${b.x2},${b.y2})`).join(' ')}\n`)
+    mask = await maskFromBoxes(input, boxes)
+  }
+
+  const png = await inpaintLocal(input, mask)
+  await writeFile(outPath, png)
+  process.stderr.write(`✅ 去水印完成（用时 ${((Date.now() - start) / 1000).toFixed(1)}s，${fmtBytes(png.length)}）\n`)
+  console.log(outPath)
+}
+
+export interface UpscaleOpts {
+  out?: string
+  scale?: string
+  model?: string
+  overwrite?: boolean
+}
+
+export async function upscaleCmd(input: string, opts: UpscaleOpts): Promise<void> {
+  if (!(await fileExists(input))) throw new Error(`文件不存在: ${input}`)
+  const scale = opts.scale ? Number(opts.scale) : 4
+  if (![2, 3, 4].includes(scale)) throw new Error('--scale 只支持 2 / 3 / 4')
+  const model = (opts.model || 'realesrgan-x4plus') as UpscaleModel
+  if (!(model in UPSCALE_MODELS)) throw new Error(`--model 只支持 ${Object.keys(UPSCALE_MODELS).join(' / ')}`)
+
+  const outPath = opts.out || defaultOut(input, `${scale}x`, 'png')
+  if ((await fileExists(outPath)) && !opts.overwrite) {
+    throw new Error(`输出已存在（用 --overwrite 覆盖或 --out 换路径）: ${outPath}`)
+  }
+
+  const start = Date.now()
+  await upscaleLocal({ input, output: outPath, scale, model })
+  const size = (await stat(outPath)).size
+  process.stderr.write(`✅ 超分完成（${UPSCALE_MODELS[model].label}，${scale}x，用时 ${((Date.now() - start) / 1000).toFixed(1)}s，${fmtBytes(size)}）\n`)
+  console.log(outPath)
+}

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,7 +15,7 @@ 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 } from './commands/img-tools.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'
@@ -190,6 +190,23 @@ program
   .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')
@@ -226,8 +243,9 @@ assetsCmd
 
 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

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 })
+}