museav-cli 2.0.0

package/dist/client.js

@@ -0,0 +1,372 @@
+/**
+ * StudioClient —— studio 中台 API 客户端
+ *
+ * 所有出图/逆向/上传能力都封装在这里。CLI commands 和编程调用共用这一个 class。
+ *
+ * 用法：
+ *   const studio = new StudioClient({ baseUrl, apiKey })
+ *   const job = await studio.generateAndWait({ prompt: '一只猫' })
+ *   console.log(job.cdn_url)
+ */
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+/**
+ * 客户端自报身份 —— 中台靠它把 gen_jobs.channel 记成 'cli'，报错告警也靠它定位调用方。
+ *
+ * 必要性：同一把租户 apiKey 既可能来自业务方后端，也可能来自有人在终端跑本 CLI；
+ * 同一个个人 JWT 既可能来自网页也可能来自这里。只看凭证分不出渠道，必须自报。
+ * 版本号从 package.json 读，随发版自动跟随；读不到就退化成不带版本（仍能识别为 cli）。
+ */
+const CLIENT_ID = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+        return `museav-cli/${pkg.version}`;
+    }
+    catch {
+        return 'museav-cli';
+    }
+})();
+/**
+ * 自报身份的头名。**过渡期两个头一起发，值都是 CLIENT_ID。**
+ *
+ *   X-Museav-Client —— 新头，跟产品名一致，长期只留这一个。
+ *   X-Studio-Client —— 旧头，头名里还带着已经废弃的 "Studio" 叫法，纯为兼容保留。
+ *
+ * 为什么两个都发：中台的渠道识别（detectChannel）与报错上下文（_middleware 的
+ * requestContext）现在读的是旧头，且对值做前缀匹配。CLI 单方面改名，中台就会把 CLI
+ * 的调用记成 browser/api，渠道统计当场失真。过渡期中台两个头都读，等所有客户端都升上来
+ * 之后，中台先停读旧头，这里再把 X-Studio-Client 删掉——那时删是纯清理，不影响任何人。
+ */
+const CLIENT_HEADERS = {
+    'X-Museav-Client': CLIENT_ID,
+    'X-Studio-Client': CLIENT_ID,
+    // 中台还有一条 UA 兜底匹配（有人只改 UA 不带自报头时也能认出是 CLI）。
+    // Node 默认 UA 是 "node"，什么信息都没有，这里显式带上同一个身份串。
+    'User-Agent': CLIENT_ID,
+};
+export class StudioClient {
+    baseUrl;
+    authHeader;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        // 个人用户 JWT 走 Bearer；租户 apikey 走 X-API-Key
+        if (opts.token) {
+            this.authHeader = { Authorization: `Bearer ${opts.token}` };
+        }
+        else if (opts.apiKey) {
+            this.authHeader = { 'X-API-Key': opts.apiKey };
+        }
+        else {
+            throw new Error('需要 token 或 apiKey');
+        }
+    }
+    headers(extra = {}) {
+        return { ...CLIENT_HEADERS, ...this.authHeader, ...extra };
+    }
+    async request(path, init = {}) {
+        const url = `${this.baseUrl}/api/${path}`;
+        const resp = await fetch(url, {
+            ...init,
+            headers: { ...this.headers(), ...init.headers },
+        });
+        const text = await resp.text();
+        let body;
+        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}`);
+        }
+        return body;
+    }
+    /** 可用技能清单：私有 + 所属租户专属模板 + 公共库，服务端已按调用者权限过滤 */
+    async skills() {
+        const r = await this.request('skills');
+        return Array.isArray(r) ? r : [];
+    }
+    /** 可用图片/文字模板清单：自己租户建的 + 平台共享的，服务端已按调用者权限过滤。
+     *  type=image|article 二选一（不传则图片+文字都返回，跟中台默认一致）。 */
+    async templates(type) {
+        const qs = type ? `?type=${type}` : '';
+        const r = await this.request(`templates${qs}`);
+        return Array.isArray(r) ? r : [];
+    }
+    /** 视频模板清单（POST /api/videos 用 template_id）。结构同图片模板的 generation_configs 形态 */
+    async videoTemplates() {
+        const r = await this.request('video-templates');
+        return Array.isArray(r) ? r : [];
+    }
+    /** 新建图片模板。归属（是否关联租户）由服务端根据鉴权身份决定，见 CreateTemplateInput 注释 */
+    async createTemplate(input) {
+        const r = await this.request('templates', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(input),
+        });
+        return r.row;
+    }
+    /** 新建视频模板。归属同图片模板：租户 apiKey 自动归租户，平台管理员归平台共享 */
+    async createVideoTemplate(input) {
+        const r = await this.request('video-templates', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(input),
+        });
+        return r.row;
+    }
+    /** 提交出图任务，立即返回 jobId */
+    async generate(opts) {
+        // prompt / skill_slug / template_id 三选一：都传时服务端按 prompt > template_id > skill_slug
+        // 的优先级取（见服务端 generate.js），这里不替服务端做决定，只保证不凭空造字段
+        const body = {};
+        if (opts.prompt)
+            body.prompt = opts.prompt;
+        if (opts.skill_slug)
+            body.skill_slug = opts.skill_slug;
+        if (opts.template_id)
+            body.template_id = opts.template_id;
+        // input 是服务端黑盒展开的入参：skill_slug 配一句话描述，template_id 配占位符取值对象，
+        // 两者都写进同一个 input 字段（服务端按类型分支处理），CLI 侧分开成两个选项只是好懂
+        if (opts.input)
+            body.input = opts.input;
+        else if (opts.template_fields)
+            body.input = opts.template_fields;
+        if (opts.ratio)
+            body.ratio = opts.ratio;
+        if (opts.model)
+            body.model = opts.model;
+        if (opts.reference_image)
+            body.reference_image = opts.reference_image;
+        if (opts.quality)
+            body.quality = opts.quality;
+        const r = await this.request('generate', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        return { jobId: r.jobId, trace_id: r.trace_id };
+    }
+    /** 查单个任务状态 */
+    async getJob(id) {
+        const r = await this.request(`jobs?id=${encodeURIComponent(id)}`);
+        return r;
+    }
+    /**
+     * 列出当前身份名下的出图工作流（不传 id，走同一个 jobs 端点的集合语义）。
+     * 范围由鉴权凭证决定：个人 token 只看得到自己出的图；租户 apiKey 看得到自己业务下的全部记录。
+     *
+     * 服务端 GET /api/jobs 目前只认 id / all 两个 query 参数，固定按 created_at
+     * 倒序返回最近 50 条，不支持 limit/status 这类过滤——传了也会被忽略。
+     * 所以 limit/status 在这里做客户端过滤：先拿到这最多 50 条，再本地按 status
+     * 筛、按 limit 截断。这意味着 --limit 只能在这 50 条以内选，选不到更早的历史。
+     */
+    async listJobs(opts = {}) {
+        const r = await this.request('jobs');
+        let list = Array.isArray(r) ? r : r.jobs || [];
+        if (opts.status)
+            list = list.filter((j) => j.status === opts.status);
+        if (opts.limit)
+            list = list.slice(0, opts.limit);
+        return list;
+    }
+    /**
+     /** 提交出图 + 自动轮询直到完成/失败。
+      * onProgress 可选，每次轮询回调一次（用于 CLI 显示进度）。
+      */
+    async generateAndWait(opts, onProgress, intervalMs = 3000, maxAttempts = 100) {
+        const { jobId } = await this.generate(opts);
+        for (let i = 0; i < maxAttempts; i++) {
+            await sleep(intervalMs);
+            const job = await this.getJob(jobId);
+            onProgress?.(job.status);
+            if (job.status === 'done')
+                return job;
+            if (job.status === 'failed') {
+                throw new Error(`出图失败: ${job.error || '未知原因'}（jobId: ${jobId}）`);
+            }
+        }
+        throw new Error(`出图超时（${(maxAttempts * intervalMs) / 1000}s 未返回，jobId: ${jobId}）`);
+    }
+    /** 提交视频任务（POST /api/videos）——video 走独立链路，不走图片 queue */
+    async generateVideo(opts) {
+        const body = {};
+        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;
+        const r = await this.request('videos', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        return { jobId: r.job_id || r.id, upstreamTaskId: r.id };
+    }
+    /** 轮询视频任务直到完成/失败。返回 { cdn_url, status } */
+    async waitVideo(jobId, onProgress, intervalMs = 5000, maxAttempts = 120) {
+        for (let i = 0; i < maxAttempts; i++) {
+            await sleep(intervalMs);
+            const r = await this.request(`videos?id=${encodeURIComponent(jobId)}`);
+            onProgress?.(r.status || 'processing');
+            if (r.status === 'completed')
+                return { cdn_url: r.cdn_url || null, status: 'completed' };
+            if (r.status === 'failed')
+                return { cdn_url: null, status: 'failed', error: r.error || '未知原因' };
+        }
+        throw new Error(`视频生成超时（${(maxAttempts * intervalMs) / 1000}s 未完成，jobId: ${jobId}）`);
+    }
+    /**
+     * 图片逆向（**纯读图**）：传文件路径或图片 URL，拿回 SCULPT 六要素与出图 prompt。
+     *
+     * ⚠️ 这里只发图片，一个别的字段都不发。2026-08-16 中台把「读图」和「把图做成模板」
+     * 拆成两个接口后，/api/reverse 见到 variablize / variables / variable_labels /
+     * create_template / template / async 任何一个都会直接 400（不是静默忽略）。
+     * 要做模板走 imageToTemplate()。
+     */
+    async reverse(input) {
+        if (input.file) {
+            return this.request('reverse', { method: 'POST', body: fileForm(input.file) });
+        }
+        return this.request('reverse', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ image_url: input.imageUrl }),
+        });
+    }
+    /**
+     * 上传素材（POST /api/upload-ref），返回公网直链。
+     *
+     * 图片 / 音频 / 视频都收：中台按**字节魔数**判真实类型（不信客户端声明的 MIME），
+     * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
+     * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
+     */
+    async uploadRef(filePath) {
+        const r = await this.request('upload-ref', { method: 'POST', body: fileForm(filePath) });
+        return { url: r.url, media_type: r.media_type, mime: r.mime };
+    }
+    /**
+     * 图片转模板（POST /api/image-to-template）：一张图 → 一个可复用的图片模板。
+     *
+     * 同步还是异步**由入参决定，不要猜**（中台契约 §7.6）：
+     *   createTemplate=true 或 async=true → 返回 { jobId }（这里是 ImageToTemplateJob）
+     *   两者都不给                        → 直接返回结果本体（ImageToTemplateResult）
+     * 调用方用返回值里有没有 jobId 区分，见 isAsyncJob()。
+     *
+     * 这个接口没有 variablize 开关：调它本身就是「我要模板」这个意图。
+     */
+    async imageToTemplate(input) {
+        const { file, imageUrl, variables, variableLabels, createTemplate, template, async: forceAsync } = input;
+        if (file) {
+            // multipart 分支：中台 formOptions() 对这几个键做 JSON.parse（variables 还支持逗号分隔），
+            // 所以对象/数组要自己序列化成字符串，不能直接塞进 FormData。
+            const fd = fileForm(file);
+            if (variables?.length)
+                fd.append('variables', JSON.stringify(variables));
+            if (variableLabels)
+                fd.append('variable_labels', JSON.stringify(variableLabels));
+            if (createTemplate)
+                fd.append('create_template', 'true');
+            if (template)
+                fd.append('template', JSON.stringify(template));
+            if (forceAsync)
+                fd.append('async', 'true');
+            return this.request('image-to-template', { method: 'POST', body: fd });
+        }
+        const body = { image_url: imageUrl };
+        if (variables?.length)
+            body.variables = variables;
+        if (variableLabels)
+            body.variable_labels = variableLabels;
+        if (createTemplate)
+            body.create_template = true;
+        if (template)
+            body.template = template;
+        if (forceAsync)
+            body.async = true;
+        return this.request('image-to-template', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    /** 取 image-to-template 异步任务的**结果本体**（进度看 getJob 的 steps，结果在这里） */
+    async getImageToTemplateResult(jobId) {
+        return this.request(`image-to-template?job_id=${encodeURIComponent(jobId)}`);
+    }
+    /**
+     * 轮询 image-to-template 异步任务直到终态，返回结果本体。
+     *
+     * 进度和结果是两条通道（中台刻意分开的）：阶段在 GET /api/jobs?id= 的 steps 里，
+     * 结果在 GET /api/image-to-template?job_id= 里。所以这里每轮先拉 job 看阶段
+     * （回调给 CLI 打「正在解析图片…」），到终态再去取结果。
+     */
+    async waitImageToTemplate(jobId, onStep, intervalMs = 3000, maxAttempts = 100) {
+        for (let i = 0; i < maxAttempts; i++) {
+            await sleep(intervalMs);
+            const job = await this.getJob(jobId);
+            if (job.steps?.length)
+                onStep?.(job.steps);
+            if (job.status !== 'done' && job.status !== 'failed')
+                continue;
+            const out = await this.getImageToTemplateResult(jobId);
+            if (job.status === 'failed' || out.status === 'failed') {
+                throw new Error(`图生模板失败: ${out.error || job.error || '未知原因'}（jobId: ${jobId}）`);
+            }
+            if (!out.result) {
+                // 任务是 done 但结果取不到——中台把原因写在 error 里（例如结果列缺失还没跑迁移）。
+                // 不再继续轮询：状态已经是终态，等下去也不会变。
+                throw new Error(`任务已完成但取不到结果：${out.error || '中台未返回 result'}（jobId: ${jobId}）`);
+            }
+            return out.result;
+        }
+        throw new Error(`图生模板超时（${(maxAttempts * intervalMs) / 1000}s 未完成，jobId: ${jobId}）`);
+    }
+    /** 查当前登录账户信息（含租户归属品牌）。仅个人 token 鉴权可用，apiKey 调用会 401。 */
+    async me() {
+        return this.request('me');
+    }
+    /** 查可用模型列表 */
+    async models() {
+        return this.request('available-models');
+    }
+    /** 查上游余额 */
+    async balance() {
+        return this.request('balance');
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * 把本地文件包成 multipart 的 file 字段。
+ *
+ * 带上原文件名：中台判类型靠字节魔数不靠这个，但文件名会进日志/对象存储的排查线索，
+ * 匿名的 "blob" 出问题时谁也认不出是哪张图。故意不设 MIME——声明的 MIME 中台本来就不信。
+ */
+function fileForm(filePath) {
+    const fd = new FormData();
+    fd.append('file', new Blob([readFileSync(filePath)]), basename(filePath));
+    return fd;
+}
+/**
+ * 区分 imageToTemplate() 拿到的是异步回执还是结果本体。
+ * 判据是有没有 jobId —— 跟中台契约一致，不靠 status 字符串猜。
+ */
+export function isAsyncJob(r) {
+    return typeof r.jobId === 'string';
+}

package/dist/commands/assets.d.ts

@@ -0,0 +1,14 @@
+/**
+ * museav assets —— 查所属租户自己的素材/资产库。
+ *
+ * 数据不在 Studio 中台，在租户自己的后台（见 ../tenant-client.ts 顶部注释）。
+ *
+ * 【响应形状故意没有统一】两个已接入租户的"素材"根本不是一回事：
+ *   - 好易美（hym）：明星素材库 + 贴图库两张互不关联的表 → 返回
+ *     { celebrity_materials: [...], stickers: [...] }
+ *   - mzmeso：品牌素材库 brand_assets 一张表 → 返回扁平数组 [...]
+ * 调查过程中发现二者字段/数量级差异很大，硬凑成一种格式只会两边都不像，所以这里
+ * 按响应形状分别展示，而不是假装它们是同一种资源。
+ */
+import type { TenantClient } from '../tenant-client.js';
+export declare function assets(client: TenantClient): Promise<void>;

package/dist/commands/assets.js

@@ -0,0 +1,30 @@
+export async function assets(client) {
+    const data = await client.get('tenant-assets');
+    if (Array.isArray(data)) {
+        if (!data.length) {
+            process.stderr.write('该租户暂无素材数据\n');
+            console.log('[]');
+            return;
+        }
+        process.stderr.write(`素材（${data.length} 个）:\n`);
+        for (const a of data) {
+            process.stderr.write(`  ${String(a.id).padEnd(38)} ${String(a.category || '').padEnd(14)} ${String(a.name || '')}\n`);
+        }
+        console.log(JSON.stringify(data));
+        return;
+    }
+    if (data && typeof data === 'object') {
+        const obj = data;
+        for (const [group, rows] of Object.entries(obj)) {
+            const list = Array.isArray(rows) ? rows : [];
+            process.stderr.write(`${group}（${list.length} 个）:\n`);
+            for (const r of list) {
+                process.stderr.write(`  ${String(r.id).padEnd(38)} ${String(r.name || r.artist || '')}\n`);
+            }
+        }
+        console.log(JSON.stringify(obj));
+        return;
+    }
+    process.stderr.write('返回数据格式未知，原样输出到 stdout\n');
+    console.log(JSON.stringify(data));
+}

package/dist/commands/balance.d.ts

@@ -0,0 +1,3 @@
+/** museav balance —— 查租户余额（¥，实时计算：充值总额 − 历史消耗） */
+import type { StudioClient } from '../client.js';
+export declare function balance(client: StudioClient): Promise<void>;

package/dist/commands/balance.js

@@ -0,0 +1,11 @@
+export async function balance(client) {
+    const r = await client.balance();
+    // 单位 ¥ 人民币（后台 2026-08-09 起只返回租户自己的余额，不再下发上游供应商聚合数据）
+    process.stderr.write(`余额: ¥${r.balance_usd?.toFixed(2) ?? '?'}`);
+    if (r.markup_pct)
+        process.stderr.write(`  加价率: ${(r.markup_pct * 100).toFixed(0)}%`);
+    if (r.checked_at)
+        process.stderr.write(`  校验时间: ${r.checked_at.slice(0, 19).replace('T', ' ')}`);
+    process.stderr.write('\n');
+    console.log(JSON.stringify(r));
+}

package/dist/commands/bind-feishu.d.ts

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

package/dist/commands/bind-feishu.js

@@ -0,0 +1,63 @@
+/**
+ * museav bind-feishu —— CLI 绑定飞书（设备码模式，2026-08-15）
+ *
+ * 流程：CLI 调 /feishu-bind/cli-start（需个人 login token）→ 终端显示验证码 + 授权链接
+ *      → 用户在浏览器打开链接（已登录后台）授权飞书 → CLI 轮询 /feishu-bind/cli-poll
+ *      → 绑定完成，提示已关联的平台账户数。
+ *
+ * 一个飞书 open_id 可绑定多个平台账户（owner 的 gmail/163 双 superadmin）：
+ * 绑定后 agent 在飞书里能认出你（resolveSpeaker superadmin 优先）。
+ * 只支持个人 login 账户；租户 apiKey 身份无法绑定个人飞书。
+ */
+import { loadConfig, DEFAULT_BASE_URL } from '../config.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function bindFeishu(opts) {
+    const baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const cfg = loadConfig();
+    if (!cfg.token) {
+        throw new Error('绑定飞书需要个人账户登录：先执行 museav login（租户 apiKey 无法绑定个人飞书）');
+    }
+    process.stderr.write('正在发起飞书绑定...\n');
+    const startResp = await fetch(`${baseUrl}/api/feishu-bind/cli-start`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${cfg.token}` },
+    });
+    if (!startResp.ok) {
+        const d = await startResp.json().catch(() => ({}));
+        throw new Error(`发起绑定失败: HTTP ${startResp.status} ${d?.error || ''}`);
+    }
+    const start = await startResp.json();
+    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.authorize_url + '\n');
+    process.stderr.write('│                                                  │\n');
+    process.stderr.write('└──────────────────────────────────────────────────┘\n');
+    process.stderr.write('\n等待授权完成...（可随时 Ctrl+C 取消）\n');
+    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/feishu-bind/cli-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') {
+            const n = poll.linked_count || 1;
+            process.stderr.write(`\n✅ 飞书绑定成功！已关联 ${n} 个平台账户。agent 在飞书里能认出你了。\n`);
+            return;
+        }
+        if (poll.status === 'expired') {
+            throw new Error('绑定请求已过期，请重新执行 museav bind-feishu');
+        }
+    }
+    throw new Error('绑定超时，请重新执行 museav bind-feishu');
+}

package/dist/commands/gen.d.ts

@@ -0,0 +1,16 @@
+/** museav gen —— 出图 / 出视频（核心命令） */
+import type { StudioClient } from '../client.js';
+export declare function gen(client: StudioClient, opts: {
+    prompt?: string;
+    skill?: string;
+    input?: string;
+    template?: string;
+    fields?: string;
+    ratio?: string;
+    model?: string;
+    quality?: string;
+    ref?: string;
+    video?: boolean;
+    duration?: number;
+    image?: string;
+}): Promise<void>;

package/dist/commands/gen.js

@@ -0,0 +1,88 @@
+export async function gen(client, opts) {
+    // prompt / skill / template 三选一。commander 不好表达互斥，在这里校验，报错要说清怎么改
+    const picked = [opts.prompt, opts.skill, opts.template].filter(Boolean).length;
+    if (picked === 0) {
+        throw new Error('需要 --prompt "完整提示词" 或 --skill <技能名>（museav skills 查）或 --template <模板id>（museav templates 查）');
+    }
+    if (picked > 1) {
+        throw new Error('--prompt / --skill / --template 只能给一个：分别对应自己写提示词、用中台技能展开、用图片模板展开');
+    }
+    if (opts.input && !opts.skill) {
+        throw new Error('--input 是配合 --skill 的业务描述；只写提示词请用 --prompt');
+    }
+    if (opts.fields && !opts.template) {
+        throw new Error('--fields 是配合 --template 的占位符取值；用技能请用 --input');
+    }
+    if (opts.video && opts.skill) {
+        throw new Error('--video 暂不支持配合 --skill（视频模板走 --template 或直接 --prompt）');
+    }
+    let templateFields;
+    if (opts.fields) {
+        try {
+            templateFields = JSON.parse(opts.fields);
+        }
+        catch {
+            throw new Error(`--fields 必须是合法 JSON 对象，如 '{"artist":"王嘉尔","city":"南京"}'，收到: ${opts.fields}`);
+        }
+    }
+    // 可选：先上传垫图（图片出图 --ref / 视频图生视频 --image 都走这里）
+    let referenceImage;
+    const refPath = opts.ref || opts.image;
+    if (refPath) {
+        process.stderr.write(`上传垫图 ${refPath} ...\n`);
+        const up = await client.uploadRef(refPath);
+        referenceImage = up.url;
+        process.stderr.write(`垫图就绪: ${referenceImage}\n`);
+    }
+    // ── 视频模式：走 /api/videos 独立链路 ──
+    if (opts.video) {
+        if (opts.quality)
+            throw new Error('--quality 仅图片出图支持');
+        if (opts.skill)
+            throw new Error('--video 暂不支持配合 --skill（视频模板走 --template，清单用 museav video-templates 查）');
+        process.stderr.write(`提交视频: ${opts.template ? `模板 ${opts.template}` : opts.prompt?.slice(0, 40) || ''}${opts.image ? ' · 图生视频' : ''}\n`);
+        const { jobId } = await client.generateVideo({
+            prompt: opts.prompt,
+            model: opts.model,
+            ratio: opts.ratio,
+            duration: opts.duration,
+            image_url: referenceImage,
+            template_id: opts.template,
+            input: templateFields,
+        });
+        process.stderr.write(`视频任务已提交: ${jobId}\n生成中（视频通常 1-5 分钟）...\n`);
+        const result = await client.waitVideo(jobId, (status) => {
+            if (status === 'processing')
+                process.stderr.write('生成中...\r');
+        });
+        if (result.status !== 'completed' || !result.cdn_url) {
+            throw new Error(`视频生成失败: ${result.error || '未知原因'}`);
+        }
+        process.stderr.write(`✅ 视频完成\n`);
+        console.log(result.cdn_url);
+        return;
+    }
+    // ── 图片模式（原逻辑）──
+    process.stderr.write(opts.skill
+        ? `提交出图: 技能 ${opts.skill}${opts.input ? ` · ${opts.input.slice(0, 30)}` : '（未给描述，按技能规范自由发挥）'}\n`
+        : opts.template
+            ? `提交出图: 模板 ${opts.template}${templateFields ? ` · ${JSON.stringify(templateFields).slice(0, 40)}` : ''}\n`
+            : `提交出图: ${opts.prompt.slice(0, 40)}...\n`);
+    const job = await client.generateAndWait({
+        prompt: opts.prompt,
+        skill_slug: opts.skill,
+        input: opts.input,
+        template_id: opts.template,
+        template_fields: templateFields,
+        ratio: opts.ratio,
+        model: opts.model,
+        quality: opts.quality,
+        reference_image: referenceImage,
+    }, (status) => {
+        if (status === 'processing')
+            process.stderr.write('生成中...\r');
+    });
+    // 成功：图片 URL 输出到 stdout（便于管道），元信息到 stderr
+    process.stderr.write(`✅ 完成 (${job.elapsed_ms ? (job.elapsed_ms / 1000).toFixed(1) + 's' : '?'})\n`);
+    console.log(job.cdn_url);
+}

package/dist/commands/image-to-template.d.ts

@@ -0,0 +1,24 @@
+/**
+ * museav image-to-template —— 一张图 → 一个可复用的图片模板。
+ *
+ * 跟 reverse 的分工（中台 2026-08-16 拆成两个接口，别再混）：
+ *   reverse            只读图：SCULPT 六要素 + 出图 prompt，一次模型调用，同步返回。
+ *   image-to-template  读图 + 文字层逆向 + 变量化 + 建模板，原图还会被焊成模板的参考图。
+ * 想要哪个就调哪个，没有开关可拨——调用这个命令本身就是「我要模板」的意图。
+ *
+ * 同步/异步不由 --async 一个人说了算（中台契约 §7.6）：
+ *   建模板（默认）或显式 --async → 异步，先拿 jobId 再轮询
+ *   --no-create 且没给 --async  → 同步，直接返回草稿
+ */
+import type { StudioClient } from '../client.js';
+export interface ImageToTemplateOpts {
+    /** commander 的 --no-create 会把 create 置 false，默认 true */
+    create?: boolean;
+    name?: string;
+    slug?: string;
+    category?: string;
+    variables?: string;
+    labels?: string;
+    async?: boolean;
+}
+export declare function imageToTemplate(client: StudioClient, input: string, opts?: ImageToTemplateOpts): Promise<void>;