museav-cli 2.2.0 → 2.4.0

package/AGENTS.md

@@ -59,6 +59,14 @@ museav image-to-template ./poster.jpg --no-create      # dry run: draft JSON on
 # Upload a file (image/audio/video; type is detected from the bytes, not the extension)
 museav upload ./face.png
 
+# Local image tools — no login, no platform quota, work on macOS AND Windows
+# (all deps ship prebuilt binaries; zero platform-specific code):
+#   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).
+museav compress ./photo.jpg --max-edge 800 --format webp --quality 70
+museav remove-bg ./shoe.png              # stdout: path to <name>-nobg.png
+
 # List your own (or, if using a tenant apiKey, your tenant's) recent jobs as JSON
 museav jobs --limit 10 --status failed
 
@@ -81,6 +89,7 @@ Full flag reference: `museav <command> --help`. Full command table and auth deta
 
 ## Failure modes worth knowing
 
+- **Cross-platform contract**: the CLI targets macOS AND Windows. No Unix-only assumptions anywhere — paths go through `node:path`/`os.homedir()`, no shell expansions, no brew/which calls in code (OS-specific text like Ollama start hints adapts via `process.platform`). Keep it that way in new code.
 - `gen` polls until the job finishes or times out (default 600s controlled by the underlying `generateAndWait`); a timeout throws, it does not hang forever.
 - `jobs --limit`/`--status` are filtered **client-side** — the server always returns your most recent 50 jobs; you cannot page past that.
 - Non-zero exit code + a message on stderr is the only failure signal; there's no separate machine-readable error format on stdout.

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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 或名称。
+
+- `projects` 列表 / `projects create --name` 新建（每账户最多 5 个）
+- `projects assets --project` 素材库 ls / add / rm：素材按**母版不压缩**上传，类型按字节判定（图片/音频/视频），stdout 出 `id<TAB>url` 可直接喂 `--ref`
+- `gen --project` 出图/出视频归档进项目；`jobs --project` 按项目查任务
+- `--ref` / `--image` 现在也收 http(s) 直链（素材库 URL 直接垫图，不再只认本地文件）
+- 需中台 `workspace-assets` 接口（2026-08-17 已上线）；账户 Key 白名单已放行
+
+**本地图像工具箱（免登录、零成本、macOS/Windows 通用）。** 依赖全走 npm 预编译，代码零平台假设。
+
+- `compress <file>`：sharp 压缩，`--max-edge / --quality / --format`，默认输出 `<名>-min.<格式>` 不覆写原文件，实测 597KB → 18KB
+- `remove-bg <file>`：本地抠图去背景（ISNet + onnxruntime，刻意没用 AGPL 的现成包），输出带 alpha 的 PNG，热跑秒级；模型首次自动下载 ~170MB 缓存 `~/.museav-models`
+- Ollama 未运行时的启动指引按操作系统区分（Windows 不再提示 brew）
+
 ## 2.2.0 · 2026-08-17
 
 **`reverse` 主路改本地：Ollama + qwen3-vl。** 中台 API 读图要上传、排队、等云端推理；本地 8b 量化模型在自己机器上跑，免登录、零成本、离线可用。本地不可用（服务没起 / 模型没拉 / 推理出错）自动回落中台 API，回落时明确提示较慢，缺什么会告诉你补什么命令。

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 把这两件事
@@ -322,6 +320,58 @@ museav upload face.png
 > `gen --ref` / `gen --video --image` 内部已经自动帮你上传了，不需要先手动跑一次 `upload`。
 > 单独用 `upload` 的场景是：同一张垫图要复用多次，或者你想把 URL 存下来给别的系统用。
 
+### 本地图像工具 `compress` / `remove-bg`
+
+纯本地、免登录、不消耗中台额度，macOS / Windows / Linux 通用（依赖全走 npm 预编译，无平台特化代码）：
+
+```bash
+# 压缩：默认同目录 <名>-min.<格式>，绝不覆写原文件
+museav compress photo.jpg
+museav compress photo.jpg --max-edge 800 --format webp --quality 70   # 597KB → 18KB 级别
+
+# 抠图去背景：输出带 alpha 的 PNG（ISNet 模型，本地 ONNX 推理，热跑秒级）
+museav remove-bg product.png
+# stdout 都是产物路径，方便管道串联
+museav gen --prompt "$(museav reverse $(museav remove-bg shoe.png))"   # 抠图 → 逆向 → 重生成
+```
+
+- `compress` 用 sharp（已是 CLI 可选依赖）；`remove-bg` 用 onnxruntime-node + ISNet/U2Net 模型（均 MIT/Apache 兼容许可证，刻意没用 AGPL 的现成 npm 包）。模型首次使用自动下载 ~170MB，缓存到 `~/.museav-models/`（Windows 是 `%USERPROFILE%\.museav-models`）。
+- 两个命令的输出默认带后缀（`-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 个项目，每个项目挂自己的素材库——「人像库的项目出模特图、产品库的项目出电商图」，业务隔离互不污染：
+
+```bash
+museav projects                                        # 列项目（id / 名称 / 出图统计）
+museav projects create --name 'meso猫砂电商'            # 新建
+museav projects assets --project meso                  # 列该项目素材库（stdout: id<TAB>url）
+museav projects assets add ./model.jpg --project meso --name '白T正面' --tag 产品 --tag 电商
+museav projects assets rm <素材id>
+
+# 生成归档进项目；垫图直接用素材库里的 URL
+museav gen --project meso --prompt '...' --ref <素材URL>
+museav jobs --project meso                             # 只看该项目的任务
+```
+
+素材是**母版不压缩**（跟垫图上传的视觉压缩是两回事），类型按字节判定（图片/音频/视频）。`--project` 收 id 或名称，重名时提示用 id。**需要中台部署 `workspace-assets` 接口后可用**（含账户 Key 白名单放行）。
+
 ### 查模型 / 余额
 
 ```bash
@@ -424,6 +474,10 @@ console.log(r.sculpt.light)  // 光影分析
 | `reverse <file\|url>` | 读图，反推 prompt（**只读图**，不建模板） | 英文 prompt |
 | `image-to-template <file\|url>` | 图生模板：读图 + 文字层逆向 + 变量化 → 建成可复用图片模板 | 模板 id（`--no-create` 时是草稿 JSON） |
 | `upload <file>` | 上传素材（图片/音频/视频） | 公网直链 |
+| `compress <file>` | 本地压缩图片（免登录，`--max-edge`/`--quality`/`--format`） | 产物路径 |
+| `remove-bg <file>` | 本地抠图去背景（免登录，输出带 alpha 的 PNG） | 产物路径 |
+| `projects` | 工作区（项目）列表：一账户多项目，各带自己的素材库 | 项目 id 列表 |
+| `projects assets --project` | 项目素材库：ls / add / rm（垫图母版，人像库/产品库各管各的） | `id<TAB>url` 行 |
 | `models` | 可用模型 | 模型名列表 |
 | `balance` | 上游余额 | JSON |
 | `jobs` | 查自己（租户则是自己业务下）的工作流 | JSON 数组 |

package/dist/client.d.ts

@@ -31,6 +31,30 @@ 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） */
 export interface TemplateOption {
@@ -310,6 +334,21 @@ export declare class StudioClient {
     }>;
     /** 查单个任务状态 */
     getJob(id: string): Promise<Job>;
+    /** 列当前账户的工作区（含生成统计） */
+    workspaces(): Promise<Workspace[]>;
+    /** 新建工作区（最多 5 个，超了服务端会 400） */
+    createWorkspace(name: string): Promise<Workspace>;
+    /** 列某工作区的素材库 */
+    workspaceAssets(workspaceId: string): Promise<WorkspaceAsset[]>;
+    /** 上传素材进工作区素材库。素材是母版，**不做视觉压缩**（fileForm 那套压缩是给模型看的） */
+    addWorkspaceAsset(input: {
+        file: string;
+        workspaceId: string;
+        name?: string;
+        tags?: string[];
+    }): Promise<WorkspaceAsset>;
+    /** 删除素材（硬删：R2 对象 + 记录） */
+    deleteWorkspaceAsset(id: string): Promise<void>;
     /**
      * 列出当前身份名下的出图工作流（不传 id，走同一个 jobs 端点的集合语义）。
      * 范围由鉴权凭证决定：个人 token 只看得到自己出的图；租户 apiKey 看得到自己业务下的全部记录。
@@ -339,6 +378,8 @@ export declare class StudioClient {
         template_id?: string;
         input?: string | Record<string, string>;
         callback_url?: string;
+        /** 项目归档（账户身份才生效） */
+        workspace_id?: string;
     }): Promise<{
         jobId: string;
         upstreamTaskId?: string;

package/dist/client.js

@@ -149,6 +149,9 @@ export class StudioClient {
             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' },
@@ -161,6 +164,40 @@ export class StudioClient {
         const r = await this.request(`jobs?id=${encodeURIComponent(id)}`);
         return r;
     }
+    // ── 工作区（项目）与项目素材库 ──
+    // 平台 → 账户 → 工作区三层归属；素材挂工作区，换业务换工作区，互不污染。
+    /** 列当前账户的工作区（含生成统计） */
+    async workspaces() {
+        return this.request('workspaces');
+    }
+    /** 新建工作区（最多 5 个，超了服务端会 400） */
+    async createWorkspace(name) {
+        return this.request('workspaces', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name }) });
+    }
+    /** 列某工作区的素材库 */
+    async workspaceAssets(workspaceId) {
+        return this.request(`workspace-assets?workspace_id=${encodeURIComponent(workspaceId)}`);
+    }
+    /** 上传素材进工作区素材库。素材是母版，**不做视觉压缩**（fileForm 那套压缩是给模型看的） */
+    async addWorkspaceAsset(input) {
+        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) {
+        await this.request('workspace-assets', {
+            method: 'DELETE',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id }),
+        });
+    }
     /**
      * 列出当前身份名下的出图工作流（不传 id，走同一个 jobs 端点的集合语义）。
      * 范围由鉴权凭证决定：个人 token 只看得到自己出的图；租户 apiKey 看得到自己业务下的全部记录。
@@ -216,6 +253,8 @@ export class StudioClient {
             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/dist/commands/gen.d.ts

@@ -11,6 +11,7 @@ export declare function gen(client: StudioClient, opts: {
     quality?: string;
     ref?: string[];
     transparent?: boolean;
+    project?: string;
     video?: boolean;
     duration?: number;
     image?: string;

package/dist/commands/gen.js

@@ -1,3 +1,4 @@
+import { resolveWorkspace } from './projects.js';
 /** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
 const MAX_REFS = 5;
 export async function gen(client, opts) {
@@ -44,6 +45,13 @@ export async function gen(client, opts) {
     if (refPaths.length) {
         const urls = [];
         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);
@@ -52,6 +60,8 @@ export async function gen(client, opts) {
         referenceImage = urls[0]; // 兼容：中台单数字段仍收
         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)
@@ -67,6 +77,7 @@ export async function gen(client, 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) => {
@@ -100,6 +111,7 @@ export async function gen(client, opts) {
         // 开关 → 枚举：CLI 这层用布尔开关最顺手，中台契约是 background: transparent|opaque
         // （跟上游 gpt-image 的参数同名同值）。不传就不发，行为跟以前完全一样。
         background: opts.transparent ? 'transparent' : undefined,
+        workspace_id: workspaceId,
     }, (status) => {
         if (status === 'processing')
             process.stderr.write('生成中...\r');

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

@@ -0,0 +1,29 @@
+/** 默认输出路径：同目录 <名字>-<后缀>.<新扩展名>。绝不覆写输入文件 */
+export declare function defaultOut(input: string, suffix: string, newExt?: string): string;
+export interface CompressOpts {
+    out?: string;
+    maxEdge?: string;
+    quality?: string;
+    format?: string;
+    overwrite?: boolean;
+}
+export declare function compressCmd(input: string, opts: CompressOpts): Promise<void>;
+export interface RemoveBgOpts {
+    out?: string;
+    model?: string;
+    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

@@ -0,0 +1,130 @@
+/** 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 } 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();
+    }
+    catch {
+        return false;
+    }
+}
+function fmtBytes(n) {
+    return n >= 1048576 ? `${(n / 1048576).toFixed(2)}MB` : `${(n / 1024).toFixed(1)}KB`;
+}
+/** 默认输出路径：同目录 <名字>-<后缀>.<新扩展名>。绝不覆写输入文件 */
+export function defaultOut(input, suffix, newExt) {
+    const ext = newExt || extname(input).slice(1) || 'png';
+    return join(dirname(input), `${basename(input, extname(input))}-${suffix}.${ext}`);
+}
+export async function compressCmd(input, opts) {
+    if (!(await fileExists(input)))
+        throw new Error(`文件不存在: ${input}`);
+    let sharp;
+    try {
+        const m = await import('sharp');
+        sharp = m.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 async function removeBgCmd(input, opts) {
+    if (!(await fileExists(input)))
+        throw new Error(`文件不存在: ${input}`);
+    const modelKey = (opts.model || 'isnet');
+    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 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/jobs.d.ts

@@ -8,4 +8,5 @@ import type { StudioClient, Job } from '../client.js';
 export declare function jobs(client: StudioClient, opts: {
     limit?: string;
     status?: Job['status'];
+    project?: string;
 }): Promise<void>;

package/dist/commands/jobs.js

@@ -1,3 +1,4 @@
+import { resolveWorkspace } from './projects.js';
 const STATUS_MARK = {
     pending: '⏳',
     processing: '🔄',
@@ -6,7 +7,12 @@ const STATUS_MARK = {
 };
 export async function jobs(client, opts) {
     const limit = opts.limit ? Number(opts.limit) : 20;
-    const list = await client.listJobs({ limit, status: opts.status });
+    let list = await client.listJobs({ limit, status: opts.status });
+    // --project 客户端过滤：服务端 jobs 不认 workspace 参数，在最近 50 条内筛
+    if (opts.project) {
+        const ws = await resolveWorkspace(client, opts.project);
+        list = list.filter((j) => j.workspace_id === ws.id);
+    }
     if (!list.length) {
         process.stderr.write('没有找到工作流记录\n');
         console.log('[]');

package/dist/commands/projects.d.ts

@@ -0,0 +1,21 @@
+/** museav projects —— 工作区（项目）与项目素材库。
+ *  层级：平台 → 账户 → 工作区；素材挂工作区，业务隔离互不污染。
+ *  「人像库的工作区出模特图、产品库的工作区出电商图」的载体就是这里。 */
+import type { StudioClient, Workspace } from '../client.js';
+/** --project <id|名> 的解析：id 精确命中，否则按名称匹配；找不到/歧义时把可选项列出来 */
+export declare function resolveWorkspace(client: StudioClient, idOrName: string): Promise<Workspace>;
+export declare function projects(client: StudioClient): Promise<void>;
+export declare function createProject(client: StudioClient, opts: {
+    name: string;
+}): Promise<void>;
+export declare function listAssets(client: StudioClient, opts: {
+    project?: string;
+}): Promise<void>;
+export declare function addAsset(client: StudioClient, file: string, opts: {
+    project?: string;
+    name?: string;
+    tag?: string[];
+}): Promise<void>;
+export declare function removeAsset(client: StudioClient, opts: {
+    id: string;
+}): Promise<void>;

package/dist/commands/projects.js

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

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