返回技能市场
开发运维 安全

阿里云RDS智能运维助手

@aliyun/alibabacloud-rds-copilot

使用阿里云 RDS Copilot API,帮助用户完成 RDS 相关的智能问答、SQL 优化、实例运维和故障排查

云Skills门户 热度 59v0.0.4

阿里云 RDS Copilot 智能运维助手

此 skill 在对话中充当阿里云 RDS Copilot 的智能 agent，帮助用户处理 RDS 相关的智能问答、SQL 优化、实例运维和故障排查。

场景说明

架构：Alibaba Cloud CLI + RdsAi OpenAPI

主要功能：

  • 理解用户的自然语言请求（中文或英文），识别其是否与 RDS Copilot 相关
  • 直接调用阿里云 CLI，执行 aliyun rdsai chat-messages 命令，实时查询 RDS Copilot
  • 收到结果或用户粘贴的错误消息时，进一步解释、诊断并提供建议

---

Agent 执行契约

调用 RDS Copilot 前，只要可以执行命令，agent 就必须自行完成本地环境准备。如果 agent 能够直接安装或升级 CLI 或插件，则不得先要求用户安装这些组件。 如果安装或升级需要网络访问、sudo 或工具审批，应提供具体命令并请求批准，获批后继续。

硬性前置条件：所有就绪检查通过之前，不得执行 aliyun rdsai chat-messages：

  1. 阿里云 CLI 已安装，且 aliyun version 的版本 >= 3.3.3。
  2. 已启用插件自动安装，且 rdsai 产品插件/命令可用。
  3. 已配置阿里云 CLI 凭证，且所选配置文件有效。

如果任一前置条件未满足：

  • 缺少 CLI 或其版本过旧：安装或升级阿里云 CLI，然后重新运行 aliyun version。
  • 缺少 rdsai 插件：启用插件自动安装，并安装或触发安装 rdsai，然后重新检查该命令。
  • 凭证缺失/无效：在调用 RDS Copilot API 前停止操作，并指导用户配置凭证。如果用户要求 agent 代为配置，只索取必填字段，然后通过 aliyun configure 进行配置；不得要求用户将密钥粘贴到环境变量中。

默认地域：如果用户未明确提供地域，始终使用 cn-hangzhou。自然语言“杭州”映射到 cn-hangzhou。除非用户指定其他地域，否则必须在 --inputs RegionId=cn-hangzhou 和任何凭证配置指导中保留此默认值。

---

安装

Agent 预检：阿里云 CLI 必须已安装，或必须由 agent 安装
此 skill 使用阿里云 CLI 调用 RdsAi OpenAPI。agent 必须先检查 CLI 是否已安装且可用。如果缺少 CLI 且可以执行命令，应先将其安装好，再要求用户手动操作。

预检查：要求阿里云 CLI >= 3.3.3

运行 command -v aliyun 和 aliyun version，验证版本是否 >= 3.3.3。
如果尚未安装或版本过低，请在继续前安装或更新。
低于 3.3.0 的 CLI 版本不支持 aliyun plugin 命令；应先升级 CLI，而不是反复运行插件命令。

预检查：必须更新阿里云 CLI 插件

[必须] 运行 aliyun configure set --auto-plugin-install true 以启用插件自动安装。
[必须] 使用 aliyun plugin list、aliyun plugin search rdsai 或 aliyun rdsai --help 验证 rdsai 插件能力。
[必须] 如果未安装 rdsai，运行 aliyun plugin install --names rdsai 并重新检查。
[必须] 如果插件已安装，运行 aliyun plugin update --name rdsai；如果 CLI 仅支持 aliyun plugin update，则使用该命令并继续。

[必须] CLI User-Agent——每次调用 aliyun rdsai chat-messages 时，都必须包含以下格式的命令级 --user-agent 值： AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}。 有关 session-id 生成规则，请参阅“可观测性”部分。不得将 --user-agent 传递给 aliyun configure、aliyun plugin、aliyun version 等系统命令或安装/升级命令。

macOS 安装

# Option 1: Install via Homebrew (recommended)
brew install aliyun-cli

# Option 2: Install via PKG package
curl -O https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg
sudo installer -pkg aliyun-cli-latest.pkg -target /

# Option 3: Install via one-click script
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

Linux 安装

# Install via one-click script
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

# Or download TGZ package for manual installation
curl https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz -o aliyun-cli.tgz
tar xzvf aliyun-cli.tgz
sudo mv aliyun /usr/local/bin/

验证安装

command -v aliyun
aliyun version

---

凭证配置

选项 1：交互式配置（推荐）

aliyun configure --mode AK --profile rdsai

按照提示输入：

  • Access Key Id：您的 AccessKey ID
  • Access Key Secret：您的 AccessKey Secret
  • Default Region Id：除非用户指定其他地域，否则使用 cn-hangzhou

在向用户索取密钥之前，应说明建议使用的交互式命令会将密钥保存在阿里云 CLI 的凭证存储中。不得打印该密钥，也不得让该密钥在聊天记录中的保留时间超过必要时长。

选项 2：非交互式配置

aliyun configure set \
  --profile rdsai \
  --mode AK \
  --access-key-id <yourAccessKeyID> \
  --access-key-secret <yourAccessKeySecret> \
  --region cn-hangzhou

---

命令格式

基本命令结构

aliyun rdsai chat-messages \
  --query '<query content>' \
  --inputs RegionId=cn-hangzhou Language=zh-CN Timezone=Asia/Shanghai [CustomAgentId=<custom agent ID>] \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}' \
  [--conversation-id '<conversation ID>']

参数说明

重要：参数确认——在执行任何命令之前，
确定用户意图：SQL 编写/优化、SQL 诊断、实例参数调优、故障排查、性能分析、查询实例列表等。
收集必要参数（如果未指定，则使用默认值）。

| 参数 | 必填/可选 | 描述 | 默认值 | |-----------|-------------------|-------------|---------| | --query | 必须 | 用户查询内容 | - | | --inputs RegionId= | 可选 | 阿里云地域 ID | cn-hangzhou | | --inputs Language= | 可选 | 语言 | zh-CN | | --inputs Timezone= | 可选 | 时区 | Asia/Shanghai | | --inputs CustomAgentId= | 可选 | 自定义 Agent ID | 无 | | --event-mode | 可选 | 事件模式 | separate | | --endpoint | 必须 | API 端点 | rdsai.aliyuncs.com | | --conversation-id | 可选 | 用于多轮对话的会话 ID | 无 | | --region | 可选 | API 调用的地域 | 凭证的默认地域 | | --profile | 可选 | 指定凭证配置文件名称 | 默认配置文件 | | --user-agent | 业务 API 命令必须提供 | 自定义 User-Agent | AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id} |

---

RAM 权限

此 skill 需要以下 RAM 权限。详情参见 [references/ram-policies.md](references/ram-policies.md)。

| 权限 | 描述 | |------------|-------------| | rdsai:ChatMessages | 调用 RDS AI 助手 API |

---

核心工作流程

0. 环境就绪预检（调用 RDS Copilot 前）

每个 RDS Copilot 任务开始时都必须执行一次此预检。不得仅因用户只提出了简单查询而跳过。

# 0.1 Check Alibaba Cloud CLI existence and version
command -v aliyun
aliyun version

如果缺少 aliyun，请选择本地可用的最安全方法进行安装：

# macOS, when Homebrew is available
brew install aliyun-cli

# macOS/Linux fallback
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

如果 aliyun version 低于 3.3.3，必须先升级，再运行插件命令：

# CLI 3.3.5+ non-Homebrew install
aliyun upgrade --yes

# macOS Homebrew install
brew update
brew upgrade aliyun-cli

# Fallback for old CLI versions such as 3.0.x that do not support plugin commands
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

安装或升级后，重新运行 aliyun version。

# 0.2 Enable and verify plugin support. These are system commands; do not add --user-agent.
aliyun configure set --auto-plugin-install true
aliyun plugin list
aliyun plugin search rdsai

# Run only if the previous checks do not show the rdsai plugin/command.
aliyun plugin install --names rdsai

# Final capability check. This may also trigger auto-install after auto-plugin-install is enabled.
aliyun rdsai --help

如果 aliyun plugin 返回类似 'plugin' is not a valid command or product 的错误，则 CLI 版本过旧。请先升级 CLI；不得继续反复重试插件命令。

# 0.4 Check credentials before the first API call
aliyun configure list

将以下凭证状态视为未就绪：

  • 未列出任何配置文件。
  • 所选或默认配置文件的 Credential 为空。
  • Valid 为 Invalid 或未显示为有效。
  • 命令报告 unknown profile、InvalidAccessKeyId、SignatureDoesNotMatch、缺少 AccessKey、STS 令牌已过期或类似的身份验证错误。

凭证未就绪时，必须在执行 aliyun rdsai chat-messages 前停止操作，并回复以下凭证配置指南：

# Recommended interactive setup
aliyun configure --mode AK --profile rdsai

# Non-interactive setup if the user explicitly asks the agent to configure credentials
aliyun configure set \
  --profile rdsai \
  --mode AK \
  --access-key-id <AccessKeyId> \
  --access-key-secret <AccessKeySecret> \
  --region cn-hangzhou

如果用户希望由 agent 配置凭证，请询问以下信息：

  • 凭证模式：默认为 AK，除非用户指定 OAuth、STS、RAM 角色、EcsRamRole 或其他受支持的模式。
  • 配置文件名称：默认为 rdsai。
  • AK 模式需提供 AccessKeyId 和 AccessKeySecret；STS/RAM 角色模式则需提供对应模式的字段。
  • 使用临时凭证时需提供 STS 令牌。
  • RegionId：未指定时默认为 cn-hangzhou。

禁止将 export ALIBABA_CLOUD_ACCESS_KEY_ID=... 或 export ALIBABA_CLOUD_ACCESS_KEY_SECRET=... 用作常规配置方式。必须使用 aliyun configure，以便凭证保存在 CLI 凭证存储中。

1. 确认任务类型和参数

确定用户意图：SQL 编写/优化、SQL 诊断、实例参数调优、故障排查、性能分析、查询实例列表等。

收集必要参数（未指定时使用默认值）：

  • RegionId：地域 ID（默认为 cn-hangzhou；省略时使用此值）
  • Language：语言（默认为 zh-CN）
  • Timezone：时区（默认为 Asia/Shanghai）
  • CustomAgentId：自定义 Agent ID（可选）
  • --conversation-id：用于多轮对话的会话 ID（可选）

2. 构造命令并调用 CLI

仅在环境就绪预检成功后执行此步骤。必须始终包含 RegionId；如果用户未提供地域，请使用 cn-hangzhou。 session-id 必须在首次业务 API 调用前按照下方的可观测性规则生成一次，并在本次 RDS Copilot 任务的所有 aliyun rdsai chat-messages 调用中复用。

# Basic query
aliyun rdsai chat-messages \
  --query 'List RDS MySQL instances in Hangzhou region' \
  --inputs RegionId=cn-hangzhou Language=zh-CN Timezone=Asia/Shanghai \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

# Troubleshooting example
aliyun rdsai chat-messages \
  --query 'RDS instance rm-bp1xxx connection timeout, error Too many connections, please help troubleshoot. Instance is in Hangzhou region.' \
  --inputs RegionId=cn-hangzhou Language=zh-CN Timezone=Asia/Shanghai \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

# Query with Beijing region
aliyun rdsai chat-messages \
  --query 'Optimize this SQL: SELECT * FROM users WHERE name LIKE "%test%"' \
  --inputs RegionId=cn-beijing Language=zh-CN Timezone=Asia/Shanghai \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

# Multi-turn dialogue (using ConversationId from previous response)
aliyun rdsai chat-messages \
  --query 'Continue analyzing the above issue' \
  --conversation-id '<ConversationId from previous response>' \
  --inputs RegionId=cn-hangzhou Language=zh-CN Timezone=Asia/Shanghai \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

# Using custom Agent
aliyun rdsai chat-messages \
  --query 'Analyze database performance' \
  --inputs RegionId=cn-hangzhou Language=zh-CN Timezone=Asia/Shanghai CustomAgentId=your-custom-agent-id \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

3. 解析结果和后续处理

  • 仅当响应或用户粘贴的错误中包含 No valid order found 时，才停止常规结果分析，并直接向用户返回以下指南：
  • 当前调用未找到有效的 RDS AI 助手专业版订单。请为当前阿里云账号开通 RDS AI 助手专业版，然后重试失败的调用。
  • 开通页面：https://rdsnext.console.aliyun.com/rdsCopilotProfessional/cn-hangzhou
  • 操作指南：https://help.aliyun.com/zh/rds/apsaradb-rds-for-mysql/manage-rds-colipot-professional-edition
  • 根据操作指南，通过 RDS 控制台创建 RDS AI 助手专业版：选择 RDS AI 助手 > 专业版，然后点击 立即开通。开通成功后，使用已开通该服务的账号重试失败的调用。
  • 用自然语言向用户解释 RDS Copilot 的响应
  • 如果响应中包含 SQL 或操作步骤，请评估风险并发出警告：
  • 避免在生产环境中直接执行高风险语句（例如，对大表执行 DELETE / UPDATE 或表结构变更）
  • 建议先在测试环境中验证，或增加备份措施或条件限制
  • 如果继续对话，请记录响应中的 ConversationId，供下次查询使用

---

可观测性

在每个 RDS Copilot 任务/会话首次调用业务 API 之前，生成一个 session-id。session-id 必须是由 32 个字符组成的小写十六进制字符串，仅生成一次，并在同一任务中每次执行 aliyun rdsai chat-messages 命令时复用，包括多轮对话中的后续调用。

推荐的生成方法：

openssl rand -hex 16

备用方法：

python3 -c 'import secrets; print(secrets.token_hex(16))'

User-Agent 模板：

AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}

仅在业务 API 命令中通过每条命令单独设置的 --user-agent 参数应用此 User-Agent：

aliyun rdsai chat-messages \
  --query '<query content>' \
  --inputs RegionId=cn-hangzhou Language=zh-CN Timezone=Asia/Shanghai \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

不得使用已弃用的全局 User-Agent 配置机制。不得向 aliyun configure、aliyun plugin、aliyun version、command -v aliyun 等系统命令以及安装命令或升级命令添加 --user-agent。

---

输出格式

阿里云 CLI 返回 JSON 格式的响应（以流式方式返回多个 JSON 事件）：

{"data":{"ConversationId":"8227be22-xxxx-xxxx-xxxx-xxxxxxxxxxxx","Event":"workflow_started","MessageId":"a79c881c-xxxx-xxxx-xxxx-xxxxxxxxxxxx",...}}
{"data":{"Answer":"<partial answer content>","Event":"message",...}}
{"data":{"Event":"workflow_finished",...}}

关键字段：

  • ConversationId：会话 ID（用于多轮对话）
  • Answer：AI 助手的响应内容
  • Event：事件类型（workflow_started、消息、workflow_finished）

---

成功验证

  1. CLI 安装成功：aliyun version 显示版本号
  2. 凭证配置正确：aliyun configure list 显示已配置的凭证
  3. 可观测性配置正确：业务 API 调用包含 --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'，其中 session-id 为 32 个字符的十六进制字符串
  4. API 调用成功：响应为 JSON 格式，并包含 ConversationId 和 Answer
  5. 响应内容有效：回答与查询内容相关

有关详细验证步骤，请参阅 [references/verification-method.md](references/verification-method.md)。

---

清理

此 skill 仅执行只读查询操作，不会创建任何云资源，因此无需清理。

---

API 和命令列表

详情请参阅 [references/related-apis.md](references/related-apis.md)。

| 产品 | API 操作 | CLI 命令 | 说明 | |---------|------------|-------------|-------------| | RdsAi | ChatMessages | aliyun rdsai chat-messages | RDS AI 助手对话 API |

---

最佳实践

  1. 使用多轮对话：对于复杂问题，使用 --conversation-id 开展具备上下文感知能力的多轮对话
  2. 指定正确的地域：根据 RDS 实例所在地域设置 RegionId 参数
  3. 在生产环境中谨慎操作：RDS Copilot 提供的 SQL 建议应先在测试环境中验证
  4. 保存会话 ID：如需跟进或继续分析，请保存返回的 ConversationId
  5. 使用配置文件：建议使用 aliyun configure 配置凭证，避免在命令行中暴露敏感信息
  6. 使用 --profile：您可以配置多个凭证配置文件，并使用 --profile 在账号之间切换

---

参考链接

| 参考文档 | 说明 | |--------------------|-------------| | 阿里云 CLI 文档 | 阿里云 CLI 用户指南 | | [references/related-apis.md](references/related-apis.md) | API 和命令列表 | | [references/ram-policies.md](references/ram-policies.md) | RAM 权限策略配置 | | [references/verification-method.md](references/verification-method.md) | 验证方法 | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | 验收标准 |

qianwen skills install @aliyun/alibabacloud-rds-copilot