vibe-aso

Vibe ASO — 在 Claude Code 中完成 App Store 全流程

你已经开发好一款应用。这个技能将助你完成后续所有工作：用户会搜索什么、每种语言的商店页面文案、截图文案、各国家和地区的应用定价，以及用户安装应用后看到的内容。

本技能分为六个阶段。新应用按顺序执行；也可以直接跳到用户指定的阶段。每个阶段都有一份参考文件，详细列出了完整规则——开始某个阶段前，请先阅读对应的参考文件；本页面只是地图，并非整个领地。

阶段	内容	参考文件
0 SETUP	一次性配置向导：ASC API 密钥、翻译引擎、数据源	下文
1 RESEARCH	关键词研究 → 主关键词、副标题关键词、关键词字段	reference/keyword-research.md
2 METADATA	名称／副标题／关键词／描述，先完成 en-US，再处理所有选定的语言区域	reference/metadata.md
3 SCREENSHOTS	将本地化标题叠加到用户的样图上，覆盖所有语言区域	reference/screenshots.md
4 PRICING	由用户选择定价模式，并应用到各个市场	reference/pricing.md
5 IN-APP	本地化应用自身的 UI 字符串	reference/app-localization.md
6 SUBMIT	上传、验证，以及 Apple API 无法完成的手动操作清单	reference/submission-checklist.md

完整示例会逐一演示所有参考文件：一款品牌名为 Glow Up 的卡路里追踪应用。每条规则都会通过它来展示，但没有任何规则仅适用于这款应用。

阶段 0 — 设置向导（首次运行，或检查失败时）

先运行 scripts/check_setup.sh。如果全部通过，跳转到用户想执行的阶段。否则，按以下顺序引导用户完成仅缺少的部分：

1. App Store Connect API 密钥（阶段 2、3、4、6 需要）。 请用户创建密钥：前往 App Store Connect → 用户与访问权限 → 集成 → App Store Connect API → 团队密钥 → 生成 API 密钥，角色选择 App Manager，然后下载 .p8 文件（只能下载一次）。接着：

• 将 .p8 文件存储在 ~/.vibe-aso/AuthKey.p8，并运行 chmod 600。
• 写入 ~/.vibe-aso/config.json（创建目录并运行 chmod 700，文件运行 chmod 600）：

{
  "asc": {
    "key_id": "<10-char Key ID shown next to the key>",
    "issuer_id": "<UUID at the top of the Team Keys page>",
    "p8_path": "~/.vibe-aso/AuthKey.p8"
  },
  "translation": { "engine": "subagents" }
}

• 运行 ruby scripts/asc.rb GET '/v1/apps?limit=1' 验证 → 必须打印 HTTP 200。

**安全性不可妥协：**密钥必须存放在 ~/.vibe-aso/ 中，绝不能放在任何项目目录、仓库或提交中，也绝不能回显到终端，或粘贴到用户可能分享的文件中。如果用户在聊天中粘贴密钥内容，请保存该密钥，并告知他们：如果此对话曾离开其设备，就应撤销并重新生成密钥。

2. 翻译引擎（阶段 2、3、5）。通过 AskUserQuestion 询问：

• Claude 子 Agent（默认；推荐）——翻译由启动的子 Agent 按地区批量生成。无需额外账户或密钥。费用计入用户现有的 Claude 使用量。
• DeepSeek API——处理超大批量时成本最低（整个应用内目录 × 40 个地区只需几美分）。密钥存放在 ~/.vibe-aso/deepseek-key （chmod 600），配置为：{"engine": "deepseek", "api_key_path": "~/.vibe-aso/deepseek-key", "base_url": "https://api.deepseek.com", "model": "deepseek-chat"}。
• 任何兼容 OpenAI 的 API——配置格式相同：{"engine": "openai", "api_key_path": "...", "base_url": "...", "model": "..."}。用户可自行选择服务提供商。

对于 API 引擎，在进行任何长时间运行之前，先用一个小请求验证密钥是否有效。对于 DeepSeek，务必检查账户余额，而不只是密钥——有效密钥遇到空账户时，每个请求都会返回 HTTP 402；而且可能在级联运行 30 分钟后才失败，而不是一开始就失败（check_setup.sh 会检查这一点）。

3. 关键词数据来源（阶段 1）。研究方法需要每个关键词的：热度（搜索量的替代指标）、难度，最好还包括“有多少应用在名称或副标题中使用该关键词”。询问用户有哪些工具：

• Astro（Mac ASO 应用），且已连接其 MCP 服务——支持最好；参考文件会将每个步骤对应到 Astro 的工具。
• 其他 ASO 工具（AppFigures、Sensor Tower、Mobile Action、AppTweak……）——方法相同；用户在自己的工具中查询，并在需要时粘贴数据。
• 没有工具——阶段 1 仍可进行，但会如实说明能力有所下降：Apple 自带的搜索建议和竞争对手列表可提供关键词候选项，而该技能会明确说明热度和难度的判断只是猜测。建议用户在决定将某个关键词用于应用名称之前，先获取数据工具。

将答案存入配置中的 "keyword_source": "astro" | "manual" | "none"。

跨阶段规则

这些规则适用于每个阶段；参考文件会在相关之处重复说明。

1. 一次性覆盖所有语言区域，通过自动检查进行审核。 除非用户明确要求，否则绝不要因等待逐语言人工审核而暂停本地化流程。人无法审核 40 多种语言，而且审核一种语言并不能说明其他 39 种语言的情况。有效的审核方式包括：字符数限制检查、格式说明符一致性检查、原样保留内容检查、与源文相同内容检测，以及对难处理文字系统（中日韩文字、从右向左文字、印度文字）的抽查——这些都在参考文件中定义。
2. 在第 2 阶段询问一次要涵盖哪些语言区域。 默认值：所有受支持的语言区域。用户可以缩小范围（例如，覆盖前 15 大市场）；所选范围也适用于截图和应用内字符串。不要在每个阶段重复询问。
3. App Store Connect 是所有 Apple 相关事项的事实来源——包括线上元数据、价格、审核状态和应用内购买项目是否存在。编辑前先从中获取信息；不要相信可能过时的本地副本，而忽略线上条目。
4. 一次性完整扫描，再在本地切分。 ASC API 速度慢且有速率限制。凡是需要遍历多个语言区域或多个产品的操作，都只需导出到本地文件一次；后续问题一律根据该文件回答，不要因为分析发生变化而重新扫描。
5. 收到 2xx 响应不代表已验证。 每次写入后，都要 GET 回读该字段并检查值。只报告已通过回读确认的内容。
6. 字符数限制不可超出：名称 30，副标题 30，关键词字段 100，推广文本 170，描述 4000。写入后按语言区域逐一验证。
7. 有些字符串绝不本地化：Apple 产品名称（iPhone、Apple Watch、iPad）、URL、电子邮件地址、用户所用样式的品牌名称、产品代码。翻译后的客服邮箱无法正常使用 mailto；“翻译后”的 URL 会导致 404。
8. 将长时间运行的工作拆分执行。 翻译级联和批量上传应拆分为多个小型前台命令（按语言区域、按批次），不要用一个超出 shell 耐心范围的巨型调用。只报告在磁盘上或通过 API 回读验证的结果——“级联正在运行”不算结果。

此技能中的脚本和资源

scripts/asc.rb          # minimal ASC API client — ruby asc.rb GET '/v1/apps'
scripts/check_setup.sh  # PASS/WARN/FAIL per prerequisite, with fix commands
renderer/               # screenshot heading renderer (playwright + per-script fonts)
renderer/fetch_fonts.sh # one-time ~55MB font download (DM Sans + Noto per script)
reference/*.md          # the six phase guides — read before the phase

渲染器需要在 renderer/ 中一次性运行 npm install && npx playwright install chromium 和 ./fetch_fonts.sh（check_setup.sh 会提示缺少哪些内容）。

免费 Figma 样机模板（包含 iPhone / iPad / Apple Watch 边框和 “Your screenshot here”占位符）——用户没有截图设计稿或询问如何提供截图时，请提供此模板： https://www.figma.com/design/ftvaN3ZMfgkGrn7SAuqCvt/vibe-ASO-mockups

报告

每个阶段结束时都要包含三个简短部分：已完成（发生了什么、已验证的内容）、 问题（遇到了什么意外情况以及如何处理）、需要你处理（仅限用户才能完成的手动步骤——或者写“无”）。只报告结果层面的内容；除非用户询问，否则不要提文件路径和内部细节。