@weisiren000/oiiai 0.1.2 → 0.1.4

package/dist/index.d.mts

@@ -6,20 +6,56 @@ interface ChatMessage {
     content: string;
 }
 /**
- * 思考/推理配置
- * - effort: OpenAI o1/o3, Grok 使用
- * - maxTokens: Anthropic Claude, Gemini, Qwen 使用
+ * 统一的思考努力程度
+ * - off: 关闭思考
+ * - low: 快速思考，适合简单问题
+ * - medium: 平衡模式（默认）
+ * - high: 深度思考，适合复杂问题
+ */
+type ReasoningEffort = 'off' | 'low' | 'medium' | 'high';
+/**
+ * 统一的思考/推理配置
+ *
+ * 只需设置 effort，库会自动转换为各 Provider 需要的格式：
+ * - OpenRouter: effort 参数
+ * - Gemini: reasoning_effort 参数
+ * - Groq: reasoning_effort 参数
+ * - ModelScope: enable_thinking 参数
+ *
+ * @example
+ * ```ts
+ * // 简单用法 - 只设置 effort
+ * { effort: 'high' }
+ *
+ * // 高级用法 - 精细控制
+ * { effort: 'high', budgetTokens: 8000 }
+ * ```
  */
 interface ReasoningConfig {
-    /** 思考努力程度 */
-    effort?: 'high' | 'medium' | 'low';
-    /** 思考最大 token 数 */
-    maxTokens?: number;
-    /** 是否在响应中排除思考内容 */
+    /**
+     * 思考努力程度（推荐使用）
+     * - 'off': 关闭思考
+     * - 'low': 快速思考
+     * - 'medium': 平衡模式
+     * - 'high': 深度思考
+     */
+    effort?: ReasoningEffort;
+    /**
+     * 思考 token 预算（可选，精细控制）
+     * 设置后会覆盖 effort 对应的默认值
+     * 仅部分 Provider 支持（OpenRouter）
+     */
+    budgetTokens?: number;
+    /**
+     * 是否在响应中排除思考内容
+     * 仅部分 Provider 支持（OpenRouter）
+     */
     exclude?: boolean;
-    /** 是否启用思考 */
-    enabled?: boolean;
 }
+/**
+ * effort 到 token 预算的默认映射
+ */
+declare const EFFORT_TOKEN_MAP: Record<ReasoningEffort, number>;
 interface ChatOptions {
     /** 模型 ID */
     model: string;
@@ -78,6 +114,57 @@ interface ModelInfo {
     supportedParameters: string[];
 }
 
+/**
+ * 模型特性自动检测与智能降级策略
+ *
+ * 解决问题：
+ * 1. 思考模型（thinking models）在低 token 限制下 content 为空
+ * 2. 模型聚合平台无法预知哪些是思考模型
+ * 3. 避免硬编码模型列表
+ *
+ * 策略：
+ * 1. 基于模型名称模式匹配（启发式检测）
+ * 2. 基于响应特征动态检测（运行时检测）
+ * 3. 智能降级：自动调整参数或提取有效内容
+ */
+
+/**
+ * 模型行为类型
+ */
+type ModelBehavior = 'thinking-first' | 'direct-answer' | 'hybrid' | 'unknown';
+/**
+ * 模型特性信息
+ */
+interface ModelCharacteristics {
+    /** 模型行为类型 */
+    behavior: ModelBehavior;
+    /** 是否支持 reasoning 参数 */
+    supportsReasoningConfig: boolean;
+    /** 推荐的最小 maxTokens（针对思考模型） */
+    recommendedMinTokens: number;
+    /** 检测置信度 0-1 */
+    confidence: number;
+    /** 检测来源 */
+    detectedBy: 'pattern' | 'runtime' | 'cache';
+}
+/**
+ * 降级策略配置
+ */
+interface FallbackConfig {
+    /** 是否启用自动降级 */
+    enabled: boolean;
+    /** 当 content 为空时，是否返回 reasoning */
+    returnReasoningAsContent: boolean;
+    /** 是否从 reasoning 中提取结论 */
+    extractConclusionFromReasoning: boolean;
+    /** 是否自动增加 maxTokens 重试 */
+    autoRetryWithMoreTokens: boolean;
+    /** 重试时的 token 增量 */
+    retryTokenIncrement: number;
+    /** 最大重试次数 */
+    maxRetries: number;
+}
+
 /**
  * AI Provider 接口和基类
  */
@@ -109,27 +196,135 @@ interface AIProvider {
      * 获取可用模型列表（可选实现）
      */
     listModels?(): Promise<ModelInfo[]>;
+    /**
+     * 获取模型特性信息（可选实现）
+     */
+    getModelCharacteristics?(modelId: string): ModelCharacteristics;
+}
+/**
+ * 扩展的 ask 选项，支持降级配置
+ */
+interface AskOptions extends Omit<ChatOptions, 'model' | 'messages'> {
+    /** 降级策略配置 */
+    fallback?: Partial<FallbackConfig>;
+    /** 是否自动调整参数以适应模型特性 */
+    autoAdjust?: boolean;
 }
 /**
  * AI Provider 基础抽象类
  * 提供一些通用实现，子类只需实现核心方法
+ *
+ * 特性：
+ * - 自动检测模型类型（思考模型 vs 直接回答模型）
+ * - 智能降级策略（content 为空时自动处理）
+ * - 参数自动调整（为思考模型增加 maxTokens）
  */
 declare abstract class BaseProvider implements AIProvider {
     abstract readonly name: string;
+    /** 降级策略配置 */
+    protected fallbackConfig: FallbackConfig;
+    /** 是否启用自动参数调整 */
+    protected autoAdjustEnabled: boolean;
     abstract chat(options: ChatOptions): Promise<ChatResult>;
     abstract chatStream(options: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * 配置降级策略
+     */
+    configureFallback(config: Partial<FallbackConfig>): this;
+    /**
+     * 启用/禁用自动参数调整
+     */
+    setAutoAdjust(enabled: boolean): this;
+    /**
+     * 获取模型特性信息
+     */
+    getModelCharacteristics(modelId: string): ModelCharacteristics;
+    /**
+     * 智能聊天：自动检测模型特性并应用降级策略
+     */
+    chatSmart(options: ChatOptions): Promise<ChatResult>;
     /**
      * 简单对话：单轮问答（默认实现）
-     * 对于思考模型，如果 content 为空则返回 reasoning
+     *
+     * 智能处理思考模型：
+     * 1. 自动检测模型类型
+     * 2. 为思考模型自动调整 maxTokens
+     * 3. 如果 content 为空，智能降级（提取结论或返回 reasoning）
      */
-    ask(model: string, question: string, options?: Omit<ChatOptions, 'model' | 'messages'>): Promise<string>;
+    ask(model: string, question: string, options?: AskOptions): Promise<string>;
     /**
      * 带系统提示的对话（默认实现）
-     * 对于思考模型，如果 content 为空则返回 reasoning
+     *
+     * 智能处理思考模型：
+     * 1. 自动检测模型类型
+     * 2. 为思考模型自动调整 maxTokens
+     * 3. 如果 content 为空，智能降级（提取结论或返回 reasoning）
      */
-    askWithSystem(model: string, systemPrompt: string, userMessage: string, options?: Omit<ChatOptions, 'model' | 'messages'>): Promise<string>;
+    askWithSystem(model: string, systemPrompt: string, userMessage: string, options?: AskOptions): Promise<string>;
+    /**
+     * 场景化问答：根据场景自动配置参数
+     *
+     * @param model 模型 ID
+     * @param question 问题
+     * @param scenario 场景类型
+     *   - 'simple': 简单问答（默认）
+     *   - 'math': 数学计算
+     *   - 'reasoning': 逻辑推理
+     *   - 'fast': 快速回答（关闭思考）
+     */
+    askWithScenario(model: string, question: string, scenario?: 'simple' | 'math' | 'reasoning' | 'fast', options?: AskOptions): Promise<string>;
 }
 
+/**
+ * 统一的 Provider 工厂
+ * 让所有 Provider 使用方式一致
+ */
+
+/**
+ * 支持的 Provider 类型
+ */
+type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek' | 'poe' | 'nova';
+/**
+ * 统一的 Provider 配置
+ */
+interface ProviderConfig {
+    /** Provider 类型 */
+    provider: ProviderType;
+    /** API Key */
+    apiKey: string;
+    /** 自定义 API 地址（可选） */
+    baseUrl?: string;
+}
+/**
+ * 创建 AI Provider 实例
+ *
+ * @example
+ * ```ts
+ * // 所有 Provider 使用相同方式创建
+ * const openrouter = createProvider({ provider: 'openrouter', apiKey: 'xxx' });
+ * const gemini = createProvider({ provider: 'gemini', apiKey: 'xxx' });
+ * const groq = createProvider({ provider: 'groq', apiKey: 'xxx' });
+ *
+ * // 之后使用方式完全一致
+ * const answer = await openrouter.ask('gpt-4o', '你好');
+ * const answer = await gemini.ask('gemini-2.5-flash', '你好');
+ * ```
+ */
+declare function createProvider(config: ProviderConfig): AIProvider;
+/**
+ * 快捷创建函数
+ */
+declare const ai: {
+    openrouter: (apiKey: string, baseUrl?: string) => AIProvider;
+    gemini: (apiKey: string, baseUrl?: string) => AIProvider;
+    groq: (apiKey: string, baseUrl?: string) => AIProvider;
+    huggingface: (apiKey: string, baseUrl?: string) => AIProvider;
+    modelscope: (apiKey: string, baseUrl?: string) => AIProvider;
+    deepseek: (apiKey: string, baseUrl?: string) => AIProvider;
+    poe: (apiKey: string, baseUrl?: string) => AIProvider;
+    nova: (apiKey: string, baseUrl?: string) => AIProvider;
+};
+
 /**
  * OpenRouter Provider 实现
  */
@@ -172,4 +367,133 @@ declare class OpenRouterProvider extends BaseProvider {
     listModels(): Promise<OpenRouterModelInfo[]>;
 }
 
-export { type AIProvider, BaseProvider, type ChatMessage, type ChatOptions, type ChatResult, type ModelInfo, type ModelPricing, type OpenRouterModelInfo, OpenRouterProvider, type ReasoningConfig, type StreamChunk, type TokenUsage };
+/**
+ * ModelScope Provider 实现
+ * 使用 OpenAI 兼容 API
+ */
+
+/**
+ * ModelScope Provider 配置
+ */
+interface ModelScopeConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * ModelScope Provider
+ * 兼容 OpenAI API 格式，支持 DeepSeek 等模型
+ */
+declare class ModelScopeProvider extends BaseProvider {
+    readonly name = "modelscope";
+    private apiKey;
+    private baseUrl;
+    constructor(config: ModelScopeConfig | string);
+    /**
+     * 发送聊天请求（非流式）
+     */
+    chat(options: ChatOptions): Promise<ChatResult>;
+    /**
+     * 发送流式聊天请求
+     */
+    chatStream(options: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
+}
+
+/**
+ * HuggingFace Provider 实现
+ * 使用 HuggingFace Router API (OpenAI 兼容)
+ */
+
+/**
+ * HuggingFace Provider 配置
+ */
+interface HuggingFaceConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * HuggingFace Provider
+ * 使用 HuggingFace Router，兼容 OpenAI API 格式
+ */
+declare class HuggingFaceProvider extends BaseProvider {
+    readonly name = "huggingface";
+    private apiKey;
+    private baseUrl;
+    constructor(config: HuggingFaceConfig | string);
+    /**
+     * 发送聊天请求（非流式）
+     *
+     * reasoning 参数说明：
+     * - HuggingFace 是模型聚合平台，thinking 支持取决于具体模型
+     * - 如果模型支持，会返回 reasoning_content
+     */
+    chat(options: ChatOptions): Promise<ChatResult>;
+    /**
+     * 发送流式聊天请求
+     */
+    chatStream(options: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
+}
+
+/**
+ * Groq Provider 实现
+ * 使用 Groq API (OpenAI 兼容)
+ */
+
+/**
+ * Groq Provider 配置
+ */
+interface GroqConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * Groq Provider
+ * 兼容 OpenAI API 格式，支持 reasoning_effort 参数
+ */
+declare class GroqProvider extends BaseProvider {
+    readonly name = "groq";
+    private apiKey;
+    private baseUrl;
+    constructor(config: GroqConfig | string);
+    /**
+     * 发送聊天请求（非流式）
+     */
+    chat(options: ChatOptions): Promise<ChatResult>;
+    /**
+     * 发送流式聊天请求
+     */
+    chatStream(options: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
+}
+
+/**
+ * Gemini Provider 实现
+ * 使用 Google Gemini API (OpenAI 兼容格式)
+ * https://ai.google.dev/gemini-api/docs/openai
+ */
+
+/**
+ * Gemini Provider 配置
+ */
+interface GeminiConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * Gemini Provider
+ * 使用 Google Gemini API，兼容 OpenAI 格式
+ */
+declare class GeminiProvider extends BaseProvider {
+    readonly name = "gemini";
+    private apiKey;
+    private baseUrl;
+    constructor(config: GeminiConfig | string);
+    /**
+     * 发送聊天请求（非流式）
+     */
+    chat(options: ChatOptions): Promise<ChatResult>;
+    /**
+     * 发送流式聊天请求
+     */
+    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 };