aa-kpi-pulse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KPI Pulse (Adobe Analytics)

KPI Pulse（Adobe Analytics）

Produce a compact, digestible KPI digest showing how key metrics changed over a chosen period, which items drove the change, and what stood out. Batches all KPIs into two

runReport

calls (current period + comparison period) and assembles results into an HTML performance card deck.

生成简洁易懂的KPI摘要，展示关键指标在选定时间段内的变化情况、变动驱动因素以及突出表现。将所有KPI批量分为两次

runReport

调用（当前时间段+对比时间段），并将结果整合为HTML绩效卡片集。

AA MCP Tools Used

使用的AA MCP工具

```
findReportSuites
```
— select working report suite
```
setSessionDefaults
```
— set session context (reportSuiteId + globalCompanyId)
```
describeAa(REPORT_SUITE_CONTEXT_GUIDE)
```
— load org context, top metrics, calendar config, and timezone
```
findMetrics
```
— discover and validate metric IDs
```
listComponentUsage
```
— identify top-used metrics if user hasn't specified
```
runReport
```
— all KPIs batched in one call per period (current + comparison)
```
searchDimensionItems
```
— find top contributors for top-mover callouts

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

Phase 0 — Setup

阶段0 — 准备工作

Confirm report suite with
```
findReportSuites
```
/
```
setSessionDefaults
```
.
Call
```
describeAa(REPORT_SUITE_CONTEXT_GUIDE)
```
to load organizational context: top metrics, calendar configuration, and timezone. Record the report suite's first-day-of-week as
```
WEEK_START_DOW
```
and the report suite timezone as
```
TIMEZONE
```
— you will use both when computing reporting periods in Phase 2. If the context guide returns no
```
WEEK_START_DOW
```
, default to Monday (ISO 8601).

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

通过
```
findReportSuites
```
/
```
setSessionDefaults
```
确认报表套件。
调用
```
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")

Phase 1 — Select KPIs

阶段1 — 选择KPI

1.1 If the user specified metrics

1.1 若用户指定了指标

Resolve each to an AA metric ID:

findMetrics(searchTerm: "<metric name>")

Cap at 8 metrics for a focused pulse. If more are requested, ask the user to prioritize or offer to split into multiple reports.

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

findMetrics(searchTerm: "<metric name>")

为保证摘要聚焦，指标数量上限为8个。若用户请求更多指标，请让用户优先选择，或提议拆分为多份报告。

1.2 If the user has not specified metrics

1.2 若用户未指定指标

Use

listComponentUsage

to find the most-used metrics in the report suite:

listComponentUsage(componentType: "metric")

Select the top 5–7 by usage count. Confirm with the user:

"Based on usage, I'll track: Visits, Page Views, Revenue, Orders, Conversion Rate, Bounce Rate. Does this look right, or would you like to adjust?"

使用

listComponentUsage

查找报表套件中使用频率最高的指标：

listComponentUsage(componentType: "metric")

选择使用量排名前5-7的指标，并与用户确认：

"基于使用情况，我将跟踪以下指标：访问量、页面浏览量、收入、订单量、转化率、跳出率。这样可以吗？还是您需要调整？"

Phase 2 — Select Time Periods

阶段2 — 选择时间段

Ask the user what period to report on, or infer from context:

Request	Current Period	Comparison Period
"this week"	Last 7 days	Prior 7 days
"this month"	Month-to-date	Same period last month
"last month"	Last full calendar month	Same month prior year
"this quarter"	Quarter-to-date	Same period last quarter
"YTD"	Jan 1 to today	Same period prior year

Confirm: "I'll compare [current period] vs [comparison period]. Is that right?"

Calendar rule (mandatory): the current period and the comparison period MUST use the same

WEEK_START_DOW

from Phase 0. For weekly pulses, both periods'

startDate

fall on the same day-of-week, both are exactly 7 days long, and the comparison period ends immediately before the current period starts. Never mix conventions (e.g., a Mon–Sun current with a Sun–Sat prior) within the same pulse. For custom date ranges, compute the comparison period as the equal-length window ending immediately before the current period starts.

Sanity check before calling
runReport
: confirm

current.startDate

and

comparison.startDate

are the same day-of-week and that

current.startDate - comparison.endDate == 1 day

. If not, recompute.

Edge case: If today is within the first 3 days of a period, note that the current-period data may be incomplete and the comparison may look skewed.

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

请求内容	当前时间段	对比时间段
"本周"	过去7天	之前7天
"本月"	当月截至今日	上月同期
"上月"	完整上月	去年同月
"本季度"	当季截至今日	去年同期季度
"年初至今"	1月1日至今日	去年同期

与用户确认："我将对比[当前时间段]与[对比时间段]，对吗？"

日历规则（强制）：当前时间段与对比时间段必须使用阶段0中获取的相同

WEEK_START_DOW

。对于周度摘要，两个时间段的

startDate

必须是同一星期几，时长均为7天，且对比时间段结束时间紧邻当前时间段开始时间。切勿在同一份摘要中混用不同规则（例如当前时间段为周一至周日，对比时间段为周日至周六）。对于自定义日期范围，对比时间段需设置为与当前时间段时长相同、且结束时间紧邻当前时间段开始时间的窗口。

调用
runReport
前的合理性检查：确认

current.startDate

和

comparison.startDate

是同一星期几，且

current.startDate - comparison.endDate == 1天

。若不符合，重新计算。

边缘情况：若当前日期处于某时间段的前3天，需提示用户当前时间段的数据可能不完整，对比结果可能存在偏差。

Phase 3 — Fetch KPI Data

阶段3 — 获取KPI数据

Batch all selected metrics into a single call per period:

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"
)

Note:
metricIds
accepts comma-separated IDs — pass all KPIs at once.
startDate
/
endDate
(not
dateRange
); no
granularity
parameter. Use
variables/daterangeday
for day-by-day breakdown.
summaryData.totals[0]
,
totals[1]
, etc. correspond to each metric in order. Unauthorized metrics surface in
columnErrors
; the rest of the call still succeeds.

2 calls total regardless of metric count.

From each pair, compute:

Current value (total over period)
Prior value (total over comparison period)
Absolute delta: current - prior
Percent change: (delta / prior) × 100
Trend: ↑ if positive, ↓ if negative, → if within ±2%

将所有选定指标批量放入每个时间段的单次调用中：

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%以内显示→

Phase 4 — Top Mover Context

阶段4 — 变动最大指标的上下文分析

For the 1–2 metrics with the largest percent changes (positive or negative), run a dimension breakdown to find the top contributor:

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

Repeat for a second dimension if relevant (e.g., pages for a traffic spike, products for a revenue change).

Use results to write a 1–2 sentence driver narrative:

"Visits rose 18% WoW, driven primarily by Organic Search (+34%) which offset a decline in Direct traffic (-12%)."

针对变化百分比最大的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%）。"

Phase 5 — Generate HTML Report

阶段5 — 生成HTML报告

Build the KPI pulse HTML report inline and write to

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

在线构建KPI摘要HTML报告，并写入

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

。

Rendering rules — apply consistently across runs

渲染规则 — 所有运行需保持一致

Two runs of this skill on the same report suite + period must render identically (modulo the generation timestamp). The rules below pin the formatting choices that the AI would otherwise drift on.

针对同一报表套件和时间段运行两次此技能，生成的报告必须完全相同（生成时间戳除外）。以下规则固定了AI可能会随意变动的格式选项。

Number formatting

数字格式

KPI values (the big number in each tile) — use full digits with thousands separators (
```
8,160
```
,
```
77,584
```
,
```
1,250,000
```
). Do NOT use SI suffixes like
```
K
```
or
```
M
```
, even for large values. Executives want exact numbers, not abbreviations.
Percent change (in pills and narrative bullets) — always one decimal place, rounded half-away-from-zero. For example,
```
−23.55%
```
displays as
```
−23.6%
```
, never
```
−23.5%
```
. Compute on full-precision values; round only at display time.
Percentage-point change (for already-percentage metrics like Conversion Rate or Bounce Rate) — same rounding, suffix
```
pp
```
. Example:
```
+0.40 pp
```
.
Currency —
```
$
```
prefix with thousands separators and no decimals for values ≥ $100 (
```
$1,240,000
```
); cents only when value < $100 (
```
$45.20
```
).

KPI数值（每个卡片中的大数字）——使用完整数字并添加千位分隔符（
```
8,160
```
、
```
77,584
```
、
```
1,250,000
```
）。即使数值很大，也禁止使用
```
K
```
或
```
M
```
等国际单位制后缀。管理人员需要精确数字，而非缩写。
变化百分比（在标签和说明要点中）——始终保留一位小数，采用四舍五入到最近整数的规则。例如，
```
−23.55%
```
显示为
```
−23.6%
```
，而非
```
−23.5%
```
。基于全精度数值计算；仅在显示时进行四舍五入。
百分点变化（针对转化率或跳出率等本身为百分比的指标）——四舍五入规则相同，后缀为
```
pp
```
。示例：
```
+0.40 pp
```
。
货币——添加
```
$
```
前缀和千位分隔符，数值≥$100时不保留小数（
```
$1,240,000
```
）；数值<$100时保留分（
```
$45.20
```
）。

Null / missing data handling

空值/缺失数据处理

A KPI tile must reflect what the report suite actually returned. The AI must not silently substitute a different metric or hide a tile to make the report look cleaner.

Both periods return 0 or NULL for a KPI being rendered: render the tile with
```
kpi-value
```
=
```
Data unavailable
```
, pill class
```
flat
```
, pill text
```
⚠ N/A
```
, and
```
prior
```
text =
```
Both periods returned no data — validate instrumentation
```
. The tile stays in the grid; do not omit it.
One period returns valid data, the other 0 / NULL: render the tile with the valid value as
```
kpi-value
```
, pill class
```
flat
```
, pill text
```
⚠ N/A
```
, and
```
prior
```
text =
```
Prior {period_noun}: no data
```
.
Never substitute a derived metric (e.g., adding "Conversion Rate" because Revenue came back $0). The visible KPI set MUST match the metrics selected for this run.

KPI卡片必须如实反映报表套件返回的结果。AI不得擅自替换其他指标或隐藏卡片来美化报告。

若某KPI在两个时间段均返回0或NULL：渲染卡片时
```
kpi-value
```
设为
```
数据不可用
```
，标签类为
```
flat
```
，标签文本为
```
⚠ N/A
```
，
```
prior
```
文本为
```
两个时间段均无数据——请验证数据采集
```
。卡片需保留在网格中；不得省略。
若某KPI仅在一个时间段返回有效数据，另一个时间段返回0/NULL：渲染卡片时
```
kpi-value
```
设为有效数值，标签类为
```
flat
```
，标签文本为
```
⚠ N/A
```
，
```
prior
```
文本为
```
对比[时间段名称]：无数据
```
。
禁止替换衍生指标（例如因收入返回$0而添加“转化率”）。显示的KPI集合必须与本次运行选定的指标一致。

HTML template

HTML模板

Read

template.html

and use it verbatim. Do not improvise the HTML structure or CSS — only fill in the

{PLACEHOLDER}

tokens (

{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}

) and repeat the KPI tile / detail row / mover row blocks once per data item. Preserve the

.up | .down | .flat

and

.green | .red | .yellow | .grey

modifier classes per the trend rules in Phase 3.

Section titles — no phase prefix: Section headings in the HTML report must not include the phase number. Use the plain section name only (e.g., "KPI Scorecards" not "Phase 2 — KPI Scorecards", "Top Movers" not "Phase 4 — Top Movers").

Write the completed HTML to

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

, then open:

bash

open /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.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

，然后打开：

bash

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

KPI Card Coloring Rules

KPI卡片配色规则

Delta badge green if change >= +2%
Delta badge red if change <= -2%
Delta badge grey if between -2% and +2% (flat)
Border-top on card: green for positive movement, red for negative, grey for flat

差值标签为绿色：变化≥+2%
差值标签为红色：变化≤-2%
差值标签为灰色：变化在-2%至+2%之间（持平）
卡片顶部边框：正向变动为绿色，负向变动为红色，持平为灰色

Inline Summary (Always Deliver)

在线摘要（必须提供）

In addition to the HTML report, always provide a brief inline text summary:

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%).

除HTML报告外，还需始终提供简短的在线文本摘要：

KPI摘要 — [当前时间段] vs [对比时间段]
报表套件：[名称]

指标              当前值    变动情况
─────────────────   ───────   ──────
访问量              124,500   ▲ 18%
收入             $42,800   ▲  9%
转化率       2.4%    ▼  0.3pp
页面浏览量          398,200   ▲ 11%
跳出率          48.2%    ▼  1.8pp

关键驱动因素：访问量增长由付费搜索（+34%）引领。
收入增长得益于移动端的强劲表现（+22%）。

Guardrails

约束规则

Always confirm the time period with the user before fetching data — wrong periods are the most common source of confusion.
Flag partial periods explicitly (e.g., "This month has only 5 days of data").
For percentage metrics (conversion rate, bounce rate), report deltas as percentage points (pp), not percent change.
Cap at 8 metrics for reasonable call volume. Offer a second pulse for additional metrics if needed.

在获取数据前，务必与用户确认时间段——时间段错误是最常见的混淆来源。
明确标记不完整的时间段（例如“本月仅包含5天数据”）。
对于百分比类指标（转化率、跳出率），以百分点（pp）为单位报告差值，而非变化百分比。
指标数量上限为8个，以保证合理的调用量。若需要更多指标，可提供第二份摘要。

Example Interaction

交互示例

"Give me a KPI update for last week."

Confirm report suite with
```
findReportSuites
```
and
```
setSessionDefaults
```
.

Load context with

describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")

Identify top 6 metrics from

listComponentUsage(componentType: "metric")

or user input.

Confirm: last 7 days vs prior 7 days.

Run 12

runReport

calls (2 per metric) — use

metricIds

startDate

endDate

, and

dimensionId: "variables/daterangeday"

. Sum

summaryData.totals[0]

for each period total.

Run dimension breakdown for 2 biggest movers (use
```
dimensionId: "variables/marketingchannel"
```
).
Generate HTML report, open it, deliver inline summary.
Narrative: "Visits were up 18% WoW driven by paid search. Revenue grew 9% with mobile leading. Bounce rate improved 1.8pp."

"给我一份上周的KPI更新。"

通过
```
findReportSuites
```
和
```
setSessionDefaults
```
确认报表套件。

通过

describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")

加载上下文。

通过
```
listComponentUsage(componentType: "metric")
```
或用户输入确定排名前6的指标。
确认：过去7天 vs 之前7天。
运行12次
```
runReport
```
调用（每个指标2次）——使用
```
metricIds
```
、
```
startDate
```
、
```
endDate
```
和
```
dimensionId: "variables/daterangeday"
```
。汇总每个时间段的
```
summaryData.totals[0]
```
得到总计值。
针对2个变动最大的指标运行维度拆分（使用
```
dimensionId: "variables/marketingchannel"
```
）。
生成HTML报告并打开，同时提供在线摘要。
说明："访问量较上周增长18%，由付费搜索驱动。收入增长9%，移动端表现领先。跳出率改善1.8pp。"