用途
该技能用于为 Capacitor 应用构建和修复 CI/CD 流水线，覆盖 GitHub Actions、GitLab CI、Fastlane 以及 Capgo Cloud Build（npx @capgo/cli@latest build request）。目标是从 CI 中完成构建、签名和发布，并依据 Capacitor 主版本选用正确的工具链。
触发场景
创建或修复 .github/workflows/*.yml、.gitlab-ci.yml、fastlane/Fastfile 或 Capgo Cloud Build 任务时触发。具体包括：为 Capacitor 8 或 9 选择 runner 镜像以及 Node/Xcode/JDK 版本；自动化签名、TestFlight/Play 上传、版本号自增或 Capgo OTA 上传；以及排查“本地构建正常、CI 构建失败”的问题。
不适合的场景：手动提交、商店列表与截图（使用 capacitor-app-store）；Capgo Cloud Build 凭据设置与故障排查（使用 capgo-native-builds）；渠道晋升与分阶段 OTA 发布（使用 capgo-release-workflows）；编写单元/E2E 测试（使用 capacitor-testing）；安全扫描规则（使用 capacitor-security）。
工具链矩阵
技能提供 Capacitor 8.x（稳定版）与 Capacitor 9（next，pre-GA）的版本对照：Node 分别为 22+ 与 24+（9 自带 npm 11）；Xcode 分别为 26+（8.5+ 采用 UIScene 后 27 也可）与 27+；GitHub macOS runner 分别为 macos-26（默认 Xcode 26.x）与列出 Xcode 27 的 xcode-27 镜像或 macos-* 镜像；iOS 部署目标分别为 15.0 与 16.0；JDK 均为 21；Gradle/AGP 分别为 8.14.3/8.13 与 9.5.1/9.2.1；compile/target SDK 分别为 36 与 37。商店侧截止要求：Apple 当前要求 iOS 26 SDK，自 2027 年 4 月起要求 iOS 27 SDK；Google Play 自 2026 年 8 月 31 日起要求 target API 36。多版本 Xcode 共存时需显式指定：sudo xcode-select -s /Applications/Xcode_<version>.app。
流水线形态选择
当不明确时需询问用户：Capgo Cloud Build 无需 macOS runner 或本地签名配置，任意 Linux runner 调用 npx @capgo/cli@latest build request <appId> --platform ios|android，凭据先用 npx @capgo/cli@latest build credentials save ...（或 build init 引导 iOS 设置）保存一次，在 CI 中以环境变量传入；自托管 GitHub Actions/GitLab 提供完全控制，需自行管理 macOS runner、证书与 keystore；Fastlane 适用于已使用 match/pilot/supply 的场景。原生发布后的纯 Web 变更可跳过原生构建，直接上传 Capgo bundle（npx @capgo/cli@latest bundle upload --channel <channel>，通过 CAPGO_TOKEN 认证）；原生变更（插件、权限、Capacitor 升级）必须走原生构建。
执行流程
流程包括：读取项目快照（Capacitor 主版本、包管理器与锁文件、iOS 依赖管理器、已有工作流）；按矩阵选工具链版本，若存在 .nvmrc/engines 则据其设置 Node；组织任务结构为 test（lint、typecheck、unit）→ build-web（产物 <webDir>）→ iOS 与 Android 并行 → 按分支/tag 门控的部署任务，原生任务恢复 Web 产物后必须运行 npx cap sync <platform>，不得提交同步后的资源作为捷径；签名优先使用 App Store Connect API key 而非 Apple ID 密码，Android keystore 与密码存放在 secrets 中并于运行时解码、用后删除；构建号从 CI 推导（GITHUB_RUN_NUMBER、CI_PIPELINE_IID）或交由 Capgo Cloud Build 自增，不得复用；添加缓存；先在分支上运行流水线，仅上传到 TestFlight 内部 / Play 内部轨道。
验证与错误处理
验证要求：工作流在干净 runner 上连续两次通过（缓存冷、热各一次）；日志显示预期工具版本（添加 node -v、xcodebuild -version、java -version、./gradlew --version 步骤）；iOS 产物用 unzip -l App.ipa | grep Payload/App.app 检查并出现在 TestFlight；Android 产物用 bundletool dump manifest --bundle app-release.aab | grep -E "versionCode|targetSdkVersion" 核对并出现在 Play 内部轨道；Capgo 用 npx @capgo/cli@latest bundle list 确认上传版本与目标渠道；日志不打印任何密钥值。
技能还给出常见 CI 报错与修复对照，例如 Node 引擎版本不匹配需调整 actions/setup-node 的 node-version；找不到 Web 资源目录需检查 artifact 路径；签名证书或描述文件缺失需按签名参考处理；Xcode 选择错误或 Swift 6 报错需切换 Xcode 版本并把 @UIApplicationMain 换成 @main；Java 版本问题需用 actions/setup-java 安装 JDK 21（temurin）；Capacitor 9 升级后 Kotlin 插件冲突需移除 kotlin-android；Android SDK 路径需配置 ANDROID_HOME 或使用 setup-android；Play 版本号重复需从 CI run number 推导；Capgo API key 缺失或失效需从 secrets 导出 CAPGO_TOKEN 或新建密钥；安全扫描包名为 @capgo/capgo-sec，命令为 npx @capgo/capgo-sec@latest scan --ci。
参考文档
references/github-actions.md 提供完整工作流（test、Web 构建、iOS（SPM/CocoaPods）、Android、Capgo OTA、Capgo Cloud Build 任务）；references/gitlab-ci.md 提供带 macOS runner 标签的 GitLab 流水线；references/fastlane.md 提供使用 API key 与 match 的 iOS 和 Android lane；references/signing-and-secrets.md 涵盖证书/描述文件导入、API key 认证、Android keystore 接线与密钥清单；references/caching-and-versioning.md 涵盖 npm/Gradle/SPM/CocoaPods 缓存、构建号与 semantic-release。
限制
技能不覆盖手动提交与商店列表、Capgo Cloud Build 凭据设置与故障排查、渠道晋升与分阶段 OTA 发布、单元/E2E 测试编写、安全扫描规则制定，这些需使用各自对应的技能。