@weisiren000/oiiai 0.1.3 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 oiiai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,9 +9,9 @@
 [![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**
+支持 **OpenRouter** · **Gemini** · **Groq** · **HuggingFace** · **ModelScope** · **DeepSeek** · **Poe** · **Nova**
 
-[📖 详细文档](./docs/providers.md) · [🚀 快速开始](#快速开始) · [💡 示例](#使用示例)
+[📖 详细文档](./docs/providers.md) · [🚀 快速开始](#快速开始) · [💡 示例](#使用示例) · [🔗 Fluent API](#-fluent-api-新)
 
 </div>
 
@@ -20,10 +20,13 @@
 ## ✨ 特性
 
 - 🔌 **统一接口** - 所有 Provider 使用相同 API，学会一个就会全部
+- 🎯 **Fluent API** - 全新链式调用和预设实例，极简代码完成 AI 调用
 - 🧠 **Reasoning 支持** - 统一的思考模式配置，自动转换各 Provider 格式
 - 🌊 **流式输出** - 支持实时流式响应，区分思考/回答内容
+- 💬 **多轮对话** - 内置对话会话管理，自动维护上下文
 - 📦 **TypeScript** - 完整类型定义，开发体验友好
 - 🔧 **可扩展** - 轻松实现自定义 Provider
+- 🧪 **智能模型检测** - 自动识别思考模型，智能降级处理
 
 ## 📦 安装
 
@@ -33,16 +36,188 @@ npm install @weisiren000/oiiai
 
 ## 🚀 快速开始
 
+### 方式一：Fluent API（推荐 ⭐）
+
+最简洁的使用方式，支持预设实例和链式调用：
+
 ```typescript
-import { ai } from '@weisiren000/oiiai';
+import { deepseek, openrouter, oiiai } from '@weisiren000/oiiai';
+
+// 🎯 预设实例 - 一行代码完成调用
+deepseek.configure({ apiKey: 'your-key' });
+const answer = await deepseek.ask('deepseek-chat', '你好');
+
+// 🔗 链式调用 - 灵活配置
+const answer = await oiiai
+  .use('deepseek')
+  .key('your-key')
+  .model('deepseek-chat')
+  .system('你是一个友好的助手')
+  .temperature(0.7)
+  .ask('你好');
+
+// 🌊 流式输出
+for await (const chunk of deepseek.stream('deepseek-chat', '写首诗')) {
+  process.stdout.write(chunk.text);
+}
+
+// 💬 多轮对话
+const chat = deepseek.chat('deepseek-chat');
+await chat.send('你好');
+await chat.send('继续上面的话题');
+```
+
+### 方式二：工厂函数
+
+传统方式，适合需要更多控制的场景：
+
+```typescript
+import { ai, createProvider } from '@weisiren000/oiiai';
+
+// 快捷工厂
+const provider = ai.deepseek('your-api-key');
+const answer = await provider.ask('deepseek-chat', '你好');
+
+// 完整配置
+const provider = createProvider({
+  provider: 'openrouter',
+  apiKey: 'your-api-key',
+  baseUrl: 'https://custom.openrouter.ai/api/v1', // 可选
+});
+```
+
+## 🎯 Fluent API（新）
+
+全新的 Fluent API 提供两种使用模式：
 
-// 创建 Provider（所有 Provider 使用方式完全一致）
-const openrouter = ai.openrouter('your-api-key');
-const gemini = ai.gemini('your-api-key');
-const groq = ai.groq('your-api-key');
+### 预设实例
+
+预配置的 Provider 实例，开箱即用：
+
+```typescript
+import { deepseek, openrouter, gemini, groq } from '@weisiren000/oiiai';
+
+// 配置 API Key（二选一）
+deepseek.configure({ apiKey: 'your-key' }); // 显式配置
+openrouter.fromEnv(); // 从环境变量读取 (OPENROUTER_API_KEY)
 
 // 简单问答
-const answer = await openrouter.ask('openai/gpt-4o', '你好');
+const answer = await deepseek.ask('deepseek-chat', '什么是 TypeScript？');
+
+// 带选项的问答
+const answer = await deepseek.ask('deepseek-chat', '解释量子计算', {
+  system: '你是一个科学家',
+  temperature: 0.7,
+  maxTokens: 1000,
+  reasoning: { effort: 'high' },
+});
+
+// 流式输出
+for await (const chunk of deepseek.stream('deepseek-chat', '写一首诗')) {
+  if (chunk.type === 'reasoning') {
+    console.log('[思考]', chunk.text);
+  } else {
+    process.stdout.write(chunk.text);
+  }
+}
+
+// 带回调的流式输出
+await deepseek.streamWithCallbacks('deepseek-chat', '分析这个问题', {
+  onReasoning: text => console.log('[思考]', text),
+  onContent: text => process.stdout.write(text),
+  onDone: result => console.log('\n完成！', result),
+});
+```
+
+### 链式构建器
+
+灵活的链式调用，精细控制每个参数：
+
+```typescript
+import { oiiai } from '@weisiren000/oiiai';
+
+// 基础用法
+const answer = await oiiai
+  .use('deepseek')
+  .key('your-key')
+  .model('deepseek-chat')
+  .ask('你好');
+
+// 完整配置
+const answer = await oiiai
+  .use('openrouter')
+  .key('your-key')
+  .model('anthropic/claude-sonnet-4')
+  .system('你是一个专业的代码助手')
+  .temperature(0.7)
+  .maxTokens(2000)
+  .reasoning({ effort: 'high' })
+  .ask('如何实现快速排序？');
+
+// 流式输出
+const stream = oiiai
+  .use('gemini')
+  .key('your-key')
+  .model('gemini-2.5-flash')
+  .stream()
+  .ask('写一个故事');
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.text);
+}
+```
+
+### 预设实例与构建器互转
+
+从简单开始，需要时再增加复杂度：
+
+```typescript
+import { deepseek } from '@weisiren000/oiiai';
+
+deepseek.configure({ apiKey: 'your-key' });
+
+// 从预设实例获取构建器
+const builder = deepseek.builder('deepseek-chat');
+
+// 继续链式配置
+const answer = await builder
+  .system('你是一个诗人')
+  .temperature(0.9)
+  .ask('写一首关于春天的诗');
+```
+
+### 多轮对话
+
+内置对话会话管理，自动维护上下文：
+
+```typescript
+import { deepseek } from '@weisiren000/oiiai';
+
+deepseek.configure({ apiKey: 'your-key' });
+
+// 创建对话会话
+const chat = deepseek.chat('deepseek-chat', {
+  system: '你是一个友好的助手',
+  temperature: 0.7,
+});
+
+// 多轮对话
+const reply1 = await chat.send('你好，我叫小明');
+console.log(reply1); // "你好小明！很高兴认识你..."
+
+const reply2 = await chat.send('我叫什么名字？');
+console.log(reply2); // "你叫小明..."
+
+// 流式对话
+for await (const chunk of chat.sendStream('给我讲个笑话')) {
+  process.stdout.write(chunk.text);
+}
+
+// 查看对话历史
+console.log(chat.getHistory());
+
+// 清空历史开始新对话
+chat.clearHistory();
 ```
 
 ## 💡 使用示例
@@ -112,17 +287,24 @@ 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) |
+| Provider      | 服务商        | Reasoning 参数               | 支持思考模型 | 环境变量              |
+| ------------- | ------------- | ---------------------------- | ------------ | --------------------- |
+| `deepseek`    | DeepSeek      | `thinking.type: 'enabled'`   | ✅           | `DEEPSEEK_API_KEY`    |
+| `openrouter`  | OpenRouter    | `reasoning.effort`           | ✅           | `OPENROUTER_API_KEY`  |
+| `gemini`      | Google Gemini | `reasoning_effort`           | ✅           | `GEMINI_API_KEY`      |
+| `groq`        | Groq          | `reasoning_format: 'parsed'` | ✅           | `GROQ_API_KEY`        |
+| `huggingface` | HuggingFace   | 取决于具体模型               | ⚠️ 部分模型  | `HUGGINGFACE_API_KEY` |
+| `modelscope`  | 魔搭社区      | `enable_thinking`            | ✅           | `MODELSCOPE_API_KEY`  |
+| `poe`         | Poe           | `reasoning_effort`           | ✅           | `POE_API_KEY`         |
+| `nova`        | AWS Nova      | `reasoningConfig.type`       | ✅           | `NOVA_API_KEY`        |
 
 ## 📝 常用模型
 
 ```typescript
+// DeepSeek
+'deepseek-chat'; // DeepSeek-V3 通用对话
+'deepseek-reasoner'; // DeepSeek-R1 推理模型
+
 // OpenRouter
 'openai/gpt-4o';
 'anthropic/claude-sonnet-4';
@@ -134,32 +316,182 @@ console.log('最终答案:', result.content);
 
 // Groq
 'llama-3.3-70b-versatile';
-'qwen/qwen3-32b';
+'mixtral-8x7b-32768';
 
-// ModelScope
-'deepseek-ai/DeepSeek-R1';
-'Qwen/Qwen2.5-72B-Instruct';
+// Poe (使用 bot 名称)
+'GPT-4o';
+'Claude-3.5-Sonnet';
+
+// AWS Nova
+'nova-2-lite-v1';
+'nova-2-v1';
+'nova-premier-v1';
 ```
 
-## 🛠️ 自定义 Provider
+## 🌍 环境变量
+
+推荐使用 `.env` 文件管理 API 密钥：
+
+```bash
+# .env
+DEEPSEEK_API_KEY=sk-xxx
+OPENROUTER_API_KEY=sk-or-xxx
+GEMINI_API_KEY=xxx
+GROQ_API_KEY=gsk_xxx
+HUGGINGFACE_API_KEY=hf_xxx
+MODELSCOPE_API_KEY=xxx
+POE_API_KEY=xxx
+NOVA_API_KEY=xxx
+```
+
+```typescript
+import 'dotenv/config';
+import { deepseek, openrouter } from '@weisiren000/oiiai';
+
+// 从环境变量读取配置
+deepseek.fromEnv();
+openrouter.fromEnv();
+
+const answer = await deepseek.ask('deepseek-chat', '你好');
+```
+
+## 🧪 高级用法
+
+### 智能模型检测与降级
+
+```typescript
+import { ModelDetection, detectByModelName } from '@weisiren000/oiiai';
+
+// 基于模型名称模式检测
+const characteristics = detectByModelName('deepseek-r1');
+console.log(characteristics.behavior); // 'thinking-first'
+
+// 自定义降级策略
+provider.configureFallback({
+  enabled: true,
+  returnReasoningAsContent: true,
+  extractConclusionFromReasoning: true,
+});
+```
+
+### 场景化问答
 
 ```typescript
-import { BaseProvider } from '@weisiren000/oiiai';
-import type { ChatOptions, ChatResult, StreamChunk } from '@weisiren000/oiiai';
+const answer = await provider.askWithScenario(
+  'deepseek-r1',
+  '证明勾股定理',
+  'math' // 'simple' | 'math' | 'reasoning' | 'fast'
+);
+```
+
+## 🛠️ 自定义 Provider
 
-class MyProvider extends BaseProvider {
+### 使用适配器模式（推荐）
+
+```typescript
+import {
+  BaseAdapter,
+  ProviderRegistry,
+  RequestBuilder,
+  StreamProcessor,
+} from '@weisiren000/oiiai';
+
+class MyAdapter extends BaseAdapter {
   readonly name = 'my-provider';
 
-  async chat(options: ChatOptions): Promise<ChatResult> {
-    // 实现非流式请求
+  getEndpointUrl(baseUrl: string): string {
+    return `${baseUrl}/v1/chat/completions`;
+  }
+
+  buildChatRequest(options: ChatOptions): Record<string, unknown> {
+    return RequestBuilder.buildChatBody(options);
+  }
+
+  parseChatResponse(
+    response: Record<string, unknown>,
+    model: string
+  ): ChatResult {
+    // 解析响应
+  }
+
+  extractStreamChunk(delta: Record<string, unknown>): StreamChunk | null {
+    // 提取流式数据块
   }
+}
+
+// 注册并使用
+ProviderRegistry.register(new MyAdapter());
+const provider = createProvider({ provider: 'my-provider', apiKey: 'xxx' });
+```
+
+## 🏗️ 架构概览
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  Fluent API (新)                         │
+│         预设实例 / 链式构建器 / 对话会话                  │
+├─────────────────────────────────────────────────────────┤
+│                    用户层 (API)                          │
+│              createProvider / ai 快捷函数                │
+├─────────────────────────────────────────────────────────┤
+│                   注册层 (Registry)                      │
+│                   ProviderRegistry                       │
+├─────────────────────────────────────────────────────────┤
+│                   适配器层 (Adapter)                     │
+│    OpenRouterAdapter / GeminiAdapter / GroqAdapter ...  │
+├─────────────────────────────────────────────────────────┤
+│                   客户端层 (Client)                      │
+│                  HttpProviderClient                      │
+├─────────────────────────────────────────────────────────┤
+│                    工具层 (Utils)                        │
+│     StreamProcessor / RequestBuilder / ConfigValidator   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## ❓ 故障排除
+
+### 常见问题
+
+**Q: 为什么某些思考模型返回的 `content` 为空？**
+A: 思考模型在低 token 限制下可能只输出 reasoning。启用智能降级策略或增加 `maxTokens` 即可解决。
+
+**Q: 如何自定义 API 地址？**
+A: 使用 `baseUrl` 参数：
+
+```typescript
+// Fluent API
+deepseek.configure({ apiKey: 'xxx', baseUrl: 'https://custom.api.com' });
 
-  async *chatStream(options: ChatOptions): AsyncGenerator<StreamChunk> {
-    // 实现流式请求
+// 或链式调用
+oiiai.use('deepseek').key('xxx').baseUrl('https://custom.api.com');
+```
+
+**Q: 流式输出中如何区分思考和回答？**
+A: 检查 `chunk.type`：`'reasoning'` 表示思考内容，`'content'` 表示最终回答。
+
+### 错误处理
+
+```typescript
+import { ConfigurationError, APIError } from '@weisiren000/oiiai';
+
+try {
+  const answer = await deepseek.ask('model', 'question');
+} catch (error) {
+  if (error instanceof ConfigurationError) {
+    console.error('配置错误:', error.message);
+  } else if (error instanceof APIError) {
+    console.error('API 错误:', error.message);
   }
 }
 ```
 
+## 📚 更多文档
+
+- [API 参考](./docs/API.md) - 完整的 API 文档
+- [Provider 指南](./docs/providers.md) - 各 Provider 详细说明
+- [快速上手指南](./docs/quickstart.md) - 新手入门教程
+- [贡献指南](./CONTRIBUTING.md) - 如何参与贡献
+
 ## 📄 License
 
 MIT