alibabacloud-polardbx-ai-assistant

PolarDB-X 分布式数据库 AI 助手

此技能通过 aliyun CLI DAS 插件调用 DAS（数据库自治服务）的 get-yao-chi-agent API，为 Alibaba Cloud PolarDB-X 分布式数据库提供智能运维能力。

架构：Aliyun CLI -> DAS Plugin (Signature V3) -> get-yao-chi-agent API -> PolarDB-X 智能诊断

支持的能力

能力	描述
实例信息	实例详情、集群配置、版本信息
拓扑检查	CN/DN 节点分布、分片拓扑、数据节点状态
存储信息	磁盘使用量、存储容量、空间增长趋势
SQL 优化	慢 SQL 分析、分布式执行计划解读、索引建议、跨分片查询优化
集群性能监控	QPS/TPS/连接数/吞吐量等核心指标分析
连接与会话分析	连接数监控、会话故障排查、连接池优化
安全审计	白名单、SSL、安全策略审计
备份状态检查	备份完整性、保留策略、时间点恢复
实例健康检查	实例健康状态、运行状态验证
日志诊断	错误日志分析、慢日志故障排查
数据分布分析	分片数据倾斜检测、热点分片诊断
弹性伸缩诊断	扩缩容状态、数据迁移进度、节点负载均衡
参数调优	内核参数解读、变更影响评估、配置建议
高可用与灾备	高可用配置评估、灾备架构诊断、主备状态
即将到期实例查询	订阅实例到期提醒、续费状态

安装

前置检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装或更新， 或参阅 references/cli-installation-guide.md 获取安装说明。

前置检查：需要更新 Aliyun CLI 插件 [MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保本地计算机上已有的插件始终保持最新。

[MUST] CLI User-Agent — 每次调用 aliyun CLI 命令都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ai-assistant

[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-polardbx-ai-assistant"

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

aliyun configure ai-mode disable

# Install aliyun CLI
curl -fsSL https://aliyuncli.alicdn.com/install.sh | bash
aliyun version  # Verify >= 3.3.3

# Enable automatic plugin installation
aliyun configure set --auto-plugin-install true

# Install DAS plugin (get-yao-chi-agent requires plugin for Signature V3 support)
aliyun plugin install --names aliyun-cli-das

# Install jq (for JSON response parsing)
# macOS:
brew install jq
# Ubuntu/Debian:
# sudo apt-get install jq

环境变量

无需设置其他环境变量。此技能完全依赖 aliyun CLI 中现有的凭证配置。

身份验证

预检：需要 Alibaba Cloud 凭证

安全规则：

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

aliyun configure list

检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效配置文件，请在此处停止。

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

凭证通过 aliyun CLI 配置管理，无需额外设置 AK/SK：

# Recommended: OAuth mode
aliyun configure --mode OAuth

# Alternative: AK mode (configure outside of agent session)
aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

# Cross-account access: RamRoleArn mode
aliyun configure set \
  --mode RamRoleArn \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --ram-role-arn acs:ram::<account-id>:role/<role-name> \
  --role-session-name yaochi-agent-session \
  --region cn-hangzhou

RAM 策略

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

[MUST] 权限失败处理： 在执行过程中的任何时候，如果命令或 API 调用因权限错误而失败，请按以下流程处理：

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

参数确认

重要：参数确认 — 执行任何命令或 API 调用之前， 必须与用户确认所有可自定义参数（例如 RegionId、实例名称、CIDR 网段、 密码、域名、资源规格等）。未经用户明确批准，不得假设或使用默认值。

参数	必填/可选	描述	默认值
query	必填	自然语言查询内容（包括地域、实例信息等）	-
--session-id	可选	多轮对话上下文的会话 ID	-
--profile	可选	aliyun CLI 配置文件名称	default

核心工作流

所有智能运维操作必须通过 scripts/call_yaochi_agent.sh 调用。该脚本封装了 aliyun das get-yao-chi-agent（DAS 插件的 kebab-case 命令，支持 Signature V3），并解析流式响应。

⚠️ 严格限制：

• 不得使用直接的 aliyun polardbx 或 aliyun rds CLI 命令进行诊断、拓扑查询或安全审计。
• 不得尝试直接使用 DescribeDBInstances 或类似 API 查询实例详情。
• 只能使用 DAS 插件命令：aliyun das get-yao-chi-agent（由 call_yaochi_agent.sh 封装）。
• 如果脚本失败，请通过 ram-permission-diagnose skill 检查权限，不得改用其他产品 API。

# Cluster Management
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List PolarDB-X instances in Hangzhou region"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show detailed configuration of instance pxc-xxx"

# Topology Inspection
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show CN/DN node distribution of instance pxc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show shard topology of instance pxc-xxx"

# Performance Diagnostics
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Analyze performance of instance pxc-xxx in the last hour"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show slow SQL of instance pxc-xxx"

# SQL Optimization
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Optimize execution plan of this SQL on instance pxc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Which cross-shard queries on instance pxc-xxx need optimization"

# Data Distribution
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Check whether data distribution of instance pxc-xxx is even"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Are there any hotspot shards on instance pxc-xxx"

# Elastic Scaling
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show scale-out status of instance pxc-xxx"

# Parameter Tuning
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "How to tune CONN_POOL_MAX_POOL_SIZE parameter on instance pxc-xxx"

# Connection & Session
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "How to troubleshoot high connection count on instance pxc-xxx"

# Backup & Restore
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show backup status of instance pxc-xxx"

# Security Audit
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Check security configuration of instance pxc-xxx"

# High Availability & DR
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show HA configuration of instance pxc-xxx"

# Multi-turn Conversation (use session ID returned from previous call)
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Continue analysis" --session-id "<session-id>"

# Specify profile
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List instances" --profile myprofile

# Read from stdin
echo "List instances" | bash $SKILL_DIR/scripts/call_yaochi_agent.sh -

典型查询示例

场景	示例查询
集群管理	显示实例 pxc-xxx 的节点列表
拓扑结构	实例 pxc-xxx 有多少个 CN 和 DN 节点
性能诊断	如何排查实例 pxc-xxx 的 CPU 使用率过高问题
慢 SQL 分析	显示实例 pxc-xxx 最近一小时的慢 SQL
SQL 优化	为什么这条 SELECT 语句在实例 pxc-xxx 上执行缓慢
数据分布	实例 pxc-xxx 的分片是否存在数据倾斜
弹性扩缩容	实例 pxc-xxx 的扩容进度如何
参数调优	如何优化实例 pxc-xxx 的连接池参数
备份与恢复	实例 pxc-xxx 最近一次备份是什么时候
存储优化	如何处理实例 pxc-xxx 存储快速增长的问题
连接故障排查	实例 pxc-xxx 的连接数已达到上限
安全审计	检查实例 pxc-xxx 的安全配置
高可用	实例 pxc-xxx 的容灾架构是否合理
到期提醒	哪些 PolarDB-X 实例即将到期

成功验证

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

清理

此技能仅关注查询和诊断能力，不会创建任何资源，因此无需清理。

以下操作不在此技能的范围内：

• 创建或删除 PolarDB-X 实例
• 更改实例规格
• 购买或续费实例

命令表

完整的 API 和 CLI 命令列表请参阅 references/related-apis.md。

最佳实践

1. 实例 ID 格式：PolarDB-X 实例 ID 以 pxc- 开头。查询时始终提供完整的实例 ID。
2. 指定地域：在自然语言查询中明确指定地域（例如“杭州地域”“北京地域”），以提高查询准确性。
3. 多轮对话：在复杂的诊断场景中使用 --session-id 保持上下文连贯。
4. 并发限制：每个账号最多允许 2 个并发会话。避免发起多个并行调用。
5. 分布式特性：排查问题时，区分 CN（计算节点）层和 DN（数据节点）层。
6. 限流处理：如果遇到 Throttling.UserConcurrentLimit 错误，请等待之前的查询完成后再重试。
7. 凭证安全：使用 aliyun configure 管理凭证。切勿在脚本中硬编码 AK/SK。

参考链接

参考资料	描述
references/cli-installation-guide.md	Aliyun CLI 安装和配置指南
references/related-apis.md	相关 API 和 CLI 命令列表
references/ram-policies.md	RAM 权限策略列表
references/verification-method.md	成功验证方法
references/acceptance-criteria.md	验收标准