asc-aso-audit

用途

asc-aso-audit 用于对 App Store 元数据执行 ASO 审计，帮助发现关键词浪费、字段利用率不足、缺失字段、格式错误以及跨语言本地化问题，并在可用时通过 Astro MCP 进行关键词缺口分析。

前置条件

• 已通过 asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" 将元数据拉取到本地规范化文件。
• 若元数据来自 asc migrate export 或 asc localizations download，需先规范化为 ./metadata 布局。
• Astro 缺口分析为可选：应用需在 Astro MCP 中被跟踪，离线检查无需它即可运行。
• Apple 生成的可发现性标签可通过 asc app-tags list --app "APP_ID" --output json 获取（当 API 返回标签时）。

开始之前

• 阅读 references/aso_rules.md 了解每项检查执行的规则。
• 识别 metadata/version/ 下最新版本目录（语义版本号最高者），用于所有版本级字段。
• 主语言默认为 en-US，除非用户另行指定。

元数据文件路径

• App-info 字段（subtitle）：metadata/app-info/{locale}.json
• 版本字段（keywords、description、whatsNew）：metadata/version/{latest-version}/{locale}.json
• App 名称：可能不在导出元数据中。若 app-info JSON 中缺少名称，可通过 asc apps info list 获取或询问用户，不要将其标记为缺失字段错误。

第一阶段：离线检查

对本地元数据目录运行以下检查，无需网络调用。

1. 关键词浪费

对 subtitle 字段（以及可用的 name）进行分词，标记同时出现在 keywords 字段中的 token——它已被索引，浪费关键词预算。严重级别：⚠️ 警告。

检查方法：读取 subtitle（和 name）与 keywords；分词规则：拉丁/西里尔字母按空白拆分、去首尾标点、转小写；中日韩按 、 ， , 拆分或逐字符迭代；阿拉伯语按空白拆分并生成去 ال 前缀的变体。关键词按逗号拆分、去空白、转小写，报告交集（含前缀剥离的模糊匹配）。

可选：App 标签对齐

App 标签是 Apple 生成的标签，不可编辑，但可作为 Apple 分类是否匹配预期定位的证据。使用标签仅作上下文参考，不要承诺更改元数据会立即改变 Apple 生成的标签。

可选：官方 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

App Store Connect 用 asc auth 认证，Apple Ads 用 asc ads auth login 单独认证，两套凭据独立。生成的 CSV 和 JSON 为审查产物，命令不会应用元数据、精确关键词或否定关键词。不要从中推断自然排名或关键词难度。

2. 字段利用率不足

标记使用量低于推荐最小值的字段：

字段	最小值	上限	理由
Keywords	90 字符	100	90%+ 使用率最大化索引
Subtitle	20 字符	30	推荐 65%+ 使用率

严重级别：⚠️ 警告。

3. 缺失字段

标记空或缺失的必填字段：subtitle、keywords、description、whatsNew。注意：name 可能不在导出中，仅当 app-info JSON 明确包含 name 键且值为空时才标记。严重级别：❌ 错误。

4. 错误的关键词分隔符

检查 keywords 字段的格式问题：逗号后有空格、用分号代替逗号、用竖线代替逗号。严重级别：❌ 错误。

5. 跨语言关键词缺口

比较所有可用语言的 keywords 字段，标记与主语言（默认 en-US）完全相同者——通常意味着未本地化。严重级别：⚠️ 警告。

6. 描述关键词覆盖

检查关键词是否自然出现在 description 中。Apple 不索引描述用于搜索，但用户看到搜索词反映在描述中更可能下载，从而提升转化率间接提升排名。严重级别：💡 信息。需考虑词形变化（阿拉伯语词根、动词变位、格变化）。不要标记非拉丁描述中的拉丁关键词。

第二阶段：Astro MCP 关键词缺口分析

若 Astro MCP 可用且应用被跟踪，按商店/语言运行关键词缺口分析。步骤：

1. 获取当前关键词：调用 get_app_keywords 获取跟踪关键词及当前排名。
2. 检查多商店跟踪：查询各语言 App Store 区域的现有跟踪。未跟踪的商店报告为不可用并继续。仅在用户单独授权时使用 add_keywords。
3. 提取竞品关键词：调用 extract_competitors_keywords，传入 3-5 个顶级竞品应用 ID，发现关键词缺口。
4. 获取建议：调用 get_keyword_suggestions。
5. 检查当前排名：调用 search_rankings。
6. 与元数据对比：将建议和竞品关键词与本地元数据中的 subtitle、name、keywords 字段 token 对比。
7. 呈现缺口：按流行度分数从高到低报告所有缺口，包含来源。

跨字段组合策略

推荐关键词添加时，考虑单词在索引字段（标题+副标题+关键词）间的组合。例如：当 subtitle 已有 "vakti" 时，向 keywords 添加 "namaz" 可匹配搜索 "namaz vakti"；当 subtitle 有 "Quran" 时，添加 "holy" 可匹配 "holy quran"。标记高价值组合。

跳过条件

• Astro MCP 未连接 → 跳过并注明："Connect Astro MCP for keyword gap analysis"
• 应用未在 Astro 中跟踪 → 跳过并注明："Add app to Astro with mcp__astro__add_app for gap analysis"
• 某语言商店未跟踪 → 报告缺口并跳过其排名；跟踪设置需单独授权

输出格式

以单一审计报告呈现结果，仅覆盖最新版本目录。报告包含：字段利用率表、离线检查表、关键词缺口分析表（Astro MCP）以及按优先级排列的建议（错误优先、其次关键词浪费、利用率改进、关键词缺口机会）。

备注

• 离线检查无需网络，仅读取本地文件。
• Astro 缺口分析为附加项，即使没有它审计也有用。
• 在 asc metadata pull 后运行此技能以确保规范化元数据文件最新。
• 审计后仅需关键词跟进时，优先使用规范关键词工作流：

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 不索引它）。