用途
measurement-debug 是一个用于诊断 Spotify Ads 测量实现问题的技能，覆盖 Spotify Ads Pixel、Conversions API（CAPI）和数据集（dataset）三种测量路径。当事件缺失、过期、重复、数量异常偏高或偏低时，它帮助使用者在建议任何变更之前，先找到失败的层级。技能明确要求：诊断前先阅读 troubleshooting.md。
主要能力
分诊信息采集
技能会引导采集以下信息：预期事件、预期量级、首次/最后已知正常时间、时区、受影响环境；问题涉及 Pixel、CAPI 还是两者，以及是直接代码、Web GTM、Server GTM 还是其他方负责；business、dataset、integration、connection、ad-account 等 ID；问题属于接收、去重、共享/选择还是归因报告；以及在可用时提供经脱敏的失败请求/响应和 trace ID。技能明确禁止索取 CAPI token、原始邮箱/电话、cookie、设备 ID、IP 地址或生产 payload，改为索取脱敏字段名和错误元数据。
只读审计
1. 解析拓扑
使用如下端点：
api GET "businesses/<business_id>/datasets"
api GET "businesses/<business_id>/datasets/<dataset_id>"
api GET "businesses/<business_id>/capi/<capi_connection_id>"
api GET "businesses/<business_id>/ad_accounts/<ad_account_id>/datasets"
技能说明：GET datasets 端点不接受 limit 或 offset 参数；要发现 Pixel，应检查每个 dataset 响应中的 pixel 字段，而不是调用独立的 pixels 端点。只有在事件确实需要 token 清单时，才调用 GET businesses/<business_id>/capi/<capi_connection_id>/tokens，且该响应包含活跃 token 值，必须将整个原始响应视为机密，绝不在命令结果或记录中展示，最终审计中只暴露脱敏后的 token ID/数量。
需要核实：预期 integration 是否在预期 dataset 中；dataset 是否共享给目标 ad account；每个 integration 的 dataset_id 字段是否指向正确的 dataset（null 值意味着事件被摄取但未被路由）；Pixel 域名和 CAPI connection ID 是否匹配预期环境/business；当认证在范围内时，token ID 是否存在于同一 CAPI connection 上（绝不显示 token 值）；dataset 的 is_receiving_events、is_receiving_lead_events 等标志是否符合症状。
2. 检查事件接收
api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=HOURLY"
api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=DAILY"
api GET "businesses/<business_id>/datasets/<dataset_id>/diagnostics?granularities=HOURLY&datasource_ids=<datasource_id>"
对比每个数据源的事件名、计数、时间戳和 last_activity_ms，显式转换时间戳并说明时区。近期事件用小时数据，趋势对比用天数据。技能提醒：接收诊断只能回答“Spotify 是否收到事件”，不能证明触发正确性、标识符、去重、campaign 数据源选择或归因。
3. 隔离层级
技能提供症状对照表，例如：无数据源收到事件 → 实现/网络；Pixel 缺失而 CAPI 存在 → 浏览器；CAPI 缺失而 Pixel 存在 → 服务器；两者都存在但总量偏高 → 去重；诊断存在但 campaign 指标缺失 → 选择/归因；错误站点/账户收到数据 → 拓扑/配置；事件突然停止 → 部署/凭证；integration 在 dataset 中但 dataset_id 为 null → 数据集路由（事件被摄取但未路由，解决办法是移除该 integration 并重新添加到正确关联的 dataset）。
4. 检查实现证据
若用户提供公开页面、浏览器访问、GTM 导出或脱敏 CAPI 示例，可进行只读检查：Pixel 方面对比 pixel key 与基础/事件代码，搜索直接安装中的 spdt，检查 console/network/CSP，验证事件只在预期动作触发；不要仅因源码 HTML 缺少 spdt 就断定 Pixel 不存在（标签管理器可在运行时注入）；确认站点未同时使用直接安装和 GTM 安装；验证重定向保留 Spotify 的 spclid 查询参数；Web GTM 用于 Pixel，CAPI GTM 需要 server container。CAPI 方面校验 envelope、事件枚举、唯一稳定的 event ID、ISO 8601 时间、至少一个标识符、SHA-256 规范化、可选 source URL/action source 和 revenue 字段。绝不在发现中暴露机密或个人数据。
使用方式
技能以只读审计开始。设置环境：
PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}"
api() { "$PLUGIN_ROOT/scripts/api-request.sh" measurement-debug "$@"; }
在首次调用 Ads API v3 之前，需阅读并遵循 $PLUGIN_ROOT/skills/api-reference/references/live-openapi.md。测量路径使用 business_id，缺失时用 GET businesses 发现。
涉及变更的测试和修复默认先给出修复计划，并在以下操作前立即请求明确确认：提交任何 CAPI 事件（包括测试事件）、创建/撤销 token、更改 Pixel/CAPI/dataset 元数据、共享/取消共享 dataset、在 dataset 间移动 integration。测试事件会改变测量数据，优先在非生产 integration 中重放合法的已知事件并使用稳定的唯一 event_id，并加以标注/记录；绝不在超时或 5xx 后盲目重放生产 POST。对于源代码或 GTM 变更，提供最小隔离变更和验收测试，不声称 Ads API 可以部署网站或 GTM 代码。
归因边界
若接收健康但报告异常：核实 dataset 是否共享给相关 campaign/ad set 并被其选择；核实报告日期范围、实体和转化字段；区分总接收事件活动与归因转化；考虑归因窗口和隐私阈值；将报告提取路由到 report 技能。不要为了强制归因数字匹配内部分析而“修复”健康的摄取。
事故报告
返回内容包含：症状和受影响范围；一行拓扑图 business → dataset → source(s) → ad account；含检查项、结果、时间戳/时区和置信度的证据表；最可能的失败层及备选；按负责方划分的精确修复方案；安全验证步骤和等待时间；用于升级的脱敏 trace ID/错误。分别标注事实、推断和未验证假设。若问题未解决，建议联系 Spotify Ads API 支持，并附 client ID、endpoint、脱敏请求/响应、时间戳和 sp_trace_id。
限制与防护
从只读开始；在新事件活动后至少等待 20 分钟再诊断空的 Ads Manager 诊断；绝不请求、回显或存储 CAPI 机密或个人标识；绝不自动重试 POST、PATCH 或 DELETE；遇到 4xx 时保留脱敏错误并停止，POST 失败有歧义时先检查接收/资源状态再重试。