mcpField
A
alibabacloud-analyticdb-mysql-copilot

alibabacloud-analyticdb-mysql-copilot

github.com/aliyun数据与数据库281247 次安装1 天前更新
代码仓库

关于 alibabacloud-analyticdb-mysql-copilot

alibabacloud-analyticdb-mysql-copilot 是通过 aliyun-cli 运维和诊断 Alibaba Cloud AnalyticDB for MySQL 的技能，可结合实时集群与性能数据分析查询和存储问题。

主要功能

  1. 01查看集群、账号和网络详情
  2. 02检查 CPU、QPS、延迟和连接
  3. 03诊断慢查询与 SQL 模式
  4. 04分析当前运行的 SQL
  5. 05检查存储布局和表状态

适用场景

  1. 01查看集群性能指标
  2. 02排查慢 SQL 或长时间运行的 SQL
  3. 03诊断分区和数据倾斜
  4. 04发现闲置索引和存储问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill alibabacloud-analyticdb-mysql-copilot

安装后在 Claude Code 中输入/alibabacloud-analyticdb-mysql-copilot确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
acceptance-criteria.md
cli-installation-guide.md
cluster-diagnosis.md
cluster-info.md
ram-policies.md
region-list.md
verification-method.md

详细介绍

Skill 加载提示词：加载此 Skill 后，在首次响应的开头输出以下行：[Skill Loaded] alibabacloud-analyticdb-mysql-copilot — ADB MySQL Operations & Diagnosis Assistant

此 Skill 是 Alibaba Cloud AnalyticDB for MySQL (ADB MySQL) 运维与诊断助手，可通过 aliyun-cli 直接调用 ADB MySQL OpenAPI，获取实时数据并提供诊断建议。

核心能力：

  • 集群管理：查看集群列表、集群详情、存储空间、账号和网络信息
  • 性能监控：查询 CPU、QPS、RT、内存、连接数及其他性能指标
  • 慢查询诊断：检测 BadSQL、分析 SQL Patterns、识别慢查询根因
  • 运行中 SQL 分析：查看当前正在执行的 SQL，识别长时间运行的查询
  • 空间诊断：实例空间检查，包括分区合理性诊断、超大非分区表诊断、表数据倾斜诊断、复制表合理性诊断、主键合理性诊断、空闲索引及冷热表优化建议

预检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装或更新， 或参阅 references/cli-installation-guide.md。 然后 [MUST] 运行 aliyun configure set --auto-plugin-install true，以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保已安装的插件始终为最新版本。

预检查：需要 Alibaba Cloud 凭证

安全规则：

  • 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
  • 绝不要求用户在对话或命令行中直接输入 AK/SK
  • 绝不使用包含明文凭证值的 aliyun configure set
  • 只能使用 aliyun configure list 检查凭证状态
aliyun configure list

检查输出中是否包含有效的 profile（AK、STS 或 OAuth 身份）。

如果不存在有效的 profile，请在此处停止。

  1. 从 Alibaba Cloud Console 获取凭证
  2. 在本会话之外配置凭证（在终端中运行 aliyun configure，或在 shell profile 中设置环境变量）
  3. 返回并重新执行，直到 aliyun configure list 显示有效的 profile

[MUST] CLI User-Agent — 每次调用 aliyun CLI 命令时都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot

在核心工作流开始时（调用任何 CLI 命令之前）： [MUST] 启用 AI-Mode — 执行 Agent Skill 时必须启用 AI-mode。 调用任何 CLI 命令之前，运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot"

[MUST] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在提供最终响应之前，务必先禁用 AI-mode。此要求适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何其他不再执行 CLI 命令的情况。 AI-mode 仅用于 Agent Skill 调用场景，Skill 停止运行后不得保持启用状态。

aliyun configure ai-mode disable

1. 区域与集群 ID 约定

1.1 集群管理（aliyun adb）

约定：对于任何需要 --db-cluster-id 的接口，aliyun adb 命令也必须显式包含 --biz-region-id。即使官方或 CLI 帮助中没有将其标记为“必填”，也必须优先遵循本技能的约定——始终包含该参数，避免依赖隐式默认区域。

例外：仅在按区域列出资源或调用不包含 --db-cluster-id 的接口（例如 describe-db-clusters）时，仍必须包含 --biz-region-id，但不适用“与 db-cluster-id 配对”的规则。

<region-id> 来源优先级：用户明确指定 → 对话或工单上下文 → aliyun configure list 中的默认区域 → 向用户确认。

1.2 智能诊断（aliyun adbai）

aliyun adbai describe-chat-message 支持两种具有不同工作流的场景：

产品知识问答（无需区域或集群）

当用户询问产品概念、语法、功能问题等（例如“什么是 BUILD”“如何创建分区表”）时，无需确认区域和集群——直接执行以下命令：

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
实例级诊断（需要地域 + 集群）

当诊断涉及特定实例数据或状态（例如慢查询、BadSQL、SQL Pattern 分析、实例健康检查、索引优化建议、实例诊断、表建模诊断等）时，必须完成以下步骤：

  1. 确认地域：<region-id> 的来源优先级为：用户明确指定 → 对话 / 工单上下文 → aliyun configure list 中的默认地域 → 向用户确认。如需用户确认，必须读取 references/region-list.md，并以选项卡形式展示选项——禁止要求用户手动输入地域 ID。
  2. 验证集群 ID：调用 aliyun adbai 前，必须先执行 aliyun adb describe-db-clusters --api-version 2021-12-01 --biz-region-id <region-id> --region <region-id>，并在返回的 Items.DBCluster[] 中查找用户的集群 ID：
    • 找到匹配项 → 验证通过
    • 列表为空或未找到匹配项 → 不得继续，以选项卡形式展示实际集群，供用户选择
    • 用户未提供集群 ID → 以选项卡形式展示集群列表（≤10 个选项），供用户选择
  3. 执行前确认：参数验证后，以选项卡形式向用户展示待执行的操作（例如“继续” / “取消”），供用户确认——禁止要求用户手动输入确认信息。
  4. 必需检查清单（执行前必须满足所有条件，不得遗漏任何一项）：
    • 用户已确认 biz-region-id
    • 用户已确认 cluster-id，且该 ID 存在于 describe-db-clusters 返回的列表中
    • 已获得用户的执行前确认
  5. 地域路由规则（P0）：并非所有地域都部署了 aliyun adbai 服务端点。对于所有 aliyun adbai 调用，必须根据以下路由表映射强制覆盖 --region 和 --endpoint，即使用户已指定地域也不例外——不得使用用户指定的值：
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-1cn-beijingadbai.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-1ap-southeast-1adbai.ap-southeast-1.aliyuncs.com
us-east-1, us-west-1us-west-1adbai.us-west-1.aliyuncs.com

示例：用户的集群位于 cn-zhangjiakou → --biz-region-id cn-zhangjiakou --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com

以下所有章节以及 references/*.md 中不含 --biz-region-id 的 --db-cluster-id 示例，均按本节约定自动补充；各参考文档中不再重复说明——以本节为准。

2. 场景路由

产品范围：此 Skill 仅适用于 AnalyticDB for MySQL（ADB MySQL），集群 ID 通常以 am-xxx 或 amv-xxx 开头。如果用户提及其他阿里云产品（例如 Elasticsearch、RDS MySQL、PolarDB、ClickHouse 等），请明确告知用户此 Skill 不适用，并停止执行。

🚨🚨🚨 必须遵守 | P0 | 不可妥协 — 强制执行规则（违反即失败）🚨🚨🚨

以下规则具有最高优先级，必须无条件执行，在任何情况下都不得违反：

规则 1：必须调用 API

当用户请求符合以下场景时，必须立即执行相应的 API 调用，禁止跳过：

用户请求关键词必须调用的 API禁止行为
"cluster list"、"instance list"、"all clusters"、"list clusters"describe-db-clusters❌ 不调用 API，直接给出建议
"data skew"、"BadSQL"、"slow SQL detection"、"running SQL"、"idle index"、"SQL Pattern"、"space diagnosis"、"health inspection"、"instance diagnosis"、"slow query"、"RT increase"、"cluster stall" 及其他诊断关键词DescribeChatMessage❌ 不调用 API，只给出建议或解释概念
规则 2：必须输出命令字符串（响应首行）

必须：每次调用 ADB OpenAPI，都必须在响应的【首行】或【开头】明确输出已执行的命令字符串。

强制格式（必须严格遵守）：

Command executed: `aliyun adb <command-name> --api-version 2021-12-01 --biz-region-id <region-id> [--db-cluster-id <cluster-id>] [other parameters]`
或
Command executed: `aliyun adbai describe-chat-message --region <mapped-region> --endpoint <mapped-endpoint> --biz-region-id <region-id> --query "<user question>"`

[然后输出诊断结果、表格等]

正确示例：

Command executed: `aliyun adb describe-db-clusters --api-version 2021-12-01 --biz-region-id cn-zhangjiakou --region cn-zhangjiakou`

Query complete! There are 2 ADB MySQL clusters in the Zhangjiakou region...

Command executed: `aliyun adbai describe-chat-message --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com --biz-region-id cn-zhangjiakou --query "amv-xxx slow query diagnosis for the last 3 hours"`

Diagnosis complete! Found the following issues...

错误示例（违反即失败）：

❌ Query complete! There are 2 clusters in the Zhangjiakou region... (未输出命令字符串)
❌ I called the API to query the cluster list... (未输出完整命令)
❌ Command executed... (未输出具体命令内容)
❌ aliyun adb describe-db-clusters --biz-region-id cn-zhangjiakou --region cn-zhangjiakou (缺少 --api-version 2021-12-01)
规则 3：禁止规避行为

不可妥协：绝对禁止以下行为：

  • ❌ 不调用 API，直接给出一般性建议或解释概念
  • ❌ 调用 API，但未在响应开头输出完整命令字符串
  • ❌ 用“我们建议……”“你可以尝试……”等含糊说法代替实际诊断
  • ❌ 只输出文档内容，不执行实际操作
  • ❌ 将命令字符串放在响应中间或末尾
  • ❌ 调用 aliyun adb 命令时不带 --api-version 2021-12-01（否则将默认使用旧版本 2019-03-15）

违反上述规则即任务失败，不设例外

🔴 集群 ID 识别规则（最高优先级）：如果用户提供的集群 ID 以 am- 或 amv- 开头，则该集群一定是 ADB MySQL 集群。无需且不得通过 aliyun rds、aliyun polardb、aliyun clickhouse、aliyun hbase 或其他产品命令验证其归属。违反此规则会导致大量无效 API 调用。

根据用户意图，阅读相应的 references/ 文件，了解详细操作指南。

用户意图参考文件使用时机必须调用的 API
查看实例列表、实例详情、集群配置、存储空间先阅读 references/cluster-info.md，然后执行用户想了解现有实例、实例规格或磁盘使用情况时describe-db-clusters / describe-db-cluster-attribute
慢查询诊断、BadSQL、运行中的查询、SQL Pattern、实例诊断、实例写入诊断、空间诊断、表建模诊断、数据倾斜、闲置索引、产品知识问答等先阅读 references/cluster-diagnosis.md，然后执行用户报告性能异常、需要实例诊断、表建模优化或产品知识问答时describe-chat-message

路由规则：

  1. 识别用户意图，并从上表中找到匹配的场景
  2. 🚨 必须：立即执行对应的 API 命令（不得跳过，也不得只提供建议）：集群管理使用 aliyun adb，智能诊断使用 aliyun adbai describe-chat-message
  3. 🚨 必须：在回复中输出命令字符串（例如，aliyun adb describe-db-clusters --api-version 2021-12-01 --biz-region-id <region-id> --region <region-id> 或 aliyun adbai describe-chat-message --region <mapped-region> --endpoint <mapped-endpoint> --biz-region-id <region-id> --query "<question>"）
  4. 集群管理场景：阅读 references/cluster-info.md，并按其中的步骤执行；诊断场景：阅读 references/cluster-diagnosis.md，并按其中的步骤执行
  5. 如果无法将用户意图匹配到表中的具体场景，则执行以下默认诊断工作流：
    1. 调用 describe-db-clusters，确认集群存在且状态正常
    2. 使用选项卡列出 2-3 个最可能的路由选项（参考上表）——禁止要求用户手动输入诊断类型
    3. 根据用户选择，路由到相应操作并继续执行
  6. 可以组合多个场景——例如，先通过集群信息确认目标实例，然后通过 describe-chat-message 进行诊断并定位问题

集群 ID 验证规则：如果 API 响应中不存在用户提供的集群 ID（错误代码 InvalidDBClusterId.NotFound），请勿中止任务。应改为调用 describe-db-clusters，列出该区域中的实际集群，引导用户确认正确的集群 ID，并继续执行。

3. 时间参数处理

注意：describe-chat-message 接口会自动处理时间参数，无需手动传入时间范围。用户只需在 --query 中用自然语言描述时间（例如“过去 3 小时的慢查询”），接口会自动解析。

对于 aliyun adb 等集群信息查询接口（例如 describe-db-clusters），无需时间参数。

4. 命令参考

4.1 OpenAPI 命令（aliyun-cli）

此 Skill 使用两种 CLI 命令格式：

集群管理（aliyun adb）
aliyun adb <command-name> --api-version 2021-12-01 --biz-region-id <region-id> --region <region-id> [--db-cluster-id <cluster-id>] [other parameters] --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot

🚨 API 版本强制要求（P0）：调用 aliyun adb 时，必须始终显式包含 --api-version 2021-12-01。 ADB MySQL 有两个 API 版本（2019-03-15 和 2021-12-01），CLI 可能默认使用旧版本 2019-03-15， 而该版本缺少此技能所需的接口。未包含 --api-version 2021-12-01 的命令将失败，导致任务失败。

此技能的约定：对于下表中任何“需要 --db-cluster-id”的行，实际命令还必须包含 --biz-region-id <region-id>（参见第 1.1 节）。只有 describe-db-clusters 不遵循“配对”规则，但仍需要 --biz-region-id。

CLI 命令名称描述是否需要 --db-cluster-id
describe-db-clusters查询指定地域内的 ADB MySQL 集群列表否
describe-db-cluster-attribute查询集群详细属性是
describe-db-cluster-space-summary查询存储空间概览是
智能诊断（aliyun adbai）
aliyun adbai describe-chat-message --region <mapped-region> --endpoint <mapped-endpoint> --biz-region-id <region-id> --query "<user question>" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot

DescribeChatMessage 是 ADB MySQL 智能诊断助手的 SSE 流式接口，提供产品 RAG 检索和实例分析、内核诊断能力。它包含以下诊断场景：

  • 慢 SQL 查询诊断：性能指标分析、BadSQL 检测、运行中的 SQL 分析、SQL Pattern 分析
  • 实例诊断：实例健康检查、容量评估、扩缩容建议
  • 实例写入诊断：写入性能分析、写入瓶颈识别
  • 表建模诊断：超大非分区表、分区合理性、主键合理性、数据倾斜、复制表合理性、闲置索引、冷热表优化
参数描述必填
--biz-region-id用户集群的地域 ID（产品知识问答使用默认值 cn-beijing，无需向用户确认）有条件必填
--query查询内容；实例诊断的格式为 "<cluster-id> <diagnosis question>"；产品知识问题可直接提问（例如 "What is BUILD"）。是
--region服务端点地域（技能会根据 --biz-region-id 自动映射，无需用户指定）自动
--endpoint服务端点地址（技能会根据 --biz-region-id 自动映射，无需用户指定）自动
--session-id多轮对话的会话 ID（不传则新建会话）否
--timezone时区，默认为 Asia/Shanghai否

重要：实例级诊断（慢查询、表建模等）的 --query 必须包含集群 ID；无需单独传入 --db-cluster-id；产品知识问题无需集群 ID。示例："amv-xxx slow query diagnosis for the last 3 hours"、"What is BUILD"

示例：

# Slow query diagnosis
aliyun adbai describe-chat-message --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com --biz-region-id cn-zhangjiakou \
  --query "amv-xxx slow query diagnosis for the last 3 hours" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot

# Instance health inspection
aliyun adbai describe-chat-message --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com --biz-region-id cn-zhangjiakou \
  --query "amv-xxx instance health inspection analysis" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot

# Table modeling diagnosis
aliyun adbai describe-chat-message --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com --biz-region-id cn-zhangjiakou \
  --query "amv-xxx instance space diagnosis and table modeling diagnosis" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot

# Data skew detection
aliyun adbai describe-chat-message --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com --biz-region-id cn-zhangjiakou \
  --query "amv-xxx detect data skewed tables" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot

# Product knowledge Q&A
aliyun adbai describe-chat-message --region cn-beijing --endpoint adbai.cn-beijing.aliyuncs.com --biz-region-id cn-beijing \
  --query "What is BUILD" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-mysql-copilot
4.2 常用参数

集群管理参数（aliyun adb）：

参数说明默认值
--biz-region-id地域 ID（此 Skill 在存在 --db-cluster-id 时需要此参数）—
--region服务端点地域（值与 --biz-region-id 一致，aliyun adb 命令必需）—
--db-cluster-idADB MySQL 集群 ID（例如 amv-xxx）必需
--db-cluster-version集群版本（3.0/5.0/All）All
--page-number页码1
--page-size每页条目数30

智能诊断参数（aliyun adbai）：

参数说明默认值
--biz-region-id用户的集群地域 ID（产品知识问答使用默认值 cn-beijing，无需用户确认）有条件必需
--query查询内容；实例诊断格式为 "<db-cluster-id> <problem description>"，知识问答可直接提问（支持自然语言时间描述）。必需
--region服务端点地域（Skill 根据 --biz-region-id 自动映射，无需用户指定）自动
--endpoint服务端点地址（Skill 根据 --biz-region-id 自动映射，无需用户指定）自动
--session-id会话 ID（多轮对话时传入）空（新会话）
--timezone时区：例如 Asia/Shanghai 等Asia/Shanghai
4.3 凭证配置

阿里云 API 凭证通过 aliyun configure 在当前会话之外配置；CLI 会自动读取。

凭证状态检查：

aliyun configure list

如果输出中的 AccessKeyId 列为空或显示 <empty>，则表示未配置凭证。提示用户：

  1. 在当前会话之外的终端中运行 aliyun configure 进行配置
  2. 或在 shell 配置文件中配置环境变量
  3. 配置完成后返回并继续

🔴 重要规则：

  • 严禁引导用户在会话中输入 AK/SK 凭证
  • 严禁使用 aliyun configure set --access-key-id 等显式凭证参数
  • 凭证检查必须是任务的第一步；如果检查失败，直接报告并终止

支持多种凭证类型：AK、StsToken、RamRoleArn、EcsRamRole 等。请参阅凭证配置文档。

5. RAM 策略

此 Skill 所需的完整 RAM 权限列表，请参阅 references/ram-policies.md。

[MUST] 权限失败处理： 执行期间，任何命令或 API 调用因权限错误而失败时，请按以下流程处理：

  1. 阅读 references/ram-policies.md，了解此 Skill 所需的完整权限列表
  2. 使用 ram-permission-diagnose skill 引导用户申请所需权限
  3. 暂停并等待用户确认已授予所需权限

6. 参数确认

重要：参数确认 — 执行任何命令或 API 调用之前，所有用户可配置参数（如 biz-region-id、db-cluster-id、--query 等）必须先与用户确认。不得在未经用户明确同意的情况下假设或使用默认值。

交互模式强制规则：任何需要用户确认或选择的步骤（区域、集群、诊断场景、执行确认等），必须使用选项卡片，禁止要求用户手动输入。具体来说：

  • 区域确认 → 选项卡片（读取 references/region-list.md 获取选项，参见第 1.2 节区域确认规则）——产品知识问答无需执行此步骤
  • 集群 ID 选择 → 选项卡片（根据 describe-db-clusters 的结果生成）——产品知识问答无需执行此步骤
  • 诊断场景选择 → 选项卡片（用户意图不明确时，列出可用的诊断类型）
  • 执行前确认 → 选项卡片（例如，“继续” / “取消”）——产品知识问答无需执行此步骤，可直接执行

7. 最佳实践

  1. CLI 优先：优先使用 CLI 命令进行诊断；集群管理使用 aliyun adb，智能诊断使用 aliyun adbai
  2. 命令输出：每次 API 调用都必须在响应开头输出完整的命令字符串
  3. 错误处理：集群 ID 不存在时，应引导用户选择正确的集群，而不是直接报错
  4. 产品边界：仅处理 ADB MySQL 集群（ID 前缀为 am- 或 amv-），不要混用其他产品的 API
  5. 优先使用选项：任何需要用户确认或选择的步骤，都必须使用选项卡片；不得要求用户手动输入

8. 参考链接

参考文件内容
references/ram-policies.mdRAM 权限列表
references/verification-method.md验证方法
references/cli-installation-guide.mdAliyun CLI 安装指南
references/region-list.md阿里云区域 ID 列表
references/cluster-info.md集群信息查询详细步骤
references/cluster-diagnosis.md集群智能诊断详细步骤

评论

支持 Markdown