aso-analysis

aso-analysis

请先阅读 using-appfollow（会话、写入规范、错误代码）。

输入

• 范围：应用、整个集合，或用户从一个集合中选择的应用子集（例如“只要我 中的这 3 个应用”）。对于子集：通过 list_collections 解析集合，通过 list_apps 列出其中的应用，然后仅收集所选应用的 ASO 数据——输出 scope.type: "collection_subset"，设置 collection_name，并将 apps 设为所选子集（而非整个集合）。目前尚不支持在一份报告中涵盖多个集合（已延期）。
• **国家/地区：**默认为 1 个主要国家/地区。
• **设备：**App Store → iphone、ipad；Google Play → android。
• 关键词种子（可选）。

默认深度

估算 ≈ A×C×D×[S×P×12 (list_keywords) + S×12 (get_rankings)] + A×C×[K_seed×12 (suggestions) + K_serp×12 (search)] + A(as)×12 (search_ads) + A×12 (aso report, optional)。**默认 = deep：**趋势采样日期最多 S=4（今天 / −7d / −14d / −28d），K_serp=10。单个应用/国家/设备在 deep 模式下，包含 1 页关键词和 10 个种子建议时，约需 360 cr（包括完整趋势采样和 ASO 报告）。仅在用户明确要求时使用 quick/standard（将 S 从 4 降至 2，K_serp 从 10 降至 5）。

趋势部分——需通过验证门槛（smoke gate iv）

趋势功能（按采样日期记录关键词排名和类别排名，S = today, −7d, −14d, −28d）依赖于 list_keywords / get_rankings 在设置 date=<past> 时返回真实的历史快照。此功能受 smoke gate iv 控制。只有 gate iv 通过时才构建趋势部分。如果未通过，则仅提供当前快照（TOP3 / TOP10 / TOP30 / TOP100 / UNRANKED 分档、效果层级、竞争对手差距）；HTML/方法页脚会明确说明，由于历史端点尚不可用，无法提供随时间变化的趋势。绝不将今天的数据重新标记为过去日期的数据。

添加关键词循环（唯一写入路径）

1. 提出不超过 15 个候选关键词；由用户明确选择（绝不自动添加）。
2. edit_keywords 会替换 (apps_id, country, device) 对应的跟踪关键词集合——CSV 中未包含的关键词都会被删除。绝不要只发送新候选词。
3. 对每个 (country, device)：使用 list_keywords({ext_id, country, device}) 读取当前集合，不传 date（即今天的数据），并翻页直至读完。每次预览前都要重新读取，即使之前读过也一样：对同一 (apps_id, country, device) 执行任何 edit_keywords 后，旧读取结果就会过时，并可能导致该次编辑添加的关键词被删除。当前集合 = 响应中的所有跟踪关键词，包括已排名和未排名（no_pos）的关键词——替换时删除未排名关键词也会将其一并删除。任何一页读取失败 → 停止，不写入。
4. CSV = 当前集合 ∪ 已选关键词（去重，不区分大小写）。 edit_keywords_preview({country, device, keywords CSV, apps_id}) — 始终显式传入 apps_id（省略时会默认使用账户中的第一个集合，可能导致写入错误集合）。 如果大小限制拒绝请求（VALIDATION_ERROR 中指出字节数限制）→ 停止并告知用户。绝不要分多次调用来提交集合（每次调用都会替换集合，只有最后一批会保留），也绝不要为了符合限制而删减当前关键词，除非用户明确指出要删除哪些关键词（此时将它们列为已删除项）。
5. 展示此次调用会替换的内容：集合、保留的当前关键词（数量）、新增列表、删除项 = 无。 list_keywords 按 ext_id 读取，不会说明读取的是哪个集合。检查 list_collections + list_apps：如果该应用位于多个集合中，当前集合可能属于其他集合——不要声称删除项 = 无；应说明这一点，并且仅在用户明确同意后写入（否则停止）。获取批准。
6. 执行 edit_keywords 前，按照步骤 3 重新读取 list_keywords（不存在上游版本检查）。如果集合自步骤 3 后发生变化，返回步骤 4（重新构建、预览并获取批准）。然后使用原样参数和令牌调用 edit_keywords。若收到 CONFIRMATION_REQUIRED → 重新预览。
7. edit_keywords 属于 Keywords-Edit 操作（不受 Advanced 限制），因此可用于 Keywords-Edit 计划。位置会在下一个解析周期后显示；可选择为不超过 3 个关键词进行实时 SERP 抽查。已应用的批次 → 结果 status:"applied"。

元数据优化——如实的读取顺序（仅提供建议；目前无法写入元数据）

可靠性从低到高：

1. get_app_metadata — 仅当会话声明支持此功能时使用（先探测）。在确认之前，视为未经验证的透传结果。
2. 通过 aso_search_results 获取自己的 SERP 卡片（标题 / 副标题 / 类型；不含描述）——同样未经验证。
3. 用户粘贴内容——目前唯一可靠的当前元数据来源。 App Store 关键词字段仅开发者可见：始终由用户粘贴，或跳过。

每个字段的输出：当前值 → 建议值 + 新增 / 删除的关键词 + 理由 + 本地化风险 + “在 App Store Connect / Play Console 中应用”。

关键词效果分级（在页脚逐字打印实际定义）

仅根据真实的 list_keywords.effectiveness 字段为每个跟踪的关键词分级——值得投入 （effectiveness > 20）与 跳过（effectiveness <= 20）；每个等级内按效果值降序排序。effectiveness（0–100）是 AppFollow 的关键词效果指数，用于权衡热度与竞争程度；高于 20 的关键词值得放入应用标题／副标题（见下方的支持文章）。

将 popularity 和 difficulty 仅作为背景参考列展示——它们不会影响分级：

• 热度（0–100）：搜索流量评分。该评分采用指数／非线性尺度；AppFollow 不建议使用评分低于约 20 的关键词。
• 难度（0–100）：关键词进入排名前 10 的难度。数值越高 = 难度越大。

没有公开的综合公式。effectiveness、popularity 和 difficulty 均为 AppFollow 计算的数值，直接从 list_keywords 提供——在报告中明确说明这一点。引导读者查看支持文章，了解各项评分的含义： https://support.appfollow.io/hc/en-us/articles/360020831817-Keyword-Tracking。

list_keywords.score（通常为 null，是未公开的次要“AF 评分”）仅作为次要显示值展示，绝不用于分级。每条发现都包含 expected_impact{metric, direction, magnitude, confidence, basis:"effectiveness-v1"}，以及可复现的 evidence[]{source:"mcp:<tool>", args, observed, at}。

可选工具

在 ext_id schema 修复完成前，aso_featured_apps 暂停使用（修复前预计会出现 VALIDATION_ERROR——将该部分标记为 n/a）。get_aso_report_app_store / get_aso_report_gdc_google_play 为可选工具；出现任何错误时，将该部分标记为“n/a”。

输出

生成 aso-analysis-<scope>-<date>.html（填充 references/report-template.html）和 findings.json （appfollow.toolkit.findings/v1，report_type:"aso"；写入前根据 schemas/findings.schema.json 验证）。在 Claude Code 中发布该文件；在 Codex 中写入文件并说明路径。告知用户，他们自己连接的 Agent 可以将这些发现录入其跟踪器。