museav-cli 2.3.0 → 2.4.1

package/AGENTS.md

@@ -64,8 +64,14 @@ museav upload ./face.png
 #   compress:  resize/re-encode via sharp. Output <name>-min.<fmt>, never overwrites input.
 #   remove-bg: ISNet via onnxruntime-node → alpha PNG (~170MB model auto-downloaded
 #              to ~/.museav-models on first use; %USERPROFILE%\.museav-models on Windows).
+#   upscale:   Real-ESRGAN via Vulkan GPU → 2M image becomes 10M+ (~65MB engine+model
+#              auto-downloaded once to ~/.museav-bin + ~/.museav-models).
+#   remove-watermark: pixel-heuristic auto-locate (zero model deps) + LaMa inpainting
+#              → clean PNG (~200MB model on-demand, freed after run).
 museav compress ./photo.jpg --max-edge 800 --format webp --quality 70
 museav remove-bg ./shoe.png              # stdout: path to <name>-nobg.png
+museav upscale ./photo.jpg --scale 4     # stdout: path to <name>-4x.png
+museav remove-watermark ./poster.jpg     # stdout: path to <name>-clean.png
 
 # List your own (or, if using a tenant apiKey, your tenant's) recent jobs as JSON
 museav jobs --limit 10 --status failed

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

@@ -85,6 +85,27 @@
 
 两条路径互不依赖，选跟你身份匹配的那条，不用两个都配。下面「快速开始」走的是平台用户（login）这条路；如果你是租户，直接跳到下面「B 端 / CI 场景」那一节。
 
+## 能力速览（小白先看这个）
+
+`museav` 能干什么，一句话一组：
+
+| 分类 | 能力 | 命令 |
+|---|---|---|
+| **AI 生成**（中台） | 文字出图 / 垫图出图 / 技能出图 / 模板出图 | `gen`（含 `--ref` 垫图、`--transparent` 透明底） |
+| | 文生视频 / 图生视频 | `gen --video` |
+| | 从已有图片反推提示词 | `reverse` |
+| | 一张图做成可复用模板 | `image-to-template` |
+| | 建/查图片模板、视频模板 | `templates` / `video-templates` |
+| **项目管理**（中台） | 工作区（项目）+ 每个项目自己的素材库 | `projects`、`projects assets` |
+| | 素材直链垫图、作品归档进项目 | `gen --project`、`jobs --project` |
+| **本地图像处理**（免登录/免费/离线） | 压缩图片 | `compress` |
+| | 抠图去背景（输出透明 PNG） | `remove-bg` |
+| | **放大清晰度**（2M → 10M+ 级） | `upscale` |
+| | 去水印 | `remove-watermark` |
+| **素材与统计** | 上传素材 / 查任务 / 查余额 / 查模型 / 查身份 | `upload` / `jobs` / `balance` / `models` / `whoami` |
+
+> 本地工具（`compress` / `remove-bg` / `upscale` / `remove-watermark`）**不用登录、不花一分钱**，装了就能用；其余命令需要一个凭证（个人 `login` 或租户 apiKey）。
+
 ---
 
 ## 快速开始
@@ -237,24 +258,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 +360,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 个项目，每个项目挂自己的素材库——「人像库的项目出模特图、产品库的项目出电商图」，业务隔离互不污染：
@@ -463,6 +497,8 @@ console.log(r.sculpt.light)  // 光影分析
 | `upload <file>` | 上传素材（图片/音频/视频） | 公网直链 |
 | `compress <file>` | 本地压缩图片（免登录，`--max-edge`/`--quality`/`--format`） | 产物路径 |
 | `remove-bg <file>` | 本地抠图去背景（免登录，输出带 alpha 的 PNG） | 产物路径 |
+| `upscale <file>` | 本地超分放大，2M 图变 10M+（免登录，Real-ESRGAN GPU，`--scale 2/3/4`） | 产物路径 |
+| `remove-watermark <file>` | 本地去水印（免登录，自动定位 + LaMa 修复，`--mask` 手工兜底） | 产物路径 |
 | `projects` | 工作区（项目）列表：一账户多项目，各带自己的素材库 | 项目 id 列表 |
 | `projects assets --project` | 项目素材库：ls / add / rm（垫图母版，人像库/产品库各管各的） | `id<TAB>url` 行 |
 | `models` | 可用模型 | 模型名列表 |

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>;