museav-cli 2.2.0 → 2.3.0

package/dist/local-bg.js

@@ -0,0 +1,143 @@
+/**
+ * 本地抠图（去背景）—— remove-bg 的核心实现。
+ * 模型走 ONNX（ISNet / U2Net，均 Apache-2.0），推理走 onnxruntime-node（MIT），
+ * 前后处理走 sharp —— 整条链路许可证干净（imgly 那个 npm 包是 AGPL，不进依赖），
+ * 且三个依赖在 macOS / Windows / Linux 都有预编译，无平台特化代码。
+ * 模型文件首次使用时下载到 ~/.museav-models/ 缓存（一次性 ~170MB）。
+ */
+import { mkdir, writeFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+export const BG_MODELS = {
+    isnet: {
+        file: 'isnet-general-use.onnx',
+        // rembg 官方 release 托管的同一份模型（Apache-2.0，源自 xuebinqin/DIS）
+        url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/isnet-general-use.onnx',
+        label: 'ISNet（通用，质量优先）',
+    },
+    u2net: {
+        file: 'u2net.onnx',
+        url: 'https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net.onnx',
+        label: 'U2Net（经典通用）',
+    },
+};
+const MODEL_DIR = join(homedir(), '.museav-models');
+const INPUT_EDGE = 1024;
+function modelPath(key) {
+    return join(MODEL_DIR, BG_MODELS[key].file);
+}
+/** 模型在位返回路径；不在则下载（流式，进度打 stderr）。下载失败抛 Error */
+export async function ensureBgModel(key) {
+    const dest = modelPath(key);
+    try {
+        const s = await stat(dest);
+        if (s.size > 10_000_000)
+            return dest; // 正常模型都是百 MB 级；太小的文件视为残缺重下
+    }
+    catch {
+        // 不存在，走下载
+    }
+    await mkdir(MODEL_DIR, { recursive: true });
+    const def = BG_MODELS[key];
+    process.stderr.write(`↓ 首次使用，下载 ${def.label}（~170MB，一次性，缓存到 ${MODEL_DIR}）...\n`);
+    const resp = await fetch(def.url);
+    if (!resp.ok || !resp.body)
+        throw new Error(`模型下载失败 HTTP ${resp.status}：${def.url}`);
+    const total = Number(resp.headers.get('content-length') || 0);
+    const chunks = [];
+    let got = 0;
+    const reader = resp.body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(Buffer.from(value));
+        got += value.length;
+        if (total)
+            process.stderr.write(`  ${((got / total) * 100).toFixed(0)}%\r`);
+    }
+    process.stderr.write('\n');
+    const buf = Buffer.concat(chunks);
+    if (buf.length < 10_000_000)
+        throw new Error('模型下载不完整，请重试');
+    await writeFile(dest, buf);
+    return dest;
+}
+/** 抠图主流程：输入图片路径 → 输出带 alpha 的 PNG Buffer */
+export async function removeBackgroundLocal(inputPath, modelKey) {
+    // 动态加载：onnxruntime-node 是 optionalDependency，缺失时给安装指引而不是崩
+    let ort;
+    try {
+        ort = await import('onnxruntime-node');
+    }
+    catch {
+        throw new Error('onnxruntime-node 不可用。重装 CLI 即可补上：npm install -g museav-cli');
+    }
+    const sharp = await loadSharpOrThrow();
+    const modelFile = await ensureBgModel(modelKey);
+    const session = await ort.InferenceSession.create(modelFile);
+    // ── 预处理：EXIF 转正、去 alpha、RGB raw ──
+    const { data: rgb, info } = await sharp(inputPath).rotate().removeAlpha().raw().toBuffer({ resolveWithObject: true });
+    if (info.channels !== 3)
+        throw new Error(`预处理得到 ${info.channels} 通道（预期 3）`);
+    // ── 模型输入：拉伸到 1024×1024，(x/255 - 0.5)/0.5 归一化，HWC → CHW ──
+    const small = await sharp(rgb, { raw: { width: info.width, height: info.height, channels: 3 } })
+        .resize(INPUT_EDGE, INPUT_EDGE, { fit: 'fill' })
+        .raw()
+        .toBuffer();
+    const f32 = new Float32Array(3 * INPUT_EDGE * INPUT_EDGE);
+    const N = INPUT_EDGE * INPUT_EDGE;
+    for (let i = 0; i < N; i++) {
+        f32[i] = (small[i * 3] / 255 - 0.5) / 0.5;
+        f32[N + i] = (small[i * 3 + 1] / 255 - 0.5) / 0.5;
+        f32[2 * N + i] = (small[i * 3 + 2] / 255 - 0.5) / 0.5;
+    }
+    const feeds = {};
+    feeds[session.inputNames[0]] = new ort.Tensor('float32', f32, [1, 3, INPUT_EDGE, INPUT_EDGE]);
+    const results = await session.run(feeds);
+    const out = results[session.outputNames[0]];
+    const maskFlat = out.data;
+    if (maskFlat.length < N)
+        throw new Error(`模型输出尺寸异常（${maskFlat.length}）`);
+    // ── 后处理：min-max 归一化到 0-255，再缩回原图尺寸 ──
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (let i = 0; i < N; i++) {
+        const v = maskFlat[i];
+        if (v < lo)
+            lo = v;
+        if (v > hi)
+            hi = v;
+    }
+    const range = hi - lo || 1;
+    const mask8 = Buffer.alloc(N);
+    for (let i = 0; i < N; i++)
+        mask8[i] = Math.round(((maskFlat[i] - lo) / range) * 255);
+    const maskFull = await sharp(mask8, { raw: { width: INPUT_EDGE, height: INPUT_EDGE, channels: 1 } })
+        .resize(info.width, info.height, { fit: 'fill' })
+        .raw()
+        .toBuffer();
+    // ── alpha 合成：直接构造 RGBA（alpha = mask），不依赖 composite 的混合语义 ──
+    const w = info.width;
+    const h = info.height;
+    const rgba = Buffer.alloc(w * h * 4);
+    for (let i = 0; i < w * h; i++) {
+        rgba[i * 4] = rgb[i * 3];
+        rgba[i * 4 + 1] = rgb[i * 3 + 1];
+        rgba[i * 4 + 2] = rgb[i * 3 + 2];
+        rgba[i * 4 + 3] = maskFull[i];
+    }
+    return sharp(rgba, { raw: { width: w, height: h, channels: 4 } }).png().toBuffer();
+}
+async function loadSharpOrThrow() {
+    try {
+        const m = await import('sharp');
+        const sharp = m.default ?? m;
+        // 造 1px 图跑通全链路：native binding 坏了在第一次真用时才炸，这里提前暴露
+        await sharp({ create: { width: 1, height: 1, channels: 3, background: '#000' } }).raw().toBuffer();
+        return sharp;
+    }
+    catch {
+        throw new Error('sharp 不可用。重装 CLI 即可补上：npm install -g museav-cli');
+    }
+}

package/dist/local-vision.js

@@ -16,6 +16,14 @@ function ollamaHost() {
         host = `http://${host}`;
     return host.replace(/\/+$/, '');
 }
+// 各系统启动 Ollama 的正确姿势不同，提示语跟着平台走（Windows 没有 brew）
+function ollamaStartHint() {
+    if (process.platform === 'win32')
+        return '启动 Ollama 应用（开始菜单 / Ollama.exe），或命令行运行 ollama serve';
+    if (process.platform === 'darwin')
+        return 'brew services start ollama，或 ollama serve';
+    return 'systemctl --user start ollama，或 ollama serve';
+}
 /** 探活 + 模型在位检查。3 秒探不通就是没起服务，不等推理超时才发现 */
 export async function checkLocalVlm() {
     const host = ollamaHost();
@@ -32,7 +40,7 @@ export async function checkLocalVlm() {
         return { running: true, modelPresent: true, host };
     }
     catch {
-        return { running: false, modelPresent: false, host, reason: `Ollama 未运行（${host}），启动: ollama serve 或 brew services start ollama` };
+        return { running: false, modelPresent: false, host, reason: `Ollama 未运行（${host}），${ollamaStartHint()}` };
     }
 }
 /** SCULPT 系统提示词 —— 从中台 reverse-template.js 移植。本地路只做纯读图，

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "museav-cli",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "MUSE AV 出图中台官方 CLI —— 命令行调中台 API 出图、出视频、读图逆向、图生模板",
   "type": "module",
   "bin": {
@@ -53,6 +53,7 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.3",
+    "onnxruntime-node": "^1.27.0"
   }
 }

package/src/client.ts

@@ -80,6 +80,32 @@ 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） */
@@ -412,6 +438,8 @@ export class StudioClient {
     if (opts.reference_images?.length) body.reference_images = opts.reference_images
     if (opts.quality) 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' },
@@ -426,6 +454,49 @@ export class StudioClient {
     return r
   }
 
+  // ── 工作区（项目）与项目素材库 ──
+  // 平台 → 账户 → 工作区三层归属；素材挂工作区，换业务换工作区，互不污染。
+
+  /** 列当前账户的工作区（含生成统计） */
+  async workspaces(): Promise<Workspace[]> {
+    return this.request('workspaces')
+  }
+
+  /** 新建工作区（最多 5 个，超了服务端会 400） */
+  async createWorkspace(name: string): Promise<Workspace> {
+    return this.request('workspaces', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name }) })
+  }
+
+  /** 列某工作区的素材库 */
+  async workspaceAssets(workspaceId: string): Promise<WorkspaceAsset[]> {
+    return this.request(`workspace-assets?workspace_id=${encodeURIComponent(workspaceId)}`)
+  }
+
+  /** 上传素材进工作区素材库。素材是母版，**不做视觉压缩**（fileForm 那套压缩是给模型看的） */
+  async addWorkspaceAsset(input: {
+    file: string
+    workspaceId: string
+    name?: string
+    tags?: string[]
+  }): Promise<WorkspaceAsset> {
+    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: string): Promise<void> {
+    await this.request('workspace-assets', {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id }),
+    })
+  }
+
   /**
    * 列出当前身份名下的出图工作流（不传 id，走同一个 jobs 端点的集合语义）。
    * 范围由鉴权凭证决定：个人 token 只看得到自己出的图；租户 apiKey 看得到自己业务下的全部记录。
@@ -474,19 +545,22 @@ export class StudioClient {
      duration?: number
      /** 图生视频：首帧/参考图 URL（中台内部自动上传垫图后拿到 URL 再传这里） */
      image_url?: string
-     template_id?: string
-     input?: string | Record<string, string>
-     callback_url?: string
-   }): Promise<{ jobId: string; upstreamTaskId?: string }> {
-     const body: Record<string, unknown> = {}
-     if (opts.prompt) body.prompt = opts.prompt
-     if (opts.model) body.model = opts.model
-     if (opts.ratio) body.ratio = opts.ratio
-     if (opts.duration != null) body.duration = opts.duration
-     if (opts.image_url) body.image_url = opts.image_url
-     if (opts.template_id) body.template_id = opts.template_id
-     if (opts.input) body.input = opts.input
-     if (opts.callback_url) body.callback_url = opts.callback_url
+    template_id?: string
+    input?: string | Record<string, string>
+    callback_url?: string
+    /** 项目归档（账户身份才生效） */
+    workspace_id?: string
+  }): Promise<{ jobId: string; upstreamTaskId?: string }> {
+    const body: Record<string, unknown> = {}
+    if (opts.prompt) body.prompt = opts.prompt
+    if (opts.model) body.model = opts.model
+    if (opts.ratio) body.ratio = opts.ratio
+    if (opts.duration != null) body.duration = opts.duration
+    if (opts.image_url) body.image_url = opts.image_url
+    if (opts.template_id) body.template_id = opts.template_id
+    if (opts.input) 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/src/commands/gen.ts

@@ -1,5 +1,6 @@
 /** museav gen —— 出图 / 出视频（核心命令） */
 import type { StudioClient } from '../client.js'
+import { resolveWorkspace } from './projects.js'
 
 /** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
 const MAX_REFS = 5
@@ -15,6 +16,7 @@ export async function gen(client: StudioClient, opts: {
   quality?: string
   ref?: string[]      // 可重复：--ref a.jpg --ref b.jpg，顺序即「图片1、图片2…」
   transparent?: boolean   // 透明背景 PNG；能不能做由中台按上游能力判定，做不了会明确报错
+  project?: string    // 工作区 id|名：生成结果归档进该项目（账户身份才生效）
   // 视频
   video?: boolean
   duration?: number
@@ -63,6 +65,13 @@ export async function gen(client: StudioClient, opts: {
   if (refPaths.length) {
     const urls: string[] = []
     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)
@@ -72,6 +81,9 @@ export async function gen(client: StudioClient, opts: {
     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) throw new Error('--quality 仅图片出图支持')
@@ -87,6 +99,7 @@ export async function gen(client: StudioClient, 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) => {
@@ -123,6 +136,7 @@ export async function gen(client: StudioClient, opts: {
       // 开关 → 枚举：CLI 这层用布尔开关最顺手，中台契约是 background: transparent|opaque
       // （跟上游 gpt-image 的参数同名同值）。不传就不发，行为跟以前完全一样。
       background: opts.transparent ? 'transparent' : undefined,
+      workspace_id: workspaceId,
     },
     (status) => {
       if (status === 'processing') process.stderr.write('生成中...\r')

package/src/commands/img-tools.ts

@@ -0,0 +1,95 @@
+/** 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, type BgModelKey } from '../local-bg.js'
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile()
+  } catch {
+    return false
+  }
+}
+
+function fmtBytes(n: number): string {
+  return n >= 1048576 ? `${(n / 1048576).toFixed(2)}MB` : `${(n / 1024).toFixed(1)}KB`
+}
+
+/** 默认输出路径：同目录 <名字>-<后缀>.<新扩展名>。绝不覆写输入文件 */
+export function defaultOut(input: string, suffix: string, newExt?: string): string {
+  const ext = newExt || extname(input).slice(1) || 'png'
+  return join(dirname(input), `${basename(input, extname(input))}-${suffix}.${ext}`)
+}
+
+export interface CompressOpts {
+  out?: string
+  maxEdge?: string
+  quality?: string
+  format?: string
+  overwrite?: boolean
+}
+
+export async function compressCmd(input: string, opts: CompressOpts): Promise<void> {
+  if (!(await fileExists(input))) throw new Error(`文件不存在: ${input}`)
+
+  let sharp: any
+  try {
+    const m = await import('sharp')
+    sharp = (m as any).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 interface RemoveBgOpts {
+  out?: string
+  model?: string
+  overwrite?: boolean
+}
+
+export async function removeBgCmd(input: string, opts: RemoveBgOpts): Promise<void> {
+  if (!(await fileExists(input))) throw new Error(`文件不存在: ${input}`)
+  const modelKey = (opts.model || 'isnet') as BgModelKey
+  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/src/commands/jobs.ts

@@ -5,6 +5,7 @@
  * 不需要额外传租户/用户 id——你拿的是谁的凭证，就是谁的数据。
  */
 import type { StudioClient, Job } from '../client.js'
+import { resolveWorkspace } from './projects.js'
 
 const STATUS_MARK: Record<Job['status'], string> = {
   pending: '⏳',
@@ -13,9 +14,14 @@ const STATUS_MARK: Record<Job['status'], string> = {
   failed: '❌',
 }
 
-export async function jobs(client: StudioClient, opts: { limit?: string; status?: Job['status'] }): Promise<void> {
+export async function jobs(client: StudioClient, opts: { limit?: string; status?: Job['status']; project?: string }): Promise<void> {
   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 as unknown as { workspace_id?: string | null }).workspace_id === ws.id)
+  }
 
   if (!list.length) {
     process.stderr.write('没有找到工作流记录\n')

package/src/commands/projects.ts

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