alibabacloud-aes-sysom-pai-diagnosis

alibabacloud-aes-sysom-pai-diagnosis

Skill Name: alibabacloud-aes-sysom-pai-diagnosis Goal: Alibaba Cloud PAI 製品（EAS / DLC）で SysOM による詳細な診断を実行し、インスタンスレベルのパフォーマンスや健全性の問題の根本原因を特定します。

---

認証情報のセキュリティ

[CRITICAL] 認証情報のセキュリティルール：

• 絶対に会話やコマンド出力に AccessKey ID / AccessKey Secret の値を出力、エコー、表示しないでください（LTAI_ACCESS_KEY_ID を一部マスキングして表示することも禁止です）
• 絶対に会話やコマンドラインで AK/SK を直接入力するようユーザーに求めないでください
• 絶対にリテラルの認証情報を指定して aliyun configure set を使用しないでください
• 認証情報のステータス確認には aliyun configure list のみを使用してください

aliyun configure list

有効なプロファイル（AK、STS、または OAuth アイデンティティ）があるか、出力を確認してください。

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

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

---

RAM ポリシー

このスキルに必要な RAM 権限の一覧は、references/ram-policies.md を参照してください。

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

1. references/ram-policies.md を読み、このスキルに必要な権限の一覧を確認します
2. ram-permission-diagnose スキルを使用して、必要な権限を申請する手順をユーザーに案内します
3. 必要な権限が付与されたことをユーザーが確認するまで待機します

---

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズできるすべてのパラメーター（例：RegionId、インスタンス ID、製品タイプ、 時間範囲など）について、必ずユーザーに確認してください。ユーザーの明示的な承認なしに、 値を推測したりデフォルト値を使用したりしないでください。

パラメーター	必須／任意	説明	デフォルト値
region	必須	PAI リソースのリージョン（例：cn-hangzhou）	なし。ユーザーによる指定が必要
instance	必須	PAI インスタンス ID（EAS サービス ID eas-m-xxx または DLC ジョブ ID dlcxxxxxxxx）	なし。ユーザーによる指定が必要
product	必須	PAI サブ製品のタイプ。EAS または DLC のいずれか	instance のプレフィックスから自動推定（eas- → EAS、dlc → DLC）。推定できない場合のみユーザーに確認
start_time	任意	診断開始時刻のタイムスタンプ（Unix 秒）	0（リアルタイム）
end_time	任意	診断終了時刻のタイムスタンプ（Unix 秒）	0
enable_diagnosis	任意	リアルタイム診断を強制する（最優先）	false
uid	任意	リソースを所有するアカウント ID	None
ocd_description	任意	ユーザーの問題の説明（英語）。単語はアンダースコア（_）でつなぎます。中国語の文字とスペースは使用できません。例：GPU_OOM_instance_restart	None

製品の自動推定ルール

product フィールドは params JSON に必ず含めてください。値は次のように決定します。

1. ユーザーが product（EAS または DLC）を明示的に指定した場合は、その値を使用します
2. 指定がない場合は、instance のプレフィックスから推定します。
   • eas- → EAS
   • dlc（ハイフンなし。例：dlcxxxxxxxx）→ DLC
3. 推定できない場合、または推定が曖昧な場合は、EAS と DLC のどちらを使用するか、必ずユーザーに確認してください

---

コアワークフロー

ワークフローは 8 つのステップからなる 2 つのフェーズで構成されます。すべての aliyun CLI のビジネスコマンド（SysOM、EAS、DLC API 呼び出し）には、必ず --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis を含めてください。システムコマンド（version、configure、plugin）では --user-agent を使用しません。

フェーズ 1：環境のセットアップ（ステップ 0～3）

ステップ 0 — AI-Mode を有効化してプラグインを更新

CLI コマンドを実行する前に、AI-Mode を有効化し、User-Agent を設定して、プラグインを更新します。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis"
aliyun plugin update

⚠️ 上記の 3 つのコマンドは、すべての CLI 操作に先立って実行する必要があります。一度だけ実行すれば十分です。

ステップ 1 — CLI バージョンの確認

aliyun version

バージョンが 3.3.1 以上であることを確認します。満たしていない場合は、references/cli-installation-guide.md を参照してインストールしてください。

ステップ 2 — プラグインの自動インストールを有効化

aliyun configure set --auto-plugin-install true

ステップ 3 — 認証情報の確認

aliyun configure list

有効な認証情報がない場合は、停止して、セッション外で認証情報を設定するようユーザーに案内してください。

---

フェーズ 2：診断の実行（ステップ 4～8）

詳細なワークフローについては、references/diagnose-workflow.md を参照してください。

ステップ 4 — 曖昧な問題の明確化（逆転ゲート）

region、instance、および異常が発生した時刻を必ず確認してください。ユーザーから情報が提供されていない場合は、明示的に質問してください。product は instance のプレフィックス（eas- → EAS、dlc → DLC）から自動的に推定します。推定できない場合に限り、ユーザーに確認してください。任意の時間範囲も抽出してください。

⚠️ 時刻の推定ルール：ユーザーの説明に時間に関する言及（例：「今朝」、「昨日の午後」、「午後 3 時ごろ」、「昨夜」）が少しでも含まれている場合は、具体的な時間範囲を積極的に尋ね、過去の診断モードを推奨してください。問題が明らかに過去に発生した場合、リアルタイム診断を暗黙に既定値として使用してはいけません。

ステップ 5 — SysOM のロール初期化

aliyun sysom initial-sysom --check-only false --source aes-skills --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

ステップ 6 — リソースの検証

診断を呼び出す前に、推定した product に基づいてリソースを必ず検証してください。

6A. EAS — サービスの存在を確認

aliyun eas list-services \
  --region <region> \
  --filter <eas_service_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

返された Services 配列から、一致する ServiceId を持つエントリが存在することを確認してください。一致するものがない場合は、サービス ID が無効であることをユーザーに伝え、パイプラインを停止してください。

6B. DLC — リソースタイプが Lingjun であることを確認

aliyun pai-dlc get-job \
  --region <region> \
  --job-id <dlc_job_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

応答の ResourceType フィールドを確認してください。

• Lingjun → ステップ 7 に進む
• その他の値 → 停止して、ユーザーに次のように伝えてください：「SysOM 診断が現在サポートしているのは、Lingjun リソース上で実行される DLC ジョブのみです。このジョブは <ResourceType> を使用しており、まだサポートされていません。」

⚠️ params JSON の instance フィールドには、元のインスタンス ID（eas-m-xxx または dlcxxxxxxxx）をそのまま使用します。このステップは検証のみを行います。

ステップ 7 — 診断を呼び出して結果をポーリング

診断モードの決定ルール

if enable_diagnosis == true:
    mode = real-time diagnosis    # enable_diagnosis has highest priority
elif start_time != 0:
    mode = historical diagnosis   # time range specified, retrospective analysis
else:
    mode = real-time diagnosis    # default

• リアルタイム：start_time=0、end_time=0
• 過去：start_time=<unix_ts>、end_time=<unix_ts>
• リアルタイムを強制：enable_diagnosis=true の場合、値が指定されていても start_time を 0 に設定します

params JSON を作成

SDK と一貫性のある snake_case のキーを使用します。必須の基本フィールド（すべて含める必要があります）：

{
  "instance": "<eas_service_id_or_dlc_job_id>",
  "region": "<region>",
  "product": "<EAS_or_DLC>",
  "start_time": 0,
  "end_time": 0,
  "type": "ocd",
  "ai_roadmap": true,
  "enable_sysom_link": false,
  "ocd_description": "<user_problem_description_in_english_with_underscores>"
}

⚠️ 混同防止の警告：params JSON 内の "type": "ocd" と "product": "<EAS|DLC>" は、どちらも必須フィールドです。いずれも省略しないでください！

• --service-name ocd（CLI 引数）→ 呼び出す診断サービスのエンドポイントを CLI に指定します
• "type": "ocd"（params JSON フィールド）→ 内部で実行する診断タイプを診断エンジンに指定します
• "product": "EAS" または "product": "DLC"（params JSON フィールド）→ 対象となる PAI サブ製品を診断エンジンに指定します

3 つとも必須です。いずれも省略しないでください。

⚠️ instance フィールドには、元のインスタンス ID（EAS の場合は eas-m-xxx、DLC の場合は dlcxxxxxxxx）をそのまま使用します。 ServiceName やその他の識別子に変換しないでください。

条件付きフィールド（空でない場合のみ追加）：

• uid：リソースを所有するアカウント ID（整数）
• ocd_description：ユーザーの問題の説明（文字列）。書式上の制約：英語で記述し、中国語の文字やスペースを含めないでください。単語はアンダースコア（_）でつないでください。例：high_latency_first_token、GPU_OOM_killed

診断の実行

aliyun sysom invoke-diagnosis \
  --service-name ocd \
  --channel ecs \
  --params '{"instance":"<eas_service_id_or_dlc_job_id>","region":"<region>","product":"<EAS|DLC>","start_time":<start_time>,"end_time":<end_time>,"type":"ocd","ai_roadmap":true,"enable_sysom_link":false}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

レスポンスから task_id を抽出します。

⚠️ [CRITICAL] Sysom.TaskInProgress エラーの処理： invoke-diagnosis が Sysom.TaskInProgress エラーを返した場合、診断タスクがすでに実行中であることを意味します。必ず次の操作を行ってください。

1. 文字列マッチングを使用して、エラーメッセージから既存の task_id を抽出します（パターン：ocd(<task_id>)、またはメッセージ本文内の同様の識別子）。
2. 抽出した task_id を使って、直ちにポーリングのフローに進みます。
3. TaskInProgress を致命的な失敗として扱ったり、ワークフローを中止したりしてはいけません。

結果のポーリング（間隔：10s、最大：60回）

aliyun sysom get-diagnosis-result --task-id <task_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis

レスポンスの status フィールドを確認します。

• Ready ／ Running → 10s 間隔で必ずポーリングを続けます。
• Success → 診断完了。ステップ 8 に進みます。
• Fail → 診断失敗。ユーザーに伝えます。

⛔ [CRITICAL] 必須のポーリングルール（必ず遵守してください。違反すると誤った結果が生成されます）：

1. Running ステータスは正常です — 診断エンジンが処理中であることを示すだけです。必ず10秒ごとにポーリングを続けてください。Running はエラーではなく、処理を早期終了させる理由にしてはいけません。
2. ポーリングを早期に中止してはいけません — Success、Fail、または60回の上限に達する前にポーリングを止めてはいけません。Running のレスポンスが数回返っただけで「諦めて」はいけません。
3. 手動分析に切り替えてはいけません — ポーリング中またはタイムアウト時に、ListServices の出力、インスタンスのメタデータ、その他のデータソースを分析して、問題を手動で診断してはいけません。根本原因に関する有効な情報源は、診断レポートのみです。
4. 診断結果を捏造してはいけません — タスクのステータスが Success に達していない場合、summary.overall_status、summary.root_cause、または summary.suggestions の値を出力してはいけません。これらのフィールドは、完了した診断結果からのみ取得できます。
5. タイムアウトの処理 — 60回のポーリング後も未完了の場合は、次のテンプレートのみを出力して終了します。

   ⏳ SysOM diagnosis task timed out
   - Task ID: <task_id>
   - Current status: <status>
   - Suggestion: Please continue waiting for the diagnosis to complete.
   

   タイムアウト時の出力に別の提案、手動分析、または捏造した結論を加えることは禁止されています。

ステップ 8 — 結果の解析と出力

返された JSON を解析し、summary.overall_status、summary.root_cause、summary.suggestions、issues[] およびその他の重要な情報をユーザーに提示します。

---

成功の確認

各フェーズの確認方法については、references/verification-method.md を参照してください。

---

クリーンアップ

このスキルの診断操作は読み取り専用であり、PAI サービス／ジョブの状態を変更しないため、クリーンアップは不要です。

PAI EAS ／ DLC は完全マネージドサービスであり、インストールまたはアンインストールするエージェントはありません。

すべての CLI 操作が完了したら、必ず AI-Mode を無効にしてください。

aliyun configure ai-mode disable

---

コマンド一覧

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

---

ベストプラクティス

1. 製品は自動的に推測し、ユーザーには確認しません：product は instance のプレフィックス（eas- → EAS、dlc → DLC）から判定します。プレフィックスを特定できない場合にのみ、ユーザーに確認します。
2. リソースの検証は必須です：EAS では存在を確認するために ListServices を呼び出します。DLC では存在を確認し、さらに ResourceType が Lingjun であることを確認するために GetJob を呼び出します。
3. インスタンス ID はパラメーターでそのまま使用します：EAS（eas-m-xxx）と DLC（dlcxxxxxxxx）のインスタンス ID は、instance フィールドにそのまま渡します。ServiceName に変換しないでください。
4. デフォルトではリアルタイム診断モードを使用します：ユーザーが時間範囲を明示的に指定しない限り、デフォルトでリアルタイム診断を実行します。
5. 認証情報のセキュリティ：AK/SK の値を会話に出力したり、そのまま表示したりしないでください。
6. すべての業務用 CLI コマンドには --user-agent AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-pai-diagnosis を含める必要があります（version、configure、plugin などのシステムコマンドでは --user-agent を使用しません）。
7. 修復の提案には高リスクな操作が含まれる場合があります：Human-in-the-loop プロトコルに従い、ユーザーの確認を待ってください。
8. 登録やエージェントのインストールは不要です：PAI EAS と DLC はマネージドサービスです。SysOM はインスタンスレベルのエージェントを介さず、プラットフォーム側からアクセスします。

---

サポート対象外のシナリオ

• PAI 以外の製品（ECS インスタンスには alibabacloud-aes-sysom-os-diagnosis を使用してください）
• EAS と DLC 以外の PAI 製品（例：DSW、MaxCompute）。現在のスキルの対象範囲は EAS / DLC のみです。
• 純粋な設定の問題（例：モデルバージョンの不一致、EAS のルーティング設定など、OS レベルの診断が不要な問題）

---

エラー処理

エラーシナリオ	CLI の応答	エージェントの対応
無効な EAS ServiceId	ListServices が空を返す	該当リージョンにサービス ID が存在しないことをユーザーに伝え、パイプラインを停止します
無効な DLC JobId	GetJob が見つからないことを返す	DLC ジョブ ID が存在しないことをユーザーに伝え、パイプラインを停止します
DLC の ResourceType が Lingjun ではない	GetJob が Lingjun 以外のタイプを返す	SysOM がサポートするのは Lingjun リソースのみであることをユーザーに伝え、パイプラインを停止します
製品が不明／プレフィックスが曖昧	instance から推測できない	EAS または DLC を選択するよう、ユーザーにはっきり確認します
ロールの認可に失敗	initial-sysom がエラーを返す	SysOM サービスの有効化状態を確認するようユーザーに促します
診断の実行に失敗	invoke-diagnosis がエラーを返す	認証情報、権限、product フィールドが正しいか確認します
診断がタイムアウト	get-diagnosis-result のポーリングがタイムアウト	タイムアウト用テンプレートを出力し、後で再試行するようユーザーに提案します
権限不足	API が Forbidden を返す	references/ram-policies.md を読み、権限を申請するようユーザーに案内します

---

参考リンク

参考資料	説明
references/cli-installation-guide.md	Aliyun CLI のインストールおよび設定ガイド
references/ram-policies.md	RAM 権限ポリシー一覧
references/related-commands.md	CLI コマンドの全一覧
references/verification-method.md	各フェーズの成功確認方法
references/diagnose-workflow.md	診断ワークフローの詳細（手順 4～8）
references/acceptance-criteria.md	テストの受け入れ基準