Smart Data Query

Overview

将“自然语言提问 → 数据理解 → 查询执行 → 结果解释 → 图表输出”串成一个完整闭环。

核心原则：

• 先澄清问题，再生成查询
• 先理解数据，再输出结论
• 先验证结果，再展示图表

这个 Skill 不应把“问数”理解成单次 SQL 生成，而应理解为一套受控分析流程。

When to Use

在这些场景下使用：

• 用户说“帮我查一下”“看下趋势”“对比一下”“做个图”
• 数据源是 MySQL、Excel、CSV
• 用户提问里包含业务口径、时间范围、部门、区域、产品等自然语言条件
• 用户不仅要数据，还要摘要说明、指标解释或图表

不要在这些场景直接使用：

• 用户没有提供任何数据源，也无法访问数据
• 用户的问题是纯开放讨论，不依赖数据验证
• 用户要求高风险写库操作，如删除、批量更新、改表结构

Required Inputs

执行前至少确认以下信息：

• 数据源类型：mysql / excel / csv
• 数据源位置或连接方式
• 用户问题原文
• 可用的表结构说明或字段说明

如果缺少表结构、字段口径、业务术语，优先读取：

• references/db-schema.md
• references/term-glossary.md

Workflow

1. Question Normalize

不要直接把用户原话扔给 SQL 生成器，先转换成“分析任务说明”。

需要提取的内容：

• 分析意图：统计 / 对比 / 趋势 / 排名 / 占比 / 明细
• 指标：销售额、订单量、费用、出勤率等
• 维度：时间、部门、地区、产品、人员
• 过滤条件：时间范围、状态、渠道、是否剔除异常值
• 输出要求：表格 / 条形图 / 折线图 / 饼图 / 摘要

如果用户问题存在歧义，优先提一个澄清问题，不要猜。

示例：

用户原问：
帮我看看最近华东销售怎么样

应先规范化为：

• 指标：销售额、订单量、客单价？需确认
• 区域：华东
• 时间：最近 = 近 7 天 / 30 天 / 本月？需确认
• 输出：趋势还是汇总？需确认

2. Data Grounding

在生成 SQL 或分析代码前，先做字段和口径对齐。

必须完成：

• 找到对应表
• 找到指标字段
• 找到时间字段
• 找到维度字段
• 检查业务术语和真实字段是否一致

示例：

• “成交额” 可能对应 paid_amount
• “下单人数” 可能不是 order_count，而是 count(distinct user_id)
• “本月” 需要明确是自然月还是近 30 天

如果术语与字段不能直接映射，先输出映射假设，再等待确认或在结果中标注“基于以下假设”。

3. Query Plan

先产出查询计划，再执行。

查询计划至少包含：

• 数据源
• 涉及表
• 连接关系
• 指标口径
• 分组维度
• 时间范围
• 排序方式
• 限制条件
• 输出形式

如果是 SQL 数据源，优先生成只读查询。
禁止生成：

• delete
• update
• insert
• alter
• drop

4. Execute

按数据源分流：

• MySQL：读取连接配置，执行只读 SQL
• Excel / CSV：先加载为结构化数据，再按分析任务执行筛选、聚合、排序

执行后至少检查：

• 是否为空结果
• 是否字段缺失
• 是否聚合异常
• 是否时间格式错误

如果结果异常，不要直接输出“查不到”，而要说明失败原因和下一步建议。

5. Explain Result

输出必须分成三层：

• 结果摘要：一句话结论
• 关键发现：2-4 条
• 结果明细：表格或结构化数据

如果用户要求图表，再补：

• 图表类型选择理由
• 图表数据范围
• 图表文件路径或展示结果

6. Chart Strategy

图表不要只按用户口头要求机械生成，要做一次匹配判断：

• 表格：明细查看、字段较多
• 条形图：分类对比、Top N
• 折线图：时间趋势
• 饼图：占比结构，且类别不宜过多

当用户说“做个图”，默认规则：

• 时间序列优先折线图
• 分类对比优先条形图
• 构成占比优先饼图
• 无法判断时先输出表格并建议图表类型

Natural Language Optimization

这是这个 Skill 最容易写虚的地方，必须具体化。

1. 用“分析意图识别”替代“直接问数”

先判断用户到底要什么：

用户说法	实际意图
“有多少”	总量统计
“谁最好”	排名
“怎么样了”	状态概览或趋势
“和上个月比”	环比对比
“占比多少”	结构分析
“看下异常”	异常检测或边界值检查

2. 自动补齐隐含槽位

自然语言通常缺少关键信息。至少检查这些槽位：

• 时间范围
• 指标口径
• 对比对象
• 维度粒度
• 是否去重
• 是否包含退款/取消/测试数据

如果缺槽位：

• 能从术语文档补的就补
• 不能补的就追问 1 个最关键问题

3. 先改写，再生成查询

推荐中间层输出格式：

分析任务：
- 目标：比较近 30 天华东与华南销售额
- 指标：支付销售额
- 维度：区域
- 时间粒度：天
- 数据过滤：排除退款订单
- 输出：表格 + 折线图 + 3 条结论摘要

这一层非常关键，它能显著降低 SQL 漂移和图表误配。

4. 对模糊时间做标准化

统一处理这些自然语言：

• 今天 / 昨天 / 本周 / 上周
• 本月 / 上月 / 近 7 天 / 近 30 天
• 最近 / 近期 / 今年以来

不要把“最近”默认写死。优先追问；如果必须推断，要在结果里明确注明。

5. 对业务术语做别名映射

建议在 term-glossary.md 中维护：

- 成交额 = paid_amount
- 下单用户数 = count(distinct user_id)
- 新客 = first_paid_user
- 活跃门店 = store_status = active 的门店数

让自然语言解析优先查别名表，再查 schema。

Output Contract

标准输出结构建议如下：

## 查询理解
- 数据源：
- 分析目标：
- 关键口径：
- 假设说明：

## 查询结果摘要
- ...

## 关键发现
- ...

## 结果明细
- 表格或结构化结果

## 图表输出
- 图表类型：
- 选择原因：
- 输出路径：

Tool Integration

推荐目录：

smart-data-query/
├── SKILL.md
├── scripts/
│   ├── connect-db.py
│   ├── sql-generator.py
│   └── chart-render.py
├── references/
│   ├── db-schema.md
│   └── term-glossary.md
└── assets/
    └── chart-templates/

推荐职责：

• connect-db.py：封装数据读取，屏蔽不同数据源差异
• sql-generator.py：输入“分析任务说明 + schema + glossary”，输出只读 SQL
• chart-render.py：根据结果数据和图表策略生成图表

Direct Usability Check

如果只有你截图里的那套目录和文件名，这个 Skill 还不能算“可直接使用”。

缺口主要有 6 个：

• 缺少自然语言到分析任务的显式转换层
• 缺少歧义处理策略
• 缺少字段口径校验
• 缺少只读安全约束
• 缺少空结果和错误结果处理
• 缺少统一输出格式，难以稳定复用

换句话说，当前设计更像“功能清单”，不是“可执行流程”。

Minimal Viable Version

如果先做一个真正能跑的 V1，建议只支持：

• 数据源：MySQL + CSV
• 场景：统计、对比、趋势
• 输出：表格 + 条形图 + 折线图
• 辅助：schema + glossary

先不要一开始就做：

• Excel 的复杂多 sheet 解析
• 自动图表美化
• 任意自然语言自由问答
• 复杂多表推理

先把“一个问题稳定跑通”做扎实，再扩展。

Common Mistakes

• 直接从用户原话生成 SQL，导致查询意图跑偏
• 只看字段名，不看业务口径
• 把模糊时间强行猜掉且不说明
• 饼图乱用到十几个分类
• 图表有了，但没有文字摘要
• 结果为空时没有解释是数据为空还是条件过严

Success Criteria

这个 Skill 达到可用状态，至少要满足：

• 对常见行政/运营/销售问数问题能稳定识别意图
• 缺失关键信息时能追问而不是瞎猜
• 查询语句默认只读
• 输出同时包含结论、数据、图表
• 结果里能说明口径和假设