aa-segment-performance-comparator

细分受众群体效果对比（Adobe Analytics）

并排比较两个或更多受众群体在关键指标上的表现，了解不同访客群体的行为差异。通过直接比较细分受众群体来确定每项指标的优胜者、落后者和差距，并单独显示细分受众群体规模的上下文面板。

AA 调用预算： AA 的 runReport 每次调用只接受一个 segmentId。 对于 N 个细分受众群体 × M 项指标的比较，需要调用 N×M 次，另加 1 次基线调用，用于细分受众群体规模上下文面板。3 个细分受众群体 × 5 项指标 = 16 次调用。为保证实际运行效率，最多比较 4 个细分受众群体和 6 项指标。开始前务必与用户确认细分受众群体和指标列表。

---

使用的 AA MCP 工具

• findReportSuites — 选择报告包
• setSessionDefaults — 设置会话上下文（reportSuiteId + globalCompanyId）
• findSegments — 查找并选择要比较的细分受众群体
• findMetrics — 解析指标 ID
• runReport — 每个细分受众群体和每项指标调用一次，另加一次未细分调用，用于获取规模上下文

---

阶段 0 — 设置

1. 使用 findReportSuites / setSessionDefaults 确认报告包。

findReportSuites(globalCompanyId: "<gcid>", page: 0, limit: 10)
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")

---

阶段 1 — 选择细分受众群体

询问用户要比较哪些细分受众群体。如果用户未指定，请提示：

“您想比较哪些访客受众群体？例如： 移动端与桌面端、新访客与回访访客、付费搜索与自然搜索，或 您资料库中的特定命名细分受众群体。”

搜索并确认每个细分受众群体：

findSegments(page: 0, limit: 50)
# Filter locally by name. Built-in IDs: "Paid_Search", "Purchasers", "Return_Visits"

注意： findSegments 不接受 searchTerm 参数。请检索所有细分受众群体， 并在本地按名称筛选。内置模板细分受众群体的 ID 较短，例如 "Paid_Search"， 可直接作为 runReport 中的 segmentIds 传入。

如果用户请求的细分受众群体名称不存在，请先提出使用 aa-segment-builder 技能创建， 或根据搜索结果推荐最接近的现有细分受众群体。

每次比较最多 4 个细分受众群体。请提前告知用户此限制。

---

阶段 2 — 选择指标

询问用户要比较哪些指标。建议均衡搭配：

• 流量： metrics/visits
• 互动： metrics/pageviews、metrics/bouncerate、 metrics/pagespervisit
• 转化： metrics/orders、转化率计算指标
• 收入： metrics/revenue

调用 findMetrics 解析每项指标的 ID：

findMetrics(expansions: "componentType,categories", page: 0, limit: 200)
# Filter locally by name. Key IDs: metrics/visits, metrics/revenue, metrics/orders, metrics/bouncerate

最多选择 6 项指标。与用户确认最终列表：

“我将比较这 3 个细分受众群体在 5 项指标上的表现。这需要调用 16 次报告 （3 个细分受众群体 × 5 项指标 + 1 次规模调用）。可以继续吗？”

---

阶段 3 — 选择日期范围

询问或确认分析时间段：

• 过去 7 天（适合快速比较）
• 过去 30 天（推荐默认值）
• 过去 90 天（适合平滑季节性影响）
• 自定义范围

---

阶段 4 — 运行对比报告

4.1 细分受众群体规模（仅作上下文参考）

运行一次未细分的 metrics/visits 调用，获取总人群规模；然后对每个细分受众群体分别调用一次 metrics/visits，计算其占总量的比例。这些规模值用于填充上下文面板——不会用于对比矩阵。

runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# allVisitorVisits = summaryData.totals[0]

runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  segmentIds: "<segmentId>",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# segmentVisits = summaryData.totals[0]; shareOfTotal = segmentVisits / allVisitorVisits × 100

如果 metrics/visits 已经是对比指标，请复用这些结果。

4.2 每个细分受众群体和每项指标

对每种细分受众群体 × 指标组合：

runReport(
  dimensionId: "variables/page",
  metricIds: "<metricId>",          # note: "metricIds" not "metricId"
  segmentIds: "<segmentId>",        # note: "segmentIds" not "segmentId"
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# Total = summaryData.totals[0]

从 summaryData.totals[0] 读取总计（而非 rows[]）。dimensionId 为必填项——使用任何 limit: 1 的维度获取聚合总计。细分受众群体 ID 是 findSegments 返回的原始 id 字段。

跟踪进度：“正在获取第 2/3 个细分受众群体、第 3/5 项指标……”

---

阶段 5 — 构建对比矩阵

矩阵直接比较各细分受众群，不设基准列。

对于每个指标行，计算：

计算值	公式
细分受众群值	runReport 返回的原始值
最优者	此指标值最佳的细分受众群
最差者	此指标值最差的细分受众群
差距	(最大值 − 最小值) / 最大值 × 100
是否显著？	若差距 > 10%，则为 true

对于越低越好的指标（跳出率、单次获客成本）， 反转最优者/最差者的判定逻辑——数值最低的细分受众群 获胜。在报告中明确标注这些指标。

5.1 细分受众群概况摘要

为每个细分受众群计算整体表现概况：

• 获胜次数： 此细分受众群排名第 1 的指标数量
• 落败次数： 此细分受众群排名最后的指标数量
• 最大优势： 此细分受众群相较其他细分受众群领先幅度最大的指标
• 访问量占比： 根据上下文面板计算的总访问量百分比

---

阶段 6 — 生成 HTML 对比报告

直接构建对比报告，并写入 /tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html。

HTML 模板

读取 template.html 并原样使用。不要自行调整 HTML 结构或 CSS——只填入 {ORG_NAME}、 {DATE_RANGE}、{REPORT_SUITE}、{GENERATED_DATE}、{SEGMENT_NAMES_SUMMARY}、 {SEGMENT_NAME}、{COLOR}、{VISITOR_COUNT}、{NUM_SEGMENTS}、{NUM_METRICS}、 {NUM_SIGNIFICANT}、{OVERALL_WINNER}、{METRIC_NAME}、{VALUE}、 {WINNER_SEGMENT}、{SPREAD}、{INSIGHT_TEXT} 这些 {PLACEHOLDER} 占位符，并根据数据项分别重复细分受众群标签、 矩阵行和洞察框。根据阶段 5 的最优者/最差者规则使用 cell-winner / cell-loser 类。

章节标题——不带阶段前缀：HTML 报告中的章节标题不得包含 阶段编号。只使用纯章节名称（例如，“细分受众群对比”，而不是“阶段 2 — 细分受众群对比”， “指标详情”，而不是“阶段 3 — 指标详情”）。

写入 /tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html 并打开：

open /tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html

---

内联摘要（始终提供）

HTML 报告后始终附上文本摘要：

Segment Comparison — [Date Range] | Report Suite: [Name]

Segment Context:  Mobile 48,200 visits (38.7%)  Desktop 72,400 (58.2%)

                  Mobile   Desktop   Winner     Spread
────────────────  ───────  ────────  ─────────  ──────
Visits            48,200   72,400    Desktop    33%
Bounce Rate       61.4%    40.1% ✓  Desktop    35%  ✦
Conversion Rate    1.2%     3.1% ✓  Desktop    61%  ✦
Revenue           $9,400   $31,200   Desktop    70%  ✦

✦ = spread > 10%  ✓ = winner

Key findings:
- Desktop converts 2.6× better (3.1% vs 1.2%). Prioritize mobile checkout.
- Paid Search (not shown) has highest CVR at 4.8% — most efficient channel.

---

注意事项

• 开始前与用户确认细分受众群和指标——调用次数为 N×M，可能迅速增加。
• 对于跳出率及其他“越低越好”的指标，反转最优者判定逻辑——数值最低的细分受众群获胜。在报告中明确标注这些指标（例如，“↓ 越低越好”）。
• 如果某个细分受众群的访问量很少（< 1,000），请说明结果可能不具备统计可靠性。
• 不要在对比矩阵中显示基准差异百分比（细分受众群相较于 All Visitors）。细分受众群是总体人口的一部分，因此计数指标的差异始终为负，且具有误导性。请使用上下文面板了解细分受众群规模。

---

交互示例

“比较移动端和桌面端访客的转化指标。”

1. 确认报告套件。
2. 查找细分受众群：“移动设备”和“桌面端”（或提出创建这些细分受众群）。
3. 确认指标：访问量、跳出率、订单、转化率、收入。
4. 日期范围：最近 30 天。
5. 预览：“2 个细分受众群 × 5 个指标 + 1 次规模统计调用 = 11 份报告。继续吗？”
6. 运行所有报告；宣布进度。
7. 上下文：移动端 = 48.2k 次访问（38.7%），桌面端 = 72.4k 次访问（58.2%）。
8. 矩阵：桌面端在 5 个指标中赢得 3 个。转化率差距为 61%。
9. 生成 HTML 报告并打开。
10. 洞察：“桌面端是你的主要转化引擎。移动端贡献了大量访问量（39%），但转化率为 1.2%，低于桌面端的 3.1%——差距达 61%。 优先优化移动端结账流程，以把握最大的转化提升机会。”