feedback-analysis

feedback-analysis

请先阅读 using-appfollow。此技能为只读——绝不会调用写入配对工具。

输入

• scope： 一个应用（ext_id+store）、整个集合，或用户从一个集合中选定的部分应用（例如“只要我中的这 3 个应用”）。目前不支持在一份报告中涵盖多个集合（暂缓实现）。
• window： 默认最近 30 天；对比 = 前一个等长周期。
• country / lang（可选）。
• depth： quick | standard | deep = 每次拉取时 get_reviews 的页数上限为 2 / 5 / 10。拉取整个集合时只应用一次上限；拉取单个应用或部分应用时则逐个应用应用上限。默认 deep。 仅在用户明确要求时使用 quick/standard。
• 测试反馈（可选，仅限 Google Play）：测试人员在封闭式或开放式测试渠道留下的反馈——这是单独的一组评论，默认关闭；仅在用户明确要求时才拉取（Gather 步骤 D）。

两个层级，运行时探测

读取已公布的工具列表；选择相应方案（工具包与 MCP 发布周期相互独立）：

• 层级 A（始终可用）： whoami、list_collections、list_apps、get_reviews、get_ratings_history。
• 层级 B（探测结果显示缺失时则降级）： reviews_semantic、get_reviews_summary、get_reviews_ai_summary。
• 可降级的应用级工具（不属于由探测决定的层级）： get_gp_console_ratings——降级规则见 Gather 步骤 B。

Gather

0. 会话（using-appfollow）。 A. 确定范围。 即使只有一个 ext_id，也必须查找集合——get_reviews、 get_reviews_summary 和 get_gp_console_ratings 都需要集合的 apps_id（list_collections 中的 collectionId），而 get_reviews_ai_summary 需要集合的 collection_name（collectionCode）+ store。list_apps（apps_id）会提供每个应用的 extId（即 ext_id 参数），并以长名称返回 store——在传入任何 store 参数前，先将其映射为短代码（using-appfollow → references/tool-map.md）。整个集合范围仅包含集合自身的应用（list_apps 中的 isCompetitor: false）：仅对这些应用运行以下所有逐应用调用。若范围为子集：通过 list_collections 确定集合，通过 list_apps 列出其应用，然后仅收集所选子集的数据——输出 scope.type: "collection_subset"，设置 collection_name，并令 apps = 所选子集（而非整个集合）。 B. 先获取低成本汇总数据。 每个应用调用一次 get_ratings_history，覆盖两个时间窗口 （ext_id + 短 store、period=daily、type=total、一个 country——用户指定的国家，否则用 all）：一次调用即可返回完整序列，无需分页；在客户端拆分。对于当前窗口，在步骤 C 的范围上 （apps_id，若步骤 C 按应用调用，则另加 ext_id）调用一次 get_reviews_summary（Tier B）：其 total.value、previous 和 diff 涵盖当前周期及其前一个等长周期，且 total.value 用于确定 步骤 C 的规模——评论分页不包含总数。get_gp_console_ratings（apps_id + 每个 Google Play 应用的 ext_id + 报告窗口的 from + to，fields: ["ratings"]）可降级处理——应用可能未连接 Google Play Console，或服务端可能不提供此功能。出现任何错误（FEATURE_DISABLED、VALIDATION_ERROR、 UNKNOWN_TOOL 或其他错误）或响应为空时，省略 GP Console 评分信号，在报告中注明数据缺口，然后 继续；这不会影响 App Store 评分历史路径。绝不可因该调用导致整个分析失败。 C. 叙述分析。 对每个应用，使用报告窗口的 from + to、应用的 ext_id、集合的 collection_name（collectionCode）和短 store 调用 get_reviews_ai_summary（出现任何错误时跳过： 若没有 AI 摘要功能，则会返回 FEATURE_DISABLED 或 ACCESS_DENIED）。 reviews_semantic——客户端分类是首选的备用方案。然后获取 get_reviews 原始分页：整个集合只拉取 一次（apps_id，不传 ext_id——仅包含集合自身的应用；不包含集合中的竞品应用）；单个应用或 子集则每个应用拉取一次（apps_id + ext_id）。将每个 nextCursor 作为 cursor 传回进行分页 （参数保持不变），最多达到深度上限；若 nextCursor 为 null 或不存在，则提前停止；根据步骤 B 的总数 记录覆盖率 %（references/method.md）。 D. 测试反馈（可选启用，仅限 Google Play）。 这是一个独立的评论集：对于 Google Play 应用， get_reviews 默认只返回公开评论；设置 testing_feedback: true 后则只返回测试反馈（typeList: ["beta"]）——绝不可在一次调用中同时获取，也绝不可合并到公开评论章节中。仅在用户明确要求获取测试者 / Beta / 测试轨道反馈时运行：对每个 Google Play 应用单独调用一次 get_reviews，每次调用都传入集合的 apps_id、该应用的 ext_id 和 testing_feedback: true，并限定在报告窗口内，分页方式和深度上限与步骤 C 相同。其他商店会忽略此标志，始终返回公开评论：跳过这些商店，绝不可发送工作区范围的 true 调用，并且 仅保留 typeList 包含 beta 的评论。如果 get_reviews 的参数列表中没有 testing_feedback，则跳过此 步并注明——不支持该标志的服务端会返回公开评论。结果为空不算错误——可能是该窗口内没有测试反馈，也可能 是 AppFollow 未连接 Google Play Console，且工具不会说明具体原因：如实报告为空，不要重试。如果用户只要求 测试者反馈，则运行步骤 0、A 和 D，跳过 B 和 C，并且只输出测试章节。单独分析此类反馈，不要与公开评论集 混合（references/method.md）。

分析

遵循 references/method.md：KPI 及其变化量；日均值和 7 天滚动趋势；带明确阈值的异常启发式规则；挖掘 Bug 和功能反馈（优先采用语义分析，默认回退到客户端分类）。 应用覆盖率门控：将覆盖率低于 60% 下限的文本派生发现降级为“仅供参考”。基于评分的发现不受覆盖率门控。按各应用的评分数（其最新 get_ratings_history 行中的 starsTotal）设置分组汇总权重，并将跨应用集群合并到 affected_apps。

错误处理规则（using-appfollow）

INSUFFICIENT_CREDITS → 停止，输出部分报告并附上覆盖率说明。RATE_LIMITED → 退避一次后继续。非关键调用遇到 NETWORK_ERROR/UPSTREAM_ERROR → 跳过该部分，继续处理。缺少 Tier-B 工具 → 使用已记录的回退方案。切勿因单个工具错误而导致整份报告失败。

输出

写入 ./appfollow-reports/<report_id>/：

1. findings.json — appfollow.toolkit.findings/v1，report_type:"feedback"。写入前，根据 schemas/findings.schema.json 验证。每条发现包含：稳定的 id、type、title、description、severity、priority_hint、affected_apps、metrics、evidence（3–5 条引用，每条 ≤200 个字符，通过评论 ID 标识——不存在永久链接方案）、suggested_labels、稳定的 dedup_key（确保重新运行时更新而非重复），status:"proposed"。
2. report.html — 填充 references/report-template.html；使用内嵌 SVG 图表；不发出外部请求。
3. report.md — 相同内容的 Markdown 版本。

使用 Claude Code 时，也发布 HTML 产物；使用 Codex 时，写入这些文件并注明其路径。

发现交接

告知用户，他们自己连接的跟踪器 Agent 可以将 findings.json 提交到其跟踪器——该工具包不会与跟踪器通信。