diff --git a/packages/aiCore/AI_SDK_ARCHITECTURE.md b/packages/aiCore/AI_SDK_ARCHITECTURE.md index e6316571d9..af644f71f1 100644 --- a/packages/aiCore/AI_SDK_ARCHITECTURE.md +++ b/packages/aiCore/AI_SDK_ARCHITECTURE.md @@ -3,21 +3,23 @@ ## 1. 架构设计理念 ### 1.1 设计目标 + - **统一接口**:使用 Vercel AI SDK 统一不同 AI Provider 的接口差异 - **动态导入**:通过动态导入实现按需加载,减少打包体积 - **最小包装**:直接使用 AI SDK 的类型和接口,避免重复定义 -- **中间件增强**:扩大中间件的介入范围,覆盖请求的全生命周期(规划中) +- **插件系统**:基于钩子的插件架构,支持请求全生命周期扩展 - **类型安全**:利用 TypeScript 和 AI SDK 的类型系统确保类型安全 - **轻量级**:专注核心功能,保持包的轻量和高效 - **包级独立**:作为独立包管理,便于复用和维护 ### 1.2 核心优势 + - **标准化**:AI SDK 提供统一的模型接口,减少适配工作 - **简化维护**:废弃复杂的 XxxApiClient,统一为工厂函数模式 - **更好的开发体验**:完整的 TypeScript 支持和丰富的生态系统 - **性能优化**:AI SDK 内置优化和最佳实践 - **模块化设计**:独立包结构,支持跨项目复用 -- **可扩展中间件**:支持在请求全生命周期中插入自定义逻辑 +- **可扩展插件**:基于钩子的插件系统,支持灵活的功能扩展和流转换 ## 2. 整体架构图 @@ -32,7 +34,7 @@ graph TD ApiClientFactory["ApiClientFactory (工厂类)"] UniversalClient["UniversalAiSdkClient (统一客户端)"] ProviderRegistry["Provider 注册表"] - MiddlewareChain["中间件链 (规划中)"] + PluginManager["插件管理器"] end subgraph "动态导入层" @@ -48,37 +50,33 @@ graph TD Others["其他 19+ Providers"] end - subgraph "中间件生态 (规划中)" - PreRequest["请求预处理"] - StreamTransform["流转换"] - PostProcess["后处理"] - ErrorHandle["错误处理"] - Logging["日志记录"] - Cache["缓存"] + subgraph "插件生态" + FirstHooks["First Hooks (resolveModel, loadTemplate)"] + SequentialHooks["Sequential Hooks (transformParams, transformResult)"] + ParallelHooks["Parallel Hooks (onRequestStart, onRequestEnd, onError)"] + StreamHooks["Stream Hooks (transformStream)"] end UI --> ApiClientFactory Components --> ApiClientFactory ApiClientFactory --> UniversalClient - UniversalClient --> MiddlewareChain - MiddlewareChain --> ProviderRegistry + UniversalClient --> PluginManager + PluginManager --> ProviderRegistry ProviderRegistry --> DynamicImport DynamicImport --> OpenAI DynamicImport --> Anthropic DynamicImport --> Google DynamicImport --> XAI DynamicImport --> Others - + UniversalClient --> AICore AICore --> streamText AICore --> generateText - - MiddlewareChain --> PreRequest - MiddlewareChain --> StreamTransform - MiddlewareChain --> PostProcess - MiddlewareChain --> ErrorHandle - MiddlewareChain --> Logging - MiddlewareChain --> Cache + + PluginManager --> FirstHooks + PluginManager --> SequentialHooks + PluginManager --> ParallelHooks + PluginManager --> StreamHooks ``` ## 3. 包结构设计 @@ -94,24 +92,14 @@ packages/aiCore/ │ ├── clients/ │ │ ├── UniversalAiSdkClient.ts # 统一AI SDK客户端 ✅ │ │ └── ApiClientFactory.ts # 客户端工厂 ✅ -│ ├── middleware/ # 中间件系统 (规划中) -│ │ ├── lifecycle/ # 生命周期中间件 -│ │ │ ├── PreRequestMiddleware.ts -│ │ │ ├── PostResponseMiddleware.ts -│ │ │ ├── ErrorHandlingMiddleware.ts -│ │ │ └── CacheMiddleware.ts -│ │ ├── core/ # 核心中间件 -│ │ │ ├── StreamProcessingMiddleware.ts -│ │ │ ├── RequestValidationMiddleware.ts -│ │ │ └── ResponseTransformMiddleware.ts -│ │ ├── feat/ # 特性中间件 -│ │ │ ├── ThinkingMiddleware.ts -│ │ │ ├── ToolCallMiddleware.ts -│ │ │ └── WebSearchMiddleware.ts -│ │ ├── builder.ts # 中间件构建器 -│ │ ├── composer.ts # 中间件组合器 -│ │ ├── register.ts # 中间件注册表 -│ │ └── types.ts # 中间件类型定义 +│ ├── middleware/ # 插件系统 ✅ +│ │ ├── types.ts # 插件类型定义 ✅ +│ │ ├── manager.ts # 插件管理器 ✅ +│ │ ├── examples/ # 示例插件 ✅ +│ │ │ ├── example-plugins.ts # 示例插件实现 ✅ +│ │ │ └── example-usage.ts # 使用示例 ✅ +│ │ ├── README.md # 插件系统文档 ✅ +│ │ └── index.ts # 插件模块入口 ✅ │ ├── services/ # 高级服务 (规划中) │ │ ├── AiCoreService.ts # 统一服务入口 │ │ ├── CompletionsService.ts # 文本生成服务 @@ -125,33 +113,10 @@ packages/aiCore/ ``` **图例:** + - ✅ 已实现 - 规划中:设计完成,待实现 -### 3.2 包配置 (package.json) - -```json -{ - "name": "@cherry-studio/ai-core", - "version": "1.0.0", - "description": "Cherry Studio AI Core - 基于 Vercel AI SDK 的统一 AI Provider 接口", - "main": "dist/index.js", - "types": "dist/index.d.ts", - "dependencies": { - "ai": "^4.3.16" - }, - "peerDependenciesMeta": { - "@ai-sdk/openai": { "optional": true }, - "@ai-sdk/anthropic": { "optional": true }, - "@ai-sdk/google": { "optional": true }, - "@ai-sdk/xai": { "optional": true } - }, - "keywords": [ - "ai", "sdk", "vercel-ai-sdk", "cherry-studio" - ] -} -``` - ## 4. 核心组件详解 ### 4.1 Provider 注册表 (`providers/registry.ts`) @@ -159,12 +124,14 @@ packages/aiCore/ 统一管理所有 AI Provider 的注册和动态导入。 **主要功能:** + - 动态导入 AI SDK providers - 提供统一的 Provider 创建接口 - 支持 19+ 官方 AI SDK providers - 类型安全的 Provider 配置 **核心 API:** + ```typescript export interface ProviderConfig { id: string @@ -182,6 +149,7 @@ export class AiProviderRegistry { ``` **支持的 Providers:** + - OpenAI, Anthropic, Google, XAI - Azure OpenAI, Amazon Bedrock, Google Vertex - Groq, Together.ai, Fireworks, DeepSeek @@ -193,12 +161,14 @@ export class AiProviderRegistry { 将不同 AI providers 包装为统一接口。 **主要功能:** + - 异步初始化和动态加载 - 统一的 stream() 和 generate() 方法 - 直接使用 AI SDK 的 streamText() 和 generateText() - 配置验证和错误处理 **核心 API:** + ```typescript export class UniversalAiSdkClient { async initialize(): Promise @@ -215,12 +185,14 @@ export class UniversalAiSdkClient { 统一创建和管理 AI SDK 客户端。 **主要功能:** + - 统一的客户端创建接口 - 智能缓存和复用机制 - 批量创建和健康检查 - 错误处理和重试 **核心 API:** + ```typescript export class ApiClientFactory { static async createAiSdkClient(providerId: string, options: any): Promise @@ -231,56 +203,83 @@ export class ApiClientFactory { } ``` -### 4.4 增强的中间件系统 (规划中) +### 4.4 钩子风格插件系统 ✅ -扩展中间件架构,支持请求全生命周期的介入。 +基于钩子机制的插件架构设计,提供灵活的扩展系统。 -**生命周期阶段:** -1. **Pre-Request**:请求预处理、参数验证、缓存检查 -2. **Request**:实际的 AI SDK 调用 -3. **Stream Processing**:流式响应处理、实时转换 -4. **Post-Response**:响应后处理、结果聚合 -5. **Error Handling**:错误处理、重试、降级 +**钩子类型:** -**中间件分类:** +1. **First Hooks**:执行到第一个有效结果就停止 +2. **Sequential Hooks**:按序链式执行,可变换数据 +3. **Parallel Hooks**:并发执行,用于副作用 +4. **Stream Hooks**:流转换,直接传递给 AI SDK -**生命周期中间件:** -- `PreRequestMiddleware`:请求前处理,参数验证、权限检查 -- `PostResponseMiddleware`:响应后处理,结果转换、统计记录 -- `ErrorHandlingMiddleware`:错误处理,重试机制、降级策略 -- `CacheMiddleware`:缓存中间件,请求缓存、结果缓存 +**优先级系统:** -**核心中间件:** -- `StreamProcessingMiddleware`:流式处理,chunk 转换、进度追踪 -- `RequestValidationMiddleware`:请求验证,schema 验证、安全检查 -- `ResponseTransformMiddleware`:响应转换,格式标准化、类型转换 +- `pre`:前置处理(-100 到 -1) +- `normal`:标准处理(0 到 99) +- `post`:后置处理(100 到 199) -**特性中间件:** -- `ThinkingMiddleware`:思考过程中间件,记录推理步骤 -- `ToolCallMiddleware`:工具调用中间件,函数调用处理 -- `WebSearchMiddleware`:网络搜索中间件,集成搜索功能 +**核心钩子:** + +**First Hooks (第一个有效结果):** + +- `resolveModel`:模型解析,返回第一个匹配的模型 +- `loadTemplate`:模板加载,返回第一个找到的模板 + +**Sequential Hooks (链式变换):** + +- `transformParams`:参数转换,依次变换请求参数 +- `transformResult`:结果转换,依次变换响应结果 + +**Parallel Hooks (并发副作用):** + +- `onRequestStart`:请求开始时触发 +- `onRequestEnd`:请求结束时触发 +- `onError`:错误发生时触发 + +**Stream Hooks (流转换):** + +- `transformStream`:流转换,返回 AI SDK 转换函数 + +**插件 API 设计:** -**中间件 API 设计:** ```typescript -export interface Middleware { +export interface Plugin { name: string - priority: number - execute(context: MiddlewareContext, next: () => Promise): Promise + enforce?: 'pre' | 'normal' | 'post' + + // First hooks - 执行到第一个有效结果 + resolveModel?(params: ResolveModelParams): Promise + loadTemplate?(params: LoadTemplateParams): Promise