museav-cli 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.4.0 · 2026-08-17
+
+**本地图像工具箱补全（免登录、零成本、macOS/Windows 通用）。** 均为轻量级工具，无大模型常驻内存。
+
+- `upscale <file>`：Real-ESRGAN 超分（Vulkan GPU 加速），`--scale 2/3/4`、`--model`（通用照片 / 插画动漫）。首次自动下载引擎+模型（~65MB）；M3 实测 4x 约 30 秒。
+- `remove-watermark <file>`：本地去水印。**纯像素启发式自动定位**（零模型依赖，角标式水印实测零误检）→ LaMa 掩码修复；复杂画面用 `--mask` 手工指定。修复模型 ~200MB 按需下载、用完即释放。
+- 依赖红线：本地绝不自动拉起开源大模型（reverse 已翻回 API 默认，`--local` 显式可选；Ollama 与 qwen3-vl 已从本机卸载）。
+
+**中台与前端联动。**
+
+- 上游目录移除 gemini 死条目（路由/密钥早已清除，目录残留会误判读图有冗余），相关测试 mock 统一改用 volcengine-plan-vision。
+- museav-web 参考图选择器接入工作区素材库：上传同步入库、素材库面板点选直接垫图、工作区切换自动刷新。
+- 发布卡片样式重排：标题/升级命令/仓库链接全部对齐 `museav-cli` 新名（旧包名已停更，照旧卡片敲命令装不到新版），剥掉 changelog 标题噪声，双列字段 + 三按钮。
+
 ## 2.3.0 · 2026-08-17
 
 **项目（工作区）与项目素材库。** 层级：平台 → 账户 → 工作区，素材挂工作区——人像库的项目出模特图、产品库的项目出电商图，业务隔离互不污染。`--project` 收 id 或名称。

package/README.md

@@ -237,24 +237,22 @@ museav gen --template "$ID" --fields '{"artist":"..."}'
 
 ### 图片逆向 `reverse`
 
-逆推出图 prompt，可以直接拿去再出一张同风格的。**主路是本地 Ollama（qwen3-vl）**：快、零成本、无需登录；本地不可用时自动回落中台 API（SCULPT 六要素：主体/构图/世界观/光影/输出/质感），回落时会明确提示较慢：
+逆推出图 prompt，可以直接拿去再出一张同风格。**默认走中台 API**（SCULPT 六要素：主体/构图/世界观/光影/输出/质感）；`--local` 可显式切本地 Ollama（需自备 qwen3-vl，本地不可用时自动回落 API）：
 
 ```bash
-# 本地文件走本地模型（推荐，无需登录）
+# 默认：中台 API（需登录）
 museav reverse photo.png
 
-# 图片 URL 没法喂本地模型，走中台 API（需登录）
-museav reverse https://example.com/photo.png
+# 显式本地：需 ollama pull qwen3-vl:8b 自备模型（本地大模型默认不自动拉起）
+museav reverse photo.png --local
 
-# 强制走中台 API（跳过本地，慢，需登录）
-museav reverse photo.png --api
+# 图片 URL 走中台 API
+museav reverse https://example.com/photo.png
 
 # 逆向 + 出图，一条龙
 museav gen --prompt "$(museav reverse photo.png)"
 ```
 
-本地路依赖：Ollama 运行中（`brew services start ollama`）+ 模型在位（`ollama pull qwen3-vl:8b`，换档位设 `MUSEAV_LOCAL_VLM`，自定地址设 `OLLAMA_HOST`）。缺哪个都会提示对应命令并回落 API。
-
 分析详情打到 stderr（人看），**stdout 只输出英文 prompt**（机器用，方便管道）。
 
 `reverse` **只读图**，不会顺手帮你建模板。要把图做成模板看下一节——中台 2026-08-16 把这两件事
@@ -341,6 +339,21 @@ museav gen --prompt "$(museav reverse $(museav remove-bg shoe.png))"   # 抠图
 - 两个命令的输出默认带后缀（`-min` / `-nobg`），不会覆盖你的输入文件；要覆盖已存在的输出加 `--overwrite`。
 - 可选依赖缺失时不炸，报一行重装指引（`npm install -g museav-cli`）。
 
+### 超分 `upscale` 与去水印 `remove-watermark`（轻量工具，无大模型常驻）
+
+```bash
+# 超分放大（Real-ESRGAN + Vulkan GPU；首次自动下载引擎+模型 ~65MB）
+museav upscale photo.jpg --scale 4                     # 默认输出 <名>-4x.png
+museav upscale anime.png --model realesrgan-x4plus-anime
+
+# 去水印（纯像素启发式定位 → LaMa 修复，零模型依赖；修复模型 ~200MB 按需下载）
+museav remove-watermark photo.jpg                      # 角标式水印自动定位
+museav remove-watermark photo.jpg --mask mask.png      # 复杂画面手工掩码（白=去除区）
+```
+
+- 依赖红线：本地**绝不自动拉起开源大模型**——这些工具是轻量 CNN/传统算法，用完即释放内存。reverse 的本地路已翻回显式 `--local`（需自备 Ollama），默认走中台 API。
+- 二进制与模型缓存：`~/.museav-bin/upscayl`（引擎）、`~/.museav-models/`（模型），Windows 对应 `%USERPROFILE%` 下同名目录；删除即彻底清理。
+
 ### 项目（工作区）与项目素材库 `projects`
 
 层级：**平台 → 账户 → 工作区**。一个账户最多 5 个项目，每个项目挂自己的素材库——「人像库的项目出模特图、产品库的项目出电商图」，业务隔离互不污染：

package/dist/commands/img-tools.d.ts

@@ -14,3 +14,16 @@ export interface RemoveBgOpts {
     overwrite?: boolean;
 }
 export declare function removeBgCmd(input: string, opts: RemoveBgOpts): Promise<void>;
+export interface RemoveWatermarkOpts {
+    out?: string;
+    mask?: string;
+    overwrite?: boolean;
+}
+export declare function removeWatermarkCmd(input: string, opts: RemoveWatermarkOpts): Promise<void>;
+export interface UpscaleOpts {
+    out?: string;
+    scale?: string;
+    model?: string;
+    overwrite?: boolean;
+}
+export declare function upscaleCmd(input: string, opts: UpscaleOpts): Promise<void>;

package/dist/commands/img-tools.js

@@ -4,6 +4,8 @@
 import { stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { removeBackgroundLocal, BG_MODELS } from '../local-bg.js';
+import { upscaleLocal, UPSCALE_MODELS } from '../local-upscale.js';
+import { detectWatermarkBoxes, inpaintLocal, maskFromBoxes } from '../local-watermark.js';
 async function fileExists(path) {
     try {
         return (await stat(path)).isFile();
@@ -79,3 +81,50 @@ export async function removeBgCmd(input, opts) {
     process.stderr.write(`✅ 抠图完成（${BG_MODELS[modelKey].label}，用时 ${((Date.now() - start) / 1000).toFixed(1)}s，${fmtBytes(png.length)}）\n`);
     console.log(outPath);
 }
+export async function removeWatermarkCmd(input, opts) {
+    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;
+    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 async function upscaleCmd(input, opts) {
+    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');
+    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/dist/commands/reverse.d.ts

@@ -1,8 +1,9 @@
 /** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt）。
- *  主路是本地 Ollama（qwen3-vl），快、零成本、无需登录；中台 API 是回落路，走回落时会明确提示较慢。
- *  client 懒构造（getClient）：本地路成功就完全不碰中台凭证。
- *  本地系统的 AI 能力统一收口在这个 CLI，reverse 是第一个本地化的能力。 */
+ *  默认走中台 API（快、稳定、不需本地模型）；--local 可切本地 Ollama（需自备 qwen3-vl，
+ *  仅在用户显式要求时使用——本地大模型默认不拉起，不给用户的内存添负担）。
+ *  client 懒构造：本地路成功就完全不碰中台凭证。 */
 import type { StudioClient } from '../client.js';
 export declare function reverse(getClient: () => StudioClient, input: string, opts?: {
     api?: boolean;
+    local?: boolean;
 }): Promise<void>;

package/dist/commands/reverse.js

@@ -1,7 +1,8 @@
 import { checkLocalVlm, reverseLocally, LOCAL_VLM_MODEL } from '../local-vision.js';
 export async function reverse(getClient, input, opts = {}) {
     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 {
@@ -19,7 +20,7 @@ export async function reverse(getClient, input, opts = {}) {
             process.stderr.write(`⚠ 本地读图不可用（${status.reason}），回落中台 API —— 速度较慢，请耐心等待\n`);
         }
     }
-    else if (!opts.api && isUrl) {
+    else if (opts.local && isUrl) {
         process.stderr.write(`ℹ URL 输入走中台 API（本地路只收文件路径）\n`);
     }
     const client = getClient();

package/dist/index.js

@@ -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 } from './commands/projects.js';
 import { imageToTemplate } from './commands/image-to-template.js';
 import { upload } from './commands/upload.js';
@@ -184,6 +184,21 @@ program
     .option('--model <name>', 'isnet（默认，质量优先）/ u2net')
     .option('--overwrite', '允许覆盖已存在的输出文件')
     .action(asyncRun((input, opts) => 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, opts) => 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, opts) => removeWatermarkCmd(input, opts)));
 // 工作区（项目）与项目素材库：平台 → 账户 → 工作区三层归属，素材挂工作区
 const projectsCmd = program
     .command('projects')
@@ -214,8 +229,9 @@ assetsCmd
     .action(withClient((client, id) => 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, input, opts) => reverse(getClient, input, opts)));
 program
     .command('image-to-template <input>')

package/dist/local-upscale.d.ts

@@ -0,0 +1,21 @@
+export declare const UPSCALE_MODELS: {
+    readonly 'realesrgan-x4plus': {
+        readonly label: '通用照片（默认）';
+    };
+    readonly 'realesrgan-x4plus-anime': {
+        readonly label: '插画/动漫';
+    };
+};
+export type UpscaleModel = keyof typeof UPSCALE_MODELS;
+/** 首次使用时准备好二进制与模型，返回 { exe, modelDir }。之后直接走缓存 */
+export declare function ensureUpscaleRuntime(): Promise<{
+    exe: string;
+    modelDir: string;
+}>;
+/** 超分主流程：返回输出文件的字节数组由引擎直写磁盘，这里只负责调度 */
+export declare function upscaleLocal(opts: {
+    input: string;
+    output: string;
+    scale: number;
+    model: UpscaleModel;
+}): Promise<void>;

package/dist/local-upscale.js

@@ -0,0 +1,115 @@
+/**
+ * 本地超分（放大）—— 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: '插画/动漫' },
+};
+const BIN_DIR = join(homedir(), '.museav-bin', 'upscayl');
+const MODEL_DIR = join(homedir(), '.museav-models');
+function platformAsset() {
+    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) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function download(url, dest, label) {
+    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 = [];
+    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() {
+    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) {
+    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/dist/local-watermark.d.ts

@@ -0,0 +1,21 @@
+export interface Bbox {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/**
+ * 纯像素启发式水印定位（零模型依赖）。
+ * 原理：半透明水印（角标/文字）是「低对比、高频、铺在大片区域的细碎纹理」，
+ * 把四角区域做中值模糊后与原图差分，叠字区会出现稳定的高差值像素团。
+ * 判定保守：角区差分像素占比在 [0.3%, 8%] 才算水印（太少=没叠字，
+ * 太多=画面本身纹理复杂，不硬修）；坐标 0-1000 归一化输出。
+ * 误检最坏是 LaMa 重绘一块（轻微损伤），另有 --mask 手工精确兜底。
+ */
+export declare function detectWatermarkBoxes(imagePath: string): Promise<Bbox[]>;
+/** 掩码修复主流程：mask 白色=要去除（Buffer 或文件路径）；输出 PNG Buffer。
+ *  模型是固定 512×512 输入——整图缩进去会毁分辨率，所以按掩码连通域逐块处理：
+ *  裁出带边距的局部 → letterbox 进 512 修复 → 只把掩码内的像素贴回原图。 */
+export declare function inpaintLocal(imagePath: string, mask: Buffer | string): Promise<Buffer>;
+/** 从检测框生成掩码 Buffer（框外扩 2%，白=去除区） */
+export declare function maskFromBoxes(imagePath: string, boxes: Bbox[]): Promise<Buffer>;

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.0",
   "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 })
+}

package/src/local-watermark.ts

@@ -0,0 +1,320 @@
+/**
+ * 本地去水印 —— 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(): Promise<string> {
+  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: unknown = 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: 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 / 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: number) => Math.ceil(n / 8) * 8
+
+export interface Bbox {
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+}
+
+/**
+ * 纯像素启发式水印定位（零模型依赖）。
+ * 原理：半透明水印（角标/文字）是「低对比、高频、铺在大片区域的细碎纹理」，
+ * 把四角区域做中值模糊后与原图差分，叠字区会出现稳定的高差值像素团。
+ * 判定保守：角区差分像素占比在 [0.3%, 8%] 才算水印（太少=没叠字，
+ * 太多=画面本身纹理复杂，不硬修）；坐标 0-1000 归一化输出。
+ * 误检最坏是 LaMa 重绘一块（轻微损伤），另有 --mask 手工精确兜底。
+ */
+export async function detectWatermarkBoxes(imagePath: string): Promise<Bbox[]> {
+  const sharpMod = await import('sharp')
+  const sharp = (sharpMod as any).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: Bbox[] = []
+
+  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: string, mask: Buffer | string): Promise<Buffer> {
+  const ort = await import('onnxruntime-node')
+  const sharpMod = await import('sharp')
+  const sharp = (sharpMod as any).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 as Float32Array
+
+    // 取回中心区域，缩回原尺寸
+    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: number) => Math.max(0, Math.min(255, Math.round(v)))
+
+/** 掩码连通域 → 像素 bbox 列表。在 1/4 采样上网格 BFS，快且够准 */
+function connectedBoxes(mask: Buffer, W: number, H: number): Array<{ x: number; y: number; w: number; h: number }> {
+  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: Array<{ x: number; y: number; w: number; h: number }> = []
+  const q: number[] = []
+  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: string, boxes: Bbox[]): Promise<Buffer> {
+  const sharpMod = await import('sharp')
+  const sharp = (sharpMod as any).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()
+}