# ComfyUI SDK 完全重写集成计划 ## 📋 项目概述 **目标**: 完全基于 `cargos/comfyui-sdk` 重新实现 MixVideo 项目的 ComfyUI 集成，构建现代化、高性能的 AI 工作流管理系统。 **核心优势**: - 🚀 充分利用 SDK 的所有高级功能 - 🔄 WebSocket 实时通信和进度跟踪 - 📝 强大的模板系统和参数验证 - 🛡️ 类型安全和错误处理 - ⚡ 连接池和性能优化 - 🎯 统一的架构设计 **预计工期**: 3-4 周 **风险等级**: 中等 (需要充分测试) --- ## 🏗️ 架构设计 ### 新架构概览 ``` Frontend (React + TypeScript) ↓ Tauri Invoke Backend (Rust + ComfyUI SDK) ├── Presentation Layer (Commands) ├── Business Layer (Services) ├── Data Layer (Models + Database) └── Infrastructure Layer (ComfyUI SDK) ``` ### 核心组件 1. **ComfyUIManager**: 统一的 SDK 管理器 2. **TemplateEngine**: 工作流模板引擎 3. **ExecutionEngine**: 工作流执行引擎 4. **RealtimeMonitor**: 实时状态监控 5. **CacheManager**: 智能缓存管理 --- ## 📅 详细开发计划 ## 第一阶段: 基础架构重构 (第1周) ### 🎯 目标 建立全新的基于 SDK 的基础架构，替换现有的传统实现。 ### 📋 任务清单 #### 1.1 数据模型重新设计 (2天) - [ ] **删除旧模型**: 移除 `apps/desktop/src-tauri/src/data/models/comfyui.rs` - [ ] **创建新模型**: 基于 SDK 类型创建统一数据模型 - [ ] `WorkflowModel`: 工作流数据模型 - [ ] `TemplateModel`: 模板数据模型 - [ ] `ExecutionModel`: 执行记录模型 - [ ] `QueueModel`: 队列状态模型 - [ ] **数据库迁移**: 设计新的数据库表结构 - [ ] `comfyui_workflows` 表 - [ ] `comfyui_templates` 表 - [ ] `comfyui_executions` 表 - [ ] `comfyui_queue_history` 表 #### 1.2 核心服务重构 (3天) - [ ] **删除旧服务**: 移除现有的 ComfyUI 服务实现 - [ ] 删除 `comfyui_service.rs` - [ ] 删除 `comfyui_sdk_service.rs` - [ ] **创建 ComfyUIManager**: 统一的 SDK 管理器 - [ ] 连接管理和健康检查 - [ ] 配置管理和验证 - [ ] 错误处理和重试机制 - [ ] **创建 TemplateEngine**: 模板管理引擎 - [ ] 模板加载和验证 - [ ] 参数解析和验证 - [ ] 模板实例化 - [ ] **创建 ExecutionEngine**: 执行引擎 - [ ] 工作流执行管理 - [ ] 队列管理 - [ ] 结果处理 #### 1.3 配置系统重构 (1天) - [ ] **统一配置结构**: 基于 SDK 配置重新设计 - [ ] **配置验证**: 添加配置有效性检查 - [ ] **环境适配**: 支持开发/生产环境配置 #### 1.4 错误处理系统 (1天) - [ ] **统一错误类型**: 基于 SDK 错误类型设计 - [ ] **错误映射**: SDK 错误到应用错误的映射 - [ ] **错误恢复**: 自动重试和降级策略 ### 🧪 测试要求 - [ ] 单元测试覆盖率 > 80% - [ ] 集成测试验证基础功能 - [ ] 性能基准测试 --- ## 第二阶段: 命令层重写 (第2周) ### 🎯 目标 重新实现所有 Tauri 命令，提供完整的前端 API 接口。 ### 📋 任务清单 #### 2.1 基础命令重写 (2天) - [ ] **连接管理命令** - [ ] `comfyui_connect`: 连接到 ComfyUI 服务 - [ ] `comfyui_disconnect`: 断开连接 - [ ] `comfyui_health_check`: 健康检查 - [ ] `comfyui_get_system_info`: 获取系统信息 #### 2.2 工作流管理命令 (2天) - [ ] **工作流 CRUD 命令** - [ ] `comfyui_list_workflows`: 获取工作流列表 - [ ] `comfyui_get_workflow`: 获取单个工作流 - [ ] `comfyui_create_workflow`: 创建工作流 - [ ] `comfyui_update_workflow`: 更新工作流 - [ ] `comfyui_delete_workflow`: 删除工作流 #### 2.3 模板管理命令 (2天) - [ ] **模板系统命令** - [ ] `comfyui_list_templates`: 获取模板列表 - [ ] `comfyui_get_template`: 获取模板详情 - [ ] `comfyui_validate_template`: 验证模板 - [ ] `comfyui_create_template_instance`: 创建模板实例 #### 2.4 执行管理命令 (1天) - [ ] **执行控制命令** - [ ] `comfyui_execute_workflow`: 执行工作流 - [ ] `comfyui_execute_template`: 执行模板 - [ ] `comfyui_cancel_execution`: 取消执行 - [ ] `comfyui_get_execution_status`: 获取执行状态 ### 🧪 测试要求 - [ ] 每个命令的单元测试 - [ ] 命令集成测试 - [ ] 错误场景测试 --- ## 第三阶段: 实时通信与高级功能 (第3周) ### 🎯 目标 实现 WebSocket 实时通信和高级功能，提供完整的用户体验。 ### 📋 任务清单 #### 3.1 WebSocket 实时通信 (3天) - [ ] **实时监控服务** - [ ] WebSocket 连接管理 - [ ] 事件订阅和分发 - [ ] 进度更新推送 - [ ] **前端实时更新** - [ ] 实时状态显示 - [ ] 进度条更新 - [ ] 错误实时提醒 #### 3.2 队列管理系统 (2天) - [ ] **队列监控** - [ ] 队列状态实时更新 - [ ] 任务优先级管理 - [ ] 队列统计信息 - [ ] **批量操作** - [ ] 批量提交任务 - [ ] 批量取消任务 - [ ] 批量状态查询 #### 3.3 缓存和性能优化 (2天) - [ ] **智能缓存** - [ ] 工作流结果缓存 - [ ] 模板缓存 - [ ] 连接池管理 - [ ] **性能监控** - [ ] 执行时间统计 - [ ] 资源使用监控 - [ ] 性能指标收集 ### 🧪 测试要求 - [ ] WebSocket 连接稳定性测试 - [ ] 高并发场景测试 - [ ] 性能压力测试 --- ## 第四阶段: 前端重构与UI优化 (第4周) ### 🎯 目标 重构前端代码，提供现代化的用户界面和交互体验。 ### 📋 任务清单 #### 4.1 类型定义更新 (1天) - [ ] **TypeScript 类型重写** - [ ] 基于新后端 API 更新类型定义 - [ ] 添加 SDK 特有的类型 - [ ] 类型安全验证 #### 4.2 服务层重构 (2天) - [ ] **前端服务重写** - [ ] 重写 `ComfyuiService` 类 - [ ] 添加实时通信支持 - [ ] 错误处理优化 - [ ] **状态管理优化** - [ ] Zustand store 重构 - [ ] 实时状态同步 - [ ] 缓存策略实现 #### 4.3 UI 组件优化 (3天) - [ ] **核心组件重构** - [ ] 工作流管理界面 - [ ] 模板选择器 - [ ] 执行监控面板 - [ ] 实时进度显示 - [ ] **用户体验优化** - [ ] 加载状态优化 - [ ] 错误提示改进 - [ ] 响应式设计完善 #### 4.4 高级功能界面 (1天) - [ ] **新功能界面** - [ ] 模板编辑器 - [ ] 批量操作界面 - [ ] 性能监控面板 - [ ] 队列管理界面 ### 🧪 测试要求 - [ ] 组件单元测试 - [ ] E2E 测试覆盖 - [ ] 用户体验测试 --- ## 🗂️ 文件结构规划 ### 后端文件结构 ``` apps/desktop/src-tauri/src/ ├── business/ │ ├── services/ │ │ ├── comfyui_manager.rs # 核心管理器 │ │ ├── template_engine.rs # 模板引擎 │ │ ├── execution_engine.rs # 执行引擎 │ │ └── realtime_monitor.rs # 实时监控 │ └── models/ │ └── comfyui/ # 新的数据模型 ├── data/ │ ├── repositories/ │ │ └── comfyui_repository.rs # 数据访问层 │ └── migrations/ │ └── comfyui_tables.sql # 数据库迁移 ├── presentation/ │ └── commands/ │ └── comfyui_commands.rs # 重写的命令 └── infrastructure/ └── comfyui/ # SDK 集成层 ``` ### 前端文件结构 ``` apps/desktop/src/ ├── services/ │ └── comfyuiService.ts # 重写的服务 ├── types/ │ └── comfyui.ts # 更新的类型定义 ├── components/ │ ├── ComfyUI/ # ComfyUI 相关组件 │ │ ├── WorkflowManager.tsx │ │ ├── TemplateSelector.tsx │ │ ├── ExecutionMonitor.tsx │ │ └── RealtimeProgress.tsx │ └── common/ # 通用组件 ├── pages/ │ ├── ComfyUIManagement.tsx # 重构的管理页面 │ └── ComfyUIWorkflowTest.tsx # 重构的测试页面 └── store/ └── comfyuiStore.ts # 重构的状态管理 ``` --- ## ⚠️ 风险评估与应对策略 ### 高风险项 1. **数据迁移风险** - 风险: 现有数据丢失或损坏 - 应对: 完整的数据备份和迁移脚本测试 2. **功能兼容性风险** - 风险: 新实现与现有功能不兼容 - 应对: 详细的功能对比测试 3. **性能回退风险** - 风险: 新实现性能不如旧版本 - 应对: 性能基准测试和优化 ### 中等风险项 1. **开发周期延长** - 风险: 复杂度超出预期 - 应对: 分阶段交付，及时调整计划 2. **用户体验变化** - 风险: 用户不适应新界面 - 应对: 渐进式界面更新，保留熟悉元素 ### 应对措施 - [ ] 每周进行风险评估 - [ ] 建立回滚机制 - [ ] 充分的测试覆盖 - [ ] 用户反馈收集 --- ## 📊 成功指标 ### 技术指标 - [ ] 代码覆盖率 > 85% - [ ] API 响应时间 < 200ms - [ ] WebSocket 连接稳定性 > 99% - [ ] 内存使用优化 > 20% ### 功能指标 - [ ] 支持所有现有功能 - [ ] 新增实时监控功能 - [ ] 新增模板管理功能 - [ ] 新增批量操作功能 ### 用户体验指标 - [ ] 界面响应速度提升 > 30% - [ ] 错误率降低 > 50% - [ ] 用户操作步骤减少 > 20% --- ## 🚀 开始执行 ### 立即行动项 1. [ ] 确认开发计划和时间安排 2. [ ] 备份现有代码和数据 3. [ ] 创建开发分支 `feature/comfyui-sdk-rewrite` 4. [ ] 开始第一阶段开发 ### 每日检查项 - [ ] 代码提交和备份 - [ ] 测试执行和结果记录 - [ ] 进度更新和风险评估 - [ ] 团队沟通和问题解决 --- ## 📝 实施细节补充 ### 关键技术决策 #### 1. 数据库设计 ```sql -- 工作流表 CREATE TABLE comfyui_workflows ( id TEXT PRIMARY KEY, name TEXT NOT NULL, description TEXT, workflow_data TEXT NOT NULL, -- JSON version TEXT DEFAULT '1.0', created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ); -- 模板表 CREATE TABLE comfyui_templates ( id TEXT PRIMARY KEY, name TEXT NOT NULL, category TEXT, description TEXT, template_data TEXT NOT NULL, -- JSON parameter_schema TEXT NOT NULL, -- JSON created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); -- 执行记录表 CREATE TABLE comfyui_executions ( id TEXT PRIMARY KEY, workflow_id TEXT, template_id TEXT, prompt_id TEXT, status TEXT NOT NULL, -- pending, running, completed, failed parameters TEXT, -- JSON results TEXT, -- JSON error_message TEXT, execution_time INTEGER, -- milliseconds created_at DATETIME DEFAULT CURRENT_TIMESTAMP, completed_at DATETIME ); ``` #### 2. 核心服务接口设计 ```rust // ComfyUIManager 核心接口 pub trait ComfyUIManagerTrait { async fn connect(&mut self) -> Result<()>; async fn disconnect(&mut self) -> Result<()>; async fn is_connected(&self) -> bool; async fn get_system_info(&self) -> Result; async fn health_check(&self) -> Result; } // TemplateEngine 接口 pub trait TemplateEngineTrait { async fn load_template(&self, id: &str) -> Result; async fn validate_parameters(&self, template_id: &str, params: &ParameterValues) -> Result; async fn create_instance(&self, template_id: &str, params: ParameterValues) -> Result; } // ExecutionEngine 接口 pub trait ExecutionEngineTrait { async fn execute_workflow(&self, workflow: &WorkflowInstance) -> Result; async fn execute_template(&self, template_id: &str, params: ParameterValues) -> Result; async fn cancel_execution(&self, execution_id: &str) -> Result<()>; async fn get_execution_status(&self, execution_id: &str) -> Result; } ``` #### 3. 错误处理策略 ```rust #[derive(Debug, thiserror::Error)] pub enum ComfyUIError { #[error("Connection error: {0}")] Connection(String), #[error("Template error: {0}")] Template(String), #[error("Execution error: {0}")] Execution(String), #[error("Validation error: {0}")] Validation(String), #[error("SDK error: {0}")] Sdk(#[from] comfyui_sdk::error::ComfyUIError), } ``` ### 开发环境准备 #### 必需工具 - [ ] Rust 1.70+ - [ ] Node.js 18+ - [ ] PNPM 8+ - [ ] SQLite 3 - [ ] ComfyUI 服务器 (用于测试) #### 开发配置 ```toml # Cargo.toml 依赖更新 [dependencies] comfyui-sdk = { path = "../../../cargos/comfyui-sdk", features = ["websocket", "templates"] } tokio = { version = "1.0", features = ["full"] } serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" anyhow = "1.0" thiserror = "1.0" tracing = "0.1" sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "sqlite", "chrono"] } ``` ### 测试策略 #### 单元测试 ```rust #[cfg(test)] mod tests { use super::*; #[tokio::test] async fn test_comfyui_manager_connect() { // 测试连接功能 } #[tokio::test] async fn test_template_validation() { // 测试模板验证 } #[tokio::test] async fn test_workflow_execution() { // 测试工作流执行 } } ``` #### 集成测试 - [ ] 端到端工作流测试 - [ ] WebSocket 连接测试 - [ ] 数据库操作测试 - [ ] 错误恢复测试 ### 部署和发布 #### 发布检查清单 - [ ] 所有测试通过 - [ ] 性能指标达标 - [ ] 文档更新完成 - [ ] 用户反馈收集 - [ ] 回滚方案准备 #### 发布策略 1. **Alpha 版本**: 内部测试 (第2周末) 2. **Beta 版本**: 小范围用户测试 (第3周末) 3. **正式版本**: 全量发布 (第4周末) --- ## 📞 联系和支持 ### 技术支持 - **开发问题**: 查看项目 Issues - **SDK 问题**: 参考 `cargos/comfyui-sdk/README.md` - **架构问题**: 联系架构师 ### 文档资源 - [ ] API 文档: `docs/api/comfyui.md` - [ ] 开发指南: `docs/development/comfyui-integration.md` - [ ] 故障排除: `docs/troubleshooting/comfyui.md` --- **最后更新**: 2025-01-08 **负责人**: 开发团队 **审核人**: 项目经理 **版本**: v1.0 > 💡 **提示**: 这是一个完全重写的计划，需要充分的准备和测试。建议在开始前进行详细的技术评审和团队讨论。 > ⚠️ **重要**: 开始开发前请务必备份现有代码和数据，并创建独立的开发分支。