@henjicc/ai-sdk 0.2.8

package/dist/llm/chat.d.ts

@@ -0,0 +1,66 @@
+import type { RuntimeContext } from '../runtime/RuntimeContext.js';
+import type { JsonObject, LlmChatRequestDto, LlmStreamEmitter, LlmUsageDto, LlmStreamToolCall } from './chatTypes.js';
+/**
+ * 原生 SSE 流式聊天路径（`llm:chatStream`）的编排逻辑：取密钥 → 预处理请求体
+ * （复用 2.4 迁入的 `preprocessRequestBody`）→ 解析 endpoint → 构建 payload → 发流式请求。
+ *
+ * 任务 4.2 从 `electron/main/services/llm/runtime.ts` 的 `llmChatStream` 拆出。
+ * **日志落盘与 `Done`/`Error` IPC 事件发射刻意不在这里**——那是宿主（痕迹AI 主进程）的
+ * 结构化日志格式与 IPC 契约，SDK 不应该固化具体的日志事件名/字段命名。取而代之，
+ * `runLlmChatStream` 通过可选的 `hooks` 在关键节点（请求已构建、请求已完成）把结构化数据
+ * 交还给调用方，调用方决定怎么记日志；Token/ReasoningToken 仍然通过 `emit` 实时转发
+ * （这是流式协议本身的一部分，不是"日志"）。`Done`/`Error` 事件的发射与取消任务清理，
+ * 由调用方（`electron/main/services/llm/runtime.ts`）在 `runLlmChatStream` 外层负责，
+ * 与迁移前 `llmChatStream` 的行为逐字段对齐。
+ */
+export interface LlmChatRequestBuiltInfo {
+    endpoint: string;
+    requestPayload: JsonObject;
+    processedRequest: LlmChatRequestDto;
+}
+export interface LlmChatCompletedInfo {
+    processedRequest: LlmChatRequestDto;
+    startedAtMs: number;
+    elapsedMs: number;
+    inputChars: number;
+    outputChars: number;
+    output: string;
+    reasoningOutput: string;
+    usage: LlmUsageDto | null;
+    finishReason: string | null;
+    toolCalls?: LlmStreamToolCall[];
+}
+export interface LlmChatStreamHooks {
+    /** 请求体与 endpoint 已经构建好，即将发出网络请求前触发一次。 */
+    onRequestBuilt?: (info: LlmChatRequestBuiltInfo) => void;
+    /** 流式响应正常读完（未被取消、未抛错）后触发一次。 */
+    onCompleted?: (info: LlmChatCompletedInfo) => void;
+}
+export interface LlmChatStreamOutcome {
+    providerId: string;
+    modelId: string;
+    startedAtMs: number;
+    elapsedMs: number;
+    inputChars: number;
+    outputChars: number;
+    output: string;
+    reasoningOutput: string;
+    usage: LlmUsageDto | null;
+    finishReason: string | null;
+    toolCalls?: LlmStreamToolCall[];
+}
+export interface LlmChatExecutionOptions {
+    /** 外部取消会转发到本次请求的 AbortController。 */
+    signal?: AbortSignal;
+    /** 正数毫秒；达到截止时间后中止请求，并按供应商超时错误归一。 */
+    timeoutMs?: number;
+}
+/** taskId 只应该在一次调用里计算一次（`request.requestId` 缺省时会落到 `Date.now()`），调用方与本函数必须复用同一个值。 */
+export declare function resolveLlmTaskId(request: LlmChatRequestDto): string;
+export declare function cancelLlmChatTask(taskId: string): void;
+export declare function runLlmChatStream(request: LlmChatRequestDto, taskId: string, emit: LlmStreamEmitter, runtime: RuntimeContext, hooks?: LlmChatStreamHooks, execution?: LlmChatExecutionOptions): Promise<LlmChatStreamOutcome>;
+export declare function normalizeLlmChatError(taskId: string, error: unknown, context?: {
+    providerId: string;
+    modelId: string;
+    requestId: string;
+}): string;

package/dist/llm/chat.js

@@ -0,0 +1,144 @@
+import { preprocessRequestBody } from '../upload/preprocess.js';
+import { normalizeProviderError } from '../runtime/error-classify.js';
+import { cancelTask, clearCancelFlag, isCancelled, registerAbortController, } from '../runtime/task-registry.js';
+import { buildOpenAiCompatiblePayload, resolveOpenAiCompatibleEndpoint, resolvePpioChatEndpoint, streamOpenAiCompatibleChat, } from './streaming.js';
+import { countLlmInputChars } from './message-metrics.js';
+import { resolveLlmEndpointIdentity } from './endpointProfiles.js';
+/** taskId 只应该在一次调用里计算一次（`request.requestId` 缺省时会落到 `Date.now()`），调用方与本函数必须复用同一个值。 */
+export function resolveLlmTaskId(request) {
+    const fromRequest = request.requestId?.trim();
+    return fromRequest || `llm-${request.modelId}-${Date.now()}`;
+}
+export function cancelLlmChatTask(taskId) {
+    cancelTask('llm', taskId);
+}
+export async function runLlmChatStream(request, taskId, emit, runtime, hooks = {}, execution = {}) {
+    const controller = new AbortController();
+    if (execution.timeoutMs !== undefined && (!Number.isFinite(execution.timeoutMs) || execution.timeoutMs <= 0)) {
+        throw new Error('LLM timeoutMs must be a positive finite number');
+    }
+    const forwardAbort = () => controller.abort();
+    if (execution.signal?.aborted)
+        controller.abort();
+    else
+        execution.signal?.addEventListener('abort', forwardAbort, { once: true });
+    let timedOut = false;
+    const timeout = execution.timeoutMs === undefined ? undefined : setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, execution.timeoutMs);
+    const startedAtMs = Date.now();
+    const inputChars = countLlmInputChars(request.messages);
+    const span = runtime.tracer?.startSpan('llm.chat', {
+        requestId: taskId,
+        providerId: request.providerId,
+        modelId: request.modelId,
+    });
+    registerAbortController('llm', taskId, controller);
+    try {
+        const identity = resolveLlmEndpointIdentity(request);
+        const resolvedRequest = {
+            ...request,
+            providerFamilyId: identity.providerFamilyId,
+            endpointProfile: identity.endpointProfile,
+            credentialId: identity.credentialId,
+            baseUrl: identity.baseUrl,
+        };
+        const apiKey = await runtime.credentials.get('llm', identity.credentialId);
+        if (!apiKey) {
+            throw new Error(`[api_key_missing] LLM provider "${request.providerId}" API key is not configured.`);
+        }
+        const processedRequest = await preprocessLlmRequest(resolvedRequest, runtime);
+        const endpoint = identity.providerFamilyId === 'ppio'
+            ? resolvePpioChatEndpoint(processedRequest.baseUrl)
+            : resolveOpenAiCompatibleEndpoint(processedRequest);
+        const requestPayload = buildOpenAiCompatiblePayload(processedRequest);
+        hooks.onRequestBuilt?.({ endpoint, requestPayload, processedRequest });
+        const output = await streamOpenAiCompatibleChat({
+            endpoint,
+            apiKey,
+            request: processedRequest,
+            signal: controller.signal,
+            emit,
+            transport: runtime.transport,
+        });
+        if (isCancelled('llm', taskId)) {
+            throw new Error(`[task_cancelled] LLM task cancelled: ${taskId}`);
+        }
+        const elapsedMs = Date.now() - startedAtMs;
+        const outputChars = output.output.length + output.reasoningOutput.length;
+        hooks.onCompleted?.({
+            processedRequest,
+            startedAtMs,
+            elapsedMs,
+            inputChars,
+            outputChars,
+            output: output.output,
+            reasoningOutput: output.reasoningOutput,
+            usage: output.usage,
+            finishReason: output.finishReason,
+            toolCalls: output.toolCalls,
+        });
+        span?.end();
+        return {
+            providerId: processedRequest.providerId,
+            modelId: processedRequest.modelId,
+            startedAtMs,
+            elapsedMs,
+            inputChars,
+            outputChars,
+            output: output.output,
+            reasoningOutput: output.reasoningOutput,
+            usage: output.usage,
+            finishReason: output.finishReason,
+            toolCalls: output.toolCalls,
+        };
+    }
+    catch (error) {
+        const normalizedInput = timedOut
+            ? Object.assign(new Error(`LLM request timed out after ${execution.timeoutMs}ms`), {
+                name: 'TimeoutError',
+                code: 'MODEL_REQUEST_TIMEOUT',
+            })
+            : error;
+        span?.end(normalizedInput);
+        throw new Error(normalizeLlmChatError(taskId, normalizedInput, {
+            providerId: request.providerId,
+            modelId: request.modelId,
+            requestId: taskId,
+        }));
+    }
+    finally {
+        execution.signal?.removeEventListener('abort', forwardAbort);
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+        clearCancelFlag('llm', taskId);
+    }
+}
+async function preprocessLlmRequest(request, runtime) {
+    const body = { messages: request.messages };
+    const params = request.metadata ?? {};
+    const processed = await preprocessRequestBody(request.providerFamilyId ?? request.providerId, '/v1/chat/completions', body, runtime, params);
+    const processedBody = isJsonObject(processed) ? processed : body;
+    const processedMessages = Array.isArray(processedBody.messages)
+        ? processedBody.messages
+        : request.messages;
+    return { ...request, messages: processedMessages };
+}
+export function normalizeLlmChatError(taskId, error, context) {
+    if (isCancelled('llm', taskId) || isAbortError(error)) {
+        return `[task_cancelled] LLM task cancelled: ${taskId}`;
+    }
+    if (error instanceof Error && error.message.startsWith('[api_key_missing]')) {
+        return error.message;
+    }
+    if (context)
+        return normalizeProviderError(context, error).message;
+    return error instanceof Error ? error.message : String(error);
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/llm/chatTypes.d.ts

@@ -0,0 +1,88 @@
+import type { JsonObject, JsonValue } from '../types/runtime.js';
+import type { LlmReasoningConfig } from './reasoning.js';
+export type { JsonObject, JsonValue };
+/**
+ * 原生 SSE 流式聊天路径（`llm:chatStream`）的请求/响应 DTO。
+ *
+ * 任务 4.2 从 `electron/main/services/llm/types.ts` 迁入。文件名刻意不叫 `types.ts`——
+ * 本目录（`packages/ai-sdk/src/llm/`）已有一个 4.1 迁入的 `types.ts`（模型目录/供应商预设
+ * 相关的应用侧桥接类型），两者职责不同，同名会互相遮蔽或强迫合并，`chatTypes.ts` 与
+ * `modelStep.ts`（同目录下 Vercel AI SDK 模型步类型）保持同样的"按路径命名"风格。
+ */
+export type LlmRole = 'system' | 'user' | 'assistant';
+export interface LlmContentPart {
+    type: string;
+    text?: string;
+    imageUrl?: JsonValue;
+    videoUrl?: JsonValue;
+    inputAudio?: JsonValue;
+    file?: JsonValue;
+}
+export interface LlmChatMessageDto {
+    role: LlmRole;
+    content?: string | LlmContentPart[] | null;
+    name?: string;
+}
+export interface LlmChatRequestDto {
+    requestId?: string;
+    providerId: string;
+    providerFamilyId?: string;
+    endpointProfile?: string;
+    credentialId?: string;
+    modelId: string;
+    adapter?: string;
+    baseUrl?: string;
+    reasoning?: LlmReasoningConfig;
+    messages: LlmChatMessageDto[];
+    capabilities?: JsonObject;
+    tools?: JsonValue;
+    policy?: JsonObject;
+    memory?: JsonObject;
+    metadata?: JsonObject;
+}
+export interface LlmTraceDto {
+    providerId: string;
+    modelId: string;
+    startedAtMs: number;
+    elapsedMs: number;
+    inputChars: number;
+    outputChars: number;
+}
+export type LlmStreamEventDto = {
+    type: 'Token';
+    data: string;
+} | {
+    type: 'ReasoningToken';
+    data: string;
+} | {
+    type: 'Done';
+    data: LlmTraceDto;
+} | {
+    type: 'Error';
+    data: string;
+};
+export type LlmStreamEmitter = (event: LlmStreamEventDto) => void;
+export interface LlmUsageDto {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    reasoningTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    totalTokens: number | null;
+}
+export interface LlmStreamOutput {
+    output: string;
+    reasoningOutput: string;
+    usage: LlmUsageDto | null;
+    finishReason: string | null;
+    toolCalls?: LlmStreamToolCall[];
+}
+export interface LlmStreamToolCall {
+    index: number;
+    id: string;
+    type: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}

package/dist/llm/chatTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/llm/defaults.d.ts

@@ -0,0 +1,29 @@
+import type { LlmCapabilities, LlmReasoningConfig, LlmReasoningEffort } from './types.js';
+/**
+ * 供应商无关的默认值与能力查表工具。
+ *
+ * 这里只放"任何消费方都能直接复用"的部分：内置模型能力查表的默认基线、几个官方 Base URL /
+ * 模型 ID 常量、思考强度的默认档位。痕迹AI 特有的默认配置（内置提示词模板、默认智能助手
+ * 画像、内置供应商/模型清单的产品选择）属于应用侧业务决策，留在
+ * `src/core/llm/defaults.ts`——那份文件通过重新导出这里的内容 + 自己的业务函数组合出完整的
+ * `createDefaultLlmConfig()`，对外仍是同一个导入路径，不需要动所有消费方。
+ */
+export declare const DEFAULT_DEEPSEEK_PROVIDER_ID = "deepseek";
+export declare const DEFAULT_DEEPSEEK_BASE_URL = "https://api.deepseek.com";
+export declare const DEFAULT_DEEPSEEK_MODEL_ID = "deepseek-v4-flash";
+export declare const DEFAULT_PPIO_PROVIDER_ID = "ppio";
+export declare const DEFAULT_PPIO_BASE_URL = "https://api.ppio.com/openai";
+export declare const DEFAULT_PPIO_MODEL_ID = "deepseek/deepseek-v4-flash";
+export declare const DEFAULT_LLM_REASONING_EFFORT: LlmReasoningEffort;
+export declare const DEEPSEEK_V4_CONTEXT_WINDOW = 1000000;
+export declare const DEEPSEEK_V4_MAX_OUTPUT_TOKENS = 384000;
+export declare const DEFAULT_LLM_CAPABILITIES: LlmCapabilities;
+/**
+ * 按内置模型能力目录生成一份能力声明；目录里没有的模型退回通用默认值（纯文本、能力项全关）。
+ *
+ * 添加模型的两个入口（手动添加、获取模型列表）和内置模型清单都走这里，保证"同一个模型 ID
+ * 无论从哪个入口进来，标出来的能力一致"。
+ */
+export declare function createLlmCapabilitiesForModel(modelId: string): LlmCapabilities;
+/** DeepSeek 官方要求思考模式默认开启，其余供应商默认关闭；具体档位见 `DEFAULT_LLM_REASONING_EFFORT`。 */
+export declare function createDefaultProviderReasoning(adapter?: string): LlmReasoningConfig;

package/dist/llm/defaults.js

@@ -0,0 +1,55 @@
+import { applyLlmModelCatalogEntry, findLlmModelCatalogEntry } from './modelCatalog.js';
+/**
+ * 供应商无关的默认值与能力查表工具。
+ *
+ * 这里只放"任何消费方都能直接复用"的部分：内置模型能力查表的默认基线、几个官方 Base URL /
+ * 模型 ID 常量、思考强度的默认档位。痕迹AI 特有的默认配置（内置提示词模板、默认智能助手
+ * 画像、内置供应商/模型清单的产品选择）属于应用侧业务决策，留在
+ * `src/core/llm/defaults.ts`——那份文件通过重新导出这里的内容 + 自己的业务函数组合出完整的
+ * `createDefaultLlmConfig()`，对外仍是同一个导入路径，不需要动所有消费方。
+ */
+export const DEFAULT_DEEPSEEK_PROVIDER_ID = 'deepseek';
+export const DEFAULT_DEEPSEEK_BASE_URL = 'https://api.deepseek.com';
+export const DEFAULT_DEEPSEEK_MODEL_ID = 'deepseek-v4-flash';
+export const DEFAULT_PPIO_PROVIDER_ID = 'ppio';
+export const DEFAULT_PPIO_BASE_URL = 'https://api.ppio.com/openai';
+export const DEFAULT_PPIO_MODEL_ID = 'deepseek/deepseek-v4-flash';
+export const DEFAULT_LLM_REASONING_EFFORT = 'high';
+export const DEEPSEEK_V4_CONTEXT_WINDOW = 1_000_000;
+export const DEEPSEEK_V4_MAX_OUTPUT_TOKENS = 384_000;
+export const DEFAULT_LLM_CAPABILITIES = {
+    text: true,
+    image: false,
+    video: false,
+    audio: false,
+    file: false,
+    streaming: true,
+    toolCall: false,
+    parallelTools: false,
+    jsonOutput: false,
+    structuredOutputMode: 'none',
+    reasoning: false,
+    sampling: true,
+    contextWindow: null,
+    maxOutputTokens: null,
+    usage: true,
+};
+/**
+ * 按内置模型能力目录生成一份能力声明；目录里没有的模型退回通用默认值（纯文本、能力项全关）。
+ *
+ * 添加模型的两个入口（手动添加、获取模型列表）和内置模型清单都走这里，保证"同一个模型 ID
+ * 无论从哪个入口进来，标出来的能力一致"。
+ */
+export function createLlmCapabilitiesForModel(modelId) {
+    const entry = findLlmModelCatalogEntry(modelId);
+    return entry
+        ? applyLlmModelCatalogEntry(DEFAULT_LLM_CAPABILITIES, entry)
+        : { ...DEFAULT_LLM_CAPABILITIES };
+}
+/** DeepSeek 官方要求思考模式默认开启，其余供应商默认关闭；具体档位见 `DEFAULT_LLM_REASONING_EFFORT`。 */
+export function createDefaultProviderReasoning(adapter = '') {
+    return {
+        enabled: adapter.trim().toLowerCase() === DEFAULT_DEEPSEEK_PROVIDER_ID,
+        effort: DEFAULT_LLM_REASONING_EFFORT,
+    };
+}

package/dist/llm/discovery.d.ts

@@ -0,0 +1,45 @@
+import type { RuntimeContext } from '../runtime/index.js';
+/**
+ * 模型发现（列出供应商可用模型）。任务 4.2 从 `electron/main/services/llm/discovery.ts`
+ * 迁入。唯一的实质改动：密钥读取从 `getLlmProviderApiKey`（Electron keystore）改为
+ * `RuntimeContext.credentials.get('llm', providerId)`，网络请求从全局 `fetch` 改为
+ * `RuntimeContext.transport.fetch`。
+ */
+export interface DiscoveredModelItem {
+    modelId: string;
+    displayName: string;
+    contextWindow: number | null;
+    maxOutputTokens: number | null;
+}
+interface RawDiscoveredModel {
+    id?: unknown;
+    title?: unknown;
+    name?: unknown;
+    context_size?: unknown;
+    max_input_tokens?: unknown;
+    input_token_limit?: unknown;
+    inputTokenLimit?: unknown;
+    context_window?: unknown;
+    max_tokens?: unknown;
+    max_completion_tokens?: unknown;
+    max_output_tokens?: unknown;
+    output_token_limit?: unknown;
+    outputTokenLimit?: unknown;
+    active?: unknown;
+}
+export interface DiscoverModelsOptions {
+    providerFamilyId?: string;
+    endpointProfile?: string;
+    credentialId?: string;
+    /** 宿主取消会原样下沉到 Transport.fetch。 */
+    signal?: AbortSignal;
+    /** 正数毫秒；超时中止 Transport.fetch，并抛出不含凭据的安全错误。 */
+    timeoutMs?: number;
+    /** 某些兼容端点允许匿名发现；Groq 等明确要求鉴权的供应商应开启。 */
+    requireCredential?: boolean;
+    /** 只返回供应商声明为 active 的模型；没有 active 字段的兼容响应仍保留。 */
+    activeOnly?: boolean;
+}
+export declare function parseDiscoveredModel(item: RawDiscoveredModel): DiscoveredModelItem | null;
+export declare function discoverModels(providerId: string, baseUrl: string, runtime: RuntimeContext, options?: DiscoverModelsOptions): Promise<DiscoveredModelItem[]>;
+export {};

package/dist/llm/discovery.js

@@ -0,0 +1,97 @@
+import { resolveProviderExtraAuthHeaders } from './providerProtocol.js';
+import { resolveLlmEndpointIdentity } from './endpointProfiles.js';
+function optionalText(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function optionalPositiveInteger(...values) {
+    for (const value of values) {
+        const parsed = typeof value === 'number'
+            ? value
+            : typeof value === 'string' && value.trim() ? Number(value) : Number.NaN;
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed);
+    }
+    return null;
+}
+export function parseDiscoveredModel(item) {
+    const modelId = optionalText(item.id);
+    if (!modelId)
+        return null;
+    return {
+        modelId,
+        displayName: optionalText(item.title) ?? optionalText(item.name) ?? modelId,
+        contextWindow: optionalPositiveInteger(item.context_size, item.max_input_tokens, item.input_token_limit, item.inputTokenLimit, item.context_window),
+        maxOutputTokens: optionalPositiveInteger(item.max_output_tokens, item.output_token_limit, item.outputTokenLimit, item.max_tokens, item.max_completion_tokens),
+    };
+}
+export async function discoverModels(providerId, baseUrl, runtime, options = {}) {
+    const identity = resolveLlmEndpointIdentity({
+        providerId,
+        providerFamilyId: options.providerFamilyId,
+        endpointProfile: options.endpointProfile,
+        credentialId: options.credentialId,
+        baseUrl,
+    });
+    const apiKey = await runtime.credentials.get('llm', identity.credentialId);
+    if (options.requireCredential && !apiKey) {
+        throw new Error(`[api_key_missing] LLM provider "${providerId}" API key is not configured.`);
+    }
+    const url = resolveModelsEndpoint(identity.baseUrl ?? baseUrl);
+    const headers = { Accept: 'application/json' };
+    if (apiKey) {
+        headers.Authorization = `Bearer ${apiKey}`;
+        Object.assign(headers, resolveProviderExtraAuthHeaders(identity.providerFamilyId, apiKey));
+    }
+    const deadline = createDiscoveryDeadline(options);
+    try {
+        const response = await runtime.transport.fetch(url, {
+            method: 'GET',
+            headers,
+            signal: deadline.signal,
+        });
+        if (!response.ok)
+            throw new Error(`获取模型列表失败: ${response.status}`);
+        const data = await response.json();
+        return (data.data ?? [])
+            .filter(item => !options.activeOnly || item.active !== false)
+            .map(parseDiscoveredModel)
+            .filter((item) => item !== null);
+    }
+    catch (error) {
+        if (deadline.didTimeOut())
+            throw new Error(`获取模型列表超时: ${providerId}`);
+        throw error;
+    }
+    finally {
+        deadline.dispose();
+    }
+}
+function resolveModelsEndpoint(baseUrl) {
+    const normalized = baseUrl.trim().replace(/\/+$/, '');
+    return /\/v\d+$/.test(normalized) ? `${normalized}/models` : `${normalized}/v1/models`;
+}
+function createDiscoveryDeadline(options) {
+    if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+        throw new Error('模型发现 timeoutMs 必须是正有限数');
+    }
+    const controller = new AbortController();
+    const forwardAbort = () => controller.abort();
+    if (options.signal?.aborted)
+        controller.abort();
+    else
+        options.signal?.addEventListener('abort', forwardAbort, { once: true });
+    let timedOut = false;
+    const timer = options.timeoutMs === undefined ? undefined : setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, options.timeoutMs);
+    return {
+        signal: controller.signal,
+        didTimeOut: () => timedOut,
+        dispose: () => {
+            options.signal?.removeEventListener('abort', forwardAbort);
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
+}

package/dist/llm/endpointProfiles.d.ts

@@ -0,0 +1,41 @@
+import type { LlmApiProtocol } from './providerProtocol.js';
+/**
+ * LLM 区域/租户端点身份。
+ *
+ * providerId 是宿主可命名的配置实例，providerFamilyId 才决定协议差异；credentialId
+ * 独立决定凭据槽。三者不可互相推断，避免区域化实例把一个区域密钥带到另一区端点。
+ */
+export interface LlmEndpointIdentity {
+    providerId: string;
+    providerFamilyId?: string;
+    endpointProfile?: string;
+    credentialId?: string;
+    baseUrl?: string;
+}
+export interface ResolvedLlmEndpointIdentity {
+    providerId: string;
+    providerFamilyId: string;
+    endpointProfile?: string;
+    credentialId: string;
+    baseUrl?: string;
+}
+export interface LlmEndpointProfile {
+    id: string;
+    displayName: string;
+    baseUrl: string;
+    /** 某些协议使用独立网关前缀；未声明时沿用 baseUrl。 */
+    protocolBaseUrls?: Partial<Record<LlmApiProtocol, string>>;
+    websiteUrl: string;
+    apiKeyUrl: string;
+    defaultCredentialId: string;
+    modelIds: readonly string[];
+    docs: string;
+}
+export interface LlmEndpointProfileFamily {
+    providerFamilyId: string;
+    defaultProfile: string;
+    profiles: readonly LlmEndpointProfile[];
+}
+export declare function registerLlmEndpointProfileFamily(family: LlmEndpointProfileFamily): void;
+export declare function getLlmEndpointProfileFamily(providerFamilyId: string): LlmEndpointProfileFamily | null;
+export declare function resolveLlmEndpointIdentity(input: LlmEndpointIdentity): ResolvedLlmEndpointIdentity;

package/dist/llm/endpointProfiles.js

@@ -0,0 +1,75 @@
+import { BIGMODEL_ENDPOINT_PROFILE_FAMILY } from './bigmodel/profiles.js';
+const PROFILE_FAMILIES = new Map([
+    [BIGMODEL_ENDPOINT_PROFILE_FAMILY.providerFamilyId, BIGMODEL_ENDPOINT_PROFILE_FAMILY],
+]);
+export function registerLlmEndpointProfileFamily(family) {
+    const familyId = normalizeId(family.providerFamilyId, 'providerFamilyId');
+    if (PROFILE_FAMILIES.has(familyId)) {
+        throw new Error(`[llm_endpoint_profile_conflict] provider family "${familyId}" is already registered`);
+    }
+    const ids = new Set();
+    const credentials = new Set();
+    for (const profile of family.profiles) {
+        const id = normalizeId(profile.id, 'endpointProfile');
+        const credentialId = normalizeId(profile.defaultCredentialId, 'credentialId');
+        if (ids.has(id)) {
+            throw new Error(`[llm_endpoint_profile_conflict] ${familyId} endpoint profile "${id}" is duplicated`);
+        }
+        if (credentials.has(credentialId)) {
+            throw new Error(`[llm_credential_scope_conflict] ${familyId} endpoint profiles must not share credential "${credentialId}"`);
+        }
+        ids.add(id);
+        credentials.add(credentialId);
+    }
+    if (!ids.has(family.defaultProfile)) {
+        throw new Error(`[llm_endpoint_profile_invalid] ${familyId} default profile "${family.defaultProfile}" is not registered`);
+    }
+    PROFILE_FAMILIES.set(familyId, family);
+}
+export function getLlmEndpointProfileFamily(providerFamilyId) {
+    return PROFILE_FAMILIES.get(providerFamilyId.trim().toLowerCase()) ?? null;
+}
+export function resolveLlmEndpointIdentity(input) {
+    const providerId = normalizeId(input.providerId, 'providerId');
+    // `bigmodel-global` 是 SDK 生成的稳定实例 id；即使宿主旧 schema 暂时漏存新增字段，也不能
+    // 把它退化成任意 OpenAI 兼容供应商，从而绕开 Global 端点/凭据隔离。
+    const inferredBigmodelProfile = providerId === 'bigmodel-global' ? 'global' : undefined;
+    const providerFamilyId = normalizeId(input.providerFamilyId ?? (inferredBigmodelProfile ? 'bigmodel' : providerId), 'providerFamilyId');
+    const family = PROFILE_FAMILIES.get(providerFamilyId);
+    if (!family) {
+        return {
+            providerId,
+            providerFamilyId,
+            endpointProfile: input.endpointProfile,
+            credentialId: normalizeId(input.credentialId ?? providerId, 'credentialId'),
+            baseUrl: input.baseUrl,
+        };
+    }
+    const profileId = input.endpointProfile?.trim().toLowerCase() || inferredBigmodelProfile || family.defaultProfile;
+    const profile = family.profiles.find(item => item.id === profileId);
+    if (!profile) {
+        throw new Error(`[llm_endpoint_profile_unknown] provider family "${providerFamilyId}" has no endpoint profile "${profileId}"`);
+    }
+    const credentialId = normalizeId(input.credentialId ?? profile.defaultCredentialId, 'credentialId');
+    if (credentialId !== profile.defaultCredentialId) {
+        throw new Error(`[llm_credential_scope_mismatch] endpoint profile "${providerFamilyId}/${profile.id}" requires credential "${profile.defaultCredentialId}", received "${credentialId}"`);
+    }
+    const suppliedBaseUrl = input.baseUrl?.trim().replace(/\/+$/, '');
+    const profileBaseUrl = profile.baseUrl.replace(/\/+$/, '');
+    if (suppliedBaseUrl && suppliedBaseUrl !== profileBaseUrl) {
+        throw new Error(`[llm_endpoint_profile_mismatch] endpoint profile "${providerFamilyId}/${profile.id}" requires baseUrl "${profileBaseUrl}"`);
+    }
+    return {
+        providerId,
+        providerFamilyId,
+        endpointProfile: profile.id,
+        credentialId,
+        baseUrl: profileBaseUrl,
+    };
+}
+function normalizeId(value, field) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        throw new Error(`[llm_endpoint_identity_invalid] ${field} must not be empty`);
+    return normalized;
+}

package/dist/llm/groq/index.d.ts

@@ -0,0 +1,25 @@
+import type { RuntimeContext } from '../../runtime/RuntimeContext.js';
+import { type LlmChatExecutionOptions, type LlmChatStreamHooks, type LlmChatStreamOutcome } from '../chat.js';
+import type { LlmChatRequestDto, LlmStreamEmitter } from '../chatTypes.js';
+import { type DiscoveredModelItem, type DiscoverModelsOptions } from '../discovery.js';
+export { GROQ_BASE_URL, GROQ_DEFAULT_MODEL_ID, GROQ_DEFAULT_MODEL_CONFIG, GROQ_PROVIDER_ID, GROQ_PROVIDER_PRESET, } from './preset.js';
+export type GroqChatRequest = Omit<LlmChatRequestDto, 'providerId' | 'modelId' | 'adapter' | 'baseUrl'> & {
+    /** 缺省使用 Say-It 已确认的 openai/gpt-oss-20b。 */
+    modelId?: string;
+    /** 默认使用 GroqCloud 官方地址；仅为代理或测试宿主保留显式覆盖。 */
+    baseUrl?: string;
+};
+export interface GroqChatStreamOptions extends LlmChatExecutionOptions {
+    hooks?: LlmChatStreamHooks;
+}
+export type GroqDiscoveryOptions = Omit<DiscoverModelsOptions, 'requireCredential' | 'activeOnly'>;
+/**
+ * 把 Groq 的稳定坐标补到通用 LLM DTO；真正的 SSE、错误、usage 与 finish 解析仍由共享内核完成。
+ */
+export declare function createGroqChatRequest(request: GroqChatRequest): LlmChatRequestDto;
+/** Groq 按需流式入口；没有复制第二套 OpenAI-compatible 执行逻辑。 */
+export declare function runGroqChatStream(request: GroqChatRequest, taskId: string, emit: LlmStreamEmitter, runtime: RuntimeContext, options?: GroqChatStreamOptions): Promise<LlmChatStreamOutcome>;
+/** Groq 官方 /models 发现：要求凭据并过滤 active=false，保留未知 active 的兼容项。 */
+export declare function discoverGroqModels(runtime: RuntimeContext, options?: GroqDiscoveryOptions): Promise<DiscoveredModelItem[]>;
+export type { DiscoveredModelItem, LlmChatExecutionOptions, LlmChatStreamHooks, LlmChatStreamOutcome, LlmStreamEmitter, RuntimeContext, };
+export { GROQ_LLM_MODULE_DESCRIPTOR, GROQ_LLM_MODULE_ID, createGroqLlmModule, } from './module.js';