asc-aso-audit

asc ASO 审计

分为两个阶段执行 ASO 审计：首先基于本地元数据文件完成离线检查，再通过 Astro MCP 进行关键词缺口分析。
在可用时，可将 Apple 自动生成的应用标签（App Tags）作为可被检索/发现能力的信号参考。

前置条件

• 已通过 asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" 将元数据拉取到本地的规范文件目录中。
• 如果元数据来自于 asc migrate export 或 asc localizations download，运行本 Skill 前请先将其规范化整理为标准的 ./metadata 目录结构。
• 如需进行 Astro 缺口分析：应用需已在 Astro MCP 中进行追踪（可选——离线检查无需该条件即可运行）。
• 如需获取 Apple 自动生成的检索标签：当 API 能返回该应用的标签时，运行 asc app-tags list --app "APP_ID" --output json 可正常生效。

开始之前

1. 阅读 references/aso_rules.md，了解各项检查所依据的具体规则。
2. 找到 metadata/version/ 下的最新版本目录（语义化版本号最大的目录），用于处理所有版本层级的字段。
3. 除非用户另有指定，默认的**主语言/主地区（primary locale）**为 en-US。

元数据文件路径

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

第一阶段：离线检查

对本地元数据目录执行以下 5 项检查，全程无需发起网络请求。

1. 关键词浪费检查

对 subtitle 字段（以及可用时的 name）进行分词（Tokenize）。如果某个词条（token）已经出现在 keywords 字段中，则予以标记——因为它已经被 App Store 索引，继续放在 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. 对副标题（+ 应用名）进行分词：
   • 拉丁文/西里尔文： 按空格拆分，去除首尾标点符号，统一转为小写
   • 中日韩文： 按 、 ， , 拆分或逐字遍历——每个单字或词组作为一个 token。按空格拆分对中日韩文无效。
   • 阿拉伯文： 按空格拆分，同时生成去除前缀的变体（剥离 ال 前缀），因为 Apple 可能会对定冠词进行归一化处理。例如，副标题中的 "القرآن" 应当同时在关键词中触发对 "القرآن" 和 "قرآن" 的警告。
4. 将 keywords 按逗号拆分，去除首尾空格，统一转为小写
5. 输出交集结果（包含剥离前缀后的模糊匹配项）

可选：App 标签匹配度

App 标签是 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 自动生成的标签。

2. 字段利用率不足

标记使用字符数低于建议最小值的字段：

字段	建议最小值	上限	原理/理由
Keywords	90 字符	100	利用率 90%+ 可最大化索引效果
Subtitle	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. 对每个关键词，检查其是否作为子字符串出现在 description 中（不区分大小写）
3. 考虑屈折变体：阿拉伯语词根匹配、动词变位（例如 "memorizar" ≈ "memorices"）以及格变化（例如俄语 "сура" ≈ "суры"）
4. 按语言报告缺失的关键词——建议将其自然融合到已有句子中
5. 无需标记：非拉丁语描述中出现的拉丁字母关键词（例如西里尔文文本中的 "quran"）——这些词瞄准的是不同的搜索路径

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

如果 Astro MCP 可用且应用已被追踪，请运行关键词缺口分析。请按商店/地区分别运行分析，而不要仅针对美国区商店——关键词的热度在不同市场差异巨大。

操作步骤

1. 获取当前关键词：使用应用 ID 调用 get_app_keywords，获取已追踪的关键词及其当前排名。
2. 确保多商店追踪：针对有对应 App Store 区域的每个语言/地区（例如 ar-SA → 沙特阿拉伯，fr-FR → 法国，tr → 土耳其），使用 add_keywords 添加在对应商店的关键词追踪。如果不执行此操作，search_rankings 在非美区商店会返回空值。
3. 提取竞品关键词：传入 3-5 个头部竞品的应用 ID 调用 extract_competitors_keywords 来寻找关键词缺口。这是 Astro 中价值最高的功能工具——它能揭示竞品有排名而你尚未覆盖的关键词。只要条件允许，应按不同商店分别运行。
4. 获取推荐建议：传入应用 ID 调用 get_keyword_suggestions，获取基于品类分析给出的补充推荐词。
5. 检查当前排名：调用 search_rankings 查看应用在各个商店中针对已追踪关键词的具体排名。
6. 与元数据对比求差：将推荐词和竞品关键词与本地元数据中 subtitle、name（如有）和 keywords 字段中的 token 进行对比。
7. 输出缺口列表：按热度得分（Popularity score）从高到低汇报所有关键词缺口，并注明来源（竞品分析 vs 推荐建议）。

跨字段组合策略

在推荐新增关键词时，需考虑单个词汇在不同被索引字段（title + subtitle + keywords）之间的组合效果。例如：

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

在建议中高亮标注高价值的组合词策略。

跳过条件

• Astro MCP 未连接 → 跳过并提示："Connect Astro MCP for keyword gap analysis"
• 应用未在 Astro 中追踪 → 跳过并提示："Add app to Astro with mcp__astro__add_app for gap analysis"
• 某语言/地区对应的商店未建立追踪 → 在查询前先使用 add_keywords 添加追踪

输出格式

将结果整理为一份统一的审计报告呈现。报告仅覆盖最新的版本目录。

### ASO 审计报告

**应用名称：** [name] | **主语言/地区：** [locale]
**元数据来源：** [含版本号的路径]

#### 字段利用率

| 字段 | 内容 | 字符数 | 上限 | 利用率 |
|-------|-------|--------|-------|-------|
| Name | ... | X | 30 | X% |
| Subtitle | ... | X | 30 | X% |
| Keywords | ... | X | 100 | X% |
| Promotional Text | ... | X | 170 | X% |
| Description | (前 50 个字符)... | X | 4000 | X% |

#### 离线检查

| # | 检查项 | 严重程度 | 关联字段 | 语言/地区 | 详细说明 |
|---|-------|----------|-------|--------|--------|
| 1 | 关键词浪费 | ⚠️ | keywords | en-US | "quran" 在 subtitle 中重复出现 |

**总结：** 共覆盖 Z 个语言/地区，发现 X 个错误，Y 个警告

#### 关键词缺口分析 (Astro MCP)

| 关键词 | 热度得分 | 是否已存在于元数据？ | 建议操作 |
|---------|-----------|--------------|-----------------|
| quran recitation | 72 | ❌ | 添加至 keywords |

#### 优化建议

1. [最高优先级操作 — 优先修复错误]
2. [次高优先级 — 清理关键词浪费]
3. [字段利用率提升建议]
4. [关键词缺口覆盖机会]

注意事项

• 离线检查完全不需要网络连接——仅读取本地文件。
• Astro 缺口分析属于增益功能——即使没有它，本审计功能依然十分有用。
• 请在执行 asc metadata pull 后运行本 Skill，以确保规范元数据文件是最新状态。
• 审计完成后，若仅需跟进调整关键词，建议优先使用规范的关键词工作流命令：
  • 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 不会将其纳入索引）。