verify-data:一个端到端的数据验数 Agent Skill


本文介绍了一个面向数据开发团队的端到端数据验证 Agent Skill——verify-data。该技能通过自然语言交互,自动完成从表结构获取、基准表发现、代码逻辑分析、验数 SQL 生成、执行到报告发布的全流程,将传统手工验数从"手写多条 SQL + 人工比对"升级为"一句话触发 + 评审级证据输出"。文章从背景痛点、核心架构与能力、实战场景、设计原则、踩坑经验、当前优势与挑战等方面系统展开,并在最后给出未来演进方向的思考,希望为同样在做数据质量保障和 Agent 工具落地的开发者提供参考。(文章内容基于作者个人技术实践与独立思考,旨在分享经验,仅代表个人观点。)

前置说明

什么是 Agent Skill?

Agent Skill 是一种给 AI Agent 定义的可复用能力包——你可以把它理解为"Agent 的 SOP"。一个 Skill 定义了 Agent 在特定场景下应该做什么、怎么做、有哪些约束和红线。当用户用自然语言触发后,Agent 会按照 Skill 定义的流程自动执行,而不是靠模型临时发挥。

本文介绍的 verify-data 就是这样一个 Skill:它把数据验数的全部流程——从信息收集、SQL 生成、执行到报告产出——编码成了一套可复用、可迭代的 Agent 能力。

技术栈与适用范围

本方案基于以下技术栈实现,读者可以参考其中的设计思路将类似方案适配到自己的环境:

  • 计算引擎:MaxCompute(ODPS),云端大数据计算服务

  • 数据开发平台:DataWorks,提供表结构查询、节点代码获取、数据血缘追溯、SQL 执行等 API 能力

  • 协作平台:钉钉文档(报告发布载体,可替换为其他文档协作平台)

  • Agent 运行时:支持 Skill 定义和自然语言交互的 Agent 框架

核心设计思路(标准化模板、基准表发现策略、降级验数策略等)与具体平台无关,适用于任何有元数据 API 和 SQL 执行能力的大数据环境。

术语速查

术语

含义

ADS

Application Data Store,应用数据层,面向业务场景的宽表/CUBE 表

DWS

Data Warehouse Summary,汇总数据层,按主题域轻度聚合

DWD

Data Warehouse Detail,明细数据层,清洗后的事实明细表

DIM

Dimension,维度表,描述业务实体属性的参照表

CUBE 表

使用 GROUPING SETS / CUBE 语法做多维聚合的宽表

基准表

已验证可信的参照表,用来和研发表做数据对比

验数

数据验证,即通过 SQL 比对确认数据准确性的过程

血缘

Data Lineage,数据表之间的上下游依赖关系


一、背景与痛点

1.1 数据开发的验数困境

在业务数据团队,日常主要在多个项目空间中开发各层数据表(ADS 应用层、DWS 汇总层、DWD 明细层、DIM 维度层)。每张表上线前或迭代后,都需要回答业务方的一个核心问题:

"你这个表/指标的数据,到底准不准?"

这里所说的"验数",是指数据表上线前的人工 review 环节——评审人员需要看到完整的验证证据,确认数据逻辑正确、口径一致、无异常后才允许发布上线。这是数据质量的最后一道防线。

传统的手工验数方式存在几个典型痛点:

覆盖度不够:大多数开发者只跑了总量对比 SQL,漏掉了维度逐项对比、汇总行一致性、CUBE 完整性检查、关联膨胀检测等关键验证项。一张表如果有 5 个维度组合、7 个指标,只跑一条总量对比等于只检查了冰山一角。

基准表选错:很多时候凭感觉选一张"名字差不多"的表做基准,结果两张表口径完全不同(比如基准表按买家维度去重,研发表按访客维度去重),验了半天结论无效。

代码理解偏差:没看懂研发代码的 JOIN 膨胀逻辑,验数 SQL 复刻了同样的 bug。最典型的情况是研发表里有个 LEFT JOIN 会导致行数膨胀,但验数 SQL 也跟着做了同样的 JOIN,结果两边数据"一致",但都是错的。

结论无依据:业务方问"数据准不准",回答"我跑了几条 SQL,应该没问题"。这种主观判断缺乏评审级的证据链,业务方不信,评审也过不去。

沉淀成本高:每张表的验数 SQL 散落各处,换个分区、换个人又要从头来。验数过程没有形成可复用的资产。

1.2 Agent Skill 的机会

2025 年以来,Agent 工具在代码生成、运维自动化等场景已经有了大量落地。但在数据开发领域,尤其是验数这个高频、标准化程度高但痛点明确的场景,还缺乏系统化的 Agent 解决方案。

我们开始思考:能不能做一个 Agent Skill,让数据开发者只需要说一句话,就能自动完成从取数、跑 SQL、写报告到消息推送的全流程?

这就是 verify-data 的出发点。


二、verify-data 是什么

2.1 一句话定义

verify-data 是一个端到端的数据验数 Agent Skill。你只需要给它一张研发表名,它就能自动发现基准表、生成验数 SQL、在计算引擎上执行、分析结果、组装评审级报告并发布到协作文档。整个过程通过自然语言对话完成,不需要手写一行 SQL(除非你想主动干预)。

2.2 核心价值

经过多轮迭代和实战验证,verify-data 在以下方面建立了明显优势:

效率提升:从 2-4 小时到 30 分钟。传统手工验数的流程是:手写 5-6 条 SQL → 逐条执行 → 肉眼比对结果 → 写验数文档 → 发给评审,通常需要 2-4 小时。verify-data 将这一切压缩到 30 分钟以内:一句话触发后,Agent 自动完成取数、跑 SQL、写报告、推送通知,数据开发者只需要"看结论、做决策"。

覆盖度:从冰山一角到全面体检。10 类标准化 SQL 模板确保验证覆盖度,特别是 SQL 9(关联膨胀检测)和 SQL 10(日期维度关联校验),这两项是数据评审最高频退回原因,手工验数时极易忽略。

智能决策:基准表自动发现与降级策略。通过血缘 + 维度/指标精排的两阶段策略自动选基准表,支持多基准表联合覆盖;找不到基准表时有 4 种降级策略兜底,确保任何表都能给出有意义的结论。

证据链:从"我觉得没问题"到评审级报告。产出结构化的评审级报告:7 节标准格式、三档结论判定(PASS/WARNING/FAIL)、完整可执行的 SQL 附录、自动归档到协作文档,可直接交给评审人员。

资产沉淀:验数知识不再散落。每份报告自动归档,SQL 和报告成对保存在本地 verify-sql/ 目录下,19 条踩坑记录沉淀在 lessons-learned.md 中,Agent 不会重复犯已知错误。

风险管控:强制红线防止翻车。4 条不可逾越的红线从机制上防止 Agent 在边缘场景犯错,这些不是"建议"而是"强制",到了关键节点如果不满足条件就不会继续。

2.3 整体架构

下图展示了 verify-data 的整体技术架构,包括用户交互层、核心引擎层、外部依赖和输出产物:

2.4 7-9 步工作流

verify-data 的核心是一个条件触发流程,主流程约 7-9 步,但加上条件触发的子步骤后实际可达 17 步:

Step 1   收集信息 → [Step 1.5 基准表自动发现]Step 2   获取表结构 → [Step 2.5 分区元数据预检]Step 3   获取研发表代码逻辑  → [Step 3.5 Code Diff 结构化分析](S2 强制触发)  → [Step 3.6 基准表适用性预检](用户指定基准表时触发)  → [Step 3.7 维表 CUBE 检测](有 JOIN 维表时自动触发)Step 4   分析维度/指标映射  → [Step 4.5 维度组合匹配](基准表确定后触发)  → Step 4.8 基准表与研发表主要逻辑对照(有基准表时强制)Step 5   生成验数 SQL(10 类模板按需组合)  → [Step 5.5 降级验数策略](无基准表/部分覆盖时触发)Step 6   执行跑数(三批次执行策略)Step 7   组装本地报告Step 8   发布协作文档Step 9   [上游追溯根因分析](结论 FAIL 时触发)
带 [] 的条件步骤不是每次都会执行,而是由对应的触发条件自动决定是否激活。其中 Step 3.6、3.7、4.8 是容易被忽略但非常重要的强制/自动触发步骤。

2.5 5 种验数场景

Agent 会根据用户输入自动识别验数场景:

场景

名称

触发条件

S1

新模型上线

单研发表,无基准表

S2

迭代验数

双表对比(DEV vs PROD)或含迭代关键词

S3

日常监控

"最近数据异常"类描述

S4

业务质疑

"xx 指标对不对"类问题

S5

口径迁移

"口径变了"类变更

其中 S2 迭代验数是最复杂的场景——Agent 会强制触发 Code Diff 分析,扫描 8 类风险信号(数据源变更、JOIN 关系变更、聚合方式变更、过滤条件变更等),并为每个高风险信号生成定量证实 SQL,不仅告诉你"差了多少",还能告诉你"为什么差"。


三、核心能力拆解

3.1 基准表自动发现

这是 verify-data 最核心的能力之一。当用户没有提供基准表名时,Agent 会通过两阶段策略自动发现:

第一阶段:血缘发现候选集

通过数据开发平台的血缘 API,追溯研发表的上游依赖,找出所有可能存在血缘关系的表,构建候选集。

第二阶段:指标/维度精排

对候选集中的每张表计算综合评分:

score = 血缘亲和度 × 0.5 + 维度重合度 × 0.3 + 指标重合度 × 0.2
Top-1 得分 ≥ 0.7 时,直接选为基准表;Top-1 < 0.7 但多张表联合可覆盖全部指标时,触发分路指标对比策略(多基准表联合覆盖);Top-5 最高得分 < 30% 时,进入降级验数策略。

这个设计解决了一个实际问题:一张新的 CUBE 表可能同时依赖用户行为表、转化事件表、交易明细表三张 DWD 表,没有任何一张单独的基准表能覆盖所有指标,但三张表联合就能完整验证。

3.2 10 类验数 SQL 模板

verify-data 不会凭感觉手写 SQL,而是基于 10 类标准化模板按需组合:

编号

模板名称

校验目标

必选

1

总量对比

基准表重算 vs 研发表汇总

是

2

数据质量检测

空值率、零值率、维度合法性

是

3

按维度逐项对比

有基准表且维度可匹配时

条件

4

维表分区校验

有维表 JOIN 时

条件

5

CUBE 完整性检查

有 CUBE/GROUPING SETS 时

条件

6

汇总行一致性

有 'all' 汇总行时

条件

7

逻辑关系校验

指标间有业务逻辑关系时

条件

8

历史趋势对比

有历史数据时

条件

9

关联膨胀检测

有 JOIN 操作时

是

10

日期维度关联校验

有日期维度时

是

其中 SQL 9(关联膨胀检测)和 SQL 10(日期维度关联校验)是我们从实际评审退回经验中总结出来的最高频退回原因。很多表总量对比没问题,但 JOIN 膨胀导致某些维度组合行数翻倍,或者日期维度关联时区错位,这些问题只有专项检测才能发现。

3.3 Code Diff 驱动的风险扫描

在 S2 迭代验数场景中,Agent 会分别获取 DEV 和 PROD 的运行态代码,执行结构化 Diff 分析,扫描以下 8 类风险信号:

每命中一个风险信号,Agent 就会生成对应的定量…

— 以上为试看内容(约 40%),开通会员后阅读全文 —