用途:运行客户受众关系阶梯报告(staircase audience-relationship report)。当用户要求运行 staircase 报告、为某站点运行报告,或在支持斜杠命令的环境中调用时使用。
主要能力与用法:
- 站点过滤:可提供可选 site ID(如 your-site.com)。为空表示在配置 bucket 内的全部站点运行;非空则传入 --site-id 仅过滤该站点。
- 输出约定:只输出报告内容(生成的报告 markdown 正文),末尾附一行 file:// 形式的 HTML 链接。无前言、无后记、无解释,不重述报告结论。报告顶部的 Recommendations 段即为分析本身。聊天中直接请求“run the staircase report”时同样适用:逐字渲染 markdown,再附 file:// HTML 链接。HTML 版可包含比聊天 markdown 更多细节,这种不对称是有意为之。
- 数据准备:先按 update-cache 技能增量拉取数据,然后探测 catalog 中可用的最早/最晚日期,将可用区间等分为两个窗口。优先 30/30;数据不足时回退为 N/N。若窗口小于 30 天,生成一行覆盖度说明并通过 --data-coverage-note 写入报告。
- 配置读取:读取 bucket.json(bucket、profile、cache_dir,以及可选的 employee_filter、employee_filter_checked、join_id_key)。若文件缺失,应提示先运行初始化流程并停止。
- 员工流量检测:首次缓存有数据时静默运行 identify-employees 脚本,检测结果写入 bucket.json;匹配时通过 employee_filter 参数排除对应事件并在报告顶部加一行说明。
- 运行脚本:调用 staircase.py,传入 --current、--prior 窗口,以及按条件传入 --site-id、--internal-domains、--network-label/--network-sources、--employee-filter-key/--employee-filter-value、--join-id-key、--output-md、--output-html。不传 --events-dir 和 --cache-root。
限制:
- 报告为管道角色而非分析者,禁止添加摘要、评论或叙述。
- 若 bucket.json 缺失,不得猜测取值。
- 若 lake 中无对应 DPL 事件,以一行简短错误提示并停止。
- 未提供具体收费、价格、平台支持范围等信息。