feat: 添加 VEO3 场景写作和角色定义 SDK

- 新增 gemini-sdk: 基于 Gemini AI 的通用 SDK - 新增 veo3-scene-writer: VEO3 场景写作专用工具 - 支持图片/视频附件分析 - 多轮会话功能 - VEO3 专业提示词集成 - 角色一致性管理 - 新增 Veo3ActorDefine: 角色定义专用工具 - 添加完整的示例和文档 - 支持多种输出格式 (文本/JSON/YAML)
2025-08-15 18:02:15 +08:00
parent 08b981c31f
commit 577b539ee2
18 changed files with 4389 additions and 0 deletions
--- a/cargos/gemini-sdk/promptx.md
+++ b/cargos/gemini-sdk/promptx.md
@@ -0,0 +1,477 @@
+# 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。