用途
本技能为 Spotify 广告投放提供快速的表现总览。它通过 Spotify Ads API 拉取活跃广告系列（campaign）的指标，在终端中以表格呈现曝光量、支出、触达、点击、CTR、频次等信息，并可根据预算计算投放节奏（pacing），帮助投放者快速判断预算消耗是否正常。
主要能力
- 账户总览（默认视图）：展示所有活跃广告系列的指标，包含活跃广告系列数量与总支出。
- 单个广告系列详情：指定某个广告系列 UUID，查看该系列的详细信息，并按广告组（ad set）拆分展示格式、预算、曝光、支出、触达、点击和完成数。
- 扩展总览：以
detail参数触发，在账户总览基础上进一步把每个广告系列拆解到广告组层级。 - 投放节奏计算：当存在预算信息时，对比日预算或生命周期预算与实际支出；若支出百分比与已流逝时间百分比相差超过 20 个百分点，则标记为超投（可能提前耗尽预算）或投放过慢（可能无法全额投放）。
- 分页提示：若响应中存在 continuation_token，会提示还有更多广告系列并建议分页处理。
使用方式
技能通过插件中的 scripts/api-request.sh 包装脚本调用 API。首先设置插件根目录并定义请求包装函数：
PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}"
api() { "$PLUGIN_ROOT/scripts/api-request.sh" dashboard "$@"; }
在首次调用 Ads API v3 前，需阅读并遵循 $PLUGIN_ROOT/skills/api-reference/references/live-openapi.md。
如需在 API 调用之外获取配置值（TOKEN、AD_ACCOUNT_ID、AUTO_EXECUTE、BASE_URL、SDK_HEADER、SKILL_HEADER、PLUGIN_VERSION），可运行 api --env，其输出为 eval 安全格式，可用 eval $(api --env) 一次性赋值。
参数解析规则：
- 无参数 → 账户总览（所有活跃广告系列）
<campaign_id>（UUID）→ 该广告系列的详情视图detail→ 含广告组拆分的扩展总览- 若参数含义不明确，应询问用户。
账户总览会执行两次 API 调用：一次获取广告系列的聚合指标（曝光、支出、点击、触达、频次、CTR、完成数，粒度为 LIFETIME，仅活跃状态），一次获取广告系列详情（名称、预算、节奏）。
广告系列详情视图执行三次调用：广告系列详情、按广告组聚合的指标（含父级实体）、广告组详情（预算与定向信息）。
扩展总览在账户总览的调用基础上，额外调用广告组级别的聚合报告与广告组详情。
执行行为：若 auto_execute 为 true，直接执行所有 API 调用并显示仪表盘；若为 false，则先展示 curl 命令并在执行前请求确认。出错时显示响应体中的错误信息。
格式与计算规则
- 来自 aggregate_reports 的支出已是广告账户的结算货币，直接以 $X.XX 显示（不要除以 1,000,000）。
- 来自实体详情（广告系列、广告组）的预算 micro_amount 为微单位，需除以 1,000,000 得到结算货币金额。不得向用户展示原始微单位数值。
- 曝光/触达/点击使用千位分隔符格式化。
- CTR 显示为两位小数的百分比。
- 频次显示两位小数。
- 过滤掉曝光为零的行。
- 日预算节奏显示如
$450 / $500 daily (90%)；生命周期预算显示如$2,100 / $5,000 lifetime (42%, 35% of flight elapsed)，其中已流逝百分比计算为elapsed_pct = (today - start_date) / (end_date - start_date) * 100。
适用场景
- 广告投放人员需要快速了解所有活跃 Spotify 广告系列的整体表现。
- 需要下钻到单个广告系列，查看其广告组层面的效果与预算分配。
- 需要监控预算消耗节奏，及时发现超投或投放不足的情况。
限制
- 依赖 Spotify Ads API v3 及插件提供的 API 请求脚本，需正确配置 token、广告账户 ID 等环境变量。
- 仅展示活跃状态的广告系列（并使用 LIFETIME 粒度）。
- 默认单次查询上限为 50 条，超出时需分页。
- 投放节奏标记仅在可获得预算信息时进行。
- 收费、价格、具体平台支持范围等资料未提供。