mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-27 21:01:32 +08:00
docs: update AI SDK architecture and README for enhanced clarity and new features
- Revised AI SDK architecture diagram to reflect changes in component relationships, replacing PluginEngine with RuntimeExecutor. - Updated README to highlight core features, including a refined plugin system, improved architecture design, and new built-in plugins. - Added detailed examples for using built-in plugins and creating custom plugins, enhancing documentation for better usability. - Included future version roadmap and related resources for user reference.
This commit is contained in:
MyPrototypeWhat
parent
ef6be4a6f9
commit
c3a6456499
@ -93,7 +93,7 @@ graph TD
|
||||
Factory --> XAI
|
||||
Factory --> Others
|
||||
|
||||
PluginEngine --> AICore
|
||||
RuntimeExecutor --> AICore
|
||||
AICore --> streamText
|
||||
AICore --> generateText
|
||||
AICore --> streamObject
|
||||
@ -117,31 +117,44 @@ packages/aiCore/
|
||||
│ ├── core/ # 核心层 - 内部实现
|
||||
│ │ ├── models/ # 模型层 - 模型创建和配置
|
||||
│ │ │ ├── factory.ts # 模型工厂函数 ✅
|
||||
│ │ │ ├── ProviderCreator.ts # 提供商创建器 ✅
|
||||
│ │ │ ├── ModelCreator.ts # 模型创建器 ✅
|
||||
│ │ │ ├── ConfigManager.ts # 配置管理器 ✅
|
||||
│ │ │ ├── types.ts # 模型类型定义 ✅
|
||||
│ │ │ └── index.ts # 模型层导出 ✅
|
||||
│ │ ├── runtime/ # 运行时层 - 执行和用户API
|
||||
│ │ │ ├── executor.ts # 运行时执行器 ✅
|
||||
│ │ │ ├── plugin-engine.ts # 插件引擎 ✅
|
||||
│ │ │ ├── pluginEngine.ts # 插件引擎 ✅
|
||||
│ │ │ ├── types.ts # 运行时类型定义 ✅
|
||||
│ │ │ └── index.ts # 运行时导出 ✅
|
||||
│ │ ├── middleware/ # 中间件系统
|
||||
│ │ │ ├── ModelWrapper.ts # 模型包装器 ✅
|
||||
│ │ │ ├── wrapper.ts # 模型包装器 ✅
|
||||
│ │ │ ├── manager.ts # 中间件管理器 ✅
|
||||
│ │ │ ├── types.ts # 中间件类型 ✅
|
||||
│ │ │ └── index.ts # 中间件导出 ✅
|
||||
│ │ ├── plugins/ # 插件系统
|
||||
│ │ │ ├── types.ts # 插件类型定义 ✅
|
||||
│ │ │ ├── manager.ts # 插件管理器 ✅
|
||||
│ │ │ ├── built-in/ # 内置插件 ✅
|
||||
│ │ │ │ ├── logging.ts # 日志插件 ✅
|
||||
│ │ │ │ ├── webSearchPlugin/ # 网络搜索插件 ✅
|
||||
│ │ │ │ ├── toolUsePlugin/ # 工具使用插件 ✅
|
||||
│ │ │ │ └── index.ts # 内置插件导出 ✅
|
||||
│ │ │ ├── examples/ # 示例插件 ✅
|
||||
│ │ │ ├── README.md # 插件文档 ✅
|
||||
│ │ │ └── index.ts # 插件导出 ✅
|
||||
│ │ ├── providers/ # 提供商管理
|
||||
│ │ │ ├── registry.ts # 提供商注册表 ✅
|
||||
│ │ │ ├── factory.ts # 提供商工厂 ✅
|
||||
│ │ │ ├── creator.ts # 提供商创建器 ✅
|
||||
│ │ │ ├── types.ts # 提供商类型 ✅
|
||||
│ │ │ └── utils.ts # 工具函数 ✅
|
||||
│ │ │ ├── utils.ts # 工具函数 ✅
|
||||
│ │ │ └── index.ts # 提供商导出 ✅
|
||||
│ │ ├── options/ # 配置选项
|
||||
│ │ │ ├── factory.ts # 选项工厂 ✅
|
||||
│ │ │ ├── types.ts # 选项类型 ✅
|
||||
│ │ │ ├── xai.ts # xAI 选项 ✅
|
||||
│ │ │ ├── openrouter.ts # OpenRouter 选项 ✅
|
||||
│ │ │ ├── examples.ts # 示例配置 ✅
|
||||
│ │ │ └── index.ts # 选项导出 ✅
|
||||
│ │ └── index.ts # 核心层导出 ✅
|
||||
│ ├── types.ts # 全局类型定义 ✅
|
||||
│ └── index.ts # 包主入口文件 ✅
|
||||
|
||||
@ -1,6 +1,35 @@
|
||||
# @cherrystudio/ai-core
|
||||
|
||||
Cherry Studio AI Core 是一个基于 Vercel AI SDK 的统一 AI Provider 接口包。
|
||||
Cherry Studio AI Core 是一个基于 Vercel AI SDK 的统一 AI Provider 接口包，为 AI 应用提供强大的抽象层和插件化架构。
|
||||
|
||||
## ✨ 核心亮点
|
||||
|
||||
### 🏗️ 优雅的架构设计
|
||||
- **简化分层**：`models`（模型层）→ `runtime`（运行时层），清晰的职责分离
|
||||
- **函数式优先**：避免过度抽象，提供简洁直观的 API
|
||||
- **类型安全**：完整的 TypeScript 支持，直接复用 AI SDK 类型系统
|
||||
- **最小包装**：直接使用 AI SDK 的接口，避免重复定义和性能损耗
|
||||
|
||||
### 🔌 强大的插件系统
|
||||
- **生命周期钩子**：支持请求全生命周期的扩展点
|
||||
- **流转换支持**：基于 AI SDK 的 `experimental_transform` 实现流处理
|
||||
- **插件分类**：First、Sequential、Parallel 三种钩子类型，满足不同场景
|
||||
- **内置插件**：webSearch、logging、toolUse 等开箱即用的功能
|
||||
|
||||
### 🌐 统一多 Provider 接口
|
||||
- **扩展注册**：支持自定义 Provider 注册，无限扩展能力
|
||||
- **配置统一**：统一的配置接口，简化多 Provider 管理
|
||||
|
||||
### 🚀 多种使用方式
|
||||
- **函数式调用**：适合简单场景的直接函数调用
|
||||
- **执行器实例**：适合复杂场景的可复用执行器
|
||||
- **静态工厂**：便捷的静态创建方法
|
||||
- **原生兼容**：完全兼容 AI SDK 原生 Provider Registry
|
||||
|
||||
### 🔮 面向未来
|
||||
- **Agent 就绪**：为 OpenAI Agents SDK 集成预留架构空间
|
||||
- **模块化设计**：独立包结构，支持跨项目复用
|
||||
- **渐进式迁移**：可以逐步从现有 AI SDK 代码迁移
|
||||
|
||||
## 特性
|
||||
|
||||
@ -9,6 +38,10 @@ Cherry Studio AI Core 是一个基于 Vercel AI SDK 的统一 AI Provider 接口
|
||||
- 🛠️ TypeScript 支持
|
||||
- 📦 强大的插件系统
|
||||
- 🌍 内置webSearch(Openai,Google,Anthropic,xAI)
|
||||
- 🎯 多种使用模式（函数式/实例式/静态工厂）
|
||||
- 🔌 可扩展的 Provider 注册系统
|
||||
- 🧩 完整的中间件支持
|
||||
- 📊 插件统计和调试功能
|
||||
|
||||
## 支持的 Providers
|
||||
|
||||
@ -141,6 +174,114 @@ registerProvider({
|
||||
const mistralExecutor = AiCore.create('mistral', { apiKey: 'mistral-key' })
|
||||
```
|
||||
|
||||
## 🔌 插件系统
|
||||
|
||||
AI Core 提供了强大的插件系统，支持请求全生命周期的扩展。
|
||||
|
||||
### 内置插件
|
||||
|
||||
#### webSearchPlugin - 网络搜索插件
|
||||
为不同 AI Provider 提供统一的网络搜索能力：
|
||||
|
||||
```typescript
|
||||
import { webSearchPlugin } from '@cherrystudio/ai-core/built-in/plugins'
|
||||
|
||||
const executor = AiCore.create('openai', { apiKey: 'your-key' }, [
|
||||
webSearchPlugin({
|
||||
openai: { /* OpenAI 搜索配置 */ },
|
||||
anthropic: { maxUses: 5 },
|
||||
google: { /* Google 搜索配置 */ },
|
||||
xai: {
|
||||
mode: 'on',
|
||||
returnCitations: true,
|
||||
maxSearchResults: 5,
|
||||
sources: [{ type: 'web' }, { type: 'x' }, { type: 'news' }]
|
||||
}
|
||||
})
|
||||
])
|
||||
```
|
||||
|
||||
#### loggingPlugin - 日志插件
|
||||
提供详细的请求日志记录：
|
||||
|
||||
```typescript
|
||||
import { createLoggingPlugin } from '@cherrystudio/ai-core/built-in/plugins'
|
||||
|
||||
const executor = AiCore.create('openai', { apiKey: 'your-key' }, [
|
||||
createLoggingPlugin({
|
||||
logLevel: 'info',
|
||||
includeParams: true,
|
||||
includeResult: false
|
||||
})
|
||||
])
|
||||
```
|
||||
|
||||
#### promptToolUsePlugin - 提示工具使用插件
|
||||
为不支持原生 Function Call 的模型提供 prompt 方式的工具调用：
|
||||
|
||||
```typescript
|
||||
import { createPromptToolUsePlugin } from '@cherrystudio/ai-core/built-in/plugins'
|
||||
|
||||
// 对于不支持 function call 的模型
|
||||
const executor = AiCore.create('providerId', {
|
||||
apiKey: 'your-key',
|
||||
baseURL: 'https://your-model-endpoint'
|
||||
}, [
|
||||
createPromptToolUsePlugin({
|
||||
enabled: true,
|
||||
// 可选：自定义系统提示符构建
|
||||
buildSystemPrompt: (userPrompt, tools) => {
|
||||
return `${userPrompt}\n\nAvailable tools: ${Object.keys(tools).join(', ')}`
|
||||
}
|
||||
})
|
||||
])
|
||||
```
|
||||
|
||||
### 自定义插件
|
||||
|
||||
创建自定义插件非常简单：
|
||||
|
||||
```typescript
|
||||
import { definePlugin } from '@cherrystudio/ai-core'
|
||||
|
||||
const customPlugin = definePlugin({
|
||||
name: 'custom-plugin',
|
||||
enforce: 'pre', // 'pre' | 'post' | undefined
|
||||
|
||||
// 在请求开始时记录日志
|
||||
onRequestStart: async (context) => {
|
||||
console.log(`Starting request for model: ${context.modelId}`)
|
||||
},
|
||||
|
||||
// 转换请求参数
|
||||
transformParams: async (params, context) => {
|
||||
// 添加自定义系统消息
|
||||
if (params.messages) {
|
||||
params.messages.unshift({
|
||||
role: 'system',
|
||||
content: 'You are a helpful assistant.'
|
||||
})
|
||||
}
|
||||
return params
|
||||
},
|
||||
|
||||
// 处理响应结果
|
||||
transformResult: async (result, context) => {
|
||||
// 添加元数据
|
||||
if (result.text) {
|
||||
result.metadata = {
|
||||
processedAt: new Date().toISOString(),
|
||||
modelId: context.modelId
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
})
|
||||
|
||||
// 使用自定义插件
|
||||
const executor = AiCore.create('openai', { apiKey: 'your-key' }, [customPlugin])
|
||||
```
|
||||
|
||||
### 使用 AI SDK 原生 Provider 注册表
|
||||
|
||||
> https://ai-sdk.dev/docs/reference/ai-sdk-core/provider-registry
|
||||
@ -251,9 +392,25 @@ await client.streamObject({
|
||||
- **灵活性**：可以根据需要选择使用内建逻辑或自定义注册表
|
||||
- **兼容性**：完全兼容 AI SDK 的 `createProviderRegistry` API
|
||||
- **渐进式**：可以逐步迁移现有代码，无需一次性重构
|
||||
- **插件支持**：自定义注册表仍可享受 Cherry Studio 插件系统的部分功能
|
||||
- **插件支持**：自定义注册表仍可享受插件系统的部分功能
|
||||
- **最佳实践**：结合两种方式的优点，既有动态加载的性能优势，又有统一注册表的便利性
|
||||
|
||||
## License
|
||||
## 📚 相关资源
|
||||
|
||||
MIT
|
||||
- [Vercel AI SDK 文档](https://ai-sdk.dev/)
|
||||
- [Cherry Studio 项目](https://github.com/CherryHQ/cherry-studio)
|
||||
- [AI SDK Providers](https://ai-sdk.dev/providers/ai-sdk-providers)
|
||||
|
||||
## 未来版本
|
||||
- 🔮 多 Agent 编排
|
||||
- 🔮 可视化插件配置
|
||||
- 🔮 实时监控和分析
|
||||
- 🔮 云端插件同步
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - 详见 [LICENSE](https://github.com/CherryHQ/cherry-studio/blob/main/LICENSE) 文件
|
||||
|
||||
---
|
||||
|
||||
**Cherry Studio AI Core** - 让 AI 开发更简单、更强大、更灵活 🚀
|
||||
|
||||
Loading…
Reference in New Issue
Block a user