@weisiren000/oiiai 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -204,7 +204,7 @@ interface AIProvider {
 /**
  * 扩展的 ask 选项，支持降级配置
  */
-interface AskOptions extends Omit<ChatOptions, 'model' | 'messages'> {
+interface AskOptions$1 extends Omit<ChatOptions, 'model' | 'messages'> {
     /** 降级策略配置 */
     fallback?: Partial<FallbackConfig>;
     /** 是否自动调整参数以适应模型特性 */
@@ -251,7 +251,7 @@ declare abstract class BaseProvider implements AIProvider {
      * 2. 为思考模型自动调整 maxTokens
      * 3. 如果 content 为空，智能降级（提取结论或返回 reasoning）
      */
-    ask(model: string, question: string, options?: AskOptions): Promise<string>;
+    ask(model: string, question: string, options?: AskOptions$1): Promise<string>;
     /**
      * 带系统提示的对话（默认实现）
      *
@@ -260,7 +260,7 @@ declare abstract class BaseProvider implements AIProvider {
      * 2. 为思考模型自动调整 maxTokens
      * 3. 如果 content 为空，智能降级（提取结论或返回 reasoning）
      */
-    askWithSystem(model: string, systemPrompt: string, userMessage: string, options?: AskOptions): Promise<string>;
+    askWithSystem(model: string, systemPrompt: string, userMessage: string, options?: AskOptions$1): Promise<string>;
     /**
      * 场景化问答：根据场景自动配置参数
      *
@@ -272,24 +272,131 @@ declare abstract class BaseProvider implements AIProvider {
      *   - 'reasoning': 逻辑推理
      *   - 'fast': 快速回答（关闭思考）
      */
-    askWithScenario(model: string, question: string, scenario?: 'simple' | 'math' | 'reasoning' | 'fast', options?: AskOptions): Promise<string>;
+    askWithScenario(model: string, question: string, scenario?: 'simple' | 'math' | 'reasoning' | 'fast', options?: AskOptions$1): Promise<string>;
 }
 
 /**
- * 统一的 Provider 工厂
- * 让所有 Provider 使用方式一致
+ * 配置管理类型定义
+ * 定义统一的 Provider 配置格式和注册表配置
+ */
+/**
+ * Provider 类型
+ */
+type ProviderType$2 = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek' | 'poe' | 'nova';
+/**
+ * 统一的 Provider 配置格式
+ * 用于配置各种 AI Provider 的连接和行为
+ */
+interface UnifiedProviderConfig {
+    /** Provider 类型 */
+    provider: ProviderType$2;
+    /** 自定义适配器路径（可选） */
+    adapter?: string;
+    /** 凭证信息 */
+    credentials: {
+        /** API 密钥 */
+        apiKey: string;
+        /** 基础 URL（可选） */
+        baseUrl?: string;
+    };
+    /** 选项配置（可选） */
+    options?: {
+        /** 超时时间（毫秒） */
+        timeout?: number;
+        /** 重试次数 */
+        retries?: number;
+        /** 额外请求头 */
+        headers?: Record<string, string>;
+    };
+    /** 功能开关（可选） */
+    features?: {
+        /** 是否支持流式输出 */
+        streaming?: boolean;
+        /** 是否支持推理 */
+        reasoning?: boolean;
+    };
+}
+/**
+ * 注册表配置（用于配置文件）
+ * 支持从 JSON 配置文件加载多个 Provider
+ */
+interface RegistryConfig {
+    /** Provider 配置映射 */
+    providers: {
+        [key: string]: {
+            /** 自定义适配器路径（可选） */
+            adapter?: string;
+            /** Provider 配置 */
+            config: {
+                /** API 密钥 */
+                apiKey: string;
+                /** 基础 URL（可选） */
+                baseUrl?: string;
+            };
+        };
+    };
+}
+/**
+ * Provider 能力描述
+ * 描述 Provider 支持的功能特性
+ */
+interface ProviderCapabilities {
+    /** 是否支持流式输出 */
+    streaming: boolean;
+    /** 是否支持推理/思考 */
+    reasoning: boolean;
+    /** 是否支持函数调用 */
+    functionCalling: boolean;
+    /** 是否支持视觉/图像 */
+    vision: boolean;
+}
+/**
+ * 旧格式的 Provider 配置
+ * 用于向后兼容
+ */
+interface LegacyProviderConfig {
+    /** Provider 类型 */
+    provider: ProviderType$2;
+    /** API 密钥 */
+    apiKey: string;
+    /** 基础 URL（可选） */
+    baseUrl?: string;
+}
+/**
+ * 配置默认值
+ */
+declare const CONFIG_DEFAULTS: {
+    /** 默认超时时间（毫秒） */
+    readonly timeout: 30000;
+    /** 默认重试次数 */
+    readonly retries: 3;
+    /** 默认功能开关 */
+    readonly features: {
+        readonly streaming: true;
+        readonly reasoning: false;
+    };
+};
+/**
+ * 有效的 Provider 类型列表
  */
+declare const VALID_PROVIDERS: ProviderType$2[];
 
 /**
- * 支持的 Provider 类型
+ * 统一的 Provider 工厂
+ * 让所有 Provider 使用方式一致
+ *
+ * 重构后使用 ProviderRegistry 和 ConfigManager 实现：
+ * - 通过注册表获取适配器
+ * - 通过配置管理器处理配置
+ * - 保持与现有 API 的完全向后兼容性
  */
-type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek' | 'poe' | 'nova';
+
 /**
- * 统一的 Provider 配置
+ * 统一的 Provider 配置（旧格式，保持向后兼容）
  */
 interface ProviderConfig {
     /** Provider 类型 */
-    provider: ProviderType;
+    provider: ProviderType$2;
     /** API Key */
     apiKey: string;
     /** 自定义 API 地址（可选） */
@@ -298,6 +405,11 @@ interface ProviderConfig {
 /**
  * 创建 AI Provider 实例
  *
+ * 重构后的实现：
+ * - 使用 ConfigManager 处理配置（支持旧格式自动转换）
+ * - 使用 ProviderRegistry 获取适配器
+ * - 返回基于适配器的 Provider 包装类
+ *
  * @example
  * ```ts
  * // 所有 Provider 使用相同方式创建
@@ -313,6 +425,7 @@ interface ProviderConfig {
 declare function createProvider(config: ProviderConfig): AIProvider;
 /**
  * 快捷创建函数
+ * 提供更简洁的 API 来创建各种 Provider
  */
 declare const ai: {
     openrouter: (apiKey: string, baseUrl?: string) => AIProvider;
@@ -327,6 +440,7 @@ declare const ai: {
 
 /**
  * OpenRouter Provider 实现
+ * 使用 OpenRouterAdapter 和 HttpProviderClient 进行重构
  */
 
 /**
@@ -348,11 +462,15 @@ interface OpenRouterModelInfo extends ModelInfo {
 }
 /**
  * OpenRouter Provider
+ * 使用适配器模式重构，复用统一的工具层
  */
 declare class OpenRouterProvider extends BaseProvider {
     readonly name = "openrouter";
+    private adapter;
     private client;
-    constructor(apiKey: string);
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey: string, baseUrl?: string);
     /**
      * 发送聊天请求（非流式）
      */
@@ -363,6 +481,7 @@ declare class OpenRouterProvider extends BaseProvider {
     chatStream(options: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
     /**
      * 获取可用模型列表
+     * 注意：此方法直接调用 OpenRouter API，不使用适配器
      */
     listModels(): Promise<OpenRouterModelInfo[]>;
 }
@@ -370,6 +489,7 @@ declare class OpenRouterProvider extends BaseProvider {
 /**
  * ModelScope Provider 实现
  * 使用 OpenAI 兼容 API
+ * 使用 ModelScopeAdapter 和 HttpProviderClient 进行重构
  */
 
 /**
@@ -382,10 +502,12 @@ interface ModelScopeConfig {
 /**
  * ModelScope Provider
  * 兼容 OpenAI API 格式，支持 DeepSeek 等模型
+ * 使用适配器模式重构，复用统一的工具层
  */
 declare class ModelScopeProvider extends BaseProvider {
     readonly name = "modelscope";
-    private apiKey;
+    private adapter;
+    private client;
     private baseUrl;
     constructor(config: ModelScopeConfig | string);
     /**
@@ -401,6 +523,7 @@ declare class ModelScopeProvider extends BaseProvider {
 /**
  * HuggingFace Provider 实现
  * 使用 HuggingFace Router API (OpenAI 兼容)
+ * 使用 HuggingFaceAdapter 和 HttpProviderClient 进行重构
  */
 
 /**
@@ -413,10 +536,12 @@ interface HuggingFaceConfig {
 /**
  * HuggingFace Provider
  * 使用 HuggingFace Router，兼容 OpenAI API 格式
+ * 使用适配器模式重构，复用统一的工具层
  */
 declare class HuggingFaceProvider extends BaseProvider {
     readonly name = "huggingface";
-    private apiKey;
+    private adapter;
+    private client;
     private baseUrl;
     constructor(config: HuggingFaceConfig | string);
     /**
@@ -436,6 +561,7 @@ declare class HuggingFaceProvider extends BaseProvider {
 /**
  * Groq Provider 实现
  * 使用 Groq API (OpenAI 兼容)
+ * 使用 GroqAdapter 和 HttpProviderClient 进行重构
  */
 
 /**
@@ -447,11 +573,13 @@ interface GroqConfig {
 }
 /**
  * Groq Provider
- * 兼容 OpenAI API 格式，支持 reasoning_effort 参数
+ * 兼容 OpenAI API 格式，支持 reasoning_format 参数
+ * 使用适配器模式重构，复用统一的工具层
  */
 declare class GroqProvider extends BaseProvider {
     readonly name = "groq";
-    private apiKey;
+    private adapter;
+    private client;
     private baseUrl;
     constructor(config: GroqConfig | string);
     /**
@@ -467,6 +595,7 @@ declare class GroqProvider extends BaseProvider {
 /**
  * Gemini Provider 实现
  * 使用 Google Gemini API (OpenAI 兼容格式)
+ * 使用 GeminiAdapter 和 HttpProviderClient 进行重构
  * https://ai.google.dev/gemini-api/docs/openai
  */
 
@@ -480,10 +609,12 @@ interface GeminiConfig {
 /**
  * Gemini Provider
  * 使用 Google Gemini API，兼容 OpenAI 格式
+ * 使用适配器模式重构，复用统一的工具层
  */
 declare class GeminiProvider extends BaseProvider {
     readonly name = "gemini";
-    private apiKey;
+    private adapter;
+    private client;
     private baseUrl;
     constructor(config: GeminiConfig | string);
     /**
@@ -496,4 +627,1503 @@ declare class GeminiProvider extends BaseProvider {
     chatStream(options: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
 }
 
-export { type AIProvider, BaseProvider, type ChatMessage, type ChatOptions, type ChatResult, EFFORT_TOKEN_MAP, GeminiProvider, GroqProvider, HuggingFaceProvider, type ModelInfo, type ModelPricing, ModelScopeProvider, type OpenRouterModelInfo, OpenRouterProvider, type ProviderConfig, type ProviderType, type ReasoningConfig, type ReasoningEffort, type StreamChunk, type TokenUsage, ai, createProvider };
+/**
+ * 流处理器 - 处理 SSE 流式响应
+ * 从各 Provider 中提取并统一的流处理逻辑
+ */
+
+/**
+ * Delta 提取器函数类型
+ * 从流式响应的 delta 中提取 StreamChunk
+ */
+type DeltaExtractor = (delta: Record<string, unknown>) => StreamChunk | null;
+/**
+ * 流处理器类
+ * 提供统一的 SSE 流式响应处理功能
+ */
+declare class StreamProcessor {
+    /**
+     * 从响应内容中提取文本
+     * 支持字符串和数组格式的 content
+     *
+     * @param content - 响应内容，可以是字符串、数组或其他类型
+     * @returns 提取的文本内容
+     *
+     * @example
+     * ```ts
+     * // 字符串格式
+     * StreamProcessor.extractTextContent('Hello') // => 'Hello'
+     *
+     * // 数组格式
+     * StreamProcessor.extractTextContent([
+     *   { type: 'text', text: 'Hello' },
+     *   { type: 'text', text: ' World' }
+     * ]) // => 'Hello World'
+     * ```
+     */
+    static extractTextContent(content: unknown): string;
+    /**
+     * 解析 SSE 数据行
+     *
+     * @param line - SSE 数据行（如 "data: {...}"）
+     * @returns 解析后的 JSON 对象，或 null（如果是 [DONE] 或无效数据）
+     *
+     * @example
+     * ```ts
+     * StreamProcessor.parseSSELine('data: {"content": "Hello"}')
+     * // => { content: 'Hello' }
+     *
+     * StreamProcessor.parseSSELine('data: [DONE]')
+     * // => null
+     * ```
+     */
+    static parseSSELine(line: string): Record<string, unknown> | null;
+    /**
+     * 创建流式响应处理器
+     * 处理 SSE 格式的流式响应，提取并生成 StreamChunk
+     *
+     * @param response - fetch Response 对象
+     * @param deltaExtractor - 从 delta 中提取 StreamChunk 的函数
+     * @returns AsyncGenerator<StreamChunk>
+     *
+     * @example
+     * ```ts
+     * const response = await fetch(url, { ... });
+     * const extractor = (delta) => {
+     *   if (delta.content) {
+     *     return { type: 'content', text: delta.content };
+     *   }
+     *   return null;
+     * };
+     *
+     * for await (const chunk of StreamProcessor.processStream(response, extractor)) {
+     *   console.log(chunk.type, chunk.text);
+     * }
+     * ```
+     */
+    static processStream(response: Response, deltaExtractor: DeltaExtractor): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * 创建默认的 delta 提取器
+     * 支持 reasoning_content、reasoning、thoughts 和 content 字段
+     *
+     * @returns DeltaExtractor 函数
+     */
+    static createDefaultExtractor(): DeltaExtractor;
+}
+
+/**
+ * 请求构建器 - 构建标准化的 API 请求
+ * 统一各 Provider 的请求参数构建逻辑
+ */
+
+/**
+ * 请求构建器类
+ * 提供统一的 API 请求参数构建功能
+ */
+declare class RequestBuilder {
+    /**
+     * 构建聊天请求的基础参数
+     * 生成标准化的 OpenAI 兼容格式请求体
+     *
+     * @param options - 聊天选项
+     * @param stream - 是否为流式请求
+     * @returns 请求体对象
+     *
+     * @example
+     * ```ts
+     * const body = RequestBuilder.buildChatBody({
+     *   model: 'gpt-4',
+     *   messages: [{ role: 'user', content: 'Hello' }],
+     *   temperature: 0.7
+     * });
+     * ```
+     */
+    static buildChatBody(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 OpenRouter 格式的 reasoning 参数
+     *
+     * @param config - 推理配置
+     * @returns OpenRouter 格式的 reasoning 参数，或 undefined
+     *
+     * @example
+     * ```ts
+     * const reasoning = RequestBuilder.buildOpenRouterReasoning({ effort: 'high' });
+     * // => { effort: 'high', max_tokens: 16384 }
+     * ```
+     */
+    static buildOpenRouterReasoning(config?: ReasoningConfig): Record<string, unknown> | undefined;
+    /**
+     * 构建 Gemini 格式的 reasoning 参数
+     * Gemini 2.5+ 模型使用 reasoning_effort 控制思考
+     *
+     * @param config - 推理配置
+     * @returns Gemini 格式的参数对象
+     *
+     * @example
+     * ```ts
+     * const params = RequestBuilder.buildGeminiReasoning({ effort: 'high' });
+     * // => { reasoning_effort: 'high' }
+     * ```
+     */
+    static buildGeminiReasoning(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 构建 Groq 格式的 reasoning 参数
+     * Groq 使用 reasoning_format 参数控制推理输出
+     *
+     * @param config - 推理配置
+     * @returns Groq 格式的参数对象
+     *
+     * @example
+     * ```ts
+     * const params = RequestBuilder.buildGroqReasoning({ effort: 'high' });
+     * // => { reasoning_format: 'parsed' }
+     * ```
+     */
+    static buildGroqReasoning(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 构建 DeepSeek 格式的 reasoning 参数
+     * DeepSeek 使用 thinking 参数启用思考模式
+     *
+     * @param config - 推理配置
+     * @returns DeepSeek 格式的参数对象
+     */
+    static buildDeepSeekReasoning(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 构建 Nova 格式的 reasoning 参数
+     * Nova 使用 reasoningConfig 控制 extended thinking
+     *
+     * @param config - 推理配置
+     * @returns Nova 格式的参数对象
+     */
+    static buildNovaReasoning(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 构建 HTTP 请求头
+     *
+     * @param apiKey - API 密钥
+     * @param additionalHeaders - 额外的请求头
+     * @returns 请求头对象
+     *
+     * @example
+     * ```ts
+     * const headers = RequestBuilder.buildHeaders('sk-xxx', {
+     *   'X-Custom-Header': 'value'
+     * });
+     * ```
+     */
+    static buildHeaders(apiKey: string, additionalHeaders?: Record<string, string>): Record<string, string>;
+}
+
+/**
+ * 配置验证器 - 验证 Provider 配置的有效性
+ */
+/**
+ * 验证错误
+ */
+interface ValidationError$1 {
+    /** 错误字段路径 */
+    field: string;
+    /** 错误消息 */
+    message: string;
+    /** 错误代码 */
+    code: string;
+}
+/**
+ * 验证结果
+ */
+interface ValidationResult {
+    /** 是否验证通过 */
+    valid: boolean;
+    /** 错误列表 */
+    errors: ValidationError$1[];
+}
+/**
+ * Provider 类型
+ */
+type ProviderType$1 = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek' | 'poe' | 'nova';
+/**
+ * 配置验证器类
+ * 提供 Provider 配置验证功能
+ */
+declare class ConfigValidator {
+    /**
+     * 验证 Provider 配置
+     *
+     * @param config - 要验证的配置对象
+     * @returns 验证结果
+     *
+     * @example
+     * ```ts
+     * const result = ConfigValidator.validate({
+     *   provider: 'openrouter',
+     *   credentials: { apiKey: 'sk-xxx' }
+     * });
+     *
+     * if (!result.valid) {
+     *   console.error(result.errors);
+     * }
+     * ```
+     */
+    static validate(config: unknown): ValidationResult;
+    /**
+     * 验证 API Key 格式
+     * 不同 Provider 可能有不同的 API Key 格式要求
+     *
+     * @param apiKey - API 密钥
+     * @param provider - Provider 类型
+     * @returns 验证结果
+     */
+    static validateApiKey(apiKey: string, provider: ProviderType$1): ValidationResult;
+    /**
+     * 验证 URL 格式
+     *
+     * @param url - 要验证的 URL
+     * @returns 验证结果
+     */
+    static validateUrl(url: unknown): ValidationResult;
+}
+
+/**
+ * 配置管理器
+ * 提供配置验证、默认值应用、环境变量替换等功能
+ */
+
+/**
+ * 配置管理器类
+ * 统一管理 Provider 配置的验证、转换和处理
+ */
+declare class ConfigManager {
+    /**
+     * 验证配置
+     * 检查配置是否符合 UnifiedProviderConfig 格式要求
+     *
+     * @param config - 要验证的配置对象
+     * @returns 验证结果
+     *
+     * @example
+     * ```ts
+     * const result = ConfigManager.validate({
+     *   provider: 'openrouter',
+     *   credentials: { apiKey: 'sk-xxx' }
+     * });
+     *
+     * if (!result.valid) {
+     *   console.error(result.errors);
+     * }
+     * ```
+     */
+    static validate(config: unknown): ValidationResult;
+    /**
+     * 应用默认值
+     * 为缺失的可选字段填充默认值
+     *
+     * @param config - 部分配置对象
+     * @returns 填充默认值后的完整配置
+     *
+     * @example
+     * ```ts
+     * const fullConfig = ConfigManager.applyDefaults({
+     *   provider: 'openrouter',
+     *   credentials: { apiKey: 'sk-xxx' }
+     * });
+     * // fullConfig.options.timeout === 30000
+     * // fullConfig.options.retries === 3
+     * ```
+     */
+    static applyDefaults(config: Partial<UnifiedProviderConfig>): UnifiedProviderConfig;
+    /**
+     * 合并环境变量
+     * 将 ${ENV_VAR} 格式的占位符替换为实际环境变量值
+     *
+     * @param config - 包含环境变量占位符的配置
+     * @returns 替换后的配置
+     *
+     * @example
+     * ```ts
+     * // 假设 process.env.OPENROUTER_API_KEY = 'sk-xxx'
+     * const config = ConfigManager.mergeWithEnv({
+     *   provider: 'openrouter',
+     *   credentials: { apiKey: '${OPENROUTER_API_KEY}' }
+     * });
+     * // config.credentials.apiKey === 'sk-xxx'
+     * ```
+     */
+    static mergeWithEnv(config: UnifiedProviderConfig): UnifiedProviderConfig;
+    /**
+     * 替换字符串中的环境变量占位符
+     * 支持 ${ENV_VAR} 格式
+     *
+     * @param str - 包含占位符的字符串
+     * @returns 替换后的字符串
+     */
+    private static replaceEnvPlaceholders;
+    /**
+     * 从旧格式配置转换为新格式
+     * 保持向后兼容性
+     *
+     * @param config - 旧格式的 Provider 配置
+     * @returns 新格式的统一配置
+     *
+     * @example
+     * ```ts
+     * const newConfig = ConfigManager.fromLegacyConfig({
+     *   provider: 'openrouter',
+     *   apiKey: 'sk-xxx',
+     *   baseUrl: 'https://api.example.com'
+     * });
+     * // newConfig.credentials.apiKey === 'sk-xxx'
+     * // newConfig.credentials.baseUrl === 'https://api.example.com'
+     * ```
+     */
+    static fromLegacyConfig(config: LegacyProviderConfig): UnifiedProviderConfig;
+    /**
+     * 检查配置是否为旧格式
+     *
+     * @param config - 要检查的配置对象
+     * @returns 是否为旧格式
+     */
+    static isLegacyConfig(config: unknown): config is LegacyProviderConfig;
+    /**
+     * 智能转换配置
+     * 自动检测配置格式并转换为统一格式
+     *
+     * @param config - 任意格式的配置
+     * @returns 统一格式的配置
+     */
+    static normalize(config: LegacyProviderConfig | Partial<UnifiedProviderConfig>): UnifiedProviderConfig;
+    /**
+     * 获取指定 Provider 的默认基础 URL
+     *
+     * @param provider - Provider 类型
+     * @returns 默认基础 URL
+     */
+    static getDefaultBaseUrl(provider: ProviderType$2): string;
+}
+
+/**
+ * Provider 客户端层类型定义
+ * 定义执行 HTTP 请求的客户端接口
+ */
+/**
+ * Provider 客户端配置
+ */
+interface ProviderClientConfig {
+    /** API 密钥 */
+    apiKey: string;
+    /** 基础 URL */
+    baseUrl: string;
+    /** 请求超时时间（毫秒） */
+    timeout?: number;
+    /** 额外的请求头 */
+    headers?: Record<string, string>;
+}
+/**
+ * Provider 客户端接口
+ * 定义执行 HTTP 请求的统一接口
+ */
+interface ProviderClient {
+    /**
+     * 发送聊天请求（非流式）
+     *
+     * @param endpoint - API 端点路径
+     * @param body - 请求体
+     * @returns 响应数据
+     * @throws ProviderError 当请求失败时
+     */
+    chat(endpoint: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * 发送流式聊天请求
+     *
+     * @param endpoint - API 端点路径
+     * @param body - 请求体
+     * @returns fetch Response 对象，用于流式处理
+     * @throws ProviderError 当请求失败时
+     */
+    chatStream(endpoint: string, body: Record<string, unknown>): Promise<Response>;
+}
+/**
+ * Provider 错误基类
+ */
+declare class ProviderError extends Error {
+    readonly code: string;
+    readonly provider: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, provider: string, cause?: Error | undefined);
+}
+/**
+ * API 错误
+ * 用于 HTTP 请求失败的情况
+ */
+declare class APIError extends ProviderError {
+    readonly statusCode: number;
+    readonly responseBody?: string | undefined;
+    constructor(message: string, provider: string, statusCode: number, responseBody?: string | undefined);
+}
+/**
+ * 网络错误
+ * 用于网络连接失败的情况
+ */
+declare class NetworkError extends ProviderError {
+    constructor(message: string, provider: string, cause?: Error);
+}
+/**
+ * 超时错误
+ * 用于请求超时的情况
+ */
+declare class TimeoutError extends ProviderError {
+    readonly timeoutMs: number;
+    constructor(message: string, provider: string, timeoutMs: number);
+}
+
+/**
+ * HTTP Provider 客户端实现
+ * 提供基于 fetch 的 HTTP 请求功能
+ */
+
+/**
+ * HTTP Provider 客户端
+ * 实现 ProviderClient 接口，提供统一的 HTTP 请求功能
+ */
+declare class HttpProviderClient implements ProviderClient {
+    private readonly config;
+    /**
+     * 创建 HTTP Provider 客户端实例
+     *
+     * @param config - 客户端配置
+     *
+     * @example
+     * ```ts
+     * const client = new HttpProviderClient({
+     *   apiKey: 'sk-xxx',
+     *   baseUrl: 'https://api.openai.com/v1',
+     *   timeout: 60000
+     * });
+     * ```
+     */
+    constructor(config: ProviderClientConfig);
+    /**
+     * 获取 Provider 名称（从 baseUrl 推断）
+     */
+    private getProviderName;
+    /**
+     * 构建完整的请求 URL
+     */
+    private buildUrl;
+    /**
+     * 构建请求头
+     */
+    private buildHeaders;
+    /**
+     * 创建带超时的 AbortController
+     */
+    private createAbortController;
+    /**
+     * 处理 HTTP 错误响应
+     */
+    private handleErrorResponse;
+    /**
+     * 发送聊天请求（非流式）
+     *
+     * @param endpoint - API 端点路径
+     * @param body - 请求体
+     * @returns 响应数据
+     */
+    chat(endpoint: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * 发送流式聊天请求
+     *
+     * @param endpoint - API 端点路径
+     * @param body - 请求体
+     * @returns fetch Response 对象
+     */
+    chatStream(endpoint: string, body: Record<string, unknown>): Promise<Response>;
+}
+
+/**
+ * Provider 适配器层类型定义
+ * 定义所有 Provider 适配器必须实现的接口
+ */
+
+/**
+ * Provider 类型枚举
+ * 支持的所有 Provider 类型
+ */
+type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek' | 'poe' | 'nova';
+/**
+ * 适配器配置
+ * 用于创建适配器实例时的配置
+ */
+interface AdapterConfig {
+    /** API 密钥 */
+    apiKey: string;
+    /** 基础 URL（可选，使用默认值） */
+    baseUrl?: string;
+    /** 额外的请求头 */
+    headers?: Record<string, string>;
+    /** 请求超时时间（毫秒） */
+    timeout?: number;
+}
+/**
+ * Provider 适配器接口
+ * 每个 Provider 实现一个适配器，负责将 Provider 特定的 API 适配为统一接口
+ *
+ * 适配器的职责：
+ * 1. 构建 Provider 特定的请求格式
+ * 2. 解析 Provider 特定的响应格式
+ * 3. 处理 Provider 特定的 reasoning 参数
+ * 4. 提供 API 端点 URL
+ */
+interface ProviderAdapter {
+    /**
+     * 适配器名称（与 ProviderType 对应）
+     */
+    readonly name: ProviderType;
+    /**
+     * Provider 的默认基础 URL
+     */
+    readonly defaultBaseUrl: string;
+    /**
+     * 创建 Provider 客户端
+     *
+     * @param config - 客户端配置
+     * @returns ProviderClient 实例
+     */
+    createClient(config: ProviderClientConfig): ProviderClient;
+    /**
+     * 构建聊天请求体
+     * 将统一的 ChatOptions 转换为 Provider 特定的请求格式
+     *
+     * @param options - 聊天选项
+     * @param stream - 是否为流式请求
+     * @returns Provider 特定格式的请求体
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 Provider 特定的 reasoning 参数
+     *
+     * @param config - 推理配置
+     * @returns Provider 特定格式的 reasoning 参数
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 解析聊天响应
+     * 将 Provider 特定的响应格式转换为统一的 ChatResult
+     *
+     * @param response - Provider 返回的原始响应
+     * @param model - 请求使用的模型
+     * @returns 统一格式的 ChatResult
+     */
+    parseChatResponse(response: Record<string, unknown>, model: string): ChatResult;
+    /**
+     * 从流式响应的 delta 中提取 StreamChunk
+     *
+     * @param delta - 流式响应中的 delta 对象
+     * @returns StreamChunk 或 null（如果无法提取）
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     *
+     * @param baseUrl - 基础 URL
+     * @returns 完整的 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+/**
+ * 基础适配器抽象类
+ * 提供通用的默认实现，子类可以覆盖特定方法
+ */
+declare abstract class BaseAdapter implements ProviderAdapter {
+    abstract readonly name: ProviderType;
+    abstract readonly defaultBaseUrl: string;
+    /**
+     * 创建 Provider 客户端
+     * 默认实现：需要在运行时导入 HttpProviderClient 以避免循环依赖
+     */
+    createClient(config: ProviderClientConfig): ProviderClient;
+    /**
+     * 构建聊天请求体
+     * 默认实现：构建 OpenAI 兼容格式的请求体
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 reasoning 参数
+     * 默认实现：返回空对象，子类应覆盖此方法
+     */
+    buildReasoningParams(_config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 解析聊天响应
+     * 默认实现：解析 OpenAI 兼容格式的响应
+     */
+    parseChatResponse(response: Record<string, unknown>, model: string): ChatResult;
+    /**
+     * 从 delta 中提取 StreamChunk
+     * 默认实现：支持 reasoning_content、reasoning、thoughts 和 content 字段
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     * 默认实现：返回 /chat/completions 端点
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * Provider 注册表
+ * 管理所有已注册的 Provider 适配器
+ *
+ * 职责：
+ * 1. 注册和管理 Provider 适配器
+ * 2. 提供适配器的获取和查询功能
+ * 3. 支持从配置文件加载 Provider
+ * 4. 自动初始化内置 Provider
+ */
+
+/**
+ * 注册表错误
+ * 当 Provider 未注册或注册失败时抛出
+ */
+declare class RegistryError extends Error {
+    readonly provider?: (ProviderType | string) | undefined;
+    readonly code: string;
+    constructor(message: string, provider?: (ProviderType | string) | undefined, code?: string);
+}
+/**
+ * Provider 注册表
+ * 管理所有已注册的 Provider 适配器
+ *
+ * @example
+ * ```typescript
+ * // 获取适配器
+ * const adapter = ProviderRegistry.getAdapter('openrouter');
+ *
+ * // 检查是否支持
+ * if (ProviderRegistry.hasAdapter('gemini')) {
+ *   // ...
+ * }
+ *
+ * // 列出所有支持的 Provider
+ * const supported = ProviderRegistry.listSupported();
+ *
+ * // 注册自定义适配器
+ * ProviderRegistry.register(myCustomAdapter);
+ * ```
+ */
+declare class ProviderRegistry {
+    /** 适配器映射表 */
+    private static adapters;
+    /** 是否已初始化内置适配器 */
+    private static initialized;
+    /**
+     * 注册 Provider 适配器
+     *
+     * @param adapter - 要注册的适配器实例
+     * @throws RegistryError 如果适配器无效
+     *
+     * @example
+     * ```typescript
+     * const myAdapter = new MyCustomAdapter();
+     * ProviderRegistry.register(myAdapter);
+     * ```
+     */
+    static register(adapter: ProviderAdapter): void;
+    /**
+     * 获取 Provider 适配器
+     *
+     * @param type - Provider 类型
+     * @returns 对应的适配器实例
+     * @throws RegistryError 如果 Provider 未注册
+     *
+     * @example
+     * ```typescript
+     * const adapter = ProviderRegistry.getAdapter('openrouter');
+     * const client = adapter.createClient(config);
+     * ```
+     */
+    static getAdapter(type: ProviderType | string): ProviderAdapter;
+    /**
+     * 检查 Provider 是否已注册
+     *
+     * @param type - Provider 类型
+     * @returns 是否已注册
+     *
+     * @example
+     * ```typescript
+     * if (ProviderRegistry.hasAdapter('gemini')) {
+     *   console.log('Gemini 已注册');
+     * }
+     * ```
+     */
+    static hasAdapter(type: ProviderType | string): boolean;
+    /**
+     * 获取所有已注册的 Provider 类型
+     *
+     * @returns Provider 类型数组
+     *
+     * @example
+     * ```typescript
+     * const providers = ProviderRegistry.listSupported();
+     * console.log('支持的 Provider:', providers);
+     * ```
+     */
+    static listSupported(): (ProviderType | string)[];
+    /**
+     * 从配置文件加载并注册 Provider
+     *
+     * @param config - 注册表配置
+     * @throws RegistryError 如果配置无效或加载失败
+     *
+     * @example
+     * ```typescript
+     * const config: RegistryConfig = {
+     *   providers: {
+     *     'custom-provider': {
+     *       adapter: './my-adapter',
+     *       config: {
+     *         apiKey: 'xxx',
+     *         baseUrl: 'https://api.example.com'
+     *       }
+     *     }
+     *   }
+     * };
+     * ProviderRegistry.loadFromConfig(config);
+     * ```
+     */
+    static loadFromConfig(config: RegistryConfig): void;
+    /**
+     * 初始化内置 Provider
+     * 在首次使用时自动调用
+     *
+     * @example
+     * ```typescript
+     * // 通常不需要手动调用，会在首次使用时自动初始化
+     * ProviderRegistry.initializeBuiltIn();
+     * ```
+     */
+    static initializeBuiltIn(): void;
+    /**
+     * 重置注册表（主要用于测试）
+     * 清除所有已注册的适配器并重置初始化状态
+     */
+    static reset(): void;
+    /**
+     * 获取适配器数量（主要用于测试）
+     *
+     * @returns 已注册的适配器数量
+     */
+    static get size(): number;
+}
+
+/**
+ * OpenRouter 适配器实现
+ * 将 OpenRouter API 适配为统一接口
+ *
+ * OpenRouter 特点：
+ * - 支持多种模型（Claude、GPT、Gemini 等）
+ * - 使用 reasoning 参数控制思考模式
+ * - 支持 effort 和 max_tokens 参数
+ */
+
+/**
+ * OpenRouter 适配器
+ * 实现 ProviderAdapter 接口，处理 OpenRouter 特定的 API 格式
+ */
+declare class OpenRouterAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://openrouter.ai/api/v1";
+    /**
+     * 构建聊天请求体
+     * OpenRouter 使用 OpenAI 兼容格式，但有特殊的 reasoning 参数
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 OpenRouter 格式的 reasoning 参数
+     *
+     * OpenRouter reasoning 参数格式：
+     * {
+     *   effort: 'low' | 'medium' | 'high',
+     *   max_tokens: number,
+     *   exclude: boolean
+     * }
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 获取 API 端点 URL
+     * OpenRouter 使用标准的 /chat/completions 端点
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * Gemini 适配器实现
+ * 将 Google Gemini API 适配为统一接口
+ *
+ * Gemini 特点：
+ * - 使用 OpenAI 兼容格式
+ * - Gemini 2.5+ 模型支持 reasoning_effort 参数
+ * - 思考内容通过 reasoning_content 或 thoughts 字段返回
+ */
+
+/**
+ * Gemini 适配器
+ * 实现 ProviderAdapter 接口，处理 Gemini 特定的 API 格式
+ */
+declare class GeminiAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://generativelanguage.googleapis.com/v1beta/openai";
+    /**
+     * 构建聊天请求体
+     * Gemini 使用 OpenAI 兼容格式，reasoning_effort 直接放在请求体中
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 Gemini 格式的 reasoning 参数
+     *
+     * Gemini 2.5+ 模型使用 reasoning_effort 参数：
+     * - 'low': 快速思考
+     * - 'medium': 平衡模式
+     * - 'high': 深度思考
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 从 delta 中提取 StreamChunk
+     * Gemini 可能使用 reasoning_content 或 thoughts 字段
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * Groq 适配器实现
+ * 将 Groq API 适配为统一接口
+ *
+ * Groq 特点：
+ * - 使用 OpenAI 兼容格式
+ * - 使用 reasoning_format 参数控制推理输出
+ * - 不能同时使用 include_reasoning 和 reasoning_format
+ * - 使用 max_completion_tokens 而不是 max_tokens
+ */
+
+/**
+ * Groq 适配器
+ * 实现 ProviderAdapter 接口，处理 Groq 特定的 API 格式
+ */
+declare class GroqAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://api.groq.com/openai/v1";
+    /**
+     * 构建聊天请求体
+     * Groq 使用 OpenAI 兼容格式，但有一些特殊参数
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 Groq 格式的 reasoning 参数
+     *
+     * Groq 使用 reasoning_format 参数：
+     * - 'raw': 原始格式
+     * - 'parsed': 解析格式（推荐）
+     *
+     * 注意：不能同时使用 include_reasoning 和 reasoning_format
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 从 delta 中提取 StreamChunk
+     * Groq 使用 reasoning_content 或 reasoning 字段
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * HuggingFace 适配器实现
+ * 将 HuggingFace Router API 适配为统一接口
+ *
+ * HuggingFace 特点：
+ * - 使用 OpenAI 兼容格式
+ * - 是模型聚合平台，thinking 支持取决于具体模型
+ * - 使用 reasoning_effort 参数（如果模型支持）
+ */
+
+/**
+ * HuggingFace 适配器
+ * 实现 ProviderAdapter 接口，处理 HuggingFace 特定的 API 格式
+ */
+declare class HuggingFaceAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://router.huggingface.co/v1";
+    /**
+     * 构建聊天请求体
+     * HuggingFace 使用标准 OpenAI 兼容格式
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 HuggingFace 格式的 reasoning 参数
+     * HuggingFace 使用 reasoning_effort 参数（取决于具体模型是否支持）
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 从 delta 中提取 StreamChunk
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * ModelScope 适配器实现
+ * 将 ModelScope API 适配为统一接口
+ *
+ * ModelScope 特点：
+ * - 使用 OpenAI 兼容格式
+ * - 使用 enable_thinking 参数控制思考模式
+ * - 支持 DeepSeek 等模型
+ */
+
+/**
+ * ModelScope 适配器
+ * 实现 ProviderAdapter 接口，处理 ModelScope 特定的 API 格式
+ */
+declare class ModelScopeAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://api-inference.modelscope.cn/v1";
+    /**
+     * 构建聊天请求体
+     * ModelScope 使用 OpenAI 兼容格式
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 ModelScope 格式的 reasoning 参数
+     * ModelScope 使用 enable_thinking 参数控制思考模式
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 从 delta 中提取 StreamChunk
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * DeepSeek 适配器实现
+ * 将 DeepSeek API 适配为统一接口
+ *
+ * DeepSeek 特点：
+ * - 使用 OpenAI 兼容格式
+ * - 使用 thinking 参数启用思考模式
+ * - deepseek-chat: 通用对话模型（可通过 thinking 参数启用思考）
+ * - deepseek-reasoner: 推理模型（自动启用思考）
+ */
+
+/**
+ * DeepSeek 适配器
+ * 实现 ProviderAdapter 接口，处理 DeepSeek 特定的 API 格式
+ */
+declare class DeepSeekAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://api.deepseek.com";
+    /**
+     * 构建聊天请求体
+     * DeepSeek 使用 OpenAI 兼容格式
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 DeepSeek 格式的 reasoning 参数
+     * DeepSeek 使用 thinking 参数启用思考模式
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 从 delta 中提取 StreamChunk
+     * DeepSeek R1 使用 reasoning_content 返回思考过程
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * Poe 适配器实现
+ * 将 Poe API 适配为统一接口
+ *
+ * Poe 特点：
+ * - 使用 OpenAI 兼容格式
+ * - 单一 API Key 访问数百个模型
+ * - 通过 extra_body 传递 reasoning_effort, thinking_budget 等参数
+ * - 支持 <think>...</think> 标签和 *Thinking...*\n> ... 格式的思考内容
+ */
+
+/**
+ * Poe 适配器
+ * 实现 ProviderAdapter 接口，处理 Poe 特定的 API 格式
+ */
+declare class PoeAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://api.poe.com/v1";
+    /**
+     * 构建聊天请求体
+     * Poe 使用 OpenAI 兼容格式，通过 extra_body 传递自定义参数
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 Poe 格式的 reasoning 参数
+     * Poe 通过 extra_body 传递 reasoning_effort 和 thinking_budget
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 解析聊天响应
+     * Poe 可能返回 reasoning_content，或者需要从 <think> 标签提取
+     */
+    parseChatResponse(response: Record<string, unknown>, model: string): ChatResult;
+    /**
+     * 从 delta 中提取 StreamChunk
+     * Poe 的流式响应处理比较复杂，需要处理多种思考格式
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * AWS Nova 适配器实现
+ * 将 Amazon Nova API 适配为统一接口
+ *
+ * Nova 特点：
+ * - 使用 OpenAI 兼容格式
+ * - Nova 2 Lite 支持 extended thinking (reasoningConfig)
+ * - effort 映射为 maxReasoningEffort: low/medium/high
+ * - temperature 范围是 0-1（不是 0-2）
+ */
+
+/**
+ * Nova 适配器
+ * 实现 ProviderAdapter 接口，处理 Nova 特定的 API 格式
+ */
+declare class NovaAdapter extends BaseAdapter {
+    readonly name: ProviderType;
+    readonly defaultBaseUrl = "https://api.nova.amazon.com/v1";
+    /**
+     * 构建聊天请求体
+     * Nova 使用 OpenAI 兼容格式
+     */
+    buildChatRequest(options: ChatOptions, stream?: boolean): Record<string, unknown>;
+    /**
+     * 构建 Nova 格式的 reasoning 参数
+     * Nova 使用 reasoningConfig 控制 extended thinking
+     */
+    buildReasoningParams(config?: ReasoningConfig): Record<string, unknown>;
+    /**
+     * 从 delta 中提取 StreamChunk
+     * Nova 返回 reasoning_content 作为思考过程
+     */
+    extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null;
+    /**
+     * 获取 API 端点 URL
+     */
+    getEndpointUrl(baseUrl: string): string;
+}
+
+/**
+ * 适配器层导出文件
+ * 导出所有 Provider 适配器和相关类型
+ */
+
+/**
+ * 创建所有内置适配器实例
+ * 用于 ProviderRegistry 初始化
+ */
+declare function createBuiltInAdapters(): Map<ProviderType, ProviderAdapter>;
+
+/**
+ * Fluent API 类型定义
+ * 提供链式调用和预设实例的类型支持
+ */
+
+/**
+ * 问答选项
+ * 用于配置单次 AI 调用的参数
+ */
+interface AskOptions {
+    /** 系统提示词 */
+    system?: string;
+    /** 温度参数 (0-2) */
+    temperature?: number;
+    /** 最大输出 token 数 */
+    maxTokens?: number;
+    /** 思考/推理配置 */
+    reasoning?: ReasoningConfig;
+}
+/**
+ * 流式回调函数
+ * 用于处理流式响应的各个阶段
+ */
+interface StreamCallbacks {
+    /** 收到思考内容时调用 */
+    onReasoning?: (text: string) => void;
+    /** 收到正式内容时调用 */
+    onContent?: (text: string) => void;
+    /** 完成时调用，包含完整的思考和内容 */
+    onDone?: (result: {
+        reasoning: string;
+        content: string;
+    }) => void;
+}
+/**
+ * 对话会话配置
+ * 用于创建多轮对话会话时的配置
+ */
+interface ChatSessionOptions {
+    /** 系统提示词 */
+    system?: string;
+    /** 温度参数 (0-2) */
+    temperature?: number;
+    /** 最大输出 token 数 */
+    maxTokens?: number;
+    /** 思考/推理配置 */
+    reasoning?: ReasoningConfig;
+}
+/**
+ * 多轮对话会话接口
+ * 自动维护对话历史，支持流式和非流式响应
+ */
+interface ChatSession {
+    /**
+     * 发送消息并获取响应（非流式）
+     * @param message - 用户消息
+     * @returns 助手响应内容
+     */
+    send(message: string): Promise<string>;
+    /**
+     * 发送消息并获取流式响应
+     * @param message - 用户消息
+     * @returns 流式数据块生成器
+     */
+    sendStream(message: string): AsyncGenerator<StreamChunk>;
+    /**
+     * 获取对话历史
+     * @returns 按发送顺序排列的消息列表
+     */
+    getHistory(): ChatMessage[];
+    /**
+     * 清空对话历史
+     */
+    clearHistory(): void;
+}
+/**
+ * 构建器内部配置状态
+ * 存储链式调用过程中设置的所有参数
+ */
+interface BuilderConfig {
+    /** Provider 类型 */
+    provider?: ProviderType;
+    /** 模型 ID */
+    model?: string;
+    /** API Key */
+    apiKey?: string;
+    /** 基础 URL */
+    baseUrl?: string;
+    /** 系统提示词 */
+    system?: string;
+    /** 温度参数 (0-2) */
+    temperature?: number;
+    /** 最大输出 token 数 */
+    maxTokens?: number;
+    /** 思考/推理配置 */
+    reasoning?: ReasoningConfig;
+    /** 是否流式请求 */
+    isStream?: boolean;
+}
+/**
+ * 链式调用构建器接口
+ * 支持流畅的方法链配置请求参数
+ *
+ * @example
+ * ```typescript
+ * const answer = await oiiai
+ *   .use('deepseek')
+ *   .key('your-api-key')
+ *   .model('deepseek-chat')
+ *   .system('你是助手')
+ *   .ask('你好');
+ * ```
+ */
+interface OiiaiBuilder {
+    /**
+     * 选择服务提供商
+     * @param provider - Provider 类型
+     * @returns this 支持链式调用
+     */
+    use(provider: ProviderType): this;
+    /**
+     * 指定模型
+     * @param modelId - 模型 ID
+     * @returns this 支持链式调用
+     */
+    model(modelId: string): this;
+    /**
+     * 设置系统提示词
+     * @param prompt - 系统提示词
+     * @returns this 支持链式调用
+     */
+    system(prompt: string): this;
+    /**
+     * 设置温度参数
+     * @param value - 温度值 (0-2)
+     * @returns this 支持链式调用
+     */
+    temperature(value: number): this;
+    /**
+     * 设置最大输出 token 数
+     * @param value - token 数量
+     * @returns this 支持链式调用
+     */
+    maxTokens(value: number): this;
+    /**
+     * 配置思考/推理模式
+     * @param config - 推理配置
+     * @returns this 支持链式调用
+     */
+    reasoning(config: ReasoningConfig): this;
+    /**
+     * 设置 API Key
+     * @param apiKey - API Key
+     * @returns this 支持链式调用
+     */
+    key(apiKey: string): this;
+    /**
+     * 设置基础 URL
+     * @param url - 基础 URL
+     * @returns this 支持链式调用
+     */
+    baseUrl(url: string): this;
+    /**
+     * 标记为流式请求
+     * 调用后 ask() 将返回 AsyncGenerator
+     * @returns StreamBuilder 类型
+     */
+    stream(): StreamBuilder;
+    /**
+     * 执行请求（非流式）
+     * @param question - 问题
+     * @returns 响应内容
+     */
+    ask(question: string): Promise<string>;
+}
+/**
+ * 流式构建器接口
+ * 调用 stream() 后的构建器类型，ask() 返回 AsyncGenerator
+ */
+interface StreamBuilder extends Omit<OiiaiBuilder, 'ask' | 'stream'> {
+    /**
+     * 执行流式请求
+     * @param question - 问题
+     * @returns 流式数据块生成器
+     */
+    ask(question: string): AsyncGenerator<StreamChunk>;
+}
+/**
+ * 预设实例配置选项
+ * 用于配置预设实例的 API Key 和基础 URL
+ */
+interface PresetConfigOptions {
+    /** API Key */
+    apiKey: string;
+    /** 基础 URL（可选） */
+    baseUrl?: string;
+}
+/**
+ * 预设实例接口
+ * 提供快捷的 AI 调用方法，预配置了 Provider 类型
+ *
+ * @example
+ * ```typescript
+ * // 配置并使用
+ * deepseek.configure({ apiKey: 'your-key' });
+ * const answer = await deepseek.ask('deepseek-chat', '你好');
+ *
+ * // 流式响应
+ * for await (const chunk of deepseek.stream('deepseek-chat', '写首诗')) {
+ *   console.log(chunk.text);
+ * }
+ * ```
+ */
+interface PresetProvider {
+    /** Provider 名称 */
+    readonly name: ProviderType;
+    /**
+     * 配置 API Key 和其他选项
+     * @param options - 配置选项
+     * @returns this 支持链式调用
+     */
+    configure(options: PresetConfigOptions): this;
+    /**
+     * 从环境变量读取配置
+     * 环境变量名格式: {PROVIDER}_API_KEY (如 DEEPSEEK_API_KEY)
+     * @returns this 支持链式调用
+     */
+    fromEnv(): this;
+    /**
+     * 简单问答（非流式）
+     * @param model - 模型 ID
+     * @param question - 问题
+     * @param options - 可选配置
+     * @returns 响应内容
+     */
+    ask(model: string, question: string, options?: AskOptions): Promise<string>;
+    /**
+     * 流式问答
+     * @param model - 模型 ID
+     * @param question - 问题
+     * @param options - 可选配置
+     * @returns 流式数据块生成器
+     */
+    stream(model: string, question: string, options?: AskOptions): AsyncGenerator<StreamChunk>;
+    /**
+     * 带回调的流式问答
+     * @param model - 模型 ID
+     * @param question - 问题
+     * @param callbacks - 回调函数
+     * @returns Promise，完成时 resolve
+     */
+    streamWithCallbacks(model: string, question: string, callbacks: StreamCallbacks): Promise<void>;
+    /**
+     * 获取构建器（预配置 provider 和 model）
+     * @param model - 模型 ID
+     * @returns 预配置的构建器
+     */
+    builder(model: string): OiiaiBuilder;
+    /**
+     * 创建多轮对话会话
+     * @param model - 模型 ID
+     * @param options - 会话配置
+     * @returns 对话会话实例
+     */
+    chat(model: string, options?: ChatSessionOptions): ChatSession;
+}
+
+/**
+ * Fluent API 链式构建器实现
+ * 支持流畅的方法链配置请求参数
+ */
+
+/**
+ * 创建新的构建器实例
+ * @param initialConfig - 可选的初始配置
+ * @returns 构建器实例
+ */
+declare function createBuilder(initialConfig?: Partial<BuilderConfig>): OiiaiBuilder;
+/**
+ * 全局构建器入口
+ * 每次访问返回新实例，避免状态污染
+ */
+declare const oiiai: OiiaiBuilder;
+
+/**
+ * Fluent API 错误类定义
+ * 提供配置错误和验证错误的统一处理
+ */
+/**
+ * 配置错误
+ * 在调用 ask() 时验证配置是否完整
+ *
+ * @example
+ * ```typescript
+ * // 未配置 API Key
+ * throw new ConfigurationError('请先配置 API Key：调用 configure({ apiKey: \'xxx\' }) 或 fromEnv()');
+ *
+ * // 未调用 use()
+ * throw new ConfigurationError('请先调用 use(provider) 选择服务提供商');
+ * ```
+ */
+declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+/**
+ * 验证错误
+ * 在设置参数时验证参数是否有效
+ *
+ * @example
+ * ```typescript
+ * // temperature 超出范围
+ * throw new ValidationError('temperature 必须在 0-2 之间');
+ *
+ * // 无效的 Provider
+ * throw new ValidationError('不支持的 Provider: xxx，支持的 Provider: deepseek, openrouter, ...');
+ * ```
+ */
+declare class ValidationError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * 预设实例导出
+ * 提供所有 Provider 的预配置实例
+ *
+ * @example
+ * ```typescript
+ * import { deepseek, openrouter, gemini } from 'oiiai';
+ *
+ * // 配置并使用
+ * deepseek.configure({ apiKey: 'your-key' });
+ * const answer = await deepseek.ask('deepseek-chat', '你好');
+ *
+ * // 或从环境变量读取
+ * openrouter.fromEnv();
+ * const stream = openrouter.stream('gpt-4o', '写首诗');
+ * ```
+ */
+
+/**
+ * DeepSeek 预设实例
+ * 环境变量: DEEPSEEK_API_KEY
+ */
+declare const deepseek: PresetProvider;
+/**
+ * OpenRouter 预设实例
+ * 环境变量: OPENROUTER_API_KEY
+ */
+declare const openrouter: PresetProvider;
+/**
+ * Gemini 预设实例
+ * 环境变量: GEMINI_API_KEY
+ */
+declare const gemini: PresetProvider;
+/**
+ * Groq 预设实例
+ * 环境变量: GROQ_API_KEY
+ */
+declare const groq: PresetProvider;
+/**
+ * HuggingFace 预设实例
+ * 环境变量: HUGGINGFACE_API_KEY
+ */
+declare const huggingface: PresetProvider;
+/**
+ * ModelScope 预设实例
+ * 环境变量: MODELSCOPE_API_KEY
+ */
+declare const modelscope: PresetProvider;
+/**
+ * Poe 预设实例
+ * 环境变量: POE_API_KEY
+ */
+declare const poe: PresetProvider;
+/**
+ * Nova 预设实例
+ * 环境变量: NOVA_API_KEY
+ */
+declare const nova: PresetProvider;
+
+export { type AIProvider, APIError, type AdapterConfig, type AskOptions, BaseAdapter, BaseProvider, type BuilderConfig, CONFIG_DEFAULTS, type ChatMessage, type ChatOptions, type ChatResult, type ChatSession, type ChatSessionOptions, ConfigManager, ConfigValidator, ConfigurationError, DeepSeekAdapter, type DeltaExtractor, EFFORT_TOKEN_MAP, ValidationError as FluentValidationError, GeminiAdapter, GeminiProvider, GroqAdapter, GroqProvider, HttpProviderClient, HuggingFaceAdapter, HuggingFaceProvider, type LegacyProviderConfig, type ModelInfo, type ModelPricing, ModelScopeAdapter, ModelScopeProvider, NetworkError, NovaAdapter, type OiiaiBuilder, OpenRouterAdapter, type OpenRouterModelInfo, OpenRouterProvider, PoeAdapter, type PresetConfigOptions, type PresetProvider, type ProviderAdapter, type ProviderCapabilities, type ProviderClient, type ProviderClientConfig, type ProviderConfig, ProviderError, ProviderRegistry, type ProviderType$2 as ProviderType, type ReasoningConfig, type ReasoningEffort, type RegistryConfig, RegistryError, RequestBuilder, type StreamBuilder, type StreamCallbacks, type StreamChunk, StreamProcessor, TimeoutError, type TokenUsage, type UnifiedProviderConfig, VALID_PROVIDERS, type ValidationError$1 as ValidationError, type ValidationResult, ai, createBuilder, createBuiltInAdapters, createProvider, deepseek, gemini, groq, huggingface, modelscope, nova, oiiai, openrouter, poe };