alibabacloud-smartag-pilot

SAG Pilot v1.0

SAG（Smart Access Gateway / 智能接入网关）の設定クエリおよびステータス検査スキルです。aliyun CLI のプラグインモードを使用します。

アーキテクチャ：SAG Device/APP → CCN → CEN → VPC（読み取り専用の検査で、リソースは変更しません）

事前確認

事前確認：Aliyun CLI 3.3.3 以上が必要です aliyun version を実行して、3.3.3 以上であることを確認してください。インストールされていない場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストールまたは更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。

事前確認：SAG プラグインがインストールされ、最新の状態であること

aliyun plugin install --names aliyun-cli-smartag
aliyun plugin update
aliyun configure set --auto-plugin-install true

[MUST] AI-Mode を有効にする — エージェントスキルの実行には AI-mode が必要です。 ワークフローの開始時（CLI を呼び出す前）に実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-smartag-pilot"

[MUST] すべての終了時点で AI-Mode を無効にする — どのような理由であっても最終回答を返す前に （成功、失敗、エラー、キャンセル）、必ず最初に AI-mode を無効にしてください。

aliyun configure ai-mode disable

認証

事前確認：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 Console から認証情報を取得します
2. このセッションの外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）
3. aliyun configure list で有効なプロファイルが表示されてから、戻って再実行します

RAM ポリシー

このスキルには、読み取り専用の SAG 権限が必要です。完全な JSON ポリシーについては、references/ram-policies.md を参照してください。

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

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

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（例：RegionId、SmartAGId、クエリ対象範囲、出力形式）を ユーザーに確認する必要があります。明示的な承認なしに、値を推測したりデフォルト値を使用したりしないでください。

パラメーター	必須	説明	デフォルト
RegionId	はい	対象リージョン、または全リージョンをスキャンする場合は「all regions」	cn-shanghai
SmartAGId	条件付き	SAG インスタンス ID（sag-xxxxx）。「all instances」クエリでは不要です	—
Query Scope	はい	実行するモジュール／機能	該当するすべて
Output Format	任意	会話の要約および／またはレポートファイル	両方

リージョンの確認

すべてのリージョンをクエリする場合は、必ず次のコマンドから開始してください。

aliyun smartag describe-regions \
  --endpoint smartag.cn-shanghai.aliyuncs.com \
  --read-timeout 30 \
  --connect-timeout 15

これにより、SAG がサポートするすべてのリージョンの正式な一覧（RegionId + RegionEndpoint）が返されます。後続のリージョンごとのクエリで --endpoint を構成するには、返された RegionEndpoint の値を使用してください。リージョン ID を推測したり、ハードコードしたりしないでください。

API 呼び出し方法

Aliyun CLI（プラグインモード）

SAG プラグインは、パラメーター検証と自動補完に対応したネイティブコマンドを提供します。

aliyun smartag describe-smart-access-gateways \
  --endpoint smartag.cn-shanghai.aliyuncs.com \
  --biz-region-id cn-shanghai \
  --read-timeout 30 \
  --connect-timeout 15 \
  --smart-ag-id sag-xxxxx

SAG CLI の呼び出しテンプレート：

aliyun smartag <api-name-in-kebab-case> \
  --endpoint smartag.<RegionId>.aliyuncs.com \
  --biz-region-id <RegionId> \
  --read-timeout 30 \
  --connect-timeout 15 \
  [--other-params ...]

命名規則：

• API 名：kebab-case（例：describe-smart-access-gateways、describe-sag-wan-4g）
• パラメーター：kebab-case（例：--smart-ag-id、--smart-ag-sn、--page-size）
• エンドポイントのルーティング：--endpoint smartag.<RegionId>.aliyuncs.com で、リクエストの送信先となるリージョナルエンドポイントを指定します（クロスリージョンクエリでは必須）
• ビジネスリージョン：--biz-region-id は API の RegionId パラメーターです
• 重要：エンドポイントのルーティングには --region ではなく --endpoint を使用する必要があります。プラグインの --region マッピングは不完全で、eu-west-1、us-east-1、cn-zhangjiakou-spe では失敗します
• 特記事項：describe-regions では --endpoint のみが必要です（--biz-region-id は不要）

必須の呼び出し契約

以下は必須要件です。各シナリオでは、指定された API 一式をすべて呼び出す必要があります。describe-smart-access-gateways のレスポンスに含まれるフィールドを再利用して、専用 API の呼び出しを代用してはいけません。

Contract A — 単一インスタンスの完全な設定クエリ

トリガー：ユーザーが特定の sag-xxx インスタンスの設定について尋ねる場合（「このゲートウェイの設定」「xxx の設定を確認」「完全な設定」「すべての設定」「WAN／ルート／DNAT をすべて確認」「ネットワーク切り替え後に設定を照合」「設定に問題がないか」「xxx の設定を検査」など。「点検／診断／検査」という語が含まれていてもこのシナリオに該当し、⛔ Contract D の誤用は厳禁です）。

以下の 12 個の API をすべて呼び出す必要があります（インスタンスが sag-software の場合に限り、Contract C に従ってデバイスレベルの API を省略できます）。

#	API	備考
A1	describe-smart-access-gateways	インスタンスの基本情報と分類
A2	describe-smart-access-gateway-attribute	VPN の状態と詳細属性
A3	describe-sag-device-info	デバイスレベル、--smart-ag-sn が必要
A4	describe-sag-wan-list	デバイスレベル、--smart-ag-sn が必要
A5	describe-sag-static-route-list	静的ルート
A6	describe-sag-route-list	完全なルートテーブル
A7	describe-dnat-entries	--sag-id を必ず使用（--smart-ag-id は使用しない）
A8	describe-snat-entries	--smart-ag-id を使用
A9	describe-cloud-connect-networks	CCN（リージョンレベル）
A10	describe-acls	ACL（リージョンレベル）
A11	describe-qoses	QoS（リージョンレベル）
A12	describe-sag-current-dns	デバイスレベル、--smart-ag-sn が必要

Contract A — 重要なルールの要点（詳細な 12 行の bash 骨格と Self-check のアサーションについては、references/contract-skeletons.md § Contract A を参照）：

1. パラメーターの厳密な対応：A3/A4/A12 では --smart-ag-sn $SN を使用します（SN は A1 の SerialNumber から取得します。カンマ区切りの場合は個別の SN に分割して呼び出します。空の場合、または sag-software の場合は A3/A4/A12 を省略し、Contract C に従います）。A5/A6 では --smart-ag-id を使用します。A7 の describe-dnat-entries では --sag-id を使用します（A8 とは異なる点に注意）。A9/A10/A11 では --biz-region-id のみを使用します。
2. パラメーターエラーからの復旧：CLI で Error: --smart-ag-sn is required または Error: --smart-ag-id is required が表示された場合は、A1～A12 のパラメーターテーブルを照合して直ちに修正し、2 回再試行する必要があります。❗CLI のパラメーターエラーを VPN の障害／ネットワーク異常／インスタンス不存在と誤認し、その API を省略してはいけません。
3. コマンドの連結禁止（No-Chaining）：❌ &&／;／||／| を使ってコマンドを連結してはいけません。各 API は独立した行に記述し、/tmp/sag_a*.json に個別にリダイレクトし、終了コードも個別に取得する必要があります。失敗した場合はそのコマンドのみを 500ms 間隔で 2 回再試行します。それでも失敗する場合は FAILED: と記録し、後続の処理を続けてください。中断は禁止です。set -e は禁止です。
4. 禁止される近道：❌ A3/A9/A10 の呼び出しを AclIds／AssociatedCcnId／HardwareVersion フィールドで代用してはいけません。❌ # TODO／... をプレースホルダーとして使い、いずれかの呼び出しを省略してはいけません。❌ --smart-ag-sn を誤って --smart-ag-id と記述してはいけません。
5. Self-check：12 個の呼び出しが完了した後、すべての生成ファイルが空でないことを確認する Self-check のアサーションを実行する必要があります。1 つでも不足している場合は exit 1 とします。

Contract A の 12 行 bash 骨格——「単一インスタンスの 12 項目完全設定クエリ」の場合にのみ使用します。⛔ 下記の Contract D の 10 行と混用してはいけません（D は 10 項目の健全性点検にのみ使用します）：

aliyun smartag describe-smart-access-gateways          --biz-region-id "$REGION" --smart-ag-id "$SAG_ID" > /tmp/sag_a01.json
aliyun smartag describe-smart-access-gateway-attribute --biz-region-id "$REGION" --smart-ag-id "$SAG_ID" > /tmp/sag_a02.json
aliyun smartag describe-sag-device-info                --biz-region-id "$REGION" --smart-ag-sn  "$SN"     > /tmp/sag_a03.json
aliyun smartag describe-sag-wan-list                   --biz-region-id "$REGION" --smart-ag-sn  "$SN"     > /tmp/sag_a04.json
aliyun smartag describe-sag-static-route-list          --biz-region-id "$REGION" --smart-ag-id "$SAG_ID" > /tmp/sag_a05.json
aliyun smartag describe-sag-route-list                 --biz-region-id "$REGION" --smart-ag-id "$SAG_ID" > /tmp/sag_a06.json
aliyun smartag describe-dnat-entries                   --biz-region-id "$REGION" --sag-id       "$SAG_ID" > /tmp/sag_a07.json
aliyun smartag describe-snat-entries                   --biz-region-id "$REGION" --smart-ag-id "$SAG_ID" > /tmp/sag_a08.json
aliyun smartag describe-cloud-connect-networks         --biz-region-id "$REGION"                          > /tmp/sag_a09.json
aliyun smartag describe-acls                           --biz-region-id "$REGION"                          > /tmp/sag_a10.json
aliyun smartag describe-qoses                          --biz-region-id "$REGION"                          > /tmp/sag_a11.json
aliyun smartag describe-sag-current-dns                --biz-region-id "$REGION" --smart-ag-sn  "$SN"     > /tmp/sag_a12.json

Contract B — マルチリージョンのアセットインベントリ

トリガー：ユーザーがリージョンをまたぐインベントリを求めた場合（例：「资产盘点」、「全部区域」、「所有地域」、「region discovery」）。

必ず次の手順を実行してください。

1. describe-regions を最初に呼び出します。コード内や会話文にリージョン ID をハードコードしてはいけません。
2. 返されたリージョンを変数で反復処理し（for region in ...）、各リージョンについて次を呼び出します。
   • describe-smart-access-gateways（ページネーション付きインスタンス一覧）
   • describe-cloud-connect-networks（CCN、リージョンごとに 1 回、インスタンスごとではありません）
   • describe-acls（リージョンごとに 1 回）
   • describe-qoses（リージョンごとに 1 回）
3. レポートでは、DescribeRegions の応答から取得した変数でリージョンを参照してください。説明文にリージョン ID をリテラルで記述してはいけません。

Contract B — 重要ルールの要点（詳細な for-region bash 骨格と Self-check アサーションは references/contract-skeletons.md § Contract B を参照してください）：

1. 骨格 + ループ内での即時アサーション：describe-regions で動的なリージョン一覧を取得し、各リージョンで 4 つの API（インスタンス／CCN／ACL／QoS）を並行して呼び出します。各リージョンのループ末尾で直ちに 4 つの /tmp/sag_b0[1-4]_${REGION}.json がすべて空でないことをアサートします。1 つでも欠けている場合は REGION_FAILED: $REGION を記録して次のリージョンに進み、break によるループ中断は禁止です。describe-acls／describe-qoses のリージョンごとの呼び出しが 1 回でも欠けていれば Contract B は失敗です。
2. データ収集順序：✅ for ループ内では raw JSON のみを /tmp/sag_*_${REGION}.json に保存します。✅ ループ終了後に jq でまとめて集計し、最終 CSV を書き込みます。❌ 検索しながら >> file.csv で追記することは厳禁です。
3. インスタンス 0 件のプレースホルダー：各リージョンは最終 CSV に少なくとも 1 行含める必要があります。インスタンスがないリージョンにはプレースホルダー行（Region=xxx, Instances=0, Note="no instances"）を記載し、全体から除外してはいけません。
4. CSV の整合性アサーション：CSV に現れる一意な Region の数は DescribeRegions の有効なリージョン数 N と等しくなければなりません。4 つのリージョン単位 API の生成ファイル数も N と等しくなければなりません。そうでない場合は exit 1 で終了します。

Contract B の for ループ用 bash 骨格——各リージョンで 4 つのコマンドを厳密に順番どおり実行し、ループ末尾で即時にアサートします。⛔ ループ外での単独呼び出しやリクエストの統合は禁止です。いずれかのリージョンを漏らしてはいけません：

for REGION in $(jq -r '.Regions.Region[].RegionId' /tmp/sag_regions.json); do
  EP=smartag.${REGION}.aliyuncs.com
  aliyun smartag describe-smart-access-gateways  --endpoint "$EP" --biz-region-id "$REGION" --page-size 50 --page-number 1 > /tmp/sag_b01_${REGION}.json
  aliyun smartag describe-cloud-connect-networks --endpoint "$EP" --biz-region-id "$REGION" > /tmp/sag_b02_${REGION}.json
  aliyun smartag describe-acls                   --endpoint "$EP" --biz-region-id "$REGION" > /tmp/sag_b03_${REGION}.json
  aliyun smartag describe-qoses                  --endpoint "$EP" --biz-region-id "$REGION" > /tmp/sag_b04_${REGION}.json
  for f in /tmp/sag_b0[1-4]_${REGION}.json; do [ -s "$f" ] || echo "REGION_FAILED: $REGION ($f)"; done
done

Contract C — sag-software クライアントのクエリ（デバイスレベルをスキップ）

トリガー：HardwareVersion == "sag-software"（ソフトウェア APP クライアントで、物理デバイスはありません）。

必ず次の手順を実行してください。

1. describe-smart-access-gateway-client-users（APP ユーザー一覧 — 項目 #11）を呼び出します。
2. リージョンレベルの API も呼び出します：describe-cloud-connect-networks、describe-acls、describe-qoses、describe-flow-logs。
3. デバイスレベルの API はすべてスキップします：describe-sag-device-info、describe-sag-wan-list、describe-sag-static-route-list、describe-dnat-entries、describe-snat-entries、describe-sag-current-dns。
4. どの呼び出しにも --smart-ag-sn を渡してはいけません（sag-software では SN フィールドが空です）。

Contract C — 重要ルールの要点（詳細な 8 行の bash 骨格と Self-check は references/contract-skeletons.md § Contract C を参照してください）：

• 8 つの API 呼び出しの骨格には describe-flow-logs と describe-sag-route-list が含まれます。いずれかが欠けていれば Contract C は失敗です。
• describe-sag-route-list は sag-software の場合も呼び出す必要があります。パラメーターには --smart-ag-id $SAG_ID を使用します（⛔ --smart-ag-sn の指定は禁止です。SN は空です）。
• No-Chaining：8 つのコマンドはそれぞれ独立して実行し、&&／;／|| で連結してはいけません。
• Self-check：すべての生成ファイルが空でないこと、および not a valid api エラーがないこと（PascalCase の検出）を確認します。

Contract D — 完全なヘルスチェック（10 項目）

トリガー：ユーザーが特定のインスタンスを指定せず、アカウントレベル／一括の「完全点検」「10 項目点検」「ヘルスチェック」「一式点検」を求めた場合。⛔ 具体的な sag-xxx インスタンスの設定について質問された場合（「診断／照合／確認」の語が含まれていても）は、必ず Contract A 12-line を使用し、この契約は使用しないでください。

Contract D の 10 行 bash 骨格——「完全なヘルスチェック 10 項目」の場合にのみ使用します。⛔ 単一インスタンスの 12 項目設定クエリには、上記の Contract A 12-line を使用してください（kebab-case、パラメーターはバインド済み、無条件ですべて呼び出す）：

aliyun smartag describe-smart-access-gateways          --biz-region-id "$REGION" --smart-ag-id "$SAG_ID"           > /tmp/sag_d01.json   # #1 Status + #4 EndTime
aliyun smartag describe-smart-access-gateway-attribute --biz-region-id "$REGION" --smart-ag-id "$SAG_ID"           > /tmp/sag_d02.json   # #2 VpnStatus
aliyun smartag describe-smart-access-gateway-ha        --biz-region-id "$REGION" --smart-ag-id "$SAG_ID"           > /tmp/sag_d03.json   # #3 HA DeviceLevelBackupState
aliyun smartag describe-sag-drop-topn                  --biz-region-id "$REGION" --smart-ag-id "$SAG_ID" --size 10 > /tmp/sag_d05.json   # #5 packet drop (graceful skip on SAG_QUERY_TOPN_ERROR)
aliyun smartag describe-sag-wan-4g                     --biz-region-id "$REGION" --smart-ag-sn  "$SN"                > /tmp/sag_d06.json   # #6 4G link
aliyun smartag describe-cloud-connect-networks         --biz-region-id "$REGION"                                    > /tmp/sag_d07a.json  # #7 CCN
aliyun smartag describe-grant-sag-rules                --biz-region-id "$REGION" --smart-ag-id "$SAG_ID"           > /tmp/sag_d07b.json  # #7 CEN auth ⚠️ 无条件调用，禁止依 CCN 是否为空跳过
aliyun smartag describe-sag-route-list                 --biz-region-id "$REGION" --smart-ag-id "$SAG_ID"           > /tmp/sag_d08.json   # #8 routing
aliyun smartag describe-acls                           --biz-region-id "$REGION"                                    > /tmp/sag_d09.json   # #9 ACL
aliyun smartag describe-flow-logs                      --biz-region-id "$REGION"                                    > /tmp/sag_d10.json   # #10 FlowLog

describe-health-checks は呼び出さないでください（InvalidApi.NotFound が返されます — 利用不可 API の一覧を参照してください）。

重要ルール：

1. API 名は必ず kebab-case にします：plugin-mode では PascalCase（例：DescribeSmartAccessGateways、DescribeGrantSagRules、DescribeAcls）を使用すると not a valid api が返されるため、kebab-case に書き換える必要があります。
2. 10 項目を無条件で呼び出します：❌ フィールドの状態に応じてスキップすることは厳禁です（例：if AssociatedCcnId is empty: skip describe-grant-sag-rules、if HardwareVersion != "sag-software": skip describe-sag-wan-4g）。
3. 唯一の graceful skip の例外：describe-sag-drop-topn で SAG_QUERY_TOPN_ERROR が発生した場合は、その項目をスキップできます。ただし、呼び出し自体は実行する必要があります。事前に判断してスキップしてはいけません。
4. Self-check：スクリプトの末尾で、10 個の /tmp/sag_d*.json 生成ファイルがすべて存在すること、および grep 'not a valid api' /tmp/sag_d*.json が一致しないことをアサートする必要があります。

アンチパターン：フィールドの使い回しによる代用

❌ describe-smart-access-gateways の応答を、専用 API 呼び出しの代用として絶対に使用しないでください。

必要な情報 …	❌ 使用しない	✅ 呼び出す必要がある API
VPN トンネルの状態	基本情報の Status	describe-smart-access-gateway-attribute → VpnStatus
CCN バインドの詳細	AssociatedCcnId フィールド	describe-cloud-connect-networks
インスタンスにバインドされた ACL	AclIds フィールド	describe-acls
QoS ポリシー	（該当するフィールドなし）	describe-qoses
デバイスのハードウェア情報	HardwareVersion のみ	describe-sag-device-info

基本情報の応答は、次に呼び出す API を決めるための分類情報であり、呼び出しを省略するための代替情報ではありません。

実行ブロックルール（専用 API 呼び出し失敗時の処理ゲート。詳細は contract-skeletons.md § アンチパターン を参照）：

1. ✅ 失敗した場合は、レポートに FAILED: <エラー理由> または SKIPPED: <スキップ理由> と記載する必要があります。
2. ❌ 結論を補うために AssociatedCcnId／AclIds／VpnStatus／HardwareVersion フィールドへフォールバックすることを固く禁じます。
3. ❌ 無言でスキップすることを固く禁じます。レポートには、該当項目のステータスを必ず残してください。
4. ✅ kebab-case／PascalCase の誤用があった場合は、修正したコマンドを再実行する必要があります。スキップしてはいけません。

いずれかのルールに違反した場合（特に 2 のフィールドへのフォールバック）、アンチパターンが発動したものと直接判定され、評価では契約違反と見なされます。

必須のセルフチェックテンプレート（Contract A/B/C/D 共通。スクリプト末尾にそのまま貼り付ける必要があります）

# 1. 所有 API 产物文件必须存在且非空
for f in /tmp/sag_*.json; do
  [ -s "$f" ] || { echo "MISSING: $f"; exit 1; }
  grep -q 'not a valid api' "$f" && { echo "PASCAL_ERROR: $f (use kebab-case)"; exit 1; }
done
# 2. CSV 行数（不含表头）必须等于 jq 计算的实例/区域数
[ "$(tail -n +2 final.csv | wc -l)" = "$EXPECTED_N" ] || { echo "COUNT_MISMATCH"; exit 1; }
# 3. Contract B 专用：区域级 API 产物必须 == 4 × N（N = describe-regions 有效区域数）
[ "$(ls /tmp/sag_b0[1-4]_*.json 2>/dev/null | wc -l)" = "$((4*EXPECTED_N))" ] || { echo "REGION_API_MISSING"; exit 1; }
# 4. Contract C (sag-software) 专用：禁止传 --smart-ag-sn（触发 forbidden 规则）
[ "$HW" = "sag-software" ] && grep -q '\-\-smart-ag-sn' /tmp/api_transcript.json && { echo "FORBIDDEN_SN_ON_SOFTWARE"; exit 1; }

セルフチェックに違反した場合、契約の実行失敗と見なされます。アサーションを回避するために、いかなるフィールドへのフォールバックも禁止されています。

モジュール 1：設定の照会

ユーザーのリクエストに基づいて照会を実行します。常に構造化された概要を出力してください。

照会レベルの分類

照会は 2 つのレベルに分類されます。一括照会を実行する場合、リージョンレベルの API はインスタンスごとではなく、リージョンごとに 1 回だけ呼び出してください。

リージョンレベル（リージョンごとに 1 回照会し、結果をそのリージョン内のすべてのインスタンスで共有）：

• #5 CCN リスト：describe-cloud-connect-networks
• #6 ACL ルール：describe-acls
• #7 QoS ポリシー：describe-qoses
• #9 フローログ：describe-flow-logs

インスタンスレベル（インスタンスごとに照会）：

• その他すべての機能（#1-4、#5 GrantRules/VBR、#8、#10-12）

機能の適用マトリクス

すべての照会がすべてのインスタンスタイプに適用されるわけではありません。無駄な API 呼び出しを避けるため、適用されない照会は必ずスキップしてください。

#	機能	sag-1000/100wm（SNあり）	sag-1000/100wm（SNなし）	sag-software
1	インスタンス情報	✅	✅	✅
2	デバイスのハードウェア情報	✅	❌	❌
3	WAN 設定	✅	❌	❌
4	ルーティング	✅	❌	❌
5	CCN/CEN バインド	✅	✅	✅
6	ACL ルール	✅（リージョン）	✅（リージョン）	✅（リージョン）
7	QoS ポリシー	✅（リージョン）	✅（リージョン）	✅（リージョン）
8	DNAT/SNAT	✅	✅	❌
9	フローログ	✅（リージョン）	✅（リージョン）	✅（リージョン）
10	パケットドロップ（DropTopN）	✅	✅	✅（リージョン）
11	SAG APP クライアント	❌	❌	✅
12	DNS 設定	✅	❌	❌

判定ロジック：

• HardwareVersion == "sag-software" → ソフトウェアクライアントです。#1、#5、#6、#7、#9、#11 のみを照会し（つまり Contract C）、--smart-ag-sn を渡すことは禁止です。
• SerialNumber が空 → ハードウェアデバイスはバインドされていません。#2、#3、#4、#12 をスキップします。
• ユーザーが「完全な設定」をリクエストした場合、または単一インスタンスであることが確定している場合 → Contract A に記載された 12 個の API を呼び出す必要があります（ただし、上記ルールに従い、デバイスレベルの API は除外します）。
• describe-health-checks は、バージョン 2018-03-13 で InvalidApi.NotFound を返すため、現在使用できません。レポートには明示的に skipped と記載してください。
• describe-sag-drop-topn は主要リージョン（cn-shanghai/cn-hangzhou など）で使用できますが、エッジリージョン（cn-zhangjiakou-spe など）では SAG_QUERY_TOPN_ERROR を返す場合があります。この場合は、リージョン非対応として該当項目をスキップし、全体の点検は中断しないでください。

複数 SN の処理とパラメーターの事前チェック

対象範囲：Contract A のハードウェアデバイスのシナリオにのみ適用されます。Contract C（sag-software）のシナリオでは、本節の --smart-ag-sn パラメーターの指定は禁止です（forbidden ルールに抵触します）。

一部のインスタンスにはプライマリとスタンバイの 2 台のデバイスがあり、SerialNumber フィールドはカンマ区切りです（例：sag61dacczh,sag61daccq6）。処理ルール：

1. パラメーターの事前チェック：A3/A4/A12 の呼び出し前に、必ず SN=$(jq -r '.SmartAccessGateways.SmartAccessGateway[0].SerialNumber // ""' /tmp/sag_a01.json) を実行してください。[ -z "$SN" ] の場合は echo "SKIPPED: no_sn" を明示的に出力し、空の JSON プレースホルダー echo '{}' > /tmp/sag_a03.json を書き込みます。後続の API 呼び出しが --smart-ag-sn is required エラーで中断されることは固く禁じます。
2. SN にカンマが含まれているかを確認します。複数 SN の場合は分割し、各 SN についてデバイスレベルの API（#2、#3、#4、#12）を個別に呼び出します。
3. レポートでは「プライマリデバイス／スタンバイデバイス」ごとに結果を分けて表示します。

利用可能なクエリ関数

#	関数	API	主な出力
1	インスタンス情報	describe-smart-access-gateways / describe-smart-access-gateway-attribute	ステータス、帯域幅、有効期限、CCN/CEN バインディング、デバイス SN
2	デバイスのハードウェア	describe-sag-device-info / describe-smart-access-gateway-versions	モデル、ソフトウェアバージョン、最新バージョン、4G ステータス
3	WAN 設定	describe-sag-wan-list / describe-sag-wan-4g	WAN IP／ゲートウェイ／DNS、4G 信号ステータス
4	ルーティング	describe-sag-static-route-list / describe-sag-route-list / describe-sag-route-protocol-bgp / describe-sag-route-protocol-ospf	静的ルート、BGP／OSPF 設定、ルートテーブル
5	CCN/CEN バインディング	describe-cloud-connect-networks / describe-grant-sag-rules / describe-sag-vbr-relations	CCN 情報、CEN 認証、VBR 関連付け
6	ACL ルール	describe-acls + ルールクエリ	ルール：送信元／宛先 IP、ポート、プロトコル、アクション
7	QoS ポリシー	describe-qoses + ルールクエリ	レート制限（CIR/PIR）、トラフィック分類子
8	DNAT/SNAT	describe-dnat-entries / describe-snat-entries	ポートマッピング、アドレス変換ルール
9	フローログ	describe-flow-logs	ステータス、SLS プロジェクト、バインド済みインスタンス
10	パケットドロップ	describe-sag-drop-topn	パケットドロップ統計の上位 N 件（--size 10 を使用し、SAG_QUERY_TOPN_ERROR の場合はエラーを適切にスキップ）
11	SAG APP クライアント	describe-smart-access-gateway-client-users	APP ユーザーリスト、クライアントタイプ、帯域幅クォータ（describe-sag-online-client-statistics は非推奨のため、呼び出さないでください）
12	DNS 設定	describe-sag-current-dns	アクティブな DNS サーバー

クエリのワークフロー

1. ユーザーがクエリしたい設定を特定します
2. RegionId と SmartAGId を確認します（指定されていない場合は尋ねます）
3. 適用可能性を確認します：インスタンスタイプ（sag-software またはハードウェア）と SN の有無を判定します
4. 複数 SN を確認します：SerialNumber にカンマが含まれている場合は、分割して各デバイスを個別にクエリします
5. クエリレベルを遵守します：リージョンレベルの API（#5 CCN リスト、#6、#7、#9）はリージョンごとに 1 回だけ呼び出します
6. CLI 経由で該当する API を呼び出します
7. フォールトトレランスを使用して応答を解析します（references/openapi-reference.md § Response Structure Notes を参照）
8. 構造化された要約を提示します
9. ユーザーがレポートファイルを求めた場合は、Markdown レポートを生成します（「出力」セクションを参照）

クエリ出力テンプレート

## SAG Configuration: [Query Type]

**Instance**: sag-xxxxx | **Region**: cn-shanghai | **Time**: 2026-05-09 14:30

### Results

[Formatted key-value pairs or table from API response]

### Notes
[Any observations: version outdated, config missing, potential issues]

モジュール 2：ステータス検査（状態巡検）

包括的なステータス検査を実行します。デフォルトではすべての検査項目を実行し、ユーザーが指定した場合は特定の項目を実行します。

検査項目

10 項目の検査項目とその API の対応関係は、上の表の Contract D — Complete Health Inspection（199～212 行）を参照してください。しきい値と Green/Yellow/Red の判定ロジックについては、references/inspection-rules.md を参照してください。

DropTopN の利用可否：describe-sag-drop-topn は主要リージョン（cn-shanghai/cn-hangzhou など）で利用できますが、エッジリージョン（cn-zhangjiakou-spe など）では SAG_QUERY_TOPN_ERROR が返される場合があります。その場合は「リージョン非対応のためスキップ」と記録し、全体の検査は中断しません。describe-health-checks は InvalidApi.NotFound を返すため、現行バージョンでは利用できません。

検査のワークフロー

1. パラメーター（リージョン範囲、インスタンス範囲、検査項目のサブセット）を確認します
2. references/status_inspection_template.py を読み込みます
3. [CUSTOMIZE] セクションをユーザーの要件に合わせて変更します：
   • REPORT_OUTPUT_DIR → ユーザーのワークスペースパス
   • REGION_FILTER → "all" または特定のリージョンリスト
   • INSPECTION_ITEMS → "all" または特定の項目番号（1～9）
   • THRESHOLDS → ユーザーがカスタムしきい値を指定した場合は調整します
4. 適合させたスクリプトをワークスペースに書き込み、実行します
5. スクリプトが失敗した場合：エラーを読み取り、該当する関数を修正して再試行します
6. 主な調査結果を会話内で提示し、生成されたレポートファイルへのリンクを共有します

検査レポートのテンプレート

レポートには、Summary（Normal／Attention／Critical の項目数）、Critical Issues 表、Attention Items 表、Normal Items リスト、Recommendations を含める必要があります。詳細なレポートテンプレートとしきい値の説明については、references/inspection-rules.md を参照してください。

出力形式

必ず以下を提供してください。

1. 会話の要約：結果をチャットに簡潔に直接提示します（主な調査結果を示し、赤／黄の項目があれば強調します）。
2. レポートファイル（調査または複数項目に関する問い合わせの場合）：ユーザーのワークスペースに保存する Markdown ファイルを生成します。

レポートファイルの生成

インスタンス ID と日付に基づく決定的なファイル名を使用します（同じ日に再実行した場合は上書きします）。

import os
from datetime import datetime

report_content = "..."  # Generated report markdown
filename = f"SAG_Inspection_{sag_id}_{datetime.now().strftime('%Y%m%d')}.md"
output_path = os.path.join(workspace_dir, filename)

with open(output_path, 'w', encoding='utf-8') as f:
    f.write(report_content)

データのサニタイズと整合性ルール

CSV／Markdown レポートを生成する前に、必ず以下の 3 項目のデータクリーニングと自己検証を実行してください（詳細な jq／date／awk スクリプトについては references/contract-skeletons.md § Data Sanitization を参照してください）。

1. Null 値のフォールバックとフィールド名の検出：すべての jq によるフィールド取得箇所に // "N/A" のフォールバックを追加します。帯域幅フィールドには必ずフォールバックチェーン .Bandwidth // .BandWidth // .MaxBandwidth // "N/A" を使用してください（API の実際の応答は MaxBandwidth ですが、ドキュメントでは BandWidth と誤記されていることがよくあります）。CCN 名には .Name // .CcnName // "N/A" を使用してください。CSV に null／None／空のセルを含めてはいけません（インスタンスがないリージョンのプレースホルダー行を除きます。その場合は "no instances" と記載する必要があります）。
2. タイムスタンプの人間が読める形式への変換：EndTime／ExpireTime／CreateTime などは YYYY-MM-DD に変換してください（date -r／date -d を使用します）。人間が読む CSV に epoch の生の値を残してはいけません（raw データが必要な場合は *_raw.csv に別途保存します）。
3. ヘッダーと明細の整合性チェック：Summary に記載する「インスタンスが X 個／リージョンが X 個」という数は、明細表の実際の行数と厳密に一致させてください。その数は wc -l／jq length で計算し、人手で推定してはいけません。レポート生成の最後に必ず整合性チェックを実行し、一致しない場合は exit 1 で終了してください。

エラー処理

エラー	原因	対応
InvalidRegionId	リージョンが正しくありません	ユーザーにリージョンの確認を依頼し、一般的な SAG リージョンを列挙します
InvalidSmartAGId.NotFound	このリージョンにインスタンスがありません	他のリージョンを試すか、ユーザーに確認を依頼します
Forbidden / NoPermission	RAM ポリシーの権限が不足しています	必要な権限（smartag:Describe*）をユーザーに伝えます
Throttling	API のレート制限に達しました	待機してから、バックオフを適用して再試行します
MissingSmartAGSn	API がデバイス SN を要求していますが、指定されていません	スキップします。インスタンスに物理デバイスが紐付けられていません
SmartAccessGatewayNotOnline	デバイスがオフラインです	ステータスを記録します。デバイスの現在の設定は照会できません
Sag.DeviceNotExist	SN が一致しないか、複数の SN が分割されていません	カンマ区切りの SN を分割し、個別に再試行します
MissingSagId	describe-dnat-entries のパラメーターに関する問題	この API では --smart-ag-id の代わりに --sag-id を使用します
InvalidApi.NotFound	現在のバージョンに API が存在しない可能性があります	エラーを無視してスキップし、レポートに記載します

ベストプラクティス

1. 照会の前にインスタンスを分類する — 該当しない API はスキップします（sag-software にはデバイスレベルの照会がありません）。
2. デバイスレベルの呼び出しの前に、複数の SN を分割する — カンマ区切りの SN を渡すと DeviceNotExist エラーが発生します。
3. リージョンレベルの API はリージョンごとに 1 回呼び出す — ACL／QoS／FlowLog／CCN はインスタンスごとではなく、共有リソースです。
4. すべての失敗を明示的に報告する — 何も通知せずにスキップしてはいけません。アクセスできなかった項目とその理由を必ずレポートに記載します。
5. フィールドの流用による代用をしない — 基本の describe-smart-access-gateways 応答に含まれるフィールド（AssociatedCcnId、AclIds、VpnStatus など）を、専用 API の呼び出しの代わりに使用してはいけません。基本の応答は分類用であり、専用 API の代わりにはなりません。
6. 生の JSON は一時ファイルに保存する — CLI の応答を /tmp/sag_*.json にリダイレクトし（例：aliyun smartag describe-xxx ... > /tmp/sag_<api>_<region>.json 2>&1）、その後、必要なフィールドを要約します。会話に生の JSON 全体を出力しないでください。

利用できないことが確認されている API

以下の API は、現在の SAG API バージョン（2018-03-13）では利用できないことが確認されています。これらを呼び出してはいけません。シナリオ上、呼び出しが必要と思われる場合は、レポートに「API X is unavailable in the current version; skipping this item」と明記するか、代替手段を使用してください。

API	ステータス	代替手段
describe-health-checks / describe-health-check-attribute	InvalidApi.NotFound が返されます	従来の調査の項目 #10 をスキップし、レポートに記載します
describe-sag-online-client-statistics	InvalidApi.NotFound が返されます	APP ユーザー一覧には describe-smart-access-gateway-client-users を使用します

参考リンク

参考資料	説明
references/openapi-reference.md	25 種類以上の SAG API の OpenAPI パラメーター完全リファレンス
references/contract-skeletons.md	詳細な bash スケルトン、セルフチェック、データクレンジングルール（Contract A/B/C/D + Anti-Pattern + Sanitization）
references/ram-policies.md	必須の RAM 権限（28 個の読み取り専用アクション）