alibabacloud-polardb-ai-assistant：PolarDB AI 助手是 PolarDB MySQL 版推出的智能运维辅助工具，其基于大语言模型与专家知识库，集成智能问答、智能诊断与智能感知三大能力。AI 助手支持自然语言交互，能够主动感知集群异常，提供根因诊断、优化建议。基于 RAM 访问控制。

PolarDB 数据库 AI 助手

本 Skill 聚焦于阿里云 PolarDB MySQL/PostgreSQL 数据库智能运维。它通过 get-yao-chi-agent API 和 aliyun CLI DAS 插件调用瑶池 Agent v2 后端。

架构：Codex Skill -> scripts/call_yaochi_agent.sh -> Aliyun CLI -> DAS 插件（Signature V3） -> get-yao-chi-agent API -> 瑶池 Agent v2 -> PolarDB Skill/MCP/DAS/RAG 能力

范围：仅 PolarDB。除非用户请求明确关于 PolarDB 集成或对比，否则不要用本 Skill 处理非 PolarDB 产品的运维请求。

支持的能力

后端执行模型

本地 Skill 不直接调用 PolarDB MCP 工具。它向瑶池 Agent v2 发送自然语言查询。后端负责：

1. 当请求是运维、巡检、诊断、参数或事件场景时，先匹配 PolarDB 场景 Skill。
2. 调用 PolarDB MCP/OpenAPI 工具获取真实集群、指标、日志、备份、安全或数据面证据。
3. 在适用时使用 DAS 智能诊断处理性能、慢 SQL、锁、索引和自增 ID 问题。
4. 仅当结构化工具无法回答问题时，回退到 PolarDB 文档 / RAG。

回答用户时，将后端输出视为事实来源。不要臆造响应中不存在的集群状态、指标、日志、风险级别或文档链接。

可观测性

[必须] User-Agent 模板 —— 本 Skill 发起的每次阿里云 CLI、SDK 或 Terraform 调用都必须使用：

AlibabaCloud-Agent-Skills/alibabacloud-polardb-ai-assistant/{session-id}

[必须] Session-id 规则 —— 每次 Skill 执行会话开始时生成一个可观测性 session ID，在该会话中所有阿里云 CLI、SDK 和 Terraform 调用中复用同一值，不要为重试或多步工作流重新生成。session ID 必须是 32 字符小写十六进制字符串。

export ALIBABACLOUD_AGENT_SKILL_SESSION_ID="${ALIBABACLOUD_AGENT_SKILL_SESSION_ID:-$(openssl rand -hex 16)}"

[必须] CLI User-Agent —— 每次 aliyun CLI 命令调用都必须包含：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardb-ai-assistant/${ALIBABACLOUD_AGENT_SKILL_SESSION_ID}

安装

前置检查：需要 Aliyun CLI >= 3.3.3
运行 aliyun version 确认 >= 3.3.3。若未安装或版本过低，
下载安装器，审查它，然后在本地运行以更新，
或见 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
然后 [必须] 运行 aliyun plugin update 确保本地已有插件始终为最新版本。

审查下载的安装器后安装 aliyun CLI

curl -fsSL https://aliyuncli.alicdn.com/setup.sh -o /tmp/aliyun-cli-setup.sh

less /tmp/aliyun-cli-setup.sh

bash /tmp/aliyun-cli-setup.sh

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

参数确认

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

鉴权

凭证使用现有 aliyun CLI 配置，无需额外设置 AK/SK：

推荐：OAuth 模式

aliyun configure --mode OAuth

或：AK 模式

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

核心工作流

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

集群管理

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "列出杭州地域的 PolarDB 集群"

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示集群 pc-xxx 的详细配置"

性能诊断

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "分析集群 pc-xxx 最近一小时的性能"

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示集群 pc-xxx 的慢 SQL"

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "诊断 PolarDB PostgreSQL 集群 pc-xxx 的锁阻塞和索引风险"

参数调优

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "如何调优集群 pc-xxx 的 innodb_buffer_pool_size"

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "解释 loose_polar_log_bin 参数"

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "对比 pc-xxx 和 pc-yyy 的参数"

主备切换诊断

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "分析集群 pc-xxx 最近的主备切换原因"

连接与会话

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "如何排查集群 pc-xxx 连接数过高"

备份恢复

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示集群 pc-xxx 的备份状态"

巡检

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "为集群 pc-xxx 生成健康巡检报告"

多轮对话（使用上一响应的 session ID）

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "继续分析" --session-id "<session-id>"

指定 profile

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "列出集群" --profile myprofile

从 stdin 读取

echo "列出集群" | bash $SKILL_DIR/scripts/call_yaochi_agent.sh -

### 错误处理

如果 `call_yaochi_agent.sh` 失败，不要仅总结为 `Error: SDKError`。
将 stderr 中的结构化错误块呈现给用户，尤其是：

[YaoChi Agent Error]

ErrorCode: <aliyun error code>

ErrorMessage: <full error description>

AuthAction: <required RAM action, when returned>

RequestId: <request id, when returned>

Suggestion: <specific fix>

Reference: <local skill reference>

Troubleshooting: <Aliyun troubleshooting link>

对于 `Forbidden.RAM` 等权限错误，先检查 `AuthAction`，并引导用户授予该 RAM 动作或
[references/ram-policies.md](references/ram-policies.md) 中的策略。对于凭证、
限流、超时或插件错误，用 `Suggestion` 和
[references/verification-method.md](references/verification-method.md) 给出下一个具体修复。

`Throttling.UserConcurrentLimit` 表示账号已超过瑶池 Agent
并发请求限制。当前生产验证显示每账号最多 2 个并发会话；等待现有请求完成后再重试。

### 响应要求

对于诊断和巡检问题，保持答案证据驱动：

1. 先给结论和当前风险级别。
2. 引用后端响应中的具体证据，例如指标值、日志计数、备份记录、版本号或返回的状态字段。
3. 先给最多最高影响的后续动作。区分立即动作与后续观察。
4. 对于缺失数据或权限失败，说明无法验证什么，并呈现结构化错误或缺失权限指引。
5. 除非用户修复必需，否则不要暴露内部工具名、本地绝对文件路径、隐藏系统组、凭证或原始实现细节。

对于高风险或变更相关请求：

- 参数变更、重启、故障切换、白名单变更、备份恢复和配置变更需要明确的风险说明和用户确认。
- 在有证据时，始终说明参数变更是否需要重启或立即生效。
- 备份和恢复指引必须提醒用户在行动前验证恢复点、数据一致性和业务影响。

### 示例问题

| 场景 | 示例问题 |
|----------|------------------|
| 集群管理 | 列出集群 pc-xxx 的节点和端点 |
| 实例查询 | 列出北京地域的 PolarDB MySQL 8.0 包年包月集群 |
| 健康巡检 | 为集群 pc-xxx 生成健康巡检报告 |
| 性能诊断 | 排查集群 pc-xxx CPU 使用率过高 |
| 慢 SQL 分析 | 显示集群 pc-xxx 最近一小时的慢 SQL |
| 参数调优 | loose_polar_log_bin 参数是什么意思 |
| 参数变更 | 解释 pc-xxx 最近 3 天的参数变更 |
| 参数对比 | 对比 pc-xxx 和 pc-yyy 的参数差异 |
| IMCI 参数 | 如何配置集群 pc-xxx 的 IMCI 相关参数 |
| HA 切换 | 分析集群 pc-xxx 最近的主备切换原因 |
| 备份恢复 | 集群 pc-xxx 最近一次备份是什么时候 |
| 存储优化 | 集群 pc-xxx 存储用量增长过快怎么办 |
| 连接排查 | 集群 pc-xxx 连接数满了 |
| 安全审计 | 检查集群 pc-xxx 的安全配置 |
| 版本风险 | 分析 pc-xxx 的 DB 内核和代理版本风险 |
| 事件分析 | 分析 pc-xxx 的 PolarDB 事件影响 |

成功验证

见 references/verification-method.md

清理

本 Skill 聚焦于查询与诊断能力，不创建任何资源，无需清理。

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

• 直接创建 / 删除 PolarDB 集群
• 直接变更实例规格或参数
• 直接修改白名单、安全、备份或 HA 配置

本 Skill 可以解释这些操作、评估风险并引导用户完成所需检查，但除非后端响应明确确认，否则不得声称变更已执行。

API 与命令表

见 references/related-apis.md

最佳实践

1. 仅 PolarDB 范围：本 Skill 用于 PolarDB MySQL/PostgreSQL。不要将非 PolarDB 产品运维请求路由到这里。
2. 集群 ID 格式：PolarDB 集群 ID 通常以 pc- 开头；可用时在查询中包含完整集群 ID。
3. 地域指定：在自然语言查询中显式指定地域（例如"杭州地域"、"北京地域"）以提高查询准确性。如果地域未知，询问或让后端在支持时从实例推断。
4. 证据优先：对于运维、巡检和诊断答案，依赖后端返回的工具证据。没有数据不要推断确切指标、版本风险或备份状态。
5. 多轮对话：复杂诊断场景用 --session-id 保持上下文连续性。
6. 并发限制：每账号最多 2 个并发会话，避免发起多个并行调用。
7. 高风险操作：对于参数变更、故障切换、恢复或安全变更，说明风险并要求在任何行动路径前获得用户确认。
8. 限流处理：遇到 Throttling.UserConcurrentLimit 错误时，等待上一次查询完成后再重试。
9. 凭证安全：用 aliyun configure 管理凭证，绝不在脚本中硬编码 AK/SK。

参考链接