@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/apis/google-generative-ai.js

@@ -0,0 +1,249 @@
+/**
+ * google-generative-ai 协议（设计 §3.1）：POST `{baseUrl}/models/{id}:streamGenerateContent?alt=sse`，
+ * 每个 `data:` 是一个完整的 GenerateContentResponse（没有 `[DONE]`）。
+ *
+ * - `candidates[0].content.parts`：`text`（`thought: true` 为思考）→ 文本 / 思考块，相邻同类 part
+ *   并入同一块；`functionCall` 整块到达 → toolcall_start / delta（整段 JSON）/ end；
+ * - `thoughtSignature` 可挂在任何 part 上：思考 → `thinkingSignature`，文本 → `textSignature`，
+ *   工具调用 → `thoughtSignature`；同一块后到的空签名不覆盖先到的（签名常在末尾的空文本 part 上）；
+ * - 工具调用缺 id（Gemini 2.5 起常见）时按 responseId + 内容下标生成确定的 id；
+ * - `finishReason`：STOP → stop（有工具调用则 toolUse）、MAX_TOKENS → length，其余（SAFETY、
+ *   RECITATION、MALFORMED_FUNCTION_CALL…）→ error；`promptFeedback.blockReason` → error；
+ *   流里没出现过 finishReason → 断流错误；
+ * - `usageMetadata`（每块累计，取最后一次）：input = promptTokenCount − cachedContentTokenCount，
+ *   output = candidatesTokenCount + thoughtsTokenCount（思考按输出计费），reasoning = thoughts；
+ *   cachedContentTokenCount 出现（含 0）即 `cacheReported: true`（隐式缓存未命中时常常不给该字段）；
+ * - 错误体 `{error:{code,status,message}}` 重排为 `429 RESOURCE_EXHAUSTED: …`。
+ */
+import { AssistantEventStreamImpl } from "../event-stream.js";
+import { HttpError, USER_AGENT, authHeaders, joinUrl, mergeHeaders, postJson } from "../http.js";
+import { readSseEvents } from "../sse.js";
+import { GOOGLE_BASE_URL, buildGoogleRequest, detectGoogleCompat } from "./google-request.js";
+import { BlockTracker, ProviderStopError, STREAM_ENDED_MESSAGE, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function obj(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function parseGoogleUsage(raw) {
+    const prompt = num(raw["promptTokenCount"]) ?? 0;
+    const reported = num(raw["cachedContentTokenCount"]);
+    const cached = reported ?? 0;
+    const thoughts = num(raw["thoughtsTokenCount"]) ?? 0;
+    const usage = {
+        input: Math.max(0, prompt - cached),
+        output: (num(raw["candidatesTokenCount"]) ?? 0) + thoughts,
+        cacheRead: cached,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cacheReported: reported !== undefined,
+    };
+    if (raw["thoughtsTokenCount"] !== undefined)
+        usage.reasoning = thoughts;
+    return usage;
+}
+export function mapGoogleFinishReason(raw) {
+    if (raw === "STOP")
+        return { reason: "stop" };
+    if (raw === "MAX_TOKENS")
+        return { reason: "length" };
+    return { reason: "error", message: `Provider finish reason: ${raw}` };
+}
+/** Google 错误体 `{error:{code,status,message}}` → `status: message`；其它形状返回 undefined。 */
+export function describeGoogleError(value) {
+    const error = obj(obj(value)?.["error"]);
+    if (!error)
+        return undefined;
+    const message = str(error["message"]) ?? JSON.stringify(error);
+    const status = str(error["status"]);
+    return status && !message.startsWith(status) ? `${status}: ${message}` : message;
+}
+function rewriteHttpError(error) {
+    if (!(error instanceof HttpError))
+        return error;
+    let detail;
+    try {
+        detail = describeGoogleError(JSON.parse(error.body));
+    }
+    catch {
+        detail = undefined;
+    }
+    if (!detail)
+        return error;
+    return new HttpError(error.status, `${error.status} ${detail}`, error.body, error.retryAfterMs);
+}
+function closeProse(state, tracker) {
+    if (state.prose)
+        tracker.end(state.prose.index);
+    state.prose = undefined;
+}
+function setSignature(tracker, index, signature) {
+    const block = tracker.output.content[index];
+    if (block?.type === "thinking")
+        block.thinkingSignature = signature;
+    else if (block?.type === "text")
+        block.textSignature = signature;
+}
+function toolCallId(state, tracker, provided) {
+    const taken = (id) => tracker.output.content.some((b) => b.type === "toolCall" && b.id === id);
+    if (provided && !taken(provided))
+        return provided;
+    const seed = state.idSeed.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40) || "gemini";
+    let id = `call_${seed}_${tracker.output.content.length}`;
+    for (let n = 1; taken(id); n++)
+        id = `call_${seed}_${tracker.output.content.length}_${n}`;
+    return id;
+}
+function handlePart(part, state, tracker) {
+    const signature = str(part["thoughtSignature"]) || undefined;
+    const call = obj(part["functionCall"]);
+    if (call) {
+        closeProse(state, tracker);
+        const name = str(call["name"]) ?? "";
+        const index = tracker.startToolCall(toolCallId(state, tracker, str(call["id"])), name);
+        const block = tracker.toolCallBlock(index);
+        if (block && signature)
+            block.thoughtSignature = signature;
+        tracker.appendToolArgs(index, JSON.stringify(obj(call["args"]) ?? {}));
+        tracker.end(index);
+        return;
+    }
+    const text = str(part["text"]);
+    if (text === undefined)
+        return;
+    const kind = part["thought"] === true ? "thinking" : "text";
+    if (state.prose?.kind !== kind) {
+        closeProse(state, tracker);
+        // 空 part 不单独开块；只带签名的挂到前一个同类块上
+        if (text.length === 0) {
+            const last = tracker.output.content.length - 1;
+            if (signature && tracker.output.content[last]?.type === kind) {
+                setSignature(tracker, last, signature);
+            }
+            return;
+        }
+        const index = kind === "thinking" ? tracker.startThinking() : tracker.startText();
+        state.prose = { index, kind };
+    }
+    const index = state.prose.index;
+    if (kind === "thinking")
+        tracker.appendThinking(index, text);
+    else
+        tracker.appendText(index, text);
+    if (signature)
+        setSignature(tracker, index, signature);
+}
+function handleChunk(chunk, state, tracker) {
+    if (chunk["error"] !== undefined) {
+        throw new Error(describeGoogleError(chunk) ?? JSON.stringify(chunk["error"]));
+    }
+    const output = tracker.output;
+    const responseId = str(chunk["responseId"]);
+    if (responseId && !output.responseId) {
+        output.responseId = responseId;
+        state.idSeed = responseId;
+    }
+    const usage = obj(chunk["usageMetadata"]);
+    if (usage)
+        output.usage = parseGoogleUsage(usage);
+    const blocked = str(obj(chunk["promptFeedback"])?.["blockReason"]);
+    const candidates = Array.isArray(chunk["candidates"]) ? chunk["candidates"] : [];
+    const candidate = obj(candidates[0]);
+    if (!candidate && blocked) {
+        output.rawStopReason = blocked;
+        throw new ProviderStopError(`Prompt blocked: ${blocked}`);
+    }
+    const parts = obj(candidate?.["content"])?.["parts"];
+    if (Array.isArray(parts)) {
+        for (const part of parts) {
+            const value = obj(part);
+            if (value)
+                handlePart(value, state, tracker);
+        }
+    }
+    const finish = str(candidate?.["finishReason"]);
+    if (finish) {
+        state.finish = finish;
+        output.rawStopReason = finish;
+    }
+}
+function buildHeaders(model, options) {
+    return mergeHeaders({ "content-type": "application/json", accept: "text/event-stream", "user-agent": USER_AGENT }, authHeaders(options.apiKey, model.authHeader, "x-goog-api-key"), model.headers, options.headers);
+}
+export function googleStreamUrl(model) {
+    const id = model.id.replace(/^models\//, "");
+    return joinUrl(model.baseUrl ?? GOOGLE_BASE_URL, `/models/${encodeURIComponent(id)}:streamGenerateContent?alt=sse`);
+}
+async function run(stream, model, context, options) {
+    const tracker = new BlockTracker(stream, createOutput(model));
+    try {
+        const request = buildGoogleRequest(model, context, options);
+        tracker.output.thinkingLevel = request.thinkingLevel;
+        if (request.providerThinkingLevel !== undefined) {
+            tracker.output.providerThinkingLevel = request.providerThinkingLevel;
+        }
+        const replaced = options.onPayload?.(request.body);
+        let response;
+        try {
+            response = await postJson(googleStreamUrl(model), {
+                headers: buildHeaders(model, options),
+                body: replaced === undefined ? request.body : replaced,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs,
+                onResponse: options.onResponse,
+            });
+        }
+        catch (error) {
+            throw rewriteHttpError(error);
+        }
+        stream.push({ type: "start", partial: tracker.output });
+        const state = {
+            prose: undefined,
+            finish: undefined,
+            idSeed: Date.now().toString(36),
+        };
+        const body = response.body;
+        for await (const sse of readSseEvents(body, options.signal)) {
+            const data = sse.data.trim();
+            if (data === "" || data === "[DONE]")
+                continue;
+            let chunk;
+            try {
+                chunk = obj(JSON.parse(data)) ?? {};
+            }
+            catch {
+                throw new Error(`Malformed SSE data: ${data.slice(0, 200)}`);
+            }
+            handleChunk(chunk, state, tracker);
+        }
+        if (options.signal.aborted)
+            throw new Error("aborted");
+        if (state.finish === undefined)
+            throw new Error(STREAM_ENDED_MESSAGE);
+        const mapped = mapGoogleFinishReason(state.finish);
+        if (mapped.reason === "error")
+            throw new ProviderStopError(mapped.message);
+        const reason = mapped.reason === "stop" && tracker.hasToolCalls ? "toolUse" : mapped.reason;
+        finishDone(stream, tracker, model, reason);
+    }
+    catch (error) {
+        finishError(stream, tracker, model, error, options.signal);
+    }
+}
+function stream(model, context, options) {
+    requireApiKey(model, options);
+    const events = new AssistantEventStreamImpl();
+    void run(events, model, context, options).finally(() => events.end());
+    return events;
+}
+export const googleGenerativeAiApi = {
+    id: "google-generative-ai",
+    stream,
+    detectCompat: detectGoogleCompat,
+};

package/dist/ai/apis/google-request.d.ts

@@ -0,0 +1,40 @@
+/**
+ * google-generative-ai 请求体（设计 §3.1、§3.3、§3.6）：contents 转换、thoughtSignature 回放、
+ * 工具声明、thinkingConfig。
+ *
+ * - 角色：user / model；工具结果是 user 回合里的 `functionResponse` part，连续多条合进同一回合；
+ * - thoughtSignature：只回放同 provider / 同模型、且是合法 base64 的签名（Gemini 要求 bytes）；
+ *   签名可能挂在空文本 part 上，此时空 part 也要原样送回；跨模型的思考由 transform.ts 降级为文本；
+ * - Gemini 3 起 functionCall / functionResponse 带 `id`，并支持把工具结果图片放进
+ *   `functionResponse.parts`（`supportsFunctionResponseParts`）；更早的模型图片另起一个 user 回合；
+ * - thinkingConfig：级别映射到字串（或模型属于 Gemini 3 族且映射缺省）→ 离散 `thinkingLevel`；
+ *   映射到数字或其它模型 → `thinkingBudget`（不超过回答上限留白）；off → `thinkingBudget: 0`；
+ * - 缓存：Gemini 的隐式缓存自动生效，请求里没有可设的字段；`cacheRetention` 不影响请求体；
+ * - `toolChoice: "none"`（有工具时）→ `toolConfig.functionCallingConfig.mode: "NONE"`。
+ */
+import type { AssistantMessage, GoogleCompat, JsonSchema, Model, ModelThinkingLevel, ProviderData, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
+type Json = Record<string, unknown>;
+type Conversation = UserMessage | AssistantMessage | ToolResultMessage;
+export declare const GOOGLE_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
+/** `gemini-3.1-pro-preview` → 3；不是 Gemini 版本号命名返回 undefined。 */
+export declare function geminiMajorVersion(modelId: string): number | undefined;
+/** Gemini 3 起 functionCall / functionResponse 要带 id。 */
+export declare function requiresToolCallId(modelId: string): boolean;
+/** 缺省按模型族推断离散级别：Gemini 3 Pro / Flash 及 `gemini-flash(-lite)-latest`。 */
+export declare function usesDiscreteThinkingLevel(modelId: string): boolean;
+/**
+ * compat：推断 ← provider.compat ← model.compat。原生协议的实现都认 thoughtSignature，缺省开；
+ * 工具结果内嵌图片只有 Gemini 3 起支持，非 Gemini 命名的模型保守关。
+ */
+export declare function detectGoogleCompat(model: Model, provider?: ProviderData): GoogleCompat;
+export declare function convertGoogleContents(model: Model, messages: readonly Conversation[], compat: GoogleCompat): Json[];
+/** Gemini 的 schema 是 OpenAPI 子集：去掉它不认的 `additionalProperties`。 */
+export declare function toGoogleSchema(schema: JsonSchema): Json;
+export interface GoogleRequest {
+    body: Json;
+    compat: GoogleCompat;
+    thinkingLevel: ModelThinkingLevel;
+    providerThinkingLevel: string | undefined;
+}
+export declare function buildGoogleRequest(model: Model, context: TranscriptContext, options: StreamOptions): GoogleRequest;
+export {};

package/dist/ai/apis/google-request.js

@@ -0,0 +1,255 @@
+/**
+ * google-generative-ai 请求体（设计 §3.1、§3.3、§3.6）：contents 转换、thoughtSignature 回放、
+ * 工具声明、thinkingConfig。
+ *
+ * - 角色：user / model；工具结果是 user 回合里的 `functionResponse` part，连续多条合进同一回合；
+ * - thoughtSignature：只回放同 provider / 同模型、且是合法 base64 的签名（Gemini 要求 bytes）；
+ *   签名可能挂在空文本 part 上，此时空 part 也要原样送回；跨模型的思考由 transform.ts 降级为文本；
+ * - Gemini 3 起 functionCall / functionResponse 带 `id`，并支持把工具结果图片放进
+ *   `functionResponse.parts`（`supportsFunctionResponseParts`）；更早的模型图片另起一个 user 回合；
+ * - thinkingConfig：级别映射到字串（或模型属于 Gemini 3 族且映射缺省）→ 离散 `thinkingLevel`；
+ *   映射到数字或其它模型 → `thinkingBudget`（不超过回答上限留白）；off → `thinkingBudget: 0`；
+ * - 缓存：Gemini 的隐式缓存自动生效，请求里没有可设的字段；`cacheRetention` 不影响请求体；
+ * - `toolChoice: "none"`（有工具时）→ `toolConfig.functionCallingConfig.mode: "NONE"`。
+ */
+import { contentText, normalizeContext, sanitizeText } from "../context.js";
+import { DEFAULT_THINKING_BUDGETS, clampBudgetToAnswerRoom, clampThinkingLevel, discreteThinkingLevel, } from "../thinking.js";
+export const GOOGLE_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
+const GOOGLE_COMPAT_KEYS = [
+    "supportsThoughtSignature",
+    "supportsFunctionResponseParts",
+];
+/** `gemini-3.1-pro-preview` → 3；不是 Gemini 版本号命名返回 undefined。 */
+export function geminiMajorVersion(modelId) {
+    const match = /^(?:models\/)?gemini(?:-live)?-(\d+)/.exec(modelId.toLowerCase());
+    return match?.[1] !== undefined ? Number.parseInt(match[1], 10) : undefined;
+}
+/** Gemini 3 起 functionCall / functionResponse 要带 id。 */
+export function requiresToolCallId(modelId) {
+    return (geminiMajorVersion(modelId) ?? 0) >= 3;
+}
+/** 缺省按模型族推断离散级别：Gemini 3 Pro / Flash 及 `gemini-flash(-lite)-latest`。 */
+export function usesDiscreteThinkingLevel(modelId) {
+    const id = modelId.toLowerCase();
+    return /gemini-3(?:\.\d+)?-(?:pro|flash)/.test(id) || /^gemini-flash(?:-lite)?-latest$/.test(id);
+}
+function pick(compat) {
+    const out = {};
+    for (const key of GOOGLE_COMPAT_KEYS) {
+        const value = compat?.[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * compat：推断 ← provider.compat ← model.compat。原生协议的实现都认 thoughtSignature，缺省开；
+ * 工具结果内嵌图片只有 Gemini 3 起支持，非 Gemini 命名的模型保守关。
+ */
+export function detectGoogleCompat(model, provider) {
+    const major = geminiMajorVersion(model.id);
+    return {
+        supportsThoughtSignature: true,
+        supportsFunctionResponseParts: major !== undefined && major >= 3,
+        ...pick(provider?.compat),
+        ...pick(model.compat),
+    };
+}
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+function validSignature(signature) {
+    return (signature !== undefined &&
+        signature.length > 0 &&
+        signature.length % 4 === 0 &&
+        BASE64.test(signature));
+}
+function inlineData(block) {
+    return { inlineData: { mimeType: block.mimeType, data: block.data } };
+}
+function convertUser(message) {
+    if (typeof message.content === "string") {
+        return message.content.length > 0
+            ? { role: "user", parts: [{ text: sanitizeText(message.content) }] }
+            : undefined;
+    }
+    const parts = [];
+    for (const block of message.content) {
+        if (block.type === "image")
+            parts.push(inlineData(block));
+        else if (block.text.length > 0)
+            parts.push({ text: sanitizeText(block.text) });
+    }
+    return parts.length > 0 ? { role: "user", parts } : undefined;
+}
+function convertAssistant(model, message, compat) {
+    const sameModel = message.provider === model.provider && message.model === model.id;
+    const signatureOf = (value) => sameModel && compat.supportsThoughtSignature && validSignature(value) ? value : undefined;
+    const parts = [];
+    for (const block of message.content) {
+        if (block.type === "text") {
+            const signature = signatureOf(block.textSignature);
+            if (block.text.trim().length === 0 && !signature)
+                continue;
+            parts.push({
+                text: sanitizeText(block.text),
+                ...(signature ? { thoughtSignature: signature } : {}),
+            });
+        }
+        else if (block.type === "thinking") {
+            if (block.redacted)
+                continue;
+            const signature = signatureOf(block.thinkingSignature);
+            if (sameModel) {
+                if (block.thinking.trim().length === 0 && !signature)
+                    continue;
+                parts.push({
+                    thought: true,
+                    text: sanitizeText(block.thinking),
+                    ...(signature ? { thoughtSignature: signature } : {}),
+                });
+            }
+            else if (block.thinking.trim().length > 0) {
+                parts.push({ text: sanitizeText(block.thinking) });
+            }
+        }
+        else {
+            const signature = signatureOf(block.thoughtSignature);
+            parts.push({
+                functionCall: {
+                    name: block.name,
+                    args: block.arguments,
+                    ...(requiresToolCallId(model.id) ? { id: block.id } : {}),
+                },
+                ...(signature ? { thoughtSignature: signature } : {}),
+            });
+        }
+    }
+    return parts.length > 0 ? { role: "model", parts } : undefined;
+}
+function convertToolResult(model, message, compat) {
+    const text = contentText(message.content);
+    const images = typeof message.content === "string" || !model.input.includes("image")
+        ? []
+        : message.content.filter((b) => b.type === "image");
+    const value = sanitizeText(text.length > 0 ? text : images.length > 0 ? "(see attached image)" : "(no output)");
+    const nested = images.length > 0 && compat.supportsFunctionResponseParts;
+    const part = {
+        functionResponse: {
+            name: message.toolName,
+            response: message.isError ? { error: value } : { output: value },
+            ...(nested ? { parts: images.map(inlineData) } : {}),
+            ...(requiresToolCallId(model.id) ? { id: message.toolCallId } : {}),
+        },
+    };
+    const extra = images.length > 0 && !nested
+        ? { role: "user", parts: [{ text: "Tool result images:" }, ...images.map(inlineData)] }
+        : undefined;
+    return { part, extra };
+}
+export function convertGoogleContents(model, messages, compat) {
+    const contents = [];
+    for (let i = 0; i < messages.length; i++) {
+        const message = messages[i];
+        if (!message)
+            continue;
+        if (message.role === "toolResult") {
+            const parts = [];
+            const extras = [];
+            while (messages[i]?.role === "toolResult") {
+                const converted = convertToolResult(model, messages[i], compat);
+                parts.push(converted.part);
+                if (converted.extra)
+                    extras.push(converted.extra);
+                i++;
+            }
+            i--;
+            contents.push({ role: "user", parts }, ...extras);
+            continue;
+        }
+        const converted = message.role === "user" ? convertUser(message) : convertAssistant(model, message, compat);
+        if (converted)
+            contents.push(converted);
+    }
+    return contents;
+}
+/** Gemini 的 schema 是 OpenAPI 子集：去掉它不认的 `additionalProperties`。 */
+export function toGoogleSchema(schema) {
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "additionalProperties")
+            continue;
+        if (key === "properties" && value && typeof value === "object") {
+            const props = {};
+            for (const [name, sub] of Object.entries(value)) {
+                props[name] = toGoogleSchema(sub);
+            }
+            out[key] = props;
+        }
+        else if (key === "items" && value && typeof value === "object") {
+            out[key] = toGoogleSchema(value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function convertTools(tools) {
+    return [
+        {
+            functionDeclarations: tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                parameters: toGoogleSchema({ ...tool.parameters, type: "object" }),
+            })),
+        },
+    ];
+}
+/** 写 thinkingConfig；返回实际发出的值（离散级别名或预算）。 */
+function applyThinking(config, model, level, maxTokens) {
+    if (!model.reasoning)
+        return undefined;
+    if (level === "off") {
+        const off = model.thinkingLevelMap?.off;
+        const discrete = typeof off === "string" ? off.toUpperCase() : undefined;
+        config["thinkingConfig"] = discrete ? { thinkingLevel: discrete } : { thinkingBudget: 0 };
+        return discrete ?? "0";
+    }
+    const mapped = model.thinkingLevelMap?.[level];
+    const discrete = typeof mapped === "string" || (mapped === undefined && usesDiscreteThinkingLevel(model.id))
+        ? discreteThinkingLevel(model, level)
+        : undefined;
+    if (discrete) {
+        const value = discrete.toUpperCase();
+        config["thinkingConfig"] = { includeThoughts: true, thinkingLevel: value };
+        return value;
+    }
+    const requested = typeof mapped === "number" ? mapped : DEFAULT_THINKING_BUDGETS[level];
+    // -1 = 动态预算（Gemini 自行决定），不参与留白钳位
+    const budget = requested < 0 ? -1 : clampBudgetToAnswerRoom(requested, maxTokens);
+    config["thinkingConfig"] = { includeThoughts: true, thinkingBudget: budget };
+    return String(budget);
+}
+export function buildGoogleRequest(model, context, options) {
+    const compat = detectGoogleCompat(model);
+    const normalized = normalizeContext(context, { model });
+    const maxTokens = options.maxTokens ?? model.maxTokens;
+    const level = clampThinkingLevel(model, options.thinkingLevel ?? "off");
+    const body = { contents: convertGoogleContents(model, normalized.messages, compat) };
+    if (normalized.systemPrompt.length > 0) {
+        body["systemInstruction"] = { parts: [{ text: sanitizeText(normalized.systemPrompt) }] };
+    }
+    if (normalized.tools.length > 0) {
+        body["tools"] = convertTools(normalized.tools);
+        if (options.toolChoice === "none") {
+            body["toolConfig"] = { functionCallingConfig: { mode: "NONE" } };
+        }
+    }
+    const config = { maxOutputTokens: maxTokens };
+    if (options.temperature !== undefined)
+        config["temperature"] = options.temperature;
+    const providerLevel = applyThinking(config, model, level, maxTokens);
+    if (model.samplingParams)
+        Object.assign(config, model.samplingParams);
+    body["generationConfig"] = config;
+    return { body, compat, thinkingLevel: level, providerThinkingLevel: providerLevel };
+}

package/dist/ai/apis/openai-compat.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OpenAI 兼容线的 compat 推断（设计 §3.3）。
+ *
+ * 顺序：保守缺省 ← 推断表（先按 provider id，再按 baseUrl 子串）← `provider.compat` ←
+ * `model.compat`（字段级覆盖，undefined 不覆盖）。显式配置永远胜过推断。
+ *
+ * 缺省是「最保守的 OpenAI 兼容服务」：`max_tokens`、`system` 角色、不发 `store` /
+ * `reasoning_effort` / `strict`。只有 OpenAI 官方端点打开 OpenAI 专有开关。
+ * 表里每一项都应对应一个已验证的差异（文档或真实样本）；没验证过的不要加。
+ */
+import type { Model, OpenAICompletionsCompat, ProviderCompat, ProviderData } from "../types.js";
+export declare const OPENAI_COMPAT_KEYS: readonly ["maxTokensField", "supportsDeveloperRole", "supportsUsageInStreaming", "supportsFinishReason", "supportsReasoningEffort", "thinkingFormat", "thinkingTokenBudgetField", "requiresReasoningContentOnAssistantMessages", "requiresToolResultName", "requiresAssistantAfterToolResult", "supportsMidConvoSystemMessages", "cacheControlFormat", "supportsStrictTools", "supportsStore"];
+export declare const CONSERVATIVE_COMPAT: Readonly<OpenAICompletionsCompat>;
+type Patch = Partial<OpenAICompletionsCompat>;
+interface InferenceRule {
+    /** 供应商 id（内置 id）。 */
+    provider: string;
+    /** baseUrl 子串（自定义供应商指向同一服务时命中）。 */
+    baseUrl: string;
+    patch: (modelId: string) => Patch;
+}
+/** 推断表：13 家内置里走 OpenAI 兼容线的 11 家（anthropic / google 不走本协议）。 */
+export declare const INFERENCE_RULES: readonly InferenceRule[];
+/** 命中的推断规则（先 provider id，后 baseUrl 子串）。 */
+export declare function findInferenceRule(providerId: string, baseUrl: string): InferenceRule | undefined;
+/** 从 ProviderCompat 里挑出本协议的字段（undefined 跳过）。 */
+export declare function pickOpenAICompat(compat: ProviderCompat | undefined): Patch;
+/** 推断（不含显式配置）。 */
+export declare function inferOpenAICompat(providerId: string, baseUrl: string, modelId: string): OpenAICompletionsCompat;
+/**
+ * 完整 compat：推断 ← provider.compat ← model.compat。`provider` 缺省时只用 model
+ * 自带信息（registry 物化后的模型已把 provider.compat 合进 model.compat）。
+ */
+export declare function detectCompat(model: Model, provider?: ProviderData): OpenAICompletionsCompat;
+export {};