# GitHub Actions 工作流程說明

本項目使用雙工作流程架構來優化構建和發佈流程。

## 🏗️ 工作流程架構

### 1. 桌面應用構建工作流程 (build-desktop.yml)

**用途**: 專門負責構建多平台桌面應用二進制文件

**觸發條件**:
- 手動觸發 (workflow_dispatch)
- 桌面應用代碼變更時自動觸發 (`src-tauri/**`, `scripts/build_desktop.py`)
- Pull Request 中的桌面應用變更

**功能**:
- 在各自原生平台上構建桌面應用
- 支援選擇性平台構建
- 上傳構建產物到 GitHub Artifacts (保留 30 天)
- 提供詳細的構建摘要

**支援平台**:
- Windows x64 (`windows-latest`)
- macOS Intel (`macos-latest` + `x86_64-apple-darwin`)
- macOS Apple Silicon (`macos-latest` + `aarch64-apple-darwin`)
- Linux x64 (`ubuntu-latest`)

### 2. 發佈工作流程 (publish.yml)

**用途**: 負責版本管理和 PyPI 發佈

**觸發條件**:
- 手動觸發 (workflow_dispatch)

**功能**:
- 自動或手動版本號管理
- 可選擇是否包含桌面應用
- 從最新的桌面應用構建下載二進制文件
- 發佈到 PyPI
- 創建 GitHub Release

## 🚀 使用方式

### 開發桌面應用時

1. **修改桌面應用代碼** (`src-tauri/` 目錄)
2. **自動觸發構建** - 推送到 main 分支會自動觸發桌面應用構建
3. **手動觸發構建** (可選) - 在 GitHub Actions 頁面手動運行 "Build Desktop Applications"

### 發佈新版本時

1. **確保桌面應用已構建** - 檢查最新的 "Build Desktop Applications" 工作流程是否成功
2. **手動觸發發佈** - 在 GitHub Actions 頁面運行 "Auto Release to PyPI"
3. **選擇發佈選項**:
   - `version_type`: patch/minor/major (或使用 custom_version)
   - `include_desktop`: 是否包含桌面應用 (預設: true)
   - `desktop_build_run_id`: 指定特定的構建 ID (可選)

## 📋 最佳實踐

### 桌面應用構建

```bash
# 本地測試桌面應用構建
python scripts/build_desktop.py --release

# 檢查構建產物
ls -la src/mcp_feedback_enhanced/desktop_release/
ls -la src/mcp_feedback_enhanced/desktop_app/
```

### 發佈流程

1. **準備發佈**:
   - 更新 CHANGELOG 文件
   - 確保桌面應用構建成功
   - 測試本地功能

2. **執行發佈**:
   - 手動觸發 "Auto Release to PyPI" 工作流程
   - 選擇適當的版本類型
   - 確認包含桌面應用 (如果需要)

3. **發佈後驗證**:
   - 檢查 PyPI 上的新版本
   - 測試安裝: `uvx mcp-feedback-enhanced@latest`
   - 測試桌面模式: `uvx mcp-feedback-enhanced@latest test --desktop`

## 🔧 故障排除

### 桌面應用構建失敗

1. **檢查構建日誌** - 查看 GitHub Actions 中的詳細錯誤信息
2. **平台特定問題**:
   - macOS: 可能缺少 Xcode 命令行工具
   - Linux: 可能缺少系統依賴 (GTK, Cairo 等)
   - Windows: 通常構建成功

3. **本地測試** - 在對應平台上運行本地構建腳本

### 發佈時桌面應用缺失

1. **檢查構建狀態** - 確保最新的桌面應用構建成功
2. **手動指定構建** - 使用 `desktop_build_run_id` 參數指定特定的成功構建
3. **跳過桌面應用** - 設置 `include_desktop: false` 僅發佈 Web 版本

## 📊 工作流程優勢

### 效率提升
- **分離關注點**: 構建和發佈獨立進行
- **避免重複構建**: 不是每次發佈都需要重新構建桌面應用
- **快速發佈**: 發佈流程更快速，特別是僅修改 Python 代碼時

### 靈活性
- **選擇性構建**: 可以只構建特定平台
- **選擇性發佈**: 可以選擇是否包含桌面應用
- **版本控制**: 可以使用不同的桌面應用構建版本

### 可靠性
- **原生構建**: 每個平台在其原生環境中構建
- **構建緩存**: 利用 GitHub Actions 緩存加速構建
- **錯誤隔離**: 桌面應用構建失敗不會影響 Web 版本發佈