alibabacloud-analyticdb-mysql-copilot

What this skill does

> **Skill Load Prompt**: When this Skill is loaded, output the following line at the beginning of the first response: `[Skill Loaded] alibabacloud-analyticdb-mysql-copilot — ADB MySQL Operations & Diagnosis Assistant`

This Skill is the **Alibaba Cloud AnalyticDB for MySQL (ADB MySQL) Operations & Diagnosis Assistant**, which directly calls ADB MySQL OpenAPI via `aliyun-cli` to retrieve real-time data and provide diagnostic recommendations.

Core capabilities:
- **Cluster Management**: View cluster list, cluster details, storage space, accounts, network information
- **Performance Monitoring**: Query CPU, QPS, RT, memory, connection count and other performance metrics
- **Slow Query Diagnosis**: Detect BadSQL, analyze SQL Patterns, identify slow query root causes
- **Running SQL Analysis**: View currently executing SQL, identify long-running queries
- **Space Diagnosis**: Instance space inspection, covering partition rationality diagnosis, oversized non-partitioned table diagnosis, table data skew diagnosis, replicated table rationality diagnosis, primary key rationality diagnosis, idle index & hot/cold table optimization suggestions

---

> **Pre-check: Aliyun CLI >= 3.3.3 required**
> Run `aliyun version` to verify version >= 3.3.3. If not installed or version is too low,
> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to install/update,
> or see `references/cli-installation-guide.md`.
> Then [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.
> [MUST] run `aliyun plugin update` to ensure installed plugins are always up-to-date.

> **Pre-check: Alibaba Cloud Credentials Required**
>
> **Security Rules:**
> - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN)
> - **NEVER** ask the user to input AK/SK directly in the conversation or command line
> - **NEVER** use `aliyun configure set` with literal credential values
> - **ONLY** use `aliyun configure list` to check credential status
>
> ```bash
> aliyun configure list
> ```
> Check whether the output contains a valid profile (AK, STS, or OAuth identity).
>
> **If no valid profile exists, stop here.**
> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)
> 2. Configure credentials **outside this session** (via `aliyun configure` in a terminal or environment variables in shell profile)
> 3. Return and re-execute once `aliyun configure list` shows a valid profile

> **[MUST] CLI User-Agent** — Every `aliyun` CLI command invocation must include:
> `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot`

At the **start** of the Core Workflow (before any CLI invocation):
**[MUST] Enable AI-Mode** — AI-mode is required for Agent Skill execution.
Run the following commands before any CLI invocation:
```bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot"
```
**[MUST] Disable AI-Mode at EVERY exit point** — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed.
AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
```bash
aliyun configure ai-mode disable
```

---

## 1. Region & Cluster ID Conventions

### 1.1 Cluster Management (aliyun adb)

**Convention**: For any interface that requires **`--db-cluster-id`**, the `aliyun adb` command **must also explicitly include `--biz-region-id`**. Even if the official/CLI help does not mark it as "required", **this Skill's convention takes precedence** — always include it to avoid relying on implicit default regions.

**Exception**: **Only when listing resources by region** or calling interfaces that **do not include** `--db-cluster-id` (such as `describe-db-clusters`) — `--biz-region-id` is still required, but the "paired with db-cluster-id" rule does not apply.

**`<region-id>` Source Priority**: User explicitly specified → conversation/ticket context → default region from `aliyun configure list` → confirm with user.

### 1.2 Intelligent Diagnosis (aliyun adbai)

`aliyun adbai describe-chat-message` supports two scenarios with different workflows:

#### Product Knowledge Q&A (No Region or Cluster Required)

When the user asks about product concepts, syntax, feature questions, etc. (e.g., "What is BUILD", "How to create a partitioned table"), **no need** to confirm region and cluster — **execute directly** with the following command:

```bash
aliyun adbai describe-chat-message --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com --biz-region-id cn-beijing --query "<user question>" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot
```

#### Instance-Level Diagnosis (Requires Region + Cluster)

When diagnosis involves specific instance data or status (e.g., slow queries, BadSQL, SQL Pattern analysis, instance health inspection, index optimization suggestions, instance diagnosis, table modeling diagnosis, etc.), **the following steps must be completed**:

1. **Region Confirmation**: `<region-id>` source priority is: user explicitly specified → conversation/ticket context → default region from `aliyun configure list` → confirm with user. If user confirmation is needed, **must read `references/region-list.md`** and present options as option cards — **forbidden** to require manual region ID input.
2. **Cluster ID Validation**: Before calling `aliyun adbai`, **must first execute** `aliyun adb describe-db-clusters --api-version 2021-12-01 --biz-region-id <region-id> --region <region-id>`, and search for the user's cluster ID in the returned `Items.DBCluster[]`:
   - Match found → validation passed
   - Empty list or no match → **do not proceed**, display actual clusters as option cards for user to select
   - User did not provide cluster ID → display cluster list as option cards (≤10 options) for user to select
3. **Pre-Execution Confirmation**: After parameter validation, present the operation to be executed as option cards (e.g., "Continue" / "Cancel") for user confirmation — **forbidden** to require manual confirmation input.
4. **Mandatory Checklist** (all conditions **must be met** before execution, none can be omitted):
   - [ ] `biz-region-id` confirmed by user
   - [ ] `cluster-id` confirmed by user and exists in `describe-db-clusters` returned list
   - [ ] Pre-execution confirmation obtained from user
5. **Region Routing Rules (P0)**: The `aliyun adbai` service endpoint is not deployed in every region. **For all `aliyun adbai` calls, `--region` and `--endpoint` must be forcibly overridden** according to the following routing table mapping, even if the user has specified a region — do not use the user's specified values:

| biz-region-id | --region | --endpoint |
|-----------|----------|------------|
| cn-hangzhou, cn-shanghai, cn-beijing, cn-shenzhen, cn-hongkong, cn-qingdao, cn-heyuan, cn-chengdu, cn-guangzhou, cn-zhangjiakou, cn-wulanchabu, cn-huhehaote, cn-shanghai-cloudspe, cn-hangzhou-finance, cn-beijing-finance-1, cn-shenzhen-finance-1, cn-shanghai-finance-1 | cn-beijing | adbai.cn-beijing.aliyuncs.com |
| ap-southeast-1, ap-southeast-3, ap-southeast-5, ap-southeast-6, ap-southeast-7, ap-northeast-1, ap-northeast-2, eu-central-1, eu-west-1, me-east-1, me-central-1, na-south-1 | ap-southeast-1 | adbai.ap-southeast-1.aliyuncs.com |
| us-east-1, us-west-1 | us-west-1 | adbai.us-west-1.aliyuncs.com |

**Example**: User's cluster is in `cn-zhangjiakou` → `--biz-region-id cn-zhangjiakou --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com`

All sections below and examples in `references/*.md` that contain `--db-cluster-id` without `--biz-region-id` **are automatically su