用途
serve-data 是数据工程生命周期的第 5 阶段,也是终端阶段。它运行一个简短、分支式访谈,将计划中的(或已有但未记录的)面向消费者的服务端点转化为使用方项目中的 Serving Surface markdown 文件,路径为 docs/serving-surfaces/<surface>.md。该阶段使数据血缘链闭环回第 0 阶段(Stage 0)的初始决策。
Serving Surface 是数据团队对单个面向消费者服务端点的受版本控制模型,记录:它服务的决策、读取的上游模型、surface 类型、消费者与指定负责人、新鲜度合约、访问姿态、敏感性以及退役触发条件。它是 surface 的运维和合约模型,不是服务工具配置,也不是项目管理计划——它不包含 LookML、Tableau 工作簿 XML、reverse-ETL 同步 JSON、API 处理代码、特征存储定义或 dbt exposure。实现这些承诺的代码位于使用方的 BI/服务仓库中,不在本技能范围内;本技能不输出任何服务代码。
主要能力
- 执行 8 轮有序访谈,每轮一个问题,将计划或既有端点转化为 Serving Surface 文件。
- 强制双重 Serving kill-switch:(1) 链条半部分——至少指定一个上游 Model Plan 在 related_model_plans 中;(2) 闭环半部分——至少指定一个它服务的 DGQ 在 serves_dgqs 中。
- 执行 freshness-honesty 测试、access-model-honesty 测试(convention 是诚实的可接受答案,不能将 role-based 写为愿望式声明)、sensitivity-step-down 测试和 "这是否真是 ADR 时刻" 路由测试。
- 检测并拒绝无决策服务的 surface(即"无人使用的仪表盘"),将其写为 status: rejected。
- 支持可恢复性:扫描现有 Serving Surface 文件,允许继续草稿、新建或列出状态。
- 在访谈前探索项目内已有资产(Model Plans、DGQs、Storage Plans、Ingestion Plans、Source Profiles、ADRs、相邻 Serving Surfaces、CONTEXT.md 术语表)。
使用方式
运行 /serve-data 触发技能。流程如下:
- 可恢复性检查:扫描 docs/serving-surfaces/。若已有文件,询问用户是继续草稿/需跟进、新建还是列出。若目录不存在,首次写入时才创建。
- 按顺序执行 8 轮(Turn 1 至 Turn 8),每轮一个问题(除非明确为合并轮)。
- Turn 1(链条 kill-switch):命名上游 Model Plan。若无法指定或上游模型已被拒绝/取代,触发链条 kill-switch,建议先运行 /model-data。若读取语义层/指标存储/BI 抽取,仍需追溯到根 Model Plan。
- Turn 2(闭环 kill-switch,最响亮的一轮):命名服务的 DGQ 和行动变化。若无决策或仅为"提供可见性",触发闭环 kill-switch,写入 status: rejected 并记录无决策理由。
- 后续轮次覆盖:surface 类型、消费者与负责人、新鲜度合约、访问姿态、敏感性、退役触发条件和 ADR 路由。
- 写入前阅读合约 references/serving-surface.md(frontmatter 字段、枚举域、正文章节顺序);linter 位于 scripts/lint-serving-surface.sh,强制执行合约。
典型每个 surface 进行 7–10 轮实质性交流。输出为每个 surface 一份 markdown 文件。若一次服务产生一组 surface(如一个仪表盘加上实现同一指标的 reverse-ETL 同步),先完整钻取一个,其余标记为 status: draft 排队。
交叉规则:先推荐再询问(为每轮问题先提出合理建议,再让用户接受/拒绝/细化),但不得为两个 kill-switch 答案编造推荐;先探索再询问(查找 docs/model-plans/、docs/requirements/、docs/adr/、docs/serving-surfaces/、CONTEXT.md 等已有信息)。
适用场景
- 数据团队需要为面向消费者的服务端点建立受版本控制的合约模型。
- 需要确保每个服务端点都能追溯到受治理的上游模型,避免从原始/暂存层重复计算业务逻辑(如收入定义分叉)。
- 需要确保每个服务端点服务于有名称的决策和行动变化,避免构建无人使用的仪表盘。
- 需要诚实地记录访问姿态(包括 convention 模式)和新鲜度合约。
- 需要为退役或取代服务端点建立持久记录。
限制
- 不输出任何服务代码:不包含 LookML、Tableau XML、Hightouch 同步 JSON、API 处理代码、特征存储定义或 dbt exposure。
- 不通过工具推断:不解析 dbt exposures、不进行 Looker/Tableau/Mode API 内省、不查询 reverse-ETL 平台、不查找仪表盘浏览量或使用分析。
- 将 status: accepted、status: rejected 和 status: superseded-by-<path> 文件视为不可变,不提供编辑。取代旧 surface 需写入新文件并手动更新旧文件状态。
- 若上游无命名 Model Plan,拒绝写入 surface 并建议运行 /model-data。
- 若 surface 不服务任何决策,拒绝接受,写为 rejected。
- 不得为两个 kill-switch 答案编造推荐或替代用户发明上游 Model Plan 路径或决策。
- 不得将 access_model 抬高为 role-based 仅因其听起来受治理。
其他具体细节(如各轮完整提示语、frontmatter 字段完整列表、linter 诊断输出等)在给定资料中未完全展开,暂未提供。