# 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`

## 🚀 一鍵構建和發佈

### Build Desktop & Release 工作流程

最簡單的方式是使用 **Build Desktop & Release** 工作流程，它會自動：
1. 構建所有平台的桌面應用
2. 等待構建完成
3. 自動觸發發佈流程

**使用方法**：
1. 前往 [Build Desktop & Release](../../actions/workflows/build-and-release.yml)
2. 點擊 "Run workflow"
3. 選擇版本類型或輸入自定義版本
4. 選擇要構建的平台（默認：all）
5. 如果只想構建不發佈，勾選 "只構建桌面應用，不進行發佈"

**優勢**：
- ✅ 自動化整個流程
- ✅ 確保桌面應用構建成功後才發佈
- ✅ 統一的狀態報告
- ✅ 減少手動操作錯誤

## 🔧 故障排除

### 桌面應用構建失敗

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

### 發佈流程問題

1. **桌面應用缺失**:
   - 確認 "Build Desktop Applications" 工作流程已成功運行
   - 檢查指定的 Run ID 是否正確
   - 驗證 Artifacts 是否已正確上傳

2. **版本衝突**:
   - 檢查 PyPI 上是否已存在相同版本
   - 確認版本號格式正確 (X.Y.Z)

3. **權限問題**:
   - 確認 PYPI_API_TOKEN 密鑰已正確設置
   - 檢查 GitHub Token 權限

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

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

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

## 📊 工作流程優勢

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

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

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