alibabacloud-polardbx-ai-assistant：PolarDB-X 分布式数据库智能运维助手，提供集群管理、拓扑查询、性能诊断、SQL 优化、数据分布分析、弹性扩缩容诊断、连接会话分析、安全配置审计、备份恢复、参数调优等智能运维能力。

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

本 Skill 为阿里云 PolarDB-X 分布式数据库提供智能运维能力，通过 aliyun CLI DAS 插件调用 DAS（数据库自治服务）get-yao-chi-agent API。

架构：阿里云 CLI -> DAS 插件（Signature V3） -> get-yao-chi-agent API -> PolarDB-X 智能诊断

支持的能力

安装

预检查：需要 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 插件
[必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[必须] 运行 aliyun plugin update 确保本地现有插件始终为最新版本。

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

[必须] 启用 AI-Mode —— Agent Skill 执行需要 AI-mode。
在任何 CLI 调用之前运行以下命令：
```bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ai-assistant"
```

[必须] 在每一个退出点禁用 AI-Mode —— 在交付最终响应之前（无论何种原因），必须先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不再执行 CLI 命令的场景。
AI-mode 仅用于 Agent Skill 调用场景，Skill 停止运行后绝不能保持启用状态。
```bash
aliyun configure ai-mode disable
```

安装 aliyun CLI

curl -fsSL https://aliyuncli.alicdn.com/install.sh | bash

aliyun version # 验证 >= 3.3.3

启用插件自动安装

aliyun configure set --auto-plugin-install true

安装 DAS 插件（get-yao-chi-agent 需要插件支持 Signature V3）

aliyun plugin install --names aliyun-cli-das

安装 jq（用于 JSON 响应解析）

macOS：

brew install jq

Ubuntu/Debian：

sudo apt-get install jq

环境变量

不需要额外环境变量。本 Skill 完全依赖 aliyun CLI 现有凭证配置。

认证

预检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用带有明文凭证值的 aliyun configure set
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，请在此停止。
1. 从 阿里云控制台 获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 在 aliyun configure list 显示有效 profile 后返回并重新运行

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

推荐：OAuth 模式

aliyun configure --mode OAuth

备选：AK 模式（在 agent 会话之外配置）

aliyun configure set \

--mode AK \

--access-key-id <your-access-key-id> \

--access-key-secret <your-access-key-secret> \

--region cn-hangzhou

跨账号访问：RamRoleArn 模式

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。

[必须] 权限失败处理： 当任何命令或 API 调用在执行过程中因权限错误失败时，遵循以下流程：
1. 阅读 references/ram-policies.md 获取本 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请必要权限
3. 暂停并等待用户确认所需权限已授予

参数确认

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

核心工作流

所有智能运维操作必须通过 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。

集群管理

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"

拓扑巡检

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"

性能诊断

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 优化

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"

数据分布

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"

弹性扩缩容

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

参数调优

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

连接与会话

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

备份与恢复

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

安全审计

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

高可用与容灾

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show HA configuration of instance pxc-xxx"

多轮对话（使用上次调用返回的 session ID）

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Continue analysis" --session-id "<session-id>"

指定 profile

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

从 stdin 读取

echo "List instances" | bash $SKILL_DIR/scripts/call_yaochi_agent.sh -

### 典型查询示例

| 场景 | 示例查询 |
|----------|---------------|
| 集群管理 | Show node list of instance pxc-xxx |
| 拓扑 | How many CN and DN nodes does instance pxc-xxx have |
| 性能诊断 | How to troubleshoot high CPU usage on instance pxc-xxx |
| 慢 SQL 分析 | Show slow SQL of instance pxc-xxx in the last hour |
| SQL 优化 | Why is this SELECT statement slow on instance pxc-xxx |
| 数据分布 | Is there data skew in shards of instance pxc-xxx |
| 弹性扩缩容 | What is the scale-out progress of instance pxc-xxx |
| 参数调优 | How to optimize connection pool parameters on instance pxc-xxx |
| 备份与恢复 | When was the latest backup of instance pxc-xxx |
| 存储优化 | What to do about rapid storage growth on instance pxc-xxx |
| 连接排查 | Instance pxc-xxx connection count is maxed out |
| 安全审计 | Check security configuration of instance pxc-xxx |
| 高可用 | Is the DR architecture of instance pxc-xxx reasonable |
| 到期提醒 | Which PolarDB-X instances are about to expire |

成功验证

详细验证步骤见 references/verification-method.md。

清理

本 Skill 仅聚焦查询和诊断能力。它不创建任何资源，因此无需清理。

以下操作不在本 Skill 范围内：

• 创建/删除 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。

参考链接

文档 4 / 6：alibabacloud-analyticdb-postgresql-ai-coaching-best-practice