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 执行能力的大数据环境。
术语速查
一、背景与痛点
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 会根据用户输入自动识别验数场景:
其中 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 类标准化模板按需组合:
其中 SQL 9(关联膨胀检测)和 SQL 10(日期维度关联校验)是我们从实际评审退回经验中总结出来的最高频退回原因。很多表总量对比没问题,但 JOIN 膨胀导致某些维度组合行数翻倍,或者日期维度关联时区错位,这些问题只有专项检测才能发现。
3.3 Code Diff 驱动的风险扫描
在 S2 迭代验数场景中,Agent 会分别获取 DEV 和 PROD 的运行态代码,执行结构化 Diff 分析,扫描以下 8 类风险信号:
每命中一个风险信号,Agent 就会生成对应的定量…