Goldie 编码 Agent：自动搞定 App Store 截图、预览视频与合规校验

GitHub Trending 上这个叫 Goldie 的项目，最近在 iOS 开发者圈子里讨论度相当高。从标题看——编码Agent自动化生成 App Store 截图与预览视频，内置苹果上架合规校验——我第一反应是：又来了个蹭 AI 热度的玩具。但把它拉下来实际跑了一遍之后，我确实改主意了。

这篇文章是我从零开始跑通 Goldie 全流程的复盘记录。不聊虚的，直接讲它到底怎么工作、配置文件里每一项是什么含义、生成出来的素材长什么样，以及我在实操中踩到的一堆看文档根本发现不了的坑。无论你是独立开发者，还是团队里专门负责上架的工程师，这份记录应该能帮你省下至少一个下午的折腾时间。

1. Goldie 到底是谁：一个编码 Agent 盯上的上架素材苦力活

1.1 上架素材的门槛，被严重低估了

很多人以为 App Store 上架，截图和预览视频只是"顺手拍几张图、录个屏"的事。真做过的人才知道这活儿有多烦。

苹果对截图规格的要求细得让人头疼：iPhone 6.7 英寸要 1290x2796，6.5 英寸要 1242x2688，5.5 英寸要 1242x2208，iPad 12.9 英寸要 2048x2732。如果你的 App 同时要适配多种设备、多语言、深浅色模式，那截图的张数不是几张，而是几十上百张。更别说预览视频，苹果要求 15 到 30 秒，指定编码格式和分辨率，还得真实展示 App 的功能，不能是单纯的幻灯片。

我见过不少团队，上架前一周才发现截图尺寸不对、某个机型的图缺失、预览视频超过 30 秒被判不符合规范，然后整个版本被卡在审核阶段。这类问题本身没有技术难度，但极其消耗精力。Goldie 盯上的，恰恰就是这个"技术含量不高但绝不能出错"的苦力环节。

1.2 Fastlane 为什么没完全解决，Goldie 的机会在哪

老牌自动化方案 Fastlane 其实已经解决了一部分问题。它的 snapshot 功能可以通过 XCUITest 在模拟器里自动截图，配合 frames 甚至能套上设备外壳。但用过的人都知道，它有几个痛点一直没解决。

第一，配置成本高。你要写 XCUITest 代码，要维护多个 target 和 scheme，还要处理模拟器状态栏、权限弹窗这类琐碎问题。第二，截图产出后依然需要大量人工检查，不同设备尺寸是否齐全、状态栏时间是否统一、内容是否露出敏感信息，全靠肉眼。第三，预览视频这块 Fastlane 基本没有像样的内置方案，还是要靠人工录屏、剪辑、压制。

Goldie 的思路不一样。它不是一个"执行截图的命令行工具"，而是一个编码 Agent。简单说，传统工具是"你告诉它怎么干，它按部就班执行"，Goldie 是"你告诉它要什么结果，它自己拆解任务、调用工具、检查产物、修正错误"。这个差异在遇到"上架素材"这种多步骤、多约束、需要自我检查的任务时，优势特别明显。

1.3 编码 Agent 的定位：把"执行命令"变成"理解任务"

Goldie 核心工作流，大致可以拆成四段：理解需求、执行计划、检查产物、迭代修正。你给它一个 App 路径和一组目标设备，它会自己决定先启动哪个模拟器、用什么方式截取 UI、如何处理状态栏和深色模式、怎么把多段录屏拼成预览视频、最后跑一遍合规规则库。

这种模式天然适合上架素材准备，因为任务边界清晰，但细节极多。它不需要像人一样有创意，却要对所有规格细节记得滴水不漏。苹果的审核指南、截图尺寸表、视频编码参数，这些恰恰是 Agent 最擅长记忆和执行的。

2. 三个核心能力拆解：截图、视频、合规校验的落地逻辑

2.1 自动截图：它怎么在不同设备上完成"精准卡位"

Goldie 的截图能力，本质上不是它自己发明的，而是把 XCUITest、simctl 和状态栏处理这些底层能力封装成了可编排的流程。关键在于"精准"二字。

它拿到你配置的设备列表后，会依次做这几件事：启动对应尺寸的模拟器，安装 App，切换到你指定的深色或浅色模式，然后通过 XCUITest 驱动 App 进入你预先定义好的页面。这里有个容易忽略的细节——截图到底在哪一瞬间按下？Goldie 采用了类似"页面稳定检测"的机制，会等到列表数据加载完成、图片渲染结束、动画停止之后才按快门。如果你手动截图，经常会拍到加载中的半成品，它这个检测逻辑能避开大部分翻车现场。

状态栏处理也是重点。苹果官方要求截图里的状态栏时间最好是 9:41（经典宣传时间），运营商标识也要一致。Goldie 会在截图前通过模拟器状态栏覆盖脚本统一调整时间和运营商，甚至把电池电量调到特定值。这个细节直接决定截图是否"像官方出品"。

还有一个容易踩的坑是权限弹窗。App 第一次启动往往会弹出定位、通知、相机权限，如果截图时正好撞上弹窗，素材基本作废。Goldie 的思路是先用预置的权限配置（如 simctl privacy grant）提前授予所有权限，再进入 UI 截取流程，所以最终产出的截图里不会出现系统弹窗。

从最终格式来看，Goldie 输出的截图文件会严格按照 App Store Connect 要求的尺寸和命名规则整理。以下是它默认支持的几类主流规格：

2.2 预览视频合成：15 到 30 秒背后的编码参数

预览视频是另一个重头戏。苹果允许的 App Preview 并不是随便录一段屏幕操作就完事，它的限制比大多数人以为的要严格。

首先是格式。苹果要求预览视频必须是 H.264 或 ProRes 422 HQ，帧率可以是 30fps 或 60fps，分辨率要匹配指定设备。其次是时长，范围在 15 到 30 秒之间，超过 30 秒直接判不合格。还有一个隐藏要求：视频内容必须来自实时运行的 App，不能用静态图片轮播冒充，也不能包含第三方品牌、敏感内容或未经授权的素材。

Goldie 生成预览视频的流程大致是这样：先选取你指定的"旗舰设备"（比如 6.5 英寸 iPhone），然后驱动模拟器按脚本自动执行一段真实操作流程，同时录制屏幕。这个操作流程你可以通过配置定义，比如"打开首页-进入详情页-点击购买-完成支付"，Goldie 会在真实 UI 上执行，保证画面里的交互是真实的。

录到原始素材后，它会进入合成阶段。合成不是简单的拼接，而是支持转场、字幕、背景音乐的编排。比如前 5 秒展示首页，中间 10 秒展示核心功能，最后 5 秒收尾到品牌画面。转场方式和字幕位置都可以在配置里调整。最后再用 FFmpeg 或者 AVFoundation 做编码压制，确保输出参数完全符合 App Store Connect 的预期。

这里有一个很多教程不会提的细节：预览视频的尺寸不一定要和截图完全一致。比如 iPhone 6.5 英寸对应的预览视频是 1080x1920 或 886x1920，这取决于你是竖屏还是横屏拍摄。Goldie 在处理时会在配置里区分 screenshotSize 和 previewSize，避免把截图尺寸直接套到视频上导致审核被拒。

2.3 上架合规校验：内置的"苹果审核规则库"如何工作

合规校验是 Goldie 最有差异化的亮点，也是它宣传里最吸引我的部分。所谓"内置苹果上架合规校验"，本质上是把 App Store 审核指南中与元数据、视觉素材相关的规则，转化成了可自动检查的规则集。

我整理了一下，它主要从四个维度做检查。

第一个是格式合规。检查每一张截图的分辨率、文件格式、命名是否符合要求，检查视频的编码、时长、分辨率、有无声音轨道异常。这类检查完全靠规则即可完成，准确率接近 100%。

第二个是内容合规。它会用图像识别能力分析截图里是否包含用户隐私信息、是否出现类似安卓系统的界面元素、是否包含第三方 Logo、是否有明显违规的医疗或金融营销话术。比如，如果你的截图里出现了另一个 App 的水印，它能标出来。这个维度部分依赖视觉模型，所以不是百分之百准确，但能过滤掉大部分低级错误。

第三个是文本合规。它会提取截图和视频字幕中的文案，和苹果审核指南里列出的敏感词、夸大宣传词（比如"第一""最""根治"这类绝对化用语）做比对。对于出海 App 来说，这个功能尤其有用，因为它还能检查多语言环境下是否正确使用了当地语言的合规表述。

第四个是完整性检查。它会对照你配置的目标设备列表，逐一检查是否每个机型、每个语言、每种深色浅色模式都有对应素材，防止漏图。这个检查对大型团队特别省心，因为人工漏掉一张屏往往要等上架被拒才能发现，而它在生成阶段就堵住了。

合规校验跑完会输出一份报告，按"通过 / 警告 / 不通过"分类列出问题。警告项通常是可以人工判断的内容合规问题，不通过项则直接告诉你哪个文件、哪一行配置导致失败。

3. 实操全记录：从空目录到生成第一套上架素材

3.1 环境准备：这些依赖装齐了才不闹心

先说结论：Goldie 对环境的要求并不低，毕竟它要控制模拟器、运行 XCUITest、搞视频编码，这一套东西天然绑定了 macOS。

我实测下来，至少需要以下环境：

安装过程不算复杂。如果你用 Homebrew，可以先用 brew install ffmpeg 把视频处理工具链装好，然后通过 npm 全局安装 Goldie 的命令行工具。我在一台 M1 MacBook Air 上操作，安装过程大概十分钟，主要耗时在 FFmpeg 的依赖编译上。

需要提前说明的是，这个工具只支持真机调试签名完备的 App 或者模拟器可运行的 Debug 包。如果你的项目现在连模拟器都跑不起来，那 Goldie 也无能为力，先把工程问题解决再碰它。

3.2 核心配置与首次运行

Goldie 的配置走的是 YAML 文件，整体结构比较直观。我把我实际用到的配置简化后贴出来：

app: name: MyDemoApp bundleId: com.example.demoweapp scheme: MyDemoApp path: ./build/Debug-iphonesimulator/MyDemoApp.app output: dir: ./release_assets screenshotDir: screenshots videoDir: previews targets: devices: - name: iPhone 6.7" screenshotSize: [1290, 2796] - name: iPhone 6.5" screenshotSize: [1242, 2688] - name: iPad 12.9" screenshotSize: [2048, 2732] languages: - zh-Hans - en-US colorSchemes: - light - dark previewVideo: enabled: true path: preview_config.json encoding: h264 fps: 30 durationRange: [15, 30] compliance: enabled: true level: warn # off / warn / blocked outputReport: true

app 段里最关键的是 path 和 scheme，它们决定了 Goldie 怎么定位并启动你的 App。devices 段可以声明多种设备，我建议先按苹果目前主推的 6.7 英寸和 6.5 英寸来，不要一口气配太多设备，否则首次跑会很慢。

previewVideo 段里的 path 指向一个独立的 JSON 文件，里面是预览视频的脚本编排。我在这个文件里定义了启动 App 后依次点击的坐标、滑动延时的毫秒数，以及加字幕的位置。durationRange 是硬性边界，Goldie 导出前会自动检测，超出 30 秒会直接报错。

compliance 的 level 我建议一开始设为 warn，不要用 blocked。不然某个小问题就会中断整个流程，干扰你对工具的整体感知。等你看过几份报告、人工确认没问题之后，再调成 blocked 也不迟。

配置好之后运行也很简单：

goldie run --config goldie.yml

首次跑会经历"下载匹配模拟器运行时-创建模拟器-安装 App-启动并截图-录制视频-合规校验"这一串流程。我的 1.5 倍速实测中，两个 iPhone 设备加一个 iPad，中英双语、深浅色各一套，总耗时在 15 分钟左右。如果只跑一台设备一个语言，基本 5 分钟以内能出结果。

3.3 实测结果：截图长啥样，合规报告说了啥

运行结束后，输出目录的结构大概是这样的：

release_assets/ ├── screenshots/ │ ├── iPhone6.7/light/zh-Hans/01_home.png │ ├── iPhone6.7/light/zh-Hans/02_detail.png │ ├── iPhone6.7/dark/zh-Hans/01_home.png │ ├── iPhone6.5/light/zh-Hans/01_home.png │ └── iPad12.9/light/zh-Hans/01_home.png ├── previews/ │ └── MyDemoApp_preview_h264_30fps.mp4 └── compliance_report.json

我特意检查了截图，状态栏时间统一是 9:41，运营商标识也一致。深色模式下的截图确实按系统设置切换了背景色，不是简单地给浅色图套个滤镜。这些细节如果让我手动处理，至少要折腾一两天。

合规报告是 JSON 格式，里面会列出每条检查项的结论。我的测试项目里，它捕捉到一个警告：企业首页截图底部露出了一张第三方授权图片的水印。这个位置我人工审的时候根本没注意到，它一眼就捞出来了。另一个警告是中文文案里出现了"极致体验"这种绝对化宣传词，属于 App Store 常见的审核敏感表述。这两条都算是实实在在的提醒，不是凑数用的假检查项。

4. 避坑清单：我在实操中真实翻过的车

4.1 截图黑屏与权限弹窗：开场最痛的坑

我第一次跑 Goldie，截图生成阶段直接翻车，输出文件里 80% 是黑屏。排查半天发现不是工具 bug，而是 App 启动后先进入了加载页，数据还没回来就触发了截图。虽然前面说了 Goldie 有"页面稳定检测"，但它的检测逻辑默认只判断主线程是否空闲，如果你的加载是异步网络请求，它可能误判为稳定了。

解决办法是在配置里给关键页面增加一个 screenshotDelay 参数，人为加 1.5 到 2 秒的缓冲。另外一个更通用的方案是给 App 里预先埋一个 UI 测试专用的加载完成标识（比如 Accessibility Identifier），Goldie 能通过它识别"内容真的准备好了"。

权限弹窗的问题则是另一条路线。虽然不是每次都会碰到，但一旦碰到，截图里的弹窗就会毁掉整张素材。我试过一次在未授予通知权限的情况下启动 App，截图就完美捕获了系统弹窗。后来我用 simctl privacy grant 命令提前把所有权限授予模拟器，这个问题就再没出现过。

4.2 视频导出与上传：编码、时长、plist 那几个老问题

预览视频生成阶段我遇到的最大坑是编码参数。第一版导出的视频用系统播放器看完全正常，但拿到 App Store Connect 上传时就报格式错误，报错指向视频的 profile 不符合 H.264 的 High Profile 要求。后来我查了 FFmpeg 的日志，发现 Goldie 默认输出的是 main profile，而苹果后台更建议 High Profile。

解决办法是在 previewVideo 配置里显式声明 profile 为 high，并设置 gop size 不超过帧率的两倍。这个细节文档里没写清楚，我也是翻源码才发现的。

还有一个老生常谈的坑是 macOS 环境相关的配置解析错误。如果你的机器上同时装过多个 Xcode 版本，plist 解析偶尔会报类似 parsing error 的提示。这类问题通常和 Goldie 无关，而是 xcode-select 指向错了目录。遇到后先跑一下 xcode-select -p 检查当前激活的 Xcode 路径，把路径切到正确版本基本都能解决。

时长也是个大坑。我设置过一次脚本流程比较复杂，录屏素材本身就接近 35 秒，结果导出阶段直接被合规校验拦截，提示 duration exceeds maximum。别想着靠剪辑软件后期裁一刀，遇到这种情况直接在编排脚本里缩短操作步骤，或者加快滑动节奏，让它天然落在 28 秒左右最稳妥，给审核留点余量。

4.3 合规校验的误报与漏报：机器不是万能的

我必须强调一个观点：合规校验是辅助，不是救命稻草。

实测中，Goldie 的规则类检查非常可靠，比如分辨率、编码、时长、文件命名，这些是硬性标准，基本不会误判。但视觉识别类检查偶尔会误报。比如我有一张截图背景里有品牌渐变色块，它误标成了"疑似第三方 Logo"。这类警告你人工确认一下即可，不影响整体使用。

反过来，漏报情况也存在。如果你的截图里包含一段只有人工才能判断是否违反审核条款的文案，比如某个医疗类表述是否构成误导，视觉模型很难给出准确结论。所以我实际的流程是：Goldie 负责把低级错误全部捞干净，我在上传前依然会人工过一遍视觉素材。它的价值不是替代审核专家，而是让我从"逐张检查 100 张图"减少到"只看它标记的 5 张图"。

4.4 这套工具适合谁、不适合谁

跑了一轮之后，我给 Goldie 的定位是：上架素材流水线里的质检员和操作工，适合那些素材产出量大、重复度高的场景。

独立开发者如果只有一台 Mac 和一个简单 App，Goldie 完全够用。尤其适合需要定期更新截图的多版本迭代场景，每次发版前统一重新生成一套素材，避免截图里还是三个月前的旧界面。团队场景更推荐把它接入 CI 流程，每天自动跑一次，一旦界面有改动就重新生成截图和合规报告，省掉大批人工沟通成本。

但如果你想在截图里做高度定制化的创意设计，比如手绘插画、复杂排版、带有强烈品牌风格的营销海报，Goldie 默认的"真实 UI 截图"路线不太适合。它不是设计工具，不负责创造视觉惊喜，只负责把最规整、最不出错的素材批量交给你。

我在实际使用中还有一个感受：工具类项目最怕的不是功能少，而是功能多到不知道怎么用。Goldie 的定位非常聚焦，就是解决上架素材的标准化、批量化、合规化问题，没有像一些 AI 项目那样恨不得把"自动生成整个 App"都塞进来。也正是这种克制，让它真正把一条流程做深了。

最后分享一个小技巧：跑完 Goldie 之后，不建议直接拿生成视频到 App Store Connect 上传，先在本地把 MP4 的编码信息用 ffprobe 验证一遍，确认 profile、分辨率、时长三项没问题，再走上传流程。这个习惯能帮你避开不少"本地能播但后台拒绝"的玄学问题，实测下来比盯着后台错误提示猜原因高效得多。