Back to Details

alibabacloud-polardbx-ai-assistant

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PolarDB-X Distributed Database AI Assistant

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

This skill provides intelligent O&M capabilities for Alibaba Cloud PolarDB-X distributed database, powered by the DAS (Database Autonomy Service) 
get-yao-chi-agent
API via the aliyun CLI DAS plugin.
Architecture: 
Aliyun CLI
-> 
DAS Plugin (Signature V3)
-> 
get-yao-chi-agent API
-> PolarDB-X Intelligent Diagnostics
本技能为阿里云PolarDB-X分布式数据库提供智能运维能力，通过阿里云CLI DAS插件调用DAS（Database Autonomy Service）的
get-yao-chi-agent
API实现。
架构：
Aliyun CLI
-> 
DAS Plugin (Signature V3)
-> 
get-yao-chi-agent API
-> PolarDB-X智能诊断

Supported Capabilities

支持的功能

CapabilityDescription
Instance InformationInstance details, cluster configuration, version info
Topology InspectionCN/DN node distribution, shard topology, data node status
Storage InformationDisk usage, storage capacity, space growth trends
SQL OptimizationSlow SQL analysis, distributed execution plan interpretation, index suggestions, cross-shard query optimization
Cluster Performance MonitoringQPS/TPS/connections/throughput and other core metrics analysis
Connection & Session AnalysisConnection count monitoring, session troubleshooting, connection pool optimization
Security AuditWhitelist, SSL, security policy audit
Backup Status CheckBackup completeness, retention policy, point-in-time recovery
Instance Health CheckInstance health status, running state verification
Log DiagnosticsError log analysis, slow log troubleshooting
Data Distribution AnalysisShard data skew detection, hotspot shard diagnostics
Elastic Scaling DiagnosticsScale-out/in status, data migration progress, node load balancing
Parameter TuningKernel parameter interpretation, change impact assessment, configuration recommendations
High Availability & DRHA configuration assessment, disaster recovery architecture diagnostics, primary-standby status
Expiring Instance QuerySubscription instance expiration reminders, renewal status
功能说明
实例信息实例详情、集群配置、版本信息
拓扑巡检CN/DN节点分布、分片拓扑、数据节点状态
存储信息磁盘使用率、存储容量、空间增长趋势
SQL优化慢SQL分析、分布式执行计划解读、索引建议、跨分片查询优化
集群性能监控QPS/TPS/连接数/吞吐量等核心指标分析
连接与会话分析连接数监控、会话问题排查、连接池优化
安全审计白名单、SSL、安全策略审计
备份状态检查备份完整性、保留策略、时点恢复
实例健康检查实例健康状态、运行状态验证
日志诊断错误日志分析、慢日志问题排查
数据分布分析分片数据倾斜检测、热点分片诊断
弹性扩缩容诊断扩缩容状态、数据迁移进度、节点负载均衡
参数调优内核参数解读、变更影响评估、配置建议
高可用与容灾HA配置评估、容灾架构诊断、主备状态
到期实例查询包年包月实例到期提醒、续费状态

Installation

安装

Pre-check: Aliyun CLI >= 3.3.3 required Run 
aliyun version
to verify >= 3.3.3. If not installed or version too low, run 
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
to install/update, or see references/cli-installation-guide.md for installation instructions.
Pre-check: Aliyun CLI plugin update required [MUST] run 
aliyun configure set --auto-plugin-install true
to enable automatic plugin installation. [MUST] run 
aliyun plugin update
to ensure that any existing plugins on your local machine are always up-to-date.
[MUST] CLI User-Agent — Every 
aliyun
CLI command invocation must include: 
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ai-assistant
[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:
bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ai-assistant"
[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
bash
aliyun configure ai-mode disable
bash
undefined
预检查：需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模式 — 执行Agent技能需要AI模式。 在调用任何CLI命令前运行以下命令：
bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ai-assistant"
[必须] 在所有退出点禁用AI模式 — 无论因何种原因返回最终响应前，务必先禁用AI模式。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束或任何其他不再执行CLI命令的场景。 AI模式仅用于Agent技能调用场景，技能停止运行后必须禁用。
bash
aliyun configure ai-mode disable
bash
undefined

Install aliyun CLI

安装Aliyun CLI

curl -fsSL https://aliyuncli.alicdn.com/install.sh | bash aliyun version # Verify >= 3.3.3
curl -fsSL https://aliyuncli.alicdn.com/install.sh | bash aliyun version # 验证版本>=3.3.3

Enable automatic plugin installation

启用自动插件安装

aliyun configure set --auto-plugin-install true
aliyun configure set --auto-plugin-install true

Install DAS plugin (get-yao-chi-agent requires plugin for Signature V3 support)

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

aliyun plugin install --names aliyun-cli-das
aliyun plugin install --names aliyun-cli-das

Install jq (for JSON response parsing)

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

macOS:

macOS:

brew install jq
brew install jq

Ubuntu/Debian:

Ubuntu/Debian:

sudo apt-get install jq

sudo apt-get install jq

undefined
undefined

Environment Variables

环境变量

No additional environment variables are required. This skill relies entirely on the aliyun CLI's existing credential configuration.
无需额外环境变量。本技能完全依赖Aliyun CLI现有的凭证配置。

Authentication

身份认证

Pre-check: Alibaba Cloud Credentials Required
Security Rules:
  • NEVER read, echo, or print AK/SK values (e.g., 
    echo $ALIBABA_CLOUD_ACCESS_KEY_ID
    is FORBIDDEN)
  • NEVER ask the user to input AK/SK directly in the conversation or command line
  • NEVER use 
    aliyun configure set
    with literal credential values
  • ONLY use 
    aliyun configure list
    to check credential status
bash
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).
If no valid profile exists, STOP here.
  1. Obtain credentials from Alibaba Cloud Console
  2. Configure credentials outside of this session (via 
    aliyun configure
    in terminal or environment variables in shell profile)
  3. Return and re-run after 
    aliyun configure list
    shows a valid profile
Credentials are managed through aliyun CLI configuration — no additional AK/SK setup is needed:
bash
undefined
预检查：需阿里云凭证
安全规则：
  • 禁止读取、回显或打印AK/SK值（例如
    echo $ALIBABA_CLOUD_ACCESS_KEY_ID
    是禁止操作）
  • 禁止要求用户在对话或命令行中直接输入AK/SK
  • 禁止使用带明文凭证值的
    aliyun configure set
    命令
  • 仅允许使用
    aliyun configure list
    检查凭证状态
bash
aliyun configure list
检查输出是否包含有效的配置文件（AK、STS或OAuth身份）。
如果没有有效配置文件，请在此处停止操作。
  1. 从阿里云控制台获取凭证
  2. 在本会话外配置凭证（通过终端的
    aliyun configure
    命令或shell配置文件中的环境变量）
  3. 当
    aliyun configure list
    显示有效配置文件后，返回并重新运行
凭证通过Aliyun CLI配置管理 — 无需额外设置AK/SK：
bash
undefined

Recommended: OAuth mode

推荐：OAuth模式

aliyun configure --mode OAuth
aliyun configure --mode OAuth

Alternative: AK mode (configure outside of agent session)

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

aliyun configure set
--mode AK
--access-key-id <your-access-key-id>
--access-key-secret <your-access-key-secret>
--region cn-hangzhou
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

跨账号访问：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
undefined
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
undefined

RAM Policy

RAM权限

See references/ram-policies.md for the full list of required permissions.
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
  1. Read 
    references/ram-policies.md
    to get the full list of permissions required by this SKILL
  2. Use 
    ram-permission-diagnose
    skill to guide the user through requesting the necessary permissions
  3. Pause and wait until the user confirms that the required permissions have been granted
查看references/ram-policies.md获取完整的权限列表。
[必须] 权限失败处理： 执行过程中任何命令或API调用因权限错误失败时，请遵循以下流程：
  1. 阅读
    references/ram-policies.md
    获取本技能所需的完整权限列表
  2. 使用
    ram-permission-diagnose
    技能引导用户申请必要权限
  3. 暂停操作，等待用户确认已授予所需权限

Parameter Confirmation

参数确认

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.
ParameterRequired/OptionalDescriptionDefault Value
query
RequiredNatural language query content (including region, instance info, etc.)-
--session-id
OptionalSession ID for multi-turn conversation context-
--profile
Optionalaliyun CLI profile namedefault
重要：参数确认 — 在执行任何命令或API调用前， 所有用户可自定义的参数（例如RegionId、实例名称、CIDR块、 密码、域名、资源规格等）必须与用户确认。未经用户明确批准，不得假设或使用默认值。
参数必填/可选说明默认值
query
必填自然语言查询内容（包含地域、实例信息等）-
--session-id
可选多轮对话上下文的会话ID-
--profile
可选Aliyun CLI配置文件名称default

Core Workflow

核心工作流

All intelligent O&M operations MUST be invoked through 
scripts/call_yaochi_agent.sh
, which wraps the 
aliyun das get-yao-chi-agent
(DAS plugin kebab-case command, supporting Signature V3) with streaming response parsing.
⚠️ CRITICAL RESTRICTION:
  • DO NOT use direct 
    aliyun polardbx
    or 
    aliyun rds
    CLI commands for diagnostics, topology, or security audits.
  • DO NOT attempt to query instance details using 
    DescribeDBInstances
    or similar APIs directly.
  • ONLY use the DAS plugin command: 
    aliyun das get-yao-chi-agent
    (wrapped by 
    call_yaochi_agent.sh
    ).
  • If the script fails, check permissions via 
    ram-permission-diagnose
    skill, DO NOT fallback to other product APIs.
bash
undefined
所有智能运维操作必须通过
scripts/call_yaochi_agent.sh
调用，该脚本封装了
aliyun das get-yao-chi-agent
（支持Signature V3的DAS插件短横线命名命令）并实现流式响应解析。
⚠️ 关键限制：
  • 禁止使用直接的
    aliyun polardbx
    或
    aliyun rds
    CLI命令进行诊断、拓扑或安全审计。
  • 禁止尝试直接使用
    DescribeDBInstances
    或类似API查询实例详情。
  • 仅允许使用DAS插件命令：
    aliyun das get-yao-chi-agent
    （由
    call_yaochi_agent.sh
    封装）。
  • 如果脚本失败，通过
    ram-permission-diagnose
    技能检查权限，禁止 fallback到其他产品API。
bash
undefined

Cluster Management

集群管理

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 "列出杭州地域的PolarDB-X实例" bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示实例pxc-xxx的详细配置"

Topology Inspection

拓扑巡检

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 "显示实例pxc-xxx的CN/DN节点分布" bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示实例pxc-xxx的分片拓扑"

Performance Diagnostics

性能诊断

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"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "分析实例pxc-xxx过去一小时的性能" bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示实例pxc-xxx的慢SQL"

SQL Optimization

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 "优化这条SQL在实例pxc-xxx上的执行计划" bash $SKILL_DIR/scripts/call_yaochi_agent.sh "实例pxc-xxx上哪些跨分片查询需要优化"

Data Distribution

数据分布

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 "检查实例pxc-xxx的数据分布是否均匀" bash $SKILL_DIR/scripts/call_yaochi_agent.sh "实例pxc-xxx是否存在热点分片"

Elastic Scaling

弹性扩缩容

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show scale-out status of instance pxc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示实例pxc-xxx的扩容状态"

Parameter Tuning

参数调优

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 "如何调优实例pxc-xxx的CONN_POOL_MAX_POOL_SIZE参数"

Connection & Session

连接与会话

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 "如何排查实例pxc-xxx的连接数过高问题"

Backup & Restore

备份恢复

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show backup status of instance pxc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示实例pxc-xxx的备份状态"

Security Audit

安全审计

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Check security configuration of instance pxc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "检查实例pxc-xxx的安全配置"

High Availability & DR

高可用与容灾

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show HA configuration of instance pxc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "显示实例pxc-xxx的HA配置"

Multi-turn Conversation (use session ID returned from previous call)

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

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

Specify profile

指定配置文件

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List instances" --profile myprofile
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "列出实例" --profile myprofile

Read from stdin

从标准输入读取

echo "List instances" | bash $SKILL_DIR/scripts/call_yaochi_agent.sh -
undefined
echo "列出实例" | bash $SKILL_DIR/scripts/call_yaochi_agent.sh -
undefined

Typical Query Examples

典型查询示例

ScenarioExample Query
Cluster ManagementShow node list of instance pxc-xxx
TopologyHow many CN and DN nodes does instance pxc-xxx have
Performance DiagnosticsHow to troubleshoot high CPU usage on instance pxc-xxx
Slow SQL AnalysisShow slow SQL of instance pxc-xxx in the last hour
SQL OptimizationWhy is this SELECT statement slow on instance pxc-xxx
Data DistributionIs there data skew in shards of instance pxc-xxx
Elastic ScalingWhat is the scale-out progress of instance pxc-xxx
Parameter TuningHow to optimize connection pool parameters on instance pxc-xxx
Backup & RestoreWhen was the latest backup of instance pxc-xxx
Storage OptimizationWhat to do about rapid storage growth on instance pxc-xxx
Connection TroubleshootingInstance pxc-xxx connection count is maxed out
Security AuditCheck security configuration of instance pxc-xxx
High AvailabilityIs the DR architecture of instance pxc-xxx reasonable
Expiration ReminderWhich PolarDB-X instances are about to expire
场景示例查询
集群管理显示实例pxc-xxx的节点列表
拓扑实例pxc-xxx有多少个CN和DN节点
性能诊断如何排查实例pxc-xxx的CPU使用率过高问题
慢SQL分析显示实例pxc-xxx过去一小时的慢SQL
SQL优化为什么这条SELECT语句在实例pxc-xxx上运行缓慢
数据分布实例pxc-xxx的分片是否存在数据倾斜
弹性扩缩容实例pxc-xxx的扩容进度如何
参数调优如何优化实例pxc-xxx的连接池参数
备份恢复实例pxc-xxx的最新备份是什么时候
存储优化实例pxc-xxx存储快速增长该怎么办
连接问题排查实例pxc-xxx的连接数已达上限
安全审计检查实例pxc-xxx的安全配置
高可用实例pxc-xxx的容灾架构是否合理
到期提醒哪些PolarDB-X实例即将到期

Success Verification

成功验证

See references/verification-method.md for detailed verification steps.
查看references/verification-method.md获取详细验证步骤。

Cleanup

清理

This skill focuses on query and diagnostics capabilities only. It does not create any resources, so no cleanup is needed.
The following operations are out of scope for this skill:
  • Creating/deleting PolarDB-X instances
  • Changing instance specifications
  • Purchasing/renewing instances
本技能仅专注于查询与诊断能力，不会创建任何资源，因此无需清理。
以下操作不属于本技能的范围：
  • 创建/删除PolarDB-X实例
  • 修改实例规格
  • 购买/续费实例

Command Tables

命令表

See references/related-apis.md for the full list of APIs and CLI commands.
查看references/related-apis.md获取完整的API和CLI命令列表。

Best Practices

最佳实践

  1. Instance ID Format: PolarDB-X instance IDs start with 
    pxc-
    . Always include the full instance ID in queries.
  2. Region Specification: Explicitly specify the region in natural language queries (e.g., "Hangzhou region", "Beijing region") to improve query accuracy.
  3. Multi-turn Conversation: Use 
    --session-id
    to maintain context continuity in complex diagnostic scenarios.
  4. Concurrency Limit: Maximum 2 concurrent sessions per account. Avoid launching multiple parallel calls.
  5. Distributed Characteristics: When troubleshooting issues, distinguish between CN (Compute Node) and DN (Data Node) layers.
  6. Throttling Handling: If you encounter a 
    Throttling.UserConcurrentLimit
    error, wait for the previous query to complete before retrying.
  7. Credential Security: Use 
    aliyun configure
    to manage credentials. Never hardcode AK/SK in scripts.
  1. 实例ID格式：PolarDB-X实例ID以
    pxc-
    开头。查询时务必包含完整的实例ID。
  2. 地域指定：在自然语言查询中明确指定地域（例如“杭州地域”、“北京地域”）以提高查询准确性。
  3. 多轮对话：在复杂诊断场景中使用
    --session-id
    保持上下文连续性。
  4. 并发限制：每个账号最多支持2个并发会话。避免发起多个并行调用。
  5. 分布式特性：排查问题时，区分CN（计算节点）和DN（数据节点）层级。
  6. 限流处理：如果遇到
    Throttling.UserConcurrentLimit
    错误，请等待上一次查询完成后再重试。
  7. 凭证安全：使用
    aliyun configure
    管理凭证。切勿在脚本中硬编码AK/SK。

Reference Links

参考链接

ReferenceDescription
references/cli-installation-guide.mdAliyun CLI installation and configuration guide
references/related-apis.mdRelated APIs and CLI command list
references/ram-policies.mdRAM permission policy list
references/verification-method.mdSuccess verification methods
references/acceptance-criteria.mdAcceptance criteria
参考文档说明
references/cli-installation-guide.mdAliyun CLI安装与配置指南
references/related-apis.md相关API和CLI命令列表
references/ram-policies.mdRAM权限策略列表
references/verification-method.md成功验证方法
references/acceptance-criteria.md验收标准