用codex搞定iOS APP一键提审

  请为团队搭建一套可复用的 iOS App Store 发布自动化系统，分为「AI Skill 层」和「共享发布工具层」。

  目标：

  - 用户对 AI 说“$ios-release 发布版本”后，AI 先做只读预览。

  - AI 读取上一个 Git Tag 之后的提交和相关代码变更，生成面向用户的多语言 App Store 更新说明。

  - AI 展示建议版本号、提交范围、全部语言的更新说明与字符数、现有商店文案校验结果。

  - 只有用户明确确认该预览后，才能执行发布准备。

  - 自动化完成打包、上传、创建 App Store 版本、关联 Build、同步 metadata、Precheck、Git Tag/Push。

  - 自动化绝不自动点击“提交审核”；用户必须在 App Store Connect 网页人工检查后手动提交。

  - 新建 App Store 版本必须设置“审核通过后自动发布”。

  架构：

  1. AI Skill

     - 负责理解 Git/代码变更、生成用户可见的 release notes、多语言本地化、展示预览、等待明确确认。

     - AI 不直接执行 xcodebuild、Fastlane 或 App Store API。

     - 用户确认后，将已确认的完整多语言 release notes 写入仓库外临时文件，计算 SHA-256。

     - Execute 时传入：版本号、release notes 临时文件、预览时 Git HEAD、SHA-256。

  2. 项目仓库只保存公开内容

     - fastlane/ios-release.yml：xcodeproj、scheme、bundle id、localization roots、文案路径、locale map、credential profile、共享工具版本。

     - Scripts/ios-release-tool：薄 Bash 入口，转发到共享工具。

     - Docs/app-store-descriptions.txt、Docs/app-store-promotional-text.txt。

     - 不得保存 Apple ID、API Key ID、Issuer ID、.p8 私钥或绝对私钥路径。

  3. 共享发布工具仓库

     - 使用 Bash 做流程编排。

     - 使用 Ruby 做 YAML 配置读取、文案解析和校验、版本号修改。

     - 使用 Fastlane 做 Archive、IPA 上传、metadata 上传和 Precheck。

     - 使用 Fastlane Spaceship / App Store Connect API 创建版本、查询 Build、关联精确 Build。

     - 用 Bundler、Gemfile、Gemfile.lock 锁定 Ruby/Fastlane 版本。

     - 项目配置中的 release_tool.version 必须与共享工具 VERSION 完全一致。

  安全与一致性：

  - Preview 必须只读：不修改文件、不创建提交/Tag、不 Archive、不上传、不写 App Store Connect。

  - Execute 前重新检查：

    - Git 工作区干净；

    - Git HEAD 等于 Preview 时的 HEAD；

    - release notes SHA-256 等于用户确认时的值；

    - API 凭据存在；

    - release.env 和 .p8 权限为 600；

    - 项目语言、locale map、描述、推广文本、release notes 完整且未超字符限制。

  - 任一检查失败立即停止，不做猜测性修复。

  - 不删除已上传 Build、App Store 版本、Archive、Git Tag 或文件。

  - 如果上传成功、后续失败，不要重复完整发布以免产生新 Build；先只读确认远端状态。

  版本策略：

  - 从最新 Git Tag 到 HEAD 推断建议版本：

    - BREAKING CHANGE → major；

    - feat: / feat(...) → minor；

    - 其他 → patch。

  - Build Number 取本地值和 App Store Connect 同营销版本最大值中的较大值，再加 1。

  - 先修改 MARKETING_VERSION、CURRENT_PROJECT_VERSION 并创建本地 Git 版本提交。

  - 所有发布准备成功后才创建并推送 v<marketing-version> Tag。

  App Store Connect 行为：

  - 上传 IPA 后必须等待精确营销版本 + Build Number 的构建处理为 VALID。

  - 只允许关联唯一且精确匹配的 Build。

  - 如果存在多个活跃 App Store 版本，停止，不能猜测目标。

  - 如果已有版本号不同，停止，不能重命名已有版本。

  - 新建 App Store 版本时设置：

    releaseType: AFTER_APPROVAL

    这表示“审核通过后自动发布”。

  - metadata 上传必须设置：

    submit_for_review: false

    skip_binary_upload: true

    skip_screenshots: true

    这保证工具不会替用户提交审核、重传二进制或修改截图。

  - 不修改价格、IAP、截图、未配置的字段或审核资料。

  多语言文案：

  - 扫描 *.lproj 和 *.xcstrings，再与 Xcode knownRegions 交叉验证，排除 Base。

  - 描述、推广文本和 AI 生成的 release notes 必须恰好覆盖项目语言。

  - 限制：推广文本 170；描述 4000；release notes 4000 字符。

  - 支持一个项目语言映射多个 App Store locale，例如 pt → pt-PT、pt-BR。

  - 每次上传前，在新的仓库外临时 metadata 目录生成 deliver 所需结构：

    <locale>/description.txt

    <locale>/promotional_text.txt

    <locale>/release_notes.txt

  必须提供：

  - 单元测试：语言识别、locale 展开、字符限制、版本修改、预览参数保护、发布类型 AFTER_APPROVAL、Precheck 策略。

  - Bash/Ruby 语法检查。

  - 项目入口版本匹配测试。

  - 清晰的项目接入文档和日常使用文档。

  最终用户体验：

  “$ios-release 发布版本”

  → AI 展示完整预览

  → 用户确认版本和所有语言文案

  → 工具自动完成发布准备

  → 用户在 App Store Connect 人工检查并点击 Submit for Review

  → Apple 审核通过后自动发布。