aa-executive-briefing

高管简报（Adobe Analytics）

生成简洁、适合高管阅读的绩效摘要，包含背景叙述、指标亮点和关键驱动因素。面向领导层受众——不呈现原始数据，只提供清晰的信号和业务影响。

实施期间验证的关键参数事实：

• runReport → metricIds（复数），而不是 metricId；日期格式为 YYYY-MM-DDTHH:mm:ss
• findMetrics → expansions 是必填参数（使用 "componentType"）
• describeAa → 参数是 guideType，而不是 guide；REPORT_SUITE_CONTEXT_GUIDE 对某些报表包可能返回空结果——请跳过并继续
• metrics/uniquevisitors 通常未经授权——请改用 metrics/visits
• 正确的工具名称是 setSessionDefaults（而不是 setDefaultReportSuite）

---

使用的 AA MCP 工具

• findReportSuites — 选择报表包
• setSessionDefaults — 设置会话上下文（reportSuiteId + globalCompanyId）
• describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE") — 加载组织上下文； 注意：某些报表包可能不返回输出——无需此信息也可继续
• findMetrics(expansions: "componentType") — 解析指标 ID（expansions 参数为必填）
• listComponentUsage(componentType: "metric") — 如果用户未指定指标，则识别最常用的指标
• runReport — 通过一次调用批量获取当前期和比较期的所有指标 （metricIds 接受以逗号分隔的 ID）；获取表现突出项目的维度细分
• searchDimensionItems — 验证驱动因素说明中的维度值

---

阶段 0 — 设置

1. 确认报表包。
2. 加载组织上下文：

findReportSuites()
setSessionDefaults(reportSuiteId: "<rsid>", globalCompanyId: "<companyId>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")   # may return empty — proceed if so

使用上下文指南了解：

• 组织名称和行业
• 最常用的指标（核心 KPI）
• **日历惯例和时区。**记录这些值——阶段 1 的每项日期计算都要用到：
  • WEEK_START_DOW — 每周的起始日。默认值：星期一 （ISO 8601）。
  • FISCAL_YEAR_START_MONTH — 财年的起始月份。默认值： 一月（日历年）。
  • TIMEZONE — 例如，America/Los_Angeles。
  • CALENDAR_SOURCE — 取值为 "context guide"、"default fallback" 或 "user override"。
• 当前启用的报表包区段

---

阶段 1 — 明确简报需求

询问用户：

1. 时间段 — “这份简报应涵盖哪个时间段？”
   • 上周
   • 上个月
   • 本月至今（MTD）
   • 本季度 / 季度至今（QTD）
   • 上季度
   • 自定义日期范围

原则

对同一报表包、时间段类型和提示词运行此技能两次，必须 生成完全相同的 current 和 comparison 日期范围。要确保结果确定， (a) 应从阶段 0 读取日历惯例，而不是自行判断；(b) 应针对相应时间段类型 应用对齐规则，不凭主观判断。

时间段类型 → 对齐规则

根据用户请求，准确选择一种时间段类型：

用户请求	PERIOD_TYPE	当前时间段	比较时间段
“上周”	weekly	截至今天之前最近一个完整周，按 WEEK_START_DOW 对齐（恰好 7 天）	紧邻其前的那一周，对齐方式相同
“本月” / “MTD”	month-to-date	本月 1 日 → 今天	上月 1 日 → 与今天相同的日期
“上个月”	monthly	上一个完整日历月	再前一个月
“本季度” / “QTD”	quarter-to-date	当前财季起始日 → 今天；财季依据 FISCAL_YEAR_START_MONTH 计算	前一财季中已过去的相同天数
“上季度” / “第 [N] 季度”	quarterly	上一个完整财季	再前一个财季
自定义日期范围	custom	按指定范围使用	以 current.startDate 前一天为结束日的等长时间段

通用不变量（必须适用于所有周期类型）

调用 runReport 前，请验证以下六项：

1. current.startDate < current.endDate
2. comparison.startDate < comparison.endDate
3. comparison.endDate < current.startDate（不重叠）
4. comparison.endDate 的次日等于 current.startDate（连续）
5. current 和 comparison 的天数相同
6. 满足 PERIOD_TYPE 的对齐规则：
   • weekly：两个 startDate 都落在 WEEK_START_DOW
   • monthly：两个 startDate 都落在每月 1 日
   • month-to-date：两个 startDate 都落在 1 日；两个 endDate 的月份日期相同
   • quarterly：两个 startDate 都落在财季首日
   • quarter-to-date：两个 startDate 都落在财季开始日；两个 endDate 都是该季度开始后的相同天数
   • custom：天数相同；满足连续性

如果任意一项不满足，请重新计算日期。切勿通过修改页脚来掩盖不一致。

示例 — 今天是 2026 年 5 月 26 日，星期二

假设 WEEK_START_DOW = Sunday 且 FISCAL_YEAR_START_MONTH = January。其他日历下的数字会有所不同，这正是重点。

用户请求	PERIOD_TYPE	当前周期	对比周期
“上周”	weekly	5 月 17 日（周日）– 5 月 23 日（周六）	5 月 10 日（周日）– 5 月 16 日（周六）
“本月” / “MTD”	month-to-date	5 月 1 日 – 5 月 26 日	4 月 1 日 – 4 月 26 日
“上个月”	monthly	4 月 1 日 – 4 月 30 日	3 月 1 日 – 3 月 31 日
“本季度” / “QTD”	quarter-to-date	4 月 1 日 – 5 月 26 日	1 月 1 日 – 2 月 24 日
“上季度”	quarterly	1 月 1 日 – 3 月 31 日	2025 年 10 月 1 日 – 12 月 31 日
自定义：“5 月 15 日–22 日”	custom	5 月 15 日 – 5 月 22 日（8 天）	5 月 7 日 – 5 月 14 日（8 天）

如果 WEEK_START_DOW = Monday，则周报这一行变为 May 18 (Mon) – May 24 (Sun) 与 May 11 (Mon) – May 17 (Sun)。其他行不变。

常见的 AI 失败模式

AI 可能会根据训练数据“知道”一周从周一到周日（ISO 8601），或知道季度是 Q1=1 月至 3 月（日历季度）。静默地用这些默认规则覆盖上下文指南，正是本节旨在避免的确定性错误。页脚的方法说明必须准确描述你计算出的日期——如果页脚写着“周日为每周起始日”，但 current.startDate 是星期一，那么应修正日期，而不是页脚。

2. 受众 — “这份简报面向谁？”

   • C-suite / 董事会（层级最高、指标最少、背景信息最多）
   • VP / 总监级别（更详细，包含部分维度背景）
   • 营销领导层（侧重渠道和营销活动） 默认：C-suite 风格（简洁、聚焦业务）。

3. 北极星指标 — “这份简报最重要的单一指标是什么？” （例如：收入、转化次数、留存率） 如果未指定，请使用 listComponentUsage 中使用最多的指标。

4. 辅助指标 — “还应包含哪些其他指标？（最多 5 个）”

5. 特定主题重点 — “是否有任何想要强调或调查的内容？ （例如：移动端表现、营销活动结果）”

---

第 2 阶段 — 解析指标

findMetrics(expansions: "componentType")  # expansions required
listComponentUsage(componentType: "metric")  # if metrics not specified

重要： findMetrics 需要 expansions 参数（请使用 "componentType" 作为安全默认值）。缺少此参数时，调用会失败。

避免使用 metrics/uniquevisitors — 此指标经常受限，并会返回 "unauthorized_metric" 错误。受众规模请优先使用 metrics/visits。

适用于 AA 简报的可靠标准指标： metrics/pageviews、metrics/visits、 metrics/orders、metrics/revenue、metrics/bouncerate、metrics/occurrences

确定性选择——不得自行发挥

每次运行都必须得到可复现的 KPI 集合。对同一报告套件和周期运行此技能两次，必须得出相同的指标值，这要求每次都选择相同的指标 ID。请严格遵循以下算法：

1. 如果用户明确指定了指标，请通过 findMetrics 将每个指标解析为一个具体的指标 ID。如果存在歧义，请从 listComponentUsage 中选择 usageCount 最高的指标，并记录这一选择。
2. 否则，获取 listComponentUsage(componentType: "metric") 的结果，按 usageCount 降序排序；若相同，则按指标 ID 的字母顺序排序（稳定的次级排序），然后取前 6 个指标 ID。
3. 使用 describeMetric 解析显示名称。
4. 不得按指标“类型”（流量、转化或收入）挑选指标，也不得因为某个替代指标的名称更适合叙述，就用它替换原指标。不同运行中选择 metrics/orders 与名为“Orders”的计算指标会产生截然不同的数字，并损害信任。

始终披露所用的指标 ID

在简报文件页脚中加入“包含的指标”一行，列出已解析的指标 ID。这样可以审计报告，也便于用户确认重新运行时使用的是相同指标。

记录指标 ID 和显示名称。指标总数不得超过 6 个。

---

第 3 阶段——获取效果数据

每个周期将所有指标合并到一次 runReport 调用中：

runReport(
  dimensionId: "variables/daterangeday",
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  startDate: "<YYYY-MM-DDTHH:mm:ss>",
  endDate:   "<YYYY-MM-DDTHH:mm:ss>"
)

重要： runReport 参数是 metricIds（复数），不是 metricId。 它接受以逗号分隔的 ID——在一次调用中传入所有指标。 日期必须使用带时间部分的 ISO 8601 格式：2026-03-31T00:00:00 / 2026-04-06T23:59:59。 使用 variables/daterangeday 作为 dimensionId，以获取按天细分的数据； 每个指标的总计按顺序位于 summaryData.totals[0]、totals[1] 等位置。 如果某个指标未获授权，它会显示在 columnErrors 中——整体调用仍会成功。

对于 6 个指标：总共调用 2 次（当前周期 + 对比周期）。

根据每对数据计算：

• 当前总计
• 前期总计
• 绝对变化量和百分比变化
• 趋势方向（上升／持平／下降）

---

第 4 阶段——驱动因素背景

对于北极星指标以及变化超过 ±10% 的任何指标，运行营销渠道细分报告，以查明变化的驱动因素：

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

如有需要，也对比对周期运行相同的报告，以识别占比变化。

如果用户提到了移动设备，还要检查设备类型：

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

---

第 5 阶段——撰写叙述

将执行简报写成结构化叙述，而不是数据表格。 语气：自信、清晰、着眼未来。避免行话。使用商业语言。

叙述结构

1. 开篇标题——用 1 句话概括该周期的整体结果。 “Q2 表现强劲，收入增长 14%，转化率达到 12 个月来的最高水平。”

2. 北极星指标——用 2–3 句话说明最重要的 KPI： 数值、变化、背景以及驱动因素。

3. 补充亮点——每个其他指标用 1 句话说明（先写积极表现，再写值得关注之处）。

4. 关键驱动因素——用 2 句话指出主要的变化原因。 “付费搜索带动了 60% 的收入增长，高于前一周期的 48%。电子邮件表现也显著改善，转化量提升了 22%。”

5. 风险或关注事项——用 1–2 句话说明任何令人担忧的情况： “移动设备上的跳出率上升了 4 个百分点，表明移动体验可能存在值得调查的问题。”

6. 未来展望／请求——可选：这对下一个周期意味着什么？

---

第 6 阶段——生成 HTML 简报文档

生成执行简报 HTML，并写入 /tmp/aa_executive_briefing_<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 不得悄悄替换成其他指标，也不得为了让简报看起来更整洁而隐藏卡片。

• 某指标在已解析集合中的两个时段均返回 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 时添加“转化率”）。可见 KPI 集合必须与页脚披露的已解析指标 ID 相符。
• 如果 Revenue／货币指标不可用，请在 KPI 网格上方显示 .callout.note，说明这一缺失。不得编造数值。

HTML 模板

模板变量

按照以下规则，填充下方 HTML 模板中的每个 {PLACEHOLDER}。 简报属于客户；不得将 Adobe、AA 或任何供应商相关措辞替换到面向客户的字段中。

• {ORG_NAME}——客户的业务或品牌名称，根据 Phase 0 中加载的报告套件上下文确定。删除 — Prod、 - Demo、 Stage、 Test、 MCP 等技术／环境后缀。如果报告套件名称中没有简洁的品牌名称，则删除后缀后使用报告套件的显示名称。不得编造名称，也不得替换为供应商名称。
• {PERIOD_TYPE}——Weekly、Monthly、Quarterly 或 Performance（默认值）之一，根据 Phase 1 推断的时段选择。
• {LEDE_SENTENCE}——严格使用以下模式，不得包含供应商名称： Leadership readout for the {period type lowercase} of {PERIOD_LABEL} compared to {COMPARISON_LABEL}.
• {REPORT_SUITE}——报告套件显示名称。这里可以保留后缀；此行是技术标识行，而非标题。
• {PERIOD_LABEL}／{COMPARISON_LABEL}——易读的日期范围，例如 May 12–18, 2026。
• {GENERATED_DATE}——今天的日期，使用相同的易读格式。
• {METRIC_LABEL}／{FORMATTED_VALUE}／{PCT_CHANGE}／{PRIOR_VALUE}**——Phase 3 中每个 KPI 对应的值。使用面向客户的指标显示名称，而非内部 ID。

HTML 模板

阅读 template.html 并原样使用。不要自行编写 HTML 结构或 CSS — 只填写上文 模板变量 中说明的 {PLACEHOLDER} 占位符。按照第 3 阶段的趋势规则，保留 .up | .down | .flat 和 .green | .red | .yellow | .grey 修饰类。

章节标题 — 不带阶段前缀：HTML 报告中的章节标题不得包含阶段编号。只使用纯章节名称（例如，“KPI 记分卡”，而不是“第 2 阶段 — KPI 记分卡”；“叙述”，而不是“第 3 阶段 — 叙述”；“关注事项”，而不是“第 5 阶段 — 关注事项”）。

写入 /tmp/aa_executive_briefing_<YYYY-MM-DD_HHMMSS>.html 并打开：

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

---

语气和风格指南

受众	语气	指标	长度
高管层	高层次，关注业务成果，每项指标用 1–2 句话	最多 3–5 项	1 页
副总裁／总监	运营细节、渠道背景、趋势叙述	5–7 项	1.5 页
营销领导层	活动和渠道深度、归因、细分	5–8 项	2 页

始终：

• 先强调积极成果，再说明问题。
• 将变化表述为业务影响，而不只是百分比（例如“收入增长 42K 美元，增幅为 14%”，而不只是“+14%”）。
• 对于下降的指标，说明可能的原因或下一步行动。

---

约束

• 不要直接呈现原始 API 输出 — 始终用文字说明数据。
• 如果指标变化在 ±3% 以内，应描述为“大致持平”，而不是讲述趋势。
• 始终在简报标题中明确指出比较时段。
• 如果 REPORT_SUITE_CONTEXT_GUIDE 中的背景信息指出了公司名称或行业，应在叙述中使用，以提供更个性化的内容。

---

交互示例

“为上周的业绩撰写一份面向领导团队的执行摘要。”

1. 确认报告套件；加载背景指南。
2. 确定时段：最近 7 天与之前 7 天对比。受众：副总裁级别。
3. 确认指标：收入、访问量、订单、转化率、跳出率。
4. 运行 2 份报告（每个时段的一次调用中批量处理全部 5 项指标）。
5. 运行收入渠道细分报告。
6. 撰写叙述：“收入环比增长 9%，达到 186K 美元，其中付费搜索贡献了 58% 的收入。访问量增长 18%，但移动端跳出率上升了 4 个百分点，表明结账体验可能存在值得调查的问题。”
7. 生成 HTML 简报并打开。
8. 将叙述作为内联文本提供，以便立即使用。