museav-cli 2.2.0 → 2.4.0

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.2.0",
+  "version": "2.4.0",
   "description": "MUSE AV 出图中台官方 CLI —— 命令行调中台 API 出图、出视频、读图逆向、图生模板",
   "type": "module",
   "bin": {
@@ -53,6 +53,7 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.3",
+    "onnxruntime-node": "^1.27.0"
   }
 }

package/src/client.ts

@@ -80,6 +80,32 @@ export interface GenerateOptions {
    *   · 只派给声明了该能力的上游；一家都没有时返回 400 说明原因，**不会静默出白底图**
    */
   background?: 'transparent' | 'opaque'
+  /** 项目归档：生成结果挂到该工作区（中台仅账户身份收，租户身份忽略） */
+  workspace_id?: string
+}
+
+/** 工作区（项目）：平台账户下的项目容器，素材库挂在它上面（GET/POST /api/workspaces） */
+export interface Workspace {
+  id: string
+  name: string
+  brand?: string | null
+  description?: string | null
+  /** 该项目累计提交 / 完成的生成数（列表接口附带的统计） */
+  gen_total?: number
+  gen_done?: number
+  created_at?: string
+}
+
+/** 工作区素材（GET/POST /api/workspace-assets）：项目素材库的一条记录 */
+export interface WorkspaceAsset {
+  id: string
+  workspace_id: string
+  media_type: 'image' | 'video' | 'audio'
+  cdn_url: string
+  name: string | null
+  tags: string[]
+  size_bytes?: number | null
+  created_at?: string
 }
 
 /** 图片/文字模板清单项（GET /api/templates，template_type=image|article） */
@@ -412,6 +438,8 @@ export class StudioClient {
     if (opts.reference_images?.length) body.reference_images = opts.reference_images
     if (opts.quality) body.quality = opts.quality
     if (opts.background) body.background = opts.background
+    // 项目归档：中台只对账户身份收 workspace_id（租户身份忽略），CLI 不做二次校验
+    if (opts.workspace_id) body.workspace_id = opts.workspace_id
     const r = await this.request('generate', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -426,6 +454,49 @@ export class StudioClient {
     return r
   }
 
+  // ── 工作区（项目）与项目素材库 ──
+  // 平台 → 账户 → 工作区三层归属；素材挂工作区，换业务换工作区，互不污染。
+
+  /** 列当前账户的工作区（含生成统计） */
+  async workspaces(): Promise<Workspace[]> {
+    return this.request('workspaces')
+  }
+
+  /** 新建工作区（最多 5 个，超了服务端会 400） */
+  async createWorkspace(name: string): Promise<Workspace> {
+    return this.request('workspaces', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name }) })
+  }
+
+  /** 列某工作区的素材库 */
+  async workspaceAssets(workspaceId: string): Promise<WorkspaceAsset[]> {
+    return this.request(`workspace-assets?workspace_id=${encodeURIComponent(workspaceId)}`)
+  }
+
+  /** 上传素材进工作区素材库。素材是母版，**不做视觉压缩**（fileForm 那套压缩是给模型看的） */
+  async addWorkspaceAsset(input: {
+    file: string
+    workspaceId: string
+    name?: string
+    tags?: string[]
+  }): Promise<WorkspaceAsset> {
+    const blob = new Blob([new Uint8Array(readFileSync(input.file))])
+    const fd = new FormData()
+    fd.append('file', blob, basename(input.file))
+    fd.append('workspace_id', input.workspaceId)
+    if (input.name) fd.append('name', input.name)
+    for (const t of input.tags || []) fd.append('tags', t)
+    return this.request('workspace-assets', { method: 'POST', body: fd })
+  }
+
+  /** 删除素材（硬删：R2 对象 + 记录） */
+  async deleteWorkspaceAsset(id: string): Promise<void> {
+    await this.request('workspace-assets', {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id }),
+    })
+  }
+
   /**
    * 列出当前身份名下的出图工作流（不传 id，走同一个 jobs 端点的集合语义）。
    * 范围由鉴权凭证决定：个人 token 只看得到自己出的图；租户 apiKey 看得到自己业务下的全部记录。
@@ -474,19 +545,22 @@ export class StudioClient {
      duration?: number
      /** 图生视频：首帧/参考图 URL（中台内部自动上传垫图后拿到 URL 再传这里） */
      image_url?: string
-     template_id?: string
-     input?: string | Record<string, string>
-     callback_url?: string
-   }): Promise<{ jobId: string; upstreamTaskId?: string }> {
-     const body: Record<string, unknown> = {}
-     if (opts.prompt) body.prompt = opts.prompt
-     if (opts.model) body.model = opts.model
-     if (opts.ratio) body.ratio = opts.ratio
-     if (opts.duration != null) body.duration = opts.duration
-     if (opts.image_url) body.image_url = opts.image_url
-     if (opts.template_id) body.template_id = opts.template_id
-     if (opts.input) body.input = opts.input
-     if (opts.callback_url) body.callback_url = opts.callback_url
+    template_id?: string
+    input?: string | Record<string, string>
+    callback_url?: string
+    /** 项目归档（账户身份才生效） */
+    workspace_id?: string
+  }): Promise<{ jobId: string; upstreamTaskId?: string }> {
+    const body: Record<string, unknown> = {}
+    if (opts.prompt) body.prompt = opts.prompt
+    if (opts.model) body.model = opts.model
+    if (opts.ratio) body.ratio = opts.ratio
+    if (opts.duration != null) body.duration = opts.duration
+    if (opts.image_url) body.image_url = opts.image_url
+    if (opts.template_id) body.template_id = opts.template_id
+    if (opts.input) body.input = opts.input
+    if (opts.callback_url) body.callback_url = opts.callback_url
+    if (opts.workspace_id) body.workspace_id = opts.workspace_id
      const r = await this.request('videos', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },

package/src/commands/gen.ts

@@ -1,5 +1,6 @@
 /** museav gen —— 出图 / 出视频（核心命令） */
 import type { StudioClient } from '../client.js'
+import { resolveWorkspace } from './projects.js'
 
 /** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
 const MAX_REFS = 5
@@ -15,6 +16,7 @@ export async function gen(client: StudioClient, opts: {
   quality?: string
   ref?: string[]      // 可重复：--ref a.jpg --ref b.jpg，顺序即「图片1、图片2…」
   transparent?: boolean   // 透明背景 PNG；能不能做由中台按上游能力判定，做不了会明确报错
+  project?: string    // 工作区 id|名：生成结果归档进该项目（账户身份才生效）
   // 视频
   video?: boolean
   duration?: number
@@ -63,6 +65,13 @@ export async function gen(client: StudioClient, opts: {
   if (refPaths.length) {
     const urls: string[] = []
     for (const [i, refPath] of refPaths.entries()) {
+      // http(s) 直链（典型来源：museav projects assets 的素材库 URL）本身就是
+      // 中台 CDN 地址，直接当参考图用，不走上传
+      if (/^https?:\/\//.test(refPath)) {
+        urls.push(refPath)
+        process.stderr.write(`  图片${i + 1} 直链: ${refPath}\n`)
+        continue
+      }
       process.stderr.write(`上传垫图 [图片${i + 1}] ${refPath} ...\n`)
       const up = await client.uploadRef(refPath)
       urls.push(up.url)
@@ -72,6 +81,9 @@ export async function gen(client: StudioClient, opts: {
     referenceImages = urls.length > 1 ? urls : undefined
   }
 
+  // 项目归档：--project 解析成 workspace_id（名字/ id 都行），租户身份时中台会忽略
+  const workspaceId = opts.project ? (await resolveWorkspace(client, opts.project)).id : undefined
+
   // ── 视频模式：走 /api/videos 独立链路 ──
   if (opts.video) {
     if (opts.quality) throw new Error('--quality 仅图片出图支持')
@@ -87,6 +99,7 @@ export async function gen(client: StudioClient, opts: {
       image_url: referenceImage,
       template_id: opts.template,
       input: templateFields,
+      workspace_id: workspaceId,
     })
     process.stderr.write(`视频任务已提交: ${jobId}\n生成中（视频通常 1-5 分钟）...\n`)
     const result = await client.waitVideo(jobId, (status) => {
@@ -123,6 +136,7 @@ export async function gen(client: StudioClient, opts: {
       // 开关 → 枚举：CLI 这层用布尔开关最顺手，中台契约是 background: transparent|opaque
       // （跟上游 gpt-image 的参数同名同值）。不传就不发，行为跟以前完全一样。
       background: opts.transparent ? 'transparent' : undefined,
+      workspace_id: workspaceId,
     },
     (status) => {
       if (status === 'processing') process.stderr.write('生成中...\r')

package/src/commands/img-tools.ts

@@ -0,0 +1,156 @@
+/** museav compress / remove-bg —— 本地图像工具箱。
+ *  纯本地、免登录、不碰中台；stdout 只出产物路径，统计与进度打 stderr。
+ *  代码零平台假设（路径全走 node:path/os，无 shell 展开、无 Unix-only 命令），macOS / Windows 通用。 */
+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 {
+    return (await stat(path)).isFile()
+  } catch {
+    return false
+  }
+}
+
+function fmtBytes(n: number): string {
+  return n >= 1048576 ? `${(n / 1048576).toFixed(2)}MB` : `${(n / 1024).toFixed(1)}KB`
+}
+
+/** 默认输出路径：同目录 <名字>-<后缀>.<新扩展名>。绝不覆写输入文件 */
+export function defaultOut(input: string, suffix: string, newExt?: string): string {
+  const ext = newExt || extname(input).slice(1) || 'png'
+  return join(dirname(input), `${basename(input, extname(input))}-${suffix}.${ext}`)
+}
+
+export interface CompressOpts {
+  out?: string
+  maxEdge?: string
+  quality?: string
+  format?: string
+  overwrite?: boolean
+}
+
+export async function compressCmd(input: string, opts: CompressOpts): Promise<void> {
+  if (!(await fileExists(input))) throw new Error(`文件不存在: ${input}`)
+
+  let sharp: any
+  try {
+    const m = await import('sharp')
+    sharp = (m as any).default ?? m
+  } catch {
+    throw new Error('sharp 不可用（压缩依赖它）。重装 CLI 即可补上：npm install -g museav-cli')
+  }
+
+  const format = (opts.format || '').toLowerCase()
+  if (format && !['jpg', 'png', 'webp'].includes(format)) throw new Error('--format 只支持 jpg / png / webp')
+  const quality = opts.quality ? Number(opts.quality) : 82
+  if (!Number.isFinite(quality) || quality < 1 || quality > 100) throw new Error('--quality 必须是 1-100')
+  const maxEdge = opts.maxEdge ? Number(opts.maxEdge) : 0
+  if (opts.maxEdge && (!Number.isFinite(maxEdge) || maxEdge < 16)) throw new Error('--max-edge 至少 16px')
+
+  const meta = await sharp(input).metadata()
+  // 不指定 --format 时保持原格式；不在三之列的（tiff/bmp/heic…）统一转 jpg
+  const srcFormat = String(meta.format || '')
+  const target = format || (srcFormat === 'png' ? 'png' : srcFormat === 'webp' ? 'webp' : 'jpg')
+
+  let pipeline = sharp(input).rotate() // 尊重 EXIF 方向
+  if (maxEdge) pipeline = pipeline.resize({ width: maxEdge, height: maxEdge, fit: 'inside' })
+  if (target === 'jpg') pipeline = pipeline.jpeg({ quality, mozjpeg: true })
+  else if (target === 'webp') pipeline = pipeline.webp({ quality })
+  else pipeline = pipeline.png({ compressionLevel: 9 })
+
+  const outPath = opts.out || defaultOut(input, 'min', target === 'jpg' && srcFormat === 'jpeg' ? 'jpg' : target)
+  if ((await fileExists(outPath)) && !opts.overwrite) {
+    throw new Error(`输出已存在（用 --overwrite 覆盖或 --out 换路径）: ${outPath}`)
+  }
+  const buf = await pipeline.toBuffer()
+  await writeFile(outPath, buf)
+
+  const before = (await stat(input)).size
+  process.stderr.write(`✅ ${fmtBytes(before)} → ${fmtBytes(buf.length)}（省 ${Math.max(0, Math.round((1 - buf.length / before) * 100))}%，${target.toUpperCase()}）\n`)
+  console.log(outPath)
+}
+
+export interface RemoveBgOpts {
+  out?: string
+  model?: string
+  overwrite?: boolean
+}
+
+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
+  if (!(modelKey in BG_MODELS)) throw new Error(`--model 只支持 ${Object.keys(BG_MODELS).join(' / ')}`)
+
+  const start = Date.now()
+  const png = await removeBackgroundLocal(input, modelKey)
+  const outPath = opts.out || defaultOut(input, 'nobg', 'png')
+  if ((await fileExists(outPath)) && !opts.overwrite) {
+    throw new Error(`输出已存在（用 --overwrite 覆盖或 --out 换路径）: ${outPath}`)
+  }
+  await writeFile(outPath, png)
+  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)
+}