alibabacloud-rds-copilot

阿里云 RDS Copilot 智能运维助手

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

场景说明

架构：Alibaba Cloud CLI + RdsAi OpenAPI

主要功能：

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

---

Agent 执行约定

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

硬性门槛：只有通过以下所有就绪检查后，才能执行 aliyun rdsai chat-messages：

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

如果任何一项未通过：

• CLI 缺失或版本过旧：安装或升级 Alibaba Cloud CLI，然后重新运行 aliyun version。
• 缺少 rdsai 插件：启用插件自动安装并安装或触发 rdsai 安装，然后重新检查命令。
• 缺少凭证或凭证无效：停止调用 RDS Copilot API，并引导用户配置凭证。如果用户要求 Agent 帮其配置，只询问必需的字段，然后通过 aliyun configure 进行配置；绝不要要求用户将密钥粘贴到环境变量中。

默认地域：如果用户未明确指定地域，始终使用 cn-hangzhou。自然语言中的“杭州”对应 cn-hangzhou。除非用户指定其他地域，否则在 --inputs RegionId=cn-hangzhou 和任何凭证配置指引中都使用此默认值。

---

安装

Agent 预检：必须安装 Alibaba Cloud CLI，或由 Agent 安装

此技能使用 Alibaba Cloud CLI 调用 RdsAi OpenAPI。Agent 必须先检查 CLI 是否存在且可用。如果 CLI 缺失且能够执行命令，请先安装 CLI，再要求用户手动操作。

预检：要求 Aliyun CLI >= 3.3.3

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

预检：必须更新 Aliyun 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 的生成规则请参阅“可观测性”部分。辅助命令 aliyun rdsai get-chat-model（如使用）也遵循相同的 User-Agent 规则。不要向 aliyun configure、aliyun plugin、aliyun version 等系统命令或安装/升级命令传递 --user-agent。

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

在向用户询问密钥前，请说明：推荐的交互式命令会将密钥保存在 Alibaba Cloud 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>] [EnableThinking=<true|false>] [ThinkEffort=<default|high|low>] [ModelId=<model 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=	可选	Alibaba Cloud 地域 ID	cn-hangzhou
--inputs Language=	可选	语言	zh-CN
--inputs Timezone=	可选	时区	Asia/Shanghai
--inputs CustomAgentId=	可选	自定义 Agent ID	None
--inputs EnableThinking=	可选	深度思考模式开关：true（启用）或 false（禁用）	None
--inputs ThinkEffort=	可选	思考深度：default（自动）、high（更深入的推理）、low（更快的响应）；支持的值因模型而异，请参阅 get-chat-model 响应中的 ThinkingLevels	None
--inputs ModelId=	可选	响应模型的模型 ID；显式设置时，在调用 chat-messages 前[必须]使用辅助命令 aliyun rdsai get-chat-model 对其进行验证 — 切勿依赖记忆或硬编码的模型列表	None
--event-mode	可选	事件模式	separate
--endpoint	必填	API 端点	rdsai.aliyuncs.com
--conversation-id	可选	多轮对话的对话 ID	None
--region	可选	API 调用的地域	凭证默认地域
--profile	可选	指定凭证配置名称	默认配置
--user-agent	业务 API 命令必填	自定义 User-Agent	AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}

---

RAM 权限

此技能需要以下 RAM 权限。详情请参阅 references/ram-policies.md。

权限	说明
rdsai:ChatMessages	调用 RDS AI 助手对话 API
rdsai:GetChatModel	辅助功能：显式设置 ModelId 时，查询可用的聊天模型

---

核心工作流

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 配置凭据，请询问以下信息：

• 凭据模式：除非用户指定 OAuth、STS、RAM 角色、EcsRamRole 或其他受支持的模式，否则默认为 AK。
• 配置文件名：默认为 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（可选）
• EnableThinking：深度思考模式开关，可设为 true 或 false（可选；除非用户要求深度思考或快速回答，否则省略）
• ThinkEffort：思考深度（可选；default 表示自动，high 表示对复杂诊断/优化进行更深入的推理，low 表示更快响应；各模型支持的值由 get-chat-model 返回的 ThinkingLevels 提供）
• ModelId：模型 ID（可选；仅在用户明确指定模型时使用）。明确指定后，在调用 ChatMessages 之前，[必须] 先调用辅助 GetChatModel API，并确认该 ID 出现在 Data[].ModelId 中；这适用于用户指定的所有模型 ID，包括 qwen3.8-max 等知名模型；绝不能跳过检查或依赖记忆/硬编码的模型列表。省略 ModelId 时无需查询：服务会使用 GetChatModel 响应中标记为 Default=true 的模型。向前兼容：API 支持新模型 ID 后，它们会自动出现在 GetChatModel 响应中；先通过 GetChatModel 验证，再传入即可；无需更改技能配置或代码
• --conversation-id：多轮对话的会话 ID（可选）

GetChatModel 是主调用流程中的辅助检查：ChatMessages 本身无需此检查即可工作，但只要满足以下任一条件，在调用 aliyun rdsai chat-messages 之前就[必须]进行检查：

1. 用户明确指定模型 ID——任何模型 ID 都适用，包括 qwen3.8-max 等知名模型。确认该 ID 出现在 Data[].ModelId 中。绝不能因为认为该模型已受支持而跳过检查；绝不能依赖记忆或硬编码的模型列表。
2. 用户询问有哪些可用模型。
3. 用户要求深度思考或指定思考深度（EnableThinking/ThinkEffort）——ThinkEffort 的支持值因模型而异，必须从 get-chat-model 响应的 ThinkingLevels 中读取。

仅当以上条件均不满足（未指定模型、未询问模型列表、未要求指定思考深度）时，才可以跳过 get-chat-model：

aliyun rdsai get-chat-model \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

响应中的 Data 数组列出了当前所有受支持的模型及其 ModelId、Default、ThinkingLevels、Features 和 ContextWindow。如果用户指定的模型 ID 不在 Data[].ModelId 中，请展示可用模型并让用户选择一个。

2. 构造命令并调用 CLI

仅在环境就绪预检成功后，才能执行此步骤；如果用户指定了模型 ID 或思考深度，还必须在 aliyun rdsai get-chat-model 验证成功后才能执行。始终包含 RegionId；如果用户未提供区域，则使用 cn-hangzhou。 首次调用业务 API 之前，根据下方的 Observability 规则生成一个 session-id，并在此 RDS Copilot 任务的所有 aliyun rdsai chat-messages 调用中重复使用该 ID。

# 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}'

# Deep thinking mode with explicit model and thinking depth (optional parameters)
# [MUST] The user explicitly sets ModelId and thinking depth, so first verify the model with get-chat-model,
# for EVERY user-specified model ID (including well-known ones such as qwen3.8-max), then call chat-messages;
# to switch models, re-verify with get-chat-model and change only the ModelId value
aliyun rdsai get-chat-model \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

aliyun rdsai chat-messages \
  --query 'Diagnose slow SQL on the instance and provide an optimization plan. Instance is in Hangzhou region.' \
  --inputs RegionId=cn-hangzhou Language=zh-CN Timezone=Asia/Shanghai EnableThinking=true ThinkEffort=high ModelId=qwen3.8-max \
  --event-mode separate \
  --endpoint rdsai.aliyuncs.com \
  --user-agent 'AlibabaCloud-Agent-Skills/alibabacloud-rds-copilot/{session-id}'

3. 解析结果并进行后续处理

• 仅当响应或用户粘贴的错误中包含 No valid order found 时，停止常规结果分析，并直接向用户返回以下指引：
  • 当前调用未找到有效的 RDS AI Assistant Professional Edition 订单。请为当前阿里云账号启用 RDS AI Assistant Professional Edition，然后重试失败的调用。
  • 开通页面：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 Assistant > Professional Edition，然后单击 Activate Now，创建 RDS AI Assistant Professional Edition。开通成功后，请使用已启用的账号重试失败的调用。
• 如果响应因其他错误代码而失败，请先将其映射为面向用户的指引，再重试：
  • ContentModeration（HTTP 451）：请求包含违规内容；请用户改写查询。
  • InvalidParameter（HTTP 400）：一个或多个参数无效；请检查 --inputs 值，例如 EnableThinking、ThinkEffort 和 ModelId，修正后重试。如果原因是不受支持的 ModelId，请运行 aliyun rdsai get-chat-model 获取当前支持的模型，指导用户从列表中选择一个模型，或联系技术支持确认最新的支持模型。
  • UserNotFound（HTTP 404）：用户不存在；请检查 CLI 凭据配置和账号。
  • TooManyRequests（HTTP 429）：已超过最大并发请求阈值；请等待后重试，或建议购买 AI 容量包以提高并发限制。
  • MoQuotaExceeded（HTTP 429）：路由到的 Standard 实例的 MO 令牌配额已用尽，请求受到速率限制；请等待配额恢复，或建议购买容量包。
• 用自然语言向用户说明 RDS Copilot 的响应
• 如果响应包含 SQL 或操作步骤，请评估风险并发出警告：
  • 避免直接在生产环境中执行高风险语句（例如对大表执行 DELETE / UPDATE 或进行架构变更）
  • 建议在测试环境中验证，或添加备份／条件限制
• 如果要继续对话，请记录响应中的 ConversationId，用于下一次查询

---

可观测性

在首次调用业务 API 之前，为每个 RDS Copilot 任务／会话生成一个 session-id。session-id 必须是由 32 个小写十六进制字符组成的字符串，只生成一次，并在同一任务中的每条 aliyun rdsai chat-messages 命令中重复使用，包括多轮后续对话。使用辅助命令 aliyun rdsai get-chat-model 时，也要重复使用相同的 session-id。

建议的生成方法：

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。

---

输出格式

Alibaba Cloud 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、message、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. 响应内容有效：Answer 与查询内容相关

详细验证步骤请参阅 references/verification-method.md。

---

清理

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

---

API 和命令列表

详情请参阅 references/related-apis.md。

产品	API 操作	CLI 命令	描述
RdsAi	ChatMessages	aliyun rdsai chat-messages	RDS AI 助手对话 API
RdsAi	GetChatModel	aliyun rdsai get-chat-model	辅助操作：显式设置 ModelId 时查询可用的聊天模型

---

最佳实践

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

---

参考链接

参考文档	描述
Alibaba Cloud CLI 文档	Alibaba Cloud CLI 用户指南
references/related-apis.md	API 和命令列表
references/ram-policies.md	RAM 策略配置
references/verification-method.md	验证方法
references/acceptance-criteria.md	验收标准