@chengyu08/ipa-cli 0.2.1 → 0.2.3

package/README.md

@@ -18,6 +18,7 @@
 - 基于本地基线库执行 Top N 相似检索
 - 执行 `analyze + scan + Top1 compare` 的端到端冒烟检查
 - 使用 Apple Transporter 将 IPA 真实上传到 App Store Connect
+- 初始化 GitHub Actions iOS IPA 构建模板、签名材料目录和 Secrets 说明
 - 生成、校验和批量渲染 App Store 上架图
 - 批量扫描当前目录或多个子项目中的静态图片风险
 - 输出机器可消费的静态图片整改清单 JSON
@@ -75,12 +76,11 @@ ipa-cli compare ./AppA.ipa ./AppB.ipa --format panel
 # 3) 做一次完整冒烟检查
 ipa-cli smoke ./YourApp.ipa --library ./data/library --format text
 
-# 4) 预检并准备上传到 App Store Connect
-ipa-cli upload ./YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --asset-description ./AppStoreInfo.plist \
-  --dry-run
+# 4) 直接接收 Xcode 导出目录，默认 verify 后再 upload
+ipa-cli upload ./dist/export
+
+# 5) 初始化 GitHub Actions iOS 构建模板
+ipa-cli actions init-ios-build ./YourProject
 ```
 
 如果你还没有全局安装，也可以把上面的 `ipa-cli` 替换成 `npx @chengyu08/ipa-cli`。
@@ -190,218 +190,341 @@ ipa-cli assets review . --scope children --format panel
 
 ### 9. 上传 IPA 到 App Store Connect
 
-这一节给出最常用的上传操作流程。后文 `upload` 命令说明里会再展开每个参数的含义、边界和更多示例。
+这一节只讲推荐做法：把 Xcode 导出目录直接交给 `ipa-cli`，让工具自动完成本地预检、Apple verify 和正式上传。
+
+推荐的目录结构如下：
+
+```text
+dist/export/
+  YourApp.ipa
+  AppStoreInfo.plist
+```
+
+如果你的导出目录里只有下面这些文件：
+
+```text
+dist/export/
+  YourApp.ipa
+  ExportOptions.plist
+  DistributionSummary.plist
+```
+
+那还不够。它们的作用不同：
+
+- `ExportOptions.plist`
+  这是 Xcode 导出时使用的配置文件，描述导出方式和签名选项
+- `DistributionSummary.plist`
+  这是导出结果摘要，主要记录签名、provisioning、entitlements 等信息
+- `AppStoreInfo.plist`
+  这是给 Apple Transporter 上传 IPA 时使用的描述文件
 
-推荐按下面顺序操作：
+`ExportOptions.plist` 和 `DistributionSummary.plist` 不能替代 `AppStoreInfo.plist`。
 
-1. 先准备好 `.ipa`、账号凭据，以及 Linux / Windows 必需的 `AppStoreInfo.plist`
-2. 先跑一次 `--dry-run`，确认命令拼装、路径和认证方式都正确
-3. 再跑一次 `--verify-only`，让 Apple Transporter 先做真实预校验
-4. 最后执行正式上传
+推荐流程：
+
+1. 先配置一次环境变量
+2. 之后直接执行 `ipa-cli upload ./dist/export`
+3. 默认流程会自动执行 `verify -> upload`
 
 开始前请确认：
 
 - App 已经在 App Store Connect 中创建，Bundle ID 与待上传构建一致
 - 账号角色具备上传构建版本权限
-- IPA 是 Xcode 导出的正式构建产物，而不是随手打包的临时文件
-- Linux / Windows 上传时，必须同时提供 Xcode 导出的 `AppStoreInfo.plist`
+- 输入优先使用 Xcode 导出目录，不建议手工分开传 `.ipa` 和 `AppStoreInfo.plist`
+- Linux / Windows 上传时，导出目录中必须包含 `AppStoreInfo.plist`
 - 如果使用 API key，Account Holder 需要先在 App Store Connect 开通 API 访问并生成 key
 
-认证方式建议如下：
+推荐的环境变量：
+
+```bash
+# Apple ID 方式
+export ASC_APPLE_ID="dev@example.com"
+export ASC_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+
+# API key 方式
+export ASC_API_KEY="ABCD123456"
+export ASC_API_ISSUER="57246542-96fe-1a63-e053-0824d011072a"
+export ASC_PRIVATE_KEY_FILE="./AuthKey_ABCD123456.p8"
+
+# 可选
+export ASC_PROVIDER="ExampleProvider"
+export ASC_TRANSPORTER_PATH="/usr/local/itms/bin/iTMSTransporter"
+```
+
+### 9.1 先确认你有没有 `AppStoreInfo.plist`
+
+如果你是通过 Xcode Organizer 直接点导出，目录里不一定会自动出现 `AppStoreInfo.plist`。Apple 官方说明里明确提到，这个文件会在你使用 `xcodebuild` 导出，并且开启 `generateAppStoreInformation=YES` 时生成。
+
+对于 Flutter 项目，最稳妥的做法不是猜 Flutter 导出目录里会不会顺带出现它，而是显式走这条链路：
+
+1. `flutter build ipa` 先生成 `.xcarchive`
+2. `xcodebuild -exportArchive` 再按 `ExportOptions.plist` 导出
+3. 在导出目录里检查 `AppStoreInfo.plist`
+
+一个最直接的做法是：
+
+1. 准备一个 `ExportOptions.plist`
+2. 确保其中包含 `generateAppStoreInformation`
+3. 用 `xcodebuild -exportArchive` 导出
+
+仓库里已经放了一份可直接复制的模板：
+
+```text
+scripts/ExportOptions.app-store.example.plist
+```
+
+你可以先复制它：
 
-- 本地手工上传：优先用 `--username + --password-env`
-- CI 或自动化：优先用 `--api-key + --api-issuer + --private-key-file`
-- 已有外部签发 JWT：直接用 `--jwt`
+```bash
+cp ./scripts/ExportOptions.app-store.example.plist ./ios/ExportOptions.plist
+```
 
-### 9.1 先做 dry-run
+示例 `ExportOptions.plist`：
 
-先让 CLI 做本地预检，确认它能识别 IPA、认证方式、Transporter 路径和 `AppStoreInfo.plist`，但不会真正调用 Apple 上传。
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>method</key>
+  <string>app-store</string>
+  <key>signingStyle</key>
+  <string>automatic</string>
+  <key>generateAppStoreInformation</key>
+  <true/>
+</dict>
+</plist>
+```
 
-Apple ID 示例：
+示例导出命令：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --asset-description ./AppStoreInfo.plist \
-  --dry-run
+xcodebuild -exportArchive \
+  -archivePath ./build/YourApp.xcarchive \
+  -exportPath ./dist/export \
+  -exportOptionsPlist ./ExportOptions.plist
 ```
 
-API key 示例：
+导出完成后，检查：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --private-key-file ./AuthKey_ABCD123456.p8 \
-  --asset-description ./AppStoreInfo.plist \
-  --dry-run
+ls -la ./dist/export
 ```
 
-你会看到一段“上传预检”摘要，包括：
+理想情况下你会看到：
 
-- 应用名、Bundle ID、Version、Build
-- 当前使用的 Transporter 模式：`upload` 或 `verify`
-- 当前认证方式：`apple-id`、`api-key` 或 `jwt`
-- `Transporter` 可执行文件路径
-- `Asset Description` 和 `Event File` 路径
+```text
+YourApp.ipa
+AppStoreInfo.plist
+ExportOptions.plist
+DistributionSummary.plist
+```
 
-### 9.2 再做 Apple 官方预校验
+如果没有 `AppStoreInfo.plist`，当前仓库的 `upload` 命令会直接告诉你：`ExportOptions.plist` 和 `DistributionSummary.plist` 不能替代它，并提示你重新导出。
 
-如果你希望在正式上传前就拿到 Apple 侧的校验结果，使用 `--verify-only`。这会调用 Apple Transporter 的 `verify` 模式，不执行真正上传。
+#### Flutter 项目推荐步骤
 
-只校验 metadata：
+假设你在 Flutter 项目根目录下操作，推荐顺序如下。
+
+第一步，复制模板：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --verify-only \
-  --metadata-only \
-  --event-file ./transporter-events.json \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --private-key-file ./AuthKey_ABCD123456.p8 \
-  --asset-description ./AppStoreInfo.plist
+cp ./scripts/ExportOptions.app-store.example.plist ./ios/ExportOptions.plist
 ```
 
-校验 metadata 和 assets：
+第二步，先生成 archive：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --verify-only \
-  --event-file ./transporter-events.json \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --private-key-file ./AuthKey_ABCD123456.p8 \
-  --asset-description ./AppStoreInfo.plist
+flutter build ipa --release
 ```
 
-说明：
+Flutter 官方文档说明，这一步会生成：
 
-- `--verify-only` 会调用 Apple 官方 `verify` 模式
-- `--metadata-only` 只在 verify 模式下有效
-- `--event-file` 会把 Apple 结构化输出落到文件，便于 CI 归档和后处理
-- verify 成功不代表构建已经上传，只代表它通过了这一步预校验
+- `build/ios/archive/Runner.xcarchive`
+- `build/ios/ipa/*.ipa`
 
-### 9.3 再执行正式上传
+第三步，用 `xcodebuild` 重新导出，显式生成 `AppStoreInfo.plist`：
 
-Apple ID 上传：
+```bash
+xcodebuild -exportArchive \
+  -archivePath build/ios/archive/Runner.xcarchive \
+  -exportPath dist/export \
+  -exportOptionsPlist ios/ExportOptions.plist
+```
+
+第四步，检查导出目录：
+
+```bash
+ls -la dist/export
+```
+
+第五步，确认看到了：
+
+```text
+Runner.ipa
+AppStoreInfo.plist
+ExportOptions.plist
+DistributionSummary.plist
+```
+
+第六步，再交给 `ipa-cli`：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli upload ./dist/export
 ```
 
-如果你的账号关联多个 provider，可以补 `--provider`：
+如果你想在 Flutter 项目里把这套流程先只跑检查，不正式上传：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --provider ExampleProvider \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli upload ./dist/export --check-only
 ```
 
-API key 上传：
+如果你已经有自己的 `ExportOptions.plist`，也可以不使用仓库模板。关键只有一个：必须包含 `generateAppStoreInformation = YES`。
+
+### 9.2 最简单的正式上传
+
+环境变量已经配置好后，最简单的命令就是：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --private-key-file ./AuthKey_ABCD123456.p8 \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli upload ./dist/export
 ```
 
-如果你已经有 JWT，也可以直接上传：
+默认执行流程：
+
+1. 本地预检
+2. Apple `verify`
+3. Apple `upload`
+
+这也是现在最推荐的默认路径。用户不需要自己决定先 verify 还是先 upload。
+
+### 9.3 先做 dry-run
+
+第一次上手、刚换机器、或者刚调整凭据时，先跑：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --jwt "$ASC_JWT" \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli upload ./dist/export --dry-run
 ```
 
-上传成功后，CLI 只表示“上传请求已提交给 Apple”。构建通常还要经过 App Store Connect processing，稍后才会在后台可见。
+它不会调用 Apple，只会本地检查：
+
+- 目录里是否有唯一的 `.ipa`
+- 是否发现了 `AppStoreInfo.plist`
+- 当前会使用哪种认证方式
+- 当前准备执行哪些步骤
+- 当前要调用哪个 `iTMSTransporter`
 
-### 9.4 常见场景示例
+### 9.4 只做检查，不正式上传
 
-macOS 本地上传，省略 `AppStoreInfo.plist`：
+如果你想让 Apple 做真实预校验，但这次不想正式上传：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD
+ipa-cli upload ./dist/export --check-only
 ```
 
-说明：macOS 允许不传 `AppStoreInfo.plist`，但如果你本来就有 Xcode 导出的文件，仍然建议一起传入，行为更稳定。
+如果你只想检查 metadata：
 
-Linux 上传：
+```bash
+ipa-cli upload ./dist/export --check-only --metadata-only
+```
+
+如果你希望把 Apple 结构化输出写入文件，便于 CI 归档：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --private-key-file ./AuthKey_ABCD123456.p8 \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli upload ./dist/export \
+  --check-only \
+  --event-file ./artifacts/transporter-events.json
 ```
 
-Windows 上传并显式指定 Transporter 路径：
+### 9.5 跳过 verify，直接上传
+
+默认不建议这么做，但如果你非常确定不需要 verify，可以显式跳过：
 
 ```bash
-ipa-cli upload .\\YourApp.ipa ^
-  --transporter "C:\\Program Files (x86)\\itms\\iTMSTransporter.cmd" ^
-  --api-key ABCD123456 ^
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a ^
-  --private-key-file .\\AuthKey_ABCD123456.p8 ^
-  --asset-description .\\AppStoreInfo.plist
+ipa-cli upload ./dist/export --skip-verify
 ```
 
-API key 但不显式传私钥文件：
+### 9.6 常见场景示例
+
+macOS 本地最简单用法：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --asset-description ./AppStoreInfo.plist
+export ASC_APPLE_ID="dev@example.com"
+export ASC_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+
+ipa-cli upload ./dist/export
 ```
 
-说明：这种方式依赖 Transporter 自己按默认规则查找 `AuthKey_<keyId>.p8`。如果你希望命令行为更可控，建议始终显式传 `--private-key-file`。
+Linux CI 用 API key：
+
+```bash
+export ASC_API_KEY="ABCD123456"
+export ASC_API_ISSUER="57246542-96fe-1a63-e053-0824d011072a"
+export ASC_PRIVATE_KEY_FILE="./AuthKey_ABCD123456.p8"
+
+ipa-cli upload ./dist/export --check-only
+ipa-cli upload ./dist/export
+```
 
-CI 示例：
+Windows 显式指定 Transporter：
 
 ```bash
-export APPSTORE_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+set ASC_API_KEY=ABCD123456
+set ASC_API_ISSUER=57246542-96fe-1a63-e053-0824d011072a
+set ASC_PRIVATE_KEY_FILE=.\AuthKey_ABCD123456.p8
 
-ipa-cli upload ./build/YourApp.ipa \
-  --verify-only \
-  --event-file ./artifacts/transporter-events.json \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --asset-description ./build/AppStoreInfo.plist
+ipa-cli upload .\dist\export ^
+  --transporter "C:\Program Files (x86)\itms\iTMSTransporter.cmd"
+```
 
-ipa-cli upload ./build/YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --asset-description ./build/AppStoreInfo.plist
+仍然使用单个 IPA 文件：
+
+```bash
+ipa-cli upload ./dist/export/YourApp.ipa \
+  --asset-description ./dist/export/AppStoreInfo.plist
 ```
 
-### 9.5 安全建议
+说明：单个 `.ipa` 仍然支持，但为了简化用户心智，优先推荐直接传导出目录。
+
+如果你的账号关联多个 provider，可以继续补 `--provider`：
+
+```bash
+ipa-cli upload ./dist/export --provider ExampleProvider
+```
 
-- 优先使用 `--password-env`，不要把密码直接写死在 shell 历史里
+### 9.7 高级参数什么时候用
+
+- `--asset-description <path>`
+  当自动发现失败，或者你故意想覆盖默认 plist 时再传
+- `--event-file <path>`
+  适合 CI、日志归档和结构化后处理
+- `--transporter <path>`
+  适合 PATH 不稳定，或者机器上装了多个 Transporter 的场景
+- `--jwt <token>`
+  适合外部系统已经代你签发 JWT 的场景
+- `--verify-only`
+  旧行为兼容别名。新的主路径里优先使用 `--check-only`
+
+### 9.8 安全建议
+
+- 优先使用环境变量，不要把密码直接写死在命令历史里
 - 不要把 `.p8` 私钥提交到仓库
 - `--event-file` 中可能包含 Apple 结构化返回信息，建议和构建产物一起归档，但不要对外公开
 - 如果你在 CI 中使用 JWT，尽量设置短有效期，避免长期复用
 
-### 9.6 常见报错与处理
+### 9.9 常见报错与处理
 
 - `未找到 Apple Transporter`
   先安装 Apple Transporter，或者通过 `--transporter` 显式指定 `iTMSTransporter` 路径
+- `导出目录中未找到 .ipa 文件`
+  说明当前传入的目录不是 Xcode 标准导出目录，或者目录层级传错了
+- `导出目录中找到多个 .ipa 文件`
+  说明目录里放了多个导出产物。改成只保留一个，或者直接传入目标 `.ipa` 文件
 - `Linux / Windows 上传 App 时必须提供 --asset-description`
-  说明当前是非 macOS 环境，必须补上 Xcode 导出的 `AppStoreInfo.plist`
-- `--metadata-only 仅能和 --verify-only 一起使用`
-  说明你把 metadata-only 用在了正式上传模式，去掉它或者同时加上 `--verify-only`
+  说明当前目录里没有可用的 `AppStoreInfo.plist`，或者你传的是单个 `.ipa` 但没补 plist
+- `--metadata-only 不能和 --skip-verify 同时使用`
+  说明你把 metadata-only 用在了跳过 verify 的流程里
 - `必须提供一种上传认证方式`
-  说明当前没有提供 Apple ID、API key 或 JWT 中的任意一种
+  说明当前既没有命令行参数，也没有环境变量可用于上传认证
 - `上传认证方式只能选择一种`
   说明同时传了多套认证方式，例如 `--username` 和 `--api-key` 同时出现
 - `IPA 缺少 CFBundleIdentifier / CFBundleShortVersionString / CFBundleVersion`
@@ -472,6 +595,9 @@ cp ./scripts/ipatool.env.example ./scripts/ipatool.env
 - `scan`：把目标样本与本地基线库做 Top N 检索
 - `smoke`：执行 `analyze + scan + Top1 compare` 的端到端冒烟检查
 - `upload`：使用 Apple Transporter 将 IPA 上传到 App Store Connect
+- `actions init-ios-build`：初始化 GitHub Actions iOS 构建模板、签名目录和 Secrets 说明
+- `convert pdf-to-png`：将单个 PDF 文件转换为 PNG 图片
+- `convert png-to-pdf`：将单张 PNG 或目录内多张 PNG 合并为 PDF
 - `screenshots init-config`：初始化上架图工作区，生成配置、`raw/` 目录和说明文档
 - `screenshots from-ipa`：从 IPA 中提取候选图片并自动生成上架图
 - `screenshots from-simulator`：从 iOS 模拟器采集一张原始截图
@@ -643,103 +769,113 @@ ipa-cli smoke ./fingerprint.json --library ./data/library --format html
 
 ### `upload`
 
-使用 Apple Transporter 将 IPA 上传到 App Store Connect，或先调用 Apple 官方 `verify` 模式做真实预校验。
+接收单个 `.ipa` 文件或 Xcode 导出目录，自动完成本地预检、Apple verify 和正式上传。
 
 ```bash
-ipa-cli upload <ipa> [options]
+ipa-cli upload <input> [options]
 ```
 
-最常见的两种用法如下：
+参数：
 
-先做真实预校验：
+- `<input>`：单个 `.ipa` 文件，或包含 `.ipa` / `AppStoreInfo.plist` 的 Xcode 导出目录
+- `ExportOptions.plist` / `DistributionSummary.plist` 不能替代 `AppStoreInfo.plist`
+- `--check-only`：执行本地预检并调用 Apple verify，不执行正式上传
+- `--skip-verify`：跳过 Apple verify，直接上传
+- `--metadata-only`：只在 verify 流程中有效，只校验 metadata
+- `--transporter <path>`：显式指定 `iTMSTransporter` 路径
+- `--asset-description <path>`：显式指定 `AppStoreInfo.plist`；当自动发现失败时使用
+- `--event-file <path>`：输出 Apple 结构化事件文件；默认两步流程下会自动拆成 `*.verify.*` 和 `*.upload.*`
+- `--username <appleId>` / `--password-env <env>`：Apple ID 方式
+- `--api-key <keyId>` / `--api-issuer <issuerId>` / `--private-key-file <path>`：API key 方式
+- `--jwt <token>`：直接传入外部生成的 JWT
+- `--provider <shortName>`：Apple ID 多 provider 账号使用
+- `--dry-run`：只做本地预检并展示计划执行的步骤，不真正调用 Apple
+
+最推荐的用法：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --verify-only \
-  --event-file ./transporter-events.json \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --private-key-file ./AuthKey_ABCD123456.p8 \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli upload ./dist/export
 ```
 
-再做正式上传：
+只做检查：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --api-key ABCD123456 \
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a \
-  --private-key-file ./AuthKey_ABCD123456.p8 \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli upload ./dist/export --check-only
 ```
 
-参数：
+跳过 verify：
 
-- `<ipa>`：待上传的 `.ipa` 文件
-- `--verify-only`：调用 Apple Transporter `verify` 模式做真实预校验，不执行上传
-- `--metadata-only`：只在 verify 模式下有效，只校验 metadata，不校验 assets
-- `--transporter <path>`：显式指定 `iTMSTransporter` 路径
-- `--asset-description <path>`：Xcode 导出的 `AppStoreInfo.plist`；Linux / Windows 必填
-- `--event-file <path>`：保存 Apple 结构化事件输出，适合 CI 归档或后处理
-- `--username <appleId>`：Apple ID 登录方式
-- `--password <password>`：App 专用密码；更推荐 `--password-env`
-- `--password-env <env>`：从环境变量读取 App 专用密码
-- `--api-key <keyId>`：App Store Connect API key ID
-- `--api-issuer <issuerId>`：Team API key 对应的 issuer ID
-- `--private-key-file <path>`：`AuthKey_<keyId>.p8` 私钥文件；提供后 CLI 会本地生成 JWT
-- `--jwt <token>`：已生成好的 App Store Connect JWT
-- `--provider <shortName>`：仅 Apple ID 模式使用；多 provider 账号常需要
-- `--verbose`：把 Transporter 日志级别提升到 `eXtreme`
-- `--dry-run`：只做本地预检和命令预演，不执行 Apple 上传或 verify
+```bash
+ipa-cli upload ./dist/export --skip-verify
+```
 
-推荐操作顺序：
+第一次上手先跑 dry-run：
 
-1. 先跑 `--dry-run`，确认路径、认证方式和 `AppStoreInfo.plist` 没问题
-2. 再跑 `--verify-only`，拿到 Apple 官方预校验结果
-3. 最后执行正式上传
+```bash
+ipa-cli upload ./dist/export --dry-run
+```
 
-更多示例：
+如果你已经提前配置了 `ASC_APPLE_ID` / `ASC_APP_PASSWORD` 或 `ASC_API_KEY` / `ASC_API_ISSUER` / `ASC_PRIVATE_KEY_FILE`，通常不再需要重复传认证参数。
 
-Apple ID + 环境变量密码：
+### `actions`
+
+初始化 GitHub Actions iOS 构建模板，并生成签名材料目录、Secrets 模板和指导文档。
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli actions init-ios-build [path] [options]
 ```
 
-Apple ID + 多 provider：
+参数：
+
+- `[path]`：目标项目根目录，默认当前目录
+- `--bundle-id <id>`：覆盖自动检测到的 Bundle ID
+- `--xcode-workspace <path>`：workspace 路径，默认 `ios/Runner.xcworkspace`
+- `--xcode-project <path>`：`project.pbxproj` 路径，默认 `ios/Runner.xcodeproj/project.pbxproj`
+- `--scheme <name>`：Xcode scheme 名称，默认 `Runner`
+- `--workflow-file <name>`：workflow 文件名，默认 `ios-build.yml`
+- `--force`：覆盖已存在的初始化文件
+
+示例：
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --username dev@example.com \
-  --password-env APPSTORE_PASSWORD \
-  --provider ExampleProvider \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli actions init-ios-build ./YourProject
+ipa-cli actions init-ios-build ./YourProject --bundle-id com.example.app --scheme MyApp
 ```
 
-direct JWT：
+生成后会得到：
+
+- `.github/workflows/ios-build.yml`
+- `ci/github-actions/ios-build/README.md`
+- `ci/github-actions/ios-build/secrets.example.env`
+- `ci/github-actions/ios-build/signing/`
+
+其中 README 会明确写出：
+
+- `.cer`、`.p12`、`.mobileprovision` 分别放哪里
+- 哪些 GitHub Secrets 需要创建
+- 每个 Secret 的值从哪里来
+- 如何用 `print-secrets.sh` 自动生成 base64 值
+
+### `convert`
+
+执行 PDF 与 PNG 之间的格式转换。
 
 ```bash
-ipa-cli upload ./YourApp.ipa \
-  --jwt "$ASC_JWT" \
-  --asset-description ./AppStoreInfo.plist
+ipa-cli convert pdf-to-png <input> [--output <path>] [--scale <n>] [--overwrite] [--format text|json]
+ipa-cli convert png-to-pdf <input> [--output <file>] [--overwrite] [--format text|json]
 ```
 
-Windows 显式指定 Transporter：
+- `pdf-to-png`：把单个 PDF 转成 PNG。单页 PDF 默认输出同名 `.png`；多页 PDF 默认输出到同级 `<name>-png/` 目录。
+- `png-to-pdf`：把单张 PNG 或目录内多张 PNG 合并为 PDF。目录模式会递归收集 `.png` 文件，并按路径排序后逐页写入。
+
+示例：
 
 ```bash
-ipa-cli upload .\\YourApp.ipa ^
-  --transporter "C:\\Program Files (x86)\\itms\\iTMSTransporter.cmd" ^
-  --api-key ABCD123456 ^
-  --api-issuer 57246542-96fe-1a63-e053-0824d011072a ^
-  --private-key-file .\\AuthKey_ABCD123456.p8 ^
-  --asset-description .\\AppStoreInfo.plist
+ipa-cli convert pdf-to-png ./docs/design.pdf --output ./docs/design-pages --scale 2
+ipa-cli convert png-to-pdf ./screens --output ./screens.pdf
+ipa-cli convert png-to-pdf ./poster.png --format json
 ```
 
-如果你只是想先判断当前包“能不能过 Transporter 这一关”，优先用 `--verify-only`。如果 verify 成功，再执行正式上传，失败定位会更清楚。
-
 ### `screenshots`
 
 生成、渲染并校验 App Store 上架图。README 已内置完整用法说明，不需要跳转外部文档也能查看命令、配置字段和目录约定。
@@ -747,7 +883,7 @@ ipa-cli upload .\\YourApp.ipa ^
 当前支持的子命令：
 
 ```bash
-ipa-cli screenshots init-config [path] [--force]
+ipa-cli screenshots init-config [path] [--force] [--template <id>] [--background-template <id>] [--layout-template <id>] [--device-frame-template <id>] [--list-templates]
 ipa-cli screenshots from-ipa <ipa> [--workspace <dir>] [--output <dir>] [--locale <locale>] [--target <target>] [--max-frames <n>] [--dry-run] [--overwrite] [--format text|json|panel]
 ipa-cli screenshots from-simulator [app] --output <file> [--device <name>] [--udid <udid>] [--bundle-id <id>] [--wait <ms>] [--overwrite] [--format text|json|panel]
 ipa-cli screenshots check [dir] [--platform ios] [--locale <locale>] [--strict] [--fingerprint <file>] [--format text|json|panel]
@@ -795,6 +931,9 @@ ipa-cli screenshots init-config [path] [--force]
 ipa-cli screenshots init-config
 ipa-cli screenshots init-config ./configs/appstore.screenshot.config.json --force
 ipa-cli screenshots init-config ./screenshots-workspace
+ipa-cli screenshots init-config ./screenshots-workspace --template marketing
+ipa-cli screenshots init-config ./screenshots-workspace --background-template image-hero --layout-template device-with-title --device-frame-template iphone-dark-03
+ipa-cli screenshots init-config --list-templates
 ```
 
 默认会同时生成：
@@ -805,6 +944,34 @@ ipa-cli screenshots init-config ./screenshots-workspace
 
 如果参数传的是目录，例如 `./screenshots-workspace`，这些文件会生成在该目录下；如果参数传的是 `.json` 文件路径，则会生成在该配置文件所在目录下。默认模板会先生成 `targets: ["iphone-6.5"]`。这个槽位的可接受尺寸是 `1242 × 2688px`、`2688 × 1242px`、`1284 × 2778px`、`2778 × 1284px`，当前默认竖屏输出优先使用 `1284 × 2778px`。
 
+`init-config` 现在把预设分成两层：
+
+- 推荐预设：`starter`、`feature`、`marketing`
+- 高级预设：`immersive`、`fullscreen`
+
+- `--background-template`：背景模板，内置 `solid-light`、`gradient-blue`、`gradient-sunset`、`image-hero`、`raw-blur`
+- `--layout-template`：布局模板，内置 `device-with-title-subtitle`、`device-with-title`、`raw-fullscreen`
+- `--device-frame-template`：设备框模板，内置 `iphone-dark-01`、`iphone-dark-02`、`iphone-dark-03`、`none`
+
+为了减少记忆负担，`--template` 还支持一组场景别名：
+
+- `app-store-starter`
+- `app-store-feature`
+- `app-store-marketing`
+- `app-store-immersive`
+- `app-store-fullscreen`
+
+推荐用法：
+
+1. 先只选 `--template`
+2. 只有预设不够时，再单独覆盖 `--background-template`、`--layout-template` 或 `--device-frame-template`
+
+如果你只想查看模板列表，不写任何文件，可以执行：
+
+```bash
+ipa-cli screenshots init-config --list-templates
+```
+
 #### `screenshots from-simulator`
 
 从 iOS 模拟器采集一张原始截图，可选安装并启动 `.app` 后再截图。
@@ -909,6 +1076,26 @@ ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --ove
 }
 ```
 
+如果你这次不需要标题、手机外框或副标题，只想把已经设计好的整张图直接输出为商店尺寸，可以单独使用 `raw-fullscreen`：
+
+```json
+{
+  "version": 1,
+  "platform": "ios",
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_launch",
+      "raw": "raw/{locale}/01_launch.png",
+      "layout": "raw-fullscreen"
+    }
+  ]
+}
+```
+
+把原图放到 `raw/zh-Hans/01_launch.png` 后，直接执行 `ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --format panel` 即可。`raw-fullscreen` 默认按 `cover` 铺满整个输出尺寸；只有想保留完整原图并露出背景层时，才需要额外设置 `rawFit: "contain"` 和 `background`。
+
 `init-config` 生成的默认配置会额外包含 `defaults`：
 
 ```json
@@ -954,9 +1141,16 @@ ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --ove
 | `defaults.background` | 否 | 全局背景配置；兼容纯色字符串，也支持 `preset`、`solid`、`linear-gradient`、`image`、`raw-blur`、`stack` |
 | `defaults.titleColor` | 否 | 标题颜色，默认 `#111827` |
 | `defaults.subtitleColor` | 否 | 副标题颜色，默认 `#4B5563` |
+| `defaults.titleStrokeColor` | 否 | 标题描边颜色；不填则不描边 |
+| `defaults.subtitleStrokeColor` | 否 | 副标题描边颜色；不填则不描边 |
 | `defaults.titleFontSize` | 否 | 标题字号，单位 px；不填时按画布宽度自动计算 |
 | `defaults.subtitleFontSize` | 否 | 副标题字号，单位 px；不填时按画布宽度自动计算 |
-| `defaults.fontFamily` | 否 | SVG 文本字体族，默认 `Inter, Arial, sans-serif` |
+| `defaults.fontFamily` | 否 | 标题/副标题共用字体族回退，默认 `Inter, Arial, sans-serif` |
+| `defaults.fontFile` | 否 | 标题/副标题共用字体文件回退；相对配置文件目录解析 |
+| `defaults.titleFontFamily` | 否 | 标题默认字体族；不填时回退到 `defaults.fontFamily` |
+| `defaults.titleFontFile` | 否 | 标题默认字体文件；不填时回退到 `defaults.fontFile` |
+| `defaults.subtitleFontFamily` | 否 | 副标题默认字体族；不填时回退到 `defaults.fontFamily` |
+| `defaults.subtitleFontFile` | 否 | 副标题默认字体文件；不填时回退到 `defaults.fontFile` |
 | `defaults.orientation` | 否 | `portrait` 或 `landscape`，默认 `portrait` |
 | `defaults.deviceWidthRatio` | 否 | 设备截图宽度相对画布宽度的比例，范围 `0.35` 到 `0.95`，默认 `0.76` |
 | `defaults.deviceFrame` | 否 | 全局默认手机框配置；支持内置 `preset` 或自定义 `src` + `screen` |
@@ -966,28 +1160,78 @@ ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --ove
 | `frames[].raw` | 是 | 原始截图路径，相对配置文件所在目录解析；支持 `{locale}` 和 `{target}` 占位符 |
 | `frames[].title` | 否 | 标题文案 |
 | `frames[].subtitle` | 否 | 副标题文案 |
+| `frames[].subtitles` | 否 | 多副标题数组；存在时优先于 `subtitle` |
 | `frames[].layout` | 否 | 布局类型，支持 `raw-fullscreen`、`device-with-title`、`device-with-title-subtitle` |
 | `frames[].rawFit` | 否 | `raw-fullscreen` 下原图缩放方式；默认 `cover`，设为 `contain` 时可露出背景层 |
 | `frames[].backgroundPreset` | 否 | 单张图引用背景预设名；优先级低于显式 `background`，高于全局默认背景 |
 | `frames[].background` | 否 | 覆盖全局背景配置 |
 | `frames[].titleColor` | 否 | 覆盖全局标题颜色 |
 | `frames[].subtitleColor` | 否 | 覆盖全局副标题颜色 |
+| `frames[].titleStrokeColor` | 否 | 覆盖全局标题描边颜色 |
+| `frames[].subtitleStrokeColor` | 否 | 覆盖全局副标题描边颜色 |
 | `frames[].titleFontSize` | 否 | 覆盖单张图标题字号，单位 px |
 | `frames[].subtitleFontSize` | 否 | 覆盖单张图副标题字号，单位 px |
+| `frames[].titleFontFamily` | 否 | 覆盖单张图标题字体族 |
+| `frames[].titleFontFile` | 否 | 覆盖单张图标题字体文件 |
+| `frames[].subtitleFontFamily` | 否 | 覆盖单张图副标题默认字体族 |
+| `frames[].subtitleFontFile` | 否 | 覆盖单张图副标题默认字体文件 |
+| `frames[].subtitles[].text` | 否 | 单条副标题文案 |
+| `frames[].subtitles[].color` | 否 | 单条副标题颜色 |
+| `frames[].subtitles[].strokeColor` | 否 | 单条副标题描边颜色 |
+| `frames[].subtitles[].fontSize` | 否 | 单条副标题字号，单位 px |
+| `frames[].subtitles[].fontFamily` | 否 | 单条副标题字体族 |
+| `frames[].subtitles[].fontFile` | 否 | 单条副标题字体文件 |
 | `frames[].deviceFrame` | 否 | 单张图覆盖手机框配置；可只写 `offsetY`、`scale` 等局部字段 |
 | `frames[].target` | 否 | 只对某个目标槽位生效 |
 | `frames[].locale` | 否 | 只对某个语言生效 |
 
-字号字段速查：
+文字字体与字号速查：
 
 - `defaults.titleFontSize`：全局默认标题字号
 - `defaults.subtitleFontSize`：全局默认副标题字号
 - `frames[].titleFontSize`：覆盖单张图标题字号
 - `frames[].subtitleFontSize`：覆盖单张图副标题字号
+- `defaults.titleFontFamily` / `defaults.titleFontFile`：标题默认字体
+- `defaults.subtitleFontFamily` / `defaults.subtitleFontFile`：副标题默认字体
+- `defaults.titleStrokeColor` / `defaults.subtitleStrokeColor`：标题 / 副标题默认描边颜色
+- `frames[].titleFontFamily` / `frames[].titleFontFile`：单张图覆盖标题字体
+- `frames[].subtitleFontFamily` / `frames[].subtitleFontFile`：单张图覆盖副标题默认字体
+- `frames[].titleStrokeColor` / `frames[].subtitleStrokeColor`：单张图覆盖标题 / 副标题描边颜色
+- `frames[].subtitles[].fontFamily` / `frames[].subtitles[].fontFile`：单条副标题单独字体
+- `frames[].subtitles[].strokeColor`：单条副标题单独描边颜色
+- `frames[].subtitles[].fontSize`：单条副标题单独字号
 - 单位都是 `px`，值必须是正数
 - `frames[]` 里的字号设置优先级高于 `defaults`
-- `subtitle` 只有在 `layout: "device-with-title-subtitle"` 时显示，所以 `subtitleFontSize` 也只会在这个布局下生效
+- `subtitle` 和 `subtitles` 只有在 `layout: "device-with-title-subtitle"` 时显示
+- 当 `frames[].subtitles` 存在时，会优先使用它，不再读取 `frames[].subtitle`
 - 如果这些字段都不填，渲染器会按画布宽度自动计算字号
+- 如果配置了 `*StrokeColor`，渲染器会自动给文字加一层与字号成比例的描边
+- `fontFile` 系列字段优先级高于同级 `fontFamily`
+- 如果系统里没有安装对应字体，请同时配置 `fontFile`
+
+当前支持的字体：
+
+- `Inter`
+- `PingFang SC`
+- `Noto Sans CJK`
+- `Noto Sans CJK SC`
+- `Microsoft YaHei`
+- `HarmonyOS Sans`
+- `HarmonyOS Sans SC`
+- `MiSans`
+- `Roboto`
+
+字体解析规则：
+
+1. 如果显式配置了 `fontFile`，渲染器优先使用该字体文件。
+2. 如果没配 `fontFile`，但 `fontFamily` 命中了上述别名，而且本机存在已知字体文件，渲染器会自动绑定它。
+3. 如果本机没有已知字体文件，渲染器会继续按 `fontFamily` 名称尝试系统字体解析。
+
+建议：
+
+- `Roboto` 更适合英文、数字和技术感较强的副标题。
+- `HarmonyOS Sans`、`MiSans` 如果你的机器上没有安装，建议配合 `fontFile` 一起使用。
+- 想让标题和副标题使用不同字体时，优先用 `titleFontFamily` 和 `subtitleFontFamily`，不要只共用 `fontFamily`。
 
 ```json
 {
@@ -1009,13 +1253,41 @@ ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --ove
 }
 ```
 
+多副标题示例：
+
+```json
+{
+  "name": "02_support",
+  "raw": "raw/{locale}/02_support.png",
+  "layout": "device-with-title-subtitle",
+  "title": "咨询客服",
+  "titleFontFamily": "HarmonyOS Sans",
+  "subtitles": [
+    {
+      "text": "智能秒回",
+      "fontFamily": "HarmonyOS Sans",
+      "fontSize": 38,
+      "color": "#111827",
+      "strokeColor": "#FFFFFF"
+    },
+    {
+      "text": "人工专解",
+      "fontFamily": "Roboto",
+      "fontSize": 26,
+      "color": "#DC2626",
+      "strokeColor": "#111827"
+    }
+  ]
+}
+```
+
 布局类型：
 
 | layout | 画面效果 | 适合场景 | 注意事项 |
 | --- | --- | --- | --- |
 | `raw-fullscreen` | 原图直接铺满整个输出画布，不显示设备外框、标题或副标题 | 已经是完整营销图、KV 图、海报风页面图 | `rawFit: "cover"` 时只输出原图；`rawFit: "contain"` 时才会露出背景层 |
-| `device-with-title` | 顶部显示一段标题，下方展示带手机框的设备截图 | 单卖点页、功能页、流程页 | 即使传了 `subtitle`，当前也不会显示 |
-| `device-with-title-subtitle` | 顶部显示标题和副标题，下方展示带手机框的设备截图 | 首页、详情页、需要两级文案的场景 | 这是默认布局；不填 `subtitle` 时会只显示标题区 |
+| `device-with-title` | 顶部显示一段标题，下方展示带手机框的设备截图 | 单卖点页、功能页、流程页 | 即使传了 `subtitle` 或 `subtitles`，当前也不会显示 |
+| `device-with-title-subtitle` | 顶部显示标题和副标题，下方展示带手机框的设备截图 | 首页、详情页、需要两级文案的场景 | 这是默认布局；支持单个 `subtitle` 或多个 `subtitles[]` |
 
 配置写法示例：
 
@@ -2011,10 +2283,13 @@ ipa-cli analyze --help
 ipa-cli compare --help
 ipa-cli scan --help
 ipa-cli smoke --help
+ipa-cli actions --help
+ipa-cli actions init-ios-build --help
 ipa-cli assets --help
 ipa-cli assets review --help
 ipa-cli assets manifest --help
 ipa-cli assets obfuscate --help
+ipa-cli convert --help
 ipa-cli screenshots --help
 ipa-cli screenshots init-config --help
 ipa-cli screenshots from-simulator --help
@@ -2053,6 +2328,9 @@ ipa-cli scan ./YourApp.ipa --library ./data/library --top 5
 # 端到端冒烟
 ipa-cli smoke ./YourApp.ipa --library ./data/library --format text
 
+# 初始化 GitHub Actions iOS 构建模板
+ipa-cli actions init-ios-build ./YourProject
+
 # 初始化上架图工作区
 ipa-cli screenshots init-config