museav-cli 2.0.0

package/src/index.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * museav —— MUSE AV 出图中台 CLI
+ *
+ * 用法见 README。注册中台：museav config --baseUrl ... --apiKey ...
+ */
+import { readFileSync, writeFileSync, chmodSync } from 'node:fs'
+import { Command } from 'commander'
+import updateNotifier from 'update-notifier'
+import { StudioClient } from './client.js'
+import { TenantClient } from './tenant-client.js'
+import { loadConfig, saveConfig, clearToken } from './config.js'
+import { login } from './commands/login.js'
+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 { imageToTemplate } from './commands/image-to-template.js'
+import { upload } from './commands/upload.js'
+import { models } from './commands/models.js'
+import { skills } from './commands/skills.js'
+import { templates, createTemplate } from './commands/templates.js'
+import { videoTemplates, createVideoTemplate } from './commands/video-templates.js'
+import { balance } from './commands/balance.js'
+import { jobs } from './commands/jobs.js'
+import { whoami } from './commands/whoami.js'
+import { products } from './commands/products.js'
+import { assets } from './commands/assets.js'
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')) as { name: string; version: string }
+// 每 12 小时最多查一次 npm registry，过期才提示，不拖慢日常调用
+updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 12 }).notify({ defer: false })
+
+/**
+ * 首次运行欢迎语：只在第一次执行时提示一次（用环境变量 XHS_ONCE 防止在同一会话里重复输出），
+ * 之后靠 ~/.museav.json 里的 welcome_seen 标记跳过。不打断正常输出（写 stderr）。
+ */
+function maybeWelcome(): void {
+  try {
+    if (process.env.MUSEAV_NO_WELCOME === '1' || process.env.STUDIO_NO_WELCOME === '1') return
+    const file = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')) as { version: string }
+    const CONFIG_PATH = process.env.HOME + '/.museav.json'
+    let cfg: Record<string, unknown> = {}
+    try { cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')) } catch { /* 首次运行还没有配置 */ }
+    if (cfg.welcome_seen) return
+    process.stderr.write(
+      `\n🎨 感谢使用 museav v${file.version}（MUSE AV 出图中台）\n` +
+      `   有需求 / 反馈 / 合作？小红书关注「山鬼映画」找我：东方电影美学 · 把不存在的武侠电影做成江湖\n` +
+      `   → https://www.xiaohongshu.com/user/profile/5c3c1581000000000501835d\n\n`,
+    )
+    // 标记已看过（写入失败也无所谓，最多下次再提示一次）
+    try {
+      cfg.welcome_seen = true
+      writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 })
+      chmodSync(CONFIG_PATH, 0o600)
+    } catch { /* ignore */ }
+  } catch { /* 欢迎语失败绝不阻塞任何命令 */ }
+}
+maybeWelcome()
+
+const program = new Command()
+
+program
+  .name('museav')
+  .description('MUSE AV 出图中台 CLI —— login 登录后即可命令行出图、出视频、读图逆向、图生模板')
+  .version(pkg.version)
+  // templates 有子命令 create，且父子都用了 --category（一个是列表过滤，一个是新建模板的分类）。
+  // commander 默认不区分参数出现在父命令还是子命令段，会把 --category 的值吞给父命令、
+  // 子命令读到 undefined（已用 templates create 实测复现）。开这个选项后，参数按位置归属
+  // 所在的命令段解析，同名 flag 在父子命令里就不会互相打架。
+  .enablePositionalOptions()
+
+// 工厂：加载配置 + 构造 client，把 commander 透传的参数转给命令
+function withClient<T extends (...args: any[]) => Promise<any>>(fn: T) {
+  return async (...args: any[]) => {
+    try {
+      const cfg = loadConfig()
+      const client = new StudioClient(cfg)
+      // commander action 参数固定形如 (...positionalArgs, options, command)。
+      // 之前直接 args.slice(0, -2) 想留下 positionalArgs、丢掉 options+command，
+      // 但纯 --flag、没有 <positional> 的命令（如 gen）总共只有 2 个参数
+      // (options, command)，slice(0, -2) 会把 options 也一起丢掉——gen(client, opts)
+      // 里的 opts 变成 undefined，读 opts.prompt 直接崩。这里显式取出 options，
+      // 拼在 positional 之后转发，对没声明 options 的命令（reverse/upload/models
+      // 等）只是多传一个不会被用到的参数，无影响。
+      const opts = args[args.length - 2]
+      const positional = args.slice(0, -2)
+      await fn(client, ...positional, opts)
+    } catch (e) {
+      process.stderr.write(`❌ ${(e as Error).message}\n`)
+      process.exit(1)
+    }
+  }
+}
+
+// products / assets 查的是租户自己后台的数据，不是 Studio 中台的，走独立的 TenantClient
+// （见 tenant-client.ts 顶部注释），只支持租户 apiKey 身份，不支持个人 login token。
+function withTenantClient<T extends (...args: any[]) => Promise<any>>(fn: T) {
+  return async (...args: any[]) => {
+    try {
+      const cfg = loadConfig()
+      if (!cfg.apiKey) {
+        throw new Error(
+          'products / assets 只支持租户 API Key 身份：museav config --apiKey sk-studio-xxx\n' +
+          '（业务中台服务 key，统一形态 sk-studio-<24位>；个人 login 拿到的是个人 token，查不了组织级的产品/素材数据）',
+        )
+      }
+      const client = new TenantClient({ apiKey: cfg.apiKey, tenantBaseUrl: cfg.tenantBaseUrl })
+      const opts = args[args.length - 2]
+      const positional = args.slice(0, -2)
+      await fn(client, ...positional, opts)
+    } catch (e) {
+      process.stderr.write(`❌ ${(e as Error).message}\n`)
+      process.exit(1)
+    }
+  }
+}
+
+program
+  .command('gen')
+  .description('出图 / 出视频（提交 + 自动轮询，成功输出 URL）')
+  .option('-p, --prompt <text>', '完整出图提示词（与 --skill / --template 三选一）')
+  .option('-s, --skill <slug>', '用中台技能出图，提示词在服务端展开（与 --prompt / --template 三选一）；清单见 museav skills')
+  .option('-i, --input <text>', '配合 --skill 的一句业务描述，如「米白色针织衫」；不给则按技能规范自由发挥')
+  .option('-t, --template <id>', '用图片模板出图，提示词在服务端展开（与 --prompt / --skill 三选一）；清单见 museav templates')
+  .option('--fields <json>', '配合 --template 的占位符取值，JSON 对象，如 \'{"artist":"王嘉尔"}\'；模板没有占位符则不用传')
+  // 不设默认值：--skill / --template 场景下要让技能/模板自己的比例生效，
+  // CLI 强填默认值会把它们覆盖掉（服务端在纯 --prompt 场景已有 3:4 兜底，这里不用重复兜底）
+  .option('-r, --ratio <ratio>', '宽高比: 3:4 / 9:16 / 1:1 / 4:3 / 16:9（不指定则用技能/模板自己的比例，纯 prompt 模式兜底 3:4）')
+  .option('-m, --model <name>', '指定模型，如 gpt-image-2 / seedance-2-fast / artsdance-2-0-pro-260801')
+  .option('-q, --quality <level>', '质量: low / medium / high（仅 gpt-image）')
+  .option('--ref <file>', '垫图文件路径（图片图生图，自动上传）')
+  .option('--video', '生成视频（走 /api/videos 链路，模型如 seedance-2-fast / artsdance-2-0-pro）')
+  .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
+  .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')
+  .action(withClient((client: StudioClient, opts: any) => gen(client, opts)))
+
+program
+  .command('reverse <input>')
+  .description('读图：上传图或图片 URL，反推 SCULPT prompt，stdout 输出英文 prompt（只读图；要做成模板用 image-to-template）')
+  .action(withClient((client: StudioClient, input: string) => reverse(client, input)))
+
+program
+  .command('image-to-template <input>')
+  .description('图生模板：上传图或图片 URL → 读图 + 文字层逆向 + 变量化 → 建成可复用的图片模板（原图自动焊成参考图）')
+  .option('--no-create', '只看模板草稿，不真的建模板（同步返回，不消耗模板库）')
+  .option('--name <zh_name>', '模板中文名，不给则由中台生成')
+  .option('--slug <slug>', '模板 slug（全局唯一，撞了直接报错不覆盖），不给则由中台生成')
+  .option('--category <name>', '模板分类，不给则按图片内容自动归类')
+  .option('--variables <keys>', '收窄变量白名单，逗号分隔，如 title,subject,location（不传则中台按全集自行判断）')
+  .option('--labels <json>', '变量 → 你的业务叫法，JSON 对象，如 \'{"subject":"艺人","location":"城市"}\'；只影响表单显示名')
+  .option('--async', '强制异步（建模板本来就是异步，这个只对 --no-create 有意义）')
+  .action(withClient((client: StudioClient, input: string, opts: any) => imageToTemplate(client, input, opts)))
+
+program
+  .command('upload <file>')
+  .description('上传素材（图片/音频/视频，按字节内容判类型；图片 8MB / 音频 20MB / 视频 50MB），stdout 输出公网直链')
+  .action(withClient((client: StudioClient, file: string) => upload(client, file)))
+
+program
+  .command('models')
+  .description('查可用模型列表')
+  .action(withClient((client: StudioClient) => models(client)))
+
+program
+  .command('skills')
+  .description('查可用技能：自己的私有技能 + 所属租户专属模板 + 公共技能库')
+  .option('--genre <name>', '按分类过滤，如 电商 / 人像写真')
+  .action(withClient((client: StudioClient, opts: any) => skills(client, opts)))
+
+const templatesCmd = program
+  .command('templates')
+  .description('查可用图片/文字模板：自己租户建的 + 平台共享的（跟技能是两套不同的机制，见 gen --template）')
+  .option('--category <name>', '按分类过滤，如 电商白底图 / 演唱会')
+  .option('--type <type>', '按类型过滤：image（图片） / article（文字），不传则两类都列并标注')
+  .action(withClient((client: StudioClient, opts: any) => templates(client, opts)))
+
+const videoTemplatesCmd = program
+  .command('video-templates')
+  .description('查可用视频模板：配合 gen --video --template 使用（视频模板与图片模板是两套表）')
+  .option('--category <name>', '按分类过滤，如 电商 / 换装视频')
+  .action(withClient((client: StudioClient, opts: any) => videoTemplates(client, opts)))
+
+videoTemplatesCmd
+  .command('create')
+  .description(
+    '新建视频模板——归属由账号身份自动决定：租户 apiKey 建的自动归该租户，平台管理员建的是平台共享模板，个人账号不能建',
+  )
+  .requiredOption('--name <zh_name>', '模板中文名')
+  .requiredOption('--prompt <template>', '提示词模板，占位符用 {key} 形式，如 "{product} 在 {scene} 中展示"')
+  .option('--category <name>', '分类，默认「其他」')
+  .option('--description <text>', '模板说明')
+  .option('--model <name>', '视频模型，默认 seedance-2（可选 seedance-2-fast / seedance-2-mini / artsdance-2-0-pro-260801）')
+  .option('--duration <sec>', '视频时长（秒，4-15，可选）')
+  .option('--ratio <ratio>', '画面比例: 9:16 / 16:9 / 1:1 / 3:4（可选）')
+  .option('--sample-video <url>', '参考视频 URL（可选，展示给用户的示例片）')
+  .option('--sample-cover <url>', '封面图 URL（可选）')
+  .action(withClient((client: StudioClient, opts: any) => createVideoTemplate(client, opts)))
+
+templatesCmd
+  .command('create')
+  .description(
+    '新建图片/文字模板——归属由账号身份自动决定：租户 apiKey 建的自动归该租户（其他租户看不到），' +
+      '平台管理员账号建的是平台共享模板（所有租户可见），个人账号不能建',
+  )
+  .requiredOption('--name <zh_name>', '模板中文名')
+  .requiredOption('--prompt <template>', '提示词模板，占位符用 {key} 形式，如 "{artist} 在 {city} 的演唱会海报"')
+  .option('--category <name>', '分类，默认「其他」')
+  .option('--ratio <ratio>', '宽高比，默认 3:4')
+  .option('--description <text>', '模板说明')
+  .option('--model <name>', '生成模型，默认 gpt-image-2')
+  .option('--quality <level>', '质量: low / medium / high')
+  .option('--fields <json>', '占位符字段说明，JSON 数组，如 \'[{"key":"artist","label":"艺人名"}]\'；不传则自动从 --prompt 里的 {key} 提取')
+  .option('--type <type>', '模板类型：image（图片，默认） / article（文字）')
+  .action(withClient((client: StudioClient, opts: any) => createTemplate(client, opts)))
+
+program
+  .command('products')
+  .description('查所属租户自己的产品目录（数据在租户自己的后台，不在 Studio 中台；只支持已开通该接口的租户，仅租户 apiKey 身份可用）')
+  .action(withTenantClient((client: TenantClient) => products(client)))
+
+program
+  .command('assets')
+  .description('查所属租户自己的素材/资产库（数据在租户自己的后台，不在 Studio 中台；只支持已开通该接口的租户，仅租户 apiKey 身份可用）')
+  .action(withTenantClient((client: TenantClient) => assets(client)))
+
+program
+  .command('balance')
+  .description('查上游余额')
+  .action(withClient((client: StudioClient) => balance(client)))
+
+program
+  .command('jobs')
+  .description('查自己名下的出图工作流（个人 login 看自己的；租户 apiKey 看业务下全部）——服务端固定返回最近 50 条，limit/status 是本地过滤')
+  .option('--limit <n>', '最多显示几条（在最近 50 条以内截取），默认 20', '20')
+  .option('--status <status>', '按状态过滤: pending / processing / done / failed（本地过滤，不是服务端查询）')
+  .action(withClient((client: StudioClient, opts: any) => jobs(client, opts)))
+
+program
+  .command('whoami')
+  .description('查当前登录账户 + 租户归属（仅个人 login 可用，apiKey 调用会报错）')
+  .action(withClient((client: StudioClient) => whoami(client)))
+
+program
+  .command('config')
+  .description('配置中台地址和 apiKey（存到 ~/.museav.json）')
+  .option('--baseUrl <url>', '中台地址，默认 https://manager.museav.top')
+  .option('--apiKey <key>', 'apiKey（sk-studio-xxx）')
+  .option('--tenantBaseUrl <url>', '租户自己后台的域名，供 products/assets 命令用；已知租户（hym/mzmeso）不配也能跑')
+  .action(async (opts) => {
+    if (!opts.baseUrl && !opts.apiKey && !opts.tenantBaseUrl) {
+      try {
+        const cfg = loadConfig()
+        process.stderr.write(
+          `当前配置 (~/.museav.json):\n` +
+          `  baseUrl: ${cfg.baseUrl}\n` +
+          `  apiKey: ${cfg.apiKey ? cfg.apiKey.slice(0, 16) + '...' : '(未设置)'}\n` +
+          `  tenantBaseUrl: ${cfg.tenantBaseUrl || '(未设置，products/assets 对已知租户用内置默认值)'}\n`,
+
+        )
+      } catch (e) {
+        process.stderr.write(`${(e as Error).message}\n`)
+      }
+      process.stderr.write(`\n修改: museav config --apiKey sk-studio-xxx\n`)
+      return
+    }
+    const cfg = saveConfig(opts)
+    process.stderr.write(
+      `✅ 已保存到 ~/.museav.json\n` +
+      `  baseUrl: ${cfg.baseUrl}\n` +
+      `  apiKey: ${cfg.apiKey ? cfg.apiKey.slice(0, 16) + '...' : '(未设置)'}\n` +
+      `  tenantBaseUrl: ${cfg.tenantBaseUrl || '(未设置)'}\n`,
+    )
+    // 配置了 apiKey 就识别身份打招呼（租户欢迎；个人 token 场景欢迎在 login 后打）
+    if (opts.apiKey) {
+      try {
+        await printWelcome(cfg.baseUrl, { apiKey: opts.apiKey })
+      } catch (e) {
+        process.stderr.write(`⚠ 无法识别该 apiKey 对应的账户：${(e as Error).message}\n`)
+      }
+    }
+  })
+
+program
+  .command('login')
+  .description('登录（设备授权：终端显示验证码，浏览器打开授权后 CLI 自动完成登录）')
+  .option('--baseUrl <url>', '中台地址，默认 https://manager.museav.top')
+  .action(async (opts) => {
+    try {
+      await login(opts)
+    } catch (e) {
+      process.stderr.write(`❌ ${(e as Error).message}\n`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('bind-feishu')
+  .description('绑定飞书（设备授权：终端显示验证码，浏览器授权后完成绑定；一个飞书可绑多个平台账户）')
+  .option('--baseUrl <url>', '中台地址，默认 https://manager.museav.top')
+  .action(async (opts) => {
+    try {
+      await bindFeishu(opts)
+    } catch (e) {
+      process.stderr.write(`❌ ${(e as Error).message}\n`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('logout')
+  .description('退出登录（清除本地 token）')
+  .action(() => {
+    clearToken()
+    process.stderr.write('✅ 已退出登录\n')
+  })
+
+program.parse()

package/src/tenant-client.ts

@@ -0,0 +1,90 @@
+/**
+ * TenantClient —— 调「租户自己后台」的只读产品/素材接口，注意不是 Studio 中台。
+ *
+ * 背景（2026-08-10 架构决策）：租户自己的"产品""素材/资产"数据物理上存在各租户自己
+ * 的数据库里（好易美是 hym-admin 的 Supabase，mzmeso 是 manager 的 Supabase），
+ * Studio 中台不代理这部分数据——跨库统一存取需要 Studio 保管每个租户数据库的连接
+ * 信息，风险和复杂度远超"选产品参考图 + 模板 组合出图"这一个使用场景本身的收益，
+ * 这次没有做。维持现状：数据在哪个租户后台，只读接口就长在那个后台上，
+ * museav 直接调租户自己的域名，不经过 Studio。
+ *
+ * 鉴权复用同一把 apiKey：租户后台反过来调用 Studio（出图/查模板）时，本来就要在自己
+ * 环境变量里存这把 sk-studio-xxx（业务中台服务 key），所以它可以原样再拿来当"调用自己只读接口"
+ * 的凭证用，不用为这一件事再签发一套新 key。这把 key 已经能触发出图消费（更高价值的
+ * 操作），只读产品/素材不构成新的越权面。
+ *
+ * 已知局限：只支持"租户 apiKey"身份，不支持个人登录（login token）—— 产品/素材
+ * 是组织级数据，跟个人账号无关。
+ *
+ * 后台域名怎么定（2026-08-14 统一形态后）：key 不再携带租户名段（统一 sk-studio-<24hex>），
+ * 新格式 key 无法从 key 解析租户名 → 必须显式配置 --tenantBaseUrl；旧格式 key
+ * （sk-studio-<租户名>-<24hex>）仍能解析租户名，走内置 KNOWN_TENANT_BACKENDS 映射。
+ */
+
+/** 已知租户名 → 该租户自己后台的域名。仅 hym / mzmeso 两个已接入的租户，其他租户
+ *  需要用 `museav config --tenantBaseUrl <后台域名>` 显式配置。
+ *  这份映射维护在 CLI 本地是权宜之计——见任务报告里的"开放问题"：
+ *  长期是否应该让 Studio 的 api_tenants 表补一个 portal_base_url 字段，
+ *  由服务端下发而不是 CLI 硬编码，需要人确认后再决定。 */
+const KNOWN_TENANT_BACKENDS: Record<string, string> = {
+  hym: 'https://manager.hympro.cn',
+  mzmeso: 'https://mzmeso.webkubor.online',
+}
+
+/** 从旧格式 key（sk-studio-<租户名>-<24位十六进制>）里解析出租户名；新统一形态 sk-studio-<24hex> 解析不出（返回 null，需显式 tenantBaseUrl） */
+function parseTenantName(apiKey: string): string | null {
+  const m = apiKey.match(/^sk-studio-(.+)-[0-9a-f]{24}$/i)
+  return m ? m[1] : null
+}
+
+export class TenantClient {
+  private baseUrl: string
+  private apiKey: string
+
+  constructor(opts: { apiKey: string; tenantBaseUrl?: string }) {
+    if (!opts.apiKey.startsWith('sk-studio-')) {
+      throw new Error(
+        'products / assets 需要配置「租户 API Key」（业务中台服务 key，sk-studio-<24位>）。\n' +
+        '个人登录（login）是个人 token，查不了组织级的产品/素材数据。',
+      )
+    }
+    this.apiKey = opts.apiKey
+    const tenant = parseTenantName(opts.apiKey)
+    const known = tenant ? KNOWN_TENANT_BACKENDS[tenant] : undefined
+    const resolved = opts.tenantBaseUrl || known
+    if (!resolved) {
+      throw new Error(
+        `无法确定「${tenant || '该'}」租户自己后台的域名。\n` +
+        `（统一形态 key sk-studio-<24位> 不再携带租户名，需显式配置后台域名）\n` +
+        `请先用 museav config --tenantBaseUrl <你的租户后台域名> 显式配置一次\n` +
+        `（目前内置已知租户：${Object.keys(KNOWN_TENANT_BACKENDS).join(', ')}）。`,
+      )
+    }
+    this.baseUrl = resolved.replace(/\/+$/, '')
+  }
+
+  async get<T = unknown>(path: string): Promise<T> {
+    const resp = await fetch(`${this.baseUrl}/api/${path}`, {
+      headers: {
+        'X-API-Key': this.apiKey,
+        // 自报身份：新头是长期形态，旧头 X-Studio-Client 过渡期一起发（见 client.ts 里
+        // CLIENT_HEADERS 的说明）。这条打的是租户自己的后台，不是 MUSE AV 中台——
+        // 目前已知租户后台都没读这个头，两个头一起发只是口径统一，不产生耦合。
+        'X-Museav-Client': 'museav-cli-tenant',
+        'X-Studio-Client': 'museav-cli-tenant',
+        'User-Agent': 'museav-cli-tenant',
+      },
+    })
+    const text = await resp.text()
+    let body: any
+    try { body = JSON.parse(text) } catch { body = { raw: text } }
+    if (!resp.ok) {
+      const msg = body?.error || body?.raw || `HTTP ${resp.status}`
+      throw new Error(
+        `租户后台 API /api/${path} 失败: ${msg}\n` +
+        `（该租户后台可能尚未开通这个只读端点，或域名配置不对：${this.baseUrl}）`,
+      )
+    }
+    return body as T
+  }
+}

package/src/types/update-notifier.d.ts

@@ -0,0 +1,31 @@
+declare module 'update-notifier' {
+  interface Package {
+    name: string
+    version: string
+  }
+
+  interface NotifyOptions {
+    defer?: boolean
+    isGlobal?: boolean
+    message?: string
+  }
+
+  interface UpdateInfo {
+    current: string
+    latest: string
+    type: string
+  }
+
+  interface UpdateNotifier {
+    update?: UpdateInfo
+    notify(options?: NotifyOptions): void
+  }
+
+  interface Options {
+    pkg: Package
+    updateCheckInterval?: number
+    shouldNotifyInNpmScript?: boolean
+  }
+
+  export default function updateNotifier(options: Options): UpdateNotifier
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}