Alibabacloud Polardbx Ai Assistant

Alibaba Cloud PolarDB-X Distributed Database AI Assistant. Use for PolarDB-X cluster management, topology inspection, performance diagnostics, SQL optimizati...

Security Scan

The skill and its included script are internally consistent with a PolarDB‑X diagnostic assistant that calls Alibaba Cloud's DAS YaoChi agent via the aliyun CLI; no disproportionate secrets, strange downloads, or unrelated capabilities were found, though there are minor doc/script inconsistencies and the script will install an aliyun plugin on the host.

Purpose & Capability

The skill's name, description, and runtime files all revolve around invoking the DAS get-yao-chi-agent API via the aliyun CLI and the DAS plugin — this matches the stated purpose. Minor inconsistency: documentation/acceptance examples use --source "polardbx-console" while the script sets SOURCE="polarx"; this is likely a small config mismatch but not a functional red flag.

Instruction Scope

SKILL.md and the bash script limit actions to running the aliyun CLI, optionally auto-installing the DAS plugin, parsing SSE/streaming JSON responses with jq, and emitting session IDs. The instructions explicitly forbid printing or asking for AK/SK in conversation and require credentials to be managed outside the agent session. No instructions ask the agent to read unrelated system files or exfiltrate data to third parties.

Install Mechanism

There is no install spec; this is an instruction-only skill with a bash helper. The script may call `aliyun plugin install --names aliyun-cli-das` if the plugin is missing; that uses the official aliyun CLI plugin mechanism. The installation guidance references official aliyuncli.alicdn.com binaries. No downloads from unknown/personal hosts or URL shorteners were seen.

Credentials

The skill requests no extra environment variables and relies on the aliyun CLI configuration (profiles, env vars, or ECS role) — which is appropriate for a CLI-based integration. The required DAS IAM actions in references/ram-policies.md (das:GetYaoChiAgent, das:GetDasAgentSSE, etc.) are proportional to the diagnostic capability. The documentation correctly warns not to place AK/SK in the conversation or script.

Persistence & Privilege

always:false and user-invocable:true (default) — appropriate. The only persistent side-effect is installing the aliyun DAS plugin into the user's aliyun CLI environment if not already present (the script attempts auto-install). That is within scope for a CLI-based tool but users should be aware it modifies the local CLI installation.

Assessment

This skill is coherent with its stated purpose, but review and follow these precautions before running it: - Inspect the included script (scripts/call_yaochi_agent.sh) yourself (you already have it). It only calls the aliyun CLI and parses streaming responses with jq. - Do NOT paste AccessKey/Secret into chat. Configure credentials via `aliyun configure` or environment/profile outside the agent session as the documentation instructs. - Use least-privilege RAM credentials. Start with the read-only DAS policies listed in references/ram-policies.md, and only widen permissions if you understand the actions required. - Be aware the script may auto-install the aliyun DAS plugin (or you can install it manually). Verify you trust the aliyun CLI installation source (the docs point to official aliyuncli.alicdn.com URLs). - Note the minor doc vs script mismatch: examples use --source "polardbx-console" but the script uses SOURCE="polarx"; this is likely harmless but you may want to align the source string if you have strict auditing requirements. - The skill always targets the DAS production endpoint (das.cn-shanghai.aliyuncs.com) per the docs — confirm this is acceptable for your environment/policy. - If you need to limit blast radius, run the script using a profile or credentials scoped to a test account or read-only permissions first. If you want higher assurance, run the script in an isolated environment (VM/container) and verify network calls (e.g., via logs) before using it with production credentials.

PolarDB-X Distributed Database AI Assistant

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

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

Installation

Pre-check: Aliyun CLI >= 3.3.1 required Run aliyun version to verify >= 3.3.1. If not installed or version too low, see references/cli-installation-guide.md for installation instructions. Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

# Install aliyun CLI
curl -fsSL https://aliyuncli.alicdn.com/install.sh | bash
aliyun version  # Verify >= 3.3.1

# 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

Environment Variables

No additional environment variables are required. This skill relies entirely on the aliyun CLI's existing credential configuration.

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

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:

# Recommended: OAuth mode
aliyun configure --mode OAuth

# Alternative: AK mode (configure outside of agent session)
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 Policy

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

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

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 GetYaoChiAgent (wrapped by call_yaochi_agent.sh).
• If the script fails, check permissions via ram-permission-diagnose skill, DO NOT fallback to other product APIs.

# 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"

# 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"

# 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"

# SQL Optimization
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"

# 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"

# Elastic Scaling
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show scale-out status of instance 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"

# Connection & Session
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "How to troubleshoot high connection count on instance pxc-xxx"

# Backup & Restore
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show backup status of instance pxc-xxx"

# Security Audit
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Check security configuration of instance pxc-xxx"

# High Availability & DR
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show HA configuration of instance pxc-xxx"

# Multi-turn Conversation (use session ID returned from previous call)
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 instances" --profile myprofile

# Read from stdin
echo "List instances" | bash $SKILL_DIR/scripts/call_yaochi_agent.sh -

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

Success Verification

See references/verification-method.md for detailed verification steps.

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

Command Tables

See references/related-apis.md for the full list of APIs and CLI commands.

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.

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