478 lines
14 KiB
Markdown
478 lines
14 KiB
Markdown
# Gemini SDK 开发提示词
|
||
|
||
## 项目概述
|
||
|
||
基于 `apps\desktop\src-tauri\src\infrastructure\gemini_service.rs` 的现有实现，创建一个独立的 Rust crate `gemini-sdk`，提供简洁易用的 Gemini AI 服务接口。
|
||
|
||
## 核心设计目标
|
||
|
||
1. **简化接口**: 提供统一的消息发送接口，支持文本+附件输入
|
||
2. **Agent 系统**: 支持多个 AI Agent，每个 Agent 有独立的 system prompt 和配置
|
||
3. **多轮对话**: 支持会话管理和历史记录
|
||
4. **类型安全**: 强类型设计，编译时错误检查
|
||
5. **易于集成**: 最小化外部依赖，易于在其他项目中使用
|
||
|
||
## 技术架构
|
||
|
||
### 依赖管理
|
||
```toml
|
||
[dependencies]
|
||
tokio = { version = "1.0", features = ["full"] }
|
||
reqwest = { version = "0.11", features = ["json", "multipart"] }
|
||
serde = { version = "1.0", features = ["derive"] }
|
||
serde_json = "1.0"
|
||
anyhow = "1.0"
|
||
uuid = { version = "1.0", features = ["v4"] }
|
||
chrono = { version = "0.4", features = ["serde"] }
|
||
base64 = "0.22"
|
||
rusqlite = { version = "0.31", features = ["bundled", "chrono"] }
|
||
```
|
||
|
||
### 核心数据结构
|
||
|
||
```rust
|
||
// SDK 主体
|
||
pub struct GeminiSDK {
|
||
service: GeminiService,
|
||
conversation_repo: Option<Arc<ConversationRepository>>,
|
||
agents: HashMap<String, Agent>,
|
||
}
|
||
|
||
// Agent 定义
|
||
pub struct Agent {
|
||
pub id: String,
|
||
pub name: String,
|
||
pub system_prompt: String,
|
||
pub config: AgentConfig,
|
||
pub created_at: DateTime<Utc>,
|
||
}
|
||
|
||
pub struct AgentConfig {
|
||
pub temperature: f32,
|
||
pub max_tokens: u32,
|
||
pub timeout: u64,
|
||
pub enable_conversation: bool,
|
||
}
|
||
|
||
// 消息结构
|
||
pub struct MessageRequest {
|
||
pub text: String,
|
||
pub attachments: Vec<Attachment>,
|
||
pub agent_id: Option<String>,
|
||
pub session_id: Option<String>,
|
||
pub config: Option<MessageConfig>,
|
||
}
|
||
|
||
pub struct MessageResponse {
|
||
pub content: String,
|
||
pub session_id: String,
|
||
pub message_id: Option<String>,
|
||
pub agent_id: Option<String>,
|
||
}
|
||
|
||
// 附件定义
|
||
pub struct Attachment {
|
||
pub path: String,
|
||
pub mime_type: Option<String>,
|
||
}
|
||
|
||
// 会话管理
|
||
pub struct ConversationSession {
|
||
pub session_id: String,
|
||
pub title: Option<String>,
|
||
pub created_at: DateTime<Utc>,
|
||
}
|
||
|
||
pub struct HistoryMessage {
|
||
pub role: MessageRole,
|
||
pub content: String,
|
||
pub timestamp: DateTime<Utc>,
|
||
pub attachments: Vec<String>,
|
||
}
|
||
```
|
||
|
||
## 核心功能接口
|
||
|
||
### 1. SDK 初始化
|
||
```rust
|
||
impl GeminiSDK {
|
||
// 基础初始化
|
||
pub fn new() -> Result<Self>;
|
||
|
||
// 支持多轮对话
|
||
pub fn with_conversation_support(db_path: Option<String>) -> Result<Self>;
|
||
|
||
// 自定义配置
|
||
pub fn with_config(config: GeminiConfig) -> Result<Self>;
|
||
}
|
||
```
|
||
|
||
### 2. 核心消息接口
|
||
```rust
|
||
impl GeminiSDK {
|
||
// 主要方法：发送消息+附件，获得回复
|
||
pub async fn send_message(&mut self, request: MessageRequest) -> Result<MessageResponse>;
|
||
}
|
||
```
|
||
|
||
### 3. Agent 管理
|
||
```rust
|
||
impl GeminiSDK {
|
||
// Agent CRUD
|
||
pub fn create_agent(&mut self, name: String, system_prompt: String, config: Option<AgentConfig>) -> Result<Agent>;
|
||
pub fn get_agent(&self, agent_id: &str) -> Option<&Agent>;
|
||
pub fn list_agents(&self) -> Vec<&Agent>;
|
||
pub fn update_agent(&mut self, agent_id: &str, name: Option<String>, system_prompt: Option<String>, config: Option<AgentConfig>) -> Result<()>;
|
||
pub fn delete_agent(&mut self, agent_id: &str) -> Result<()>;
|
||
|
||
// 预设 Agent
|
||
pub fn create_outfit_advisor_agent(&mut self) -> Result<Agent>;
|
||
pub fn create_video_analyst_agent(&mut self) -> Result<Agent>;
|
||
pub fn create_general_assistant_agent(&mut self) -> Result<Agent>;
|
||
}
|
||
```
|
||
|
||
### 4. 会话管理
|
||
```rust
|
||
impl GeminiSDK {
|
||
// 会话 CRUD
|
||
pub async fn create_session(&self, title: Option<String>) -> Result<ConversationSession>;
|
||
pub async fn get_session(&self, session_id: &str) -> Result<Option<ConversationSession>>;
|
||
pub async fn list_sessions(&self) -> Result<Vec<ConversationSession>>;
|
||
pub async fn delete_session(&self, session_id: &str) -> Result<()>;
|
||
|
||
// 历史记录
|
||
pub async fn get_conversation_history(&self, session_id: &str, limit: Option<u32>) -> Result<Vec<HistoryMessage>>;
|
||
pub async fn clear_conversation_history(&self, session_id: &str) -> Result<()>;
|
||
}
|
||
```
|
||
|
||
### 5. 便捷构造函数
|
||
```rust
|
||
impl Attachment {
|
||
pub fn new(path: impl Into<String>) -> Self;
|
||
pub fn with_mime_type(path: impl Into<String>, mime_type: impl Into<String>) -> Self;
|
||
}
|
||
|
||
impl MessageRequest {
|
||
pub fn text_only(text: impl Into<String>) -> Self;
|
||
pub fn with_attachments(text: impl Into<String>, attachments: Vec<Attachment>) -> Self;
|
||
pub fn with_agent(text: impl Into<String>, agent_id: impl Into<String>) -> Self;
|
||
}
|
||
```
|
||
|
||
## 实现要求
|
||
|
||
### 1. 文件结构
|
||
```
|
||
cargos/gemini-sdk/
|
||
├── Cargo.toml
|
||
├── src/
|
||
│ ├── lib.rs # 主入口
|
||
│ ├── sdk.rs # SDK 主体实现
|
||
│ ├── agent.rs # Agent 相关
|
||
│ ├── conversation.rs # 会话管理
|
||
│ ├── attachment.rs # 附件处理
|
||
│ ├── error.rs # 错误定义
|
||
│ └── presets/ # 预设 Agent
|
||
│ ├── mod.rs
|
||
│ ├── outfit_advisor.rs
|
||
│ ├── video_analyst.rs
|
||
│ └── general_assistant.rs
|
||
├── examples/
|
||
│ ├── basic_usage.rs
|
||
│ ├── agent_demo.rs
|
||
│ └── conversation_demo.rs
|
||
└── tests/
|
||
├── integration_tests.rs
|
||
└── agent_tests.rs
|
||
```
|
||
|
||
### 2. 核心实现逻辑
|
||
|
||
#### 消息发送流程
|
||
1. 检查是否指定 Agent，获取对应配置和 system prompt
|
||
2. 处理附件：根据文件类型选择上传(视频)或编码(图片)
|
||
3. 构建 Gemini API 请求，包含 system prompt
|
||
4. 如果启用会话，使用多轮对话模式；否则使用单轮模式
|
||
5. 调用底层 GeminiService 方法
|
||
6. 返回格式化的响应
|
||
|
||
#### Agent 系统
|
||
1. 内存中维护 Agent 映射表
|
||
2. 每个 Agent 包含独立的 system prompt 和配置
|
||
3. 提供预设的专业 Agent（穿搭顾问、视频分析师等）
|
||
4. 支持动态创建和管理自定义 Agent
|
||
|
||
#### 会话管理
|
||
1. 可选的 SQLite 数据库支持
|
||
2. 自动会话创建和历史记录保存
|
||
3. 支持会话标题和元数据管理
|
||
4. 历史消息检索和清理
|
||
|
||
### 3. 错误处理
|
||
```rust
|
||
#[derive(Debug, thiserror::Error)]
|
||
pub enum SDKError {
|
||
#[error("配置错误: {0}")]
|
||
Config(String),
|
||
|
||
#[error("Agent 不存在: {0}")]
|
||
AgentNotFound(String),
|
||
|
||
#[error("会话错误: {0}")]
|
||
Session(String),
|
||
|
||
#[error("附件处理错误: {0}")]
|
||
Attachment(String),
|
||
|
||
#[error("网络错误: {0}")]
|
||
Network(#[from] reqwest::Error),
|
||
|
||
#[error("数据库错误: {0}")]
|
||
Database(#[from] rusqlite::Error),
|
||
|
||
#[error("Gemini 服务错误: {0}")]
|
||
GeminiService(#[from] anyhow::Error),
|
||
}
|
||
```
|
||
|
||
### 4. 使用示例
|
||
```rust
|
||
// 基础使用
|
||
let mut sdk = GeminiSDK::with_conversation_support(None)?;
|
||
|
||
// 创建穿搭顾问 Agent
|
||
let agent = sdk.create_outfit_advisor_agent()?;
|
||
|
||
// 发送消息
|
||
let request = MessageRequest {
|
||
text: "分析这张穿搭图片".to_string(),
|
||
attachments: vec![Attachment::new("./outfit.jpg")],
|
||
agent_id: Some(agent.id),
|
||
session_id: None,
|
||
config: None,
|
||
};
|
||
|
||
let response = sdk.send_message(request).await?;
|
||
println!("回复: {}", response.content);
|
||
```
|
||
|
||
## 开发指导
|
||
|
||
### 1. 代码复用策略
|
||
- 直接复用 `gemini_service.rs` 中的核心逻辑
|
||
- 提取通用的配置、错误处理和网络请求代码
|
||
- 简化接口，隐藏内部复杂性
|
||
|
||
### 2. 测试策略
|
||
- 单元测试：各个组件的独立功能
|
||
- 集成测试：完整的消息发送流程
|
||
- 示例代码：展示各种使用场景
|
||
|
||
### 3. 文档要求
|
||
- 完整的 API 文档
|
||
- 使用示例和最佳实践
|
||
- 错误处理指南
|
||
- 性能优化建议
|
||
|
||
### 4. 性能考虑
|
||
- 连接池复用
|
||
- 合理的超时设置
|
||
- 内存使用优化
|
||
- 异步操作支持
|
||
|
||
## 交付标准
|
||
|
||
1. **功能完整性**: 所有设计的接口都能正常工作
|
||
2. **代码质量**: 遵循 Rust 最佳实践，通过 clippy 检查
|
||
3. **测试覆盖**: 核心功能有完整的测试覆盖
|
||
4. **文档完善**: 清晰的 API 文档和使用示例
|
||
5. **易用性**: 简洁的接口，最小化学习成本
|
||
|
||
## 详细实现指南
|
||
|
||
### 1. 从现有代码迁移的关键组件
|
||
|
||
#### 需要复用的核心结构
|
||
```rust
|
||
// 从 gemini_service.rs 复用
|
||
pub struct GeminiConfig { /* 保持原有字段 */ }
|
||
pub struct GenerateContentRequest { /* 保持原有结构 */ }
|
||
pub struct ContentPart { /* 保持原有结构 */ }
|
||
pub enum Part { /* 保持原有枚举 */ }
|
||
pub struct GenerationConfig { /* 保持原有结构 */ }
|
||
```
|
||
|
||
#### 需要复用的核心方法
|
||
- `get_access_token()` - 访问令牌管理
|
||
- `upload_video_file()` - 视频文件上传
|
||
- `generate_content_with_request()` - 内容生成
|
||
- `query_llm_with_grounding_multi_turn()` - 多轮对话
|
||
- `extract_json_from_response()` - JSON 解析
|
||
|
||
### 2. 简化的内部服务层
|
||
|
||
```rust
|
||
// 简化的内部服务，封装复杂逻辑
|
||
struct InternalGeminiService {
|
||
config: GeminiConfig,
|
||
client: reqwest::Client,
|
||
access_token: Option<String>,
|
||
token_expires_at: Option<u64>,
|
||
}
|
||
|
||
impl InternalGeminiService {
|
||
// 复用原有的核心方法，但简化接口
|
||
async fn send_request(&mut self, parts: Vec<Part>, config: GenerationConfig, system_prompt: Option<String>) -> Result<String>;
|
||
async fn upload_file(&mut self, path: &str) -> Result<String>;
|
||
async fn send_multipart_request(&mut self, parts: Vec<Part>, config: GenerationConfig, system_prompt: Option<String>, session_id: Option<String>) -> Result<String>;
|
||
}
|
||
```
|
||
|
||
### 4. 错误恢复和重试机制
|
||
|
||
```rust
|
||
impl GeminiSDK {
|
||
async fn send_message_with_retry(&mut self, request: MessageRequest, max_retries: u32) -> Result<MessageResponse> {
|
||
let mut last_error = None;
|
||
|
||
for attempt in 0..max_retries {
|
||
match self.send_message_internal(request.clone()).await {
|
||
Ok(response) => return Ok(response),
|
||
Err(e) => {
|
||
last_error = Some(e);
|
||
if attempt < max_retries - 1 {
|
||
let delay = std::time::Duration::from_secs(2_u64.pow(attempt));
|
||
tokio::time::sleep(delay).await;
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
Err(last_error.unwrap())
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 配置管理
|
||
|
||
```rust
|
||
impl GeminiSDK {
|
||
pub fn from_env() -> Result<Self> {
|
||
let config = GeminiConfig {
|
||
base_url: std::env::var("GEMINI_BASE_URL").unwrap_or_else(|_| "https://bowongai-dev--bowong-ai-video-gemini-fastapi-webapp.modal.run".to_string()),
|
||
bearer_token: std::env::var("GEMINI_BEARER_TOKEN").unwrap_or_else(|_| "bowong7777".to_string()),
|
||
// ... 其他配置
|
||
};
|
||
|
||
Self::with_config(config)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 完整的使用示例
|
||
|
||
```rust
|
||
#[tokio::main]
|
||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||
// 1. 初始化 SDK
|
||
let mut sdk = GeminiSDK::with_conversation_support(None)?;
|
||
|
||
|
||
// 3. 穿搭分析示例
|
||
let outfit_request = MessageRequest {
|
||
text: "请分析这张穿搭图片，给出专业的搭配建议".to_string(),
|
||
attachments: vec![Attachment::new("./examples/outfit.jpg")],
|
||
agent_id: Some(outfit_agent.id.clone()),
|
||
session_id: None,
|
||
config: None,
|
||
};
|
||
|
||
let outfit_response = sdk.send_message(outfit_request).await?;
|
||
println!("穿搭顾问分析：\n{}", outfit_response.content);
|
||
|
||
// 4. 视频分析示例
|
||
let video_request = MessageRequest {
|
||
text: "请分析这个视频的内容质量和改进建议".to_string(),
|
||
attachments: vec![Attachment::new("./examples/video.mp4")],
|
||
agent_id: Some(video_agent.id),
|
||
session_id: None,
|
||
config: Some(MessageConfig {
|
||
temperature: Some(0.6),
|
||
max_tokens: Some(12000),
|
||
timeout: Some(180),
|
||
}),
|
||
};
|
||
|
||
let video_response = sdk.send_message(video_request).await?;
|
||
println!("视频分析报告：\n{}", video_response.content);
|
||
|
||
// 5. 多轮对话示例
|
||
let session = sdk.create_session(Some("穿搭咨询".to_string())).await?;
|
||
|
||
let follow_up = MessageRequest {
|
||
text: "基于刚才的分析，我想要更正式一些的搭配方案".to_string(),
|
||
attachments: vec![],
|
||
agent_id: Some(outfit_agent.id),
|
||
session_id: Some(session.session_id.clone()),
|
||
config: None,
|
||
};
|
||
|
||
let follow_response = sdk.send_message(follow_up).await?;
|
||
println!("后续建议：\n{}", follow_response.content);
|
||
|
||
// 6. 查看对话历史
|
||
let history = sdk.get_conversation_history(&session.session_id, Some(10)).await?;
|
||
for msg in history {
|
||
println!("{}: {}", msg.role, msg.content);
|
||
}
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
## 质量保证要求
|
||
|
||
### 1. 代码规范
|
||
- 使用 `cargo fmt` 格式化代码
|
||
- 通过 `cargo clippy` 静态检查
|
||
- 添加适当的文档注释
|
||
- 遵循 Rust 命名约定
|
||
|
||
### 2. 测试要求
|
||
```rust
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
#[tokio::test]
|
||
async fn test_basic_message_sending() {
|
||
// 测试基础消息发送功能
|
||
}
|
||
|
||
#[tokio::test]
|
||
async fn test_agent_management() {
|
||
// 测试 Agent 创建和管理
|
||
}
|
||
|
||
#[tokio::test]
|
||
async fn test_conversation_flow() {
|
||
// 测试多轮对话流程
|
||
}
|
||
|
||
#[tokio::test]
|
||
async fn test_attachment_processing() {
|
||
// 测试附件处理
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 文档要求
|
||
- 每个公共接口都要有详细的文档注释
|
||
- 提供完整的使用示例
|
||
- 包含错误处理指南
|
||
- 性能和最佳实践说明
|
||
|
||
请基于这个详细的设计方案和实现指南，创建一个高质量、易用、功能完整的 Gemini SDK crate。
|