cja-kpi-pulse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KPI Pulse (Customer Journey Analytics)

KPI Pulse（客户旅程分析）

Produce a compact KPI digest in under 2 minutes. The goal is a crisp answer to "how did we do?" — not a deep-dive, not a data dump. Each KPI gets a scorecard showing current value, period-over-period change, trend direction, and the top dimension breakdown that explains any movement.

在2分钟内生成一份紧凑的KPI摘要。目标是清晰回答“我们表现如何？”——无需深入分析，也无需大量数据堆砌。每个KPI对应一个计分卡，展示当前数值、环比变化、趋势方向，以及解释指标变动的首要维度拆分。

CJA MCP Tools Used

使用的CJA MCP工具

```
describeCja(DATAVIEW_CONTEXT_GUIDE)
```
— understand the data view context
```
listComponentUsage
```
— find the most-used metrics (the org's real KPIs)
```
findMetrics
```
— resolve metric IDs from user-specified names
```
findCalculatedMetrics
```
— include custom KPIs if present
```
runReport
```
— pull metric values for current and prior periods
```
searchDimensionItems
```
— top dimension breakdown for movers

```
describeCja(DATAVIEW_CONTEXT_GUIDE)
```
— 了解数据视图上下文
```
listComponentUsage
```
— 找出使用频率最高的指标（企业的核心KPI）
```
findMetrics
```
— 根据用户指定的名称解析指标ID
```
findCalculatedMetrics
```
— 若存在自定义KPI则纳入其中
```
runReport
```
— 获取当前周期和对比周期的指标数值
```
searchDimensionItems
```
— 找出指标变动的首要维度拆分

Phase 0 — Setup

阶段0 — 准备工作

Call
```
findDataViews
```
to list available data views.
If the user hasn't specified a data view, present the list and ask which to use.
Call
```
setDefaultSessionDataViewId
```
with the chosen ID.
Call
```
describeCja("DATAVIEW_CONTEXT_GUIDE")
```
to load data view context. Record the data view's first-day-of-week as
```
WEEK_START_DOW
```
and timezone as
```
TIMEZONE
```
. If the context guide does not return a week-start value, default to Monday (ISO 8601). You will use both in Phase 1.1.
Clarify the monitoring scope: which KPIs to track and the comparison period (e.g., WoW, MoM, vs. target).

调用
```
findDataViews
```
列出可用的数据视图。
如果用户未指定数据视图，列出可选视图并询问使用哪一个。
使用选定的ID调用
```
setDefaultSessionDataViewId
```
。
调用
```
describeCja("DATAVIEW_CONTEXT_GUIDE")
```
加载数据视图上下文。记录数据视图的每周起始日为
```
WEEK_START_DOW
```
，时区为
```
TIMEZONE
```
。如果上下文指南未返回每周起始日，默认使用周一（ISO 8601标准）。这两个参数将在阶段1.1中使用。
明确监控范围：需要跟踪哪些KPI，以及对比周期（如周环比、月环比、与目标值对比）。

Phase 1 — Clarify Scope

阶段1 — 明确范围

1.1 Determine the reporting period

1.1 确定报告周期

If the user did not specify a period, ask one question:

"What time window would you like? Options: last 7 days, last 30 days, this week vs last week, this month vs last month, or a custom range."

Default to this week vs last week if no answer is given.

Map the answer to two date ranges:

Period A (current): e.g., "thisWeek", "thisMonth", last 7 days
Period B (comparison): e.g., "lastWeek", "lastMonth", prior 7 days

Calendar rule (mandatory):

Use

WEEK_START_DOW

from Phase 0 to define what "week" means. The current period (Period A) and the comparison period (Period B) MUST use the same first-day-of-week — i.e., both periods'

startDate

fall on the same day-of-week, both are exactly equal length, 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 run. Pick the boundary once, then derive both periods from it. For custom date ranges, compute Period B as the equal-length window ending immediately before Period A starts.

Sanity check before calling
runReport
: confirm

periodA.startDate

and

periodB.startDate

are the same day-of-week and that

periodA.startDate - periodB.endDate == 1 day

. If not, recompute.

如果用户未指定周期，询问以下问题：

“您想要哪个时间范围？选项：过去7天、过去30天、本周对比上周、本月对比上月，或自定义范围。”

若未得到回复，默认使用本周对比上周。

将用户的回答映射为两个日期范围：

周期A（当前）：例如“本周”“本月”“过去7天”
周期B（对比）：例如“上周”“上月”“之前7天”

日历规则（强制遵守）：

使用阶段0中获取的

WEEK_START_DOW

定义“周”的含义。当前周期（周期A）和对比周期（周期B）必须使用相同的每周起始日——即两个周期的

startDate

为同一星期几，长度完全相同，且对比周期在当前周期开始前立即结束。切勿在同一次Pulse运行中混用不同规则（例如当前周期为周一至周日，对比周期为周日至周六）。一旦确定边界，便从该边界推导两个周期。对于自定义日期范围，周期B为与周期A长度相同、且在周期A开始前立即结束的时间窗口。

**调用

runReport

前的合理性检查：**确认

periodA.startDate

和

periodB.startDate

为同一星期几，且

periodA.startDate - periodB.endDate == 1天

。若不满足，重新计算。

1.2 Determine the metrics

1.2 确定指标

If the user named specific metrics, resolve them with

findMetrics

findCalculatedMetrics

. Otherwise, discover the top 5–8 KPIs automatically:

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

Note:

listComponentUsage

may return an empty list for data views with no usage history. If it returns empty, fall back to:

findMetrics(searchQuery: "sessions visits revenue orders")
findMetrics(searchQuery: "page views cart conversion")

Pick the most business-relevant metrics from the results (sessions, orders, revenue, product views, cart views, people — in that priority order).

Deduplicate: if a built-in metric and a calculated metric measure the same thing, keep only the calculated metric (it's more intentional).

Final list: 5–8 metrics. More than 8 KPIs in a pulse report is noise.

如果用户指定了具体指标，使用

findMetrics

或

findCalculatedMetrics

进行解析。否则，自动发现排名前5-8的核心KPI：

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

注意：对于无使用历史的数据视图，

listComponentUsage

可能返回空列表。若返回空列表， fallback至：

findMetrics(searchQuery: "sessions visits revenue orders")
findMetrics(searchQuery: "page views cart conversion")

从结果中选取与业务最相关的指标（优先级顺序：会话量、订单量、收入、产品浏览量、购物车浏览量、用户数）。

去重：如果内置指标和计算指标衡量的是同一内容，仅保留计算指标（它更具针对性）。

最终列表：5-8个指标。Pulse报告中KPI数量超过8个会产生信息冗余。

Phase 2 — Pull Current and Prior Period Data

阶段2 — 获取当前周期和对比周期的数据

Run a single

runReport

call per period with all KPI metrics included. Use one call for Period A and one for Period B to minimize round-trips. Use a summary dimension (e.g.,

variables/daterangeday

) and limit: 1 to get aggregate totals from

summaryData.totals

in the response.

runReport(
  dimensionIds: "variables/daterangeday",
  metricIds: "metrics/visits,metrics/visitors,metrics/orders_1_1,metrics/productListItems.priceTotal,metrics/cart_views",
  startDate: "<periodA start>T00:00:00",
  endDate: "<periodA end>T23:59:59",
  page: 0,
  limit: 1
)

runReport(
  dimensionIds: "variables/daterangeday",
  metricIds: "metrics/visits,metrics/visitors,metrics/orders_1_1,metrics/productListItems.priceTotal,metrics/cart_views",
  startDate: "<periodB start>T00:00:00",
  endDate: "<periodB end>T23:59:59",
  page: 0,
  limit: 1
)

Read aggregate totals from

summaryData.totals

(not row data), which gives you the full-period sum for each metric in the order they were listed.

Capture for each metric:

```
valueA
```
(current period)
```
valueB
```
(comparison period)
```
delta
```
= valueA − valueB
```
pctChange
```
= (delta / valueB) × 100, rounded to 1 decimal

每个周期调用一次

runReport

，包含所有KPI指标。分别为周期A和周期B各调用一次，以减少往返次数。使用汇总维度（例如

variables/daterangeday

），并设置limit: 1，从响应中的

summaryData.totals

获取聚合总计。

runReport(
  dimensionIds: "variables/daterangeday",
  metricIds: "metrics/visits,metrics/visitors,metrics/orders_1_1,metrics/productListItems.priceTotal,metrics/cart_views",
  startDate: "<periodA start>T00:00:00",
  endDate: "<periodA end>T23:59:59",
  page: 0,
  limit: 1
)

runReport(
  dimensionIds: "variables/daterangeday",
  metricIds: "metrics/visits,metrics/visitors,metrics/orders_1_1,metrics/productListItems.priceTotal,metrics/cart_views",
  startDate: "<periodB start>T00:00:00",
  endDate: "<periodB end>T23:59:59",
  page: 0,
  limit: 1
)

从

summaryData.totals

读取聚合总计（而非行数据），这将按指标列出的顺序返回每个指标的全周期总和。

为每个指标记录：

```
valueA
```
（当前周期）
```
valueB
```
（对比周期）
```
delta
```
= valueA − valueB
```
pctChange
```
= (delta / valueB) × 100，保留一位小数

Phase 3 — Classify Trends

阶段3 — 分类趋势

For each KPI, assign a trend indicator:

↑ Up if pctChange > +3%
↓ Down if pctChange < −3%
→ Flat if −3% ≤ pctChange ≤ +3%

Assign a signal color:

For "higher is better" metrics: ↑ = green, ↓ = red, → = grey
For "lower is better" metrics (bounce rate, error rate): ↑ = red, ↓ = green

为每个KPI分配趋势标识：

↑ 上升：若pctChange > +3%
↓ 下降：若pctChange < −3%
→ 平稳：若−3% ≤ pctChange ≤ +3%

分配信号颜色：

对于“越高越好”的指标：↑=绿色，↓=红色，→=灰色
对于“越低越好”的指标（跳出率、错误率）：↑=红色，↓=绿色

Phase 4 — Top Mover Drill-Down

阶段4 — 核心变动指标深入分析

For the 1–2 metrics with the largest absolute % change, find what's driving the movement. Run a dimension breakdown for the current period:

runReport(
  dimensionIds: "variables/marketing_channel",
  metricIds: "<moving metric id>",
  startDate: "<periodA start>T00:00:00",
  endDate: "<periodA end>T23:59:59",
  page: 0,
  limit: 5
)

Note: Use

variables/marketing_channel

(not

variables/marketingchannel

) — verify the exact dimension ID with

findDimensions(searchQuery: "marketing channel")

if unsure.

Compare dimension values between Period A and Period B to identify the top contributor to the change. This becomes the "What drove it" entry in the report.

针对绝对百分比变化最大的1-2个指标，找出变动的驱动因素。对当前周期进行维度拆分：

runReport(
  dimensionIds: "variables/marketing_channel",
  metricIds: "<moving metric id>",
  startDate: "<periodA start>T00:00:00",
  endDate: "<periodA end>T23:59:59",
  page: 0,
  limit: 5
)

注意：使用

variables/marketing_channel

（而非

variables/marketingchannel

）——若不确定，使用

findDimensions(searchQuery: "marketing channel")

验证准确的维度ID。

对比周期A和周期B的维度数值，找出变动的首要贡献因素。这将作为报告中的“变动驱动因素”条目。

Phase 5 — Generate HTML Report

阶段5 — 生成HTML报告

Generate the KPI Pulse HTML report INLINE — do not use a Python script. Build the HTML string directly from the collected data and output it as a code block the user can save, or write it to

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

using a one-line bash command.

内联生成KPI Pulse HTML报告——请勿使用Python脚本。直接从收集的数据构建HTML字符串，并以代码块形式输出供用户保存，或使用单行bash命令将其写入

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

。

Rendering rules — apply consistently across runs

渲染规则 — 每次运行需保持一致

Two runs of this skill on the same data view + 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 data view 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
```
文本为
```
两个周期均无数据——请验证数据采集配置
```
。卡片需保留在网格中；请勿省略。
若一个周期返回有效数据，另一个周期返回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}

{DATA_VIEW}

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

读取

template.html

并严格使用。请勿随意修改HTML结构或CSS——仅填充

{PLACEHOLDER}

占位符（

{ORG_NAME}

、

{PERIOD_LABEL}

、

{COMPARISON_LABEL}

、

{DATA_VIEW}

、

{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

修饰类。

Phase 6 — Deliver the Report

阶段6 — 交付报告

After generating the HTML:

Write it to

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

Open with

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

Provide a 3–5 line text summary inline in the chat:

KPI Pulse — This Week vs Last Week

↑ Revenue: $1.24M (+8.2%)  — Paid Search drove most of the gain
↓ Conversion Rate: 2.1% (−0.4pp) — Drop in mobile checkout
→ Sessions: 540K (+1.1%)  — Flat week-over-week
↑ Orders: 11,340 (+6.7%)  — Product page improvements appear to be working
↓ Bounce Rate: 43.2% (+2.1pp) — Worth monitoring next week

The text summary gives immediate value even without opening the HTML file.

生成HTML后：

将其写入

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

使用

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

打开

在聊天框内提供3-5行文本摘要：

KPI Pulse — 本周对比上周

↑ 收入：$124万（+8.2%）——付费搜索是主要增长驱动因素
↓ 转化率：2.1%（−0.4pp）——移动端结账环节下滑
→ 会话量：54万（+1.1%）——周环比平稳
↑ 订单量：11,340（+6.7%）——产品页面优化似乎见效
↓ 跳出率：43.2%（+2.1pp）——下周需重点监控

即使不打开HTML文件，文本摘要也能提供即时价值。

Important Guardrails

重要约束规则

Read-only monitoring. Never modify metrics, segments, or projects.
Use consistent date ranges. Week-over-week and month-over-month comparisons must use equal-length periods.
Flag anomalies, don't diagnose them. The pulse report surfaces significant deviations — deep root cause analysis belongs in the anomaly triage skill.
Respect business calendar. Holiday periods, campaigns, and seasonal patterns affect normal variance — note context when flagging anomalies.
Cap metric count. Monitor up to 10–15 KPIs per pulse; more than that dilutes focus. Ask the user to prioritize if they specify too many.
Note data freshness. If the most recent data point is older than expected, warn the user before presenting the pulse.

只读监控。切勿修改指标、细分或项目。
使用一致的日期范围。周环比和月环比对比必须使用长度相同的周期。
标记异常，而非诊断异常。Pulse报告仅突出显示显著偏差——深入根本原因分析属于异常分类技能的范畴。
遵循业务日历。节假日、营销活动和季节性模式会影响正常波动——标记异常时需注明相关背景。
限制指标数量。每次Pulse最多监控10-15个KPI；数量过多会分散注意力。若用户指定过多指标，请让他们优先选择。
注明数据新鲜度。如果最新数据点晚于预期时间，在展示Pulse报告前需提醒用户。

Example Interaction

示例交互

"Give me a quick pulse on our key metrics for this week."

Setup: Confirm data view with
```
findDataViews
```
. User selects their main data view. Call
```
setDefaultSessionDataViewId
```
.
Scope: Ask "Which KPIs should I include?" User says: "Sessions, Revenue, Conversion Rate, and Average Order Value."
Data pull: Run
```
runReport
```
for current week vs. prior week for all four metrics.
Analysis: Sessions +8% WoW (within normal range). Revenue +3% WoW. Conversion Rate -12% WoW — flagged as anomalous. AOV +17% WoW — notable positive.
Summary: Present a KPI scorecard with traffic-light status (green/yellow/red), highlight the Conversion Rate drop as needing investigation, and note that the AOV increase partially offsets it.

“给我一份本周核心指标的快速概览。”

准备工作：使用
```
findDataViews
```
确认数据视图。用户选择主数据视图。调用
```
setDefaultSessionDataViewId
```
。
明确范围：询问“我应包含哪些KPI？”用户回答：“会话量、收入、转化率、平均订单价值。”
数据获取：针对四个指标，调用
```
runReport
```
获取本周与上周的数据。
分析：会话量周环比+8%（在正常范围内）。收入周环比+3%。转化率周环比-12%——标记为异常。平均订单价值周环比+17%——显著正向变动。
摘要：展示带有交通灯状态（绿/黄/红）的KPI计分卡，突出转化率下滑需调查，并说明平均订单价值的增长部分抵消了转化率下滑的影响。

Error Handling

错误处理

If
```
runReport
```
returns no data for Period B (comparison is too far in the past or data view lacks history), show "N/A" for the delta and flag it with a grey badge.
If a metric returns null, display "—" rather than 0 to avoid false impressions of zero performance.
If fewer than 3 metrics are available, warn the user that the pulse may be incomplete and suggest they verify the data view is correctly configured.

若
```
runReport
```
返回周期B无数据（对比周期过于久远或数据视图无历史数据），将差值显示为“N/A”，并使用灰色标记。
若指标返回null，显示“—”而非0，避免造成绩效为零的错误印象。
若可用指标少于3个，提醒用户Pulse报告可能不完整，并建议他们验证数据视图配置是否正确。