python-package.yml

# =============================================================================
# Nuitka 构建工作流 - 完全可配置版本（替换模式）
# =============================================================================
#
# 【核心设计理念】
# 三层配置优先级（高→低）：仓库变量 > 配置文件 > 代码默认值
# 关键特性：完全替换而非合并，自定义配置时不会混入默认参数
#
# =============================================================================
# 【配置方式一】仓库变量（最高优先级，适合临时调试）
# =============================================================================
#
# 位置：GitHub Repo → Settings → Secrets and variables → Actions → Variables
#
# 1. 完整平台配置变量（完全覆盖所有参数）
# 变量名格式：NUITKA_CONFIG_<PLATFORM>
# 可用平台：WIN64, WIN32, LINUX, LINUX_OLD, MACOS
#
# 示例 - NUITKA_CONFIG_WIN64：
# {
#   "enabled": true,           # 是否启用此平台构建（true/false）
#   "os": "windows-2022",      # GitHub Actions 运行器镜像
#   "arch": "x64",             # 架构：x64, x86, arm64
#   "shell": "pwsh",           # 脚本类型：bash 或 pwsh
#   "ext": ".exe",             # 输出文件扩展名
#   "nuitka_args": [           # Nuitka 编译参数数组（完整命令在此定义）
#     "--standalone",
#     "--onefile",
#     "--windows-disable-console",
#     "--enable-plugin=tk-inter",
#     "--lto=yes",             # 链接时优化
#     "--jobs=8"               # 并行编译线程数
#   ],
#   "data_files": [            # 需要打包的数据文件（自动检测存在性）
#     "config.json",
#     "assets/logo.png"
#   ],
#   "cache_path": "~\\AppData\\Local\\pip\\Cache",  # pip 缓存路径
#   "system_deps": ""          # Linux 系统依赖包（空格分隔）
# }
#
# 2. 平台开关变量（仅控制是否构建，使用默认配置）
# 变量名格式：ENABLE_<PLATFORM>
# 示例 - ENABLE_WIN32：false（禁用 32 位构建）
# 示例 - ENABLE_MACOS：true（启用 macOS 构建）
#
# 【使用场景】
# - 临时测试不同编译参数
# - 快速切换构建平台开关
# - 无需修改代码即可调整构建行为
#
# 【注意事项】
# - 变量值必须是合法 JSON 字符串
# - 设置后立即可生效，无需提交代码
# - 会完全覆盖同平台的配置文件设置
#
# =============================================================================
# 【配置方式二】nuitka-config.json 配置文件（次优先级，适合版本控制）
# =============================================================================
#
# 位置：项目根目录 nuitka-config.json（需提交到 Git）
#
# 文件结构示例：
# {
#   "win64": {                 # 平台 ID，必须与代码中定义的一致
#     "enabled": true,
#     "os": "windows-2019",
#     "arch": "x64",
#     "shell": "pwsh",
#     "ext": ".exe",
#     "nuitka_args": [
#       "--standalone",
#       "--onefile",
#       "--windows-disable-console",
#       "--enable-plugin=tk-inter"
#     ],
#     "data_files": ["config.json"],
#     "cache_path": "~\\AppData\\Local\\pip\\Cache",
#     "system_deps": ""
#   },
#   "linux": {
#     "enabled": true,
#     "os": "ubuntu-20.04",
#     "arch": "x64",
#     "shell": "bash",
#     "ext": ".bin",
#     "nuitka_args": [
#       "--standalone",
#       "--onefile",
#       "--enable-plugin=tk-inter",
#       "--strip"               # 去除调试符号，减小体积
#     ],
#     "data_files": ["config.json"],
#     "cache_path": "~/.cache/pip",
#     "system_deps": "python3-tk patchelf"  # Linux 特有：系统包依赖
#   },
#   "macos": {
#     "enabled": false,          # 默认禁用，需要时开启
#     "os": "macos-latest",
#     "arch": "x64",
#     "shell": "bash",
#     "ext": "",                 # macOS 单文件无扩展名
#     "nuitka_args": [
#       "--standalone",
#       "--onefile",
#       "--macos-disable-console",
#       "--macos-create-app-bundle"  # 创建 .app 包
#     ],
#     "data_files": ["config.json"],
#     "cache_path": "~/Library/Caches/pip",
#     "system_deps": ""
#   }
# }
#
# 【使用场景】
# - 将构建配置纳入版本控制
# - 团队协作共享配置
# - 为不同分支维护不同构建策略
#
# 【注意事项】
# - 文件必须位于仓库根目录
# - 必须是合法 JSON 格式
# - 只定义部分平台时，未定义平台使用代码默认值
# - 会被同平台的仓库变量完全覆盖（如果设置了变量）
#
# =============================================================================
# 【配置方式三】代码默认值（保底方案，无需任何配置）
# =============================================================================
#
# 当以下情况发生时使用代码中的硬编码默认配置：
# - 未设置仓库变量 NUITKA_CONFIG_<PLATFORM>
# - 未创建 nuitka-config.json 文件
# - nuitka-config.json 中未定义该平台
#
# 默认配置行为：
# - win64：启用，Windows 2019，控制台禁用，TK 插件
# - win32：禁用（现代系统很少需要 32 位）
# - linux：启用，Ubuntu 20.04，包含 patchelf
# - linux-old：禁用（Ubuntu 18.04，用于旧系统兼容）
# - macos：禁用（需要 Apple 开发者账号签名）
#
# 【修改方法】
# 编辑本文件中的 get_default_config() 函数（不推荐，建议用前两种方式）
#
# =============================================================================
# 【各平台特有参数说明】
# =============================================================================
#
# Windows 特有：
#   --windows-disable-console    # 禁用控制台窗口（GUI 应用）
#   --windows-icon-from-ico=xxx # 图标文件（脚本会自动检测 file.ico）
#   --windows-company-name=xxx   # 公司信息
#   --windows-product-name=xxx   # 产品信息
#
# Linux 特有：
#   --strip                      # 去除符号表，减小体积
#   system_deps 字段            # 需要 apt 安装的系统包
#     常见值："python3-tk patchelf"（TK 界面 + 动态库修复）
#
# macOS 特有：
#   --macos-disable-console      # 禁用控制台
#   --macos-create-app-bundle    # 创建 .app 目录结构
#   --macos-sign-identity=xxx    # 代码签名（需要开发者证书）
#
# 通用优化参数：
#   --lto=yes                    # 链接时优化，减小体积
#   --jobs=4                     # 并行编译线程数
#   --follow-import-to=numpy     # 强制包含特定模块
#   --include-package=xxx        # 强制包含整个包
#
# =============================================================================
# 【触发方式】
# =============================================================================
#
# 1. 自动触发（推荐）：推送 v* 标签
#    git tag v1.0.0
#    git push origin v1.0.0
#
# 2. 手动触发：GitHub Actions 页面 → Run workflow
#    可选择特定平台：all/windows/win64/win32/linux/linux-old/macos
#
# =============================================================================
# 【调试技巧】
# =============================================================================
#
# 1. 查看配置来源：在构建日志的 "Load build configurations" 步骤
#    会显示每个平台使用的配置来源（repository variable / nuitka-config.json / code default）
#
# 2. 验证 JSON 格式：在线工具 https://jsonlint.com
#
# 3. 测试配置不生效：
#    - 检查变量名是否拼写正确（区分大小写）
#    - 确认 JSON 格式合法（无多余逗号、引号闭合）
#    - 查看日志中的配置合并步骤输出
#
# 4. 临时禁用所有自定义配置：
#    删除仓库变量和 nuitka-config.json，回退到代码默认值
#
# =============================================================================

name: Build and Release with Nuitka (Configurable)

env:
  DEFAULT_PYTHON_VERSIONS: '["3.11"]'

on:
  push:
    tags:
      - "v*"
  workflow_dispatch:
    inputs:
      platform:
        description: '手动选择构建平台'
        required: true
        default: 'all'
        type: choice
        options:
          - all
          - windows
          - win64
          - win32
          - linux
          - linux-old
          - macos

jobs:
  # =========================================================================
  # 准备阶段 - 读取配置并生成动态 Matrix
  # =========================================================================
  prepare:
    runs-on: ubuntu-latest
    outputs:
      main_script: ${{ steps.detect.outputs.main_script }}
      version: ${{ steps.version.outputs.version }}
      should_release: ${{ steps.version.outputs.should_release }}
      python_matrix: ${{ steps.matrix.outputs.python_versions }}
      build_matrix: ${{ steps.build_config.outputs.matrix }}
      build_summary: ${{ steps.build_config.outputs.summary }}
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Detect main script file
        id: detect
        shell: bash
        run: |
          if [ -n "${{ vars.MAIN_SCRIPT }}" ]; then
            MAIN_SCRIPT="${{ vars.MAIN_SCRIPT }}"
            echo "✅ 使用仓库变量 MAIN_SCRIPT: $MAIN_SCRIPT"
          else
            echo "ℹ️ 尝试自动检测常见入口文件..."
            candidates=("main.py" "app.py" "run.py" "start.py" "cli.py" "program.py" "__main__.py")
            found=""
            for name in "${candidates[@]}"; do
              if [ -f "$name" ]; then
                found="$name"
                echo "✅ 找到入口文件: $name"
                break
              fi
            done
            if [ -z "$found" ]; then
              echo "❌ 错误：未找到任何常见入口文件"
              exit 1
            fi
            MAIN_SCRIPT="$found"
          fi
          
          if [ ! -f "$MAIN_SCRIPT" ]; then
            echo "❌ 错误：指定的主文件不存在: $MAIN_SCRIPT"
            exit 1
          fi
          
          echo "main_script=$MAIN_SCRIPT" >> "$GITHUB_OUTPUT"

      - name: Determine version
        id: version
        shell: bash
        run: |
          if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
            VERSION="${GITHUB_REF#refs/tags/}"
            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
            echo "should_release=true" >> "$GITHUB_OUTPUT"
          else
            SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
            echo "version=dev-$SHORT_SHA" >> "$GITHUB_OUTPUT"
            echo "should_release=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Generate Python matrix
        id: matrix
        shell: bash
        run: |
          if [ -n "${{ vars.PYTHON_VERSIONS }}" ]; then
            echo "python_versions=${{ vars.PYTHON_VERSIONS }}" >> "$GITHUB_OUTPUT"
          else
            echo "python_versions=${{ env.DEFAULT_PYTHON_VERSIONS }}" >> "$GITHUB_OUTPUT"
          fi

      # =========================================================================
      # 配置加载 - 替换模式（不合并，完全覆盖）
      # =========================================================================
      - name: Load build configurations (Replace Mode)
        id: build_config
        shell: bash
        env:
          # 平台开关变量
          VAR_ENABLE_WIN64: ${{ vars.ENABLE_WIN64 }}
          VAR_ENABLE_WIN32: ${{ vars.ENABLE_WIN32 }}
          VAR_ENABLE_LINUX: ${{ vars.ENABLE_LINUX }}
          VAR_ENABLE_LINUX_OLD: ${{ vars.ENABLE_LINUX_OLD }}
          VAR_ENABLE_MACOS: ${{ vars.ENABLE_MACOS }}
          # Nuitka 完整配置变量（完全覆盖模式）
          VAR_NUITKA_WIN64: ${{ vars.NUITKA_CONFIG_WIN64 }}
          VAR_NUITKA_WIN32: ${{ vars.NUITKA_CONFIG_WIN32 }}
          VAR_NUITKA_LINUX: ${{ vars.NUITKA_CONFIG_LINUX }}
          VAR_NUITKA_LINUX_OLD: ${{ vars.NUITKA_CONFIG_LINUX_OLD }}
          VAR_NUITKA_MACOS: ${{ vars.NUITKA_CONFIG_MACOS }}
        run: |
          # 安装 jq
          if ! command -v jq &> /dev/null; then
            sudo apt-get update && sudo apt-get install -y jq
          fi

          # 定义默认配置（保底方案）
          get_default_config() {
            local platform=$1
            case $platform in
              win64)
                echo '{
                  "enabled": true,
                  "os": "windows-2019",
                  "arch": "x64",
                  "shell": "pwsh",
                  "ext": ".exe",
                  "nuitka_args": ["--standalone", "--onefile", "--assume-yes-for-downloads", "--enable-plugin=tk-inter", "--windows-disable-console"],
                  "data_files": ["white_files.json", "config.json"],
                  "cache_path": "~\\AppData\\Local\\pip\\Cache",
                  "system_deps": ""
                }'
                ;;
              win32)
                echo '{
                  "enabled": false,
                  "os": "windows-2019",
                  "arch": "x86",
                  "shell": "pwsh",
                  "ext": ".exe",
                  "nuitka_args": ["--standalone", "--onefile", "--assume-yes-for-downloads", "--enable-plugin=tk-inter", "--windows-disable-console"],
                  "data_files": ["white_files.json", "config.json"],
                  "cache_path": "~\\AppData\\Local\\pip\\Cache",
                  "system_deps": ""
                }'
                ;;
              linux)
                echo '{
                  "enabled": true,
                  "os": "ubuntu-20.04",
                  "arch": "x64",
                  "shell": "bash",
                  "ext": ".bin",
                  "nuitka_args": ["--standalone", "--onefile", "--assume-yes-for-downloads", "--enable-plugin=tk-inter"],
                  "data_files": ["white_files.json", "config.json"],
                  "cache_path": "~/.cache/pip",
                  "system_deps": "python3-tk patchelf"
                }'
                ;;
              linux-old)
                echo '{
                  "enabled": false,
                  "os": "ubuntu-18.04",
                  "arch": "x64",
                  "shell": "bash",
                  "ext": ".bin",
                  "nuitka_args": ["--standalone", "--onefile", "--assume-yes-for-downloads", "--enable-plugin=tk-inter"],
                  "data_files": ["white_files.json", "config.json"],
                  "cache_path": "~/.cache/pip",
                  "system_deps": "python3-tk patchelf"
                }'
                ;;
              macos)
                echo '{
                  "enabled": false,
                  "os": "macos-latest",
                  "arch": "x64",
                  "shell": "bash",
                  "ext": "",
                  "nuitka_args": ["--standalone", "--onefile", "--assume-yes-for-downloads", "--enable-plugin=tk-inter", "--macos-disable-console"],
                  "data_files": ["white_files.json", "config.json"],
                  "cache_path": "~/Library/Caches/pip",
                  "system_deps": ""
                }'
                ;;
            esac
          }

          # 读取文件配置（如果存在）
          get_file_config() {
            local platform=$1
            if [ -f "nuitka-config.json" ]; then
              local cfg=$(jq -r ".[\"$platform\"] // empty" nuitka-config.json)
              if [ -n "$cfg" ] && [ "$cfg" != "null" ]; then
                echo "$cfg"
                return 0
              fi
            fi
            return 1
          }

          # 读取仓库变量配置（如果存在）
          get_var_config() {
            local platform=$1
            local var_name="VAR_NUITKA_$(echo $platform | tr '[:lower:]-' '[:upper:]_')"
            local var_value="${!var_name}"
            
            if [ -n "$var_value" ]; then
              echo "$var_value"
              return 0
            fi
            return 1
          }

          # 构建最终配置（替换模式：优先级 变量 > 文件 > 默认）
          build_final_config() {
            local platform=$1
            local final_cfg=""
            local source=""

            # 优先级1：仓库变量（完全覆盖）
            if cfg=$(get_var_config "$platform"); then
              final_cfg="$cfg"
              source="repository variable"
            # 优先级2：配置文件
            elif cfg=$(get_file_config "$platform"); then
              final_cfg="$cfg"
              source="nuitka-config.json"
            # 优先级3：代码默认值
            else
              final_cfg=$(get_default_config "$platform")
              source="code default"
            fi

            # 应用平台开关覆盖（如果设置了 vars.ENABLE_XXX）
            local enable_var="VAR_ENABLE_$(echo $platform | tr '[:lower:]-' '[:upper:]_')"
            local enable_value="${!enable_var}"
            if [ -n "$enable_value" ]; then
              final_cfg=$(echo "$final_cfg" | jq --arg v "$enable_value" '.enabled = ($v == "true")')
            fi

            echo "$final_cfg" | jq --arg s "$source" --arg p "$platform" '. + {"_source": $s, "_platform": $p}'
          }

          # 生成所有平台配置
          PLATFORMS=("win64" "win32" "linux" "linux-old" "macos")
          FINAL_CONFIGS=()

          for platform in "${PLATFORMS[@]}"; do
            cfg=$(build_final_config "$platform")
            FINAL_CONFIGS+=("$cfg")
            echo "📦 $platform: $(echo "$cfg" | jq -r '._source')"
          done

          # 生成 Matrix JSON（只包含 enabled=true 的平台）
          MATRIX_JSON='{"include":[]}'
          PLATFORM_FILTER="${{ github.event.inputs.platform }}"
          IS_MANUAL=$([ "${{ github.event_name }}" == "workflow_dispatch" ] && echo "true" || echo "false")

          for cfg in "${FINAL_CONFIGS[@]}"; do
            platform=$(echo "$cfg" | jq -r '._platform')
            enabled=$(echo "$cfg" | jq -r '.enabled')
            
            # 检查是否应该包含
            SHOULD_INCLUDE=false
            
            if [ "$IS_MANUAL" == "true" ]; then
              case "$PLATFORM_FILTER" in
                all) [ "$enabled" == "true" ] && SHOULD_INCLUDE=true ;;
                windows) [[ "$platform" == win* ]] && [ "$enabled" == "true" ] && SHOULD_INCLUDE=true ;;
                linux) [[ "$platform" == "linux" ]] && [ "$enabled" == "true" ] && SHOULD_INCLUDE=true ;;
                linux-old) [ "$platform" == "linux-old" ] && [ "$enabled" == "true" ] && SHOULD_INCLUDE=true ;;
                macos) [ "$platform" == "macos" ] && [ "$enabled" == "true" ] && SHOULD_INCLUDE=true ;;
                *) [ "$platform" == "$PLATFORM_FILTER" ] && [ "$enabled" == "true" ] && SHOULD_INCLUDE=true ;;
              esac
            else
              [ "$enabled" == "true" ] && SHOULD_INCLUDE=true
            fi

            if [ "$SHOULD_INCLUDE" == "true" ]; then
              # 清理内部字段，构建矩阵项
              item=$(echo "$cfg" | jq '{
                "id": ._platform,
                "name": (._platform | gsub("win64"; "Windows 64-bit") | gsub("win32"; "Windows 32-bit") | gsub("linux-old"; "Linux Old") | gsub("linux"; "Linux") | gsub("macos"; "macOS")),
                "os": .os,
                "arch": .arch,
                "shell": .shell,
                "ext": .ext,
                "nuitka_args": .nuitka_args,
                "data_files": .data_files,
                "cache_path": .cache_path,
                "system_deps": .system_deps,
                "_source": ._source
              }')
              MATRIX_JSON=$(echo "$MATRIX_JSON" | jq --argjson item "$item" '.include += [$item]')
            fi
          done

          # 输出
          BUILD_COUNT=$(echo "$MATRIX_JSON" | jq '.include | length')
          COMPACT_MATRIX=$(echo "$MATRIX_JSON" | jq -c .)
          echo "matrix=$COMPACT_MATRIX" >> "$GITHUB_OUTPUT"

          # 摘要
          echo "summary<<EOF" >> "$GITHUB_OUTPUT"
          echo "主脚本: ${{ steps.detect.outputs.main_script }}" >> "$GITHUB_OUTPUT"
          echo "Python版本: ${{ steps.matrix.outputs.python_versions }}" >> "$GITHUB_OUTPUT"
          echo "版本号: ${{ steps.version.outputs.version }}" >> "$GITHUB_OUTPUT"
          echo "构建平台数: $BUILD_COUNT" >> "$GITHUB_OUTPUT"
          echo "" >> "$GITHUB_OUTPUT"
          echo "配置来源:" >> "$GITHUB_OUTPUT"
          echo "$MATRIX_JSON" | jq -r '.include[] | "  \(.id): \(._source)"' >> "$GITHUB_OUTPUT"
          echo "EOF" >> "$GITHUB_OUTPUT"

          echo "=== 最终构建矩阵 ==="
          echo "$MATRIX_JSON" | jq .

  # =========================================================================
  # 统一构建阶段
  # =========================================================================
  build:
    needs: prepare
    if: ${{ fromJSON(needs.prepare.outputs.build_matrix).include[0] != null }}
    runs-on: ${{ matrix.build.os }}
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix: 
        build: ${{ fromJSON(needs.prepare.outputs.build_matrix).include }}
        python-version: ${{ fromJSON(needs.prepare.outputs.python_matrix) }}
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          architecture: ${{ matrix.build.arch }}

      - name: Cache pip dependencies
        uses: actions/cache@v4
        with:
          path: ${{ matrix.build.cache_path }}
          key: ${{ matrix.build.id }}-py${{ matrix.python-version }}-${{ hashFiles('**/requirements.txt') }}
          restore-keys: ${{ matrix.build.id }}-py${{ matrix.python-version }}-

      - name: Install system dependencies (Linux only)
        if: ${{ startsWith(matrix.build.id, 'linux') }}
        shell: bash
        run: |
          sudo apt-get update
          sudo apt-get install -y ${{ matrix.build.system_deps }}

      - name: Install Python dependencies (Unix)
        if: ${{ matrix.build.shell == 'bash' }}
        shell: bash
        run: |
          pip install --upgrade pip
          pip install nuitka zstandard
          if [ -f requirements.txt ]; then
            pip install -r requirements.txt
          fi

      - name: Install Python dependencies (Windows)
        if: ${{ matrix.build.shell == 'pwsh' }}
        shell: pwsh
        run: |
          pip install --upgrade pip
          pip install nuitka zstandard
          if (Test-Path requirements.txt) { pip install -r requirements.txt }

      - name: Check for icon file (Windows only)
        if: ${{ startsWith(matrix.build.id, 'win') }}
        id: check_icon
        shell: pwsh
        run: |
          if (Test-Path file.ico) {
            "HAS_ICON=true" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          } else {
            "HAS_ICON=false" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          }

      # =========================================================================
      # 构建步骤 - 使用配置中的 Nuitka 参数
      # =========================================================================
      - name: Build with Nuitka (Unix)
        if: ${{ matrix.build.shell == 'bash' }}
        shell: bash
        run: |
          # 从配置读取 Nuitka 参数数组并展开
          NUITKA_ARGS=$(echo '${{ toJson(matrix.build.nuitka_args) }}' | jq -r '.[]' | xargs)
          
          # 构建数据文件参数
          DATA_FILES=""
          for file in $(echo '${{ toJson(matrix.build.data_files) }}' | jq -r '.[]'); do
            if [ -f "$file" ]; then
              DATA_FILES="$DATA_FILES --include-data-file=$file=$file"
            fi
          done
          
          OUTPUT_NAME="${{ github.event.repository.name }}-${{ matrix.build.id }}-py${{ matrix.python-version }}"
          
          echo "🚀 执行 Nuitka 构建 [${{ matrix.build._source }}]"
          echo "完整命令: nuitka $NUITKA_ARGS --output-dir=dist --output-filename=$OUTPUT_NAME${{ matrix.build.ext }} $DATA_FILES ${{ needs.prepare.outputs.main_script }}"
          
          # 执行构建
          nuitka $NUITKA_ARGS \
            --output-dir=dist \
            --output-filename="$OUTPUT_NAME${{ matrix.build.ext }}" \
            $DATA_FILES \
            ${{ needs.prepare.outputs.main_script }}

      - name: Build with Nuitka (Windows)
        if: ${{ matrix.build.shell == 'pwsh' }}
        shell: pwsh
        run: |
          # 从配置读取 Nuitka 参数数组
          $nuitkaArgs = '${{ toJson(matrix.build.nuitka_args) }}' | ConvertFrom-Json
          
          # 构建数据文件参数
          $dataFiles = @()
          $files = '${{ toJson(matrix.build.data_files) }}' | ConvertFrom-Json
          foreach ($file in $files) {
            if (Test-Path $file) {
              $dataFiles += "--include-data-file=$file=$file"
            }
          }
          
          # Windows 特殊处理：动态添加图标（如果存在且配置中未指定）
          $hasIconFlag = $nuitkaArgs | Where-Object { $_ -match "--windows-icon-from-ico" }
          if (-not $hasIconFlag -and "${{ steps.check_icon.outputs.HAS_ICON }}" -eq "true") {
            $nuitkaArgs += "--windows-icon-from-ico=file.ico"
          }
          
          $argString = $nuitkaArgs -join " "
          $dataString = $dataFiles -join " "
          $outputName = "${{ github.event.repository.name }}-${{ matrix.build.id }}-py${{ matrix.python-version }}"
          
          Write-Host "🚀 执行 Nuitka 构建 [${{ matrix.build._source }}]"
          Write-Host "完整命令: nuitka $argString --output-dir=dist --output-filename=$outputName${{ matrix.build.ext }} $dataString ${{ needs.prepare.outputs.main_script }}"
          
          # 执行构建
          $cmd = "nuitka $argString --output-dir=dist --output-filename=$outputName${{ matrix.build.ext }} $dataString ${{ needs.prepare.outputs.main_script }}"
          Invoke-Expression $cmd

      - name: Collect build artifacts (Unix)
        if: ${{ matrix.build.shell == 'bash' }}
        shell: bash
        run: |
          mkdir -p release-artifacts
          cp dist/*${{ matrix.build.ext }} release-artifacts/ 2>/dev/null || true
          
          DIST_DIR="dist/${{ github.event.repository.name }}-${{ matrix.build.id }}-py${{ matrix.python-version }}.dist"
          if [ -d "$DIST_DIR" ]; then
            tar -czf "release-artifacts/${{ github.event.repository.name }}-${{ matrix.build.id }}-py${{ matrix.python-version }}-full.tar.gz" -C "$DIST_DIR" .
          fi

      - name: Collect build artifacts (Windows)
        if: ${{ matrix.build.shell == 'pwsh' }}
        shell: pwsh
        run: |
          New-Item -ItemType Directory -Force -Path "release-artifacts"
          Copy-Item "dist\*${{ matrix.build.ext }}" "release-artifacts\" -ErrorAction SilentlyContinue
          
          $distDir = "dist\${{ github.event.repository.name }}-${{ matrix.build.id }}-py${{ matrix.python-version }}.dist"
          if (Test-Path $distDir) {
            $zipPath = "release-artifacts\${{ github.event.repository.name }}-${{ matrix.build.id }}-py${{ matrix.python-version }}-full.zip"
            Compress-Archive -Path "$distDir\*" -DestinationPath $zipPath -Force
          }

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.build.id }}-py${{ matrix.python-version }}
          path: release-artifacts/*
          if-no-files-found: error

  # =========================================================================
  # Release发布阶段
  # =========================================================================
  release:
    needs: [prepare, build]
    runs-on: ubuntu-latest
    permissions:
      contents: write
    if: |
      always() && 
      needs.prepare.result == 'success' && 
      needs.prepare.outputs.should_release == 'true' &&
      needs.build.result == 'success'
    
    steps:
      - name: Download all build artifacts
        uses: actions/download-artifact@v4
        with:
          path: all-artifacts
          pattern: '*-py*'
          merge-multiple: false

      - name: Organize release assets
        shell: bash
        run: |
          mkdir -p release-assets
          
          for artifact_dir in all-artifacts/*/; do
            if [ -d "$artifact_dir" ]; then
              platform=$(basename "$artifact_dir")
              for file in "$artifact_dir"/*; do
                if [ -f "$file" ]; then
                  filename=$(basename "$file")
                  cp "$file" "release-assets/${filename}"
                fi
              done
            fi
          done
          
          ls -lh release-assets/

      - name: Create Release and Upload Assets
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ needs.prepare.outputs.version }}
          name: Release ${{ needs.prepare.outputs.version }}
          body: |
            ## 构建配置
            ${{ needs.prepare.outputs.build_summary }}
            
            ## 使用说明
            单文件版本直接运行，完整版本解压后运行。
          generate_release_notes: true
          files: release-assets/*
          fail_on_unmatched_files: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}