museav-cli 2.1.0 → 2.3.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） */
@@ -101,7 +127,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; label: string; placeholder?: string }> }
+    duration?: number
+    aspect_ratio?: string
     is_default?: boolean
   }>
 }
@@ -132,6 +163,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
@@ -405,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' },
@@ -419,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 看得到自己业务下的全部记录。
@@ -467,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)
+}

package/src/commands/reverse.ts

@@ -1,11 +1,43 @@
-/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt） */
-import type { StudioClient } from '../client.js'
+/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt）。
+ *  主路是本地 Ollama（qwen3-vl），快、零成本、无需登录；中台 API 是回落路，走回落时会明确提示较慢。
+ *  client 懒构造（getClient）：本地路成功就完全不碰中台凭证。
+ *  本地系统的 AI 能力统一收口在这个 CLI，reverse 是第一个本地化的能力。 */
+import type { StudioClient, ReverseResult } from '../client.js'
+import { checkLocalVlm, reverseLocally, LOCAL_VLM_MODEL } from '../local-vision.js'
 
-export async function reverse(client: StudioClient, input: string): Promise<void> {
-  // 输入是文件路径还是 URL
+export async function reverse(
+  getClient: () => StudioClient,
+  input: string,
+  opts: { api?: boolean } = {},
+): Promise<void> {
   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: ReverseResult): void {
   process.stderr.write(`✅ 逆向完成\n\n`)
   process.stderr.write(`风格: ${result.zh_name || '-'}  比例: ${result.aspect_ratio}\n`)
   process.stderr.write(`标签: ${result.style_tags.join(', ')}\n\n`)

package/src/commands/templates.ts

@@ -19,7 +19,8 @@ export async function templates(client: StudioClient, opts: { category?: string;
   process.stderr.write(`可用模板（${list.length} 个）:\n`)
   for (const t of list) {
     const cfg = t.generation_configs?.find((c) => c.is_default) || t.generation_configs?.[0]
-    const fields = cfg?.params_json?.fields || []
+    // fields 新契约在 config 顶层（CLI 自己 create 就写顶层），老数据在 params_json 里——两种都兜
+    const fields = cfg?.fields || cfg?.params_json?.fields || []
     const fieldHint = fields.length ? `字段:${fields.map((f) => f.key).join(',')}` : ''
     process.stderr.write(
       `  ${t.id.padEnd(38)} ${(t.zh_name || '').padEnd(16)} ${(t.category || '').padEnd(10)} ${(t.ratio || '').padEnd(6)} ${typeTag(t).padEnd(8)} ${fieldHint.padEnd(20)} ${tag(t)}\n`,

package/src/commands/video-templates.ts

@@ -19,8 +19,9 @@ export async function videoTemplates(client: StudioClient, opts: { category?: st
     const cfg = t.generation_configs?.find((c) => c.is_default) || t.generation_configs?.[0]
     const modelHint = cfg?.model ? `模型:${cfg.model}` : ''
     const ratioHint = t.ratio || ''
-    const fieldCount = cfg?.params_json?.fields?.length || 0
-    const fieldHint = fieldCount ? `字段:${cfg!.params_json!.fields!.map((f) => f.key).join(',')}` : ''
+    // fields 新契约在 config 顶层，老数据在 params_json 里——两种都兜，否则自己建的模板自己列不出来
+    const fields = cfg?.fields || cfg?.params_json?.fields || []
+    const fieldHint = fields.length ? `字段:${fields.map((f) => f.key).join(',')}` : ''
     const sampleHint = t.sample_video_url ? '有参考视频' : ''
     process.stderr.write(
       `  ${t.id.padEnd(38)} ${(t.zh_name || '').padEnd(20)} ${(t.category || '').padEnd(10)} ${ratioHint.padEnd(6)} ${modelHint.padEnd(30)} ${fieldHint.padEnd(24)} ${sampleHint.padEnd(10)} ${tag(t)}\n`,
@@ -36,6 +37,8 @@ export async function videoTemplates(client: StudioClient, opts: { category?: st
 
 interface CreateVideoTemplateOpts {
   name: string
+  /** 对外调用标识，全局唯一。不给就自动生成一个（vt- 前缀） */
+  slug?: string
   prompt: string
   category?: string
   description?: string
@@ -53,25 +56,32 @@ export async function createVideoTemplate(client: StudioClient, opts: CreateVide
   if (!opts.name?.trim()) throw new Error('--name 必填')
   if (!opts.prompt?.trim()) throw new Error('--prompt 必填，占位符用 {key} 形式，如 "{product} 在 {scene} 中展示"')
 
+  // slug 是视频模板的硬必填（服务端 required=['zh_name','slug']），漏了必 400。
+  // 中文名大多是中文没法直接转 slug，不给 --slug 就生成一个 vt- 短标识，撞了让服务端报出来再换。
+  const slug = (opts.slug || `vt-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 5)}`).trim()
+  if (!/^[\w-]+$/.test(slug)) throw new Error('--slug 只能包含字母、数字、下划线和连字符')
+
   // 占位符必须声明 fields（中台 validateConfig 硬校验：prompt 里有 {key} 但没 fields 会被拒）
   const keys = Array.from(new Set(Array.from(opts.prompt.matchAll(/\{(\w+)\}/g), (m) => m[1])))
   const fields = keys.map((key) => ({ key, label: key }))
 
   const cfg: Record<string, unknown> = {
-    model: opts.model || 'seedance-2',
+    // 默认 auto：交给中台路由按 ratio/duration 挑档次。锁死具体模型得自己保证参数配得上它
+    model: opts.model || 'auto',
     prompt_template: opts.prompt,
     is_default: true,
   }
   if (fields.length) cfg.fields = fields
   if (opts.duration) {
     const d = Number(opts.duration)
-    if (!Number.isFinite(d) || d < 4 || d > 15) throw new Error('--duration 必须是 4-15 之间的数字（秒）')
+    if (!Number.isFinite(d) || d < 4 || d > 30) throw new Error('--duration 必须是 4-30 之间的数字（秒；Seedance 2.0 系上限 15，2.5 到 30，具体由中台按模型校验）')
     cfg.duration = d
   }
   if (opts.ratio) cfg.aspect_ratio = opts.ratio
 
   const row = await client.createVideoTemplate({
     zh_name: opts.name,
+    slug,
     category: opts.category,
     description: opts.description,
     sample_video_url: opts.sampleVideo || null,
@@ -80,6 +90,7 @@ export async function createVideoTemplate(client: StudioClient, opts: CreateVide
   })
 
   process.stderr.write(`✅ 视频模板已建：${row.id}\n`)
+  process.stderr.write(`slug: ${slug}\n`)
   process.stderr.write(`归属：${row.tenant_id ? '当前租户（其他租户看不到）' : '平台共享（所有租户可见）'}\n`)
   process.stderr.write(`模型: ${cfg.model} 时长: ${cfg.duration || '模板默认'} 比例: ${cfg.aspect_ratio || '模板默认'}\n`)
   if (fields.length) process.stderr.write(`占位符字段: ${fields.map((f) => f.key).join(', ')}\n`)