返回技能市场
开发运维 安全

PolarDB AI助手

@aliyun/alibabacloud-polardb-ai-assistant

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

云Skills门户 热度 46v0.0.3

PolarDB 数据库 AI 助手

此 Skill 专注于阿里云 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。不得将此 Skill 用于非 PolarDB 产品的运维请求，除非用户请求明确涉及 PolarDB 集成或比较。

支持的能力

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

后端执行模型

本地 Skill 不直接调用 PolarDB MCP 工具，而是向 Yaochi 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 执行会话开始时，必须生成一个可观测性会话 ID；在该会话的所有阿里云 CLI、SDK 和 Terraform 调用中复用同一个值，并且重试或多步骤工作流不得重新生成。会话 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}

安装

预检查：阿里云 CLI 版本必须 >= 3.3.3
运行 aliyun version 以验证版本是否 >= 3.3.3。如果尚未安装或版本过低，
下载该安装程序并审查其内容，然后在本地运行以完成更新，
或参阅 [references/cli-installation-guide.md](references/cli-installation-guide.md) 中的安装说明。
然后，[必须]运行 aliyun configure set --auto-plugin-install true，以启用插件自动安装。
然后，[必须]运行 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 | 可选 | 阿里云 CLI 配置文件名称 | 默认 |

身份认证

凭据使用现有的阿里云 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](references/ram-policies.md)

核心工作流

所有智能运维操作均通过 scripts/call_yaochi_agent.sh 调用。该脚本封装了 aliyun das get-yao-chi-agent（DAS 插件的 kebab-case 命令，支持 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](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 内核和代理版本风险 | | 事件分析 | 分析 PolarDB 事件对 pc-xxx 的影响 |

成功验证

请参见 [references/verification-method.md](references/verification-method.md)

清理

此 Skill 专注于查询和诊断能力，不创建任何资源，无需清理。

以下操作不属于此 Skill 的范围：

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

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

API 和命令表

请参见 [references/related-apis.md](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。

参考链接

| 参考资料 | 说明 | |-----------|-------------| | [references/cli-installation-guide.md](references/cli-installation-guide.md) | 阿里云 CLI 安装和配置指南 | | [references/related-apis.md](references/related-apis.md) | 相关 API 和 CLI 命令列表 | | [references/ram-policies.md](references/ram-policies.md) | RAM 权限策略列表 | | [references/verification-method.md](references/verification-method.md) | 成功验证方法 | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | 验收标准 |

qianwen skills install @aliyun/alibabacloud-polardb-ai-assistant