museav-cli 2.2.0 → 2.3.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,21 @@
 # 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

@@ -322,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
@@ -424,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 {
@@ -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,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/index.js

@@ -15,6 +15,8 @@ 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 { projects, createProject, listAssets, addAsset, removeAsset } from './commands/projects.js';
 import { imageToTemplate } from './commands/image-to-template.js';
 import { upload } from './commands/upload.js';
 import { models } from './commands/models.js';
@@ -109,6 +111,18 @@ function withLazyClient(fn) {
         }
     };
 }
+// 本地命令（compress / remove-bg 等）：不碰中台、不需要任何凭证，只包一层统一的错误出口
+function asyncRun(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (e) {
+            process.stderr.write(`❌ ${e.message}\n`);
+            process.exit(1);
+        }
+    };
+}
 // products / assets 查的是租户自己后台的数据，不是 Studio 中台的，走独立的 TenantClient
 // （见 tenant-client.ts 顶部注释），只支持租户 apiKey 身份，不支持个人 login token。
 function withTenantClient(fn) {
@@ -152,7 +166,52 @@ program
     .option('--video', '生成视频（走 /api/videos 链路；模型档次如 artsdance-2-0-pro-260801，不传 --model 走 auto 路由）')
     .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
     .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')
+    .option('--project <id|名>', '归档进该工作区（museav projects 查；账户身份才生效）')
     .action(withClient((client, opts) => gen(client, opts)));
+program
+    .command('compress <file>')
+    .description('本地压缩图片（sharp，免登录）：默认同目录 <名>-min.<格式>，不覆写原文件')
+    .option('--out <path>', '输出路径（默认 <名>-min.<格式>）')
+    .option('--max-edge <px>', '最长边缩到该像素（等比，inside）')
+    .option('--quality <1-100>', 'jpg/webp 质量，默认 82')
+    .option('--format <fmt>', '输出格式 jpg / png / webp（默认跟随原格式）')
+    .option('--overwrite', '允许覆盖已存在的输出文件')
+    .action(asyncRun((input, opts) => compressCmd(input, opts)));
+program
+    .command('remove-bg <file>')
+    .description('本地抠图去背景（ISNet/U2Net + onnxruntime，免登录）：输出带 alpha 的 PNG。首次使用自动下载模型（~170MB，缓存 ~/.museav-models）')
+    .option('--out <path>', '输出路径（默认 <名>-nobg.png）')
+    .option('--model <name>', 'isnet（默认，质量优先）/ u2net')
+    .option('--overwrite', '允许覆盖已存在的输出文件')
+    .action(asyncRun((input, opts) => removeBgCmd(input, opts)));
+// 工作区（项目）与项目素材库：平台 → 账户 → 工作区三层归属，素材挂工作区
+const projectsCmd = program
+    .command('projects')
+    .description('工作区（项目）管理：一个账户多个工作区，每个工作区有自己的素材库（人像库/产品库各管各的业务）')
+    .action(withClient((client) => projects(client)));
+projectsCmd
+    .command('create')
+    .description('新建工作区（每账户最多 5 个）')
+    .requiredOption('--name <name>', '工作区名称（最多 20 字）')
+    .action(withClient((client, opts) => createProject(client, opts)));
+const assetsCmd = projectsCmd
+    .command('assets')
+    .description('项目素材库：列出 / 上传 / 删除该工作区的素材（垫图母版，不压缩）');
+assetsCmd
+    .description('列工作区素材库')
+    .option('--project <id|名>', '工作区 id 或名称（必填，不传会明确报错）')
+    .action(withClient((client, opts) => listAssets(client, opts)));
+assetsCmd
+    .command('add <file>')
+    .description('上传素材进工作区素材库（图片/音频/视频，按字节判型；母版不压缩）')
+    .requiredOption('--project <id|名>', '工作区 id 或名称')
+    .option('--name <name>', '素材名，如「白T正面」')
+    .option('--tag <tag>', '标签，可重复（产品 / 人像 / 场景…）', (v, acc) => [...acc, v], [])
+    .action(withClient((client, file, opts) => addAsset(client, file, opts)));
+assetsCmd
+    .command('rm <id>')
+    .description('删除素材（硬删：R2 对象 + 记录）')
+    .action(withClient((client, id) => removeAsset(client, { id })));
 program
     .command('reverse <input>')
     .description('读图：反推 SCULPT prompt，stdout 输出英文 prompt。主路本地 Ollama（qwen3-vl，快，无需登录）；本地不可用回落中台 API（会提示较慢）。只读图；要做成模板用 image-to-template')
@@ -235,9 +294,10 @@ program
     .action(withClient((client) => balance(client)));
 program
     .command('jobs')
-    .description('查自己名下的出图工作流（个人 login 看自己的；租户 apiKey 看业务下全部）——服务端固定返回最近 50 条，limit/status 是本地过滤')
+    .description('查自己名下的出图工作流（个人 login 看自己的；租户 apiKey 看业务下全部）——服务端固定返回最近 50 条，limit/status/project 是本地过滤')
     .option('--limit <n>', '最多显示几条（在最近 50 条以内截取），默认 20', '20')
     .option('--status <status>', '按状态过滤: pending / processing / done / failed（本地过滤，不是服务端查询）')
+    .option('--project <id|名>', '只看归档进该工作区的任务（本地过滤）')
     .action(withClient((client, opts) => jobs(client, opts)));
 program
     .command('whoami')

package/dist/local-bg.d.ts

@@ -0,0 +1,17 @@
+export declare const BG_MODELS: {
+    readonly isnet: {
+        readonly file: 'isnet-general-use.onnx';
+        readonly url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/isnet-general-use.onnx';
+        readonly label: 'ISNet（通用，质量优先）';
+    };
+    readonly u2net: {
+        readonly file: 'u2net.onnx';
+        readonly url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net.onnx';
+        readonly label: 'U2Net（经典通用）';
+    };
+};
+export type BgModelKey = keyof typeof BG_MODELS;
+/** 模型在位返回路径；不在则下载（流式，进度打 stderr）。下载失败抛 Error */
+export declare function ensureBgModel(key: BgModelKey): Promise<string>;
+/** 抠图主流程：输入图片路径 → 输出带 alpha 的 PNG Buffer */
+export declare function removeBackgroundLocal(inputPath: string, modelKey: BgModelKey): Promise<Buffer>;