@weisiren000/oiiai 0.1.2 → 0.1.4

package/README.md

@@ -1,201 +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);
-  } else if (chunk.type === 'reasoning') {
-    // 思考过程
-    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 o1/o3, Grok
-    // maxTokens: 2000,    // Anthropic, Gemini, Qwen
-    // exclude: true,      // 不返回思考内容
-    // enabled: true,      // 显式启用
-  }
-});
-
-console.log('思考过程:', result.reasoning);
-console.log('最终答案:', result.content);
-```
-
-## API
-
-### AIProvider 接口
-
-所有 Provider 实现统一接口：
-
-```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[]>;
-}
-```
-
-### 类型定义
-
-```typescript
-interface ChatMessage {
-  role: 'system' | 'user' | 'assistant';
-  content: string;
-}
-
-interface ChatOptions {
-  model: string;
-  messages: ChatMessage[];
-  temperature?: number;
-  maxTokens?: number;
-  reasoning?: ReasoningConfig;
-}
-
-interface ChatResult {
-  content: string;
-  reasoning: string | null;
-  model: string;
-  usage: TokenUsage;
-  finishReason: string | null;
-}
-
-interface StreamChunk {
-  type: 'reasoning' | 'content';
-  text: string;
-}
-
-interface ReasoningConfig {
-  effort?: 'high' | 'medium' | 'low';
-  maxTokens?: number;
-  exclude?: boolean;
-  enabled?: boolean;
-}
-
-interface TokenUsage {
-  promptTokens: number;
-  completionTokens: number;
-  totalTokens: number;
-}
-```
-
-## ModelScope Provider
-
-```typescript
-import { ModelScopeProvider } from '@weisiren000/oiiai';
-
-const ai = new ModelScopeProvider('your-modelscope-token');
-
-// 流式输出（自动启用思考模式）
-for await (const chunk of ai.chatStream({
-  model: 'deepseek-ai/DeepSeek-V3.2',
-  messages: [{ role: 'user', content: '9.9和9.11谁大' }]
-})) {
-  if (chunk.type === 'reasoning') {
-    process.stdout.write(chunk.text);
-  } else {
-    process.stdout.write(chunk.text);
-  }
-}
-```
-
-## 自定义 Provider
-
-继承 `BaseProvider` 实现自定义 Provider：
-
-```typescript
-import { BaseProvider } from '@weisiren000/oiiai';
-import type { ChatOptions, ChatResult, StreamChunk } from '@weisiren000/oiiai';
-
-class MyProvider extends BaseProvider {
-  readonly name = 'my-provider';
-
-  constructor(apiKey: string) {
-    super();
-    // 初始化 SDK 客户端
-  }
-
-  async chat(options: ChatOptions): Promise<ChatResult> {
-    // 实现非流式请求
-  }
-
-  async *chatStream(options: ChatOptions): AsyncGenerator<StreamChunk> {
-    // 实现流式请求
-  }
-}
-```
-
-`BaseProvider` 已实现 `ask` 和 `askWithSystem` 的默认逻辑，子类只需实现 `chat` 和 `chatStream`。
-
-## 获取模型列表
-
-```typescript
-const models = await ai.listModels();
-
-for (const model of models) {
-  console.log(`${model.id}: ${model.name}`);
-  console.log(`  上下文长度: ${model.contextLength}`);
-  console.log(`  价格: $${model.pricing.prompt}/token (输入)`);
-}
-```
-
-## 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