asc-aso-audit

asc ASO 审核

分两个阶段进行 ASO 审核：先对本地元数据文件进行离线检查，再通过 Astro MCP 分析关键词差距。 如果可用，请将 Apple 生成的应用标签作为一项可发现性信号纳入分析。

前提条件

• 已通过 asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" 将元数据拉取到本地规范文件中。
• 如果元数据来自 asc migrate export 或 asc localizations download，请先将其整理为规范的 ./metadata 布局，再运行此技能。
• 对于 Astro 差距分析：应用已在 Astro MCP 中跟踪（可选——即使没有 Astro MCP，也会运行离线检查）。
• 对于 Apple 生成的可发现性标签：当 API 返回该应用的标签时，asc app-tags list --app "APP_ID" --output json 可正常运行。

开始之前

1. 阅读 references/aso_rules.md，了解每项检查所执行的规则。
2. 找出 metadata/version/ 下最新的版本目录（语义版本号最高的目录）。所有版本级字段均使用此目录。
3. 除非用户另有说明，主要语言区域为 en-US。

元数据文件路径

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

阶段 1：离线检查

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

1. 关键词浪费

对 subtitle 字段（如果有 name，也包括它）进行分词。将同时出现在 keywords 字段中的词标记出来——这些词已经被编入索引，会浪费关键词额度。

Severity: ⚠️ Warning
Example:  "quran" appears in subtitle AND keywords — remove from keywords to free 6 characters

检查方法：

1. 读取 metadata/app-info/{locale}.json 中的 subtitle（以及存在时的 name）
2. 读取 metadata/version/{latest-version}/{locale}.json 中的 keywords
3. 对副标题（以及名称）进行分词：
   • **拉丁/西里尔文字：**按空白字符拆分，去除首尾标点，并转换为小写
   • **中文/日文/韩文：**按 、、，、, 拆分，或逐字遍历——每个字符或字符组均视为一个词元。对中日韩文本，按空白字符分词不可行。
   • **阿拉伯语：**按空白字符拆分，并生成去除前缀的变体（删除 ال 前缀），因为 Apple 可能会对定冠词进行规范化。例如，如果副标题中包含“القرآن”，则关键词中的“القرآن”和“قرآن”都应标记出来。
4. 按逗号拆分关键词，去除空白字符，并转换为小写
5. 报告交集（包括通过去除前缀发现的模糊匹配）

可选：应用标签对齐情况

应用标签是 Apple 生成的标签，可显示在搜索结果和产品页面中。它们不是可编辑的 ASO 元数据，但可用于判断 Apple 的分类是否符合预期定位。

asc app-tags list --app "APP_ID" --output json
asc app-tags view --app "APP_ID" --id "TAG_ID" --output json

仅将标签作为背景信息：

• 如果可见标签与副标题/关键词策略相符，请说明这一对齐情况。
• 如果标签指向了非预期的类别或用途，建议调整元数据/类别，以便改善未来的分类。
• 不要承诺更改元数据会立即改变 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

• 使用 asc auth 验证 App Store Connect 身份，并单独使用 asc ads auth login 验证 Apple Ads 身份；两组凭据相互独立。
• 将生成的 CSV 和 JSON 文件视为供审核使用的文件。此命令不会应用元数据、精确关键词或否定关键词，报告中会显示 Apple Ads 数据源的部分失败情况。
• 区分 Apple 的热度、应用专属付费覆盖范围、付费搜索结果和元数据覆盖情况。不要根据此方案推断自然排名或关键词难度。

2. 利用不足的字段

标记使用量低于建议最低值的字段：

字段	最低值	上限	原因
关键词	90 个字符	100	使用率达到 90% 以上可最大化索引效果
副标题	20 个字符	30	建议使用率达到 65% 以上

Severity: ⚠️ Warning
Example:  keywords is 62/100 characters (62%) — 38 characters of indexing opportunity unused

3. 缺失字段

标记为空或缺失的必填字段：subtitle、keywords、description、whatsNew。

注意：导出内容中可能没有 name——仅当 app-info JSON 中明确包含一个值为空的 name 键时才标记。

Severity: ❌ Error
Example:  subtitle is empty for locale en-US

4. 不正确的关键词分隔符

检查 keywords 字段是否存在格式问题：

• 逗号后有空格（quran, recitation）
• 使用分号而不是逗号（quran;recitation）
• 使用竖线而不是逗号（quran|recitation）

Severity: ❌ Error
Example:  keywords contain spaces after commas — wastes 3 characters

5. 跨地区关键词缺口

比较所有可用地区的 keywords 字段。标记关键词与主要地区（默认情况下为 en-US）完全相同的地区——这通常表示关键词尚未本地化。

Severity: ⚠️ Warning
Example:  ar keywords identical to en-US — likely not localized for Arabic market

检查方法：

1. 加载所有地区的关键词
2. 将每个非主要地区的关键词与主要地区进行比较
3. 标记完全匹配的项（忽略大小写）

6. 描述中的关键词覆盖率

检查关键词是否自然地出现在 description 字段中。虽然 Apple 不会将描述编入搜索索引，但用户如果发现描述中提到了自己的搜索词，就更有可能下载应用——这能提高转化率，进而间接提升排名。

Severity: 💡 Info
Example:  3 of 16 keywords not found in description: namaz, tarteel, adhan

检查方法：

1. 加载每个地区的 keywords 和 description
2. 检查每个关键词是否作为子字符串出现在描述中（忽略大小写）
3. 考虑词形变化：阿拉伯语词根匹配、动词变位（例如，“memorizar” ≈ “memorices”）以及格变化（例如，俄语“сура” ≈ “суры”）
4. 按地区报告缺失的关键词——建议将它们自然地融入现有句子
5. 不要标记：非拉丁文字描述中的拉丁字母关键词（例如，西里尔文字文本中的“quran”）——它们针对不同的搜索路径

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

如果 Astro MCP 可用且该应用已被跟踪，则运行关键词缺口分析。应按商店/地区分别运行，而不只是针对美国商店——关键词热度在不同市场间差异很大。

步骤

1. 获取当前关键词：调用 get_app_keywords 并提供应用 ID，以检索已跟踪的关键词及其当前排名。

2. 检查多商店跟踪情况：查询各地区 App Store 所属区域的现有跟踪情况。将未跟踪的商店报告为不可用，然后继续审核。仅在用户另行授权设置跟踪时使用 add_keywords；未跟踪商店没有排名并不能证明表现不佳。

3. 提取竞争对手关键词：调用 extract_competitors_keywords 并提供 3–5 个头部竞争对手的应用 ID，以找出关键词缺口。这是价值最高的 Astro 工具——它可以揭示竞争对手排名靠前而你没有的关键词。尽可能按商店分别运行。

4. 获取建议：调用 get_keyword_suggestions 并提供应用 ID，根据类别分析获取更多建议。

5. 检查当前排名：调用 search_rankings，查看应用在各商店中已跟踪关键词的当前排名。

6. 与元数据进行比对：将建议的关键词和竞争对手关键词与本地元数据中 subtitle、name（如有）和 keywords 字段包含的词项进行比较。

7. 列出缺口：按热度评分从高到低报告所有缺口。注明来源（竞争对手分析或建议）。

跨字段组合策略

建议添加关键词时，考虑不同已索引字段（标题 + 副标题 + 关键词）中的词语如何组合。例如：

• 当 keywords 中添加 “namaz” 且已有 “vakti” 时，即可匹配搜索词 “namaz vakti”（热度 66）
• 当副标题中有 “Quran” 且 keywords 中添加 “holy” 时，即可匹配 “holy quran”（热度 58）

在建议中标记高价值组合。

跳过条件

• Astro MCP 未连接 → 跳过并注明："Connect Astro MCP for keyword gap analysis"
• App 未在 Astro 中跟踪 → 跳过并注明："Add app to Astro with mcp__astro__add_app for gap analysis"
• 某个地区的商店未被跟踪 → 报告此差距并跳过其排名；跟踪设置需要单独授权

输出格式

将结果作为一份审计报告呈现。报告仅涵盖最新的版本目录。

### ASO Audit Report

**App:** [name] | **Primary Locale:** [locale]
**Metadata source:** [path including version number]

#### Field Utilization

| Field | Value | Length | Limit | Usage |
|-------|-------|--------|-------|-------|
| Name | ... | X | 30 | X% |
| Subtitle | ... | X | 30 | X% |
| Keywords | ... | X | 100 | X% |
| Promotional Text | ... | X | 170 | X% |
| Description | (first 50 chars)... | X | 4000 | X% |

#### Offline Checks

| # | Check | Severity | Field | Locale | Detail |
|---|-------|----------|-------|--------|--------|
| 1 | Keyword waste | ⚠️ | keywords | en-US | "quran" duplicated in subtitle |

**Summary:** X errors, Y warnings across Z locales

#### Keyword Gap Analysis (Astro MCP)

| Keyword | Popularity | In Metadata? | Suggested Action |
|---------|-----------|--------------|-----------------|
| quran recitation | 72 | ❌ | Add to keywords |

#### Recommendations

1. [Highest priority action — errors first]
2. [Next priority — keyword waste]
3. [Utilization improvements]
4. [Keyword gap opportunities]

备注

• 离线检查无需网络连接即可运行——只读取本地文件。
• 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"
• 完成更改后，重新运行审计以验证修复效果。
• Field Utilization 表格为确保信息完整而包含推广文案，但没有检查会验证其内容（Apple 不会为其编制索引）。