alibabacloud-polardb-ai-assistant

PolarDB データベース AI アシスタント

この Skill は、Alibaba Cloud PolarDB MySQL/PostgreSQL データベースのインテリジェントな運用保守に特化しています。get-yao-chi-agent API と aliyun CLI DAS プラグインを通じて、Yaochi Agent v2 バックエンドを呼び出します。

アーキテクチャ: Codex Skill -> scripts/call_yaochi_agent.sh -> Aliyun CLI -> DAS Plugin (Signature V3) -> get-yao-chi-agent API -> Yaochi Agent v2 -> PolarDB Skill/MCP/DAS/RAG capabilities

適用範囲: PolarDB のみです。ユーザーの依頼が PolarDB との統合または比較について明示的に言及している場合を除き、PolarDB 以外の製品の運用保守にはこの Skill を使用しないでください。

対応機能

機能	説明
インスタンスの照会とフィルタリング	ID、エンジン、バージョン、ステータス、課金タイプ、ゾーン、アーキテクチャ、タグ、名前、作成期間、有効期限で PolarDB クラスターを自然言語でフィルタリングします
インスタンスのステータス確認	実行時ステータス、ノードの健全性、バージョン、ロック／移行状態、エンドポイントの状態、課金タイプ、有効期限を確認します
クラスターリソースの確認	CPU、メモリ、接続数、IOPS、ストレージ、Serverless PCU の動作、容量の逼迫状況、傾向を分析します
接続とセッションの確認	接続使用量、アクティブセッション、アイドル状態のトランザクションのリスク、接続数の傾向、コネクションプールに関する提案を確認します
プロキシパフォーマンスの確認	プロキシの CPU、QPS、接続の安定性、応答時間、エンドポイント／ルーティング情報、読み書き分離の兆候を確認します
バックアップの確認	バックアップポリシー、バックアップ記録、バックアップタスクのステータス、ログバックアップ／PITR の機能、バックアップの成功／失敗リスクを確認します
セキュリティの確認	ホワイトリスト、パブリック公開のリスク、SSL/TDE、アカウントのセキュリティ状況、SQL 監査の設定を確認します
高可用性と災害復旧	マルチゾーン／HA の状況、ホットスタンバイの状態、GDN／移行の兆候、HA 切り替え記録、災害復旧への備えを確認します
ログ診断	エラーログとスローログの量、パターン分析、運用上の推奨事項を確認します
Serverless の確認	PCU の最小／最大設定、スケーリング動作、自動一時停止の状況、ワークロードとリソースの適合性を確認します
パラメーターの説明	PolarDB MySQL/PostgreSQL のパラメーターの意味、デフォルト値、リスク、ベストプラクティス、再起動／有効範囲に関する注意事項を説明します
パラメーター変更の評価	パラメーター変更ログの説明、複数パラメーターが及ぼす影響の評価、変更リスクに関する提案を行います
IMCI パラメーターの説明	PolarDB MySQL IMCI のカラムナーインデックスパラメーターの説明と使用方法を案内します
カーネルとプロキシのバージョン診断	DB カーネル／プロキシのバージョン差分分析、リリースノートに基づくリスク評価、重大度の高い修正済みバグの確認、アップグレードの提案を行います
HA 切り替えとイベント分析	HA 切り替えの根本原因、関連するパフォーマンス／ログの証拠、イベントの影響、今後の緩和策を分析します
ストレージ診断	ストレージの構成、増加傾向、異常な使用状況、コールドデータ／アーカイブの兆候、クリーンアップや容量に関する提案を確認します
SQL パフォーマンス診断	バックエンドと権限が対応している場合、スロークエリ、実行計画、ロック／ブロッキング、インデックス最適化を診断します

バックエンドの実行モデル

ローカルの Skill は PolarDB MCP ツールを直接呼び出しません。自然言語のクエリを Yaochi Agent v2 に送信します。バックエンドは次の処理を担当します。

1. 運用保守、確認、診断、パラメーター、イベントに関するシナリオでは、最初に PolarDB のシナリオ別 Skill と照合します。
2. 実際のクラスター、メトリクス、ログ、バックアップ、セキュリティ、またはデータプレーンの証拠を取得するため、PolarDB MCP/OpenAPI ツールを呼び出します。
3. 該当する場合は、パフォーマンス、スロークエリ、ロック、インデックス、自動インクリメント ID の問題に DAS インテリジェント診断を使用します。
4. 構造化ツールで質問に回答できない場合に限り、PolarDB ドキュメント／RAG にフォールバックします。

ユーザーへの回答では、バックエンドの出力を信頼できる情報源として扱ってください。レスポンスに含まれていないクラスターのステータス、メトリクス、ログ、リスクレベル、ドキュメントリンクを捏造しないでください。

可観測性

[MUST] User-Agent テンプレート — この Skill が実行する Alibaba Cloud CLI、SDK、または Terraform のすべての呼び出しでは、次を使用する必要があります。 AlibabaCloud-Agent-Skills/alibabacloud-polardb-ai-assistant/{session-id}

[MUST] セッション ID のルール — 各 Skill 実行セッションの開始時に、可観測性用のセッション ID を 1 つ生成し、そのセッション内のすべての Alibaba Cloud CLI、SDK、Terraform の呼び出しで同じ値を再利用してください。リトライや複数ステップのワークフローで再生成しないでください。セッション ID は、32 文字の小文字の 16 進数文字列である必要があります。

export ALIBABACLOUD_AGENT_SKILL_SESSION_ID="${ALIBABACLOUD_AGENT_SKILL_SESSION_ID:-$(openssl rand -hex 16)}"

[MUST] CLI User-Agent — すべての aliyun CLI コマンドの呼び出しには、次を含める必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-polardb-ai-assistant/${ALIBABACLOUD_AGENT_SKILL_SESSION_ID}

インストール

事前確認：Aliyun CLI >= 3.3.3 が必要です aliyun version を実行して、バージョンが 3.3.3 以上であることを確認してください。未インストールの場合、またはバージョンが古い場合は、 インストーラーをダウンロードして内容を確認してからローカルで実行して更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。 次に、プラグインの自動インストールを有効にするため、[MUST] aliyun configure set --auto-plugin-install true を実行してください。 次に、ローカルマシンに既存のプラグインがある場合は常に最新の状態になるよう、[MUST] aliyun plugin update を実行してください。

# Install aliyun CLI after reviewing the downloaded installer
curl -fsSL https://aliyuncli.alicdn.com/setup.sh -o /tmp/aliyun-cli-setup.sh
less /tmp/aliyun-cli-setup.sh
bash /tmp/aliyun-cli-setup.sh
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

パラメーターの確認

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

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

認証

認証情報には既存の aliyun CLI 設定を使用します。追加の AK/SK 設定は不要です。

# Recommended: OAuth mode
aliyun configure --mode OAuth

# Or: AK mode
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 を参照してください。

コアワークフロー

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

# Cluster management
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "List PolarDB clusters in Hangzhou region"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show detailed configuration of cluster pc-xxx"

# Performance diagnostics
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Analyze cluster pc-xxx performance in the last hour"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show slow SQL of cluster pc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Diagnose lock blocking and index risks for PolarDB PostgreSQL cluster pc-xxx"

# Parameter tuning
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "How to tune innodb_buffer_pool_size for cluster pc-xxx"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Explain loose_polar_log_bin parameter"
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Compare parameters between pc-xxx and pc-yyy"

# Primary-standby switchover diagnostics
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Analyze recent primary-standby switchover cause for cluster pc-xxx"

# Connection and session
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "How to troubleshoot high connection count in cluster pc-xxx"

# Backup recovery
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Show backup status of cluster pc-xxx"

# Inspection
bash $SKILL_DIR/scripts/call_yaochi_agent.sh "Generate a health inspection report for cluster pc-xxx"

# Multi-turn conversation (use session ID from previous response)
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 clusters" --profile myprofile

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

エラー処理

call_yaochi_agent.sh が失敗した場合、Error: SDKError のみとして要約しないでください。 標準エラー出力に含まれる構造化エラーブロックをユーザーに提示してください。特に次の項目に注意してください。

[YaoChi Agent Error]
ErrorCode: <aliyun error code>
ErrorMessage: <full error description>
AuthAction: <required RAM action, when returned>
RequestId: <request id, when returned>
Suggestion: <specific fix>
Reference: <local skill reference>
Troubleshooting: <Aliyun troubleshooting link>

Forbidden.RAM などの権限エラーの場合は、まず AuthAction を確認し、その RAM アクションまたは references/ram-policies.md に記載されたポリシーを付与するようユーザーに案内してください。認証情報、スロットリング、タイムアウト、またはプラグインのエラーの場合は、Suggestion と references/verification-method.md を使って、次に実行する具体的な対処方法を提示してください。

Throttling.UserConcurrentLimit は、アカウントが Yaochi Agent の同時リクエスト上限を超えたことを意味します。現在の本番環境での検証では、1 アカウントあたり最大 2 つの同時セッションが確認されています。リトライする前に、実行中のリクエストが完了するまでお待ちください。

回答要件

診断や調査に関する質問には、根拠に基づいて回答してください。

1. 結論と現在のリスクレベルを最初に示します。
2. メトリクスの値、ログの件数、バックアップ記録、バージョン番号、返されたステータスフィールドなど、バックエンドの応答から具体的な根拠を示します。
3. 影響が最も大きい次のアクションを優先して、最大限提示します。直ちに行うアクションと、その後の観察を区別します。
4. データが不足している場合や権限がない場合は、検証できなかった内容を説明し、構造化されたエラーまたは不足している権限に関する案内を提示します。
5. ユーザーによる対処に必要な場合を除き、内部ツール名、絶対ローカルファイルパス、非公開のシステムグループ、認証情報、生の実装詳細を開示しないでください。

高リスクのリクエストや変更を伴うリクエストの場合：

• パラメーター変更、再起動、フェイルオーバー、ホワイトリストの変更、バックアップからの復旧、設定変更には、明示的なリスク説明とユーザーの確認が必要です。
• 根拠となる情報がある場合は、パラメーター変更に再起動が必要か、すぐに反映されるかを必ず明示します。
• バックアップと復旧に関する案内では、実行前に復旧時点、データの整合性、ビジネスへの影響を確認するよう、必ずユーザーに注意を促します。

質問の例

シナリオ	質問の例
クラスター管理	クラスター pc-xxx のノードとエンドポイントを一覧表示してください
インスタンス照会	北京にある PolarDB MySQL 8.0 のプリペイドクラスターを一覧表示してください
ヘルスチェック	クラスター pc-xxx のヘルスチェックレポートを作成してください
パフォーマンス診断	クラスター pc-xxx の CPU 使用率が高い原因を調査してください
スロークエリ分析	クラスター pc-xxx の過去 1 時間のスロークエリを表示してください
パラメーター調整	loose_polar_log_bin パラメーターの意味を教えてください
パラメーター変更	過去 3 日間の pc-xxx のパラメーター変更について説明してください
パラメーター比較	pc-xxx と pc-yyy のパラメーターの違いを比較してください
IMCI パラメーター	クラスター pc-xxx の IMCI 関連パラメーターを設定する方法を教えてください
HA 切り替え	クラスター pc-xxx で最近発生したプライマリとスタンバイの切り替え原因を分析してください
バックアップからの復旧	クラスター pc-xxx の最新のバックアップはいつですか
ストレージ最適化	クラスター pc-xxx のストレージ使用量が急増した場合、何をすべきですか
接続のトラブルシューティング	クラスター pc-xxx の接続数が上限に達しています
セキュリティ監査	クラスター pc-xxx のセキュリティ設定を確認してください
バージョンリスク	pc-xxx の DB カーネルとプロキシのバージョンリスクを分析してください
イベント分析	クラスター pc-xxx に対する PolarDB イベントの影響を分析してください

成功の確認

references/verification-method.md を参照してください。

クリーンアップ

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

以下の操作は、この Skill の対象範囲外です。

• PolarDB クラスターを直接作成または削除する
• インスタンスの仕様またはパラメーターを直接変更する
• ホワイトリスト、セキュリティ、バックアップ、または HA の設定を直接変更する

この Skill では、これらの操作について説明し、リスクを評価し、必要な確認を行うようユーザーを案内できます。ただし、バックエンドの応答で変更が実行されたと明示的に確認されない限り、変更が実行されたと主張してはなりません。

API とコマンドの表

references/related-apis.md を参照してください。

ベストプラクティス

1. PolarDB 専用の対象範囲：この Skill は PolarDB MySQL/PostgreSQL に使用してください。PolarDB 以外の製品の O&M に関するリクエストには使用しないでください。
2. クラスター ID の形式：PolarDB のクラスター ID は通常 pc- で始まります。利用できる場合は、クエリにクラスター ID 全体を含めてください。
3. リージョンの指定：クエリの精度を高めるため、自然言語のクエリでリージョンを明示してください（例：「杭州リージョン」「北京リージョン」）。リージョンが不明な場合は、質問するか、対応していればバックエンドにインスタンスから推測させてください。
4. 証拠を最優先：O&M、調査、診断に関する回答では、バックエンドから返されたツールの証拠に基づいてください。データがない状態で、具体的なメトリクス、バージョンのリスク、バックアップの状態を推測しないでください。
5. 複数ターンの会話：複雑な診断シナリオでは、コンテキストの継続性を保つために --session-id を使用してください。
6. 同時実行数の上限：アカウントごとの同時セッション数は最大 2 です。複数の並列呼び出しを開始しないでください。
7. リスクの高い操作：パラメーターの変更、フェイルオーバー、復旧、セキュリティの変更を行う場合は、リスクを説明し、操作を開始する前にユーザーの確認を得てください。
8. スロットリングへの対処：Throttling.UserConcurrentLimit エラーが発生した場合は、前のクエリが完了するまで待ってから再試行してください。
9. 認証情報のセキュリティ：認証情報の管理には 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	受け入れ基準