| name | sql-validate-and-export |
| version | 2.0.0 |
| description | SQL 分段验证、自我修复、结果导出与智能分析。流程：解析SQL → Dataphin MCP 验证元数据 → 自动修复 → 分段执行验证 → 导出 CSV → 智能分析（漏斗解读、异常识别、预判用户问题）。适用场景："跑一下这个SQL"、"验证这个查询"、"帮我执行并导出"、"分析一下结果"等。 |
SQL 分段验证、结果导出与智能分析
核心理念
SQL 查询在复杂环境中容易出错（字段名错误、表引用错误、JOIN 膨胀等）。本 skill 通过分段验证、逐步合并的方式，确保最终结果可靠，并自动导出为 CSV 文件。最后，从数据和用户角度进行智能分析，预判用户可能追问的问题并提前给出答案。
这个流程模拟了资深数据分析师的工作习惯：先摸清数据，再逐步拼装，最后主动讲故事和提前回答追问——而不是把一张表甩给用户让他们自己看。
执行流程
Phase 1: 解析与元数据验证
- 读取 SQL 文件，解析出涉及的所有表和字段
- 调用 Dataphin MCP 验证元数据：
mcp__sh_dp_mcp__get_dp_table_meta 获取每张表的字段列表和类型- 逐一核对 SQL 中引用的字段是否存在于正确的表中
- 检查字段类型是否与使用方式匹配（如 string 类型用于数值计算需注意隐式转换）
- 记录发现的问题，分类为：
- 致命错误：字段不存在、表名错误 → 必须修复
- 警告：类型隐式转换、可能的 NULL 值 → 提示用户
Phase 2: 自动修复
如果发现错误，在用户确认后自动修复：
- 字段归属错误 → 修正表别名（如
t2.field → t1.field）
- 子查询缺字段 → 补充 SELECT 列表
- 子查询多余字段 → 移除无用字段
- 拼写错误 → 修正字段名
- GROUP BY / ORDER BY 与 SELECT 不一致 → 同步修正
修复后重新验证，确保所有引用正确。
Phase 3: 分段执行与验证
按照从简单到复杂的顺序执行，每步验证结果合理性：
Step 1: 单表验证
- 对每张基础表单独执行简单聚合查询（加 LIMIT）
- 检查：数据量级是否合理、关键字段值分布、是否有大量 NULL
Step 2: 两表 JOIN 验证
- 按 SQL 中的 JOIN 顺序，逐步添加表
- 检查：JOIN 后记录数是否膨胀、关键指标是否与单表结果可对账
Step 3: 完整查询执行
- 执行完整 SQL（保留 LIMIT 以防数据量过大）
- 交叉验证：各维度汇总是否等于上一步的总计
Phase 4: 结果导出
验证通过后：
- 执行不带 LIMIT 的完整查询（如果数据量在 10000 条以内）
- 将结果解析并写入 CSV 文件
- 文件命名规则：
{SQL文件名}_{YYYYMMDD_HHMM}.csv
- 例如：
贷前指标_20260407_1430.csv
- 如果 SQL 不是来自文件，使用用户提供的名称或查询主题
Phase 5: 智能分析与预判追问
导出完成后，从数据视角和用户视角两个维度自动生成分析：
5.1 数据视角分析
基于查询结果自动识别：
- 漏斗瓶颈：哪一步筛选过滤掉最多数据，占比多少
- 异常波动：日间/维度间的异常偏差（>2σ或环比>20%）
- 分支贡献：OR/UNION 等多分支逻辑中，各分支的独立贡献和重叠率
- 趋势判断：时间序列数据的趋势方向和稳定性
- 边界风险：接近阈值的条件（如 <=30 的条件中大量数据集中在 25-30）
5.2 用户视角预判追问
根据查询的业务语义，提前回答用户最可能追问的 3-5 个问题：
| 问题类型 | 示例 | 生成方法 |
|---|
| 量级合理性 | "这个数跟预期比是多还是少？" | 对比同类历史查询或全表占比 |
| 条件敏感度 | "如果把阈值从 30 改成 60，人数会变多少？" | 从单表验证的分布数据中估算 |
| 分支差异 | "A 分支和 B 分支的用户重叠多少？" | 从最终合并逻辑中计算交集 |
| 时间趋势 | "这个数是在涨还是在跌？" | 对时间维度做趋势判断 |
| 下钻需求 | "能不能按渠道/产品拆分看？" | 识别 SQL 中未使用但可用的维度字段 |
5.3 输出格式
分析结果以结构化方式输出：
### 关键发现
- [发现1]：一句话结论 + 数据支撑
- [发现2]：...
### 预判追问 Q&A
**Q1: [用户可能问的问题]**
A: [基于数据的回答]
**Q2: ...**
A: ...
查询提交与轮询
使用 Dataphin MCP 异步查询：
提交: mcp__sh_dp_mcp__submit_dp_query → 获取 taskId
轮询: mcp__sh_dp_mcp__get_dp_query_status → 间隔 10s+
- 多个独立查询（如单表验证）应并行提交，提高效率
- 有依赖关系的查询（如需要上一步结果判断后再决定下一步）串行执行
结果合理性检查清单
每步执行后，自动检查以下项目：
| 检查项 | 方法 | 异常标准 |
|---|
| 记录数膨胀 | JOIN 前后对比 | JOIN 后 > 单表记录数 × 1.05 |
| NULL 占比 | count 对比 | 关键维度 NULL > 10% |
| 数值范围 | min/max/avg | 超出业务常识（如金额为负、比率 >100%） |
| 维度覆盖 | distinct count | 缺少预期的维度值 |
| 汇总可对账 | 分维度 sum vs 总计 | 差异 > 0.01% |
CSV 导出格式
- 编码：UTF-8 with BOM（确保 Excel 打开中文不乱码）
- 分隔符：逗号
- 第一行为列名（使用 SQL 中的 AS 别名）
- 数值保留原始精度，不做格式化
- 导出路径：与 SQL 文件同目录，或用户指定目录
异常处理
- 查询超时：使用
mcp__sh_dp_mcp__kill_dp_query 终止，缩小日期范围或加更多过滤条件后重试
- 权限不足：使用
mcp__sh_dp_mcp__apply_dp_table_permission 申请权限
- 表不存在：使用
mcp__sh_dp_mcp__get_dp_tables_by_path 搜索正确路径
- 结果超过 10000 条：提示用户是否分批导出或增加聚合粒度
输出给用户的信息
每个 Phase 完成后，输出简洁的中间结果摘要：
- Phase 1: 表结构验证结果（通过/发现N个问题）
- Phase 2: 修复内容清单（如有）
- Phase 3: 每步的关键数据指标（记录数、核心指标值、合理性判断）
- Phase 4: CSV 文件路径和数据概览（行数、列数、关键统计量）
- Phase 5: 关键发现（漏斗瓶颈、异常波动）+ 预判追问 Q&A（3-5 个）
