@weisiren000/oiiai 0.1.3 → 0.1.4

package/dist/index.d.mts

@@ -114,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 接口和基类
  */
@@ -145,25 +196,83 @@ 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>;
 }
 
 /**
@@ -174,7 +283,7 @@ declare abstract class BaseProvider implements AIProvider {
 /**
  * 支持的 Provider 类型
  */
-type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek';
+type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek' | 'poe' | 'nova';
 /**
  * 统一的 Provider 配置
  */
@@ -212,6 +321,8 @@ declare const ai: {
     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;
 };
 
 /**
@@ -310,6 +421,10 @@ declare class HuggingFaceProvider extends BaseProvider {
     constructor(config: HuggingFaceConfig | string);
     /**
      * 发送聊天请求（非流式）
+     *
+     * reasoning 参数说明：
+     * - HuggingFace 是模型聚合平台，thinking 支持取决于具体模型
+     * - 如果模型支持，会返回 reasoning_content
      */
     chat(options: ChatOptions): Promise<ChatResult>;
     /**

package/dist/index.d.ts

@@ -114,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 接口和基类
  */
@@ -145,25 +196,83 @@ 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>;
 }
 
 /**
@@ -174,7 +283,7 @@ declare abstract class BaseProvider implements AIProvider {
 /**
  * 支持的 Provider 类型
  */
-type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek';
+type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek' | 'poe' | 'nova';
 /**
  * 统一的 Provider 配置
  */
@@ -212,6 +321,8 @@ declare const ai: {
     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;
 };
 
 /**
@@ -310,6 +421,10 @@ declare class HuggingFaceProvider extends BaseProvider {
     constructor(config: HuggingFaceConfig | string);
     /**
      * 发送聊天请求（非流式）
+     *
+     * reasoning 参数说明：
+     * - HuggingFace 是模型聚合平台，thinking 支持取决于具体模型
+     * - 如果模型支持，会返回 reasoning_content
      */
     chat(options: ChatOptions): Promise<ChatResult>;
     /**