museav-cli 2.1.0 → 2.3.0

package/AGENTS.md

@@ -19,8 +19,10 @@ Don't try both — whichever credential is present is what gets used (env var `S
 # Generate an image, wait for it, get the URL on stdout
 museav gen --prompt 'a poster, neon lights, cyberpunk' --ratio 9:16
 
-# Generate a video (文生视频/图生视频), wait, get the mp4 URL on stdout
-museav gen --video --prompt 'a cat stretching on a windowsill, cinematic' --model seedance-2-fast --ratio 9:16
+# Generate a video (文生视频/图生视频), wait, get the mp4 URL on stdout.
+# Omit --model to let the platform route automatically (auto); pinning a tier uses
+# artsdance-* ids like artsdance-2-0-pro-260801 (Seedance 2.0).
+museav gen --video --prompt 'a cat stretching on a windowsill, cinematic' --ratio 9:16
 museav gen --video --image logo.png --prompt 'logo glows slowly, background fades' --ratio 1:1
 
 # Generate from a pre-configured image template instead of a raw prompt (deterministic
@@ -37,6 +39,10 @@ museav gen --template <id> --fields '{"artist":"name","city":"place"}'
 museav templates create --name '演唱会海报' --prompt '{artist} 在 {city} 的演唱会海报' --ratio 9:16
 
 # Reverse-engineer a prompt from an existing image (stdout: English prompt only).
+# PRIMARY path is LOCAL: Ollama qwen3-vl — fast, free, NO login needed. Falls back to
+# the platform API (with a slowness warning) only if Ollama isn't running or the model
+# is missing. Image URLs always go to the API (local path takes file paths only);
+# --api forces the API path.
 # This READS the image and nothing else — it will NOT build a template. Passing any
 # template-ish flag to the underlying API is a hard 400 since 2026-08-16.
 museav reverse ./photo.png
@@ -53,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
 
@@ -75,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,36 @@
 # 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，回落时明确提示较慢，缺什么会告诉你补什么命令。
+
+- 一次性配置：`brew install ollama && brew services start ollama && ollama pull qwen3-vl:8b`（Intel Mac / Linux 用官方安装脚本同理）。换模型档位设 `MUSEAV_LOCAL_VLM`（如 `qwen3-vl:4b`，更快、识图质量略降），自定服务地址走标准 `OLLAMA_HOST`。
+- SCULPT 提示词从中台移植，砍掉本地不消费的 genre / body_md；返回归一化后与 API 路完全同构，`$(museav reverse x.png)` 管线用法不变，stdout 仍只出英文 prompt。
+- 读图前复用上传同款压缩（压到视觉模型够用的尺寸），本地推理也跟着快。
+- URL 输入固定走中台 API（本地路只收文件路径）；`--api` 强制走中台。
+- 本地路完全不需要中台凭证——未登录也能用，只有真回落 API 时才提示登录。
+
+**修复 `video-templates create` 必被 400 拒**：中台视频模板契约硬性要求 `slug`（required=['zh_name','slug']），且 toapis 2026-08-14 下线后 CLI 默认的 `seedance-2` 成了悬空引用——不带参数建视频模板必挂。现在 `--slug` 缺省自动生成 `vt-` 短标识并在 stderr 回显，默认模型改 `auto`（交给中台路由），`--duration` 放宽到 4-30（Seedance 2.5 支持到 30 秒）。
+
+- `templates` / `video-templates` 列表兼容读 config 顶层的 `fields`（现行契约存法——CLI 自己 create 写的就是顶层，之前自己建的模板自己都列不出字段）。
+- `gen` / `video-templates` 帮助文案与 README / AGENTS.md 示例里已下线的 `seedance-2-*` 代号全部清掉，照旧文案传参会 400。
+
 ## 2.0.0 · 2026-08-16
 
 **改名：npm 包 `museav-cli`，命令 `museav`。** 产品叫 MUSE AV，命令却叫另一个名字，同一个东西两个叫法——这次统一到产品名。

package/README.md

@@ -172,8 +172,8 @@ museav gen --prompt '把这只鞋抠成透明底' --ref shoe.jpg --transparent
 #     （白底图看起来完全正常，静默降级只会让你以为提示词没写对，反复重试）
 #   · 会强制 PNG 输出：JPEG / 有损 WebP 没有 alpha 通道，装不下透明
 
-# 文生视频（模型如 seedance-2-fast / artsdance-2-0-pro-260801，自动轮询直到完成）
-museav gen --video --prompt '一只橘猫在窗台上伸懒腰，阳光洒进来，电影感' --model seedance-2-fast --ratio 9:16
+# 文生视频（不传 --model 走 auto 路由；锁死档次用 artsdance-2-0-pro-260801 这类代号，自动轮询直到完成）
+museav gen --video --prompt '一只橘猫在窗台上伸懒腰，阳光洒进来，电影感' --ratio 9:16
 
 # 图生视频（--image 传首帧图，自动上传）
 museav gen --video --image logo.png --prompt 'logo 缓缓发光，背景渐暗' --ratio 1:1
@@ -237,17 +237,24 @@ museav gen --template "$ID" --fields '{"artist":"..."}'
 
 ### 图片逆向 `reverse`
 
-上传一张图，中台用 **SCULPT 六要素**（主体/构图/世界观/光影/输出/质感）逆推出图 prompt，可以直接拿去再出一张同风格的：
+逆推出图 prompt，可以直接拿去再出一张同风格的。**主路是本地 Ollama（qwen3-vl）**：快、零成本、无需登录；本地不可用时自动回落中台 API（SCULPT 六要素：主体/构图/世界观/光影/输出/质感），回落时会明确提示较慢：
 
 ```bash
-# 本地文件或图片 URL 都行
+# 本地文件走本地模型（推荐，无需登录）
 museav reverse photo.png
+
+# 图片 URL 没法喂本地模型，走中台 API（需登录）
 museav reverse https://example.com/photo.png
 
+# 强制走中台 API（跳过本地，慢，需登录）
+museav reverse photo.png --api
+
 # 逆向 + 出图，一条龙
 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 把这两件事
@@ -315,6 +322,43 @@ 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`）。
+
+### 项目（工作区）与项目素材库 `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
@@ -417,6 +461,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 {
@@ -51,6 +75,12 @@ export interface TemplateOption {
         model: string;
         prompt_template: string;
         ref_slots?: string[];
+        /** 表单字段声明——现行契约放 config 顶层（服务端 validateConfig 读这里） */
+        fields?: Array<{
+            key: string;
+            label: string;
+        }>;
+        /** 旧存法：fields 曾在 params_json 里，老模板还这么存，读时两种都要兜 */
         params_json?: {
             fields?: Array<{
                 key: string;
@@ -58,6 +88,8 @@ export interface TemplateOption {
                 placeholder?: string;
             }>;
         };
+        duration?: number;
+        aspect_ratio?: string;
         is_default?: boolean;
     }>;
 }
@@ -89,6 +121,8 @@ export interface CreateTemplateInput {
  *  ratio/duration/model 放在 generation_configs 每项里。 */
 export interface CreateVideoTemplateInput {
     zh_name: string;
+    /** 对外调用标识，视频模板硬必填（服务端 validateCore required=['zh_name','slug']），全局唯一 */
+    slug: string;
     category?: string;
     description?: string;
     sample_video_url?: string | null;
@@ -300,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 看得到自己业务下的全部记录。
@@ -329,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,16 @@
+/** 默认输出路径：同目录 <名字>-<后缀>.<新扩展名>。绝不覆写输入文件 */
+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>;

package/dist/commands/img-tools.js

@@ -0,0 +1,81 @@
+/** 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';
+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);
+}

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,3 +1,8 @@
-/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt） */
+/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt）。
+ *  主路是本地 Ollama（qwen3-vl），快、零成本、无需登录；中台 API 是回落路，走回落时会明确提示较慢。
+ *  client 懒构造（getClient）：本地路成功就完全不碰中台凭证。
+ *  本地系统的 AI 能力统一收口在这个 CLI，reverse 是第一个本地化的能力。 */
 import type { StudioClient } from '../client.js';
-export declare function reverse(client: StudioClient, input: string): Promise<void>;
+export declare function reverse(getClient: () => StudioClient, input: string, opts?: {
+    api?: boolean;
+}): Promise<void>;

package/dist/commands/reverse.js

@@ -1,7 +1,33 @@
-export async function reverse(client, input) {
-    // 输入是文件路径还是 URL
+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) {
+        const status = await checkLocalVlm();
+        if (status.running && status.modelPresent) {
+            try {
+                const start = Date.now();
+                const result = await reverseLocally(input);
+                process.stderr.write(`✓ 本地 Ollama（${LOCAL_VLM_MODEL}）用时 ${((Date.now() - start) / 1000).toFixed(1)}s\n`);
+                renderReverse(result);
+                return;
+            }
+            catch (e) {
+                process.stderr.write(`⚠ 本地读图失败（${e instanceof Error ? e.message : e}），回落中台 API —— 速度较慢，请耐心等待\n`);
+            }
+        }
+        else {
+            process.stderr.write(`⚠ 本地读图不可用（${status.reason}），回落中台 API —— 速度较慢，请耐心等待\n`);
+        }
+    }
+    else if (!opts.api && isUrl) {
+        process.stderr.write(`ℹ URL 输入走中台 API（本地路只收文件路径）\n`);
+    }
+    const client = getClient();
     const result = await client.reverse(isUrl ? { imageUrl: input } : { file: input });
+    renderReverse(result);
+}
+/** 两条路产出同构，渲染只写一份 */
+function renderReverse(result) {
     process.stderr.write(`✅ 逆向完成\n\n`);
     process.stderr.write(`风格: ${result.zh_name || '-'}  比例: ${result.aspect_ratio}\n`);
     process.stderr.write(`标签: ${result.style_tags.join(', ')}\n\n`);