goldie

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

goldie: App Store assets for the app in this repo

goldie：为本仓库内应用生成App Store资产

goldie replays argent YAML flows on an iOS simulator, captures raw screenshots and recordings, and turns them into upload-ready assets: screenshots get a device bezel, a background, and marketing copy; the preview video is the raw recordings joined as-is, since Apple requires app previews to be a plain screen recording with no framing or captions. A React studio shows the result as the real store page. Your job is everything goldie cannot do alone: pick the screens worth marketing, author the flows that reach them, write the copy, and drive the pipeline.

The end state: 4 or 5 framed screenshots and the raw clips for a preview video, visible in the studio at http://localhost:4321, with the video rendering in the background.

goldie会在iOS模拟器上重放argent YAML流程，捕获原始截图和录屏，并将其转换为可直接上传的资产：截图会添加设备边框、背景和营销文案；预览视频则是原始录屏的拼接，因为苹果要求应用预览必须是无框架、无字幕的纯屏幕录制。一个React工作室会将最终效果展示为真实的商店页面。你的工作是goldie无法独立完成的部分：挑选值得用于营销的界面、编写到达这些界面的流程、撰写文案，并推动整个流程运行。

最终成果：4到5张带框截图，以及预览视频的原始片段，可在http://localhost:4321的工作室中查看，视频会在后台渲染。

Before anything: check for an existing goldie setup

第一步：检查是否已有goldie配置

goldie keeps the whole outcome in files the user can re-prompt against. If the app repo already has a config, this is a follow-up, so read it first and skip to "Iterating on an existing setup" below rather than starting over:

bash

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

Read

goldie/goldie.config.ts

in full and the flows it names. Together they are the source of truth for every visible choice: which screens, in what order, the headlines and subheads, the background and copy colors, the bezel, the store listing, and the preview story. Nothing lives only in your head or in the studio, so a user who says "make it darker" or "swap the search screenshot for settings" is asking for an edit to those files.

goldie会将所有成果保存在文件中，用户可基于这些文件重新发起请求。如果应用仓库已有配置，说明这是后续修改需求，请先读取配置文件，直接跳至下方的“基于现有配置迭代”部分，无需从头开始：

bash

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

完整读取

goldie/goldie.config.ts

以及它引用的流程文件。这些文件是所有可见设置的唯一来源：包括选择哪些界面、界面顺序、标题和副标题、背景和文案颜色、边框、商店列表信息以及预览故事。所有设置都不会仅存在于你的记忆或工作室中，因此当用户要求“调暗背景”或“把搜索截图换成设置截图”时，本质是要求修改这些文件。

Step 0: Make sure goldie runs

步骤0：确保goldie可运行

goldie is an npm package that bundles the CLI, the studio and a pinned argent driver. Nothing needs cloning;

npx

fetches it on first use:

bash

npx -y goldie@0 help

Every command below is

npx -y goldie@0 <cmd>

, referred to as

goldie

. It needs Node 20+ and

ffmpeg

on the PATH (

brew install ffmpeg

). If

$GOLDIE_ROOT

is set, the user is working from a source checkout; run

bun $GOLDIE_ROOT/src/cli.ts <cmd>

instead. All app-specific files live in the app repo.

goldie是一个npm包，集成了CLI、工作室和固定版本的argent驱动。无需克隆仓库；首次使用时

npx

会自动获取它：

bash

npx -y goldie@0 help

以下所有命令均为

npx -y goldie@0 <cmd>

，后续简称为

goldie

。运行它需要Node 20+版本，且

ffmpeg

需在PATH环境变量中（可通过

brew install ffmpeg

安装）。如果已设置

$GOLDIE_ROOT

，说明用户正在从源码目录操作；此时请改用

bun $GOLDIE_ROOT/src/cli.ts <cmd>

运行。所有应用相关文件均存储在应用仓库内。

Step 1: Gather app facts

步骤1：收集应用信息

From the app repo, find:

App name and bundle id. Look in the Xcode project,
```
app.json
```
/
```
app.config.*
```
(Expo), or
```
Info.plist
```
.
A Release simulator build. Look for the newest
```
~/Library/Developer/Xcode/DerivedData/<App>-*/Build/Products/Release-iphonesimulator/<App>.app
```
. If only Debug exists, build Release: a Debug build needs Metro and paints LogBox banners into the captures, so it makes unusable marketing assets. Use the repo's own build scripts if it has them.

从应用仓库中查找：

应用名称和Bundle ID：可在Xcode项目、
```
app.json
```
/
```
app.config.*
```
（Expo项目）或
```
Info.plist
```
中查找。
Release版本模拟器构建包：查找最新的
```
~/Library/Developer/Xcode/DerivedData/<App>-*/Build/Products/Release-iphonesimulator/<App>.app
```
。如果只有Debug版本，请构建Release版本：Debug版本依赖Metro，且会在捕获内容中显示LogBox横幅，无法生成可用的营销资产。如果仓库有自带的构建脚本，请使用脚本构建。

Step 2: Explore the app and choose the scenes

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

Use argent MCP tools to see the app before deciding anything. Boot an iPhone 16 Pro Max class simulator, install the Release build, launch it, and walk the main screens with

describe

and

screenshot

. Also check the app repo for existing recorded flows in

.argent/flows/

; they are the best source of working selectors and coordinates.

Choose:

4 or 5 screenshot scenes. Each is one screen that sells a feature: the main list, a detail view, search, a distinctive feature screen. Prefer screens with real-looking content.
A 3 or 4 segment preview story. One short user journey told in order, for example: see the main screen, start a core action, complete it, see the result. Each segment becomes one clip. The clips are joined with no captions or framing, so each step must read on its own, and the total video must land between 15 and 30 seconds.

While exploring, note the exact visible text labels and accessibility ids you will need as selectors, and normalized coordinates for anything with no label (icon-only tab bars are the usual case).

使用argent MCP工具先查看应用，再做决策。启动iPhone 16 Pro Max级别的模拟器，安装Release版本构建包，启动应用，通过

describe

和

screenshot

命令浏览主要界面。同时检查应用仓库中

.argent/flows/

目录下是否已有录制好的流程；这些流程是获取可用选择器和坐标的最佳来源。

选择：

4到5个截图场景：每个场景对应一个能展示功能的界面，比如主列表、详情页、搜索页、特色功能页。优先选择内容真实自然的界面。
3到4个片段组成的预览故事：一个按顺序呈现的简短用户流程，例如：查看主界面→启动核心操作→完成操作→查看结果。每个片段会成为一个视频剪辑。剪辑直接拼接，无字幕或框架，因此每个步骤必须能独立理解，总视频时长需控制在15到30秒之间。

探索过程中，记录所需的精确可见文本标签和无障碍ID作为选择器，以及无标签元素（通常是纯图标标签栏）的标准化坐标。

Step 3: Author the config and flows

步骤3：编写配置和流程

The flows are argent flows and belong in the app's own flow store, next to any flow already recorded there. The config sits in a

goldie/

directory:

<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

A scene names its flow the way

argent flow run <name>

does:

flow: "store-01-home"

runs

.argent/flows/store-01-home.yaml

. Prefix the marketing flows so they read apart from the app's test flows, and reuse an existing flow by name when one already reaches the screen.

flowsDir

in the config overrides the location; the default is

.argent/flows

under

appRoot

Read

references/config.md

for the config schema, an annotated example, and copywriting guidance. Read

references/flows.md

for the flow YAML vocabulary and the conventions that keep flows replayable. Write the headlines and subheads yourself in the app's voice; they are the marketing layer, so make them benefit-led and short.

Everything renders relative to the config file: output lands in

<app-repo>/goldie/out/

. Add

goldie/out/

to the app's

.gitignore

, and commit

goldie.config.ts

and the flows.

Because they are plain argent flows, each one is runnable on its own with

argent flow run store-01-home

from the app repo, which is the fastest way to check a flow before a full capture.

流程为argent流程，需存储在应用自身的流程仓库中，与已录制的其他流程放在一起。配置文件存储在

goldie/

目录下：

<app-repo>/
├── .argent/flows/
│   ├── store-01-<scene>.yaml ...        每个截图场景对应一个文件
│   └── store-preview-01-<segment>.yaml  每个预览片段对应一个文件
└── 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

获取配置 schema、带注释的示例和文案撰写指南。查看

references/flows.md

获取流程YAML的语法和保持流程可重放的约定。请以应用的风格自行撰写标题和副标题；这是营销层面的内容，需突出价值且简洁。

所有内容均相对于配置文件渲染：输出结果会保存在

<app-repo>/goldie/out/

目录下。将

goldie/out/

添加到应用的

.gitignore

文件中，并提交

goldie.config.ts

和流程文件。

由于这些是标准的argent流程，每个流程都可单独在应用仓库中通过

argent flow run store-01-home

运行，这是在完整捕获前检查流程是否可用的最快方式。

Step 4: Doctor, then capture

步骤4：检查配置，然后捕获内容

Every goldie command reads the config path from the

GOLDIE_CONFIG

env var. Shell state does not persist between your Bash calls, so prefix every goldie command with it:

bash

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

Fix everything doctor flags before capturing. The usual findings and their fixes are in the Gotchas section of goldie's README; the common ones are the argent video watermark flag, a screenshot scale override, and a Debug build.

Then capture and render the stills (skip the video for now, it takes minutes):

bash

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

capture

replays every flow, including the preview segments, so the raw clips exist for the lazy video render later.

每个goldie命令都会从

GOLDIE_CONFIG

环境变量读取配置路径。Bash调用之间不会保留Shell状态，因此请在每个goldie命令前添加该环境变量：

bash

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

在捕获内容前修复

doctor

命令标记的所有问题。常见问题及修复方法可在goldie README的Gotchas部分找到；其中最常见的问题包括argent视频水印标记、截图缩放覆盖设置和使用Debug版本构建包。

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

bash

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

capture

会重放所有流程，包括预览片段，因此后续懒加载渲染视频时所需的原始剪辑已存在。

When a flow breaks

流程运行失败时

Flows replay with no LLM, so a wrong selector fails loudly. goldie prints the failed step and argent's reason. Fix it over argent MCP:

describe

the live screen to find the real label or id, correct the YAML, and re-run capture. Prefer

text:

and

id:

selectors; when only a coordinate works, add an

echo:

step above it explaining what it points at, so the next repair knows what to re-resolve.

流程重放不依赖大语言模型，因此错误的选择器会直接导致运行失败。goldie会打印失败的步骤和argent给出的原因。通过argent MCP修复：使用

describe

命令查看当前界面，找到正确的标签或ID，修改YAML文件，然后重新运行

capture

。优先使用

text:

和

id:

选择器；当只能使用坐标时，在该步骤上方添加

echo:

步骤说明坐标指向的元素，方便后续维护时重新定位。

Step 5: Open the studio, render the video lazily

步骤5：启动工作室，懒加载渲染视频

Start the studio in the background. It needs

GOLDIE_CONFIG

too, so it serves the app repo's

out/

bash

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

Tell the user it is up at http://localhost:4321. Then, also in the background, render the preview video so it appears on reload once done:

bash

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

preview

refuses because the total is outside 15 to 30 seconds, adjust segment pacing (

wait:

steps and

holdSeconds

) and re-capture only what changed.

Finish with

GOLDIE_CONFIG=... npx -y goldie@0 verify

and report the result: which assets exist, where they are, and whether they pass Apple's rules. The studio's sidebar shows the same checks; a red row is a rule violation. The Design panel lets the user restyle backgrounds, layouts, bezels and fonts without you, and Export downloads an upload-ready zip.

在后台启动工作室。它同样需要

GOLDIE_CONFIG

环境变量，这样才能加载应用仓库的

out/

目录内容：

bash

GOLDIE_CONFIG=... npx -y goldie@0 studio --no-open   # 后台任务；服务地址为http://localhost:4321

告知用户工作室已在http://localhost:4321启动。然后同样在后台渲染预览视频，完成后刷新页面即可查看：

bash

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

并报告结果：已生成哪些资产、存储位置，以及是否符合苹果的规则。工作室侧边栏会显示相同的检查结果；红色行表示违反规则。设计面板允许用户自行重新设置背景、布局、边框和字体，无需你的参与，导出功能可下载可直接上传的压缩包。

Iterating on an existing setup

基于现有配置迭代

A follow-up prompt maps onto a small change in the config or a flow, then the cheapest stage that reflects it. Do not re-explore the app or rewrite scenes the user did not mention. Report which file and field you changed so the next prompt can build on it.

The user asks for	Edit	Then run
Different headline, subhead or store copy	`scenes[].headline` / `subhead` , `store.*`	`frame` , `manifest`
A new look: background, text colors, font, sizing	`theme.*` , or `scenes[].background` for one tile	`frame` , `manifest`
A different bezel, or no bezel	`frame.variant` , `theme.screenOnly`	`frame` , `manifest`
A varied strip: panorama opener, hero, tilted tiles, a breather	`theme.template` : a built-in key or a sequence of layout keys (see `references/config.md` )	`frame` , `manifest`
A different layout for every tile, or one	`theme.layout` , or `scenes[].layout` for one tile	`frame` , `manifest`
Two screens in one tile, or a two-tile panorama	`scenes[].layout: "duo"` / `"panorama-duo"` plus `secondScene` , or `"panorama"`	`frame` , `manifest`
A badge, sticker or logo on the tiles	`theme.decorations` (all) or `scenes[].decorations` (one)	`frame` , `manifest`
Dark mode captures	`appearance: "dark"` (and text colors to match)	`capture` , `frame` , `manifest`
Reorder, drop or add a screenshot	`scenes[]` ; a new scene needs a new flow in `.argent/flows`	`capture` (new flows), `frame` , `manifest`
Show a different state on one screen	the scene's flow YAML	`capture` , `frame` , `manifest`
Change the preview story or its pacing	preview `segments[]` , `holdSeconds` , flow `wait:` steps	`capture` , `preview` , `manifest`
Another locale	`locales` , plus a `<locale>` key in every copy record	`capture` , `frame` , `preview` , `manifest`

capture

replays every flow; to re-capture only what changed, keep the other scenes as they are and accept the extra minute, or delete only the stale files under

out/raw/

before running it.

frame

and

manifest

take seconds, so run them freely. The studio at http://localhost:4321 picks up changes on reload; start it again with

GOLDIE_CONFIG

if it is not running.

The studio's Design panel writes to

goldie.design.json

next to the config, and the CLI's

--background

--frame

--font

--template

--layout

--screen-only

flags are one-run overrides; neither touches the config. If the user tried something there and wants to keep it, copy the value into

theme.background

frame.variant

theme.fontFamily

theme.template

theme.layout

scenes[].layout

so the next re-prompt starts from what they see. The current on-disk values are also in

goldie/out/web/store.json

under

design

, which is the fastest way to confirm what the studio is showing right now.

后续请求对应配置或流程中的小修改，然后运行能反映修改的最低成本步骤。无需重新探索应用或重写用户未提及的场景。告知用户你修改了哪个文件和字段，以便后续请求可基于此继续调整。

用户需求	修改内容	运行命令
修改标题、副标题或商店文案	`scenes[].headline` / `subhead` 、 `store.*`	`frame` , `manifest`
更换外观：背景、文字颜色、字体、尺寸	`theme.*` ，或针对单个卡片修改 `scenes[].background`	`frame` , `manifest`
更换边框或移除边框	`frame.variant` 、 `theme.screenOnly`	`frame` , `manifest`
更换布局样式：全景开场、主视觉、倾斜卡片、留白	`theme.template` ：内置模板键或布局键序列（查看 `references/config.md` ）	`frame` , `manifest`
为所有卡片或单个卡片更换布局	`theme.layout` ，或针对单个卡片修改 `scenes[].layout`	`frame` , `manifest`
单个卡片显示两个界面，或双卡片全景布局	`scenes[].layout: "duo"` / `"panorama-duo"` 加上 `secondScene` ，或使用 `"panorama"`	`frame` , `manifest`
在卡片上添加徽章、贴纸或Logo	`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`

capture

会重放所有流程；若仅需重新捕获修改的部分，可保留其他场景不变，接受额外的一分钟耗时，或在运行前删除

out/raw/

下的过时文件。

frame

和

manifest

仅需数秒，可随时运行。http://localhost:4321的工作室会在刷新后加载修改内容；如果工作室未运行，请重新使用`GOLDIE_CONFIG`启动它。

工作室的设计面板会将修改写入配置文件旁的

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

字段中查看，这是确认工作室当前展示内容的最快方式。