在拉取 App Store 元数据后，用离线检查和…

适用于已通过 asc metadata pull 将 App Store 元数据拉到 ./metadata 后，检查字段利用、关键词浪费/缺失/分隔符/跨区域本地化，并通过 Astro MCP 和 Apple 标签做关键词差距分析。

适用场景

解决思路

1. 读取 references/aso_rules.md，了解每项检查执行的规则。
2. 识别 metadata/version/ 下最新版本目录（语义版本号最高），所有 version-level 字段都使用该目录。
3. 主 locale 默认使用 en-US，除非用户另行指定。
4. 按路径读取元数据：app-info 字段（subtitle）在 metadata/app-info/{locale}.json；version 字段（keywords、description、whatsNew）在 metadata/version/{latest-version}/{locale}.json；App name 可能不在导出中，若 app-info JSON 缺少 name，则用 asc apps info list 获取或询问用户，不要把它标记为缺失字段错误。
5. 离线检查 1：关键词浪费。读取 metadata/app-info/{locale}.json 的 subtitle（以及 name 若存在），读取 metadata/version/{latest-version}/{locale}.json 的 keywords；对 subtitle（+ name）分词：拉丁/西里尔按空白分割、去除首尾标点、转小写；中文/日文/韩文按 、，, 或逐字符/字符组分词，不能用空白分词；阿拉伯语按空白分词，并生成去掉 ال 前缀的变体；keywords 按逗号分割、trim、小写；报告交集（包括前缀剥离后的模糊匹配），例如 quran 同时出现在 subtitle 和 keywords，应标记为警告并建议从 keywords 移除，以节省字符。
6. 离线检查 2：未充分利用字段。检查 keywords 是否至少 90 字符（限制 100），subtitle 是否至少 20 字符（限制 30）；低于推荐最小值则标记警告，并说明未使用的索引机会。
7. 离线检查 3：缺失字段。标记空或缺失的 subtitle、keywords、description、whatsNew；name 仅在 app-info JSON 明确包含 name 键且值为空时才标记，否则不要因导出缺失而标记。
8. 离线检查 4：错误关键词分隔符。检查 keywords 中是否存在逗号后有空格、用分号代替逗号、用竖线代替逗号；发现则标记错误，并指出浪费的字符。
9. 离线检查 5：跨区域关键词缺口。加载所有 locale 的 keywords；将每个非主 locale 与主 locale（默认 en-US）比较；标记与主 locale 完全相同（不区分大小写）的 locale，通常说明未本地化，标记警告。
10. 离线检查 6：Description 关键词覆盖。加载每个 locale 的 keywords 和 description；对每个关键词在 description 中做不区分大小写的子串检查；考虑词形变化（阿拉伯词根匹配、动词变位如 memorizar≈memorices、格变化如俄语 сура≈суры）；报告每个 locale 缺失的关键词，并建议自然融入现有句子；不要标记非拉丁描述中的拉丁关键词（如西里尔文本中的 quran），因为面向独立搜索路径。
11. 可选 App 标签对齐：运行 asc app-tags list --app "APP_ID" --output json 和 asc app-tags view --app "APP_ID" --id "TAG_ID" --output json；把 tags 仅作为上下文：若可见 tags 强化 subtitle/keywords 策略，记录一致性；若 tags 指向非预期类别或用例，建议修改 metadata/category 以可能改善未来分类；不要承诺修改 metadata 会立即改变 Apple 生成的 tags。
12. 可选官方 Apple 搜索计划：当 App Store Connect 和 Apple Ads 凭据都配置时，运行实验性只读命令 asc optimize search plan --app "APP_ID" --version "1.2.3" --ad-account "AD_ACCOUNT_ID" --country "US" --genre "PRODUCTIVITY_UTILITIES" --locale "en-US" --out-dir ".asc/optimization/1.2.3" --output markdown；用 asc auth 认证 App Store Connect，用 asc ads auth login 单独认证 Apple Ads，两套凭据独立；将生成的 CSV 和 JSON 视为审查工件；该命令不应用 metadata、exact keywords 或 negative keywords，Apple Ads 部分源失败会保留在报告中；保持 Apple popularity、app-specific paid reach、paid search outcomes、metadata coverage 区分，不要从中推断 organic rank 或 keyword difficulty。
13. Phase 2 Astro MCP 关键词缺口分析：如果 Astro MCP 可用且应用已跟踪，按 store/locale 运行，不要只跑 US store，因为关键词流行度跨市场差异很大。
14. Astro 步骤 1：调用 get_app_keywords，传入 app ID，获取跟踪的关键词及当前排名。
15. Astro 步骤 2：检查多商店跟踪。针对每个 locale 的 App Store territory 查询现有跟踪；将未跟踪商店报告为不可用并继续审计；仅在用户另行授权跟踪设置时才用 add_keywords；未跟踪商店的空排名不能证明表现差。
16. Astro 步骤 3：调用 extract_competitors_keywords，传入 3-5 个顶级竞品 app ID，查找关键词缺口；这是最高价值的 Astro 工具，能揭示竞品有排名而你没有的关键词；尽可能按 store 运行。
17. Astro 步骤 4：调用 get_keyword_suggestions，传入 app ID，基于分类分析获取额外推荐。
18. Astro 步骤 5：调用 search_rankings，查看应用在每个 store 中对跟踪关键词的当前排名。
19. Astro 步骤 6：将建议和竞品关键词与本地元数据中 subtitle、name（若可用）、keywords 字段的 token 做 diff。
20. Astro 步骤 7：按 popularity score 从高到低展示所有缺口；注明来源（竞品分析 vs. 建议）。
21. 跨字段组合策略：推荐新增关键词时考虑单词在索引字段（title + subtitle + keywords）之间的组合；例如 keywords 加 namaz 且已有 vakti 可匹配 namaz vakti（66 popularity），keywords 加 holy 且 subtitle 有 Quran 可匹配 holy quran（58 popularity）；在推荐中标记高价值组合。
22. 跳过条件：Astro MCP 未连接则跳过并注明 Connect Astro MCP for keyword gap analysis；应用未在 Astro 跟踪则跳过并注明 Add app to Astro with mcp__astro__add_app for gap analysis；某 locale 的 store 未跟踪则报告缺口并跳过其排名，跟踪设置需单独授权。
23. 按指定输出格式输出单一审计报告，只覆盖最新版本目录：包含字段利用表（Name、Subtitle、Keywords、Promotional Text、Description 的值、长度、限制、使用率）；离线检查表（#、Check、Severity、Field、Locale、Detail）；摘要行（X errors、Y warnings across Z locales）；关键词缺口分析表（Keyword、Popularity、In Metadata?、Suggested Action）；建议按优先级排列（errors 优先，其次 keyword waste，再次 utilization improvements，最后 keyword gap opportunities）。
24. 注意事项：离线检查无需网络，只读本地文件；Astro gap analysis 是附加项，没有它审计仍有用；在 asc metadata pull 后运行本技能以确保 canonical metadata 文件最新；审计后仅做关键词跟进时优先用 canonical keyword workflow：asc metadata keywords diff --app "APP_ID" --version "1.2.3" --dir "./metadata"；asc metadata keywords apply --app "APP_ID" --version "1.2.3" --dir "./metadata" --confirm；asc metadata keywords sync --app "APP_ID" --version "1.2.3" --dir "./metadata" --input "./keywords.csv" 导入外部关键词研究；修改后重新运行审计验证修复；字段利用表包含 promotional text 仅为了完整性，但没有检查验证其内容（Apple 不索引）。

适用边界 · 注意事项

• 未通过 asc metadata pull 将元数据拉取到本地，或未把 asc migrate export / asc localizations download 的结果规范化为 canonical ./metadata layout 时不适用。
• Astro MCP 未连接或应用未在 Astro 中跟踪时，关键词缺口分析不可用；离线检查仍可单独运行。
• 未配置 App Store Connect 与 Apple Ads 凭据时，官方 Apple 搜索计划不可用。