verify-data：一个端到端的数据验数 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 应用层、DWS 汇总层、DWD 明细层、DIM 维度层）。每张表上线前或迭代后，都需要回答业务方的一个核心问题：

"你这个表/指标的数据，到底准不准？"

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

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

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

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

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

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

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

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

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

这就是 verify-data 的出发点。

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

经过多轮迭代和实战验证，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 在边缘场景犯错，这些不是"建议"而是"强制"，到了关键节点如果不满足条件就不会继续。

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

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 是容易被忽略但非常重要的强制/自动触发步骤。

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

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

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

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

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

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

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

score = 血缘亲和度 × 0.5 + 维度重合度 × 0.3 + 指标重合度 × 0.2

Top-1 得分 ≥ 0.7 时，直接选为基准表；Top-1 < 0.7 但多张表联合可覆盖全部指标时，触发分路指标对比策略（多基准表联合覆盖）；Top-5 最高得分 < 30% 时，进入降级验数策略。

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

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

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

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

每命中一个风险信号，Agent 就会生成对应的定量证实 SQL，用数据来证明或证伪该风险的实际影响。这是"知道差了多少"到"知道为什么差"的关键跨越。

无基准表或者部分覆盖维度和指标时，verify-data 不会放弃验证，而是自动选择 4 种降级策略之一：

降级策略的特殊耦合判定：

强制卡点：除了执行 D 类（一致性检查）SQL，另外必须对原代码进行风险审查，并针对 Top-3 风险点生成定量证实 V 类 SQL（逻辑性校验）。审查时需逐项扫描以下 8 类风险信号，每类都必须在代码中显式扫一遍：

这是因为如果 DWD 重算 SQL 直接复制了 ADS 代码逻辑，只能证明"执行一致"，无法发现 ADS 本身的逻辑错误。这一部分使用的 AI 代码审查（Code Review）能力，是基于强规则加上历史验数的错误记录总结。

分区预检：在跑 SQL 之前，Agent 会通过元数据 API（秒级完成）确认目标分区是否存在、实例状态是否成功。避免白跑几十分钟的 SQL 后发现分区还没产出。

这个设计解决了大数据计算引擎执行的一个实际问题：含 SET 语句的 SQL 如果并行执行会互相覆盖会话状态，必须串行；而纯 SELECT 可以并行以节省时间。

在 verify-data 的 17 步流程中，以下三个步骤常被忽略，但它们对验数质量至关重要：

Step 3.6 基准表适用性预检（用户指定基准表时强制触发）

当用户主动指定基准表时，Agent 不会直接信任，而是先计算维度相似性：similarity = 重合维度数 / max(研发表维度数, 基准表维度数)。若相似性 < 50% 且基准表多余维度无 CUBE 聚合，会主动建议降级策略，避免"选错基准表导致结论无效"。

Step 3.7 维表 CUBE 检测（代码中有 JOIN 维表时自动触发）

检测维表是否存在一对多关系（CUBE 聚合），这是关联膨胀的源头。如果维表有 CUBE，研发表指标会按维度拆分重复计算，不能直接跟汇总表对比总量。检测方法：对维表按关联键 GROUP BY，HAVING COUNT(1) > 1。

Step 4.8 基准表与研发表主要逻辑对照（有基准表时强制）

在生成验数 SQL 前，强制对比研发表和基准表在数据来源、JOIN 维表、CUBE 状态、过滤条件、聚合函数、指标口径上的差异，产出"可直接对比的指标"和"不可直接对比的指标"清单。这是防止"口径不同却强行对比"的最后一道防线。

背景：业务新增了一种活动类型，需要和原有类型合并到一张 CUBE 表里，按 type × label × flag 三维度做 GROUPING SETS 聚合。明天上线，今天必须验数。

触发方式：

帮我验数 my_project.ads_activity_cube_1d，分区 20260419

注：项目空间.表名 是 MaxCompute 的命名格式，类似于 Hive 的 database.table。下同。

Agent 决策树：

1. 识别为 S1 场景（单表 + 无 DEV/PROD 关键词）

2. 自动发现基准表：沿血缘追溯出 3 张候选 CUBE 表，评分分别为 0.56、0.56、0.59

3. 单表得分都 < 0.7，但联合可覆盖全部 7 个指标 → 选择分路指标对比策略

4. 维度匹配：研发表有新增维度值，基准表只有旧值 → 交集走基准对比，新增部分走降级

5. 生成 9 条基准对比 SQL + 5 条降级 SQL

6. 跑数 → 组装报告 → 推送通知

结论：PASS。基准表对比部分 7 指标 × 32 维度组合全部精确一致；降级部分 CUBE 层级自洽、DWD 上游比对 100% 一致。

背景：开发者在 DEV 改了某张表的代码（加了新指标、改了某个 JOIN 条件），跑了一天发现 DEV 和 PROD 数据有差异。需要区分预期内差异和非预期差异。

触发方式：

对比 my_project_dev.ads_campaign_1d 和 my_project.ads_campaign_1d

关键输出：

• 变更摘要：新增 2 个字段、修改 1 个 JOIN、修改 1 个过滤条件

• 高风险信号 1 个（JOIN 类型变更可能导致膨胀）

• V1-V6 定量证实 SQL，逐个验证每个变更的实际影响

• 预期内差异清单（如新增字段必然导致行数变化）

• 非预期差异清单（这是评审关注的重点）

背景：业务想看"某营销活动后 7 天的阅读/成交转化"，这是一张全新分析口径的 CUBE 表，线上没有任何表能直接对。

Agent 行为：

1. 尝试自动发现基准表 → Top-5 评分均 < 0.3 → 触发降级

2. 自动选择策略 [1]（CUBE 表）：CUBE 层级自洽性校验 + DWD 上游比对 + 数据质量校验

3. 强制启动代码逻辑审查（降级前置环节）：8 类风险信号扫描

4. 针对膨胀维表 JOIN 生成 V1 定量证实 SQL

结论：PASS。CUBE 层级自洽性验证 3 个核心指标差异均 < 0.01%；DWD 重算与研发表 100% 一致。

背景：新建了一张维表 dim_xxx_tag（业务标签维表），维表没有传统意义的"指标"，怎么验？

Agent 行为：自动识别为维表（从 dim_ 前缀和无指标列特征），走策略 [3] 静态逻辑校验：

• 主键唯一性（主键字段不能重复）

• 关键字段 NULL 率（标签字段不能为 NULL）

• 业务规则一致性（如 actual_ratio = base_ratio * 0.9）

• 标签分布合理性

• 数据完整性

结论：WARNING（有条件通过）。静态校验全过，但动态数据验证因源表权限不足受阻。建议申请权限后复验。

在 verify-data 的设计中，有 4 条不可逾越的红线：

1. 禁止跳过 SQL 生成直接手写跑数：所有验数 SQL 必须从模板生成，确保覆盖度和可追溯性

2. 禁止靠字段名猜映射：必须读运行态代码 + 查 schema，凭经验猜字段是最常见的验数错误来源

3. 禁止降级策略 [1] 仅跑 D 类 SQL 就出报告：必须追加代码审查和 V 类定量证实，否则只能自证执行一致

4. 必须对所有 JOIN 做膨胀率验证、对所有日期维度做日期关联校验：这是评审最高频退回原因

结论判定的完整决策流程如下：

降级策略的特殊耦合判定：

高频退回判定速查：

GROUPING SETS 生成的汇总行中，某些维度的值为 NULL 或 'all'，某些指标为 NULL 是正常行为。曾经有人误判为"数据缺失"，反复排查后才发现是 GROUPING SETS 的标准行为。verify-data 在报告生成时会专门标注这一点，避免误判。

浮点类型金额字段在多次累加后会产生 ~10^-10 级的精度差异。verify-data 内置了浮点精度容忍度判定（差异 < 1e-6 视为实质为 0），避免在无关紧要的精度上浪费时间。

如果降级策略中 DWD 重算 SQL 直接复制了 ADS 代码的 JOIN 和聚合逻辑，即使结果 100% 一致，也只能证明"我写的 SQL 和我写的 ADS 代码执行结果一致"，无法证明"ADS 代码本身是对的"。

典型案例：DWD 重算与 ADS 汇总行四个指标完全一致（差异 < 1e-11），初判 PASS。但追问"代码本身有没有错？"后审代码发现两个真 bug：

• 某退款流程的 refund_stage > '1' 在当前分区命中 0 条（该分区全部 refund_stage='1'）——退款路径事实失效，但 DWD 重算同样跳过这些行，两侧照样"一致"

• 某计数指标用 trade_id IS NOT NULL 作判据——当前 DWD 数据质量好所以无损，但一旦脏数据出现就会产生"幽灵金额"（统计值凭空多出来）

这就是为什么降级策略 [1] 强制要求代码审查 + 独立构造 V 类证实 SQL——V 类 SQL 必须从 DWD 源头独立构造。

verify-data 不是独立工作的，它采用模块化架构，依赖以下能力模块的协同：

这种设计的好处是：核心验数逻辑与具体的平台实现解耦。如果你的环境使用了不同的计算引擎和数据开发平台，只需要替换"表结构与元数据服务"模块的实现，核心验数流程无需改动。

verify-data 的主文件是流程路由骨架，每步的执行细节都在 references/ 目录的 14 个文档中：

• 场景识别规则、基准表自动发现策略、分区预检逻辑

• 代码分析清单、Code Diff 分析规范、维度匹配决策树

• 10 类 SQL 模板、4 种降级策略、执行策略与硬约束

• 报告模板、文档发布规范、根因分析流程、踩坑记录

这种设计让 Agent 在执行时能够按需加载细节，保持主流程清晰的同时不丢失边缘场景的处理能力。

verify-data 是完整数据链路中的一环：

在实际推广中，verify-data 仍存在一些待解决的挑战：

执行效率与交互体验：完整 9 步流程通常耗时 15-30 分钟，且中间多个节点需要用户确认（基准表选择、降级策略、发布确认等），对高频使用的开发者来说交互成本偏高。

权限与环境依赖：验数常涉及多个项目空间（dev / prod / cdm 等），跨项目 SELECT 权限不齐全会导致流程中断；同时 verify-data 依赖完整的元数据 + SQL 执行 + 文档发布链路，任一环节故障都会阻塞全流程。

降级结论的信任成本：当走降级策略时，WARNING（有条件通过）的结论需要向评审人额外解释可信度，增加了沟通成本。

新用户上手门槛：首次配置涉及多个模块安装和参数配置，对不熟悉 Agent 生态的开发者有一定门槛。

verify-data 从一个"能不能让 Agent 帮我验数"的想法，发展到现在覆盖 5 类场景、10 类 SQL 模板、14 个参考文档、19 条踩坑记录的生产级工具，核心经验可以归纳为以下几点：

1. 从最高频场景开始：不要试图一开始就覆盖所有场景。我们先做了 S1 新表上线和 S2 迭代对比，这两个场景占了 80% 的验数需求。先让 80% 的需求跑通，再逐步补齐长尾。

2. 标准化比智能化更重要：验数最关键的是覆盖度和可重复性，10 类标准化模板比"让 AI 自由发挥"可靠得多。AI 的能力放在理解代码逻辑、选择模板组合和解读结果上，而不是临时发挥写 SQL。

3. 踩坑记录是核心资产：lessons-learned.md 里记录的 19 条实战经验，每一条都是真实踩过的坑。没有这些，Agent 就会重复犯同样的错误。每次生产事故都是一次 Skill 升级的契机。

4. 红线要硬：关键红线在流程层面做了约束，不是"建议"而是"强制"。没有红线的 Agent 工具很容易在边缘场景翻车——尤其是在降级场景和 Code Diff 场景，没有强制约束的 Agent 会倾向于走捷径。

5. 用户体验和工程可靠性并重：优势再大，如果用户等 30 分钟还要反复确认，推广就会受阻。接下来的优化方向（异步执行、一键到底、权限预检）本质上都是在可靠性的基础上提升体验。

我们相信，数据验证这个场景天然适合 Agent 化——它高频、标准化程度高、涉及多系统协同、结果需要结构化沉淀。verify-data 的实践证明了这条路是可行的，也希望这些经验能给在做类似工具的开发者一些参考。

基于实践经验和团队反馈，我们对 verify-data 的下一阶段演进有以下几个方向的思考：

当前验数流程的最大摩擦在于执行耗时和中间交互。我们的目标是让验数变成一件"无感"的事情：用户触发后即可离开，Agent 全程异步执行，完成后通过消息通知主动推送结论。

具体来说，计划引入异步执行 + 主动通知机制，让 SQL 提交后用户不再需要等待；同时提供"一键到底"的静默模式，对高频常规场景（如每日分区切换、回归验数）跳过所有确认环节，只在异常时打断。此外，通过历史缓存复用表结构和基准表选择结果，将同表复验的耗时大幅缩短。最终目标是让验数从"主动操作"退化为"被动通知"——用户只需要看结论，不需要参与过程。

verify-data 目前是一个独立的 Agent Skill，与数据研发流程是松耦合关系。但验数的最大价值不是"事后补做"，而是"嵌入流程、自动拦截"。

我们正在探索与数据开发平台发布流水线的深度集成：表推到生产环境前自动触发验数，验数不通过则自动阻断发布。同时支持多表批量验数，适配大版本发布前的回归场景。在权限层面，计划在流程早期就完成全链路权限预检，并生成一键申请引导，避免"跑到一半才发现没权限"的问题。长远来看，verify-data 应该像单元测试之于代码一样，成为数据上线的标准质量门禁。

当前 verify-data 的核心能力是"按模板执行验证并输出结论"，但在"理解为什么数据会这样"方面还有很大提升空间。

未来的智能进化方向包括：增强根因定位能力，从当前的"上游追溯"升级为"全链路根因定位"，结合代码变更历史和数据血缘，做到一键定位到具体代码行；引入降级结论的可信度量化评分，基于验证覆盖维度和 V 类证实 SQL 通过率综合计算，让评审人员无需理解策略细节也能直观判断结论可靠程度；探索增量验数模式，对日常监控场景只验证变化数据而非全量重跑。最终愿景是让 verify-data 不仅能回答"数据准不准"，还能回答"为什么不准"和"怎么修"。

1. 帮我验数 <表名>2. 帮我验数 <表名>，分区 <YYYYMMDD>3. 帮我验数 <表名>，基准表是 <基准表名>4. 对比 <DEV 表> 和 <PROD 表>5. 对比 <DEV 表> 和 <PROD 表>，DEV 改了 <变更描述>6. 帮我验数 <表名>，这是新模型，应该没有基准表7. 帮我验数 <维表名>，业务规则：<具体规则>8. <表名> 已经修复了 <问题>，帮我重新验一下9. 帮我生成 <表名> 的验数 SQL，不要执行10. 帮我验数 <表名>，请展示基准表自动发现的评分明细