gpc-metadata-sync

GPC 元数据同步

使用场景

在任务涉及以下内容时使用此技能：

• 查看或更新商店详情（标题、描述、简短描述）
• 在本地文件与 Google Play Console 之间同步元数据
• 管理截图和图片（上传、删除、列出）
• 使用兼容 Fastlane 的元数据目录结构
• 管理多语言商店详情
• 将商店详情拉取到本地以进行版本控制
• 将本地商店详情推送到 Play Console

所需输入

• 软件包名称（或通过 GPC_APP 配置的默认值）
• 语言代码（例如 en-US、ja-JP）
• 对于推送/拉取：元数据文件的本地目录路径
• 对于图片：图片类型和文件路径

操作步骤

0) 查看当前商店详情

# Default language listing
gpc listings get

# Specific language
gpc listings get --lang ja-JP

# All languages at once (omit --lang)
gpc listings get

# JSON output for scripting
gpc listings get --output json

1) 直接更新商店详情

gpc listings update --lang en-US \
  --title "My App" \
  --short "A great app for great things" \
  --full "Full description here..."

也可以从文件中读取完整描述：

gpc listings update --lang en-US --full-file metadata/en-US/full_description.txt

如需在一次编辑中更新 Fastlane 风格目录中的所有语言区域，请使用 gpc listings push --dir metadata/（第 2 节）。

1a) 在本地验证商店详情（lint）

无需调用 API 的本地验证——在推送前检查字符数限制：

gpc listings lint

# Point at a specific metadata directory
gpc listings lint --dir metadata/
gpc listings lint --dir fastlane/metadata/android/

输出表格：

Field             Chars  Limit   %    Status
────────────────────────────────────────────
title              28     30    93%    ✓
shortDescription   76     80    95%    ✓
fullDescription   3820   4000   96%    ✓
video URL          0      256    0%    ✓

强制执行的字符数限制：title = 30、shortDescription = 80、fullDescription = 4000、视频 URL = 256。

如果任何字段超出限制，则返回退出码 1。可将其用作提交前或推送前的检查关卡。

1b) 验证线上商店详情（analyze）

从 Play Store 获取线上商店详情，并执行相同的字符数限制检查：

gpc listings analyze

# Compare against an expected set of locales
gpc listings analyze --expected en-US,ja-JP,de-DE

# JSON output
gpc listings analyze --json

输出表格与 lint 相同，但反映的是 Play Store 当前上线的内容。--expected 标志会标记列表中存在但 Play Console 中缺失的语言区域（反之亦然）。

2) 拉取/推送工作流（双向同步）

这是对商店详情进行版本控制的推荐工作流。

拉取（从 Play Console 下载到本地）：

gpc listings pull --dir metadata/

创建以下目录结构：

metadata/
├── en-US/
│   ├── title.txt
│   ├── short_description.txt
│   ├── full_description.txt
│   └── changelogs/
│       └── 142.txt
├── ja-JP/
│   ├── title.txt
│   ├── short_description.txt
│   └── full_description.txt
└── ...

推送（将本地文件上传到 Play Console）：

gpc listings push --dir metadata/

# Prevent changes from being auto-submitted for review
gpc listings push --dir metadata/ --changes-not-sent-for-review

# Fail if the app is currently in review or rejected
gpc listings push --dir metadata/ --error-if-in-review

# Preview changes without applying
gpc listings push --dir metadata/ --dry-run

# Bypass the preflight lint gate (not recommended)
gpc listings push --dir metadata/ --force

上传前 lint 检查关卡： gpc listings push 会在上传前自动运行 gpc listings lint。如果任何字段超出字符数限制，推送操作将中止并返回退出码 1。传入 --force 可跳过检查并继续推送。

阅读：

• references/directory-structure.md

3) Fastlane 兼容性

GPC 可读取和写入 Fastlane 元数据目录格式。如果你要从 Fastlane 迁移：

# Your existing Fastlane metadata/ directory works as-is
gpc listings push --dir fastlane/metadata/android/

# Pull into Fastlane-compatible structure
gpc listings pull --dir fastlane/metadata/android/

阅读：

• references/fastlane-migration.md

4) 图片管理

列出已有图片：

gpc listings images list --lang en-US --type phoneScreenshots

图片类型：phoneScreenshots、sevenInchScreenshots、tenInchScreenshots、tvScreenshots、wearScreenshots、icon、featureGraphic、tvBanner、promoGraphic。

上传图片：

# Single image
gpc listings images upload --lang en-US --type phoneScreenshots screenshot.png

# Multiple images (glob)
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png

# Preview what would be uploaded without making API calls (v0.9.74+)
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png --dry-run

删除图片：

gpc listings images delete --lang en-US --type phoneScreenshots --id <image-id>

# Preview what would be deleted without making API calls (v0.9.74+)
gpc listings images delete --lang en-US --type phoneScreenshots --dry-run

v0.9.74 新增： gpc listings images upload 和 gpc listings images delete 均支持 --dry-run。在试运行模式下，命令会打印将要执行的操作（将上传的文件、将删除的图片 ID），而不会调用 Play API。

AI 生成图片声明（v0.9.96+）

Google Play 要求开发者声明由 AI 生成的商店图片。传入 --ai-generated 可在上传时记录该声明；不传入此标志则会上传图片，但不作声明。images upload 和 images sync 均支持此标志；对于 sync，该标志适用于本次运行上传的所有图片——因此，请将 AI 生成的图片单独分批运行，而不要对混合目录作声明。

gpc listings images upload ./screenshots/hero.png \
  --app com.example.app --lang en-US --type phoneScreenshots --ai-generated

gpc listings images sync --dir ./ai-screens --lang en-US --type phoneScreenshots --ai-generated

从本地目录同步图片（v0.9.69+）——优先使用此命令，而非逐张上传/删除

gpc listings images sync 使用 SHA-256 内容哈希对图片进行去重——只上传 Play Store 上尚不存在的文件，并可选择删除远程没有对应本地文件的图片。整个操作只需进行一次 Play 编辑和一次提交。

保存配额规则（重要——始终优先使用 sync）。 Google 对每个应用设定了远低于常规 API 请求配额的发布（保存）上限，每次提交编辑都会计为一次保存。逐张使用 gpc listings images upload 和 gpc listings images delete 命令时，每条命令都会单独开启并提交编辑，因此对多个语言区域循环执行这些命令会让每次调用都消耗一次保存配额——例如，使用先删除再上传的方式处理 27 个语言区域、2 种设备类型中的 5 张图片，每次运行大约会消耗 540 次保存配额，运行几次就会耗尽每日限额。sync --dir（可选搭配 --delete）会将整个操作合并为一次保存；如果重复运行后没有任何变化，则会直接丢弃，不执行提交，耗费零次配额。只有在确实需要一次性修复单张图片时，才使用独立的 upload/delete 命令。

# Sync EVERY locale and image type under a tree, mirror deletions — one save for the whole run
gpc listings images sync --dir ./images --delete

# Sync all phone screenshots for en-US from a local directory
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/

# Sync all image types for a language
gpc listings images sync --lang en-US --dir ./screenshots/en-US/

# Preview what would change without touching the API (spends no save)
gpc listings images sync --dir ./images --delete --dry-run

主要行为：

• 将每个本地文件的 SHA-256 哈希与远程图片哈希进行比较。已匹配的图片会跳过（不会重新上传）。
• 整个操作只需一次编辑和一次提交 = 一次保存（无操作时为零次）。这是符合配额要求的安全方式；请参阅上方的保存配额规则。
• --delete 会删除没有匹配本地文件的远程图片。不使用此标志时，多余的远程图片会保留。
• 使用 --delete 时保证显示顺序（v0.9.92+）： Play API 没有重新排序接口，并且会保留上传顺序，因此仅按哈希进行部分更新会导致屏幕截图顺序错乱（未更改的图片保留原位，已更改的图片则追加到末尾）。当某个语言区域/类型的内容或顺序与本地不一致时，--delete 会通过一次调用清空该组合，并按已排序的文件名顺序重新上传本地文件（1.png、2.png……）；顺序已正确的组合则会跳过。请按显示顺序为文件命名；接近每种类型的数量上限时，请在文件名前补零（01.png）。
• 本地目录不存在时的安全处理（v0.9.92+）： 本地不存在的类型目录会保持原样，因此只同步屏幕截图不会清除远程图标或宣传图。存在但为空的目录表示明确要“清除此类型”。
• 目录不可读时的安全处理（v1.0.0-rc.1+）： 如果本地图片目录存在但无法读取（权限问题，或 CI 容器中的卷所有权问题），同步会以 IMAGE_SYNC_DIR_UNREADABLE 停止（退出码 1），不会更改 Google Play 上的任何内容。早期版本会将其视为空目录，因此 --delete 可能会清除对应的远程图片。只有实际读取失败时才会触发此错误；目录不存在仍会跳过。
• --dry-run 会打印差异表（add / skip / delete），不会调用任何 API。
• 支持与 gpc listings images upload 相同的图片类型：phoneScreenshots、sevenInchScreenshots、tenInchScreenshots、tvScreenshots、wearScreenshots、icon、featureGraphic、tvBanner、promoGraphic。

标志	说明
--dir	包含要同步的图片文件的本地目录
--lang	语言代码（例如 en-US、ja-JP）
--type	图片类型筛选条件（省略时同步目录中的所有类型）
--delete	删除没有对应本地文件的远程图片
--ai-generated	声明本次运行上传的所有图片均由 AI 生成（v0.9.96+）
--dry-run	预览更改，不上传或删除图片

5）多语言工作流

对于支持多种语言的应用：

# Pull all languages
gpc listings pull --dir metadata/

# Edit locally (use your preferred text editor or translation tools)

# Push all languages back
gpc listings push --dir metadata/ --dry-run  # Preview first
gpc listings push --dir metadata/ --changes-not-sent-for-review  # Apply without auto-submitting for review

**提示：**如需为每种语言生成“更新内容”发布说明文本（而非完整的商品信息字段），请参阅 gpc changelog generate --target play-store（v0.9.62+）——该命令会读取你的 git log，并生成各语言的输出，同时确保不超过 Play Store 的 500 字符限制。添加 --ai（v0.9.63+）后，可使用你自己的 LLM 密钥翻译非源语言（自动检测 AI_GATEWAY_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY）。

6）使用 dry-run 预览

所有写入操作都支持 --dry-run：

gpc listings update --lang en-US --title "New Title" --dry-run
gpc listings push --dir metadata/ --dry-run
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png --dry-run
gpc listings images delete --lang en-US --type phoneScreenshots --dry-run
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/ --dry-run

在 dry-run 模式下不会发起 API 调用。输出会说明将要发生的更改：将上传的文件、将删除的图片 ID，以及将更新的字段。

验证

• gpc listings get --lang <lang> 会显示更新后的内容
• gpc listings get（不带 --lang）可确认所有语言均正确
• gpc listings images list --lang <lang> --type <type> 会显示已上传的图片
• Play Console 界面会反映更改（可能需要几分钟）

安全说明（v0.9.74+）

--notes-dir 中的符号链接遍历防护

使用 --notes-dir 加载发布说明时（例如 gpc releases upload --notes-dir changelogs/），GPC 现在会对每个条目调用 lstat()，并在读取文件内容前拒绝符号链接。这可防止目录遍历攻击，例如攻击者在说明目录中放置经过构造的符号链接，指向目录树外的敏感文件（如 /etc/passwd、SSH 密钥）。

如果遇到符号链接，命令会退出并显示错误说明，指出有问题的路径。请在说明目录中使用实际文件。

防止评论导出中的 CSV 公式注入

gpc reviews export 和其他生成 CSV 输出的命令，现在会为以 =、+、-、@、制表符（\t）或回车符（\r）开头的单元格添加单引号（'）前缀。这样可防止电子表格应用（Excel、Google Sheets）在打开 CSV 时，将用户提供的内容（评论文本、应用标题）解释为公式。

如果你以编程方式处理 CSV，请根据需要去掉字符串值开头的 '。

故障情形 / 调试

症状	可能原因	修复方法
LISTING_NOT_FOUND	Play Console 中尚未设置该语言	先在 Console 中添加该语言，然后推送
运行几次后超出每日保存/发布配额	循环逐张执行 upload/delete（每次提交的编辑都会单独保存一次）	改用 gpc listings images sync --dir ... --delete（整次运行只保存一次），并使用 gpc listings push --dir 推送文本。请参阅第 4 节中的保存配额规则。
部分更新后截图显示顺序错乱	GPC 版本较旧，或逐张上传图片会将更改的图片追加到末尾	升级到 v0.9.92+ 并使用 sync --delete（确保顺序）；将文件命名为 1.png、2.png、……
IMAGE_SYNC_DIR_UNREADABLE（退出码 1）	本地图片目录存在，但无法读取（权限问题、CI 卷所有权问题）	修正目录权限后重试。Google Play 上的内容未发生任何更改（v1.0.0-rc.1+）
图片上传失败	格式或尺寸错误	检查 Google 的图片要求（PNG/JPEG、各类型的尺寸限制）
描述被截断	超出字符限制	标题：30 个字符；简短说明：80 个字符；完整说明：4000 个字符
推送时显示没有更改	本地文件与远程内容一致	确认编辑已保存到正确的文件路径
编码问题	文件编码不是 UTF-8	确保所有文本文件均采用 UTF-8 编码

相关技能

• gpc-setup：身份验证和配置
• gpc-release-flow：上传和发布管理
• gpc-ci-integration：在 CI/CD 中自动同步元数据