mxivideo/docs/PYTHON_CORE_DISTRIBUTION.md

# Python Core 分发解决方案

## 问题背景

当前项目使用 `python -m python_core.services.xxx` 的方式调用Python模块，这在开发环境下工作正常，但打包成exe后会遇到以下问题：

1. **Python环境依赖**：用户机器可能没有安装Python或缺少依赖包
2. **模块路径问题**：python_core目录不在用户的Python路径中
3. **分发复杂性**：需要用户单独安装Python环境

## 解决方案：Tauri Sidecar + PyInstaller

### 方案概述

使用PyInstaller将Python代码打包成独立可执行文件，作为Tauri的sidecar与主应用一起分发。

### 优势

1. **无需Python环境**：用户无需安装Python
2. **依赖自包含**：所有Python依赖都打包在内
3. **分发简单**：单个exe文件包含所有功能
4. **性能优化**：避免Python解释器启动开销
5. **安全性**：代码被编译，不易被逆向

## 实现步骤

### 1. 创建Python入口文件

**文件**: `python_core/main.py`

这是PyInstaller的入口点，提供统一的命令行接口：

```python
# 支持模块映射
MODULE_MAP = {
    'template_manager': 'services.template_manager',
    'project_manager': 'services.project_manager',
    # ... 更多模块
}

# 统一的执行接口
def execute_action(module_name, action, params=None, progress_callback=None):
    # 动态加载和执行模块函数
```

### 2. PyInstaller配置

**文件**: `python_core/build.spec`

配置打包选项：
- 隐藏导入：确保所有模块被包含
- 数据文件：包含配置和资源文件
- 排除模块：减少打包大小
- 单文件模式：生成单个可执行文件

### 3. 自动化构建脚本

**文件**: `scripts/build_python_core.py`

提供完整的构建流程：
1. 安装构建依赖
2. 清理构建目录
3. 运行PyInstaller
4. 复制到sidecar目录
5. 更新Tauri配置
6. 验证构建结果

### 4. Rust代码适配

**文件**: `src-tauri/src/python_executor.rs`

添加sidecar支持：
- 自动检测sidecar可用性
- 开发环境使用系统Python
- 生产环境使用sidecar
- 统一的API接口

## 使用方法

### 构建Python Core

#### Windows
```cmd
scripts\build_python_core.bat
```

#### Linux/macOS
```bash
./scripts/build_python_core.sh
```

#### 手动构建
```bash
python scripts/build_python_core.py
```

### 开发和测试

```bash
# 开发模式（使用系统Python）
cargo tauri dev

# 生产构建（包含sidecar）
cargo tauri build
```

### API调用

```rust
// 新的模块化API
use crate::python_executor::execute_python_module_action;

#[tauri::command]
pub async fn my_command(app: AppHandle) -> Result<String, String> {
    let params = serde_json::json!({
        "folder_path": "/path/to/templates",
        "force_reimport": false
    });
    
    execute_python_module_action(
        app,
        "template_manager",  // 模块名
        "batch_import",      // 动作名
        Some(params),        // 参数
        None                 // 配置
    ).await
}
```

## 文件结构

```
project/
├── python_core/
│   ├── main.py              # PyInstaller入口文件
│   ├── build.spec           # PyInstaller配置
│   ├── services/            # 服务模块
│   ├── utils/               # 工具模块
│   └── ...
├── scripts/
│   ├── build_python_core.py # 构建脚本
│   ├── build_python_core.bat# Windows批处理
│   └── build_python_core.sh # Linux/macOS脚本
├── src-tauri/
│   ├── binaries/            # sidecar可执行文件
│   │   └── mixvideo-python-core(.exe)
│   ├── src/
│   │   └── python_executor.rs # 更新的执行器
│   └── tauri.conf.json      # 更新的配置
└── docs/
    └── PYTHON_CORE_DISTRIBUTION.md
```

## 配置说明

### Tauri配置更新

`src-tauri/tauri.conf.json`:
```json
{
  "bundle": {
    "externalBin": [
      {
        "name": "mixvideo-python-core",
        "src": "binaries/mixvideo-python-core",
        "targets": ["all"]
      }
    ]
  }
}
```

### 环境检测逻辑

```rust
fn should_use_sidecar() -> bool {
    #[cfg(not(debug_assertions))]
    {
        // 生产环境：检查sidecar是否存在
        return get_sidecar_path().is_some();
    }
    
    // 开发环境：使用系统Python
    false
}
```

## 性能对比

| 方案 | 启动时间 | 内存占用 | 分发大小 | 依赖管理 |
|------|----------|----------|----------|----------|
| 系统Python | 慢 | 低 | 小 | 复杂 |
| PyInstaller | 快 | 中 | 大 | 简单 |

## 故障排除

### 常见问题

#### 1. 构建失败
```bash
# 检查Python环境
python --version
pip --version

# 安装构建依赖
pip install pyinstaller requests Pillow opencv-python-headless
```

#### 2. 模块导入错误
- 检查 `build.spec` 中的 `hiddenimports`
- 添加缺失的模块到隐藏导入列表

#### 3. 资源文件缺失
- 检查 `build.spec` 中的 `datas` 配置
- 确保所有资源文件都被包含

#### 4. sidecar不可用
- 检查 `src-tauri/binaries/` 目录
- 验证可执行文件权限
- 查看Tauri配置中的sidecar设置

### 调试方法

#### 1. 测试sidecar
```bash
# 直接测试可执行文件
./src-tauri/binaries/mixvideo-python-core --version
./src-tauri/binaries/mixvideo-python-core --module template_manager --action get_templates
```

#### 2. 查看日志
```rust
// 在Rust代码中添加调试输出
println!("Using sidecar: {}", should_use_sidecar());
println!("Sidecar path: {:?}", get_sidecar_path());
```

#### 3. 环境变量
```bash
# 强制使用系统Python（调试用）
export MIXVIDEO_FORCE_SYSTEM_PYTHON=1
```

## 最佳实践

### 1. 开发流程
1. 在开发环境使用系统Python进行开发和测试
2. 定期构建sidecar验证打包正确性
3. 在CI/CD中自动化构建流程

### 2. 版本管理
- 为sidecar添加版本信息
- 在主应用中检查sidecar版本兼容性
- 提供版本不匹配时的降级方案

### 3. 错误处理
- 提供详细的错误信息
- 实现自动重试机制
- 支持降级到系统Python

### 4. 性能优化
- 使用单文件模式减少启动时间
- 排除不必要的模块减少大小
- 考虑使用UPX压缩可执行文件

## 未来改进

### 短期计划
- [ ] 添加自动更新机制
- [ ] 支持插件化架构
- [ ] 优化启动性能

### 长期计划
- [ ] 考虑使用Rust重写核心逻辑
- [ ] 支持多语言sidecar
- [ ] 集成云端分发

---

通过这个解决方案，我们成功解决了Python代码分发的问题，为用户提供了无需Python环境的一体化体验。