gaoding-cli 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/src/creative/contract.js

@@ -0,0 +1,743 @@
+import { CliUsageError } from "../core/output/cli-error.js";
+export const CREATIVE_SCHEMA_VERSION = "creative/v1";
+export const CREATIVE_INPUT_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://www.gaoding.com/cli/schemas/creative-input-v1.json",
+    title: "Creative Input",
+    description: "发起或继续一次稿定 Creative 创作所需的完整输入。",
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        prompt: {
+            type: "string",
+            minLength: 1,
+            description: "详细描述期望的最终结果，包括主体、用途、内容、风格、场景、构图或镜头，以及必须保留和避免的事项。比例、分辨率、时长等可结构化表达的要求，建议通过 parameters 传入。",
+        },
+        media: {
+            type: "array",
+            minItems: 1,
+            description: "本次创作使用的输入素材；媒体不能脱离 prompt 或 answers 单独提交。",
+            items: {
+                type: "object",
+                description: "一份带有明确用途的输入素材。",
+                additionalProperties: false,
+                required: ["source", "role"],
+                properties: {
+                    source: {
+                        type: "string",
+                        minLength: 1,
+                        description: "本地文件路径或可访问的 HTTP(S) URL。",
+                    },
+                    role: {
+                        type: "string",
+                        enum: ["reference", "first_frame", "last_frame"],
+                        description: "素材用途；reference 是参考素材，first_frame 和 last_frame 分别是视频首帧和尾帧。CLI 不根据数组顺序、文件名或 prompt 推断。",
+                    },
+                },
+            },
+        },
+        parameters: {
+            type: "object",
+            description: "可选的结构化创作约束。GD Agent 会优先遵循本字段中的约束；存在对应参数时，建议使用本字段，而不是仅在 prompt 中通过文本描述。",
+            additionalProperties: false,
+            properties: {
+                ratio: {
+                    type: "string",
+                    minLength: 1,
+                    description: "期望输出媒体的宽高比，例如 1:1、16:9 或 9:16。",
+                },
+                resolution: {
+                    type: "string",
+                    minLength: 1,
+                    description: "期望输出媒体的分辨率，例如 720p、1080p、2K 或 4K。",
+                },
+                duration_seconds: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "期望生成视频的时长，单位为秒；仅适用于视频创作。",
+                },
+            },
+        },
+        conversation_id: {
+            type: "string",
+            minLength: 1,
+            description: "继续已有创作或回答追问时使用的会话标识；首次请求和独立的新创作不传。",
+        },
+        last_tool_message_id: {
+            type: "string",
+            minLength: 1,
+            description: "正在回答或跳过的追问消息标识，原样使用上一次 requires_input 输出中的值。",
+        },
+        answers: {
+            type: "array",
+            minItems: 1,
+            description: "对上一次 requires_input 输出中一个或多个问题的结构化回答。",
+            items: {
+                type: "object",
+                description: "对一条 GD Agent 追问的回答。",
+                additionalProperties: false,
+                required: ["question", "values"],
+                properties: {
+                    question: {
+                        type: "string",
+                        minLength: 1,
+                        description: "必须与上一次输出中的 question 文本一致。",
+                    },
+                    values: {
+                        type: "array",
+                        minItems: 1,
+                        description: "选择项或自定义回答；推荐 options 不是枚举限制。",
+                        items: {
+                            type: "string",
+                            minLength: 1,
+                            description: "一项非空的选择值或自定义回答。",
+                        },
+                    },
+                },
+            },
+        },
+    },
+    anyOf: [
+        {
+            description: "普通新创作或连续编辑必须提供 prompt。",
+            required: ["prompt"],
+        },
+        {
+            description: "回答追问时 answers 可以替代 prompt，但必须同时携带两个连续对话标识。",
+            required: ["answers", "conversation_id", "last_tool_message_id"],
+        },
+    ],
+    dependentRequired: {
+        answers: ["conversation_id", "last_tool_message_id"],
+        last_tool_message_id: ["conversation_id"],
+    },
+    allOf: [
+        {
+            description: "first_frame 最多出现一次。",
+            properties: {
+                media: {
+                    description: "用于检查首帧数量的素材列表。",
+                    contains: {
+                        type: "object",
+                        properties: {
+                            role: {
+                                const: "first_frame",
+                                description: "首帧素材角色。",
+                            },
+                        },
+                        required: ["role"],
+                    },
+                    minContains: 0,
+                    maxContains: 1,
+                },
+            },
+        },
+        {
+            description: "last_frame 最多出现一次。",
+            properties: {
+                media: {
+                    description: "用于检查尾帧数量的素材列表。",
+                    contains: {
+                        type: "object",
+                        properties: {
+                            role: {
+                                const: "last_frame",
+                                description: "尾帧素材角色。",
+                            },
+                        },
+                        required: ["role"],
+                    },
+                    minContains: 0,
+                    maxContains: 1,
+                },
+            },
+        },
+    ],
+};
+export const CREATIVE_OUTPUT_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://www.gaoding.com/cli/schemas/creative-output-v1.json",
+    title: "Creative Output",
+    description: "creative run 的统一最终输出；中间事件和内部调用过程不属于本 Schema。",
+    type: "object",
+    additionalProperties: false,
+    required: ["status", "data", "error", "meta"],
+    properties: {
+        status: {
+            type: "string",
+            enum: ["completed", "failed"],
+            description: "CLI 调用是否成功；requires_input 仍属于 completed。",
+        },
+        data: {
+            description: "status 为 completed 时存在的 Creative 最终结果；failed 时为 null。",
+            oneOf: [{ $ref: "#/$defs/result" }, { type: "null" }],
+        },
+        error: {
+            description: "status 为 failed 时存在的结构化错误；completed 时为 null。",
+            oneOf: [{ $ref: "#/$defs/error" }, { type: "null" }],
+        },
+        meta: {
+            type: "object",
+            description: "本次输出对应的命令与公共契约版本。",
+            additionalProperties: false,
+            required: ["command", "schema_version"],
+            properties: {
+                command: {
+                    const: "creative run",
+                    description: "产生本 Envelope 的 GD CLI 命令。",
+                },
+                schema_version: {
+                    const: CREATIVE_SCHEMA_VERSION,
+                    description: "Creative 公共契约版本。",
+                },
+            },
+        },
+    },
+    oneOf: [
+        {
+            description: "成功完成或需要使用者继续回答的结果。",
+            properties: {
+                status: { const: "completed", description: "成功状态。" },
+                data: { $ref: "#/$defs/result", description: "Creative 结果。" },
+                error: { type: "null", description: "成功时没有错误。" },
+            },
+        },
+        {
+            description: "校验、认证、业务或网络失败的结果。",
+            properties: {
+                status: { const: "failed", description: "失败状态。" },
+                data: { type: "null", description: "失败时没有 Creative 结果。" },
+                error: { $ref: "#/$defs/error", description: "结构化失败信息。" },
+            },
+        },
+    ],
+    $defs: {
+        result: {
+            type: "object",
+            description: "GD Agent 本轮的最终结果。",
+            additionalProperties: false,
+            required: ["conversation_id", "finish_reason", "message", "outputs"],
+            properties: {
+                conversation_id: {
+                    type: "string",
+                    minLength: 1,
+                    description: "新请求由 GD Agent 创建；连续请求沿用输入值。",
+                },
+                finish_reason: {
+                    type: "string",
+                    enum: ["completed", "requires_input"],
+                    description: "completed 表示本轮完成；requires_input 表示需要继续回答 questions。",
+                },
+                message: {
+                    type: "string",
+                    description: "GD Agent 面向使用者的最终说明。",
+                },
+                outputs: {
+                    type: "array",
+                    description: "本轮最终产出的文本、结构化数据或媒体。",
+                    items: { $ref: "#/$defs/output", description: "一项 Creative 最终产出。" },
+                },
+                last_tool_message_id: {
+                    type: "string",
+                    minLength: 1,
+                    description: "requires_input 时必填，并在下一次请求中原样回传。",
+                },
+                questions: {
+                    $ref: "#/$defs/question_group",
+                    description: "requires_input 时必填的结构化追问。",
+                },
+            },
+            allOf: [
+                {
+                    if: {
+                        properties: {
+                            finish_reason: {
+                                const: "requires_input",
+                                description: "需要使用者回答。",
+                            },
+                        },
+                    },
+                    then: { required: ["last_tool_message_id", "questions"] },
+                    else: {
+                        not: {
+                            anyOf: [
+                                { required: ["last_tool_message_id"] },
+                                { required: ["questions"] },
+                            ],
+                        },
+                    },
+                },
+            ],
+        },
+        question_group: {
+            type: "object",
+            description: "GD Agent 在本轮提出的一组问题。",
+            additionalProperties: false,
+            required: ["title", "questions"],
+            properties: {
+                title: {
+                    type: "string",
+                    description: "本组追问的标题。",
+                },
+                questions: {
+                    type: "array",
+                    minItems: 1,
+                    description: "需要使用者回答的一个或多个问题。",
+                    items: {
+                        type: "object",
+                        description: "一条 GD Agent 追问。",
+                        additionalProperties: false,
+                        required: ["question", "options", "allow_multiple"],
+                        properties: {
+                            question: {
+                                type: "string",
+                                minLength: 1,
+                                description: "问题文本；提交 answers 时原样作为 answers[].question。",
+                            },
+                            options: {
+                                type: "array",
+                                description: "推荐选项，可以为空；label 不是严格枚举。",
+                                items: {
+                                    type: "object",
+                                    description: "一项推荐回答。",
+                                    additionalProperties: false,
+                                    required: ["label"],
+                                    properties: {
+                                        label: {
+                                            type: "string",
+                                            minLength: 1,
+                                            description: "推荐回答的展示文本。",
+                                        },
+                                    },
+                                },
+                            },
+                            allow_multiple: {
+                                type: "boolean",
+                                description: "是否允许为本问题提交多个回答值。",
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        output: {
+            description: "文本、JSON、图片、视频、音频或文件结果。",
+            oneOf: [
+                {
+                    type: "object",
+                    description: "文本结果。",
+                    additionalProperties: false,
+                    required: ["type", "text"],
+                    properties: {
+                        type: { const: "text", description: "结果类型。" },
+                        text: { type: "string", description: "文本内容。" },
+                    },
+                },
+                {
+                    type: "object",
+                    description: "可机器解析的结构化结果。",
+                    additionalProperties: false,
+                    required: ["type", "value"],
+                    properties: {
+                        type: { const: "json", description: "结果类型。" },
+                        value: { description: "任意合法 JSON 值。" },
+                    },
+                },
+                {
+                    type: "object",
+                    description: "最终媒体或文件结果。",
+                    additionalProperties: false,
+                    required: ["type", "url", "mime_type"],
+                    properties: {
+                        type: {
+                            type: "string",
+                            enum: ["image", "video", "audio", "file"],
+                            description: "媒体或文件类型。",
+                        },
+                        url: {
+                            type: "string",
+                            format: "uri",
+                            pattern: "^https?://",
+                            description: "可访问或下载结果的 HTTP(S) URL。",
+                        },
+                        mime_type: {
+                            type: "string",
+                            minLength: 1,
+                            description: "结果的 MIME type，例如 image/png 或 video/mp4。",
+                        },
+                        name: {
+                            type: "string",
+                            minLength: 1,
+                            description: "建议的展示名或文件名。",
+                        },
+                        asset_id: {
+                            type: "string",
+                            minLength: 1,
+                            description: "结果已进入 DAM 时的素材标识。",
+                        },
+                        width: {
+                            type: "number",
+                            minimum: 0,
+                            description: "图片或视频的像素宽度。",
+                        },
+                        height: {
+                            type: "number",
+                            minimum: 0,
+                            description: "图片或视频的像素高度。",
+                        },
+                        duration_seconds: {
+                            type: "number",
+                            minimum: 0,
+                            description: "视频或音频的时长，单位为秒。",
+                        },
+                    },
+                },
+            ],
+        },
+        error: {
+            type: "object",
+            description: "Creative 失败时的稳定错误信息。",
+            additionalProperties: false,
+            required: ["code", "type", "message"],
+            properties: {
+                code: {
+                    type: "string",
+                    minLength: 1,
+                    description: "稳定、可机器判断的错误码。",
+                },
+                type: {
+                    type: "string",
+                    enum: ["validation", "auth", "business", "network", "unknown"],
+                    description: "错误所属类别。",
+                },
+                message: {
+                    type: "string",
+                    minLength: 1,
+                    description: "面向使用者的错误说明。",
+                },
+                hint: {
+                    type: "string",
+                    minLength: 1,
+                    description: "可执行的处理建议。",
+                },
+                retryable: {
+                    type: "boolean",
+                    description: "使用相同输入稍后重试是否可能成功。",
+                },
+            },
+        },
+    },
+};
+export function getCreativeSchema() {
+    return {
+        schema_version: CREATIVE_SCHEMA_VERSION,
+        input_schema: CREATIVE_INPUT_SCHEMA,
+        output_schema: CREATIVE_OUTPUT_SCHEMA,
+    };
+}
+export const CREATIVE_EXAMPLES = {
+    examples: [
+        {
+            name: "text_creation",
+            description: "纯文本创作",
+            input: {
+                prompt: "为一款轻量缓震跑鞋写三条电商主图标题，语言简洁有力。",
+            },
+        },
+        {
+            name: "image_with_reference",
+            description: "使用参考图创作图片",
+            input: {
+                prompt: "以产品为主体生成一张户外晨跑场景广告图，保持鞋款外观和配色。",
+                media: [
+                    {
+                        source: "./product.png",
+                        role: "reference",
+                    },
+                ],
+                parameters: {
+                    ratio: "1:1",
+                    resolution: "2K",
+                },
+            },
+        },
+        {
+            name: "video_with_first_and_last_frames",
+            description: "使用首尾帧创作视频",
+            input: {
+                prompt: "生成从清晨城市街道过渡到终点冲线的运动广告视频，镜头运动自然。",
+                media: [
+                    {
+                        source: "./first-frame.png",
+                        role: "first_frame",
+                    },
+                    {
+                        source: "./last-frame.png",
+                        role: "last_frame",
+                    },
+                ],
+                parameters: {
+                    ratio: "16:9",
+                    resolution: "1080p",
+                    duration_seconds: 5,
+                },
+            },
+        },
+        {
+            name: "continue_creation",
+            description: "继续修改已有创作",
+            input: {
+                conversation_id: "conversation_123",
+                prompt: "保留主体和构图，把整体风格调整得更克制，并降低背景饱和度。",
+            },
+        },
+        {
+            name: "answer_questions",
+            description: "回答 GD Agent 的结构化追问",
+            input: {
+                conversation_id: "conversation_123",
+                last_tool_message_id: "message_456",
+                answers: [
+                    {
+                        question: "希望采用什么视觉风格？",
+                        values: ["极简"],
+                    },
+                    {
+                        question: "主要投放到哪些渠道？",
+                        values: ["电商详情页", "社交媒体"],
+                    },
+                ],
+            },
+        },
+    ],
+};
+export function getCreativeExamples() {
+    return CREATIVE_EXAMPLES;
+}
+const INPUT_KEYS = new Set([
+    "prompt",
+    "media",
+    "parameters",
+    "conversation_id",
+    "last_tool_message_id",
+    "answers",
+]);
+const PARAMETER_KEYS = new Set(["ratio", "resolution", "duration_seconds"]);
+const MEDIA_KEYS = new Set(["source", "role"]);
+const ANSWER_KEYS = new Set(["question", "values"]);
+const MEDIA_ROLES = new Set(["reference", "first_frame", "last_frame"]);
+const IMAGE_EXTENSIONS = new Set([
+    "avif",
+    "bmp",
+    "gif",
+    "heic",
+    "heif",
+    "jpeg",
+    "jpg",
+    "png",
+    "svg",
+    "webp",
+]);
+const VIDEO_EXTENSIONS = new Set(["avi", "m4v", "mkv", "mov", "mp4", "webm"]);
+const AUDIO_EXTENSIONS = new Set([
+    "aac",
+    "flac",
+    "m4a",
+    "mp3",
+    "oga",
+    "ogg",
+    "opus",
+    "wav",
+]);
+const KNOWN_NON_MEDIA_EXTENSIONS = new Set([
+    "csv",
+    "doc",
+    "docx",
+    "html",
+    "json",
+    "pdf",
+    "ppt",
+    "pptx",
+    "txt",
+    "xls",
+    "xlsx",
+    "xml",
+    "zip",
+]);
+export function validateCreativeInput(value) {
+    const input = requireRecord(value, "$", "Creative 输入必须是 JSON object");
+    rejectUnknownKeys(input, INPUT_KEYS, "$");
+    const hasPrompt = Object.hasOwn(input, "prompt");
+    const hasAnswers = Object.hasOwn(input, "answers");
+    const prompt = hasPrompt ? requireNonEmptyString(input.prompt, "prompt") : undefined;
+    const conversationId = Object.hasOwn(input, "conversation_id")
+        ? requireNonEmptyString(input.conversation_id, "conversation_id")
+        : undefined;
+    const lastToolMessageId = Object.hasOwn(input, "last_tool_message_id")
+        ? requireNonEmptyString(input.last_tool_message_id, "last_tool_message_id")
+        : undefined;
+    if (!hasPrompt && !hasAnswers) {
+        invalid("prompt", "普通创作必须提供非空 prompt；回答追问时可以改为提供 answers");
+    }
+    if (lastToolMessageId && !conversationId) {
+        invalid("last_tool_message_id", "last_tool_message_id 必须与 conversation_id 一起使用");
+    }
+    if (Object.hasOwn(input, "media"))
+        validateMedia(input.media);
+    if (Object.hasOwn(input, "parameters"))
+        validateParameters(input.parameters);
+    if (hasAnswers) {
+        validateAnswers(input.answers);
+        if (!conversationId || !lastToolMessageId) {
+            invalid("answers", "answers 必须同时携带 conversation_id 和 last_tool_message_id");
+        }
+    }
+    if (prompt === undefined && !hasAnswers) {
+        invalid("prompt", "prompt 不能为空");
+    }
+    return input;
+}
+function validateMedia(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        invalid("media", "media 必须是至少包含一项素材的数组");
+    }
+    let firstFrameCount = 0;
+    let lastFrameCount = 0;
+    value.forEach((item, index) => {
+        const path = `media[${index}]`;
+        const media = requireRecord(item, path, `${path} 必须是 object`);
+        rejectUnknownKeys(media, MEDIA_KEYS, path);
+        const source = requireNonEmptyString(media.source, `${path}.source`);
+        const role = requireNonEmptyString(media.role, `${path}.role`);
+        if (!MEDIA_ROLES.has(role)) {
+            invalid(`${path}.role`, "role 只支持 reference、first_frame 或 last_frame");
+        }
+        validateMediaSource(source, role, `${path}.source`);
+        if (role === "first_frame")
+            firstFrameCount += 1;
+        if (role === "last_frame")
+            lastFrameCount += 1;
+    });
+    if (firstFrameCount > 1) {
+        invalid("media", "first_frame 最多只能提供一份");
+    }
+    if (lastFrameCount > 1) {
+        invalid("media", "last_frame 最多只能提供一份");
+    }
+}
+function validateMediaSource(source, role, path) {
+    const isWindowsPath = /^[A-Za-z]:[\\/]/.test(source);
+    const scheme = !isWindowsPath ? source.match(/^([A-Za-z][A-Za-z\d+.-]*):/)?.[1] : undefined;
+    if (scheme && scheme !== "http" && scheme !== "https") {
+        invalid(path, "source 只支持本地文件路径或 HTTP(S) URL");
+    }
+    const remote = /^https?:\/\//i.test(source);
+    if (remote) {
+        try {
+            new URL(source);
+        }
+        catch {
+            invalid(path, "source 必须是合法的 HTTP(S) URL");
+        }
+    }
+    const extension = mediaExtension(source, remote);
+    const kind = mediaKind(extension);
+    if (role === "first_frame" || role === "last_frame") {
+        if (kind === "video" || kind === "audio" || kind === "unsupported") {
+            invalid(path, `${role} 只支持图片素材`);
+        }
+        if (!remote && kind !== "image") {
+            invalid(path, `${role} 的本地文件必须是支持的图片格式`);
+        }
+        return;
+    }
+    if (kind === "unsupported" || (!remote && kind === "unknown")) {
+        invalid(path, "reference 只支持图片、视频或音频素材");
+    }
+}
+function validateParameters(value) {
+    const parameters = requireRecord(value, "parameters", "parameters 必须是 object");
+    rejectUnknownKeys(parameters, PARAMETER_KEYS, "parameters");
+    if (Object.hasOwn(parameters, "ratio")) {
+        requireNonEmptyString(parameters.ratio, "parameters.ratio");
+    }
+    if (Object.hasOwn(parameters, "resolution")) {
+        requireNonEmptyString(parameters.resolution, "parameters.resolution");
+    }
+    if (Object.hasOwn(parameters, "duration_seconds")) {
+        const duration = parameters.duration_seconds;
+        if (typeof duration !== "number" || !Number.isInteger(duration) || duration < 1) {
+            invalid("parameters.duration_seconds", "duration_seconds 必须是大于等于 1 的整数");
+        }
+    }
+}
+function validateAnswers(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        invalid("answers", "answers 必须是至少包含一项回答的数组");
+    }
+    value.forEach((item, index) => {
+        const path = `answers[${index}]`;
+        const answer = requireRecord(item, path, `${path} 必须是 object`);
+        rejectUnknownKeys(answer, ANSWER_KEYS, path);
+        requireNonEmptyString(answer.question, `${path}.question`);
+        if (!Array.isArray(answer.values) || answer.values.length === 0) {
+            invalid(`${path}.values`, "values 必须至少包含一项非空回答");
+        }
+        answer.values.forEach((itemValue, valueIndex) => {
+            requireNonEmptyString(itemValue, `${path}.values[${valueIndex}]`);
+        });
+    });
+}
+function requireRecord(value, path, message) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        invalid(path, message);
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" || !value.trim()) {
+        invalid(path, `${path} 必须是非空字符串`);
+    }
+    return value;
+}
+function rejectUnknownKeys(value, allowed, path) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0) {
+        invalid(path, `不支持字段: ${unknown.join(", ")}`);
+    }
+}
+function mediaExtension(source, remote) {
+    let pathname = source;
+    if (remote) {
+        try {
+            pathname = new URL(source).pathname;
+        }
+        catch {
+            return "";
+        }
+    }
+    const filename = pathname.split(/[\\/]/).pop() ?? "";
+    const dot = filename.lastIndexOf(".");
+    return dot >= 0 ? filename.slice(dot + 1).toLowerCase() : "";
+}
+function mediaKind(extension) {
+    if (IMAGE_EXTENSIONS.has(extension))
+        return "image";
+    if (VIDEO_EXTENSIONS.has(extension))
+        return "video";
+    if (AUDIO_EXTENSIONS.has(extension))
+        return "audio";
+    if (KNOWN_NON_MEDIA_EXTENSIONS.has(extension))
+        return "unsupported";
+    return "unknown";
+}
+function invalid(path, message) {
+    throw new CliUsageError({
+        code: "PARAM_INVALID",
+        type: "validation",
+        message,
+        hint: "请运行 gd-cli creative schema --format json 查看完整输入结构。",
+        retryable: false,
+        detail: { path },
+    });
+}