Skill: sdk-team/alibabacloud-polardbx-ai-assistant (version 0.0.2)

--- name: alibabacloud-polardbx-ai-assistant description: | Alibaba Cloud PolarDB-X Distributed Database AI Assistant. Use for PolarDB-X cluster management, topology inspection, performance diagnostics, SQL optimization, data distribution analysis, elastic scaling diagnostics, connection/session analysis, security audit, backup/restore, parameter tuning, and other O&M operations. Triggers: "PolarDB-X", "distributed database", "pxc-", "DN/CN nodes", "data sharding", "PolarDB-X diagnostics", "PolarDB-X performance", "PolarDB-X slow SQL", "YaoChi Agent", "PolarDB-X topology", "PolarDB-X backup", "PolarDB-X security audit", "PolarDB-X scaling" --- # 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.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](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 [REDACTED_SECRET] > ``` > **[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 # Install aliyun CLI curl -fsSL https://aliyuncli.alicdn.com/install.sh | bash 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 ``` ## 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 > > ```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](https://ram.console.aliyun.com/manage/ak) > 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 # 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](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 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 # 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](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](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](references/cli-installation-guide.md) | Aliyun CLI installation and configuration guide | | [references/related-apis.md](references/related-apis.md) | Related APIs and CLI command list | | [references/ram-policies.md](references/ram-policies.md) | RAM permission policy list | | [references/verification-method.md](references/verification-method.md) | Success verification methods | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | Acceptance criteria |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)