cja-kpi-pulse

KPI 脉搏（客户旅程分析）

在 2 分钟内生成精简的 KPI 摘要。目标是清晰回答“我们的表现如何？”，而不是深入分析或倾倒数据。每个 KPI 都会显示一张记分卡，列出当前值、与上一周期相比的变化、趋势方向，以及解释变动的首要维度细分。

---

使用的 CJA MCP 工具

• describeCja(DATAVIEW_CONTEXT_GUIDE) — 了解数据视图上下文
• listComponentUsage — 找出使用频率最高的指标（即组织实际关注的 KPI）
• findMetrics — 根据用户指定的名称解析指标 ID
• findCalculatedMetrics — 纳入自定义 KPI（如果有）
• runReport — 获取当前周期和上一周期的指标值
• searchDimensionItems — 查看变化指标的首要维度细分

---

阶段 0 — 设置

1. 调用 findDataViews，列出可用的数据视图。
2. 如果用户未指定数据视图，展示列表并询问要使用哪个。
3. 使用选定的 ID 调用 setDefaultSessionDataViewId。
4. 调用 describeCja("DATAVIEW_CONTEXT_GUIDE") 加载数据视图上下文。 记录数据视图的一周首日为 WEEK_START_DOW，时区为 TIMEZONE。如果上下文指南未返回一周首日，则默认使用星期一（ISO 8601）。你将在阶段 1.1 中使用这两项。
5. 明确监测范围：要跟踪哪些 KPI，以及比较周期（例如 WoW、MoM、与目标相比）。

阶段 1 — 明确范围

1.1 确定报告周期

如果用户未指定周期，提出一个问题：

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

如果用户未回答，默认使用本周与上周对比。

将答案映射为两个日期范围：

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

日历规则（强制）：

使用阶段 0 中的 WEEK_START_DOW 定义“周”。当前周期（周期 A）和比较周期（周期 B）必须使用相同的一周首日——也就是说，两个周期的 startDate 必须落在同一个星期几，长度必须完全相等，并且比较周期必须紧接在当前周期开始之前结束。同一次脉搏报告中，绝不能混用不同的周起始规则（例如，当前周期为周一至周日，上一周期为周日至周六）。先选定边界，再据此推算两个周期。对于自定义日期范围，将周期 B 计算为紧接在周期 A 开始之前结束、长度相等的时间窗口。

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

1.2 确定指标

如果用户指定了具体指标，使用 findMetrics 或 findCalculatedMetrics 解析。否则，自动发现排名前 5–8 的 KPI：

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

注意：对于没有使用历史记录的数据视图，listComponentUsage 可能返回空列表。如果返回为空，则改用：

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

从结果中选出与业务最相关的指标（按以下优先级：会话、订单、收入、产品查看、购物车查看、人数）。

去重：如果内置指标和计算指标衡量的是同一事项，只保留计算指标（其定义更明确）。

最终列表：5–8 个指标。脉搏报告中的 KPI 超过 8 个会造成信息噪声。

---

第 2 阶段 — 拉取当前及前一周期的数据

每个周期调用一次 runReport，并在调用中包含所有 KPI 指标。 Period A 和 Period 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，四舍五入到 1 位小数

---

第 3 阶段 — 分类趋势

为每项 KPI 指定趋势指示符：

• ↑ 上升，如果 pctChange > +3%
• ↓ 下降，如果 pctChange < −3%
• → 持平，如果 −3% ≤ pctChange ≤ +3%

指定信号颜色：

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

---

第 4 阶段 — 深入分析变化最大的指标

对于绝对百分比变化最大的 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。

比较 Period A 和 Period B 的维度值，找出对变化贡献最大的因素。将其作为报告中的“变化原因”条目。

---

第 5 阶段 — 生成 HTML 报告

直接生成 KPI Pulse HTML 报告的行内内容——不要使用 Python 脚本。 直接根据收集的数据构建 HTML 字符串，并将其作为代码块输出，供用户保存；或者使用单行 bash 命令将其写入 /tmp/cja_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html。

渲染规则 — 每次运行都一致应用

对于相同的数据视图和周期，两次运行此技能时必须生成相同的渲染结果 （生成时间戳除外）。以下规则固定格式选项，避免 AI 在其他方面出现偏差。

数字格式

• KPI 值（每个卡片中的大号数字）——使用完整数字，并添加千位分隔符 （8,160、77,584、1,250,000）。即使数值较大，也不要使用 K 或 M 等 SI 后缀。高管需要精确数字，而非缩写。
• 百分比变化（徽标和叙述性要点中）——始终保留 1 位小数，并采用远离零舍入。例如，−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。
• 绝不得替换为派生指标（例如，Revenue 返回 $0 时添加“Conversion Rate”）。可见 KPI 集合必须与本次运行所选指标一致。

HTML 模板

阅读 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 磁贴／详情行／变动行代码块。根据 Phase 3 中的趋势规则，保留 .up | .down | .flat 和 .green | .red | .yellow | .grey 修饰类。

---

Phase 6 — 交付报告

生成 HTML 后：

1. 将其写入 /tmp/cja_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html
2. 使用 open /tmp/cja_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html 打开
3. 在聊天中直接提供 3–5 行文字摘要：

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

即使不打开 HTML 文件，文字摘要也能立即提供有用信息。

---

重要注意事项

• 只读监控。 切勿修改指标、细分或项目。
• 使用一致的日期范围。 周环比和月环比比较必须使用等长周期。
• 标记异常，不要诊断。 脉冲报告会呈现显著偏差 — 深入的根因分析应在异常分类技能中进行。
• 遵循业务日历。 节假日、营销活动和季节性模式会影响正常波动 — 标记异常时请注明相关背景。
• 限制指标数量。 每次脉冲最多监控 10–15 项 KPI；更多指标会分散关注点。如果用户指定过多，请让用户优先选择。
• 注明数据新鲜度。 如果最新数据点比预期更早，请在呈现脉冲前提醒用户。

交互示例

“快速查看一下我们本周的关键指标。”

1. 设置： 使用 findDataViews 确认数据视图。用户选择其主要数据视图。调用 setDefaultSessionDataViewId。
2. 范围： 询问“应包含哪些 KPI？”用户回答：“会话数、收入、转化率和平均订单价值。”
3. 提取数据： 对全部四项指标运行 runReport，比较本周与上周。
4. 分析： 会话数周环比 +8%（在正常范围内）。收入周环比 +3%。转化率周环比 -12% — 标记为异常。平均订单价值周环比 +17% — 值得关注的正向变化。
5. 摘要： 提供带有红绿灯状态（绿／黄／红）的 KPI 记分卡，突出显示需要调查的转化率下降，并指出平均订单价值的增长部分抵消了这一影响。

错误处理

• 如果 runReport 未返回 Period B 的数据（比较周期太久远，或数据视图缺少历史记录），请在变化值处显示“N/A”，并使用灰色徽标标记。
• 如果某项指标返回 null，请显示“—”而非 0，以免造成业绩为零的错觉。
• 如果可用指标少于 3 项，请提醒用户脉冲可能不完整，并建议他们确认数据视图配置正确。