museav-cli 2.0.0

package/dist/client.d.ts

@@ -0,0 +1,387 @@
+export interface GenerateOptions {
+    /** 自己写完整提示词。与 skill_slug / template_id 三选一 */
+    prompt?: string;
+    /**
+     * 用中台技能出图（技能黑盒）：提示词正文在服务端展开，不下发。
+     * 查找顺序：自己的私有技能 → 所属租户的专属模板 → 公共技能库。
+     * 与 prompt / template_id 三选一。
+     */
+    skill_slug?: string;
+    /** 配合 skill_slug 的一句业务描述，如「米白色针织衫」。不给则按技能规范自由发挥 */
+    input?: string;
+    /**
+     * 用图片模板出图（模板黑盒）：提示词模板在服务端展开，确定性字符串替换，不经模型、
+     * 不产生 chat 成本。模板清单用 museav templates 查。与 prompt / skill_slug 三选一。
+     */
+    template_id?: string;
+    /** 配合 template_id 的占位符取值，如 {artist:'王嘉尔', city:'南京'}；模板没有占位符则不用传 */
+    template_fields?: Record<string, string>;
+    ratio?: string;
+    model?: string;
+    reference_image?: string;
+    quality?: 'low' | 'medium' | 'high';
+}
+/** 图片/文字模板清单项（GET /api/templates，template_type=image|article） */
+export interface TemplateOption {
+    id: string;
+    category: string;
+    zh_name: string;
+    description?: string;
+    ratio: string;
+    /** image=图片模板 / article=文字模板（视频模板在 videoTemplates()） */
+    template_type?: string;
+    sample_images?: string[] | null;
+    /** 视频模板专用：参考视频/封面（video-templates 接口返回，租户后台和 CLI 都靠它看参考） */
+    sample_video_url?: string | null;
+    sample_cover_image?: string | null;
+    /** 归属：自己租户建的 vs 平台共享的（tenant_id 为空） */
+    tenant_id: string | null;
+    generation_configs: Array<{
+        model: string;
+        prompt_template: string;
+        ref_slots?: string[];
+        params_json?: {
+            fields?: Array<{
+                key: string;
+                label: string;
+                placeholder?: string;
+            }>;
+        };
+        is_default?: boolean;
+    }>;
+}
+/**
+ * 新建模板入参（POST /api/templates）。不传 tenant_id —— 归属完全由服务端根据
+ * 调用者身份决定：租户 apiKey 自动打自己的 tenant_id，平台管理员 JWT 建的是
+ * tenant_id=null 的平台共享模板，个人账号（无租户、非管理员）会被服务端拒绝（401）。
+ */
+export interface CreateTemplateInput {
+    zh_name: string;
+    category?: string;
+    description?: string;
+    ratio?: string;
+    /** image=图片模板 / article=文字模板（不传默认 image，跟中台一致） */
+    template_type?: 'image' | 'article';
+    generation_configs: Array<{
+        model: string;
+        prompt_template: string;
+        quality?: string;
+        /** 表单字段声明——按中台契约放 config 顶层（不是 params_json 里），服务端校验/渲染都读这里 */
+        fields?: Array<{
+            key: string;
+            label: string;
+        }>;
+        is_default?: boolean;
+    }>;
+}
+/** 新建视频模板入参（POST /api/video-templates）。视频模板字段跟图片不同：
+ *  ratio/duration/model 放在 generation_configs 每项里。 */
+export interface CreateVideoTemplateInput {
+    zh_name: string;
+    category?: string;
+    description?: string;
+    sample_video_url?: string | null;
+    sample_cover_image?: string | null;
+    generation_configs: Array<{
+        model?: string;
+        duration?: number;
+        aspect_ratio?: string;
+        prompt_template?: string;
+        is_default?: boolean;
+    }>;
+}
+/** 技能清单项（GET /api/skills） */
+export interface SkillOption {
+    slug: string;
+    zh_name?: string;
+    description?: string;
+    genre?: string;
+    ratio?: string;
+    ref_required?: boolean;
+    /** 私有技能（自己建的） */
+    private?: boolean;
+    /** 所属租户的专属模板 */
+    agency?: boolean;
+}
+/**
+ * 任务进度里的业务阶段。中台的口径（别自己重新发明）：
+ *   job.status 只有 pending / done / failed —— 业务阶段**不在 status 里**，在 steps 里。
+ *   每步 status：running=正在做（可以直接拿来渲染「正在解析图片…」）、ok=做完、fail=卡在这步。
+ *   任务结束后不会再有 running。
+ */
+export interface JobStep {
+    name: string;
+    status: 'running' | 'ok' | 'fail';
+    ms: number | null;
+}
+export interface Job {
+    id: string;
+    status: 'pending' | 'processing' | 'done' | 'failed';
+    cdn_url: string | null;
+    error: string | null;
+    trace_id?: string;
+    model?: string;
+    elapsed_ms?: number;
+    created_at?: string;
+    /** 业务阶段进度（中台 sanitizeSteps 脱敏后下发），image-to-template 这类多阶段任务才有 */
+    steps?: JobStep[];
+}
+export interface ReverseResult {
+    ok: boolean;
+    sculpt: Record<string, string>;
+    prompt: string;
+    prompt_cn: string;
+    style_tags: string[];
+    aspect_ratio: string;
+    zh_name?: string;
+    description?: string;
+}
+/** 图上一处文字的逆向结果（POST /api/image-to-template 的 text_layers 每项） */
+export interface TextLayer {
+    role?: string;
+    content?: string;
+    position?: string;
+    font_category?: string;
+    font_weight?: string;
+    size_ratio?: number;
+    color?: string;
+    treatment?: string;
+    alignment?: string;
+    is_variable?: boolean;
+    variable?: string | null;
+}
+/** 模板表单字段声明（中台 7.3 的 fields 契约） */
+export interface TemplateField {
+    key: string;
+    label: string;
+    type?: string;
+    placeholder?: string;
+}
+/**
+ * POST /api/image-to-template 的结果本体（同步返回，或异步 job 完成后的 result）。
+ *
+ * 它是「读图结果 + 文字层 + 模板」三段的叠加：ReverseResult 那几个 key 照常给，
+ * 后面几个是这个接口独有的。中台的降级口径：文字层逆向 / 变量化 / 建模板任一步失败，
+ * 都只是 prompt_template=null + template_error=<原因>，sculpt / prompt_cn 照常返回——
+ * 所以 template 为 null **不等于** 整件事失败，要看 template_error。
+ */
+export interface ImageToTemplateResult extends ReverseResult {
+    image_category?: string;
+    text_layers?: TextLayer[];
+    /** 变量化后的提示词模具（含 {key} 占位符）。null = 这一步降级了，原因在 template_error */
+    prompt_template: string | null;
+    fields?: TemplateField[];
+    /** create_template=true 且建成时非空 */
+    template: {
+        id: string;
+        slug: string;
+        zh_name: string;
+        tenant_id: string | null;
+        reference_image?: string | null;
+    } | null;
+    /** 非 null = 模板没建成（读图结果仍然有效） */
+    template_error: string | null;
+    template_warnings?: string[];
+    reference_image?: string | null;
+}
+/** 异步提交后的回执（create_template=true 或 async=true 时中台返回这个，不是结果本体） */
+export interface ImageToTemplateJob {
+    ok: boolean;
+    jobId: string;
+    status: string;
+    async: boolean;
+}
+/** GET /api/image-to-template?job_id=<uuid> 的返回 */
+export interface ImageToTemplateJobResult {
+    ok: boolean;
+    job_id: string;
+    status: 'pending' | 'done' | 'failed';
+    error: string | null;
+    elapsed_ms: number | null;
+    result: ImageToTemplateResult | null;
+}
+/** image-to-template 入参（除图片外都可选，字段名与中台契约 §7.6 一一对应） */
+export interface ImageToTemplateInput {
+    /** 本地文件路径，与 imageUrl 二选一 */
+    file?: string;
+    /** 图片 URL，与 file 二选一 */
+    imageUrl?: string;
+    /** 允许出现的变量白名单，可收窄。不允许模型发明白名单外的变量 */
+    variables?: string[];
+    /** 变量 → 你自己的业务叫法，只影响 fields[].label；key 永远是中台通用语义 */
+    variableLabels?: Record<string, string>;
+    /** true = 直接建好模板（走异步）；false/不传 = 只回模板草稿 */
+    createTemplate?: boolean;
+    /** 模板元信息，缺省由中台生成。slug 全局唯一，撞了报错不覆盖 */
+    template?: {
+        zh_name?: string;
+        slug?: string;
+        category?: string;
+        domain?: string;
+    };
+    /** 强制异步（createTemplate=true 时本来就是异步） */
+    async?: boolean;
+}
+export interface ModelOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface Balance {
+    /** 数值单位是 ¥（人民币）。字段名带 usd 是历史遗留命名，不代表美元——中台侧不存在汇率换算 */
+    balance_usd: number;
+    /** 租户加价率（0.2 = 加价 20%） */
+    markup_pct: number;
+    checked_at: string;
+}
+export interface MeInfo {
+    id: string;
+    email: string;
+    nickname?: string;
+    role: string;
+    /** 邀请码注册的账户，若该邀请码归属某个租户，这里带出该租户的白标品牌；平台用户（无归属）为 null */
+    brand: {
+        name: string;
+        logo: string | null;
+    } | null;
+    gen_total: number;
+    gen_done: number;
+    skill_count: number;
+    generation_used: number | null;
+    generation_remaining: number | null;
+    creation_credits: number;
+    /** 租户 Key（apiKey）调用 /api/me 时返回：identity='tenant' + tenant 信息（2026-08-15） */
+    identity?: 'tenant';
+    tenant?: {
+        id: string;
+        name: string;
+        nickname: string;
+        logo: string | null;
+    };
+    /** 飞书绑定 open_id（已绑定飞书时存在，welcome 提示 agent 能认出你） */
+    feishu_open_id?: string | null;
+}
+export declare class StudioClient {
+    private baseUrl;
+    private authHeader;
+    constructor(opts: {
+        baseUrl: string;
+        apiKey?: string;
+        token?: string;
+    });
+    private headers;
+    private request;
+    /** 可用技能清单：私有 + 所属租户专属模板 + 公共库，服务端已按调用者权限过滤 */
+    skills(): Promise<SkillOption[]>;
+    /** 可用图片/文字模板清单：自己租户建的 + 平台共享的，服务端已按调用者权限过滤。
+     *  type=image|article 二选一（不传则图片+文字都返回，跟中台默认一致）。 */
+    templates(type?: 'image' | 'article'): Promise<TemplateOption[]>;
+    /** 视频模板清单（POST /api/videos 用 template_id）。结构同图片模板的 generation_configs 形态 */
+    videoTemplates(): Promise<TemplateOption[]>;
+    /** 新建图片模板。归属（是否关联租户）由服务端根据鉴权身份决定，见 CreateTemplateInput 注释 */
+    createTemplate(input: CreateTemplateInput): Promise<TemplateOption>;
+    /** 新建视频模板。归属同图片模板：租户 apiKey 自动归租户，平台管理员归平台共享 */
+    createVideoTemplate(input: CreateVideoTemplateInput): Promise<TemplateOption>;
+    /** 提交出图任务，立即返回 jobId */
+    generate(opts: GenerateOptions): Promise<{
+        jobId: string;
+        trace_id?: string;
+    }>;
+    /** 查单个任务状态 */
+    getJob(id: string): Promise<Job>;
+    /**
+     * 列出当前身份名下的出图工作流（不传 id，走同一个 jobs 端点的集合语义）。
+     * 范围由鉴权凭证决定：个人 token 只看得到自己出的图；租户 apiKey 看得到自己业务下的全部记录。
+     *
+     * 服务端 GET /api/jobs 目前只认 id / all 两个 query 参数，固定按 created_at
+     * 倒序返回最近 50 条，不支持 limit/status 这类过滤——传了也会被忽略。
+     * 所以 limit/status 在这里做客户端过滤：先拿到这最多 50 条，再本地按 status
+     * 筛、按 limit 截断。这意味着 --limit 只能在这 50 条以内选，选不到更早的历史。
+     */
+    listJobs(opts?: {
+        limit?: number;
+        status?: Job['status'];
+    }): Promise<Job[]>;
+    /**
+     /** 提交出图 + 自动轮询直到完成/失败。
+      * onProgress 可选，每次轮询回调一次（用于 CLI 显示进度）。
+      */
+    generateAndWait(opts: GenerateOptions, onProgress?: (status: string) => void, intervalMs?: number, maxAttempts?: number): Promise<Job>;
+    /** 提交视频任务（POST /api/videos）——video 走独立链路，不走图片 queue */
+    generateVideo(opts: {
+        prompt?: string;
+        model?: string;
+        ratio?: string;
+        duration?: number;
+        /** 图生视频：首帧/参考图 URL（中台内部自动上传垫图后拿到 URL 再传这里） */
+        image_url?: string;
+        template_id?: string;
+        input?: string | Record<string, string>;
+        callback_url?: string;
+    }): Promise<{
+        jobId: string;
+        upstreamTaskId?: string;
+    }>;
+    /** 轮询视频任务直到完成/失败。返回 { cdn_url, status } */
+    waitVideo(jobId: string, onProgress?: (status: string) => void, intervalMs?: number, maxAttempts?: number): Promise<{
+        cdn_url: string | null;
+        status: string;
+        error?: string;
+    }>;
+    /**
+     * 图片逆向（**纯读图**）：传文件路径或图片 URL，拿回 SCULPT 六要素与出图 prompt。
+     *
+     * ⚠️ 这里只发图片，一个别的字段都不发。2026-08-16 中台把「读图」和「把图做成模板」
+     * 拆成两个接口后，/api/reverse 见到 variablize / variables / variable_labels /
+     * create_template / template / async 任何一个都会直接 400（不是静默忽略）。
+     * 要做模板走 imageToTemplate()。
+     */
+    reverse(input: {
+        file?: string;
+        imageUrl?: string;
+    }): Promise<ReverseResult>;
+    /**
+     * 上传素材（POST /api/upload-ref），返回公网直链。
+     *
+     * 图片 / 音频 / 视频都收：中台按**字节魔数**判真实类型（不信客户端声明的 MIME），
+     * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
+     * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
+     */
+    uploadRef(filePath: string): Promise<{
+        url: string;
+        media_type?: string;
+        mime?: string;
+    }>;
+    /**
+     * 图片转模板（POST /api/image-to-template）：一张图 → 一个可复用的图片模板。
+     *
+     * 同步还是异步**由入参决定，不要猜**（中台契约 §7.6）：
+     *   createTemplate=true 或 async=true → 返回 { jobId }（这里是 ImageToTemplateJob）
+     *   两者都不给                        → 直接返回结果本体（ImageToTemplateResult）
+     * 调用方用返回值里有没有 jobId 区分，见 isAsyncJob()。
+     *
+     * 这个接口没有 variablize 开关：调它本身就是「我要模板」这个意图。
+     */
+    imageToTemplate(input: ImageToTemplateInput): Promise<ImageToTemplateResult | ImageToTemplateJob>;
+    /** 取 image-to-template 异步任务的**结果本体**（进度看 getJob 的 steps，结果在这里） */
+    getImageToTemplateResult(jobId: string): Promise<ImageToTemplateJobResult>;
+    /**
+     * 轮询 image-to-template 异步任务直到终态，返回结果本体。
+     *
+     * 进度和结果是两条通道（中台刻意分开的）：阶段在 GET /api/jobs?id= 的 steps 里，
+     * 结果在 GET /api/image-to-template?job_id= 里。所以这里每轮先拉 job 看阶段
+     * （回调给 CLI 打「正在解析图片…」），到终态再去取结果。
+     */
+    waitImageToTemplate(jobId: string, onStep?: (steps: JobStep[]) => void, intervalMs?: number, maxAttempts?: number): Promise<ImageToTemplateResult>;
+    /** 查当前登录账户信息（含租户归属品牌）。仅个人 token 鉴权可用，apiKey 调用会 401。 */
+    me(): Promise<MeInfo>;
+    /** 查可用模型列表 */
+    models(): Promise<ModelOption[]>;
+    /** 查上游余额 */
+    balance(): Promise<Balance>;
+}
+/**
+ * 区分 imageToTemplate() 拿到的是异步回执还是结果本体。
+ * 判据是有没有 jobId —— 跟中台契约一致，不靠 status 字符串猜。
+ */
+export declare function isAsyncJob(r: ImageToTemplateResult | ImageToTemplateJob): r is ImageToTemplateJob;