Tchoused Nl2sql Analysis

---
name: 腾讯云TCHouse-D 自然语言 SQL 生成
description: >
  TCHouse-D（Doris）自然语言 SQL 生成 Skill。用户通过自然语言描述分析需求，AI 自动理解意图、结合表结构生成对应 Doris SQL，输出到 SQL 工作区手动执行的指引；用户回贴执行结果后，Agent 继续选择合适的图表类型进行可视化呈现，并输出中文业务结论摘要。
  触发词：数据分析、统计、报表、趋势图、柱状图、饼图、折线图、数据查询、NL2SQL、自然语言查询、帮我查一下、帮我统计、帮我分析、数据可视化、图表、汇总、按天统计、按月统计、分组统计、TOP排名、占比分析、同比、环比、趋势分析、数据报告、Doris查询、TCHouse-D查询、cdwdoris、SQL生成、数据洞察、业务分析、用户画像、漏斗分析、留存分析、GMV、DAU、转化率、支付金额、订单量。
  本 Skill 包含 4 个子能力：①自然语言转 SQL（NL2SQL）②SQL 与手工执行指引输出 ③智能图表可视化推荐（基于用户回贴的结果数据）④中文业务结论摘要生成。
  何时不触发：慢 SQL 诊断与自动调优（已有 SQL 的性能分析）、集群健康诊断与故障排查（监控指标/告警/节点故障）、集群选型与架构推荐、智能建表与数据建模、集群扩缩容操作、权限管理、数据导入导出等非数据分析查询相关问题不走本 Skill。
allowed-tools:
  - TCHouseDDescribeInstance
  - TCHouseDDescribeDDL
  - ask_user # WorkBuddy 中为 AskUserQuestion
  - show_widget
---

# 自然语言数据分析（NL2SQL）

## 概述

本 Skill 提供 TCHouse-D（Doris）集群的自然语言 SQL 生成能力，包含四个子能力：

1. **自然语言转 SQL（NL2SQL）**：理解用户自然语言描述的分析需求，结合表结构生成对应的 Doris SQL
2. **SQL 与手工执行指引输出**：向用户输出完整 SQL 与 SQL 工作区手动执行指引，请用户回贴执行结果
3. **智能图表可视化推荐**：根据用户回贴的结果数据特征和分析意图，自动选择最合适的图表类型
4. **中文业务结论摘要生成**：基于用户回贴的查询结果，输出面向业务人员的中文分析结论

## 依赖与运行环境

本 Skill 的所有调用通过 MCP Tool 完成（云 API 类工具由平台封装为 MCP Tool，Agent 直接调用工具名即可）。

**依赖工具清单**：

| #   | Tool 名称                | 能力定位                                              | 参考文档                                               |
| --- | ------------------------ | ----------------------------------------------------- | ------------------------------------------------------ |
| 1   | TCHouseDDescribeInstance | 集群基本信息获取                                      | [参考](references/tchoused-describe-instance.md) |
| 2   | TCHouseDDescribeDDL      | 根据库表名获取建表 DDL（用于 SQL 生成的表结构上下文） | [参考](references/tchoused-describe-ddl.md)      |
| 3   | ask_user                 | 向用户询问确认信息（WorkBuddy 中为 AskUserQuestion）  | —                                                      |
| 4   | show_widget              | 渲染可交互的 Chart.js 图表（折线图/柱状图/饼图等）    | —                                                      |

## 凭证 / 环境变量

- `instance_id`：集群实例 ID，需通过 `ask_user`（WorkBuddy 中为 `AskUserQuestion`）向用户询问获取
- `region_id`：地域 ID，需通过 `ask_user`（WorkBuddy 中为 `AskUserQuestion`）向用户询问获取（可能是 `RegionId` 数字，也可能是 `Region` 字符串，也可能是中文地域名）

> ⚠️ **地域参数强制规则**：**任何工具调用前**都必须先按 [地域映射表](references/region-mapping.md) 把上下文中的地域信息补齐为 **`Region`（字符串）+ `RegionId`（数字）** 两种形式，禁止凭记忆填写。不同工具对参数形式的要求见 [工具传参形式速查](references/region-mapping.md#工具传参形式速查)：本 Skill 使用的 `TCHouseDXxx` 系工具 **只传 `Region` 字符串**。

> 💡 **多平台兼容说明**：本文档中所有提到的 `ask_user` 工具，在 WorkBuddy 平台中对应为 `AskUserQuestion`。后文不再重复标注。

## 地域映射与缓存机制

### 地域映射规则

无论用户以何种形式提供地域信息（中文名、英文串、数字 ID），**都必须**按 [地域映射表](references/region-mapping.md) 补齐为 `Region`（字符串）+ `RegionId`（数字）两种形式后再进入工具调用，**不允许凭印象猜测**：

1. **精确匹配优先**：如果用户给出的地域名称能精确匹配到地域映射表中的"地域名称"列，直接使用对应的 Region / RegionId 值
2. **常见简称映射**：支持常见地域简称（如"广州"→`ap-guangzhou`、"上海"→`ap-shanghai`、"北京"→`ap-beijing`、"重庆"→`ap-chongqing`、"成都"→`ap-chengdu`、"深圳"→`ap-shenzhen`）
3. **金融区识别**：用户提到"金融"、"金融区"时，优先匹配带 `-fsi` 后缀的地域
4. **所属地区模糊匹配**：如果用户只说了"华南地区"等大区名称，需通过 `ask_user` 让用户确认具体地域
5. **不熟悉的地域兜底**：如果用户提到"乌鲁木齐""清远"等不熟悉的地域名，**不要**凭印象猜测 code，必须查地域映射表确认；若映射表中仍找不到，调用 `ask_user` 让用户确认

### 地域选择优化流程

**步骤 0.1：地域参数确认与映射**

**判断逻辑**：

- ✅ `region_id` 已提供（任意形式）→ **强制**按地域映射表补齐为 `Region` + `RegionId` 两种形式后进入步骤 1
- ❌ `region_id` 缺失但用户问题中包含地域信息（中文名/英文串/数字 ID）→ 按地域映射表补齐两种形式后进入步骤 1
- ❌ `region_id` 缺失且用户问题中无地域信息 → 调用 `ask_user` 询问用户确认地域

**询问话术示例**：
"请确认您要分析的 TCHouse-D 集群所在地域（如：广州、上海、北京等）"

**缓存机制**：

- 用户确认的地域信息在当前会话中缓存，避免重复询问
- 如果地域调用返回 `ResourceNotFound`，提示用户确认地域是否正确

## 核心工作流

### 步骤 0：参数确认

**必需参数**：

- `instance_id`（集群 ID，`cdwdoris-` 前缀）
- `region_id`（地域）

**可选参数**：

- 数据库名与表名：从用户问题中提取，未指定 → 步骤 2 让用户提供或选择
- 时间范围：从用户问题中提取（如"过去7天"、"本月"），未指定 → 询问用户
- 分析维度/指标：从用户问题中提取

**判断逻辑**：

- ✅ `instance_id` + `region_id` 都已齐全 → 直接进入步骤 1
- ✅ 仅 `region_id` 已知（或从中文地域名转换得到）、`instance_id` 缺失 → **一次** `ask_user`：调用 `TCHouseDDescribeInstance` 或集群列表接口列出该地域下的集群，以选项形式让用户从列表中选择具体集群
- ❌ 两个参数都缺失 → **一次** `ask_user` 同时收集「地域」和「集群 ID 或集群名」，例如："请提供要分析的 TCHouse-D 集群，格式：地域 + 集群 ID/名称（如：广州 cdwdoris-xxxxxxxx）"

> 💡 **调度友好原则**：尽量合并多个参数到**一次** `ask_user`中收集，避免「地域问一轮 → 集群问另一轮」这种多轮连环。

### 步骤 1：确认集群信息

调用 `TCHouseDDescribeInstance` 获取集群基本信息。

**判断逻辑**：

- ✅ 集群状态为 `Serving` → 进入步骤 2
- ❌ 集群状态异常 → 告知用户集群当前不可用，终止分析
- ❌ 调用失败（AuthFailure）→ 报告错误，提示检查权限
- ❌ 调用失败（ResourceNotFound）→ 检查 instance_id 格式（`cdwdoris-` 前缀），格式错则修正重试

### 步骤 2：确认目标库表并获取表结构

**目的**：了解用户数据的库表结构，为 SQL 生成提供上下文。

> **注意**：本 Skill **不再直接连接集群执行 SQL**（`SHOW DATABASES` / `SHOW TABLES` 也不再自动执行）。库表信息通过以下方式获取：
>
> 1. 优先从用户问题中提取
> 2. 通过 `TCHouseDDescribeDDL` 获取表 DDL（需要用户提供三段式 `catalog.database.table`）
> 3. 无法从上述方式确定时，通过 `ask_user` 请用户提供，或让用户到 SQL 工作区执行 `SHOW DATABASES` / `SHOW TABLES` 后回贴清单

#### 2.1 确定目标库表

**判断逻辑**：

- ✅ 用户明确指定库名和表名 → 进入 2.2
- ✅ 用户仅指定表名，库名可从上下文推断（如用户在同会话中已提到） → 进入 2.2
- ❌ 库表名缺失或不明确 → 调用 `ask_user`，请用户提供以下之一：
  1.  明确的 `catalog.database.table` 三段式表名
  2.  到 SQL 工作区执行 `SHOW DATABASES` / `SHOW TABLES FROM <db>` 后回贴清单，Agent 再基于清单与用户描述推断

> ⚠️ **禁止基于用户描述的维度/指标猜测表名**。库表信息必须由用户明确给出或从 DDL 结果确认，不允许凭印象编造。

#### 2.1.1 系统库/表拦截（硬校验，先于 DDL 拉取）

> ⚠️ **在调用 `TCHouseDDescribeDDL` 之前**，必须先对目标库名做系统库校验；命中则直接终止业务分析流程，不得继续拉 DDL、更不得基于系统表生成业务 SQL。

**Doris 内置系统库黑名单**（不区分大小写）：

| 库名                 | 用途                                              | 特征                                  |
| -------------------- | ------------------------------------------------- | ------------------------------------- |
| `information_schema` | ANSI 标准元数据视图（表/列/权限等）               | 只读元数据，无业务数据                |
| `mysql`              | Doris 内置的 MySQL 兼容权限库（`user` / `db` 等） | `ENGINE=SCHEMA`，为权限视图不是业务表 |
| `__internal_schema`  | Doris 内部审计/统计库（下划线开头）               | 内核使用，用户禁止查询                |
| `sys`                | 系统监控/内核指标                                 | 与业务无关                            |

**其它可识别信号**（即便库名不在上表内，命中以下任一也判定为系统表）：

- `TCHouseDDescribeDDL` 返回的 DDL 中出现 `ENGINE=SCHEMA` / `ENGINE=MYSQL` / `ENGINE=INTERNAL` 等非 `OLAP` 引擎
- 库名以下划线开头（`__` 或 `_`）
- catalog 不为 `internal`（外部 catalog 数据源，本 Skill 暂不承接）

**判断逻辑**：

- ❌ 用户提供的 `catalog.database.table` 中 database 命中黑名单 → **不调用 `TCHouseDDescribeDDL`**，直接向用户说明「`mysql` / `information_schema` / `__internal_schema` 等为 Doris 内置系统库，不承载业务数据，本 Skill 不做业务分析」，并请用户提供真实业务库表
- ❌ 已调用 DDL 但返回结果显示 `ENGINE!=OLAP` → 视为系统/元数据表，走同上分支终止
- ⚠️ 用户明确表达要看系统库内容（如「我想看 `mysql.user` 里有哪些账号」） → 只作为管理型查询处理，不走本 Skill 的可视化/业务结论流程（不生成图表/不写业务摘要），输出基础 SQL 后提醒用户“该库为 Doris 内置元数据，请确认是否仅需要管理目的的查询”

#### 2.2 获取表结构

> ⚠️ **TableName 必须为三段式**：`catalog.database.table`（默认 catalog 为 `internal`，例如 `internal.demo_db.orders`）。若用户只提供了库.表两段或仅表名，需要补全为三段式后再调用。

**记录信息**：列名、数据类型、注释（Comment）、KEY 列（排序键）、分区键、分桶键、数据模型（DUPLICATE/UNIQUE/AGGREGATE）。

**判断逻辑**：

- ✅ 成功 → 进入步骤 3
- ❌ 表不存在（`ResourceNotFound`）→ 调用 `ask_user` 让用户确认库表名，重试 1 次
- ❌ 权限不足 → 告知用户无权限查看该表结构，请联系管理员

### 步骤 3：理解需求与生成 SQL

**3.1 需求理解**：

从用户自然语言中提取：

- **分析目标**：统计什么（如"支付金额"、"用户数"）
- **时间范围**：什么时间段（如"过去7天"、"本月"）
- **分组维度**：按什么维度汇总（如"按天"、"按渠道"）
- **过滤条件**：有什么限制（如"只看VIP用户"）
- **排序/限制**：TOP N、升序/降序
- **可视化意图**：趋势图、对比图、占比图等

**3.2 SQL 生成**：

基于表结构和需求理解，生成 Doris SQL。遵循 [SQL 生成规范](references/sql-generation-guide.md#生成规范)。

**关键原则**：

- 必须使用分区键过滤（避免全分区扫描）
- 只 SELECT 需要的列（Doris 列式存储，SELECT \* 性能差）
- 时间函数使用 Doris 原生函数（`DATE`/`DATE_TRUNC`/`DATE_FORMAT`/`FROM_UNIXTIME`/`NOW()` 等）
- 大表 JOIN 时小表放右侧，必要时使用 `[broadcast]` / `[shuffle]` hint
- 聚合查询必须有 GROUP BY
- UNIQUE 模型表查询设置 session 变量 `enable_unique_key_partial_update` 不影响读，无需额外处理
- 物化视图：Doris 自动路由（如启用），无需 SQL 中显式指定

**3.2.1 分区覆盖预校验（生成时间过滤前必做）**：

> ⚠️ **在把用户所述的时间窗口翻译成 WHERE 条件之前**，必须先核对表的**现有分区**是否覆盖该时间窗。DDL 中 `PARTITION` 段/`PARTITION BY RANGE` 明确列出的分区区间即为唯一真源；**分区未覆盖时不得静默生成 SQL、不得假定“长期存在”**。

**校验步骤**：

1. 从步骤 2 拉取到的 DDL 中提取分区列表，归纳为已存在分区的**时间区间并集**（如 `p202606` → `[2026-06-01, 2026-07-01)`）
2. 把用户时间窗口展开为具体区间（如“过去 7 天”在1月10日当天展开为 `[2026-07-03, 2026-07-10)`）
3. 两个区间做交集：
   - ✅ 交集非空且 = 用户区间 → 直接使用用户时间窗生成 SQL
   - ⚠️ 交集非空但 ⊂ 用户区间（部分覆盖）→ 向用户说明“分区仅覆盖 X~Y，将基于实际分区区间生成 SQL”，并按交集区间生成
   - ❌ 交集为空（分区完全不覆盖，如用户问“过去 7 天”但只有 `p202606` 分区）→ **不能静默生成 SQL**，必须主动提供以下兜底方案并请用户选择：
     - **方案 A（推荐）**：建议用户重选时段——告知实际可查时段（如“当前表仅有 2026-06 一个月的分区数据，可查询该月的情况吗？”），等用户确认后重新生成
     - **方案 B（兜底）**：将时间范围限定为已知分区内最新区间，从而至少返回非空结果（适用于用户只要​​任何近期​​样本而非硬约束“过去 N 天”）

**禁止行为**：

- 禁止在未校验分区覆盖时直接把“过去 7 天”翻译为 `WHERE date >= CURDATE() - INTERVAL 7 DAY`——表只有 `p202606` 时会返回空结果，而用户无法得知归因
- 禁止把“返回 0 行”归因为“业务无数据”并结束分析：回贴 0 行前必须先排除分区错配
- 禁止仅靠 `INFORMATION_SCHEMA.PARTITIONS` 推断分区（本 Skill 未直连集群），分区信息一律以 `TCHouseDDescribeDDL` 返回的 DDL 为准

详细映射与样例见 [SQL 生成规范§2.5 分区覆盖预校验](references/sql-generation-guide.md#25-分区覆盖预校验生成时间过滤前必做)。

### 步骤 4：输出 SQL 与手工执行指引，等待用户回贴结果

本 Skill **不再直接执行 SQL**。Agent 需要在此步骤向用户输出 SQL 及执行指引，请用户到 SQL 工作区手动执行后回贴结果。

**4.1 输出 SQL 与执行指引**：

向用户输出以下内容：

1. **完整可复制的 SQL 语句**（单独代码块，便于用户复制）
2. **执行方式**：登录腾讯云 TCHouse-D 控制台 → 打开目标集群 → 进入「SQL 工作区」→ 选择目标数据库 → 粘贴 SQL 执行
3. **回贴指引**：请用户将查询结果以下列任一形式回贴：
   - 直接粘贴 SQL 工作区导出的 CSV / JSON / Markdown 表格
   - 手动整理为「列名 + 若干行数据」的结构化文本

**4.2 结果数据量控制建议**：

- SQL 生成时，如判断结果行数可能 > 1000 行，**主动在 SQL 中加 `LIMIT 1000`**，并在指引中提示"结果已限制为 1000 行，如需完整数据请分批查询或导出"
- 提醒用户避免直接对大表做无 `LIMIT` 的 `SELECT *`

**4.3 等待用户回贴**：

- ✅ 用户回贴结构化结果 → 解析结果数据，进入步骤 5 生成图表
- ✅ 用户回贴执行错误信息 → 分析错误（语法/权限/表列不存在/内存不足），修正 SQL 后回到 4.1 重新输出
- ❌ 用户未回贴或表示无法执行 → 说明本 Skill 需要用户自行到 SQL 工作区执行，如无法执行则终止流程

**4.4 常见执行错误的排查建议（供用户参考）**：

| 错误场景                          | 处理方式                                                                                                          |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| SQL 语法错误                      | 用户回贴 `ErrMsg`，Agent 分析并修正 SQL 后重新输出                                                                |
| 内存不足（Memory limit exceeded） | 建议：1) 添加 LIMIT 2) 减少 GROUP BY 维度 3) 缩小数据范围；或调整 session `exec_mem_limit`                        |
| 表/列不存在                       | 重新调用 `TCHouseDDescribeDDL` 确认表结构，修正 SQL 后重新输出                                                    |
| 权限不足                          | 告知用户无该表的查询权限                                                                                          |
| 查询超时                          | 建议缩小范围/添加 LIMIT/简化逻辑                                                                                  |
| 无报错但返回 0 行                 | 先核对分区覆盖：回到步骤 3.2.1 用 DDL 分区区间与用户时间窗做交集校验；确认分区错配后按兜底方案 A/B 与用户重选时段 |

### 步骤 5：智能图表可视化

详见 [可视化推荐规则](references/visualization-guide.md#图表选择规则)。

#### 5.0 结果非空校验（进入可视化前必做）

> ⚠️ **收到用户回贴的执行结果后，先判空再走可视化**。若结果为 0 行或全部指标为 0，不要直接归因为"业务无数据"，必须先回溯以下项目：
>
> 1. **步骤 3.2.1 分区覆盖预校验**是否已通过？若当时未做（如老会话续跑或跳步），**必须补做**：拿用户时间窗与 DDL 分区区间做交集，交集为空则按方案 A/B 与用户重新确认，不进入下方可视化
> 2. 时间窗内是否落在了未来时段（如用户表述"过去 7 天"但系统时间早于分区最新时段边界）
> 3. WHERE 条件里的业务过滤（如 `status='paid'`）是否过严
>
> 上述三项均排除后，才可判定为"业务确实无数据"并向用户输出结论。**禁止在未复核分区覆盖前直接生成"无数据"结论或空图表**。

**图表选择决策树**：

| 数据特征               | 分析意图   | 推荐图表       |
| ---------------------- | ---------- | -------------- |
| 时间序列 + 数值        | 趋势变化   | 📈 折线图      |
| 分类 + 数值（≤ 10 类） | 对比大小   | 📊 柱状图      |
| 分类 + 占比（≤ 8 类）  | 占比分布   | 🥧 饼图/环形图 |
| 两个数值维度           | 相关性     | 散点图         |
| 时间 + 分类 + 数值     | 多系列趋势 | 📈 多折线图    |
| 分类 + 多指标          | 多维对比   | 📊 分组柱状图  |
| 单一数值               | 关键指标   | 🔢 数字卡片    |
| 排名（TOP N）          | 排序对比   | 📊 横向柱状图  |

**输出方式**：

1. **优先使用 `show_widget` 工具直接渲染图表**
2. **辅助输出 Markdown 表格**
3. **降级方案**：仅当 `show_widget` 不可用时退回到纯 Markdown 表格

### 步骤 6：生成业务结论摘要

详见 [结论生成规范](references/visualization-guide.md#业务结论规范)。

**结论结构**：

1. **核心发现**（1-2 句话概括最重要的结论）
2. **数据支撑**（关键数字和对比）
3. **趋势判断**（上升/下降/平稳，环比/同比变化）
4. **异常提示**（如有明显异常值或突变）
5. **建议行动**（基于数据的业务建议，可选）

**输出要求**：

- 使用中文，面向非技术人员
- 数字使用千分位分隔（如 1,234,567）
- 百分比保留 2 位小数
- 金额标注单位（元/万元/亿元）
- 避免使用技术术语（如"聚合"、"JOIN"）

## 频率控制

| 限制                     | 阈值          | 说明                 |
| ------------------------ | ------------- | -------------------- |
| 工具总调用频率           | ≤ 15 次/分钟  | 避免触发平台限流     |
| TCHouseDDescribeDDL 调用 | ≤ 5 次/轮分析 | 拉取目标表结构上下文 |

**超限处理**：连续收到 `RequestLimitExceeded` → 等 5 秒重试，连续 3 次仍失败 → 降低调用频率，告知用户被限流。

## 错误码与处理策略

| 错误码/场景            | Agent 行为                                                                                                                                                                                            |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AuthFailure.*`        | 报告鉴权失败，提示用户检查集群访问权限                                                                                                                                                                |
| `ResourceNotFound`     | 检查 ID 格式（`cdwdoris-` 前缀）；格式错 → 修正重试；格式对 → 请用户确认                                                                                                                              |
| `InvalidParameter.*`   | 检查参数格式，尝试修正后重试 1 次；无法修正 → 报告具体问题                                                                                                                                            |
| `UnsupportedRegion`    | 该地域未开通 TCHouseD 产品。**不重试、不自动切换地域**，必须调用 `ask_user` 让用户确认地域。详见 [error-handling.md §1](references/error-handling.md#1-unsupportedregion该接口不支持此地域访问) |
| `InternalError`        | 等 3 秒重试，最多 3 次；仍失败 → 报告错误码 + RequestId                                                                                                                                               |
| `RequestLimitExceeded` | 等 5 秒重试；连续 3 次 → 降低频率，告知被限流                                                                                                                                                         |
| 网络超时               | 等 3 秒重试，最多 3 次；仍失败 → 告知用户服务暂时不可用                                                                                                                                               |
| 兜底（未列出错误码）   | 报告完整错误信息 + RequestId                                                                                                                                                                          |

## 安全规则

1. **本 Skill 仅生成 SELECT 查询**：生成的 SQL 必须是 SELECT 语句，严禁生成 INSERT/UPDATE/DELETE/DROP/ALTER/TRUNCATE/CREATE 等写操作
2. **严禁自行造测试数据**：当集群无业务库或无业务数据时，必须终止流程并提示用户，禁止生成建库/建表/插入数据等任何写操作 SQL，禁止主动询问用户是否需要造数
3. **SQL 注入防护**：用户输入不直接拼接到 SQL 中，通过参数化或严格校验处理
4. **数据量控制**：生成 SQL 时对预估大结果集的查询主动加 `LIMIT 1000`
5. **敏感数据提示**：如果查询结果可能包含个人隐私数据（手机号、身份证等），在输出前提醒用户注意数据安全
6. **只读操作**：本 Skill 不直接连接集群执行 SQL，也不保存任何集群凭据

## 检查清单（各步骤执行前自动验证）

### 步骤 0：参数确认检查清单

- [ ] 确认 `instance_id` 和 `region_id` 参数是否齐全
- [ ] 如果用户提供中文地域名称，是否已按地域映射表转换
- [ ] 是否需要通过 `ask_user` 询问缺失参数

### 步骤 1：集群信息确认检查清单

- [ ] 集群状态是否为 `Serving`
- [ ] `TCHouseDDescribeInstance` 调用是否成功

### 步骤 2：表结构获取检查清单

- [ ] 目标库表名是否已确定（从用户描述提取、从上下文推断或通过 `ask_user` 确认）
- [ ] **目标库是否命中系统库黑名单**（`mysql` / `information_schema` / `__internal_schema` / `sys`）；命中则终止业务分析，不再拉 DDL
- [ ] **DDL 返回的 `ENGINE` 是否为 `OLAP`**；非 `OLAP`（如 `SCHEMA` / `MYSQL`）视为系统/元数据表，同样终止
- [ ] `TCHouseDDescribeDDL` 是否已拉取到目标表的完整结构（列名、类型、KEY 列、分区键、分桶键等）
- [ ] 是否避免了基于维度/指标猜测表名

### 步骤 3：SQL 生成检查清单

- [ ] WHERE 条件是否包含分区键过滤（避免全分区扫描）
- [ ] **是否已按步骤 3.2.1 做过分区覆盖预校验**（对比 DDL 中分区区间与用户所述时间窗），分区错配时是否主动告知用户并给出兜底方案 A/B
- [ ] 是否避免使用 `SELECT *`
- [ ] 时间范围是否使用动态函数（`NOW()`、`CURDATE()` 而非硬编码）
- [ ] 中文列名是否用反引号包裹
- [ ] 非聚合查询是否添加了 `LIMIT`
- [ ] 复杂查询是否需要用户确认（多表 JOIN、子查询等）

### 步骤 4：SQL 输出与手工执行指引检查清单

- [ ] SQL 语句是否以完整可复制的形式输出给用户
- [ ] 是否向用户提供了到 SQL 工作区手工执行的指引
- [ ] 是否提醒用户回贴执行结果（结构化数据或错误信息）
- [ ] 结果预估数据量大时是否主动在 SQL 中加了 LIMIT 1000

### 步骤 5：可视化检查清单

- [ ] **若结果为 0 行**：是否已按 §5.0 回溯步骤 3.2.1 分区覆盖校验，排除分区错配后才判定为"业务无数据"
- [ ] 图表类型是否匹配数据特征和分析意图
- [ ] 是否优先使用 `show_widget` 工具直接渲染 Chart.js 图表
- [ ] 时间序列数据是否推荐折线图
- [ ] 分类占比数据是否推荐饼图/柱状图
- [ ] 多维度对比是否推荐分组柱状图/多折线图
- [ ] 图表标签是否使用中文

### 步骤 6：结论生成检查清单

- [ ] 结论是否使用中文面向业务人员
- [ ] 数字是否使用千分位分隔
- [ ] 是否包含核心发现、数据支撑、趋势判断
- [ ] 是否避免使用技术术语

## 高频经验提醒

| 经验                    | 触发时机                  | 说明                                                                                                                                                   |
| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 本 Skill 不直接执行 SQL | 步骤 4 开始前             | Skill 仅输出 SQL 与手工执行指引，由用户到 SQL 工作区执行后回贴结果，Agent 再做可视化与结论分析                                                         |
| 时间过滤必须命中分区键  | 步骤 3 生成 SQL 时        | WHERE 条件必须包含分区键字段，优先使用 `NOW()`/`CURDATE()` 等动态函数                                                                                  |
| 分区覆盖必须先校验      | 步骤 3.2.1 生成时间过滤前 | 生成 WHERE 时间条件前必须用 DDL 中的分区区间与用户所述时间窗做交集；交集为空时必须提供兜底方案 A/B 并请用户确认，不得静默返回 0 行并归因为"无业务数据" |
| 系统库不走业务分析      | 步骤 2.1.1 校验时         | `mysql` / `information_schema` / `__internal_schema` / `sys` 等为 Doris 内置元数据库，命中后直接告知用户并终止业务分析，不拉 DDL、不作可视化           |
| 中文列名需要反引号      | 步骤 3 生成 SQL 时        | Doris 中文列名必须用反引号包裹，否则语法错误                                                                                                           |
| 库表名必须用户明确提供  | 步骤 2 开始前             | 禁止基于维度/指标猜测表名；表信息必须由用户提供或从 DDL 确认                                                                                           |
| 地域缺失必须询问        | 步骤 0 参数确认时         | 不要自动猜测地域，按地域映射表转换或询问用户                                                                                                           |