Alibabacloud Polardbx Ai Assistant

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

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

```

# 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

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.

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.

# 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

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

Acceptance Criteria: alibabacloud-polardbx-ai-assistant

Scenario: PolarDB-X Distributed Database AI Assistant Purpose: Skill testing acceptance criteria

---

Correct CLI Command Patterns

1. Product - DAS (Database Autonomy Service)

CORRECT

# Plugin kebab-case command (Signature V3, recommended)
aliyun das get-yao-chi-agent --query "List instances" --source "polardbx-console" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Error: product name wrong case
aliyun DAS get-yao-chi-agent --query "List instances"

# Error: missing --user-agent flag
aliyun das get-yao-chi-agent --query "List instances" --source "polardbx-console" --endpoint das.cn-shanghai.aliyuncs.com

2. Command - get-yao-chi-agent

CORRECT

aliyun das get-yao-chi-agent --query "Hello" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Error: API name typo
aliyun das get-yao-chi --query "Hello"

# Error: using non-existent API
aliyun das yaochi-agent --query "Hello"

3. Parameters

get-yao-chi-agent Parameters

CORRECT

# Required parameter --query
aliyun das get-yao-chi-agent --query "List PolarDB-X instances in Hangzhou region" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills

# Optional parameter --source
aliyun das get-yao-chi-agent --query "List instances" --source "polardbx-console" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills

# Optional parameter --session-id (multi-turn)
aliyun das get-yao-chi-agent --query "Continue analysis" --session-id "sess-xxx" --source "polardbx-console" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Error: missing required parameter --query
aliyun das get-yao-chi-agent --source "polardbx-console"

# Error: using non-existent parameter
aliyun das get-yao-chi-agent --query "List instances" --region-id "cn-hangzhou"

4. Endpoint

CORRECT

# get-yao-chi-agent always uses cn-shanghai endpoint
aliyun das get-yao-chi-agent --query "List instances" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Error: wrong endpoint
aliyun das get-yao-chi-agent --query "List instances" --endpoint das.cn-beijing.aliyuncs.com

# Error: missing endpoint, may use wrong default
aliyun das get-yao-chi-agent --query "List instances"

5. --user-agent Flag - Required

CORRECT

aliyun das get-yao-chi-agent --query "List instances" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Error: missing --user-agent flag
aliyun das get-yao-chi-agent --query "List instances" --endpoint das.cn-shanghai.aliyuncs.com

6. Timeout Settings

CORRECT

# SSE streaming API needs longer read timeout (180s)
aliyun das get-yao-chi-agent --query "List instances" --endpoint das.cn-shanghai.aliyuncs.com --read-timeout 180 --connect-timeout 30 --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Error: read timeout too short, streaming API may timeout
aliyun das get-yao-chi-agent --query "List instances" --endpoint das.cn-shanghai.aliyuncs.com --read-timeout 10 --user-agent AlibabaCloud-Agent-Skills

---

Correct Bash Script Patterns

1. Script Invocation

CORRECT

bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List PolarDB-X instances in Hangzhou region"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Analyze performance of instance pxc-xxx" --session-id "sess-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List instances" --profile myprofile
echo "List instances" | bash $SKILL_DIR/scripts/call_yaochi_agent.sh -

INCORRECT

# Error: using Python script (does not exist)
uv run $SKILL_DIR/scripts/call_yaochi_agent.py "List instances"

# Error: using Python interpreter on bash script
python $SKILL_DIR/scripts/call_yaochi_agent.sh "List instances"

# Error: using old parameter format
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List instances" --role-arn acs:ram::xxx:role/xxx

2. SSE Response Parsing

CORRECT - script auto-parses SSE response

# Input: SSE format response body
data: {"Content":"PolarDB-X instance list:","SessionId":"sess-abc123","ReasoningContent":""}
data: {"Content":"\n1. pxc-xxx (cn-hangzhou)","SessionId":"sess-abc123","ReasoningContent":""}
data: [DONE]

# Output: concatenated Content
PolarDB-X instance list:
1. pxc-xxx (cn-hangzhou)

3. Credential Management

CORRECT

# Use existing aliyun CLI configuration
aliyun configure --mode OAuth
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List instances"

# Use specific profile
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List instances" --profile myprofile

INCORRECT

# Error: hardcoding AK/SK in script
export ALIBABA_CLOUD_ACCESS_KEY_ID="LTAI5tXXXXXXXX"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="8dXXXXXXXXXXXX"

# Error: using custom credential variables
export YAOCHI_ACCESS_KEY_ID="xxx"
export YAOCHI_ACCESS_KEY_SECRET="xxx"

---

Authentication Patterns

CORRECT - use aliyun CLI configuration

# OAuth mode (recommended)
aliyun configure --mode OAuth

# AK mode
aliyun configure set --mode AK --access-key-id <AK> --access-key-secret <SK> --region cn-hangzhou

# Cross-account RamRoleArn mode
aliyun configure set --mode RamRoleArn --access-key-id <AK> --access-key-secret <SK> --ram-role-arn <ARN> --role-session-name yaochi-session --region cn-hangzhou

INCORRECT - managing credentials in script

# Error: using Python SDK for credentials
from alibabacloud_das20200116.client import Client as DAS20200116Client

# Error: parsing credentials from .env file
# Error: parsing credentials from ~/.alibabacloud/credentials

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Policies

Required Permissions

Using PolarDB-X AI Assistant (YaoChi Agent) requires the following RAM permissions:

Core Permission - DAS GetYaoChiAgent

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "das:GetYaoChiAgent",
        "das:GetDasAgentSSE"
      ],
      "Resource": "*"
    }
  ]
}

Recommended - DAS Read-Only

For full diagnostic capabilities, grant the following specific DAS read-only permissions:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "das:GetYaoChiAgent",
        "das:GetDasAgentSSE",
        "das:DescribeInstanceDasPro",
        "das:GetInstanceInspections",
        "das:GetQueryOptimizeExecErrorStats"
      ],
      "Resource": "*"
    }
  ]
}

Cross-Account Access - STS AssumeRole

For cross-account access, configure RAM role trust policy on the target account:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Principal": {
        "RAM": [
          "acs:ram::<caller-account-id>:root"
        ]
      }
    }
  ]
}

Recommended System Policies

Permission Mapping

Related APIs

DAS (Database Autonomy Service) - Core API

GetYaoChiAgent API Parameters

GetDasAgentSSE API Parameters

SSE Response Format

GetYaoChiAgent returns SSE (Server-Sent Events) streaming response:

data: {"Content":"Response text chunk 1","SessionId":"sess-xxx","ReasoningContent":""}
data: {"Content":"Response text chunk 2","SessionId":"sess-xxx","ReasoningContent":""}
...
data: [DONE]

Response Fields

API Endpoint

Note: GetYaoChiAgent API uses das.cn-shanghai.aliyuncs.com endpoint uniformly, regardless of the PolarDB-X instance's region.

Verification Method

Steps to Verify Skill Execution

Step 1: Verify aliyun CLI installation and configuration

# Check CLI version
aliyun version
# Expected: 3.3.3 or higher

# Check auth configuration
aliyun configure get
# Expected: shows current profile configuration

# Test basic connectivity
aliyun das describe-instance-das-pro --instanceId "pxc-test" --endpoint das.cn-shanghai.aliyuncs.com --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ai-assistant 2>&1
# Expected: JSON response (API error for non-existent instance is OK, connection error is NOT)

Step 2: Verify jq installation

echo '{"Content":"test"}' | jq -r '.Content'
# Expected: test

Step 3: Verify call_yaochi_agent.sh script

# Verify script is runnable
bash $SKILL_DIR/scripts/call_yaochi_agent.sh --help
# Expected: shows help information

# Verify no-argument error prompt
bash $SKILL_DIR/scripts/call_yaochi_agent.sh
# Expected: shows usage prompt and exits

Step 4: Verify actual invocation (requires valid credentials)

# Simple query test
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Hello"
# Expected: YaoChi Agent response content

# With debug mode
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Hello" --debug
# Expected: response content + debug info on stderr

Step 5: Verify multi-turn conversation

# First query - note the session ID in stderr output
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List PolarDB-X instances in Hangzhou region"
# Expected: instance list, stderr shows [SessionID] sess-xxx

# Second query - use session ID from previous call
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Continue analyzing the first instance" --session-id "sess-xxx"
# Expected: contextual analysis based on previous conversation

Common Errors and Solutions