cja-segment-performance-comparator

细分表现对比（客户旅程分析）

通过并排矩阵，对比 2–5 个受众细分在一组关键指标上的表现。输出不仅会告诉用户每个细分各自的情况，还会指出每项指标上哪个细分表现最好或最差，以及哪些差异大到值得采取行动。

这项技能用数据回答“我们应该重点关注哪个受众？”这一问题。细分对比会影响产品决策、个性化策略和预算分配，因此清晰且可操作比穷尽所有数据更重要。

---

使用的 CJA MCP 工具

• findSegments — 按名称或关键词搜索细分
• describeSegment — 在使用候选细分前了解其逻辑
• findMetrics — 获取基础指标 ID
• findCalculatedMetrics — 在对比中纳入自定义 KPI
• listComponentUsage — 将使用最多的指标确定为默认对比集
• runReport（使用 segmentIds 或 adhocSegments）— 获取各细分的指标值

---

阶段 0 — 设置

1. 调用 findDataViews，列出可用的数据视图。
2. 如果用户未指定数据视图，请展示列表并询问要使用哪个。
3. 使用选定的 ID 调用 setDefaultSessionDataViewId。
4. 如果用户尚未指定要对比的细分，请询问用户。确认要对比哪些指标。

---

阶段 1 — 确定要对比的细分

1.1 根据用户描述

如果用户指定了具体细分，解析这些细分：

findSegments(search: "<segment name>")

对于每个匹配项，调用 describeSegment，确认它是否正确：

describeSegment(segmentId: "<id>")

如果存在歧义，向用户展示细分定义摘要：

"我找到了两个与“移动用户”匹配的细分：所有设备上的移动访客 和 移动应用用户。你想对比哪一个？"

1.2 根据自然语言描述

如果用户说“对比移动端用户和桌面端用户”，但没有匹配的细分，请提议直接为此次对比创建临时临时细分：

"我没有找到预先构建的移动端和桌面端细分。我可以使用设备类型为此次对比创建临时的即席细分。要继续创建即席细分，还是先创建永久细分？"

在 runReport 中使用 adhocSegments 构建即席细分——对比本身无需保存。

1.3 细分数量上限

单次对比最多支持 5 个细分。超过 5 个会导致矩阵过宽，难以有效阅读。如果用户要求更多，请说：

"为便于阅读，我会将范围限制在最相关的 5 个细分。你希望我按使用次数优先排序，还是沿用你列表中的顺序？"

---

阶段 2 — 确定要对比的指标

2.1 根据用户指定

通过 findMetrics 和 findCalculatedMetrics 解析指定的指标。

2.2 默认指标发现

如果用户未指定指标，请按使用次数获取排名靠前的指标。listComponentUsage 工具不支持 limit 参数——它会返回所有组件，并按使用次数排序；从结果中选取排名前 6–8 个：

listComponentUsage(componentType: "metric")
listComponentUsage(componentType: "calculatedMetric")

如果计算指标和原始基础指标衡量的是同一内容，优先选择计算指标——计算指标体现了有意定义的 KPI。

2.3 为对比选择指标

适合用于对比的指标应当对所有细分都有意义。例如，“收入”对移动端和桌面端用户都很有意义；“应用安装量”则只对移动端有意义。移除对某个细分而言必然为零的指标。

如果不确定，请询问：“要使用你们的标准 KPI 集，还是聚焦于转化率、收入和互动等特定指标？”

---

第 3 阶段 — 运行比较

对于每个细分，应用该细分并包含所有比较指标，运行一次 runReport。请注意，runReport 接受以逗号分隔的字符串 metricIds、startDate/endDate（而非 dateRange），以及 dimensionIds（即使是仅包含汇总数据的报告也必填——请使用低基数维度，例如 variables/daterangeday 或 variables/web.webPageDetails.name）。 所有指标的汇总总计都在 summaryData.filteredTotals 中：

runReport(
  dimensionIds: "variables/web.webPageDetails.name",
  metricIds: "metrics/visits,metrics/revenue_1,metrics/orders_1_1",
  startDate: "<period start>T00:00:00",
  endDate: "<period end>T23:59:59",
  page: 0,
  limit: 1,
  segmentIds: "<segment id>"
)

对于临时细分，请使用完整的 CJA 细分定义对象：

runReport(
  dimensionIds: "variables/web.webPageDetails.name",
  metricIds: "metrics/visits,metrics/orders_1_1",
  startDate: "<period start>T00:00:00",
  endDate: "<period end>T23:59:59",
  page: 0,
  limit: 1,
  adhocSegments: [{
    "func": "segment",
    "version": [1, 0, 0],
    "container": {
      "func": "container",
      "context": "visitors",
      "pred": {
        "func": "streq",
        "val": { "func": "attr", "name": "variables/device_type" },
        "str": "Mobile Phone"
      }
    }
  }]
)

从 summaryData.filteredTotals[i] 读取指标总计，其中 i 是 metricIds 字符串中指标的从 0 开始的索引。

每个细分运行一份报告。将所有结果收集到一个矩阵中：

• 行 = 指标
• 列 = 细分

---

第 4 阶段 — 构建比较矩阵

对于每个单元格（指标 × 细分）：

• value[metric][segment] = runReport 返回的原始指标值

对于每个指标行：

• winner = 值最高的细分（对于“越低越好”的指标，则为值最低的细分）
• loser = 值最低的细分（对于反向指标，则为值最高的细分）
• range = (max − min) / max × 100 — 各细分之间的差异幅度，以百分比表示
• significant = 当 range > 10% 时为 true（差异显著，值得采取行动）

---

第 5 阶段 — 生成 HTML 比较报告

在内联方式生成报告，并写入 /tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html。

HTML 模板

读取 template.html 并原样使用。不要自行调整 HTML 结构或 CSS——只填充 {PLACEHOLDER} 标记（{ORG_NAME}、 {DATE_RANGE}、{DATA_VIEW}、{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}），并为每个数据项重复生成细分标签、 矩阵行和洞察框。根据第 4 阶段的胜者／败者规则使用 cell-winner / cell-loser 类。

---

第 6 阶段 — 叙述性洞察

构建矩阵后，为洞察部分生成 3–5 条要点：

1. 总体胜者：“回访访客在 7 项指标中的 5 项上优于新访客，差距最大的是每次会话收入（+82%）。”
2. 最显著差异：“差距最大的是转化率：移动端的转化率为 1.2%，桌面端为 3.8%——差距达 68%，值得优先关注。”
3. 出乎意料的相近表现：“新访客与回访访客的跳出率几乎相同（42% 和 44%），说明落地页质量一致。”
4. 可采取行动的信号：“付费搜索访客的每次会话收入比直接访问访客高 2.3 倍——可以考虑将预算转向付费搜索。”
5. 异常：“某个细分的所有指标值都接近零——请确认细分定义正确，并与当前数据视图匹配。”

洞察应使用通俗英语，而非指标 ID。请指出具体细分和指标值。

---

工作流摘要

1. 确定 2–5 个细分（按名称或临时定义）。
2. 确定 5–8 项比较指标（由用户提供或依据使用频率选取）。
3. 每个细分运行一次包含所有指标的 runReport；收集结果。
4. 构建比较矩阵：行 = 指标，列 = 细分。
5. 标记每行的胜者／败者；计算差异幅度；标记显著差异。
6. 生成包含矩阵和洞察要点的 HTML 报告。
7. 写入 /tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html。
8. 使用 open /tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html 打开。
9. 提供内联摘要：总体胜出的细分、差距最大的指标，以及一条可执行的建议。

---

重要注意事项

• 只进行只读分析。 切勿删除或修改细分或计算指标。
• 运行前务必确认细分。 对含义不明确的细分名称（例如，“Mobile” 可能对应多个细分），应显示匹配的细分 ID 和定义，让用户确认。
• 所有细分使用相同的日期范围。 比较不同时间段会产生误导。
• 注明细分之间的重叠情况。 如果两个细分的受众有大量重叠，应注明这一点——“差异”可能被夸大。
• 限制比较的细分数量。 在单份报告中比较超过 5–6 个细分会让输出难以阅读；请用户优先选择。
• 区分统计显著性与实际意义。 0.1% 的差异通常没有实际参考价值——除非用户另有说明，否则应重点关注 5% 以上的差异。

---

示例交互

“比较我们上季度移动端与桌面端细分的表现。”

1. 设置： 确认数据视图。调用 findDataViews，由用户选择。调用 setDefaultSessionDataViewId。
2. 解析细分： 调用 findSegments 查找 “Mobile Users” 和 “Desktop Users” 细分。显示匹配的名称和 ID 以供确认。用户批准。
3. 指标： 询问“要比较哪些指标？”用户回答：“会话数、转化率、收入和平均订单价值。”
4. 分析： 针对 Q1 2026 应用这两个细分并运行 runReport。将结果并列表格展示。
5. 发现： 移动端：占会话数的 45%，CVR 为 2.1%，RPV 为 $0.84。桌面端：占会话数的 55%，CVR 为 4.8%，RPV 为 $2.10。桌面端的转化效果高出 2.3 倍。提供一张对比表和 3 条建议的后续步骤。