museav-cli 2.0.0

package/dist/commands/image-to-template.js

@@ -0,0 +1,111 @@
+import { isAsyncJob } from '../client.js';
+const STEP_MARK = { running: '🔄', ok: '✅', fail: '❌' };
+export async function imageToTemplate(client, input, opts = {}) {
+    const isUrl = /^https?:\/\//.test(input);
+    const createTemplate = opts.create !== false;
+    // --variables 收窄白名单：逗号分隔。中台只认它那套通用语义 key（title/subject/location…），
+    // 传了白名单外的会被忽略并在 template_warnings 里说明，全都不合法才 400。
+    const variables = opts.variables
+        ? opts.variables.split(',').map((s) => s.trim()).filter(Boolean)
+        : undefined;
+    if (opts.variables && !variables?.length) {
+        throw new Error('--variables 给了但解析不出任何变量名，格式是逗号分隔，如 --variables title,subject,location');
+    }
+    let variableLabels;
+    if (opts.labels) {
+        try {
+            variableLabels = JSON.parse(opts.labels);
+        }
+        catch {
+            throw new Error(`--labels 必须是合法 JSON 对象，如 '{"subject":"艺人","location":"城市"}'，收到: ${opts.labels}`);
+        }
+    }
+    // 模板元信息全是可选的，一个都没给就整个不传，让中台自己生成 slug / 中文名
+    const template = opts.name || opts.slug || opts.category
+        ? { zh_name: opts.name, slug: opts.slug, category: opts.category }
+        : undefined;
+    if (template && !createTemplate) {
+        process.stderr.write('⚠ --no-create 只看草稿，--name / --slug / --category 不会生效\n');
+    }
+    process.stderr.write(`${createTemplate ? '图生模板' : '图生模板草稿（--no-create，不建模板）'}: ${input}\n`);
+    const submitted = await client.imageToTemplate({
+        file: isUrl ? undefined : input,
+        imageUrl: isUrl ? input : undefined,
+        variables,
+        variableLabels,
+        createTemplate,
+        template,
+        async: opts.async,
+    });
+    let result;
+    if (isAsyncJob(submitted)) {
+        process.stderr.write(`任务已提交: ${submitted.jobId}\n`);
+        // 阶段名去重打印：中台每轮返回的是完整 steps 数组，不过滤的话每 3 秒把同样的阶段重刷一遍
+        const printed = new Set();
+        result = await client.waitImageToTemplate(submitted.jobId, (steps) => {
+            for (const s of steps) {
+                const key = `${s.name}:${s.status}`;
+                if (printed.has(key))
+                    continue;
+                printed.add(key);
+                const cost = s.ms != null ? ` (${(s.ms / 1000).toFixed(1)}s)` : '';
+                process.stderr.write(`  ${STEP_MARK[s.status] || '·'} ${s.name}${cost}\n`);
+            }
+        });
+    }
+    else {
+        result = submitted;
+    }
+    printResult(result, createTemplate);
+}
+function printResult(r, createTemplate) {
+    process.stderr.write(`\n✅ 读图完成\n`);
+    process.stderr.write(`风格: ${r.zh_name || '-'}  分类: ${r.image_category || '-'}  比例: ${r.aspect_ratio}\n`);
+    if (r.style_tags?.length)
+        process.stderr.write(`标签: ${r.style_tags.join(', ')}\n`);
+    const layers = r.text_layers || [];
+    if (layers.length) {
+        process.stderr.write(`\n文字层（${layers.length} 处）:\n`);
+        for (const l of layers) {
+            const varTag = l.is_variable ? `{${l.variable}}` : '固定';
+            process.stderr.write(`  ${(l.role || '-').padEnd(12)} ${varTag.padEnd(14)} ${(l.position || '').padEnd(12)} ${String(l.content || '').slice(0, 30)}\n`);
+        }
+    }
+    if (r.prompt_template) {
+        process.stderr.write(`\n提示词模具:\n  ${r.prompt_template}\n`);
+        process.stderr.write(`变量: ${fieldSummary(r.fields)}\n`);
+    }
+    else {
+        // 中台的降级口径：文字层/变量化/建模板任一步失败都只降级，读图结果照常返回。
+        // 所以这里不抛错——上面那段读图结果是真的，用户可以照常拿去出图。
+        process.stderr.write(`\n⚠ 没能做出提示词模具${r.template_error ? `：${r.template_error}` : ''}\n`);
+        process.stderr.write(`  读图结果仍然有效，可直接用下面的 prompt 出图\n`);
+    }
+    for (const w of r.template_warnings || [])
+        process.stderr.write(`⚠ ${w}\n`);
+    if (r.template) {
+        process.stderr.write(`\n✅ 模板已建：${r.template.id}\n`);
+        process.stderr.write(`  slug: ${r.template.slug}  名称: ${r.template.zh_name}\n`);
+        process.stderr.write(`  归属：${r.template.tenant_id ? '当前租户（其他租户看不到）' : '平台共享（所有租户可见）'}\n`);
+        if (r.template.reference_image)
+            process.stderr.write(`  参考图（已焊进模板）: ${r.template.reference_image}\n`);
+        const example = r.fields?.length ? ` --fields '{"${r.fields[0].key}":"..."}'` : '';
+        process.stderr.write(`\n出图: museav gen --template ${r.template.id}${example}\n`);
+        // stdout 只出模板 id，跟 templates create 一致，便于脚本链式使用
+        console.log(r.template.id);
+        return;
+    }
+    if (createTemplate && r.template_error) {
+        process.stderr.write(`\n❌ 模板没建成：${r.template_error}\n`);
+    }
+    else if (!createTemplate) {
+        process.stderr.write(`\n这是草稿（--no-create）。满意的话去掉 --no-create 重跑一次即可建成模板。\n`);
+    }
+    // 没建成模板时 stdout 给完整草稿 JSON——脚本还能拿它自己调 POST /api/templates
+    console.log(JSON.stringify(r));
+}
+function fieldSummary(fields) {
+    if (!fields?.length)
+        return '(无)';
+    return fields.map((f) => (f.label && f.label !== f.key ? `${f.key}(${f.label})` : f.key)).join(', ');
+}

package/dist/commands/jobs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * museav jobs —— 查自己名下的出图工作流
+ *
+ * 范围自动跟着鉴权凭证走：个人 login 只看自己的记录；租户 apiKey 看自己业务下的全部记录。
+ * 不需要额外传租户/用户 id——你拿的是谁的凭证，就是谁的数据。
+ */
+import type { StudioClient, Job } from '../client.js';
+export declare function jobs(client: StudioClient, opts: {
+    limit?: string;
+    status?: Job['status'];
+}): Promise<void>;

package/dist/commands/jobs.js

@@ -0,0 +1,27 @@
+const STATUS_MARK = {
+    pending: '⏳',
+    processing: '🔄',
+    done: '✅',
+    failed: '❌',
+};
+export async function jobs(client, opts) {
+    const limit = opts.limit ? Number(opts.limit) : 20;
+    const list = await client.listJobs({ limit, status: opts.status });
+    if (!list.length) {
+        process.stderr.write('没有找到工作流记录\n');
+        console.log('[]');
+        return;
+    }
+    process.stderr.write(`最近 ${list.length} 条工作流:\n\n`);
+    for (const j of list) {
+        const mark = STATUS_MARK[j.status] || '?';
+        const time = j.created_at ? new Date(j.created_at).toLocaleString() : '?';
+        process.stderr.write(`${mark} ${j.id}  ${j.status.padEnd(10)} ${(j.model || '?').padEnd(16)} ${time}\n`);
+        if (j.cdn_url)
+            process.stderr.write(`   → ${j.cdn_url}\n`);
+        if (j.status === 'failed' && j.error)
+            process.stderr.write(`   error: ${j.error}\n`);
+    }
+    // stdout 输出完整 JSON，供脚本消费
+    console.log(JSON.stringify(list));
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,3 @@
+export declare function login(opts: {
+    baseUrl?: string;
+}): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,67 @@
+/**
+ * museav login —— 设备授权登录（RFC 8628）
+ *
+ * 流程：CLI 调 /cli-auth/start 拿验证码 → 用户浏览器打开审批页授权
+ *      → CLI 轮询 /cli-auth/poll 拿 JWT → 存到 ~/.museav.json
+ *
+ * 之后所有命令用 Bearer JWT 调 API，权限/额度与网页端一致。
+ */
+import { saveConfig, DEFAULT_BASE_URL } from '../config.js';
+import { printWelcome } from './welcome.js';
+export async function login(opts) {
+    const baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    // 1. 发起设备授权
+    process.stderr.write('正在发起授权...\n');
+    const startResp = await fetch(`${baseUrl}/api/cli-auth/start`, { method: 'POST' });
+    if (!startResp.ok) {
+        throw new Error(`发起授权失败: HTTP ${startResp.status}`);
+    }
+    const start = await startResp.json();
+    // 2. 展示验证码和链接，等用户去浏览器授权
+    process.stderr.write('\n');
+    process.stderr.write('┌──────────────────────────────────────────────────┐\n');
+    process.stderr.write('│                                                  │\n');
+    process.stderr.write(`│   验证码:  ${start.user_code.padEnd(34)}        │\n`);
+    process.stderr.write('│                                                  │\n');
+    process.stderr.write('│   请在浏览器打开以下地址，登录并批准授权：        │\n');
+    process.stderr.write('│                                                  │\n');
+    process.stderr.write('│   ' + start.verification_uri + '\n');
+    process.stderr.write('│                                                  │\n');
+    process.stderr.write('└──────────────────────────────────────────────────┘\n');
+    process.stderr.write('\n等待授权完成...（可随时 Ctrl+C 取消）\n');
+    // 3. 轮询直到拿到 token
+    const interval = (start.interval || 3) * 1000;
+    const maxAttempts = Math.floor((start.expires_in || 600) * 1000 / interval);
+    for (let i = 0; i < maxAttempts; i++) {
+        await sleep(interval);
+        const pollResp = await fetch(`${baseUrl}/api/cli-auth/poll`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ device_code: start.device_code }),
+        });
+        if (!pollResp.ok)
+            continue;
+        const poll = await pollResp.json();
+        if (poll.status === 'approved' && poll.token) {
+            saveConfig({ baseUrl, token: poll.token });
+            process.stderr.write('\n✅ 登录成功！token 已保存到 ~/.museav.json\n');
+            await printWelcome(baseUrl, { token: poll.token });
+            return;
+        }
+        if (poll.status === 'expired') {
+            throw new Error('授权已过期，请重新运行 museav login');
+        }
+        // 服务端目前只有 pending → approved 或过期两条路，没有"拒绝"这个动作
+        // （浏览器审批页没有拒绝按钮，不批准就是不动，最终走 expired）。
+        // 这里仍保留未知状态的兜底，万一以后服务端加了新状态，报错文案不会文不对题。
+        if (poll.status !== 'pending') {
+            throw new Error(`授权失败: ${poll.error || poll.status || '未知错误'}`);
+        }
+        // pending：继续等
+        process.stderr.write('.');
+    }
+    throw new Error('等待授权超时，请重新运行 museav login');
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/commands/models.d.ts

@@ -0,0 +1,3 @@
+/** museav models —— 查可用模型列表 */
+import type { StudioClient } from '../client.js';
+export declare function models(client: StudioClient): Promise<void>;

package/dist/commands/models.js

@@ -0,0 +1,9 @@
+export async function models(client) {
+    const list = await client.models();
+    process.stderr.write(`可用模型（${list.length} 个）:\n`);
+    for (const m of list) {
+        process.stderr.write(`  ${m.value.padEnd(28)} ${m.label}\n`);
+    }
+    // stdout 输出 value 列表（便于脚本解析）
+    console.log(list.map((m) => m.value).join('\n'));
+}

package/dist/commands/products.d.ts

@@ -0,0 +1,9 @@
+/**
+ * museav products —— 查所属租户自己的产品目录。
+ *
+ * 数据不在 Studio 中台，在租户自己的后台（见 ../tenant-client.ts 顶部注释）。
+ * 不是每个租户都有"产品"这个概念——比如好易美是演唱会海报/票务业务，没有实体商品，
+ * 它的后台没有开通这个端点，调用会报错，这是预期行为，不是 bug。
+ */
+import type { TenantClient } from '../tenant-client.js';
+export declare function products(client: TenantClient): Promise<void>;

package/dist/commands/products.js

@@ -0,0 +1,16 @@
+export async function products(client) {
+    const list = await client.get('tenant-products');
+    if (!Array.isArray(list) || !list.length) {
+        process.stderr.write('该租户暂无产品数据\n');
+        console.log('[]');
+        return;
+    }
+    process.stderr.write(`产品（${list.length} 个）:\n`);
+    for (const p of list) {
+        const imgCount = (p.images?.length || 0) + (p.cover_image_url ? 1 : 0);
+        process.stderr.write(`  ${String(p.id).padEnd(38)} ${(p.name || '').padEnd(20)} ${(p.series || '').padEnd(12)} ${(p.status || '').padEnd(10)} 图${imgCount}张\n`);
+    }
+    process.stderr.write(`\n配合出图: museav gen --template <模板id> --fields '{"...":"..."}'（参考图 URL 从上面产品的 cover_image_url / images 里挑）\n`);
+    // stdout 输出完整 JSON，方便 agent/脚本挑参考图字段
+    console.log(JSON.stringify(list));
+}

package/dist/commands/reverse.d.ts

@@ -0,0 +1,3 @@
+/** museav reverse —— 图片逆向（SCULPT 六要素反推 prompt） */
+import type { StudioClient } from '../client.js';
+export declare function reverse(client: StudioClient, input: string): Promise<void>;

package/dist/commands/reverse.js

@@ -0,0 +1,16 @@
+export async function reverse(client, input) {
+    // 输入是文件路径还是 URL
+    const isUrl = /^https?:\/\//.test(input);
+    const result = await client.reverse(isUrl ? { imageUrl: input } : { file: input });
+    process.stderr.write(`✅ 逆向完成\n\n`);
+    process.stderr.write(`风格: ${result.zh_name || '-'}  比例: ${result.aspect_ratio}\n`);
+    process.stderr.write(`标签: ${result.style_tags.join(', ')}\n\n`);
+    process.stderr.write(`SCULPT 六要素:\n`);
+    for (const [k, v] of Object.entries(result.sculpt)) {
+        process.stderr.write(`  ${k}: ${v}\n`);
+    }
+    process.stderr.write(`\n英文 prompt:\n  ${result.prompt}\n`);
+    process.stderr.write(`中文 prompt:\n  ${result.prompt_cn}\n`);
+    // stdout 输出英文 prompt（便于管道直接喂给 gen）
+    console.log(result.prompt);
+}

package/dist/commands/skills.d.ts

@@ -0,0 +1,5 @@
+/** museav skills —— 查可用技能（私有 + 所属租户专属模板 + 公共库） */
+import type { StudioClient } from '../client.js';
+export declare function skills(client: StudioClient, opts?: {
+    genre?: string;
+}): Promise<void>;

package/dist/commands/skills.js

@@ -0,0 +1,22 @@
+export async function skills(client, opts = {}) {
+    let list = await client.skills();
+    if (opts.genre) {
+        const kw = opts.genre.toLowerCase();
+        list = list.filter((s) => (s.genre || '').toLowerCase().includes(kw));
+    }
+    if (!list.length) {
+        process.stderr.write(opts.genre ? `没有匹配「${opts.genre}」的技能\n` : '没有可用技能\n');
+        return;
+    }
+    // 归属标记：自己建的 / 所属租户的专属模板 / 公共库——同名时服务端按这个顺序取
+    const tag = (s) => (s.private ? '[私有]' : s.agency ? '[专属]' : '');
+    process.stderr.write(`可用技能（${list.length} 个）:\n`);
+    for (const s of list) {
+        const flag = s.ref_required ? '需垫图' : '';
+        process.stderr.write(`  ${s.slug.padEnd(30)} ${(s.zh_name || '').padEnd(16)} ${(s.genre || '').padEnd(10)} ${(s.ratio || '').padEnd(6)} ${flag.padEnd(6)} ${tag(s)}\n`);
+    }
+    process.stderr.write(`\n出图: museav gen --skill <技能名> --input "一句业务描述"\n`);
+    process.stderr.write(`标「需垫图」的必须加 --ref ./图.jpg，否则服务端会拒绝\n`);
+    // stdout 只出 slug，便于脚本与 agent 解析
+    console.log(list.map((s) => s.slug).join('\n'));
+}

package/dist/commands/templates.d.ts

@@ -0,0 +1,28 @@
+/** museav templates —— 查可用图片/文字模板（自己租户建的 + 平台共享的）
+ *  --type image|article 可过滤（中台 templates 表同时装两种，不传则都列并标注类型） */
+import type { StudioClient } from '../client.js';
+export declare function templates(client: StudioClient, opts?: {
+    category?: string;
+    type?: string;
+}): Promise<void>;
+interface CreateTemplateOpts {
+    name: string;
+    prompt: string;
+    category?: string;
+    ratio?: string;
+    description?: string;
+    model?: string;
+    quality?: string;
+    fields?: string;
+    type?: string;
+}
+/**
+ * museav templates create —— 新建图片模板。
+ *
+ * 归属不用自己传：服务端根据鉴权身份自动决定——租户 apiKey 建的自动归该租户
+ * （其他租户看不到），平台管理员 JWT 建的是 tenant_id=null 的平台共享模板，
+ * 个人账号（无租户、非管理员）会被服务端拒绝。CLI 这里不做额外判断，直接把
+ * 服务端返回的结果（含真实归属）打印出来。
+ */
+export declare function createTemplate(client: StudioClient, opts: CreateTemplateOpts): Promise<void>;
+export {};

package/dist/commands/templates.js

@@ -0,0 +1,79 @@
+export async function templates(client, opts = {}) {
+    let list = await client.templates((opts.type === 'image' || opts.type === 'article') ? opts.type : undefined);
+    if (opts.category) {
+        const kw = opts.category.toLowerCase();
+        list = list.filter((t) => (t.category || '').toLowerCase().includes(kw));
+    }
+    if (!list.length) {
+        process.stderr.write(opts.category ? `没有匹配「${opts.category}」的模板\n` : '没有可用模板\n');
+        return;
+    }
+    const tag = (t) => (t.tenant_id ? '' : '[平台]');
+    const typeTag = (t) => (t.template_type === 'article' ? '[文字]' : t.template_type === 'image' ? '[图片]' : '');
+    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 || [];
+        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`);
+    }
+    process.stderr.write(`\n出图: museav gen --template <模板id> [--fields '{"key":"值"}']\n`);
+    process.stderr.write(`按类型过滤: museav templates --type image|article\n`);
+    // stdout 只出 id，便于脚本与 agent 解析
+    console.log(list.map((t) => t.id).join('\n'));
+}
+/**
+ * museav templates create —— 新建图片模板。
+ *
+ * 归属不用自己传：服务端根据鉴权身份自动决定——租户 apiKey 建的自动归该租户
+ * （其他租户看不到），平台管理员 JWT 建的是 tenant_id=null 的平台共享模板，
+ * 个人账号（无租户、非管理员）会被服务端拒绝。CLI 这里不做额外判断，直接把
+ * 服务端返回的结果（含真实归属）打印出来。
+ */
+export async function createTemplate(client, opts) {
+    if (!opts.name?.trim())
+        throw new Error('--name 必填');
+    if (!opts.prompt?.trim())
+        throw new Error('--prompt 必填，占位符用 {key} 形式，如 "{artist} 在 {city} 的演唱会海报"');
+    let fields;
+    if (opts.fields) {
+        try {
+            fields = JSON.parse(opts.fields);
+        }
+        catch {
+            throw new Error('--fields 必须是合法 JSON 数组，如 \'[{"key":"artist","label":"艺人名"}]\'');
+        }
+    }
+    else {
+        // 不传 --fields 就自动从 --prompt 里的 {key} 占位符提取，label 先等于 key，
+        // 想要更友好的中文标签可以自己传 --fields 覆盖
+        const keys = Array.from(new Set(Array.from(opts.prompt.matchAll(/\{(\w+)\}/g), (m) => m[1])));
+        fields = keys.map((key) => ({ key, label: key }));
+    }
+    const type = opts.type === 'article' ? 'article' : 'image';
+    const row = await client.createTemplate({
+        zh_name: opts.name,
+        category: opts.category,
+        ratio: opts.ratio,
+        description: opts.description,
+        template_type: type,
+        generation_configs: [
+            {
+                model: opts.model || 'gpt-image-2',
+                prompt_template: opts.prompt,
+                quality: opts.quality,
+                // 契约要求 fields 在 config 顶层（服务端 validateConfig 读 cfg.fields）
+                fields: fields.length ? fields : undefined,
+                is_default: true,
+            },
+        ],
+    });
+    process.stderr.write(`✅ ${type === 'article' ? '文字' : '图片'}模板已建：${row.id}\n`);
+    process.stderr.write(`归属：${row.tenant_id ? '当前租户（其他租户看不到）' : '平台共享（所有租户可见）'}\n`);
+    if (fields.length)
+        process.stderr.write(`占位符字段: ${fields.map((f) => f.key).join(', ')}\n`);
+    const fieldExample = fields.length ? ` --fields '{"${fields[0].key}":"..."}'` : '';
+    process.stderr.write(`\n出图: museav gen --template ${row.id}${fieldExample}\n`);
+    // stdout 只出新建的模板 id，便于脚本链式使用
+    console.log(row.id);
+}

package/dist/commands/upload.d.ts

@@ -0,0 +1,9 @@
+/**
+ * museav upload —— 上传素材到中台图库，stdout 输出公网直链。
+ *
+ * 走 POST /api/upload-ref：图片 / 音频 / 视频都收，类型按**字节魔数**判定（中台不信
+ * 客户端声明的 MIME），分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。
+ * 拿到的 URL 可以直接喂给 gen --ref / gen --video --image，也能给 reverse 当图片 URL。
+ */
+import type { StudioClient } from '../client.js';
+export declare function upload(client: StudioClient, filePath: string): Promise<void>;

package/dist/commands/upload.js

@@ -0,0 +1,8 @@
+const KIND_LABEL = { image: '图片', audio: '音频', video: '视频' };
+export async function upload(client, filePath) {
+    process.stderr.write(`上传 ${filePath} ...\n`);
+    const { url, media_type, mime } = await client.uploadRef(filePath);
+    const kind = media_type ? `${KIND_LABEL[media_type] || media_type}${mime ? ` · ${mime}` : ''}` : '';
+    process.stderr.write(`✅ 上传成功${kind ? `（${kind}）` : ''}\n`);
+    console.log(url);
+}

package/dist/commands/video-templates.d.ts

@@ -0,0 +1,21 @@
+/** museav video-templates —— 查可用视频模板（配合 gen --video --template） */
+import type { StudioClient } from '../client.js';
+export declare function videoTemplates(client: StudioClient, opts?: {
+    category?: string;
+}): Promise<void>;
+interface CreateVideoTemplateOpts {
+    name: string;
+    prompt: string;
+    category?: string;
+    description?: string;
+    model?: string;
+    duration?: string;
+    ratio?: string;
+    sampleVideo?: string;
+    sampleCover?: string;
+}
+/** museav video-templates create —— 新建视频模板。
+ *  视频模板字段跟图片不同：模型/时长/比例在 generation_configs 每项里（服务端契约）。
+ *  归属跟图片模板一样由服务端根据鉴权身份自动决定。 */
+export declare function createVideoTemplate(client: StudioClient, opts: CreateVideoTemplateOpts): Promise<void>;
+export {};

package/dist/commands/video-templates.js

@@ -0,0 +1,71 @@
+export async function videoTemplates(client, opts = {}) {
+    let list = await client.videoTemplates();
+    if (opts.category) {
+        const kw = opts.category.toLowerCase();
+        list = list.filter((t) => (t.category || '').toLowerCase().includes(kw));
+    }
+    if (!list.length) {
+        process.stderr.write(opts.category ? `没有匹配「${opts.category}」的视频模板\n` : '没有可用视频模板\n');
+        return;
+    }
+    const tag = (t) => (t.tenant_id ? '' : '[平台]');
+    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 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(',')}` : '';
+        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`);
+        if (t.sample_video_url) {
+            process.stderr.write(`      参考视频: ${t.sample_video_url}\n`);
+        }
+    }
+    process.stderr.write(`\n出视频: museav gen --video --template <模板id> [--fields '{"key":"值"}']\n`);
+    // stdout 只出 id 和参考视频 URL（tab 分隔），便于脚本与 agent 解析
+    console.log(list.map((t) => t.sample_video_url ? `${t.id}\t${t.sample_video_url}` : t.id).join('\n'));
+}
+/** museav video-templates create —— 新建视频模板。
+ *  视频模板字段跟图片不同：模型/时长/比例在 generation_configs 每项里（服务端契约）。
+ *  归属跟图片模板一样由服务端根据鉴权身份自动决定。 */
+export async function createVideoTemplate(client, opts) {
+    if (!opts.name?.trim())
+        throw new Error('--name 必填');
+    if (!opts.prompt?.trim())
+        throw new Error('--prompt 必填，占位符用 {key} 形式，如 "{product} 在 {scene} 中展示"');
+    // 占位符必须声明 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 = {
+        model: opts.model || 'seedance-2',
+        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 之间的数字（秒）');
+        cfg.duration = d;
+    }
+    if (opts.ratio)
+        cfg.aspect_ratio = opts.ratio;
+    const row = await client.createVideoTemplate({
+        zh_name: opts.name,
+        category: opts.category,
+        description: opts.description,
+        sample_video_url: opts.sampleVideo || null,
+        sample_cover_image: opts.sampleCover || null,
+        generation_configs: [cfg],
+    });
+    process.stderr.write(`✅ 视频模板已建：${row.id}\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`);
+    process.stderr.write(`\n出视频: museav gen --video --template ${row.id}\n`);
+    // stdout 只出新建的模板 id，便于脚本链式使用
+    console.log(row.id);
+}

package/dist/commands/welcome.d.ts

@@ -0,0 +1,6 @@
+export interface WelcomeCred {
+    token?: string;
+    apiKey?: string;
+}
+/** 打印身份欢迎。识别失败时给兜底问候，不影响 CLI 继续使用。 */
+export declare function printWelcome(baseUrl: string, cred: WelcomeCred): Promise<void>;

package/dist/commands/welcome.js

@@ -0,0 +1,93 @@
+import { StudioClient } from '../client.js';
+/** 终端显示宽度：ASCII=1，中文等宽字符=2（终端等宽字体下中文占 2 格） */
+function displayWidth(s) {
+    return [...s].reduce((w, ch) => w + (ch.charCodeAt(0) > 255 ? 2 : 1), 0);
+}
+function box(lines) {
+    const width = Math.max(...lines.map(displayWidth)) + 4;
+    const border = '┌' + '─'.repeat(width) + '┐';
+    const bottom = '└' + '─'.repeat(width) + '┘';
+    return [
+        border,
+        ...lines.map((l) => `│ ${l}${' '.repeat(width - displayWidth(l))} │`),
+        bottom,
+    ].join('\n');
+}
+/** 打印身份欢迎。识别失败时给兜底问候，不影响 CLI 继续使用。 */
+export async function printWelcome(baseUrl, cred) {
+    let me = null;
+    try {
+        me = await new StudioClient({ baseUrl, ...cred }).me();
+    }
+    catch {
+        me = null;
+    }
+    if (me?.identity === 'tenant') {
+        // ── 系统接入方（apiKey 模式）──
+        // 「租户」是内部技术称谓，对客户不暴露：客户视角是「我们的系统接入了
+        // MUSE AV AI 创作平台」，我们是服务提供方，不是把对方当租客。
+        const t = me.tenant;
+        const tname = t?.nickname || t?.name || '贵方系统';
+        process.stderr.write(`👋 欢迎，${tname}！MUSE AV AI 创作平台已为你的系统接入创作能力\n`);
+        process.stderr.write(`   接入方：${tname}（系统级 API Key，为你的业务后台提供图片/视频创作）\n`);
+    }
+    else if (me) {
+        // ── 个人身份 ──
+        const name = me.nickname || me.email;
+        let identity = '平台用户';
+        let greeting = '欢迎使用 MUSE AV 创作中台';
+        if (me.role === 'superadmin') {
+            identity = '平台超级管理员';
+            greeting = '欢迎回来，山鬼映画！平台归你管，出了事找你本人 😄';
+        }
+        else if (me.role === 'admin') {
+            identity = '平台管理员';
+            greeting = `欢迎回来，${name}！`;
+        }
+        else if (me.brand) {
+            // 接入方业务系统的成员（如好易美员工账户）：
+            // 身份表达 = 我是「XX」的人，MUSE AV 为「XX」提供创作能力。
+            // 不用「租户/租户成员」这类内部词，客户不该有被出租的感觉。
+            const biz = me.brand.name;
+            identity = `${biz}成员`;
+            greeting = `欢迎，${name}！MUSE AV 为「${biz}」提供 AI 创作能力，你的创作工作台已就绪`;
+        }
+        else {
+            greeting = `欢迎，${name}！`;
+        }
+        const quota = me.generation_remaining != null ? `${me.generation_remaining} 次` : '不限';
+        process.stderr.write(`👋 ${greeting}\n`);
+        process.stderr.write(`   账户：${me.email}（${identity}）\n`);
+        if (me.gen_done != null)
+            process.stderr.write(`   已出图 ${me.gen_done} 张 · 剩余额度 ${quota}\n`);
+        // 已绑定飞书：让客户知道缪斯 agent 在飞书里能认出他（未绑定不提示，绑定说明区有引导）
+        if (me.feishu_open_id)
+            process.stderr.write('   飞书：已绑定 ✓（缪斯 agent 在飞书群里能认出你）\n');
+    }
+    else {
+        process.stderr.write('👋 欢迎使用 MUSE AV 创作中台\n');
+    }
+    process.stderr.write('\n' + box([
+        '📖 怎么用（常用命令）',
+        '  museav gen --prompt "英文提示词"    自由出图',
+        '  museav gen --skill <技能> --input "描述"   技能出图',
+        '  museav gen --template <id> --fields \'{..}\'  模板出图',
+        '  museav image-to-template <图>       一张图做成可复用模板',
+        '  museav skills / templates / reverse    查技能/模板/读图',
+        '  museav jobs / whoami              记录 / 身份',
+        '  museav bind-feishu                绑定飞书',
+    ]) + '\n');
+    process.stderr.write('\n🔗 找我 / 支持我：\n');
+    process.stderr.write('   · GitHub 给项目点个 ⭐ → https://github.com/webkubor/museav-cli\n');
+    process.stderr.write('   · 小红书「山鬼映画」（东方电影美学）→ https://www.xiaohongshu.com/user/profile/5c3c1581000000000501835d\n');
+    process.stderr.write('\n🎁 我的其他作品（GitHub 上给它们点个 ⭐ 就是最大的支持）：\n');
+    process.stderr.write('   · typora-Bloom-theme（Typora 写作主题，★89）→ github.com/webkubor/typora-Bloom-theme\n');
+    process.stderr.write('   · voice-editor（本地中文 TTS 工作台）→ github.com/webkubor/voice-editor\n');
+    process.stderr.write('   · kyvault（本地加密密钥管理 CLI）→ github.com/webkubor/kyvault\n');
+    process.stderr.write('   · wechat-chat-gen（高仿真微信聊天截图生成器）→ github.com/webkubor/wechat-chat-gen\n');
+    process.stderr.write('   · knowledge-pdf-kit（Markdown → PDF/长图）→ github.com/webkubor/knowledge-pdf-kit\n');
+    process.stderr.write('\nℹ️ 绑定说明：\n');
+    process.stderr.write('   · 出图 / 技能 / 模板 / 逆向等全部创作功能【不需要】绑定飞书\n');
+    process.stderr.write('   · 绑定飞书（bind-feishu）只影响：让 agent 在飞书里认出你的身份\n');
+    process.stderr.write('\n现在就可以开始：museav gen --prompt "一只猫"\n');
+}