@weisiren000/oiiai 0.1.1 → 0.1.3

package/README.md

@@ -1,112 +1,165 @@
-# @weisiren000/oiiai
-
-统一的 AI Provider 接口封装，支持 OpenRouter、OpenAI、Anthropic 等多种 AI 服务。
-
-## 安装
-
-```bash
-npm install @weisiren000/oiiai
-```
-
-## 快速开始
-
-```typescript
-import { OpenRouterProvider } from '@weisiren000/oiiai';
-
-const ai = new OpenRouterProvider('your-api-key');
-
-// 简单问答
-const answer = await ai.ask('deepseek/deepseek-chat', '你好');
-
-// 带系统提示
-const response = await ai.askWithSystem(
-  'deepseek/deepseek-chat',
-  '你是一个有帮助的助手',
-  '介绍一下自己'
-);
-
-// 完整对话
-const result = await ai.chat({
-  model: 'deepseek/deepseek-chat',
-  messages: [
-    { role: 'system', content: '你是一个简洁的助手' },
-    { role: 'user', content: '1+1=?' }
-  ],
-  temperature: 0.7,
-  maxTokens: 100
-});
-
-console.log(result.content);
-console.log(result.usage);
-```
-
-## 流式输出
-
-```typescript
-for await (const chunk of ai.chatStream({
-  model: 'deepseek/deepseek-chat',
-  messages: [{ role: 'user', content: '写一首诗' }]
-})) {
-  if (chunk.type === 'content') {
-    process.stdout.write(chunk.text);
-  }
-}
-```
-
-## 思考模型 (Reasoning)
-
-支持 OpenAI o1/o3、DeepSeek R1、Claude 等思考模型：
-
-```typescript
-const result = await ai.chat({
-  model: 'deepseek/deepseek-r1',
-  messages: [{ role: 'user', content: '9.11 和 9.9 哪个大？' }],
-  reasoning: {
-    effort: 'high',        // OpenAI/Grok 风格
-    // maxTokens: 2000,    // Anthropic/Gemini 风格
-    // exclude: true,      // 不返回思考内容
-  }
-});
-
-console.log('思考过程:', result.reasoning);
-console.log('最终答案:', result.content);
-```
-
-## 统一接口
-
-所有 Provider 实现统一的 `AIProvider` 接口：
-
-```typescript
-interface AIProvider {
-  readonly name: string;
-  chat(options: ChatOptions): Promise<ChatResult>;
-  chatStream(options: ChatOptions): AsyncGenerator<StreamChunk>;
-  ask(model: string, question: string, options?): Promise<string>;
-  askWithSystem(model: string, systemPrompt: string, userMessage: string, options?): Promise<string>;
-  listModels?(): Promise<ModelInfo[]>;
-}
-```
-
-## 自定义 Provider
-
-继承 `BaseAIProvider` 实现自定义 Provider：
-
-```typescript
-import { BaseAIProvider, ChatOptions, ChatResult, StreamChunk } from '@weisiren000/oiiai';
-
-class MyProvider extends BaseAIProvider {
-  readonly name = 'my-provider';
-
-  async chat(options: ChatOptions): Promise<ChatResult> {
-    // 实现非流式请求
-  }
-
-  async *chatStream(options: ChatOptions): AsyncGenerator<StreamChunk> {
-    // 实现流式请求
-  }
-}
-```
-
-## License
-
-MIT
+<div align="center">
+
+# 🤖 @weisiren000/oiiai
+
+**统一的 AI Provider 接口封装库**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@weisiren000/oiiai?style=flat-square&color=CB3837&logo=npm)](https://www.npmjs.com/package/@weisiren000/oiiai)
+
+支持 **OpenRouter** · **Gemini** · **Groq** · **HuggingFace** · **ModelScope**
+
+[📖 详细文档](./docs/providers.md) · [🚀 快速开始](#快速开始) · [💡 示例](#使用示例)
+
+</div>
+
+---
+
+## ✨ 特性
+
+- 🔌 **统一接口** - 所有 Provider 使用相同 API，学会一个就会全部
+- 🧠 **Reasoning 支持** - 统一的思考模式配置，自动转换各 Provider 格式
+- 🌊 **流式输出** - 支持实时流式响应，区分思考/回答内容
+- 📦 **TypeScript** - 完整类型定义，开发体验友好
+- 🔧 **可扩展** - 轻松实现自定义 Provider
+
+## 📦 安装
+
+```bash
+npm install @weisiren000/oiiai
+```
+
+## 🚀 快速开始
+
+```typescript
+import { ai } from '@weisiren000/oiiai';
+
+// 创建 Provider（所有 Provider 使用方式完全一致）
+const openrouter = ai.openrouter('your-api-key');
+const gemini = ai.gemini('your-api-key');
+const groq = ai.groq('your-api-key');
+
+// 简单问答
+const answer = await openrouter.ask('openai/gpt-4o', '你好');
+```
+
+## 💡 使用示例
+
+### 简单问答
+
+```typescript
+const answer = await provider.ask('model-id', '什么是 TypeScript？');
+```
+
+### 带系统提示
+
+```typescript
+const answer = await provider.askWithSystem(
+  'model-id',
+  '你是一个专业的代码助手',
+  '如何定义 TypeScript 接口？'
+);
+```
+
+### 完整对话
+
+```typescript
+const result = await provider.chat({
+  model: 'model-id',
+  messages: [
+    { role: 'system', content: '你是一个友好的助手' },
+    { role: 'user', content: '你好！' },
+  ],
+  temperature: 0.7,
+  maxTokens: 1000,
+});
+
+console.log(result.content); // 回答内容
+console.log(result.usage); // Token 使用情况
+```
+
+### 流式输出
+
+```typescript
+for await (const chunk of provider.chatStream({
+  model: 'model-id',
+  messages: [{ role: 'user', content: '写一首诗' }],
+})) {
+  if (chunk.type === 'reasoning') {
+    process.stdout.write(`[思考] ${chunk.text}`);
+  } else {
+    process.stdout.write(chunk.text);
+  }
+}
+```
+
+### 思考模式 (Reasoning)
+
+```typescript
+const result = await provider.chat({
+  model: 'deepseek/deepseek-r1',
+  messages: [{ role: 'user', content: '9.11 和 9.9 哪个大？' }],
+  reasoning: {
+    effort: 'high', // 'off' | 'low' | 'medium' | 'high'
+  },
+});
+
+console.log('思考过程:', result.reasoning);
+console.log('最终答案:', result.content);
+```
+
+## 🔧 支持的 Provider
+
+| Provider      | 服务商        | Reasoning 参数               | 参考文档                                                               |
+| ------------- | ------------- | ---------------------------- | ---------------------------------------------------------------------- |
+| `openrouter`  | OpenRouter    | `reasoning.effort`           | [Docs](https://openrouter.ai/docs/requests)                            |
+| `gemini`      | Google Gemini | `reasoning_effort`           | [Docs](https://ai.google.dev/gemini-api/docs/text-generation)          |
+| `groq`        | Groq          | `reasoning_format: 'parsed'` | [Docs](https://console.groq.com/docs/reasoning)                        |
+| `huggingface` | HuggingFace   | 不支持                       | -                                                                      |
+| `modelscope`  | 魔搭社区      | `enable_thinking`            | [Docs](https://www.alibabacloud.com/help/en/model-studio/deepseek-api) |
+
+## 📝 常用模型
+
+```typescript
+// OpenRouter
+'openai/gpt-4o';
+'anthropic/claude-sonnet-4';
+'deepseek/deepseek-r1';
+
+// Gemini
+'gemini-2.5-flash';
+'gemini-2.5-pro';
+
+// Groq
+'llama-3.3-70b-versatile';
+'qwen/qwen3-32b';
+
+// ModelScope
+'deepseek-ai/DeepSeek-R1';
+'Qwen/Qwen2.5-72B-Instruct';
+```
+
+## 🛠️ 自定义 Provider
+
+```typescript
+import { BaseProvider } from '@weisiren000/oiiai';
+import type { ChatOptions, ChatResult, StreamChunk } from '@weisiren000/oiiai';
+
+class MyProvider extends BaseProvider {
+  readonly name = 'my-provider';
+
+  async chat(options: ChatOptions): Promise<ChatResult> {
+    // 实现非流式请求
+  }
+
+  async *chatStream(options: ChatOptions): AsyncGenerator<StreamChunk> {
+    // 实现流式请求
+  }
+}
+```
+
+## 📄 License
+
+MIT

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;
@@ -114,20 +150,70 @@ interface AIProvider {
  * AI Provider 基础抽象类
  * 提供一些通用实现，子类只需实现核心方法
  */
-declare abstract class ProviderBase implements AIProvider {
+declare abstract class BaseProvider implements AIProvider {
     abstract readonly name: string;
     abstract chat(options: ChatOptions): Promise<ChatResult>;
     abstract chatStream(options: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
     /**
      * 简单对话：单轮问答（默认实现）
+     * 对于思考模型，如果 content 为空则返回 reasoning
      */
     ask(model: string, question: string, options?: Omit<ChatOptions, 'model' | 'messages'>): Promise<string>;
     /**
      * 带系统提示的对话（默认实现）
+     * 对于思考模型，如果 content 为空则返回 reasoning
      */
     askWithSystem(model: string, systemPrompt: string, userMessage: string, options?: Omit<ChatOptions, 'model' | 'messages'>): Promise<string>;
 }
 
+/**
+ * 统一的 Provider 工厂
+ * 让所有 Provider 使用方式一致
+ */
+
+/**
+ * 支持的 Provider 类型
+ */
+type ProviderType = 'openrouter' | 'gemini' | 'groq' | 'huggingface' | 'modelscope' | 'deepseek';
+/**
+ * 统一的 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;
+};
+
 /**
  * OpenRouter Provider 实现
  */
@@ -152,7 +238,7 @@ interface OpenRouterModelInfo extends ModelInfo {
 /**
  * OpenRouter Provider
  */
-declare class OpenRouterProvider extends ProviderBase {
+declare class OpenRouterProvider extends BaseProvider {
     readonly name = "openrouter";
     private client;
     constructor(apiKey: string);
@@ -170,4 +256,129 @@ declare class OpenRouterProvider extends ProviderBase {
     listModels(): Promise<OpenRouterModelInfo[]>;
 }
 
-export { type AIProvider, type ChatMessage, type ChatOptions, type ChatResult, type ModelInfo, type ModelPricing, type OpenRouterModelInfo, OpenRouterProvider, ProviderBase, 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);
+    /**
+     * 发送聊天请求（非流式）
+     */
+    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 };