knight-agent 1.1.0 → 1.1.2

package/utility/LLMUtility.d.ts

@@ -0,0 +1,1328 @@
+/** 大模型工具 */
+export declare namespace LLMUtility {
+    /**
+     * JSON数据格式规范(符合MCP InputSchema规范)
+     */
+    interface JSONSchema {
+        /** 数据类型 */
+        type: "object" | "string" | "number" | "boolean" | "array" | "null" | string;
+        /** 对象类型的属性定义,当type为"object"时使用,键为属性名,值为该属性的JSONSchema */
+        properties?: Record<string, JSONSchema>;
+        /** 必需属性列表,当type为"object"时使用,列出必须包含的属性名 */
+        required?: string[];
+        /** 字段描述 */
+        description?: string;
+        /** 枚举值限制 */
+        enum?: any[];
+        /** 数值最小值(包含),仅用于number类型 */
+        minimum?: number;
+        /** 数值最大值(包含),仅用于number类型 */
+        maximum?: number;
+        /** 正则表达式模式,用于约束字符串格式 */
+        pattern?: string;
+        /** 数组元素类型定义,当type为"array"时使用,描述数组中每个元素的Schema */
+        items?: JSONSchema;
+    }
+    /** 大模型配置 */
+    interface Config {
+        /** 类型 */
+        type: string | any;
+        /** 名称 */
+        name: string;
+        /** 描述 */
+        description: string;
+        /** 请求地址 */
+        url: string;
+        /** 模型名称 */
+        model: string;
+        /** API密钥 */
+        apiKey: string;
+        /** 请求超时(ms) */
+        timeout?: number;
+        /** 采样温度 (0~2)，Claude 4.7+ 弃用仅接受 1.0 */
+        temperature?: number;
+        /** 核采样 (0~1)，与 temperature 二选一或配合 */
+        topP?: number;
+        /** 最大输出 token 数 */
+        maxTokens?: number;
+        /** 停止序列 (最多 4 条) */
+        stop?: string | string[];
+        /** 流式响应开关 */
+        stream?: boolean;
+        /** 可复现采样种子 (Anthropic 不支持) */
+        seed?: number;
+        /** 最大消息缓存数量 */
+        maxMessageCache?: number;
+        /** 工具输出最大字符数，超出部分截断 (默认 800) */
+        maxToolOutput?: number;
+    }
+    /** 发送数据接口 */
+    interface SendData {
+        /** 提示词 */
+        prompt: string;
+        /** 技能 */
+        skill: string;
+        /** 工具列表 */
+        tools?: Array<LLMUtility.ToolDefinition>;
+        /** 用量回调 */
+        onUsage?: LLMUtility.UsageCallback;
+    }
+    /** 缓存消息基础接口 — 消息须有 role 以支持轮次修剪 */
+    interface MessageData {
+        /** 角色 */
+        role?: string;
+        /** 保持 */
+        preserve?: boolean;
+    }
+    /** 通用消息缓存 — 各平台通过泛型 T 指定消息类型 */
+    class Message<T extends MessageData> {
+        /** 消息缓存池 */
+        private readonly messages;
+        /** 最大保留轮次数(以 role==="user" 为轮次起点) */
+        private readonly maxTurns;
+        /** 构造函数 */
+        constructor(maxTurns?: number);
+        /** 消息数量 */
+        get count(): number;
+        /**
+         * 添加单条消息
+         * @param preserve trim 时是否保留此消息(系统消息设为 true)
+         */
+        Add(message: T): this;
+        /** 批量添加消息 */
+        AddRange(list: Array<T>): this;
+        /** 获取全部消息(返回副本) */
+        All(): Array<T>;
+        /** 获取最后一条消息 */
+        Last(): T | undefined;
+        /** 获取最后N条消息 */
+        LastN(n: number): Array<T>;
+        /** 移除最后一条消息 */
+        RemoveLast(): T | undefined;
+        /** 清空所有消息 */
+        Clear(): this;
+        /** 导出全部消息（返回副本，供快照使用） */
+        Export(): Array<T>;
+        /** 导入消息（替换当前缓存，供快照恢复使用） */
+        Import(messages: Array<T>): void;
+        /**
+         * 按轮次修剪缓存 — 保留最近 maxTurns 轮，preserve=true 的消息不被裁剪
+         * @returns 被移除的消息数量
+         */
+        Trim(): number;
+        /**
+         * 对每条消息应用转换函数(如工具输出截断/观察屏蔽)
+         * @param transform 转换函数，返回新消息替换旧消息，返回原引用则跳过
+         * @returns 被修改的消息数量
+         */
+        Compact(transform: (msg: T) => T): number;
+    }
+    /**
+     * 大模型工具定义
+     * 各平台 request() 中转换为原生格式
+     */
+    interface ToolDefinition {
+        /** 工具名称 */
+        name: string;
+        /** 工具描述 */
+        description?: string;
+        /** 输入参数 JSON Schema */
+        inputSchema: JSONSchema;
+        /** 调用处理函数(业务层封装，内部可调 MCP 或任何逻辑) */
+        handler: (args: Record<string, any>) => Promise<string>;
+    }
+    /**
+     * 大模型响应
+     * 各平台 LLM 负责将原始响应映射为此结构
+     */
+    interface Response {
+        /** 响应ID */
+        id: string;
+        /** 模型名称 */
+        model: string;
+        /** 文本内容 */
+        content: string;
+        /** 工具调用 */
+        toolCalls?: Array<ToolCall>;
+        /** 结束原因 */
+        finishReason: FinishReason;
+        /** Token 用量 */
+        usage: Usage;
+        /** 原始响应(调试用) */
+        raw: object;
+    }
+    /** 大模型工具调用 */
+    interface ToolCall {
+        /** 调用ID */
+        id: string;
+        /** 工具名 */
+        name: string;
+        /** 参数 */
+        arguments: Record<string, any>;
+    }
+    /** 统一工具结果 — 工具执行后返回 */
+    interface ToolResult {
+        /** 对应的工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 结果数据(已序列化) */
+        data: string;
+    }
+    /** 大模型结束原因 */
+    type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "unknown";
+    /** 大模型Token用量 */
+    interface Usage {
+        /** 输入 token */
+        input: number;
+        /** 输出 token */
+        output: number;
+        /** 总计 token */
+        total: number;
+    }
+    /** 用量回调 — send() 结束时触发，携带单次指令的聚合 token 用量 */
+    type UsageCallback = (usage: Usage) => void;
+    /** 大模型快照 — 序列化消息缓存与配置，供恢复使用 */
+    interface Snapshot {
+        /** 原始实例 ID */
+        id: string;
+        /** 平台配置(用于 LLMModule.restore 重建) */
+        config: Config;
+        /** 消息缓存快照 */
+        messages: MessageData[];
+        /** 导出时间戳 */
+        timeStemp: number;
+    }
+    /** Anthropic Claude接口 */
+    namespace Claude {
+        /**
+         * Anthropic Claude 平台配置
+         *   参考: https://platform.claude.com/docs/en/build-with-claude/working-with-messages
+         *   注意: Opus 4.7+ temperature/topP/topK 已弃用
+         */
+        interface Config extends LLMUtility.Config {
+            /** 类型 */
+            type: "Claude";
+            /** 扩展思考: enabled(含budget_tokens) / disabled / adaptive */
+            thinking?: {
+                type: "enabled" | "disabled" | "adaptive";
+                budgetTokens?: number;
+            };
+            /** 输出控制: effort 取 low ~ xhigh */
+            outputConfig?: {
+                effort?: "low" | "medium" | "high" | "xhigh" | "max";
+            };
+            /** 推理速度: fast 高吞吐 */
+            speed?: "standard" | "fast";
+            /** 用户标识(限流/防滥用) */
+            userId?: string;
+            /** 输出格式控制 (text / json_object)，通过 prefill 实现 */
+            responseFormat?: string;
+        }
+        /** 消息数据 */
+        interface MessageData extends LLMUtility.MessageData {
+            role: "user" | "assistant";
+            content: string | Array<ContentBlock>;
+        }
+        /** 内容块 */
+        type ContentBlock = TextBlock | ImageBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock;
+        /** 文本块 */
+        interface TextBlock {
+            type: "text";
+            text: string;
+        }
+        /** 图片块 */
+        interface ImageBlock {
+            type: "image";
+            source: {
+                type: "base64";
+                media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+                data: string;
+            };
+        }
+        /** 工具使用块(响应) */
+        interface ToolUseBlock {
+            type: "tool_use";
+            id: string;
+            name: string;
+            input: Record<string, unknown>;
+        }
+        /** 工具结果块(请求) */
+        interface ToolResultBlock {
+            type: "tool_result";
+            tool_use_id: string;
+            content: string;
+            is_error?: boolean;
+        }
+        /** 思考块(响应) */
+        interface ThinkingBlock {
+            type: "thinking";
+            thinking: string;
+            signature: string;
+        }
+        /** 思考配置 */
+        interface ThinkingConfig {
+            type: "enabled" | "disabled" | "adaptive";
+            budget_tokens?: number;
+        }
+        /** 工具定义 */
+        interface Tool {
+            name: string;
+            description?: string;
+            input_schema: {
+                type: "object";
+                properties?: Record<string, unknown>;
+                required?: Array<string>;
+            };
+        }
+        /** 工具选择 */
+        type ToolChoice = "auto" | "any" | "none" | {
+            type: "tool";
+            name: string;
+            disable_parallel_tool_use?: boolean;
+        };
+        /** Messages API请求结构 */
+        interface ChatRequest {
+            model: string;
+            messages: Array<MessageData>;
+            system?: string | Array<TextBlock>;
+            max_tokens: number;
+            temperature?: number;
+            top_p?: number;
+            top_k?: number;
+            stop_sequences?: Array<string>;
+            stream?: boolean;
+            thinking?: ThinkingConfig;
+            tools?: Array<Tool>;
+            tool_choice?: ToolChoice;
+            metadata?: {
+                user_id?: string;
+            };
+        }
+        /** Messages API响应结构 */
+        interface ChatResponse {
+            id: string;
+            type: "message";
+            role: "assistant";
+            model: string;
+            content: Array<ContentBlock>;
+            stop_reason: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | null;
+            stop_sequence: string | null;
+            usage: {
+                input_tokens: number;
+                output_tokens: number;
+                cache_creation_input_tokens?: number;
+                cache_read_input_tokens?: number;
+            };
+        }
+    }
+    /** DeepSeek接口 */
+    namespace DeepSeek {
+        /**
+         * DeepSeek 平台配置
+         *   参考: https://api-docs.deepseek.com/api/create-chat-completion
+         *   注意: thinking 模式下 temperature/topP/logprobs 不生效
+         */
+        interface Config extends LLMUtility.Config {
+            /** 类型 */
+            type: "DeepSeek";
+            /** 思考模式: enabled 开启 / disabled 关闭 (DeepSeek V4 核心特性) */
+            thinking?: {
+                type: "enabled" | "disabled";
+            };
+            /** 输出格式: text 或 JSON 模式 */
+            responseFormat?: "text" | "json_object";
+            /** 用户标识(安全审查) */
+            userId?: string;
+        }
+        /** 消息结构 */
+        interface MessageData extends LLMUtility.MessageData {
+            /**
+             * 消息角色
+             * 系统-system、助手-assistant、用户-user、工具-tool
+             */
+            role: "system" | "user" | "assistant" | "tool";
+            /** 消息内容 */
+            content: string;
+        }
+        /** 系统消息 */
+        interface SystemMessage extends MessageData {
+            role: "system";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+        }
+        /** 用户消息 */
+        interface UserMessage extends MessageData {
+            role: "user";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+        }
+        /** 助手消息 */
+        interface AssistantMessage extends MessageData {
+            role: "assistant";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+            /**
+             * (Beta)设置此参数为 true，来强制模型在其回答中以此 assistant 消息中提供的前缀内容开始
+             * 注意：必须设置 base_url="https://api.deepseek.com/beta" 来使用此功能
+             */
+            prefix?: boolean;
+            /** 模型的思考内容(thinking mode时返回) */
+            thinking?: string;
+            /** 推理内容(Beta DeepSeek扩展,当启用thinking模式时返回)用于思考模式下在对话前缀续写功能下，作为最后一条 assistant 思维链内容的输入。使用此功能时，prefix 参数必须设置为 true */
+            reasoning_content?: string;
+            /** 模型生成的 tool 调用 */
+            tool_calls?: Array<ToolResponse>;
+        }
+        /** 工具消息 */
+        interface ToolMessage extends MessageData {
+            role: "tool";
+            /** 此消息所响应的 tool call 的 ID */
+            tool_call_id: string;
+        }
+        /** 工具调用函数(请求时为工具定义无 id，响应时有 id) */
+        interface ToolCall {
+            /** 工具调用唯一标识(仅响应) */
+            id?: string;
+            /** 调用类型,固定为"function" */
+            type: "function";
+            /** 函数调用详情 */
+            function: {
+                /** 函数名称 */
+                name: string;
+                /** 函数描述 */
+                description?: string;
+                /** 函数参数 */
+                parameters: JSONSchema;
+                /** 如果设置为 true，API 将在函数调用中使用 strict 模式，以确保输出始终符合函数的 JSON schema 定义。该功能为 Beta 功能 */
+                strict?: boolean;
+            };
+        }
+        /** 工具响应 */
+        interface ToolResponse {
+            /** 索引 */
+            index: number;
+            /** tool 调用的 ID */
+            id: string;
+            /** tool 的类型 */
+            type: "function";
+            /** 模型调用的 function */
+            function: {
+                /** 模型调用的 function 名 */
+                name: string;
+                /** 要调用的 function 的参数，由模型生成，格式为 JSON。请注意，模型并不总是生成有效的 JSON，并且可能会臆造出你函数模式中未定义的参数。在调用函数之前，请在代码中验证这些参数 */
+                arguments: string;
+            };
+        }
+        /** OpenAI Chat API请求结构 */
+        interface ChatRequest {
+            /** 模型 */
+            model: string;
+            /** 消息 */
+            messages: Array<MessageData>;
+            /** 思考模式开关(默认思考开关为 enabled) */
+            thinking: {
+                type: "enabled" | "disabled";
+            };
+            /**
+             * 控制模型的推理强度
+             * - 对普通请求,默认为 high
+             * - 对一些复杂 Agent 类请求(如 Claude Code、OpenCode),自动设置为 max
+             * - 出于兼容考虑 low、medium 会映射为 high, xhigh 会映射为 max
+             */
+            reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** 惩罚频率(-2.0 和 2.0 之间的数字)
+             * - 如果该值为正,那么新 token 会根据其在已有文本中的出现频率受到相应的惩罚,降低模型重复相同内容的可能性
+             */
+            frequency_penalty?: number;
+            /** 限制一次请求中模型生成 completion 的最大 token 数。输入 token 和输出 token 的总长度受模型的上下文长度的限制 */
+            max_tokens?: number;
+            /** 实时惩罚(-2.0 和 2.0 之间的数字)
+             * - 如果该值为正,那么新 token 会根据其是否已在已有文本中出现受到相应的惩罚,从而增加模型谈论新主题的可能性。
+             */
+            presence_penalty?: number;
+            /** 指定模型必须输出的格式
+             * - 设置为 { "type": "json_object" } 以启用 JSON 模式,该模式保证模型生成的消息是有效的 JSON。
+             * - 注意: 使用 JSON 模式时,你还必须通过系统或用户消息指示模型生成 JSON。否则,模型可能会生成不断的空白字符,直到生成达到令牌限制,从而导致请求长时间运行并显得“卡住”。此外,如果 finish_reason="length",这表示生成超过了 max_tokens 或对话超过了最大上下文长度,消息内容可能会被部分截断。
+             */
+            response_format?: {
+                /** 类型(默认：text) */
+                type: "text" | "json_object";
+            };
+            /** 停止词
+             * - 在遇到这些词时,API将停止生成更多的token */
+            stop?: string | Array<string>;
+            /** 如果设置为 True,将会以 SSE(server-sent events)的形式以流式发送消息增量。消息流以 data: [DONE] 结尾。 */
+            stream?: boolean;
+            /** 流式输出相关选项(只有在stream参数为true时,才可设置此参数) */
+            stream_options?: {
+                /** 如果设置为 true，在流式消息最后的 data: [DONE] 之前将会传输一个额外的块。此块上的 usage 字段显示整个请求的 token 使用统计信息，而 choices 字段将始终是一个空数组。所有其他块也将包含一个 usage 字段，但其值为 null */
+                include_usage: boolean;
+            };
+            /** 采样温度(0 - 2之间,默认：1)
+             * - 更高的值，如 0.8，会使输出更随机，而更低的值，如 0.2，会使其更加集中和确定。 我们通常建议可以更改这个值或者更改 top_p，但不建议同时对两者进行修改。 */
+            temperature?: number;
+            /** 作为调节采样温度的替代方案，模型会考虑前 top_p 概率的 token 的结果(默认：1)
+             * - 所以 0.1 就意味着只有包括在最高 10% 概率中的 token 会被考虑。
+             * - 我们通常建议修改这个值或者更改 temperature，但不建议同时对两者进行修改 */
+            top_p?: number;
+            /** 模型可能会调用的 tool 的列表。
+             * - 目前，仅支持 function 作为工具。
+             * - 使用此参数来提供以 JSON 作为输入参数的 function 列表。最多支持 128 个 function */
+            tools?: Array<ToolCall>;
+            /** 控制模型调用 tool 的行为
+             * - none 意味着模型不会调用任何 tool，而是生成一条消息。
+             * - auto 意味着模型可以选择生成一条消息或调用一个或多个 tool。
+             * - required 意味着模型必须调用一个或多个 tool。
+             * - 通过 {"type": "function", "function": {"name": "my_function"}} 指定特定 tool，会强制模型调用该 tool。
+             * - 当没有 tool 时，默认值为 none。如果有 tool 存在，默认值为 auto。
+             */
+            tool_choice?: "none" | "auto" | "required" | {
+                /** 类型 */
+                type: "function" | string;
+                /** 要调用的函数 */
+                function: {
+                    /** 要调用的函数名称 */
+                    name: string;
+                };
+            };
+            /** 是否返回所输出 token 的对数概率。如果为 true，则在 message 的 content 中返回每个输出 token 的对数概率 */
+            logprobs?: boolean;
+            /** 一个介于 0 到 20 之间的整数 N，指定每个输出位置返回输出概率 top N 的 token，且返回这些 token 的对数概率。指定此参数时，logprobs 必须为 true */
+            top_logprobs?: number;
+            /** 采样种子(Anthropic 不支持) */
+            seed?: number;
+        }
+        /**
+         * OpenAI Chat API响应结构
+         * 参考: https://platform.openai.com/docs/api-reference/chat/object
+         */
+        interface ChatResponse extends ErrorReponse {
+            /** 唯一标识符(由服务端生成) */
+            id: string;
+            /** 对象类型,固定为 "chat.completion" */
+            object: "chat.completion";
+            /** 响应创建时的 Unix 时间戳(秒) */
+            created: number;
+            /** 使用的模型名称 */
+            model: string;
+            /** 系统指纹(用于识别服务端配置,调试用) */
+            system_fingerprint?: string;
+            /** 生成的回答选项列表(通常只有一个,但可配置n参数生成多个) */
+            choices: Array<Choice>;
+            /** Token 使用统计 */
+            usage: Usage;
+        }
+        /** 回答选项结构 */
+        interface Choice {
+            /** 选项索引(当n>1时用于区分不同回答) */
+            index: number;
+            /** 消息内容(助手回复的消息对象) */
+            message: AssistantMessage;
+            /** 日志概率信息(需要设置logprobs参数,默认null) */
+            logprobs: LogProbs | null;
+            /** 结束原因
+             * - stop：模型自然停止生成，或遇到 stop 序列中列出的字符串
+             * - length ：输出长度达到了模型上下文长度限制，或达到了 max_tokens 的限制
+             * - content_filter：输出内容因触发过滤策略而被过滤
+             * - insufficient_system_resource：系统推理资源不足，生成被打断
+             */
+            finish_reason: "stop" | "length" | "content_filter" | "tool_calls" | "insufficient_system_resource";
+        }
+        /** 日志概率结构 */
+        interface LogProbs {
+            /** 一个包含输出 token 对数概率信息的列表 */
+            content: Array<{
+                /** 输出的 token */
+                token: string;
+                /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                logprob: number;
+                /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                bytes: Array<number>;
+                /** 一个包含在该输出位置上，输出概率 top N 的 token 的列表，以及它们的对数概率。在罕见情况下，返回的 token 数量可能少于请求参数中指定的 top_logprobs 值 */
+                top_logprobs: Array<{
+                    /** 输出的 token */
+                    token: string;
+                    /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                    logprob: number;
+                    /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                    bytes: Array<number>;
+                }>;
+            }>;
+            /** 一个包含输出 token 对数概率信息的列表 */
+            reasoning_content: Array<{
+                /** 输出的 token */
+                token: string;
+                /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                logprob: number;
+                /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                bytes: Array<number>;
+                /** 一个包含在该输出位置上，输出概率 top N 的 token 的列表，以及它们的对数概率。在罕见情况下，返回的 token 数量可能少于请求参数中指定的 top_logprobs 值 */
+                top_logprobs: Array<{
+                    /** 输出的 token */
+                    token: string;
+                    /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                    logprob: number;
+                    /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                    bytes: Array<number>;
+                }>;
+            }>;
+        }
+        /** Token使用统计 */
+        interface Usage {
+            /** 模型 completion 产生的 token 数 */
+            completion_tokens: number;
+            /** 用户 prompt 所包含的 token 数。该值等于 prompt_cache_hit_tokens + prompt_cache_miss_tokens */
+            prompt_tokens: number;
+            /** 用户 prompt 中，命中上下文缓存的 token 数 */
+            prompt_cache_hit_tokens?: number;
+            /** 用户 prompt 中，未命中上下文缓存的 token 数 */
+            prompt_cache_miss_tokens?: number;
+            /** 该请求中，所有 token 的数量（prompt + completion） */
+            total_tokens: number;
+            /** 回答token详细信息(DeepSeek 扩展) */
+            completion_tokens_details?: {
+                /** 推理(思考)过程消耗的 token 数量 */
+                reasoning_tokens?: number;
+            };
+            /** 提示token详情(非标准但常见) */
+            prompt_tokens_details?: {
+                /** 命中缓存的 token 数量 */
+                cached_tokens?: number;
+            };
+        }
+        /** 错误响应 */
+        interface ErrorReponse {
+            /** 错误信息 */
+            error: {
+                /** 错误码 */
+                code: string;
+                /** 错误类型 */
+                type: string;
+                /** 错误消息 */
+                message: string;
+                /** 错误参数 */
+                param: string | null;
+            };
+        }
+    }
+    /** Google Gemini接口 */
+    namespace Gemini {
+        /**
+         * Google Gemini 平台配置
+         *   参考: https://ai.google.dev/api
+         *   注意: 参数在官方 SDK 中嵌套于 generation_config 内
+         */
+        interface Config extends LLMUtility.Config {
+            /** 类型 */
+            type: "Gemini";
+            /** Top-K 采样 (1~40)，OpenAI/DeepSeek 无此参数 */
+            topK?: number;
+            /** 候选数量 (1~8)，等同于 OpenAI n */
+            candidateCount?: number;
+            /** 输出格式: text 或 JSON 模式 */
+            responseFormat?: "text" | "json_object";
+            /** 思考预算 (Gemini 3) */
+            thinkingConfig?: {
+                includeThoughts?: boolean;
+                thinkingBudget?: number;
+            };
+            /** 安全过滤阈值 */
+            safetySettings?: Array<{
+                category: string;
+                threshold: string;
+            }>;
+            /** 输出模态 */
+            responseModalities?: Array<"TEXT" | "IMAGE">;
+        }
+        /** 消息数据 */
+        interface MessageData {
+            role?: "user" | "model";
+            parts: Array<Part>;
+        }
+        /** 消息数据零件 */
+        type Part = TextPart | InlineDataPart | FileDataPart | FunctionCallPart | FunctionResponsePart | ThoughtPart;
+        /** 文本零件 */
+        interface TextPart {
+            text: string;
+            thought?: boolean;
+        }
+        /** 内联数据零件 */
+        interface InlineDataPart {
+            inlineData: {
+                mimeType: string;
+                data: string;
+            };
+        }
+        /** 文件数据零件 */
+        interface FileDataPart {
+            fileData: {
+                mimeType: string;
+                fileUri: string;
+            };
+        }
+        /** 函数调用零件(响应) */
+        interface FunctionCallPart {
+            functionCall: {
+                name: string;
+                args: Record<string, unknown>;
+            };
+        }
+        /** 函数响应零件(请求) */
+        interface FunctionResponsePart {
+            functionResponse: {
+                name: string;
+                response: Record<string, unknown>;
+            };
+        }
+        /** 思考零件 */
+        interface ThoughtPart {
+            thought: boolean;
+            text?: undefined;
+        }
+        /** 生成配置 */
+        interface GenerationConfig {
+            temperature?: number;
+            topP?: number;
+            topK?: number;
+            candidateCount?: number;
+            maxOutputTokens?: number;
+            stopSequences?: Array<string>;
+            responseMimeType?: string;
+            responseSchema?: Record<string, unknown>;
+        }
+        /** 安全设置 */
+        interface SafetySetting {
+            category: string;
+            threshold: "BLOCK_NONE" | "BLOCK_ONLY_HIGH" | "BLOCK_MEDIUM_AND_ABOVE" | "BLOCK_LOW_AND_ABOVE" | string;
+        }
+        /** 工具定义 */
+        interface Tool {
+            functionDeclarations?: Array<FunctionDeclaration>;
+            codeExecution?: object;
+            googleSearch?: object;
+        }
+        /** 函数声明 */
+        interface FunctionDeclaration {
+            name: string;
+            description?: string;
+            parameters?: {
+                type: "object";
+                properties?: Record<string, unknown>;
+                required?: Array<string>;
+            };
+        }
+        /** 工具配置 */
+        interface ToolConfig {
+            functionCallingConfig?: {
+                mode: "AUTO" | "ANY" | "NONE";
+                allowedFunctionNames?: Array<string>;
+            };
+        }
+        /** generateContent API请求结构 */
+        interface ChatRequest {
+            contents: Array<MessageData>;
+            systemInstruction?: {
+                parts: Array<Part>;
+            };
+            generationConfig?: GenerationConfig;
+            safetySettings?: Array<SafetySetting>;
+            tools?: Array<Tool>;
+            toolConfig?: ToolConfig;
+        }
+        /** 候选 */
+        interface Candidate {
+            content: MessageData;
+            finishReason?: "STOP" | "MAX_TOKENS" | "SAFETY" | "RECITATION" | "OTHER";
+            safetyRatings?: Array<SafetyRating>;
+            tokenCount?: number;
+            index?: number;
+        }
+        /** 安全评级 */
+        interface SafetyRating {
+            category: string;
+            probability: "NEGLIGIBLE" | "LOW" | "MEDIUM" | "HIGH";
+            blocked?: boolean;
+        }
+        /** Token用量 */
+        interface UsageMetadata {
+            promptTokenCount: number;
+            candidatesTokenCount: number;
+            totalTokenCount: number;
+            cachedContentTokenCount?: number;
+        }
+        /** generateContent API响应结构 */
+        interface ChatResponse {
+            responseId?: string;
+            candidates: Array<Candidate>;
+            usageMetadata?: UsageMetadata;
+            modelVersion?: string;
+            promptFeedback?: {
+                blockReason?: string;
+                safetyRatings?: Array<SafetyRating>;
+            };
+        }
+    }
+    /** OpenAI接口 */
+    namespace OpenAI {
+        /**
+         * OpenAI 平台配置
+         *   参考: https://developers.openai.com/api/reference
+         */
+        interface Config extends LLMUtility.Config {
+            /** 类型 */
+            type: "OpenAI";
+            /** 推理强度 (o-series / gpt-5)，null 为禁用 */
+            reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** 结构化输出: json_schema 需配合 jsonSchema 字段 */
+            responseFormat?: "text" | "json_object" | "json_schema";
+            /** JSON Schema 定义(配合 responseFormat: "json_schema") */
+            jsonSchema?: {
+                name: string;
+                schema: Record<string, unknown>;
+                strict?: boolean;
+            };
+            /** 流式附带 usage 信息 */
+            streamOptions?: {
+                include_usage?: boolean;
+            };
+            /** 多模态输出 */
+            modalities?: Array<"text" | "audio">;
+            /** 存储 completion 供蒸馏/评估 */
+            store?: boolean;
+            /** 处理优先级 */
+            serviceTier?: "auto" | "default" | "flex" | "priority";
+            /** 安全审计标识(替代已弃用的 user) */
+            safetyIdentifier?: string;
+            /** 联网搜索(Beta) */
+            webSearchOptions?: {
+                searchContextSize?: "low" | "medium" | "high";
+                userLocation?: object;
+            };
+            /** 禁用并行工具调用 */
+            parallelToolCalls?: boolean;
+        }
+        /** 消息结构 */
+        interface MessageData extends LLMUtility.MessageData {
+            /**
+             * 消息角色
+             * 系统-system、助手-assistant、用户-user、工具-tool
+             */
+            role: "system" | "user" | "assistant" | "tool";
+            /** 消息内容 */
+            content: string | null;
+        }
+        /** 系统消息 */
+        interface SystemMessage extends MessageData {
+            role: "system";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+        }
+        /** 用户消息 */
+        interface UserMessage extends MessageData {
+            role: "user";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+        }
+        /** 助手消息 */
+        interface AssistantMessage extends MessageData {
+            role: "assistant";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+            /**
+             * (Beta)设置此参数为 true，来强制模型在其回答中以此 assistant 消息中提供的前缀内容开始
+             * 注意：必须设置 base_url="https://api.deepseek.com/beta" 来使用此功能
+             */
+            prefix?: boolean;
+            /** 模型的思考内容(thinking mode时返回) */
+            thinking?: string;
+            /** 推理内容(Beta DeepSeek扩展,当启用thinking模式时返回)用于思考模式下在对话前缀续写功能下，作为最后一条 assistant 思维链内容的输入。使用此功能时，prefix 参数必须设置为 true */
+            reasoning_content?: string;
+            /** 模型生成的 tool 调用 */
+            tool_calls?: Array<ToolResponse>;
+        }
+        /** 工具消息 */
+        interface ToolMessage extends MessageData {
+            role: "tool";
+            /** 此消息所响应的 tool call 的 ID */
+            tool_call_id: string;
+        }
+        /** 工具调用函数(请求时为工具定义无 id，响应时有 id) */
+        interface ToolCall {
+            /** 工具调用唯一标识(仅响应) */
+            id?: string;
+            /** 调用类型,固定为"function" */
+            type: "function";
+            /** 函数调用详情 */
+            function: {
+                /** 函数名称 */
+                name: string;
+                /** 函数描述 */
+                description?: string;
+                /** 函数参数 */
+                parameters: JSONSchema;
+                /** 如果设置为 true，API 将在函数调用中使用 strict 模式，以确保输出始终符合函数的 JSON schema 定义。该功能为 Beta 功能 */
+                strict?: boolean;
+            };
+        }
+        /** 工具响应 */
+        interface ToolResponse {
+            /** 索引 */
+            index: number;
+            /** tool 调用的 ID */
+            id: string;
+            /** tool 的类型 */
+            type: "function";
+            /** 模型调用的 function */
+            function: {
+                /** 模型调用的 function 名 */
+                name: string;
+                /** 要调用的 function 的参数，由模型生成，格式为 JSON。请注意，模型并不总是生成有效的 JSON，并且可能会臆造出你函数模式中未定义的参数。在调用函数之前，请在代码中验证这些参数 */
+                arguments: string;
+            };
+        }
+        /** OpenAI Chat API请求结构 */
+        interface ChatRequest {
+            /** 模型 */
+            model: string;
+            /** 消息 */
+            messages: Array<MessageData>;
+            /** 思考模式开关(默认思考开关为 enabled) */
+            thinking: {
+                type: "enabled" | "disabled";
+            };
+            /**
+             * 控制模型的推理强度
+             * - 对普通请求,默认为 high
+             * - 对一些复杂 Agent 类请求(如 Claude Code、OpenCode),自动设置为 max
+             * - 出于兼容考虑 low、medium 会映射为 high, xhigh 会映射为 max
+             */
+            reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+            /** 惩罚频率(-2.0 和 2.0 之间的数字)
+             * - 如果该值为正,那么新 token 会根据其在已有文本中的出现频率受到相应的惩罚,降低模型重复相同内容的可能性
+             */
+            frequency_penalty?: number;
+            /** 限制一次请求中模型生成 completion 的最大 token 数。输入 token 和输出 token 的总长度受模型的上下文长度的限制 */
+            max_tokens?: number;
+            /** 实时惩罚(-2.0 和 2.0 之间的数字)
+             * - 如果该值为正,那么新 token 会根据其是否已在已有文本中出现受到相应的惩罚,从而增加模型谈论新主题的可能性。
+             */
+            presence_penalty?: number;
+            /** 指定模型必须输出的格式
+             * - 设置为 { "type": "json_object" } 以启用 JSON 模式,该模式保证模型生成的消息是有效的 JSON。
+             * - 注意: 使用 JSON 模式时,你还必须通过系统或用户消息指示模型生成 JSON。否则,模型可能会生成不断的空白字符,直到生成达到令牌限制,从而导致请求长时间运行并显得“卡住”。此外,如果 finish_reason="length",这表示生成超过了 max_tokens 或对话超过了最大上下文长度,消息内容可能会被部分截断。
+             */
+            response_format?: {
+                /** 类型(默认：text) */
+                type: "text" | "json_object";
+            };
+            /** 停止词
+             * - 在遇到这些词时,API将停止生成更多的token */
+            stop?: string | Array<string>;
+            /** 如果设置为 True,将会以 SSE(server-sent events)的形式以流式发送消息增量。消息流以 data: [DONE] 结尾。 */
+            stream?: boolean;
+            /** 流式输出相关选项(只有在stream参数为true时,才可设置此参数) */
+            stream_options?: {
+                /** 如果设置为 true，在流式消息最后的 data: [DONE] 之前将会传输一个额外的块。此块上的 usage 字段显示整个请求的 token 使用统计信息，而 choices 字段将始终是一个空数组。所有其他块也将包含一个 usage 字段，但其值为 null */
+                include_usage: boolean;
+            };
+            /** 采样温度(0 - 2之间,默认：1)
+             * - 更高的值，如 0.8，会使输出更随机，而更低的值，如 0.2，会使其更加集中和确定。 我们通常建议可以更改这个值或者更改 top_p，但不建议同时对两者进行修改。 */
+            temperature?: number;
+            /** 作为调节采样温度的替代方案，模型会考虑前 top_p 概率的 token 的结果(默认：1)
+             * - 所以 0.1 就意味着只有包括在最高 10% 概率中的 token 会被考虑。
+             * - 我们通常建议修改这个值或者更改 temperature，但不建议同时对两者进行修改 */
+            top_p?: number;
+            /** 模型可能会调用的 tool 的列表。
+             * - 目前，仅支持 function 作为工具。
+             * - 使用此参数来提供以 JSON 作为输入参数的 function 列表。最多支持 128 个 function */
+            tools?: Array<ToolCall>;
+            /** 控制模型调用 tool 的行为
+             * - none 意味着模型不会调用任何 tool，而是生成一条消息。
+             * - auto 意味着模型可以选择生成一条消息或调用一个或多个 tool。
+             * - required 意味着模型必须调用一个或多个 tool。
+             * - 通过 {"type": "function", "function": {"name": "my_function"}} 指定特定 tool，会强制模型调用该 tool。
+             * - 当没有 tool 时，默认值为 none。如果有 tool 存在，默认值为 auto。
+             */
+            tool_choice?: "none" | "auto" | "required" | {
+                /** 类型 */
+                type: "function" | string;
+                /** 要调用的函数 */
+                function: {
+                    /** 要调用的函数名称 */
+                    name: string;
+                };
+            };
+            /** 是否返回所输出 token 的对数概率。如果为 true，则在 message 的 content 中返回每个输出 token 的对数概率 */
+            logprobs?: boolean;
+            /** 一个介于 0 到 20 之间的整数 N，指定每个输出位置返回输出概率 top N 的 token，且返回这些 token 的对数概率。指定此参数时，logprobs 必须为 true */
+            top_logprobs?: number;
+            /** 采样种子(Anthropic 不支持) */
+            seed?: number;
+        }
+        /**
+         * OpenAI Chat API响应结构
+         * 参考: https://platform.openai.com/docs/api-reference/chat/object
+         */
+        interface ChatResponse extends ErrorReponse {
+            /** 唯一标识符(由服务端生成) */
+            id: string;
+            /** 对象类型,固定为 "chat.completion" */
+            object: "chat.completion";
+            /** 响应创建时的 Unix 时间戳(秒) */
+            created: number;
+            /** 使用的模型名称 */
+            model: string;
+            /** 系统指纹(用于识别服务端配置,调试用) */
+            system_fingerprint?: string;
+            /** 生成的回答选项列表(通常只有一个,但可配置n参数生成多个) */
+            choices: Array<Choice>;
+            /** Token 使用统计 */
+            usage: Usage;
+        }
+        /** 回答选项结构 */
+        interface Choice {
+            /** 选项索引(当n>1时用于区分不同回答) */
+            index: number;
+            /** 消息内容(助手回复的消息对象) */
+            message: AssistantMessage;
+            /** 日志概率信息(需要设置logprobs参数,默认null) */
+            logprobs: LogProbs | null;
+            /** 结束原因
+             * - stop：模型自然停止生成，或遇到 stop 序列中列出的字符串
+             * - length ：输出长度达到了模型上下文长度限制，或达到了 max_tokens 的限制
+             * - content_filter：输出内容因触发过滤策略而被过滤
+             * - insufficient_system_resource：系统推理资源不足，生成被打断
+             */
+            finish_reason: "stop" | "length" | "content_filter" | "tool_calls" | "insufficient_system_resource";
+        }
+        /** 日志概率结构 */
+        interface LogProbs {
+            /** 一个包含输出 token 对数概率信息的列表 */
+            content: Array<{
+                /** 输出的 token */
+                token: string;
+                /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                logprob: number;
+                /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                bytes: Array<number>;
+                /** 一个包含在该输出位置上，输出概率 top N 的 token 的列表，以及它们的对数概率。在罕见情况下，返回的 token 数量可能少于请求参数中指定的 top_logprobs 值 */
+                top_logprobs: Array<{
+                    /** 输出的 token */
+                    token: string;
+                    /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                    logprob: number;
+                    /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                    bytes: Array<number>;
+                }>;
+            }>;
+            /** 一个包含输出 token 对数概率信息的列表 */
+            reasoning_content: Array<{
+                /** 输出的 token */
+                token: string;
+                /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                logprob: number;
+                /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                bytes: Array<number>;
+                /** 一个包含在该输出位置上，输出概率 top N 的 token 的列表，以及它们的对数概率。在罕见情况下，返回的 token 数量可能少于请求参数中指定的 top_logprobs 值 */
+                top_logprobs: Array<{
+                    /** 输出的 token */
+                    token: string;
+                    /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                    logprob: number;
+                    /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                    bytes: Array<number>;
+                }>;
+            }>;
+        }
+        /** Token使用统计 */
+        interface Usage {
+            /** 模型 completion 产生的 token 数 */
+            completion_tokens: number;
+            /** 用户 prompt 所包含的 token 数。该值等于 prompt_cache_hit_tokens + prompt_cache_miss_tokens */
+            prompt_tokens: number;
+            /** 用户 prompt 中，命中上下文缓存的 token 数 */
+            prompt_cache_hit_tokens?: number;
+            /** 用户 prompt 中，未命中上下文缓存的 token 数 */
+            prompt_cache_miss_tokens?: number;
+            /** 该请求中，所有 token 的数量（prompt + completion） */
+            total_tokens: number;
+            /** 回答token详细信息(DeepSeek 扩展) */
+            completion_tokens_details?: {
+                /** 推理(思考)过程消耗的 token 数量 */
+                reasoning_tokens?: number;
+            };
+            /** 提示token详情(非标准但常见) */
+            prompt_tokens_details?: {
+                /** 命中缓存的 token 数量 */
+                cached_tokens?: number;
+            };
+        }
+        /** 错误响应 */
+        interface ErrorReponse {
+            /** 错误信息 */
+            error: {
+                /** 错误码 */
+                code: string;
+                /** 错误类型 */
+                type: string;
+                /** 错误消息 */
+                message: string;
+                /** 错误参数 */
+                param: string | null;
+            };
+        }
+    }
+    /** 通义千问接口 */
+    namespace QWen {
+        /**
+         * 通义千问 (DashScope) 平台配置
+         *   参考: https://help.aliyun.com/zh/model-studio/getting-started/models
+         *   注意: Qwen API 与 OpenAI 兼容，使用相同的消息格式
+         */
+        interface Config extends LLMUtility.Config {
+            /** 类型 */
+            type: "QWen";
+            /** 联网搜索 (仅 qwen-max/qwen-plus 等支持) */
+            enableSearch?: boolean;
+            /** 高分辨率图像 (视觉模型) */
+            vlHighResolutionImages?: boolean;
+            /** 重复惩罚 (0~5)，减少模型重复输出的倾向 */
+            repetitionPenalty?: number;
+            /** 思考模式: enabled 开启 / disabled 关闭 (Qwen3 系列) */
+            thinking?: {
+                type: "enabled" | "disabled";
+            };
+            /** 输出格式: text 或 JSON 模式 */
+            responseFormat?: "text" | "json_object";
+        }
+        /** 消息结构 */
+        interface MessageData extends LLMUtility.MessageData {
+            /**
+             * 消息角色
+             * 系统-system、助手-assistant、用户-user、工具-tool
+             */
+            role: "system" | "user" | "assistant" | "tool";
+            /** 消息内容 */
+            content: string;
+        }
+        /** 系统消息 */
+        interface SystemMessage extends MessageData {
+            role: "system";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+        }
+        /** 用户消息 */
+        interface UserMessage extends MessageData {
+            role: "user";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+        }
+        /** 助手消息 */
+        interface AssistantMessage extends MessageData {
+            role: "assistant";
+            /** (选填)参与者的名称，为模型提供信息以区分相同角色的参与者 */
+            name?: string;
+            /**
+             * (Beta)设置此参数为 true，来强制模型在其回答中以此 assistant 消息中提供的前缀内容开始
+             * 注意：必须设置 base_url="https://api.deepseek.com/beta" 来使用此功能
+             */
+            prefix?: boolean;
+            /** 模型的思考内容(thinking mode时返回) */
+            thinking?: string;
+            /** 推理内容(Beta DeepSeek扩展,当启用thinking模式时返回)用于思考模式下在对话前缀续写功能下，作为最后一条 assistant 思维链内容的输入。使用此功能时，prefix 参数必须设置为 true */
+            reasoning_content?: string;
+            /** 模型生成的 tool 调用 */
+            tool_calls?: Array<ToolResponse>;
+        }
+        /** 工具消息 */
+        interface ToolMessage extends MessageData {
+            role: "tool";
+            /** 此消息所响应的 tool call 的 ID */
+            tool_call_id: string;
+        }
+        /** 工具调用函数(请求时为工具定义无 id，响应时有 id) */
+        interface ToolCall {
+            /** 工具调用唯一标识(仅响应) */
+            id?: string;
+            /** 调用类型,固定为"function" */
+            type: "function";
+            /** 函数调用详情 */
+            function: {
+                /** 函数名称 */
+                name: string;
+                /** 函数描述 */
+                description?: string;
+                /** 函数参数 */
+                parameters: JSONSchema;
+                /** 如果设置为 true，API 将在函数调用中使用 strict 模式，以确保输出始终符合函数的 JSON schema 定义。该功能为 Beta 功能 */
+                strict?: boolean;
+            };
+        }
+        /** 工具响应 */
+        interface ToolResponse {
+            /** 索引 */
+            index: number;
+            /** tool 调用的 ID */
+            id: string;
+            /** tool 的类型 */
+            type: "function";
+            /** 模型调用的 function */
+            function: {
+                /** 模型调用的 function 名 */
+                name: string;
+                /** 要调用的 function 的参数，由模型生成，格式为 JSON。请注意，模型并不总是生成有效的 JSON，并且可能会臆造出你函数模式中未定义的参数。在调用函数之前，请在代码中验证这些参数 */
+                arguments: string;
+            };
+        }
+        /** OpenAI Chat API请求结构 */
+        interface ChatRequest {
+            model: string;
+            messages: Array<MessageData>;
+            thinking?: {
+                type: "enabled" | "disabled";
+            };
+            enable_search?: boolean;
+            search_options?: {
+                enable_search_by_google?: boolean;
+                enable_search_by_quark?: boolean;
+            };
+            vl_high_resolution_images?: boolean;
+            repetition_penalty?: number;
+            response_format?: {
+                type: "text" | "json_object";
+            };
+            temperature?: number;
+            top_p?: number;
+            max_tokens?: number;
+            stop?: string | Array<string>;
+            stream?: boolean;
+            stream_options?: {
+                include_usage: boolean;
+            };
+            frequency_penalty?: number;
+            presence_penalty?: number;
+            tools?: Array<OpenAI.ToolCall>;
+            tool_choice?: "none" | "auto" | "required" | {
+                type: "function";
+                function: {
+                    name: string;
+                };
+            };
+            seed?: number;
+        }
+        /**
+         * OpenAI Chat API响应结构
+         * 参考: https://platform.openai.com/docs/api-reference/chat/object
+         */
+        interface ChatResponse extends ErrorReponse {
+            /** 唯一标识符(由服务端生成) */
+            id: string;
+            /** 对象类型,固定为 "chat.completion" */
+            object: "chat.completion";
+            /** 响应创建时的 Unix 时间戳(秒) */
+            created: number;
+            /** 使用的模型名称 */
+            model: string;
+            /** 系统指纹(用于识别服务端配置,调试用) */
+            system_fingerprint?: string;
+            /** 生成的回答选项列表(通常只有一个,但可配置n参数生成多个) */
+            choices: Array<Choice>;
+            /** Token 使用统计 */
+            usage: Usage;
+        }
+        /** 回答选项结构 */
+        interface Choice {
+            /** 选项索引(当n>1时用于区分不同回答) */
+            index: number;
+            /** 消息内容(助手回复的消息对象) */
+            message: AssistantMessage;
+            /** 日志概率信息(需要设置logprobs参数,默认null) */
+            logprobs: LogProbs | null;
+            /** 结束原因
+             * - stop：模型自然停止生成，或遇到 stop 序列中列出的字符串
+             * - length ：输出长度达到了模型上下文长度限制，或达到了 max_tokens 的限制
+             * - content_filter：输出内容因触发过滤策略而被过滤
+             * - insufficient_system_resource：系统推理资源不足，生成被打断
+             */
+            finish_reason: "stop" | "length" | "content_filter" | "tool_calls" | "insufficient_system_resource";
+        }
+        /** 日志概率结构 */
+        interface LogProbs {
+            /** 一个包含输出 token 对数概率信息的列表 */
+            content: Array<{
+                /** 输出的 token */
+                token: string;
+                /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                logprob: number;
+                /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                bytes: Array<number>;
+                /** 一个包含在该输出位置上，输出概率 top N 的 token 的列表，以及它们的对数概率。在罕见情况下，返回的 token 数量可能少于请求参数中指定的 top_logprobs 值 */
+                top_logprobs: Array<{
+                    /** 输出的 token */
+                    token: string;
+                    /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                    logprob: number;
+                    /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                    bytes: Array<number>;
+                }>;
+            }>;
+            /** 一个包含输出 token 对数概率信息的列表 */
+            reasoning_content: Array<{
+                /** 输出的 token */
+                token: string;
+                /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                logprob: number;
+                /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                bytes: Array<number>;
+                /** 一个包含在该输出位置上，输出概率 top N 的 token 的列表，以及它们的对数概率。在罕见情况下，返回的 token 数量可能少于请求参数中指定的 top_logprobs 值 */
+                top_logprobs: Array<{
+                    /** 输出的 token */
+                    token: string;
+                    /** 该 token 的对数概率。-9999.0 代表该 token 的输出概率极小，不在 top 20 最可能输出的 token 中 */
+                    logprob: number;
+                    /** 一个包含该 token UTF-8 字节表示的整数列表。一般在一个 UTF-8 字符被拆分成多个 token 来表示时有用。如果 token 没有对应的字节表示，则该值为 null */
+                    bytes: Array<number>;
+                }>;
+            }>;
+        }
+        /** Token使用统计 */
+        interface Usage {
+            /** 模型 completion 产生的 token 数 */
+            completion_tokens: number;
+            /** 用户 prompt 所包含的 token 数。该值等于 prompt_cache_hit_tokens + prompt_cache_miss_tokens */
+            prompt_tokens: number;
+            /** 用户 prompt 中，命中上下文缓存的 token 数 */
+            prompt_cache_hit_tokens?: number;
+            /** 用户 prompt 中，未命中上下文缓存的 token 数 */
+            prompt_cache_miss_tokens?: number;
+            /** 该请求中，所有 token 的数量（prompt + completion） */
+            total_tokens: number;
+            /** 回答token详细信息(DeepSeek 扩展) */
+            completion_tokens_details?: {
+                /** 推理(思考)过程消耗的 token 数量 */
+                reasoning_tokens?: number;
+            };
+            /** 提示token详情(非标准但常见) */
+            prompt_tokens_details?: {
+                /** 命中缓存的 token 数量 */
+                cached_tokens?: number;
+            };
+        }
+        /** 错误响应 */
+        interface ErrorReponse {
+            /** 错误信息 */
+            error: {
+                /** 错误码 */
+                code: string;
+                /** 错误类型 */
+                type: string;
+                /** 错误消息 */
+                message: string;
+                /** 错误参数 */
+                param: string | null;
+            };
+        }
+    }
+}
+//# sourceMappingURL=LLMUtility.d.ts.map