alibabacloud-polardb-ai-assistant

PolarDB 数据库 AI 助手

此 Skill 专注于 Alibaba Cloud PolarDB MySQL/PostgreSQL 数据库智能运维。它通过 get-yao-chi-agent API 和 aliyun CLI DAS 插件调用 Yaochi Agent v2 后端。

架构：Codex Skill -> scripts/call_yaochi_agent.sh -> Aliyun CLI -> DAS Plugin (Signature V3) -> get-yao-chi-agent API -> Yaochi Agent v2 -> PolarDB Skill/MCP/DAS/RAG capabilities

范围：仅限 PolarDB。除非用户的请求明确涉及 PolarDB 集成或比较，否则不要将此 Skill 用于非 PolarDB 产品运维请求。

支持的能力

能力	描述
实例查询和筛选	使用自然语言按 ID、引擎、版本、状态、付费类型、可用区、架构、标签、名称、创建时间范围或过期时间范围筛选 PolarDB 集群
实例状态检查	检查运行状态、节点健康状况、版本、锁定/迁移状态、终端节点状态、付费类型和过期情况
集群资源检查	检查 CPU、内存、连接数、IOPS、存储、Serverless PCU 行为、容量压力和趋势分析
连接和会话检查	检查连接使用情况、活跃会话、空闲事务风险、连接趋势和连接池建议
代理性能检查	检查代理 CPU、QPS、连接稳定性、响应时间、终端节点/路由信息和读写分离信号
备份检查	检查备份策略、备份记录、备份任务状态、日志备份/PITR 能力以及备份成功/失败风险
安全检查	检查白名单、公网暴露风险、SSL/TDE、账户安全状况和 SQL 审计配置
高可用性和灾难恢复	检查多可用区/HA 状况、热备状态、GDN/迁移信号、HA 切换记录和灾难恢复准备情况
日志诊断	分析错误日志和慢日志数量、模式，并提供运维建议
Serverless 检查	检查 PCU 最小/最大配置、扩缩容行为、自动暂停状况以及工作负载与资源的匹配情况
参数说明	说明 PolarDB MySQL/PostgreSQL 参数的含义、默认值、风险、最佳实践以及重启/生效范围注意事项
参数变更评估	说明参数修改日志，评估多参数影响，并提供变更风险建议
IMCI 参数说明	说明 PolarDB MySQL IMCI 列存索引参数并提供使用指导
内核和代理版本诊断	分析数据库内核/代理版本差异，基于发行说明评估风险，检查已修复的高风险 Bug，并提供升级建议
HA 切换和事件分析	分析 HA 切换的根因、相关性能/日志证据、事件影响和后续缓解措施
存储诊断	检查存储构成、增长趋势、异常使用情况、冷数据/归档信号，并提供清理或容量建议
SQL 性能诊断	在后端和权限支持的情况下，诊断慢 SQL、执行计划、锁/阻塞和索引优化问题

后端执行模型

本地 Skill 不会直接调用 PolarDB MCP 工具，而是向 Yaochi Agent v2 发送自然语言查询。后端负责：

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

回答用户时，应将后端输出视为事实依据。不要编造响应中未提供的集群状态、指标、日志、风险级别或文档链接。

可观测性

[MUST] User-Agent 模板 — 此 Skill 执行的每次 Alibaba Cloud CLI、SDK 或 Terraform 调用都必须使用： AlibabaCloud-Agent-Skills/alibabacloud-polardb-ai-assistant/{session-id}

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

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

[MUST] 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 中的安装说明。 然后**[MUST]运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 然后[MUST]**运行 aliyun plugin update，确保本地计算机上的所有现有插件始终为最新版本。

# Install aliyun CLI after reviewing the downloaded installer
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  # 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

参数确认

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

参数	必需/可选	说明	默认值
query	必需	自然语言查询内容（包括地域、集群信息）	-
--session-id	可选	用于多轮对话的会话 ID	-
--profile	可选	aliyun CLI 配置名称	default

身份验证

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

# Recommended: OAuth mode
aliyun configure --mode OAuth

# Or: AK mode
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

核心工作流

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

# Cluster management
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List PolarDB clusters in Hangzhou region"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show detailed configuration of cluster pc-xxx"

# Performance diagnostics
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Analyze cluster pc-xxx performance in the last hour"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show slow SQL of cluster pc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Diagnose lock blocking and index risks for PolarDB PostgreSQL cluster pc-xxx"

# Parameter tuning
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "How to tune innodb_buffer_pool_size for cluster pc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Explain loose_polar_log_bin parameter"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Compare parameters between pc-xxx and pc-yyy"

# Primary-standby switchover diagnostics
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Analyze recent primary-standby switchover cause for cluster pc-xxx"

# Connection and session
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "How to troubleshoot high connection count in cluster pc-xxx"

# Backup recovery
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show backup status of cluster pc-xxx"

# Inspection
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Generate a health inspection report for cluster pc-xxx"

# Multi-turn conversation (use session ID from previous response)
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 clusters" --profile myprofile

# Read from stdin
echo "List clusters" | 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 中所述的策略。对于凭证、 限流、超时或插件错误，请使用 Suggestion 和 references/verification-method.md 提供 下一步可执行的修复方法。

Throttling.UserConcurrentLimit 表示账号已超过 Yaochi 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 内核和代理版本风险
事件分析	分析 PolarDB 事件对 pc-xxx 的影响

成功验证

请参阅 references/verification-method.md

清理

此 Skill 侧重于查询和诊断功能，不会创建任何资源，因此无需清理。

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

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

此 Skill 可以说明这些操作、评估风险并指导用户完成必要检查，但除非后端响应明确确认变更已执行，否则不得声称变更已经执行。

API 和命令表

请参阅 references/related-apis.md

最佳实践

1. 仅限 PolarDB：此 Skill 仅用于 PolarDB MySQL/PostgreSQL。请勿将非 PolarDB 产品的 O&M 请求路由至此处。
2. 集群 ID 格式：PolarDB 集群 ID 通常以 pc- 开头；如有完整集群 ID，请在查询中提供。
3. 指定地域：在自然语言查询中明确指定地域（例如“杭州地域”“北京地域”），以提高查询准确性。如果地域未知，请询问用户，或在后端支持的情况下让后端根据实例推断。
4. 证据优先：对于 O&M、检查和诊断类回答，请依据后端返回的工具证据。没有数据时，请勿推断具体指标、版本风险或备份状态。
5. 多轮对话：对于复杂诊断场景，请使用 --session-id 以保持上下文连贯。
6. 并发限制：每个账户最多允许 2 个并发会话，请避免发起多个并行调用。
7. 高风险操作：对于参数更改、故障转移、恢复或安全更改，请说明风险，并在执行任何操作前征得用户确认。
8. 限流处理：如果遇到 Throttling.UserConcurrentLimit 错误，请等待之前的查询完成后重试。
9. 凭证安全：使用 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	验收标准