Tchoused Slow Sql Diagnosis

---
name: 腾讯云TCHouse-D 慢 SQL 诊断与自动调优
description: >
  TCHouse-D（Doris）慢 SQL 诊断与自动调优 Skill。AI 自动检索指定集群的慢查询日志，对业务 SQL 模式（排除元数据/会话语句与后台系统任务）基于 SQL 文本与建表 DDL 做静态分析，识别性能瓶颈（全表扫描/JOIN 顺序不优/索引缺失/数据倾斜），生成 SQL 改写方案；若需 EXPLAIN 验证执行计划，则建议用户到控制台 SQL 工作区手动执行。若慢查询样本全部为系统 SQL，则明确给出「业务侧无慢查询」的结论并指引调度参数调优。
  触发词：慢查询、慢SQL、slow query、SQL优化、查询优化、执行计划、EXPLAIN、查询耗时、查询超时、SQL调优、索引优化、全表扫描、数据倾斜、JOIN优化、查询性能、SQL性能、query performance、查询变慢、报表变慢、Doris优化、TCHouse-D优化、cdwdoris、查询诊断、SQL诊断、Bucket倾斜、物化视图。
  本 Skill 包含 3 个子能力：①慢查询 Top N 检索与趋势分析 ②基于 SQL 文本 + DDL 的静态瓶颈识别 ③SQL 改写与索引优化方案生成。
  何时不触发：集群选型与架构推荐、智能建表与数据建模、NL2SQL、集群健康诊断与故障排查（监控指标/告警/节点故障）、集群扩缩容、权限管理、数据导入导出等非查询性能相关问题不走本 Skill。
allowed-tools:
  - TCHouseDDescribeInstance
  - TCHouseDDescribeSlowQueryRecords
  - TCHouseDDescribeOnlineQueryLoads
  - TCHouseDDescribeDDL
  - TCHouseDDescribeClusterConfigs
  - ask_user # WorkBuddy 中为 AskUserQuestion
---

# 慢 SQL 诊断与自动调优

## 概述

本 Skill 提供 TCHouse-D（Doris）集群的慢 SQL 诊断与自动调优能力，包含三个子能力：

1. **慢查询 Top N 检索与趋势分析**：检索慢查询日志，分析趋势判断是突发还是持续恶化
2. **基于 SQL 与 DDL 的静态瓶颈定位**：从慢 SQL 文本与建表 DDL 判断全表扫描/JOIN 不优/分区裁剪失败等问题（如需 EXPLAIN 验证，在报告中提示用户到控制台手动执行）
3. **SQL 改写与索引优化方案生成**：生成 SQL 改写、Bloom Filter 索引、Bucket 调整、物化视图等优化建议

## 默认参数速查

> 💡 用户未显式指定时使用下表默认值。详细语义见【步骤 0：参数确认】与【步骤 2：获取慢查询数据】。

| 参数       | 默认值    | 说明                                                                                        |
| ---------- | --------- | ------------------------------------------------------------------------------------------- |
| 时间范围   | 最近 7 天 | 覆盖一个完整业务周期，兼顾趋势判断与调用成本                                                |
| 慢查询阈值 | 3000ms    | 对齐 TCHouse-D 控制台默认；BI/交互场景可下调至 1000ms，Ad-hoc/离线场景可上调至 5000~10000ms |
| Top N      | 10        | 单次拉取的慢查询条数；步骤 3.5 归一化去重后重点分析前 3~5 个 SQL 模式                       |

## 依赖与运行环境

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

> 💡 **工具名约定**：本 Skill `allowed-tools` 中列出的是 MCP 工具的**原始名**（如 `TCHouseDDescribeInstance`）。
> 部分平台（如 Claude Code / WorkBuddy）会自动加上 `mcp__<server>__` 前缀。
> 在 WorkBuddy 中实际工具名为 `mcp__tchoused-cloudapi-cross-region-mcp-server__TCHouseDDescribeInstance`，
> Agent 可直接按此完整名调用，无需先执行 ToolSearch。

**依赖工具清单**：

| #   | Tool 名称                        | 能力定位                                         | 参考文档                                                         |
| --- | -------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
| 1   | TCHouseDDescribeInstance         | 集群信息获取                                     | [参考](references/tchoused-describe-instance.md)           |
| 2   | TCHouseDDescribeSlowQueryRecords | 慢查询明细检索                                   | [参考](references/tchoused-describe-slow-query-records.md) |
| 3   | TCHouseDDescribeOnlineQueryLoads | 正在运行的查询负载                               | [参考](references/tchoused-describe-online-query-loads.md) |
| 4   | TCHouseDDescribeDDL              | 获取表 DDL（用于静态分析 SQL 与表结构匹配关系）  | [参考](references/tchoused-describe-ddl.md)                |
| 5   | TCHouseDDescribeClusterConfigs   | 集群配置参数                                     | [参考](references/tchoused-describe-cluster-configs.md)    |
| 6   | ask_user                         | 向用户询问确认（WorkBuddy 中为 AskUserQuestion） | —                                                                |

> 💡 **设计说明**：Doris 没有独立的 `ExplainSQL` 接口和 `SlowQueryTrend` 接口。本 Skill **不再自动执行 EXPLAIN**；瓶颈定位基于「SQL 文本 + 建表 DDL」的静态分析，如需 EXPLAIN 验证则在报告中提示用户到控制台 SQL 工作区手动执行；趋势分析基于 `TCHouseDDescribeSlowQueryRecords` 的多次时间分段查询合并完成。

## 凭证 / 环境变量

- `instance_id`：从会话 context 的 X-Context header 自动注入
- `region_id`：从会话 context 的 X-Context header 自动注入（可能是 `RegionId` 数字，也可能是 `Region` 字符串，也可能是中文地域名）
- 若以上参数缺失，通过 `ask_user`（WorkBuddy 中为 `AskUserQuestion`）询问用户

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

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

## 核心工作流

### 步骤 0：参数确认

**必需参数**：

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

**可选参数**：

- 时间范围：未指定 → 默认最近 7 天
- 慢查询阈值：未指定 → 默认 3000ms（对齐 TCHouse-D 控制台默认值；BI/交互场景可下调至 1000ms，Ad-hoc/离线场景可上调至 5000~10000ms）
- Top N 条数：未指定 → 默认 10

**判断逻辑**：

- ✅ 参数齐全 → **强制**按 [地域映射表](references/region-mapping.md) 把地域补齐为 `Region`（字符串）+ `RegionId`（数字）两种形式（任何输入形式都要过这一步：中文名、英文串、数字 ID 都不例外），补齐后进入步骤 1
- ❌ `instance_id` 或 `region_id` 缺失 → 调用 `ask_user` 询问
- ❌ 地域信息在映射表中匹配不到（或大区模糊，如"华南地区"）→ 调用 `ask_user` 确认后再补齐

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

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

**判断逻辑**：

- ✅ 集群状态为 `Serving` → 进入步骤 1.5
- ❌ 集群状态异常（`Init`/`Changing`）→ 告知用户集群当前不可用，建议等待恢复后重试
- ❌ 集群状态 `Isolated` → 终止诊断
- ❌ 调用失败（AuthFailure）→ 报告错误，提示检查权限
- ❌ 调用失败（ResourceNotFound）→ 检查 instance_id 格式（`cdwdoris-` 前缀），格式错则修正重试

**记录信息**：Doris 内核版本号（影响 EXPLAIN 输出格式，2.0+ 支持 `EXPLAIN VERBOSE`/`EXPLAIN GRAPH`）、FE/BE 节点规格和数量。

### 步骤 1.5：集群健康速检与诊断深度预判

> 💡 **设计目的**：诊断深度（轻量 vs 深度）与集群当前健康度强相关。健康集群上做深度执行计划分析的 ROI 较低，应先做一次快速预检以决定后续投入。

**输入**：步骤 1 返回的 `Status` 字段、`InstanceStateInfo`（如有）、节点规格。

**操作**：基于步骤 1 已返回的字段做轻量预检——本步骤 **不**再调用额外接口，仅基于已有数据做判定（如需要更细颗粒的健康指标，由用户显式要求时再扩展）。

**判定矩阵**：

| 输入信号                                                         | 预判结论                      | 后续动作                                                                  |
| ---------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------- |
| 集群 `Serving` 且后续步骤 2 日均慢查询 ≤ 10 条/天                | **健康集群**，深度分析 ROI 低 | 进入【轻量报告模式】：步骤 4 仅对 Top 1-2 条 EXPLAIN，步骤 6 输出精简报告 |
| 集群 `Serving` 且日均慢查询 10~500 条/天                         | 常规诊断                      | 进入【标准模式】，正常执行步骤 2~6                                        |
| 集群 `Serving` 但日均慢查询 > 500 条/天，或步骤 2 中位耗时 > 30s | 集群压力大                    | 进入【深度模式】：步骤 4 EXPLAIN Top 5 条 + 步骤 5 强制纳入完整配置巡检   |
| 集群非 `Serving`                                                 | 异常，已在步骤 1 处理         | —                                                                         |

> ⚠️ 健康度判定需要步骤 2 的统计数据，因此本步骤的最终深度结论会在拿到步骤 2 结果后回填。Agent 在执行步骤 2 时应同时记录 `TotalCount`、查询天数、平均/中位耗时三项基础指标，并在进入步骤 3.5 之前显式给出「本次诊断模式：轻量 / 标准 / 深度」+ 判定依据。

### 步骤 2：获取慢查询数据

调用 `TCHouseDDescribeSlowQueryRecords`。

**参数确定策略**：

- 时间范围：根据用户描述（"最近一周" → 7天，"昨天" → 昨天0点到今天0点）
- 慢查询阈值（QueryDurationMs）：用户指定则按用户要求，未指定默认 3000ms
- PageSize：默认 10
- 排序：按耗时降序

**判断逻辑**：

- ✅ 返回有数据 → 进入步骤 3
- ❌ 返回为空 → 告知用户，建议：1) 扩大时间范围 2) 降低阈值
- ❌ 慢查询日志未开启 → 提供开启步骤指引（控制台 → 集群详情 → 参数配置 → `enable_query_log`），告知需等待数据积累
- ❌ 调用超时 → 等 3 秒重试，最多 3 次；仍失败则告知用户服务暂时不可用

**强制输出**：本步骤完成后，**必须**在分析记录与最终报告中明确给出趋势结论，二选一即可：「**稳定** / **恶化** / **突发** / **改善**」+ 判定依据（如各时间分段的 TotalCount/平均耗时对比、最近 1 天与中间/最早 1 天的比值等）。无论是否执行了多分段采样都要给出结论；若数据量过小不足以判断，须显式说明"数据量不足，暂不下结论"并给出原因。

**辅助步骤（趋势分析，可选）**：Doris 无独立 SlowQueryTrend 接口，可对 `TCHouseDDescribeSlowQueryRecords` 在不同时间分段（如最近 1 天 + 中间 1 天 + 最早 1 天）多次调用并比较 TotalCount，判断慢查询是突发性还是持续恶化。

**小样本兜底（重要）**：如果时间范围内**全量样本数 < 5 条**：

- ✅ **跳过**所有统计聚合操作（不计算 P95/平均耗时、不做趋势分段、不做 Top-N 排序）
- ✅ 直接进入**逐条深度分析模式**：步骤 3.5 不去重（样本本身就少，去重无意义），步骤 4 对每一条都做完整 EXPLAIN + DDL 分析
- ✅ 步骤 5（集群健康/配置巡检）改为**强制执行**，补足样本不足导致的诊断维度
- ⚠️ 报告中**禁止**输出形如「P95 = xxx ms」「平均耗时 = xxx ms」这类基于 < 5 条样本计算的伪统计指标；必须显式标注「样本数过少（n=X），未做统计聚合」

> ⚠️ **调用策略**：根据 `TotalCount` 和查询天数计算**日均慢查询数 = TotalCount ÷ 天数**：
>
> | 日均慢查询数 | 策略                                             |
> | ------------ | ------------------------------------------------ |
> | ≤ 50 条/天   | **直接查整个时间段**（如 7 天一次性查）          |
> | 50~500 条/天 | **采样 3 天**：最近 1 天 + 中间 1 天 + 最早 1 天 |
> | > 500 条/天  | **只查最近 1 天**                                |

### 步骤 3：检查当前运行查询（条件触发）

**触发条件**：用户描述"正在发生"的问题（如"现在查询很慢"）。

调用 `TCHouseDDescribeOnlineQueryLoads` 查看当前长耗时 SQL，辅助判断锁等待、资源争抢、死循环查询。

**判断逻辑**：

- ✅ 有长耗时查询 → 纳入分析范围
- ✅ 无异常 → 继续步骤 3.5
- ❌ 调用失败 → 跳过此步骤，基于历史慢查询数据继续分析

### 步骤 3.5：SQL 模式归一化与去重

对步骤 2 返回的 Top N 慢查询记录进行归一化去重。

**归一化规则**（按顺序应用）：

1. 字符串字面量替换为 `'?'`
2. 数字字面量替换为 `?`
3. `IN (...)` 列表替换为 `IN (?)`
4. 去除多余空白、统一为单空格
5. 转为小写后比较

**去重与聚合**：

- 归一化后 SQL 文本相同的记录归为同一**SQL 模式**
- 每个模式记录：出现次数、最大耗时、平均耗时、最近一次执行时间
- 按**最大耗时降序**排列

**判断逻辑**：

- ✅ 去重后有 ≥ 3 个不同模式 → 取前 3-5 个进入步骤 4
- ⚠️ 去重后只有 1-2 个模式 → 重点分析高频模式，可翻页或降阈值补充
- ❌ 翻页后仍只有 1 个模式 → 只分析该模式，但在报告中重点标注高频特征

**系统级任务的分类处理**（按场景区分，避免一刀切跳过）：

Doris 慢查询日志中常见的「系统级 SQL」需要按以下两类处理。**两类系统 SQL 都跳过 EXPLAIN**（EXPLAIN 对系统 SQL 无业务改写价值），区别在于报告中是否要给出调度参数优化建议：

| 类别                | 典型 SQL                                                                                                                            | EXPLAIN 策略                                                                       | 优化方向                                                                                                                                                                            | 报告标注                                                                                                                         |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **A. 元数据/会话**  | `SHOW ...`、`USE <db>`、`DESC ...`、`SELECT @@version_comment`、JDBC 心跳查询                                                       | **跳过 EXPLAIN**                                                                   | **无需优化**（语句本身耗时通常 < 10ms，进入慢查询多半是网络抖动或瞬时压力）                                                                                                         | 报告中合并为一行："识别到 X 条元数据/会话类系统语句，已跳过"                                                                     |
| **B. 后台系统任务** | `INSERT INTO __internal_schema.column_statistics ...`（ANALYZE 任务）、`CREATE ROUTINE LOAD`、Compaction 相关 SQL、内置统计回写 SQL | **跳过 EXPLAIN**（系统任务执行路径固定，EXPLAIN 出的是内部 plan，无 SQL 改写空间） | **聚焦调度/资源参数**（如 `analyze_task_concurrency`、`auto_analyze_table_width_threshold`、`max_cumu_compaction_threads`、`routine_load_thread_pool_size`），**不出 SQL 改写建议** | 报告中明确标注："这是系统任务（ANALYZE/Routine Load/Compaction），不做 EXPLAIN；优化路径在调度参数，详见步骤 5 的集群配置巡检表" |

**判定逻辑**：

- ✅ 模式属于 A 类 → 跳过该模式的 EXPLAIN，不出任何优化建议，但**不要**因此而跳过整个步骤 4，应继续分析其他模式
- ✅ 模式属于 B 类 → 跳过 EXPLAIN，但**必须**进入步骤 5 做配置巡检，并在步骤 6 报告中给出调度参数优化建议（关联到具体配置项当前值/默认值/建议值）
- ⚠️ **当所有模式都属于 A 类时**：直接跳到步骤 5（仅做最小化配置巡检）和步骤 6，**最终结论必须明确为「业务侧无慢查询，集群健康」**，不要给出形如"集群存在性能问题"的误导性表述。具体话术参考步骤 6 的「全 A 类收尾模板」
- ⚠️ **当所有模式都属于 B 类时**（如 ANALYZE 占满）：跳过所有 EXPLAIN，**且步骤 5 的集群配置巡检由「默认执行」升级为「强制执行」**，必须输出完整的调度参数诊断表。最终结论必须明确为「业务侧无慢查询，慢查询全部来自后台系统任务，建议调优调度参数」
- ⚠️ **当 A+B 类合计占比 ≥ 80%** 且业务 SQL < 3 条时：在报告开头显著位置标注「业务侧慢查询样本极少（n=X），集群整体健康；以下分析聚焦在系统任务调度参数」

### 步骤 4：逐条分析慢 SQL（仅业务 SQL 模式）

> ⚠️ **入口前置条件**：本步骤**仅处理**步骤 3.5 判定后剩余的**业务 SQL 模式**。A 类（元数据/会话）和 B 类（ANALYZE/Compaction/Routine Load 等后台系统任务）模式已在步骤 3.5 决定跳过瓶颈分析，**不要**重新进入本步骤。若步骤 3.5 已判定为「全 A 类」或「全 B 类」，直接跳到步骤 5。

对步骤 3.5 输出的每个**业务 SQL 模式**：

> 💡 **并行化提示**：4.1（SQL 文本解析）和 4.2（DDL 获取）无依赖，可并行；步骤 5（集群配置）也可并行启动。

**4.1 SQL 文本解析与初步瓶颈线索**：

对 SQL 文本本身做结构化解析，提取以下关键要素，作为 4.3 瓶颈识别的输入：

- 涉及的表名列表（用于步骤 4.2 拉取 DDL）
- WHERE 子句中的谓词字段与条件类型（等值 / 范围 / LIKE / IN 等）
- JOIN 结构（表数量 / JOIN 键 / 是否显式指定 hint）
- 是否存在 `SELECT *`、深分页、跨表子查询、嵌套聚合等模式

> 💡 **执行计划补充建议**：本 Skill 不自动执行 EXPLAIN。若 4.3 判定的瓶颈类型需要 EXPLAIN 佐证（如分区裁剪是否生效、Runtime Filter 是否命中、统计信息是否过期），在最终报告中提示用户到控制台 SQL 工作区手动执行 `EXPLAIN <SQL>` 或 `EXPLAIN VERBOSE <SQL>` 进一步确认。

**判断逻辑**：

- ✅ SQL 解析成功 → 进入 4.3
- ❌ SQL 语法错误/表已删除 → 跳过该条，继续下一条

**4.2 获取表 DDL**：

从 SQL 中提取涉及的表名，调用 `TCHouseDDescribeDDL` 获取建表 DDL。

> ⚠️ **TableName 必须为三段式**：`catalog.database.table`（默认 catalog 为 `internal`，例如 `internal.demo_db.orders`）。若 SQL 中只出现库.表两段或仅表名，需要补全为三段式后再调用，否则接口可能返回 `InvalidParameter` 或空 DDL。

**判断逻辑**：

- ✅ 成功 → 进入 4.3
- ❌ 表已删除/权限不足 → 跳过表结构分析，基于执行计划给出有限建议

**4.3 瓶颈识别**：

按 [分析框架](references/analysis-framework.md#1-性能瓶颈识别) 识别问题类型（全表扫描、Bucket 倾斜、JOIN 顺序、未走索引等），生成对应优化建议（详见 [优化方案模板](references/optimization-templates.md)）。

### 步骤 5：检查集群配置（默认执行）

> 💡 **执行策略**：本步骤为**默认执行**，与步骤 4 并行启动。

调用 `TCHouseDDescribeClusterConfigs` 获取 FE/BE 配置。

**关键配置项必查清单**（**必须**逐项检查并在报告中标注实际值与默认值的差异；缺失视为使用默认值）：

| 配置项                                 | 所属 | 默认值  | 关注原因                                             | 关联场景                 |
| -------------------------------------- | ---- | ------- | ---------------------------------------------------- | ------------------------ |
| `qe_max_connection`                    | FE   | 1024    | 连接数瓶颈                                           | 高并发                   |
| `max_running_txn_num_per_db`           | FE   | 1000    | 写入并发                                             | 导入慢                   |
| `default_replication_num`              | FE   | 3       | 副本数                                               | 写放大                   |
| `parallel_fragment_exec_instance_num`  | FE   | 8       | 单查询并行度                                         | 大查询                   |
| `analyze_task_concurrency`             | FE   | 2       | ANALYZE 任务并发数                                   | ANALYZE 慢、统计回写慢   |
| `auto_analyze_table_width_threshold`   | FE   | 100     | 自动 ANALYZE 表宽度（列数）阈值，超过则跳过自动分析  | ANALYZE 慢、宽表统计缺失 |
| `huge_table_default_sample_rows`       | FE   | 4194304 | 大表自动 ANALYZE 时的采样行数（默认 4M 行）          | ANALYZE 慢、统计精度     |
| `huge_table_lower_bound_size_in_bytes` | FE   | 0       | "大表"判定下限（字节）。超过此值采用采样而非全量分析 | ANALYZE 慢、统计成本     |
| `mem_limit`                            | BE   | 80%     | BE 内存上限                                          | OOM                      |
| `query_max_memory_limit_percent`       | BE   | 90%     | 单查询内存占比                                       | 大查询 OOM               |
| `enable_cpu_hard_limit`                | BE   | false   | CPU 硬限制                                           | 资源隔离                 |
| `compaction_task_num_per_disk`         | BE   | 4       | Compaction 并发                                      | 写入抖动                 |
| `max_cumu_compaction_threads`          | BE   | 10      | Cumu Compaction 线程数                               | 写入抖动                 |
| `tablet_max_compaction_score`          | BE   | 2000    | Tablet Compaction 上限                               | 读放大                   |
| `storage_flood_stage_usage_percent`    | BE   | 90      | 磁盘水位告警阈值                                     | 磁盘满                   |
| `routine_load_thread_pool_size`        | BE   | 10      | Routine Load 线程池                                  | 系统级任务慢             |

> 💡 **ANALYZE 调度参数调优指引**（当步骤 3.5 识别为 B 类 ANALYZE 任务集中时使用）：
>
> - `analyze_task_concurrency` 默认 2 偏保守，宽表多/统计任务积压时可调至 4~8（不超过 FE CPU 核数的一半）
> - `auto_analyze_table_width_threshold` 默认 100 会导致超宽表（列数 > 100）的自动统计被跳过，影响 CBO 准确性；如业务有宽表，可调至 300~500
> - `huge_table_default_sample_rows` 默认 4M 行对超大表足够，但若发现统计估算明显偏差（EXPLAIN 中估算行数与实际相差 > 10 倍），可调至 8M~16M
> - `huge_table_lower_bound_size_in_bytes` 默认 0 表示所有表都按 huge 处理（采样而非全量）；若小表统计也想全量精确，可设为 5GB（`5368709120`）

**判断逻辑**：

- ✅ 成功获取并解析出配置值 → 逐项与上表默认值对照，**与步骤 4 的瓶颈和步骤 3.5 的 SQL 类型显式关联**（例如：发现 ANALYZE 慢 + `analyze_task_concurrency=2` 是默认值 → 建议调高）
- ⚠️ 目标配置项不存在 → 标注"使用默认值"，仍纳入分析
- ❌ 接口调用失败 → 跳过配置分析，报告中注明
- 🔴 当步骤 3.5 判定为「全 B 类系统级任务」或「样本数 < 5」时，本步骤升级为**强制执行且必须输出完整配置巡检表**

### 步骤 6：综合分析与生成报告

按 [输出报告格式](references/analysis-framework.md#3-输出报告格式) 生成诊断报告。

**报告必须包含**：

1. 集群概况（ID/版本/状态）
2. **诊断模式标注**（轻量 / 标准 / 深度，来自步骤 1.5）+ 判定依据
3. 慢查询概览（时间范围 / 总数 / 平均耗时 / 中位耗时；样本 < 5 时改为「样本清单 + 标注未做统计聚合」）
4. 趋势分析（突发 / 持续恶化 / 稳定 / 改善 / 数据不足，必须四选一并给依据）
5. 逐条诊断（SQL 文本 / 耗时 / 瓶颈 / 优化建议；A 类元数据语句合并为一行说明且无优化建议；B 类系统任务跳过 EXPLAIN 并指向调度参数）
6. **集群配置巡检表**（步骤 5 的关键配置项必查清单，逐项列出「实际值 / 默认值 / 是否异常」）
7. 综合优化建议（**强制使用 P0/P1/P2 三级优先级**，每条必须带「预期收益」和「实施成本」两个维度，详见 [报告模板](references/analysis-framework.md#3-输出报告格式)）

**全系统 SQL 收尾结论模板**（当步骤 3.5 判定全部为 A 类或 A+B 类时**必须**使用，禁止给出"集群存在慢查询问题"等误导性表述）：

- **全 A 类**（全部为元数据/会话语句）：
  > 📊 **诊断结论：业务侧无慢查询，集群非常健康**
  >
  > 本次时间范围内检索到的 X 条"慢查询"全部为 `SHOW`/`USE`/`DESC`/JDBC 心跳等元数据/会话类语句（典型耗时 < 10ms，进入慢查询日志多为网络抖动或瞬时压力，无业务影响）。**集群侧没有需要优化的业务 SQL**，建议关注业务侧是否有偶发网络抖动即可。
- **全 B 类**（全部为 ANALYZE/Compaction/Routine Load 等后台任务）：
  > 📊 **诊断结论：业务侧无慢查询，集群健康；慢查询全部来自后台系统任务**
  >
  > 本次 X 条慢查询全部为后台系统任务（ANALYZE 统计回写 / Compaction / Routine Load 等），与业务 SQL 无关，**不存在业务侧性能问题**。如系统任务耗时过长影响后台调度，可参考步骤 5 的集群配置巡检表调优调度参数（如 `analyze_task_concurrency`、`max_cumu_compaction_threads`）。
- **A+B 类合计 ≥ 80%** 且业务 SQL < 3 条：
  > 📊 **诊断结论：业务侧慢查询样本极少（n=X），集群整体健康**
  >
  > 大部分慢查询样本来自系统任务/元数据语句，业务 SQL 仅 X 条，样本量不足以判定业务侧普遍性能问题。本次报告聚焦在系统任务调度参数优化，业务 SQL 仅做点查式分析。

> ⚠️ **优先级标注规范（强制）**：所有优化建议**必须**使用 `P0`/`P1`/`P2` 而不是 `⭐⭐⭐`、`高/中/低`、`重要/次要`等其他写法。定义如下：
>
> - `P0`：直接影响业务（OOM / 查询失败 / 阻塞），需立即处理
> - `P1`：明显的性能瓶颈，建议本周内处理
> - `P2`：可观察性/工程化优化，可排期处理

## 频率控制

| 限制                                  | 阈值         | 说明             |
| ------------------------------------- | ------------ | ---------------- |
| 工具总调用频率                        | ≤ 10 次/分钟 | 避免触发平台限流 |
| TCHouseDDescribeSlowQueryRecords 翻页 | ≤ 3 次/轮    | 避免拉取过多数据 |

**超限处理**：连续收到 `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 次 → 降低频率，告知被限流                                                                                                                                                         |
| 表 DDL 获取失败        | 跳过表结构分析，基于执行计划和 SQL 文本给出有限建议                                                                                                                                                   |
| 集群配置获取失败       | 跳过配置分析，基于已有数据给出建议                                                                                                                                                                    |
| 网络超时               | 查询类操作等 3 秒重试，最多 3 次；仍失败 → 告知用户服务暂时不可用                                                                                                                                     |
| 兜底（未列出错误码）   | 报告完整错误信息 + RequestId                                                                                                                                                                          |

## 安全规则

1. **本 Skill 为纯只读诊断**：所有操作均为查询类（Describe），不涉及写操作
2. **SQL 脱敏**：输出报告中的 SQL 文本可能包含敏感数据，如实展示但不额外暴露
3. **凭据安全**：不在输出中展示任何凭据信息
4. **数据量控制**：Top N 不超过 10 条，重点分析前 3-5 条

## 经验沉淀库

| 经验                                             | 置信度 | 说明                                                                                |
| ------------------------------------------------ | ------ | ----------------------------------------------------------------------------------- |
| 分区键未命中是最常见的慢查询原因                 | ⭐⭐⭐ | WHERE 未含分区键 → 全分区扫描；通过 EXPLAIN 看 `partitions=N/N` 判断                |
| Bucket 数量不合理导致数据倾斜                    | ⭐⭐⭐ | 单 Tablet 过大（> 5GB）会拖慢查询；建议单 Tablet 1-3GB                              |
| SELECT \* 在宽表上性能极差                       | ⭐⭐⭐ | Doris 列存，SELECT \* 读取所有列；应只选需要的列                                    |
| 大表 JOIN 小表时应将小表放右侧（Broadcast）      | ⭐⭐⭐ | 默认会自动选择，但有时优化器误判，可用 `[broadcast]` hint 强制                      |
| Bloom Filter 索引对高基数等值查询效果好          | ⭐⭐   | 高基数列（如 user_id、order_no）等值过滤建议加 BF 索引                              |
| 倒排索引适合字符串模糊匹配                       | ⭐⭐   | 2.0+ 支持 INVERTED INDEX，替代 LIKE '%xx%' 全表扫描                                 |
| 物化视图可加速固定模式聚合查询                   | ⭐⭐   | 高频聚合查询（如按天 GROUP BY）建物化视图，毫秒级响应                               |
| Runtime Filter 失效会导致 Hash Join 性能差       | ⭐⭐   | 检查 EXPLAIN 中的 `runtime filters`；可通过 session 变量 `runtime_filter_type` 调整 |
| Colocate Join 比 Shuffle Join 快                 | ⭐⭐   | 高频 JOIN 的两张表建议放同一 Colocate Group，避免数据 shuffle                       |
| `EXPLAIN VERBOSE` 看实际行数差异判定统计信息过期 | ⭐⭐⭐ | 估算行数与实际相差大 → 执行 `ANALYZE TABLE` 更新统计信息                            |