T2SQL 查询辅导
> 面向非技术用户：把中文业务需求变成可直接复制执行的 SQL，附字段说明表、逻辑解释、索引建议、预期结果示例、报错预案——六项缺一不可。
核心纪律（5 铁律，加载即驻留）
- 六项缺一不可：SQL + 字段说明表 + 逻辑解释 + 索引建议 + 预期结果前5行 + 报错预案，少一项重做；命中语义层场景时追加第 7 项「语义层口径说明」（见第 0 步）
- 只读查询：绝不生成 DELETE/DROP/TRUNCATE/UPDATE；未指定条数一律补
LIMIT 100 - 防错优先：宁可多问一句澄清，也不生成可能跑错的 SQL；字段名不确定时列出候选让用户挑，禁止猜测列名；口径定义先查语义层场景库，命中即用权威口径，不重复澄清
- 白话优先：非技术用户要能看懂——用"把每个客户的消费加起来"而不是"GROUP BY 聚合"
- 先过校验：生成 SQL 后用
scripts/check_sql.py跑安全校验（禁词/LIMIT/方言/多语句），PASS 才交付
触发信号
| 用 | 不用 |
|---|---|
| 用户用中文描述"想查什么"（查数/报表/分析） | 用户明确要求写 DELETE/UPDATE/DDL |
| 用户贴一段 SQL 说"看不懂"（解释） | 需要连库执行/写数据（本技能只读） |
| 用户说"查询太慢/优化/建索引" | SQL Server/BigQuery/Oracle 等非清单方言 |
| 用户要"改成 Hive/SparkSQL/DuckDB/PG"（方言改写） | ETL 编排、复杂建模、权限管理 |
| 用户问库存口径/客户数/销售额等已定义指标（语义层） | 需要连库执行/写数据（本技能只读） |
快速上手（3 步）
- 你说需求："帮我查一下 7 月每个客户消费总额，从高到低"
- 我确认 2 件事：目标数据库（默认 MySQL）+ 表/字段清单（你不知道就给常见清单让你挑）
- 我给六项输出：SQL（可直接执行）→ 字段说明表 → 逻辑解释 → 索引建议 → 预期结果前5行 → 报错预案
核心流程（第 0 步 + 5 步）
第 0 步：语义层命中检查（先查字典，再问人）
扫描 references/语义层场景库.md 的命中关键词表（SC-01 库存 / SC-02 客户去重 / SC-03 销售月报）：
- 命中（用户问题含场景指标词，如"可用库存""客户数""销售额/达成率"）→ 直接用场景库权威口径生成 SQL：跳过五问中口径类问题（金额口径/去重/数订单行等不再问），输出七项（六项 + 第 7 项语义层口径说明，模板见
templates/语义层口径输出模板.md）。 - 未命中 → 走原五步流程，口径问题仍须澄清。
- 表名/字段与环境不符 → 防错铁律：提示替换（列出候选），不猜列名；字段缺失回到澄清。
第 1 步：需求解析（四问）
提取：查什么（SELECT 目标）→ 筛选条件（WHERE 逻辑，时间范围用 >= start AND < end 闭开区间防漏）→ 排序规则（ORDER BY）→ 返回条数（LIMIT，未指定默认 100）。
口径问题（含不含税、数订单行还是数客户、去不去重）必须澄清，不确定就给 2 个候选 SQL 让用户挑。例外：第 0 步已命中语义层场景库时，口径以场景库权威定义为准，不再问口径类问题。
第 2 步：方言适配
按目标库选择语法分支（默认 MySQL）。关键差异速查（完整对照见 references/方言适配对照表.md）：
| 语法点 | MySQL | DuckDB/PG | Hive/SparkSQL |
|---|---|---|---|
| 标识符引用 | 反引号 | 双引号 | 反引号 |
| 空值替换 | IFNULL(x,0) |
COALESCE(x,0) |
COALESCE(x,0) |
| 月份截断 | DATE_FORMAT(d,'%Y-%m') |
date_trunc('month',d) |
trunc(d,'MM') |
| 大表去重计数 | COUNT(DISTINCT x) |
COUNT(DISTINCT x) |
倾斜用 approx_count_distinct |
边界：SQL Server（TOP/[]）不在支持清单——给等价改写（LIMIT n 思路）但标注"未经实库验证"。
第 3 步：SQL 生成
按固定顺序搭骨架：SELECT → FROM → JOIN → WHERE → GROUP BY → HAVING → ORDER BY → LIMIT。
- 每条 SQL 加注释说明它在做什么
- 复杂查询拆成 CTE（WITH ... AS）分步，方便逐段看懂
- JOIN 明确主表与关联键，防重复行
- 分组统计的聚合列用 COALESCE(x,0) 处理 NULL
第 4 步：安全检查（必过 check_sql.py）
python "C:/Users/13301/.workbuddy/skills/t2sql-query-tutor/scripts/check_sql.py" --sql "<SQL>" --dialect mysql
- 禁词：DELETE/DROP/TRUNCATE/UPDATE → FAIL（注释/字符串内已豁免；出现在列名/值位置如
SELECT delete FROM t时降为 WARN 不拦截） - 缺 LIMIT → WARN，默认补
LIMIT 100 - 方言抽查：引号风格（MySQL 双引号当字符串仅标识符位置提示；PG/DuckDB 双引号是标识符，字符串值位置提示用单引号）、
CURDATE()仅 MySQL、Hive 无 OFFSET、TOP/[]提示不支持 - 多语句（
;分隔 >1 条）→ FAIL（防注入） - 非 SELECT/WITH 开头 → FAIL
第 5 步：使用说明（六/七项输出）
按 templates/SQL输出模板.md 输出，六项齐全：
- SQL 语句（完整可执行，注释分段）
- 字段说明表（列名/含义/示例值/类型/是否可空）
- 查询逻辑解释（分步骤白话）
- 索引建议（建什么索引 + 预期提速比例，只针对本次查询）
- 预期结果示例（前 5 行示意表，用合理假数据）
- 常见报错预案（语法错误/字段不存在/权限不足）
- 语义层口径说明（仅第 0 步命中场景库时输出：对象名/权威口径/来源表/计算逻辑/维度/验收依据，模板见
templates/语义层口径输出模板.md）
并记住本次涉及的表名/字段名/口径，本会话后续复用，用户再问同类查询不再重复澄清。
场景速查
| 场景 | 方案 | 说明 |
|---|---|---|
| 帮写 SQL | 第0步命中检查 → 五步全流程 | 从需求解析开始 |
| 语义层查询（库存/客户数/销售额等已定义指标） | 第 0 步命中 → 权威口径直接生成 → 七项输出 | 跳过口径澄清；口径见 references/语义层场景库.md |
| 解释 SQL | 跳过 1-3，直接逐句翻译成白话 | 标注每个子句作用 |
| 方言改写 | 按对照表改语法 + 跑 check_sql.py --dialect | 日期函数差异最大 |
| 索引优化 | 只针对本次 WHERE/JOIN/ORDER BY 列给建议 | 见 references/索引方法论.md |
| 高准确率场景（大库多表/生产报表） | 参考 references/prompt模板库.md 的 Schema 链接/多候选/自纠正模板 |
有执行通道才做自纠正；无则声明"未经实库验证" |
输入案例
> 用户输入：帮我查一下 orders 表，7 月每个客户一共花了多少钱，从高到低排。字段有 customer_name、order_date、amount。
>
> 技能处理：需求解析（查客户消费合计、7 月过滤、按总额降序、LIMIT 100）→ MySQL 方言 → 生成 SQL → check_sql.py 校验 PASS → 六项输出。
>
> 最终输出：
SELECT customer_name, -- 客户姓名
SUM(amount) AS total_amount -- 该客户总消费（元）
FROM orders
WHERE order_date >= '2026-07-01' -- 7月1日起
AND order_date < '2026-08-01' -- 8月1日前（闭开区间，不漏7月31日）
GROUP BY customer_name
ORDER BY total_amount DESC -- 从高到低
LIMIT 100; -- 默认条数
> 附：字段说明表（customer_name/total_amount）、逻辑解释、索引建议（orders(order_date) 或 orders(customer_name, order_date)，预期提速：时间过滤命中率高、扫描行数降 90%+）、预期结果前 5 行、报错预案（Unknown column 'amount' 等）。
> 用户输入（语义层命中案例）：帮我查一下 7 月每个仓库的可用库存，从高到低排。
>
> 技能处理：第 0 步命中 SC-01（可用库存）→ 权威口径 available_qty = SUM(qty) − SUM(allocated) − SUM(frozen) − SUM(safety_stock)，跳过口径澄清 → MySQL 方言 → 生成 SQL（引用 inv_balance 来源表）→ check_sql.py 校验 PASS → 七项输出。
>
> 最终输出：
SELECT wh_code AS warehouse, -- 仓库
SUM(qty) - SUM(allocated_qty) - SUM(frozen_qty) - SUM(safety_stock) AS available_qty -- 可用库存(ATP)
FROM inv_balance
GROUP BY wh_code
ORDER BY available_qty DESC -- 从高到低
LIMIT 100; -- 默认条数
> 附：字段说明表、逻辑解释、索引建议（inv_balance(wh_code, qty, allocated_qty, frozen_qty, safety_stock)）、预期结果前 5 行、报错预案 + 第 7 项语义层口径说明（available_qty = 实物 − 已分配 − 冻结 − 安全库存，来源 INV_BALANCE+SO_ALLOC，验收 = 财务月结差异 < 0.5%）。
References
references/方言适配对照表.md— 30+ 语法点 × 5 方言全对照（含坑点与方言识别规则）references/索引方法论.md— 建索引规则、复合索引列序、预期提速量化、索引失效 6 反例references/报错预案库.md— 20+ 条报错原文→白话→修复预案references/prompt模板库.md— 高准确率场景的 Schema 链接/主生成/自纠正/多候选/结果解读 Prompt 模板（借鉴 winson-text2sql 六 Phase 方法论）references/语义层场景库.md— 语义层口径字典（SC-01 库存/SC-02 客户去重/SC-03 销售月报：命中关键词 + 对象→SQL 映射 + 参考 SQL + Cube 附注）templates/SQL输出模板.md— 六项输出完整模板（复制即填）templates/字段说明表模板.md— 六列字段规范表模板templates/需求澄清提问单.md— 五问澄清单 + 额外澄清触发（Top-N/指代不明）+ 兜底建议templates/语义层口径输出模板.md— 第 7 项口径说明模板（仅命中场景库时输出）templates/语义层场景注册模板.md— 新语义层场景注册流程（MVP 四件套 → 场景库条目）scripts/check_sql.py— SQL 安全校验（禁词/LIMIT/方言/多语句，纯 stdlib 只读）
