aa-kpi-pulse

KPI Pulse（Adobe Analytics）

生成一份精简易读的 KPI 摘要，展示关键指标在所选时间段内的变化、推动变化的项目，以及值得关注的亮点。将所有 KPI 批量放入两次 runReport 调用中（当前时间段 + 对比时间段），并将结果整理成 HTML 绩效卡片组。

---

使用的 AA MCP 工具

• findReportSuites — 选择工作报表包
• setSessionDefaults — 设置会话上下文（reportSuiteId + globalCompanyId）
• describeAa(REPORT_SUITE_CONTEXT_GUIDE) — 加载组织上下文、核心指标、日历配置和时区
• findMetrics — 查找并验证指标 ID
• listComponentUsage — 用户未指定指标时，识别使用频率最高的指标
• runReport — 每个时间段调用一次，批量获取所有 KPI（当前时间段 + 对比时间段）
• searchDimensionItems — 查找贡献最大的项目，用于标注主要变化项

---

阶段 0 — 设置

1. 使用 findReportSuites / setSessionDefaults 确认报表包。
2. 调用 describeAa(REPORT_SUITE_CONTEXT_GUIDE) 加载组织上下文：核心指标、日历配置和时区。将报表包的每周首日记录为 WEEK_START_DOW，将报表包时区记录为 TIMEZONE——在阶段 2 计算报告时间段时需要用到这两项。如果上下文指南未返回 WEEK_START_DOW，则默认为星期一（ISO 8601）。

findReportSuites(globalCompanyId: "<gcid>")
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")

---

阶段 1 — 选择 KPI

1.1 如果用户指定了指标

将每项指标解析为 AA 指标 ID：

findMetrics(searchTerm: "<metric name>")

最多选择 8 项指标，以确保摘要聚焦。如果用户请求的指标超过 8 项，请让用户确定优先级，或提出拆分成多份报告。

1.2 如果用户未指定指标

使用 listComponentUsage 查找报表包中使用频率最高的指标：

listComponentUsage(componentType: "metric")

按使用次数选择排名前 5–7 的指标。向用户确认：

"根据使用情况，我会跟踪：访问次数、页面浏览量、收入、订单数、转化率、跳出率。这样合适吗？或者你想调整一下？"

---

阶段 2 — 选择时间段

询问用户要报告哪个时间段，或根据上下文推断：

请求	当前时间段	对比时间段
"this week"	最近 7 天	前 7 天
"this month"	本月至今	上月同期
"last month"	上一个完整日历月	上年同月
"this quarter"	本季度至今	上季度同期
"YTD"	1 月 1 日至今	上年同期

确认："我会对比[当前时间段]与[对比时间段]。这样对吗？"

**日历规则（必须遵守）：**当前时间段和对比时间段必须使用阶段 0 中的同一 WEEK_START_DOW。对于每周摘要，两个时间段的 startDate 必须是同一星期几，且都恰好为 7 天；对比时间段必须紧接在当前时间段开始之前结束。切勿在同一份摘要中混用不同规则（例如，当前时间段为周一至周日，对比时间段为周日至周六）。对于自定义日期范围，请将对比时间段设为长度相同且紧接在当前时间段开始之前结束的时间窗口。

**调用 runReport 前的合理性检查：**确认 current.startDate 和 comparison.startDate 是同一星期几，且 current.startDate - comparison.endDate == 1 day。如果不符合，请重新计算。

**边界情况：**如果今天处于某个时间段的前 3 天内，请注明当前时间段的数据可能不完整，对比结果可能出现偏差。

---

阶段 3 — 获取 KPI 数据

将所选指标批量合并，每个周期仅调用一次：

runReport(
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  dimensionId: "variables/daterangeday",
  startDate: "<current period start>T00:00",
  endDate: "<current period end>T23:59"
)

runReport(
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  dimensionId: "variables/daterangeday",
  startDate: "<comparison period start>T00:00",
  endDate: "<comparison period end>T23:59"
)

注意：metricIds 接受以逗号分隔的 ID——一次传入所有 KPI。 使用 startDate/endDate（而非 dateRange）；不要传入 granularity 参数。 使用 variables/daterangeday 获取逐日明细。 summaryData.totals[0]、totals[1] 等依次对应各项指标。 未授权的指标会显示在 columnErrors 中；调用的其余部分仍会成功。

无论指标数量多少，总共调用 2 次。

根据每组数据计算：

• 当前值（周期内总计）
• 前期值（对比周期内总计）
• 绝对变化：当前值 - 前期值
• 百分比变化：（变化值 / 前期值）× 100
• 趋势：正值用 ↑，负值用 ↓，在 ±2% 范围内用 →

---

阶段 4 — 主要变化因素分析

针对百分比变化最大（正向或负向）的 1–2 项指标， 运行维度明细以找出主要贡献因素：

runReport(
  metricIds: "<metricId>",
  dimensionId: "variables/marketingchannel",
  startDate: "<current period start>T00:00",
  endDate: "<current period end>T23:59",
  limit: 5
)

如果相关，可对第二个维度重复分析（例如，流量激增时分析页面， 收入变化时分析产品）。

使用结果撰写 1–2 句说明变化原因：

“访问量环比增长 18%，主要由自然搜索（+34%）带动，抵消了直接流量的下降（-12%）。”

---

阶段 5 — 生成 HTML 报告

直接构建 KPI 脉冲 HTML 报告，并写入 /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html。

渲染规则 — 每次运行都必须一致

对同一报表套件和周期运行此技能两次，渲染结果必须完全相同 （生成时间戳除外）。以下规则固定了 AI 否则可能出现偏差的格式选择。

数字格式

• KPI 值（每个卡片中的大号数字）——使用完整数字，并添加 千位分隔符（8,160、77,584、1,250,000）。不要使用 K 或 M 等 SI 后缀，即使数值很大也不例外。高管需要准确数字，而非缩写。
• 百分比变化（徽标和说明要点中）——始终保留一位小数，并按 远离零方向舍入。例如，−23.55% 显示为 −23.6%，绝不能显示为 −23.5%。使用完整精度值计算；仅在 显示时舍入。
• 百分点变化（适用于转化率或跳出率等本身以百分比表示的指标）—— 使用相同的舍入规则，后缀为 pp。例如：+0.40 pp。
• 货币——使用 $ 前缀和千位分隔符，金额 ≥ $100 时不显示小数 （$1,240,000）；金额 < $100 时显示美分（$45.20）。

空值 / 缺失数据处理

KPI 卡片必须反映报表套件实际返回的数据。AI 不得擅自替换为其他指标， 也不得为了让报告看起来更整洁而隐藏卡片。

• 所渲染的 KPI 在两个周期都返回 0 或 NULL：渲染卡片，kpi-value 设为 Data unavailable，徽标类设为 flat，徽标文本设为 ⚠ N/A，prior 文本设为 Both periods returned no data — validate instrumentation。卡片必须保留在网格中；不得省略。
• 一个周期返回有效数据，另一个周期返回 0 / NULL：渲染卡片， kpi-value 使用有效值，徽标类设为 flat，徽标文本设为 ⚠ N/A， prior 文本设为 Prior {period_noun}: no data。
• 绝不替换为衍生指标（例如，收入返回 $0 时添加“转化率”）。 可见 KPI 集合必须与本次运行所选指标一致。

HTML 模板

阅读 template.html 并原样使用。不要自行设计 HTML 结构或 CSS——只填入 {PLACEHOLDER} 令牌（{ORG_NAME}、{PERIOD_LABEL}、{COMPARISON_LABEL}、{REPORT_SUITE}、{GENERATED_DATE}、{METRIC_NAME}、{FORMATTED_VALUE_A}、{FORMATTED_VALUE_B}、{PCT_CHANGE}、{VALUE_A}、{VALUE_B}、{DELTA}、{ARROW}），并针对每项数据重复 KPI 卡片／详细行／变动项行区块。按照阶段 3 中的趋势规则，保留 .up | .down | .flat 和 .green | .red | .yellow | .grey 修饰类。

区块标题——不带阶段前缀：HTML 报告中的区块标题不得包含阶段编号。仅使用区块名称（例如，“KPI 记分卡”，而非“阶段 2 — KPI 记分卡”；“主要变动项”，而非“阶段 4 — 主要变动项”）。

将完成的 HTML 写入 /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html，然后打开：

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

---

KPI 卡片颜色规则

• 变动徽标：变化 >= +2% 时为绿色
• 变动徽标：变化 <= -2% 时为红色
• 变动徽标：变化介于 -2% 和 +2% 之间（持平）时为灰色
• 卡片顶部边框：正向变化时为绿色，负向变化时为红色， 持平时为灰色

---

内联摘要（始终提供）

除了 HTML 报告，还应始终提供一段简短的内联文本摘要：

KPI Pulse — [Period] vs [Comparison]
Report Suite: [Name]

Metric              Current   Change
─────────────────   ───────   ──────
Visits              124,500   ▲ 18%
Revenue             $42,800   ▲  9%
Conversion Rate       2.4%    ▼  0.3pp
Page Views          398,200   ▲ 11%
Bounce Rate          48.2%    ▼  1.8pp

Key driver: Visits growth led by Paid Search (+34%).
Revenue up on strong Mobile performance (+22%).

---

注意事项

• 获取数据前，始终先与用户确认时间段——时间段错误是最常见的困惑来源。
• 明确标注不完整的时间段（例如，“本月目前只有 5 天的数据”）。
• 对于百分比指标（转化率、跳出率），以百分点（pp）而非百分比变化报告差值。
• 指标数量最多为 8 个，以控制调用量。如需更多指标，可提供第二次数据快报。

---

交互示例

“给我一份上周的 KPI 更新。”

1. 使用 findReportSuites 和 setSessionDefaults 确认报告套件。
2. 使用 describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE") 加载上下文。
3. 从 listComponentUsage(componentType: "metric") 或用户输入中确定最重要的 6 个指标。
4. 确认：最近 7 天与之前 7 天对比。
5. 运行 12 次 runReport 调用（每个指标 2 次）——使用 metricIds、startDate、endDate 和 dimensionId: "variables/daterangeday"。对每个时间段，将 summaryData.totals[0] 相加，得出总值。
6. 对变动最大的 2 个指标运行维度细分（使用 dimensionId: "variables/marketingchannel"）。
7. 生成 HTML 报告，打开报告，并提供内联摘要。
8. 总结：“访问量环比增长了 18%，主要由付费搜索带动。收入增长了 9%，移动端表现领先。跳出率改善了 1.8pp。”