alibabacloud-polardbx-ai-assistant

PolarDB-X 分散データベース AI アシスタント

このスキルは、aliyun CLI の DAS プラグインを介して DAS（Database Autonomy Service）の get-yao-chi-agent API を利用し、Alibaba Cloud PolarDB-X 分散データベース向けのインテリジェントな O&M 機能を提供します。

アーキテクチャ：Aliyun CLI -> DAS Plugin (Signature V3) -> get-yao-chi-agent API -> PolarDB-X インテリジェント診断

対応機能

機能	説明
インスタンス情報	インスタンスの詳細、クラスター構成、バージョン情報
トポロジー検査	CN/DN ノードの分布、シャードトポロジー、データノードのステータス
ストレージ情報	ディスク使用量、ストレージ容量、容量の増加傾向
SQL 最適化	スロークエリ分析、分散実行計画の解釈、インデックスの提案、クロスシャードクエリの最適化
クラスターのパフォーマンス監視	QPS/TPS/接続数/スループットなどの主要メトリクス分析
接続とセッションの分析	接続数の監視、セッションのトラブルシューティング、コネクションプールの最適化
セキュリティ監査	ホワイトリスト、SSL、セキュリティポリシーの監査
バックアップステータスの確認	バックアップの完全性、保持ポリシー、ポイントインタイムリカバリ
インスタンスのヘルスチェック	インスタンスのヘルスステータス、実行状態の確認
ログ診断	エラーログの分析、スローログのトラブルシューティング
データ分布の分析	シャードデータの偏りの検出、ホットスポットシャードの診断
弾力的スケーリングの診断	スケールアウト／スケールインのステータス、データ移行の進行状況、ノードの負荷分散
パラメーター調整	カーネルパラメーターの解釈、変更による影響の評価、構成の推奨事項
高可用性と DR	HA 構成の評価、災害復旧アーキテクチャの診断、プライマリとスタンバイのステータス
有効期限が近いインスタンスの照会	サブスクリプションインスタンスの有効期限リマインダー、更新ステータス

インストール

事前確認：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-Mode の有効化 — エージェントスキルの実行には AI-mode が必要です。 CLI コマンドを実行する前に、次のコマンドを実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-polardbx-ai-assistant"

[必須] すべての終了時に AI-Mode を無効化 — いかなる理由であっても、最終応答を返す前に必ず AI-mode を無効にしてください。ワークフローの成功、ワークフローの失敗、エラー／例外、ユーザーによるキャンセル、セッションの終了、またはそれ以降 CLI コマンドを実行しないその他の状況など、すべての終了経路に適用されます。 AI-mode はエージェントスキルを呼び出す場合にのみ使用し、スキルの実行終了後も有効な状態にしておいてはなりません。

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

環境変数

追加の環境変数は必要ありません。このスキルは、aliyun CLI に既存の認証情報設定のみを使用します。

認証

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• 絶対に AK/SK の値を読み取ったり、エコーしたり、出力したりしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止です）。
• 絶対に会話中またはコマンドラインで、ユーザーに AK/SK を直接入力するよう求めないでください。
• 絶対に aliyun configure set をリテラルの認証情報とともに使用しないでください。
• 認証情報の状態確認には、必ず aliyun configure list のみを使用してください。

aliyun configure list

出力を確認し、有効なプロファイル（AK、STS、または OAuth ID）があることを確認してください。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud コンソールから認証情報を取得します。
2. このセッション外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）。
3. aliyun configure list に有効なプロファイルが表示されたら、戻って再実行します。

認証情報は aliyun CLI の設定を通じて管理されます。AK/SK の追加設定は不要です。

# 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 ポリシー

必要な権限の全リストについては、references/ram-policies.md を参照してください。

**[MUST] 権限エラーへの対応：**実行中のいずれかの時点で、コマンドまたは API 呼び出しが権限エラーにより失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL で必要な権限の全リストを確認します。
2. ram-permission-diagnose スキルを使用して、必要な権限をユーザーが申請できるよう案内します。
3. 必要な権限が付与されたことをユーザーが確認するまで、一時停止して待ちます。

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズできるすべてのパラメーター（RegionId、インスタンス名、CIDR ブロック、 パスワード、ドメイン名、リソース仕様など）を、必ずユーザーに確認してください。 明示的な承認なしに、値を仮定したりデフォルト値を使用したりしないでください。

パラメーター	必須／任意	説明	デフォルト値
query	必須	自然言語によるクエリ内容（リージョン、インスタンス情報などを含む）	-
--session-id	任意	複数ターンの会話コンテキストに使用するセッション ID	-
--profile	任意	aliyun CLI のプロファイル名	default

コアワークフロー

すべてのインテリジェントな O&M 操作は、ストリーミングレスポンス解析に対応した aliyun das get-yao-chi-agent（DAS プラグインのケバブケース形式のコマンドで、Signature V3 に対応）をラップする scripts/call_yaochi_agent.sh を通じて必ず呼び出してください。

⚠️ 重大な制限：

• 診断、トポロジー、セキュリティ監査に、aliyun polardbx または aliyun rds の CLI コマンドを直接使用しないでください。
• DescribeDBInstances などの API を直接使用して、インスタンスの詳細を照会しようとしないでください。
• DAS プラグインコマンド aliyun das get-yao-chi-agent（call_yaochi_agent.sh 経由）のみを使用してください。
• スクリプトが失敗した場合は、ram-permission-diagnose スキルを使用して権限を確認し、他の製品 API へのフォールバックは行わないでください。

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

一般的なクエリ例

シナリオ	クエリ例
クラスター管理	インスタンス pxc-xxx のノード一覧を表示してください
トポロジー	インスタンス pxc-xxx には CN ノードと DN ノードがそれぞれいくつありますか
パフォーマンス診断	インスタンス pxc-xxx の CPU 使用率が高い場合のトラブルシューティング方法を教えてください
スロークエリ分析	インスタンス pxc-xxx の過去 1 時間のスロークエリを表示してください
SQL 最適化	インスタンス pxc-xxx でこの SELECT 文の実行が遅いのはなぜですか
データ分散	インスタンス pxc-xxx のシャードにデータの偏りはありますか
弾力的なスケーリング	インスタンス pxc-xxx のスケールアウトの進行状況を教えてください
パラメーター調整	インスタンス pxc-xxx のコネクションプールパラメーターを最適化する方法を教えてください
バックアップと復元	インスタンス pxc-xxx の最新のバックアップはいつですか
ストレージの最適化	インスタンス pxc-xxx のストレージが急速に増加している場合、どうすればよいですか
接続のトラブルシューティング	インスタンス pxc-xxx の接続数が上限に達しています
セキュリティ監査	インスタンス pxc-xxx のセキュリティ設定を確認してください
高可用性	インスタンス pxc-xxx の DR アーキテクチャは妥当ですか
有効期限のリマインダー	有効期限が近づいている PolarDB-X インスタンスを教えてください

成功の確認

詳細な確認手順については、references/verification-method.md を参照してください。

クリーンアップ

このスキルはクエリと診断機能のみに特化しています。リソースは作成しないため、クリーンアップは不要です。

以下の操作は、このスキルの対象外です。

• PolarDB-X インスタンスの作成／削除
• インスタンスの仕様変更
• インスタンスの購入／更新

コマンド一覧

API と CLI コマンドの全一覧については、references/related-apis.md を参照してください。

ベストプラクティス

1. インスタンス ID の形式：PolarDB-X のインスタンス ID は pxc- で始まります。クエリには必ず完全なインスタンス ID を含めてください。
2. リージョンの指定：クエリの精度を高めるため、自然言語でリージョン（例：「杭州リージョン」、「北京リージョン」）を明示してください。
3. 複数ターンの会話：複雑な診断シナリオでコンテキストを維持するには、--session-id を使用してください。
4. 同時実行数の上限：アカウントごとに同時実行できるセッションは最大 2 つです。複数の呼び出しを並行して開始しないでください。
5. 分散システムの特性：問題のトラブルシューティングでは、CN（コンピュートノード）層と DN（データノード）層を区別してください。
6. スロットリングへの対処：Throttling.UserConcurrentLimit エラーが発生した場合は、前のクエリが完了するまで待ってから再試行してください。
7. 認証情報のセキュリティ：認証情報の管理には aliyun configure を使用してください。AK/SK をスクリプトにハードコードしないでください。

参考リンク

参考資料	説明
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	受け入れ基準