534 lines
14 KiB
Markdown
534 lines
14 KiB
Markdown
# 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<SystemInfo>;
|
|
async fn health_check(&self) -> Result<HealthStatus>;
|
|
}
|
|
|
|
// TemplateEngine 接口
|
|
pub trait TemplateEngineTrait {
|
|
async fn load_template(&self, id: &str) -> Result<WorkflowTemplate>;
|
|
async fn validate_parameters(&self, template_id: &str, params: &ParameterValues) -> Result<ValidationResult>;
|
|
async fn create_instance(&self, template_id: &str, params: ParameterValues) -> Result<WorkflowInstance>;
|
|
}
|
|
|
|
// ExecutionEngine 接口
|
|
pub trait ExecutionEngineTrait {
|
|
async fn execute_workflow(&self, workflow: &WorkflowInstance) -> Result<ExecutionResult>;
|
|
async fn execute_template(&self, template_id: &str, params: ParameterValues) -> Result<ExecutionResult>;
|
|
async fn cancel_execution(&self, execution_id: &str) -> Result<()>;
|
|
async fn get_execution_status(&self, execution_id: &str) -> Result<ExecutionStatus>;
|
|
}
|
|
```
|
|
|
|
#### 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
|
|
|
|
> 💡 **提示**: 这是一个完全重写的计划，需要充分的准备和测试。建议在开始前进行详细的技术评审和团队讨论。
|
|
|
|
> ⚠️ **重要**: 开始开发前请务必备份现有代码和数据，并创建独立的开发分支。
|