# cargo-packager

## 项目概述

应用打包工具，支持生成多种平台安装包。是从 Tauri 框架剥离出来的独立打包工具。

**本地路径**: `vendors/cargo-packager`

## 目录结构

```
cargo-packager/
├── Cargo.toml                    # workspace 配置
├── packager/                     # 打包核心
│   └── src/
│       ├── lib.rs
│       ├── config.rs             # 配置
│       ├── package.rs            # 打包逻辑
│       └── utils.rs              # 工具函数
├── config/                       # 配置定义
│   └── src/
│       └── lib.rs
├── resource-resolver/            # 资源解析
│   └── src/
│       └── lib.rs
├── updater/                      # 自动更新
│   └── src/
│       └── lib.rs
├── codesign/                     # 代码签名
│   └── src/
│       └── lib.rs
├── package/
│   ├── deb/                      # Debian 包
│   ├── appimage/                 # AppImage
│   ├── dmg/                      # macOS DMG
│   ├── msi/                      # Windows MSI
│   └── nsis/                     # Windows NSIS
└── Cargo.toml
```

## 核心依赖

```toml
[dependencies]
serde = "1.0"
serde_json = "1.0"
toml = "0.7"
clap = { version = "4.0", features = ["derive"] }
schemars = "0.8"
tracing = "0.1"
tar = "0.4"
zip = "0.6"
napi = { version = "2.0", optional = true }
dirs = "5.0"
semver = "1.0"
url = "2.4"
thiserror = "1.0"
```

## 核心 API

### Config

```rust
// config/src/lib.rs

pub struct PackageConfig {
    pub product_name: String,
    pub version: String,
    pub description: Option<String>,
    pub homepage: Option<String>,
    pub default_author: Option<String>,
    pub icons: Vec<IconConfig>,
    pub resources: Vec<ResourceConfig>,
    pub bin: Vec<BinConfig>,
    pub i18n: Vec<I18nConfig>,
}

pub struct Config {
    pub package: PackageConfig,
    pub formats: Vec<PackageFormat>,
    pub signing: Option<SigningConfig>,
    pub windows: Option<WindowsConfig>,
    pub macos: Option<MacosConfig>,
    pub linux: Option<LinuxConfig>,
}
```

### PackageFormat

```rust
pub enum PackageFormat {
    /// Windows MSI
    Msi(WindowsMsiConfig),
    /// Windows NSIS
    Nsis(WindowsNsisConfig),
    /// macOS DMG
    Dmg(MacosDmgConfig),
    /// macOS Bundle
    Bundle(MacosBundleConfig),
    /// Linux Deb
    Deb(DebConfig),
    /// Linux AppImage
    AppImage(AppImageConfig),
}
```

### 使用示例

```rust
use cargo_packager::{Config, PackageFormat};

#[tokio::main]
async fn main() -> Result<()> {
    let config = Config {
        package: PackageConfig {
            product_name: "qiming-agent".to_string(),
            version: "1.0.0".to_string(),
            description: Some("Agent Client".to_string()),
            homepage: Some("https://example.com".to_string()),
            default_author: Some("Author <author@example.com>".to_string()),
            icons: vec![IconConfig::Path {
                path: "icons/icon.png".into(),
            }],
            resources: vec![ResourceConfig {
                patterns: vec!["assets/**/*".into()],
                target: None,
            }],
            bin: vec![],
            i18n: vec![],
        },
        formats: vec![
            PackageFormat::Msi(WindowsMsiConfig::default()),
            PackageFormat::Dmg(MacosDmgConfig::default()),
            PackageFormat::Deb(DebConfig::default()),
            PackageFormat::AppImage(AppImageConfig::default()),
        ],
        signing: Some(SigningConfig {
            identity: None,
            digest: Some(DigestAlgorithm::Sha256),
            timestamp: Some(TimestampConfig::default()),
            ..Default::default()
        }),
        windows: Some(WindowsConfig {
            signing_config: Some(SigningConfig::default()),
            ..Default::default()
        }),
        macos: Some(MacosConfig {
            signing_config: Some(SigningConfig::default()),
            provider: None,
        }),
        linux: Some(LinuxConfig {
            package: LinuxPackageFormatConfig::default(),
            ..Default::default()
        }),
    };

    // 执行打包
    cargo_packager::package(&config).await?;

    Ok(())
}
```

## 自动更新配置

```rust
pub struct UpdaterConfig {
    /// 启用自动更新
    pub active: bool,
    /// 更新端点 URL 模板
    pub endpoints: Option<Vec<String>>,
    /// 公钥
    pub pubkey: String,
    /// 苹果开发者 ID
    pub apple_id: Option<String>,
    /// Windows 证书
    pub windows: Option<WindowsUpdaterConfig>,
}

impl UpdaterConfig {
    /// 默认端点模板
    pub fn default_endpoints(&self, target: &str) -> Vec<String> {
        vec![
            format!("https://updates.example.com/update/{target}/{version}"),
            format!("https://updates.example.com/update/{target}/{version}-{target}.{extension}"),
        ]
    }
}
```

## 与 agent-client 集成场景

### 场景1：完整的打包配置

```rust
// build.rs 或打包脚本

use cargo_packager::{Config, PackageFormat, PackageConfig};
use cargo_packager::config::{MacosDmgConfig, WindowsMsiConfig, DebConfig, AppImageConfig};

pub async fn build_packages() -> Result<()> {
    let version = env!("CARGO_PKG_VERSION");
    let app_name = "qiming-agent";

    let config = Config {
        package: PackageConfig {
            product_name: app_name.to_string(),
            version: version.to_string(),
            description: Some("Cross-platform AI Agent Client".to_string()),
            homepage: Some("https://example.com".to_string()),
            default_author: Some("qiming <support@example.com>".to_string()),
            icons: vec![
                IconConfig::Path {
                    path: "assets/icons/icon.png".into(),
                },
                IconConfig::Path {
                    path: "assets/icons/icon.ico".into(),
                },
                IconConfig::Path {
                    path: "assets/icons/icon.icns".into(),
                },
            ],
            resources: vec![
                ResourceConfig {
                    patterns: vec![
                        "assets/**/*".into(),
                        "locales/**/*".into(),
                    ],
                    target: None,
                },
            ],
            bin: vec![],
            i18n: vec![],
        },
        formats: vec![
            PackageFormat::Msi(WindowsMsiConfig {
                // MSI 配置
                database_path: Some("assets/wix/database.wxs".into()),
                ..Default::default()
            }),
            PackageFormat::Dmg(MacosDmgConfig {
                // DMG 配置
                background: Some("assets/dmg/background.png".into()),
                ..Default::default()
            }),
            PackageFormat::Deb(DebConfig {
                // Debian 包配置
                priority: Some("optional".to_string()),
                section: Some("utils".to_string()),
                ..Default::default()
            }),
            PackageFormat::AppImage(AppImageConfig {
                // AppImage 配置
                ..Default::default()
            }),
        ],
        signing: Some(SigningConfig {
            identity: std::env::var("SIGNING_IDENTITY").ok(),
            digest: Some(DigestAlgorithm::Sha256),
            timestamp: Some(TimestampConfig {
                server: Some("http://timestamp.digicert.com".to_string()),
            }),
            ..Default::default()
        }),
        windows: Some(WindowsConfig {
            signing_config: Some(SigningConfig {
                identity: std::env::var("WINDOWS_CERT").ok(),
                ..Default::default()
            }),
            ..Default::default()
        }),
        macos: Some(MacosConfig {
            signing_config: Some(SigningConfig {
                identity: std::env::var("APPLE_SIGNING_ID").ok(),
                provider: std::env::var("APPLE_PROVIDER").ok(),
            }),
            ..Default::default()
        }),
        linux: Some(LinuxConfig {
            package: LinuxPackageFormatConfig::default(),
            ..Default::default()
        }),
    };

    // 执行打包
    cargo_packager::package(&config).await?;

    Ok(())
}
```

### 场景2：CI/CD 集成

```yaml
# .github/workflows/release.yml

name: Release

on:
  release:
    types: [created]

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            targets: deb,appimage
          - os: macos-latest
            targets: dmg
          - os: windows-latest
            targets: msi

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          target: ${{ matrix.target == 'deb' && 'x86_64-unknown-linux-gnu' || 'x86_64-apple-darwin' }}

      - name: Build
        run: cargo build --release

      - name: Package
        run: |
          cargo run --package cargo-packager -- --package-format ${{ matrix.targets }}

      - name: Sign macOS
        if: matrix.os == 'macos-latest'
        run: |
          echo "${{ secrets.APPLE_CERT }}" | base64 -d > certificate.p12
          security create-keychain -p password build.keychain
          security default-keychain -s build.keychain
          security unlock-keychain -p password build.keychain
          security import certificate.p12 -P "" -A -t cert -f pkcs12 -k build.keychain
          codesign --deep --force --sign "${{ secrets.APPLE_SIGNING_ID }}" target/release/qiming-agent

      - name: Sign Windows
        if: matrix.os == 'windows-latest'
        run: |
          & "C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64\signtool.exe" sign /f certificate.pfx /p ${{ secrets.WINDOWS_CERT_PASSWORD }} /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /v target/release/qiming-agent-*.msi

      - name: Upload Assets
        uses: softprops/action-gh-release@v1
        with:
          files: |
            target/release/qiming-agent-*.msi
            target/release/qiming-agent-*.dmg
            target/release/qiming-agent-*.deb
            target/release/qiming-agent-*.AppImage
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### 场景3：自动更新配置

```rust
// 打包时生成更新配置

pub struct UpdaterConfig {
    /// 更新服务器地址
    pub update_url: String,

    /// 公钥（用于签名验证）
    pub public_key: String,

    /// 是否启用自动更新
    pub enable_auto_update: bool,
}

impl UpdaterConfig {
    /// 生成更新配置模板
    pub fn generate_app_config(&self) -> String {
        format!(r#"
[updater]
enabled = {}
url = "{}"
"#, self.enable_auto_update, self.update_url)
    }

    /// 获取更新端点
    pub fn get_update_endpoints(&self, version: &str, target: &str) -> Vec<String> {
        vec![
            format!("{}/{}/{}/qiming-agent_{}_{}.{}",
                self.update_url, version, target, version, target, self.extension(target)),
        ]
    }

    fn extension(target: &str) -> &str {
        match target {
            _ if target.contains("windows") => "msi",
            _ if target.contains("darwin") => "dmg",
            _ if target.contains("linux") => if target.contains("deb") { "deb" } else { "AppImage" },
            _ => "tar.gz",
        }
    }
}
```

### 场景4：资源文件处理

```rust
// 打包时的资源处理

pub struct ResourceProcessor {
    // 资源目录
    resource_dir: PathBuf,
    // 输出目录
    output_dir: PathBuf,
}

impl ResourceProcessor {
    pub fn new(resource_dir: &str, output_dir: &str) -> Self {
        Self {
            resource_dir: PathBuf::from(resource_dir),
            output_dir: PathBuf::from(output_dir),
        }
    }

    /// 处理所有资源
    pub async fn process(&self) -> Result<Vec<ResourceFile>> {
        let mut resources = Vec::new();

        // 1. 图标资源
        resources.extend(self.process_icons().await?);

        // 2. 翻译文件
        resources.extend(self.process_locales().await?);

        // 3. 配置文件
        resources.extend(self.process_configs().await?);

        Ok(resources)
    }

    async fn process_icons(&self) -> Result<Vec<ResourceFile>> {
        let icons_dir = self.resource_dir.join("icons");
        let mut icons = Vec::new();

        for entry in fs::read_dir(&icons_dir)? {
            let entry = entry?;
            let path = entry.path();

            if path.extension().map(|e| e == "png" || e == "ico" || e == "icns").unwrap_or(false) {
                icons.push(ResourceFile {
                    source: path.clone(),
                    target: format!("icons/{}", path.file_name().unwrap()),
                });
            }
        }

        Ok(icons)
    }

    async fn process_locales(&self) -> Result<Vec<ResourceFile>> {
        let locales_dir = self.resource_dir.join("locales");
        let mut locales = Vec::new();

        for entry in fs::read_dir(&locales_dir)? {
            let entry = entry?;
            let path = entry.path();

            if path.extension().map(|e| e == "json").unwrap_or(false) {
                locales.push(ResourceFile {
                    source: path.clone(),
                    target: format!("locales/{}", path.file_name().unwrap()),
                });
            }
        }

        Ok(locales)
    }
}
```

## 在本项目中的使用

用于打包 agent-client 为各平台安装包：

```
agent-client
    │
    ├── cargo-packager
    │       │
    │       ├── Windows MSI/NSIS 安装包
    │       ├── macOS DMG 磁盘镜像
    │       ├── Linux Deb 包
    │       └── Linux AppImage
    │
    └── 资源文件
            ├── icons/ (应用图标)
            ├── locales/ (多语言)
            └── assets/ (其他资源)
```

## 打包命令

```bash
# CLI 打包
cargo-packager --package-format msi,dmg,deb,appimage

# 代码调用
cargo_packager::package(&config).await?;

# 单独平台打包
cargo-packager --package-format msi          # Windows
cargo-packager --package-format dmg          # macOS
cargo-packager --package-format deb          # Linux Deb
cargo-packager --package-format appimage     # Linux AppImage
```