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

支持的功能

Capability	Description
Instance Information	Instance details, cluster configuration, version info
Topology Inspection	CN/DN node distribution, shard topology, data node status
Storage Information	Disk usage, storage capacity, space growth trends
SQL Optimization	Slow SQL analysis, distributed execution plan interpretation, index suggestions, cross-shard query optimization
Cluster Performance Monitoring	QPS/TPS/connections/throughput and other core metrics analysis
Connection & Session Analysis	Connection count monitoring, session troubleshooting, connection pool optimization
Security Audit	Whitelist, SSL, security policy audit
Backup Status Check	Backup completeness, retention policy, point-in-time recovery
Instance Health Check	Instance health status, running state verification
Log Diagnostics	Error log analysis, slow log troubleshooting
Data Distribution Analysis	Shard data skew detection, hotspot shard diagnostics
Elastic Scaling Diagnostics	Scale-out/in status, data migration progress, node load balancing
Parameter Tuning	Kernel parameter interpretation, change impact assessment, configuration recommendations
High Availability & DR	HA configuration assessment, disaster recovery architecture diagnostics, primary-standby status
Expiring Instance Query	Subscription 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

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

Install jq (for JSON response parsing)

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

macOS:

brew install jq

Ubuntu/Debian:

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.
Obtain credentials from Alibaba Cloud Console
Configure credentials outside of this session (via
aliyun configure
in terminal or environment variables in shell profile)
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身份）。

如果没有有效配置文件，请在此处停止操作。
从阿里云控制台获取凭证
在本会话外配置凭证（通过终端的
aliyun configure
命令或shell配置文件中的环境变量）
当
aliyun configure list
显示有效配置文件后，返回并重新运行

凭证通过Aliyun CLI配置管理 — 无需额外设置AK/SK：

bash

undefined

Recommended: OAuth 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

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

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:
Read
references/ram-policies.md
to get the full list of permissions required by this SKILL
Use
ram-permission-diagnose
skill to guide the user through requesting the necessary permissions
Pause and wait until the user confirms that the required permissions have been granted

查看references/ram-policies.md获取完整的权限列表。

[必须] 权限失败处理： 执行过程中任何命令或API调用因权限错误失败时，请遵循以下流程：
阅读
references/ram-policies.md
获取本技能所需的完整权限列表
使用
ram-permission-diagnose
技能引导用户申请必要权限
暂停操作，等待用户确认已授予所需权限

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.

Parameter	Required/Optional	Description	Default Value
`query`	Required	Natural language query content (including region, instance info, etc.)	-
`--session-id`	Optional	Session ID for multi-turn conversation context	-
`--profile`	Optional	aliyun CLI profile name	default

重要：参数确认 — 在执行任何命令或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

典型查询示例

Scenario	Example Query
Cluster Management	Show node list of instance pxc-xxx
Topology	How many CN and DN nodes does instance pxc-xxx have
Performance Diagnostics	How to troubleshoot high CPU usage on instance pxc-xxx
Slow SQL Analysis	Show slow SQL of instance pxc-xxx in the last hour
SQL Optimization	Why is this SELECT statement slow on instance pxc-xxx
Data Distribution	Is there data skew in shards of instance pxc-xxx
Elastic Scaling	What is the scale-out progress of instance pxc-xxx
Parameter Tuning	How to optimize connection pool parameters on instance pxc-xxx
Backup & Restore	When was the latest backup of instance pxc-xxx
Storage Optimization	What to do about rapid storage growth on instance pxc-xxx
Connection Troubleshooting	Instance pxc-xxx connection count is maxed out
Security Audit	Check security configuration of instance pxc-xxx
High Availability	Is the DR architecture of instance pxc-xxx reasonable
Expiration Reminder	Which 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

最佳实践

Instance ID Format: PolarDB-X instance IDs start with
```
pxc-
```
. Always include the full instance ID in queries.
Region Specification: Explicitly specify the region in natural language queries (e.g., "Hangzhou region", "Beijing region") to improve query accuracy.
Multi-turn Conversation: Use
```
--session-id
```
to maintain context continuity in complex diagnostic scenarios.
Concurrency Limit: Maximum 2 concurrent sessions per account. Avoid launching multiple parallel calls.
Distributed Characteristics: When troubleshooting issues, distinguish between CN (Compute Node) and DN (Data Node) layers.
Throttling Handling: If you encounter a
```
Throttling.UserConcurrentLimit
```
error, wait for the previous query to complete before retrying.
Credential Security: Use
```
aliyun configure
```
to manage credentials. Never hardcode AK/SK in scripts.

实例ID格式：PolarDB-X实例ID以
```
pxc-
```
开头。查询时务必包含完整的实例ID。
地域指定：在自然语言查询中明确指定地域（例如“杭州地域”、“北京地域”）以提高查询准确性。
多轮对话：在复杂诊断场景中使用
```
--session-id
```
保持上下文连续性。
并发限制：每个账号最多支持2个并发会话。避免发起多个并行调用。
分布式特性：排查问题时，区分CN（计算节点）和DN（数据节点）层级。
限流处理：如果遇到
```
Throttling.UserConcurrentLimit
```
错误，请等待上一次查询完成后再重试。
凭证安全：使用
```
aliyun configure
```
管理凭证。切勿在脚本中硬编码AK/SK。

Reference Links

参考链接

Reference	Description
references/cli-installation-guide.md	Aliyun CLI installation and configuration guide
references/related-apis.md	Related APIs and CLI command list
references/ram-policies.md	RAM permission policy list
references/verification-method.md	Success verification methods
references/acceptance-criteria.md	Acceptance criteria

参考文档	说明
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	验收标准