PolarDB 数据库 AI 助手是一个专注于阿里云 PolarDB MySQL/PostgreSQL 数据库智能运维的技能。它通过 get-yao-chi-agent API 以及 aliyun CLI 的 DAS 插件调用瑶池 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 能力。本地技能不直接调用 PolarDB MCP 工具，而是向后端发送自然语言查询，由后端负责匹配 PolarDB 场景技能、调用 MCP/OpenAPI 工具获取真实集群、指标、日志、备份、安全或数据面证据，在适用时使用 DAS 智能诊断处理性能、慢 SQL、锁、索引与自增 ID 问题，仅在结构化工具无法回答时回退到 PolarDB 文档/RAG。回答时应以后端输出为准，不得编造集群状态、指标、日志、风险等级或文档链接。
二、适用范围 本技能仅用于 PolarDB。除非用户请求明确涉及 PolarDB 集成或对比，否则不要将其用于非 PolarDB 产品的运维请求。本技能聚焦查询与诊断，不创建任何资源。
三、支持的能力
- 实例查询与过滤：按 ID、引擎、版本、状态、付费类型、可用区、架构、标签、名称、创建窗口或到期窗口对 PolarDB 集群进行自然语言过滤。
- 实例状态巡检：运行状态、节点健康、版本、锁定/迁移状态、端点状态、付费类型与到期检查。
- 集群资源检查：CPU、内存、连接、IOPS、存储、Serverless PCU 行为、容量压力与趋势分析。
- 连接与会话检查：连接使用率、活跃会话、空闲事务风险、连接趋势与连接池建议。
- Proxy 性能检查：Proxy CPU、QPS、连接稳定性、响应时间、端点/路由信息与读写分离信号检查。
- 备份检查：备份策略、备份记录、备份任务状态、日志备份/PITR 能力与备份成功/失败风险。
- 安全巡检：白名单、公网暴露风险、SSL/TDE、账号安全态势与 SQL 审计配置。
- 高可用与容灾：多可用区/HA 态势、热备状态、GDN/迁移信号、HA 切换记录与容灾就绪度。
- 日志诊断：错误日志与慢日志量、模式分析与运维建议。
- Serverless 检查：PCU 最小/最大配置、扩缩容行为、自动暂停态势与工作负载-资源匹配度。
- 参数解释：PolarDB MySQL/PostgreSQL 参数含义、默认值、风险、最佳实践与重启/生效范围说明。
- 参数变更评估：参数修改日志解释、多参数影响评估与变更风险建议。
- IMCI 参数解释：PolarDB MySQL IMCI 列存索引参数解释与使用指导。
- 内核与 Proxy 版本诊断：数据库内核/Proxy 版本差距分析、基于 Release Note 的风险评估、高危已修复 Bug 检查与升级建议。
- HA 切换与事件分析：HA 切换根因、相关性能/日志证据、事件影响与后续缓解措施。
- 存储诊断：存储构成、增长趋势、异常使用、冷数据/归档信号与清理或容量建议。
- SQL 性能诊断：在后端与权限支持时，进行慢 SQL、执行计划、锁/阻塞与索引优化诊断。
四、可观测性要求 每次由本技能发起的阿里云 CLI、SDK 或 Terraform 调用必须使用 User-Agent 模板：AlibabaCloud-Agent-Skills/alibabacloud-polardb-ai-assistant/{session-id}。每次技能执行会话开始时生成一个 32 位小写十六进制字符串作为会话 ID，并在该会话内所有调用中复用，重试或多步流程不重新生成。 示例：export ALIBABACLOUD_AGENT_SKILL_SESSION_ID="${ALIBABACLOUD_AGENT_SKILL_SESSION_ID:-$(openssl rand -hex 16)}" 所有 aliyun CLI 命令必须包含：--user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardb-ai-assistant/${ALIBABACLOUD_AGENT_SKILL_SESSION_ID}。
五、安装与配置 前置检查：需要 Aliyun CLI 版本 >= 3.3.3。运行 aliyun version 验证。若未安装或版本过低，可下载安装脚本、审查后在本地运行更新，或参阅 references/cli-installation-guide.md。随后必须运行 aliyun configure set --auto-plugin-install true 启用自动插件安装，并运行 aliyun plugin update 确保本地已有插件为最新。 安装示例命令： 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
启用自动插件安装
aliyun configure set --auto-plugin-install true
安装 DAS 插件
aliyun plugin install --names aliyun-cli-das
安装 jq（用于解析 JSON 响应）
macOS: brew install jq
Ubuntu/Debian: sudo apt-get install jq
六、参数确认 在执行任何命令或 API 调用前，所有用户可自定义参数（如 RegionId、实例名称、CIDR、密码、域名、资源规格等）必须与用户确认，不得在未获明确同意时假设或使用默认值。主要参数包括：query（必填，自然语言查询内容，含地域与集群信息）、--session-id（可选，多轮会话 ID）、--profile（可选，aliyun CLI profile 名称，默认 default）。
七、认证 凭据复用现有 aliyun CLI 配置，无需额外设置 AK/SK。推荐使用 OAuth 模式：aliyun configure --mode OAuth。也可使用 AK 模式或跨账号的 RamRoleArn 模式。RAM 策略参见 references/ram-policies.md。
八、核心工作流 所有智能运维操作通过 scripts/call_yaochi_agent.sh 调用，该脚本封装 aliyun das get-yao-chi-agent（DAS 插件 kebab-case 命令，支持 Signature V3）并解析流式响应。示例包括集群管理、性能诊断、参数调优、主备切换诊断、连接与会话、备份恢复、巡检、多轮会话、指定 profile 及从 stdin 读取等调用方式。
九、错误处理 若 call_yaochi_agent.sh 失败，不要只概括为 Error: SDKError，应将 stderr 中的结构化错误块呈现给用户，包括 ErrorCode、ErrorMessage、AuthAction、RequestId、Suggestion、Reference、Troubleshooting。对于 Forbidden.RAM 等权限错误，先查看 AuthAction 并引导用户授予相应 RAM 操作或策略。Throttling.UserConcurrentLimit 表示账号超过瑶池 Agent 并发限制，当前生产验证显示每账号最多 2 个并发会话，需等待已有请求完成后再重试。
十、响应要求 诊断与巡检类问题应基于证据：先给结论与当前风险等级，引用后端响应中的具体证据（指标值、日志计数、备份记录、版本号或返回的状态字段），优先给出最高影响的后续操作并区分即时操作与后续观察。对缺失数据或权限失败，说明无法验证的内容并给出结构化错误或缺失权限指引。不要暴露内部工具名、本地绝对路径、隐藏系统组、凭据或原始实现细节，除非用户修复所必需。高风险或变更类请求（参数变更、重启、故障切换、白名单变更、备份恢复与配置变更）需明确风险说明与用户确认；参数变更应说明是否需要重启或立即生效；备份恢复指导需提醒用户先确认恢复点、数据一致性与业务影响。
十一、限制与边界 以下操作不在本技能范围内：直接创建/删除 PolarDB 集群；直接变更实例规格或参数；直接修改白名单、安全、备份或 HA 配置。技能可解释这些操作、评估风险并引导用户完成必要检查，但除非后端响应明确确认，不得声称变更已执行。
十二、最佳实践 仅限 PolarDB 范围；集群 ID 通常以 pc- 开头，查询时尽量包含完整 ID；自然语言查询中明确地域；运维、巡检与诊断答案依赖后端返回的工具证据，无数据时不推断具体指标、版本风险或备份状态；复杂诊断使用 --session-id 维持上下文；避免多个并行调用（每账号最多 2 个并发会话）；高风险操作需先说明风险并要求用户确认；遇到限流错误等待后重试；使用 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（验收标准）。