goldie

goldie：为本仓库中的应用制作 App Store 素材

goldie 会在 iOS 模拟器上重放 argent YAML 流程，捕获原始截图和录屏，并将其制作成可直接上传的素材：截图会添加设备边框、背景和营销文案；预览视频则会原样拼接原始录屏，因为 Apple 要求应用预览必须是没有边框或字幕的纯屏幕录制。React 工作室会像真实商店页面一样展示结果。你的工作是完成 goldie 无法独立完成的所有事项：挑选值得营销的屏幕、编写能到达这些屏幕的流程、撰写文案，并驱动整个流水线。

最终成果：4 或 5 张带边框的截图，以及预览视频的原始片段；这些内容会显示在 http://localhost:4321 的工作室中，视频则在后台渲染。

首先：检查是否已有 goldie 配置

goldie 会将整个成果保存在文件中，方便用户后续再次提示。如果应用仓库中已有配置，说明这是一次后续修改。请先阅读配置，然后跳转到下方的“迭代现有配置”，不要从头开始：

ls goldie/goldie.config.ts .argent/flows/ 2>/dev/null; echo "GOLDIE_CONFIG=$GOLDIE_CONFIG"

完整阅读 goldie/goldie.config.ts 及其指定的流程。它们共同构成所有可见选择的事实来源：包括选择哪些屏幕及其顺序、主标题和副标题、背景和文案颜色、设备边框、商店列表，以及预览故事。任何内容都不只存在于你的脑海或工作室中，因此用户说“把颜色调暗”或“把搜索截图换成设置截图”，就是在要求修改这些文件。

步骤 0：确定要面向哪些商店

要面向哪些商店，取决于仓库能构建什么，因此请先检查，不要急着提问。检查是否有 iOS 目标（.xcodeproj / .xcworkspace、带应用目标的 Swift 包、ios/ 目录），以及 Android 目标（带应用模块的 build.gradle[.kts]、android/ 目录）。

• 单平台仓库——仅原生 Android，或仅 iOS/Swift。只有一种可能的选择，因此不要提问：面向对应的商店，并在第一条消息中说明你选择了哪个商店以及原因。
• 跨平台仓库——React Native、Expo、Flutter、Kotlin Multiplatform，或其他同时包含 iOS 和 Android 目标的项目。开始任何其他工作前，都必须先提问，即使用户已经指定了一个平台也一样：用户提示“Play Store 截图”时，往往仍然包括“还有 App Store 的截图吗？”，而答案会决定是否需要返工成本高昂的工作。如果有交互式提问工具（例如 Claude Code 中的 AskUserQuestion），请使用该工具并允许多选；将用户已提及的选项预先选中或放在前面。否则就在聊天中提问，让用户选择一个或两个。

两个选项如下：

• Apple App Store（iPhone）：带边框的 iPhone 截图和应用预览视频，使用 iOS 模拟器捕获。
• Google Play Store（Android）：使用 Android 模拟器捕获的 Play 手机截图，以及竖屏预览视频；Play 宣传视频使用 YouTube 链接，因此用户需要自行将视频发布到该平台。

可以同时选择两者；两个商店共用场景和流程。答案将决定配置中要使用哪些设备键、步骤 1 必须找到哪些构建产物（iOS 模拟器构建、Android APK，或两者），以及下方的 Google Play 部分是否适用。若是对现有配置进行后续修改，配置中的设备设置已经给出了答案，因此不要再次提问。

步骤 0.5：确保 goldie 可以运行

goldie 是一个 npm 包，其中打包了 CLI、工作室和固定版本的 argent 驱动程序。无需克隆任何内容；首次使用时，npx 会获取它：

npx -y goldie@0 help

以下所有命令均为 npx -y goldie@0 <cmd>，下文简称为 goldie。 它需要 Node 20+ 和 PATH 中的 ffmpeg（macOS 上运行 brew install ffmpeg， Windows 上运行 winget install ffmpeg，Linux 上运行 apt install ffmpeg）。iOS 设备需要 macOS 主机；在 Linux 和 Windows 上只能运行 Android 设备 （pixel-10-pro），因此请勿在这些系统上的 devices 中包含 iOS 键。如果设置了 $GOLDIE_ROOT，说明用户正在使用源代码检出；此时请改为运行 bun $GOLDIE_ROOT/src/cli.ts <cmd>。所有特定于应用的文件都位于 应用仓库中。

goldie 了解三种设备：iphone-6.9（iPhone 17 Pro Max，App Store 要求的尺寸）、 ipad-13（iPad Pro 13-inch，适用于也在 iPad 上发布的应用），以及 pixel-10-pro（Google Play 手机）。所有设备都会重放相同的流程， 并共用文案、主题和模板；每台设备都有自己的边框、原始捕获文件、输出文件夹和工作室视图。

步骤 1：收集应用信息

要查找的内容取决于步骤 0 中选择的商店。

• 应用名称和标识符。 iOS：Xcode 项目、app.json / app.config.*（Expo）或 Info.plist。Android：app/build.gradle[.kts] 中的 applicationId，或 Expo 配置中的 android.package。
• iOS Release 模拟器构建版本（仅限 App Store）。查找最新的 ~/Library/Developer/Xcode/DerivedData/<App>-*/Build/Products/Release-iphonesimulator/<App>.app。 如果只有 Debug 版本，则构建 Release 版本：Debug 构建需要 Metro，且会在捕获画面中 绘制 LogBox 横幅，导致营销素材无法使用。
• Android APK（仅限 Google Play）。最好使用 release APK；使用 仓库自带的脚本或 ./gradlew :app:assembleRelease 构建，并注意 未签名的 release APK 无法安装。原生 Android 应用可以使用 debug APK，因为它不会绘制调试叠加层；对于 React Native，debug APK 需要 Metro，且会显示开发叠加层，因此应构建 release 版本。

只要仓库提供了自己的构建脚本，就优先使用。

步骤 2：探索应用并选择场景

在做任何决定之前，使用 argent MCP 工具查看应用。启动目标商店对应的设备： App Store 使用 iPhone 16 Pro Max 级别的模拟器，Google Play 使用 Pixel 10 Pro（或 Pixel 9 Pro）AVD。安装构建版本，启动应用，并使用 describe 和 screenshot 浏览主要屏幕。还要检查应用仓库中 .argent/flows/ 下现有的录制流程；它们是可用选择器和坐标的最佳来源。如果应用也在 iPad 上发布（Expo 配置中的 supportsTablet，或有 iPad 目标），计划在 devices 中添加 "ipad-13"，并在 “iPad Pro 13-inch (M4)” 模拟器上检查相同屏幕。如果目标设备不止一台，流程必须使用在所有布局上都适用的选择器，因此应优先使用 text: 和 id: 而非坐标。

选择：

• 4 或 5 个截图场景。 每个场景是一张能够展示某项功能的屏幕：主列表、详情视图、搜索、特色功能屏幕。优先选择内容看起来真实的屏幕。
• 一段由 3 或 4 个片段组成的预览故事。 按顺序讲述一段简短的用户旅程，例如：查看主屏幕、开始核心操作、完成操作、查看结果。每个片段都会成为一个视频片段。这些片段会直接拼接，不添加字幕或边框，因此每一步都必须能独立看懂。App Store 视频总时长必须在 15 到 30 秒之间。Google Play 要求提供 YouTube 链接，而不是上传视频，因此 Android 视频会渲染出来供用户自行发布，不受时长限制；如果目标商店包含两个平台，请以 Apple 的时长范围为准。

探索时，记下需要用作选择器的准确可见文本标签和辅助功能 ID，以及没有标签内容的归一化坐标（通常是只有图标的标签栏）。

第 3 步：编写配置和流程

这些是 argent 流程，属于应用自己的流程存储，与其中已记录的其他流程放在一起。配置文件位于 goldie/ 目录中：

<app-repo>/
├── .argent/flows/
│   ├── store-01-<scene>.yaml ...        one per screenshot scene
│   └── store-preview-01-<segment>.yaml  one per preview segment
└── goldie/goldie.config.ts

场景按 argent flow run <name> 的方式命名其流程：flow: "store-01-home" 会运行 .argent/flows/store-01-home.yaml。为营销流程添加前缀，使其与应用的测试流程区分开来；如果已有同名流程可以到达目标屏幕，则重复使用。配置中的 flowsDir 会覆盖流程位置；默认目录是 appRoot 下的 .argent/flows。

阅读 references/config.md，了解配置架构、带注释的示例和文案撰写指南。阅读 references/flows.md，了解流程 YAML 词汇，以及让流程可重放的约定。请用应用自己的语气撰写标题和副标题；它们属于营销文案，应简短并突出收益。

所有内容都相对于配置文件渲染：输出会放在 <app-repo>/goldie/out/。将 goldie/out/ 添加到应用的 .gitignore，并提交 goldie.config.ts 和流程文件。

由于它们是普通的 argent 流程，因此每个流程都可以在应用仓库中单独运行 argent flow run store-01-home。这是完整捕获前检查流程最快的方式。

第 4 步：运行 Doctor，然后进行捕获

每条 goldie 命令都会从 GOLDIE_CONFIG 环境变量读取配置路径。 Shell 状态不会在 Bash 调用之间保留，因此每条 goldie 命令前都要加上它：

GOLDIE_CONFIG=<app-repo>/goldie/goldie.config.ts npx -y goldie@0 doctor

在捕获之前修复 Doctor 标出的所有问题。goldie README 的 Gotchas 部分列出了常见问题及其修复方法；最常见的问题包括 argent 视频水印标记、截图缩放覆盖项，以及 Debug 构建。

然后捕获并渲染静帧（暂时跳过视频，因为需要几分钟）：

GOLDIE_CONFIG=... npx -y goldie@0 capture
GOLDIE_CONFIG=... npx -y goldie@0 frame
GOLDIE_CONFIG=... npx -y goldie@0 manifest

capture 会重放每个流程，包括预览片段，因此原始片段会保留下来，之后可以懒加载渲染视频。

流程出错时

流程重放时不会使用大模型，因此错误的选择器会直接报错。goldie 会输出失败的步骤和 argent 给出的原因。通过 argent MCP 修复：对实时屏幕运行 describe，找到正确的标签或 id，修正 YAML，然后重新运行捕获。优先使用 text: 和 id: 选择器；如果只能使用坐标，则在它上方添加一个 echo: 步骤，说明坐标指向的内容，以便下次修复时知道需要重新解析什么。

第 5 步：打开工作室，懒加载渲染视频

在后台启动工作室。它也需要 GOLDIE_CONFIG，这样才能提供应用仓库的 out/：

GOLDIE_CONFIG=... npx -y goldie@0 studio --no-open   # background task; serves http://localhost:4321

告诉用户工作室已在 http://localhost:4321 启动。然后也在后台渲染预览视频，这样完成后重新加载页面时就会显示：

GOLDIE_CONFIG=... npx -y goldie@0 preview && GOLDIE_CONFIG=... npx -y goldie@0 manifest

如果 preview 因总时长不在 15 到 30 秒之间而拒绝执行，请调整片段节奏（wait: 步骤和 holdSeconds），并且只重新捕获发生变化的内容。

最后运行 GOLDIE_CONFIG=... npx -y goldie@0 verify 并报告结果：有哪些资源、它们的位置，以及是否符合 Apple 的规则。工作室的侧边栏会显示相同的检查结果；红色行表示违反规则。用户可以通过 Design 面板自行调整背景、布局、边框和字体，Export 则可下载可直接上传的 zip 文件。

Google Play

pixel-10-pro 设备密钥会从相同场景渲染 Play 手机截图（1080 x 1920）；不同设备共享场景和流程，选择器匹配时，argent 流程也会在 Android 上重放。添加配置中的 android: { appPath: "<apk>", applicationId: "<id>" } 块，确保存在采用 Pixel 10 Pro 或 Pixel 9 Pro 硬件配置的 AVD（屏幕相同；goldie 会复用正在运行的模拟器，或自行启动 AVD），然后运行相同的捕获和帧命令。Android 磁贴使用随附的 Pixel 10 Pro 边框，而不是配置中的 frame 变体（iPhone 美术图）；android.frame 可替换为你自己的美术图。Play 不接受视频上传（宣传视频使用 YouTube 链接），因此 preview 会渲染 1080x2400 的竖屏视频，供用户自行发布到 YouTube；该视频不受时长限制。

迭代现有配置

后续提示应对应配置或流程中的一项小改动，然后运行能体现该改动的最低成本阶段。不要重新探索应用，也不要重写用户未提及的场景。说明你修改了哪个文件和字段，以便后续提示能够基于此继续。

用户请求	编辑	然后运行
更换标题、副标题或商店文案	scenes[].headline / subhead、store.*	frame、manifest
更换外观：背景、文字颜色、字体、尺寸	theme.*，或者针对单个图块设置 scenes[].background	frame、manifest
更换边框，或移除边框	frame.variant（一个变体，或每个设备键对应一个变体）、theme.screenOnly	frame、manifest
也需要 iPad 截图	devices: ["iphone-6.9", "ipad-13"]、frame.variant["ipad-13"]	capture --device ipad-13、frame、preview、manifest
更丰富的截图条带：全景开场、主视觉、倾斜图块、留白页	theme.template：内置键或布局键序列（参见 references/config.md）	frame、manifest
为每个图块设置不同布局，或只设置一个	theme.layout，或者针对单个图块设置 scenes[].layout	frame、manifest
一个图块中放两个屏幕，或制作双图块全景	scenes[].layout: "duo" / "panorama-duo" 加上 secondScene，或设置为 "panorama"	frame、manifest
在图块上添加徽章、贴纸或徽标	theme.decorations（全部图块）或 scenes[].decorations（单个图块）	frame、manifest
深色模式截图	appearance: "dark"（并相应调整文字颜色）	capture、frame、manifest
调整顺序、删除或添加截图	scenes[]；新场景需要在 .argent/flows 中添加新流程	capture（新流程）、frame、manifest
在某个屏幕上显示不同状态	该场景的流程 YAML	capture、frame、manifest
更改预览叙事或节奏	预览的 segments[]、holdSeconds、流程的 wait: 步骤	capture、preview、manifest
添加另一种语言地区	locales，以及每条文案记录中的 <locale> 键	capture、frame、preview、manifest
让应用本身也显示为各语言地区对应的语言，而不只是文案	localizedCaptures: true（iOS 设备）	capture、frame、preview、manifest

capture 会重放每个流程；若只想重新捕获有变化的内容，可以保留其他场景不变并接受多花一分钟，或者在运行前只删除 out/raw/ 下过期的文件。frame 和 manifest 只需几秒，可以随时运行。工作室会在重新加载时获取更改，地址为 http://localhost:4321；如果工作室未运行，请使用 GOLDIE_CONFIG 再次启动。

工作室的 Design 面板会将更改写入配置文件旁的 goldie.design.json；CLI 的 --background / --frame / --font / --template / --layout / --screen-only 标志则只对单次运行生效；两者都不会修改配置。如果用户在其中尝试了某种设置并希望保留，请将对应值复制到 theme.background、frame.variant、theme.fontFamily、theme.template、theme.layout 或 scenes[].layout，这样下次重新提示时就会从用户当前看到的效果开始。磁盘上当前的值也存储在 goldie/out/web/store.json 的 design 下，这是确认工作室当前显示内容的最快方式。