alibabacloud-network-health-inspection

前提条件

• aliyun CLI：インストールされ、アクセス認証情報が設定されている必要があります（aliyun configure）。未インストールの場合は、macOS では brew install aliyun-cli を実行するか、GitHub Releases からダウンロードしてください。
• Python 3.7+：検査スクリプトの実行と監視チャートの生成に必要です。
• matplotlib：監視チャートの生成に使用する Python のチャート作成ライブラリです。未インストールの場合は、pip3 install matplotlib を実行してください。

必要な RAM 権限

この Skill のすべての API 呼び出しは読み取り専用のクエリであり、リソースの作成、変更、削除は行いません。以下の権限が必要です。

クラウド製品	API 権限	目的
Cloud Monitor (CMS)	cms:DescribeMetricList	すべてのネットワーク製品の監視メトリックデータをクエリします（コア権限）。
VPC	vpc:DescribeEipAddresses	EIP の一覧をクエリします。
VPC	vpc:DescribeCommonBandwidthPackages	Common Bandwidth Package の一覧をクエリします。
VPC	vpc:DescribeNatGateways	NAT Gateway の一覧をクエリします。
VPC	vpc:DescribePhysicalConnections	Physical Connection の一覧をクエリします。
VPC	vpc:DescribeVirtualBorderRouters	VBR の一覧をクエリします。
Cloud Enterprise Network (CEN)	cbn:DescribeCens	CEN の一覧をクエリします。
Cloud Enterprise Network (CEN)	cbn:DescribeCenBandwidthPackages	CEN 帯域幅パッケージをクエリします。
Cloud Enterprise Network (CEN)	cbn:ListTransitRouters	Transit Router の一覧をクエリします。
Cloud Enterprise Network (CEN)	cbn:ListTransitRouterVpcAttachments	TR VPC アタッチメントをクエリします。
Cloud Enterprise Network (CEN)	cbn:ListTransitRouterVbrAttachments	TR VBR アタッチメントをクエリします。
Cloud Enterprise Network (CEN)	cbn:ListTransitRouterRouteTables	TR ルートテーブルをクエリします。
Global Accelerator (GA)	ga:ListAccelerators	Global Accelerator インスタンスの一覧をクエリします。
CLB	slb:DescribeLoadBalancers	CLB の一覧をクエリします。
ALB	alb:ListLoadBalancers	ALB の一覧をクエリします。
NLB	nlb:ListLoadBalancers	NLB の一覧をクエリします。

推奨される RAM ポリシー JSON と詳細なセキュリティに関する注意事項については、references/ram-policies.md を参照してください。

製品に必要な API 権限が不足している場合、Skill はその製品をスキップし、レポート内でエラーとして記録します。他の製品の検査には影響しません。

運用上の安全性に関する説明（PreToolUse Hook）

この Skill では、以下の理由により PreToolUse Hook を設定していません。

1. 完全な読み取り専用操作：すべての API 呼び出しは Describe* / List* の読み取り専用クエリであり、リソースの作成、変更、削除は行いません。
2. ツールの使用範囲を制限：allowed-tools で宣言されているのは Bash Read のみです。Skill は Write、Edit、その他のファイル書き込みツールを呼び出せません。
3. Bash の使用を制限：Bash ツールは aliyun CLI の読み取り専用クエリコマンドと python3 の検査スクリプトの実行にのみ使用し、書き込み操作には使用しません。
4. 高リスク操作なし：人間による確認（HITL）が必要な削除、一括書き込み、権限変更の操作はありません。

したがって、この Skill には介入や二次確認が必要な操作がなく、PreToolUse Hook は必要ありません。将来のバージョンで書き込み操作の機能を追加する場合は、それに応じた PreToolUse Hook による介入の仕組みを追加する必要があります。

入力パラメーター

ユーザーは、以下の情報を指定する必要があります（ユーザーの自然言語から抽出します）。

• リージョン（任意）：デフォルトは cn-hangzhou です。カンマ区切りで複数のリージョンを指定できます。例：cn-hangzhou,cn-shanghai
• 期間（必須、デフォルトなし）：ユーザーは検査対象の期間を明示的に指定する必要があります。日数に変換します。
  • 「先週」／「過去7日間」→ --days 7
  • 「過去24時間」／「昨日」→ --days 1
  • 「過去3日間」→ --days 3
• データ集計間隔（必須、デフォルトなし）：ユーザーは監視データの集計粒度を明示的に指定する必要があります（単位：秒）。データクエリとグラフ生成では、この粒度を一律に使用します。一般的な値：
  • 60 — 1分粒度。データ解像度が最も高く、短期間のトラブルシューティングに適しています
  • 300 — 5分粒度。解像度とデータ量のバランスが取れています
  • 900 — 15分粒度。データ量が少なく、長期間の概要把握に適しています
• 検査対象の製品範囲（任意）：デフォルトでは、ネットワーク製品の全11カテゴリを検査します。ユーザーは一部の製品のみを指定できます。製品名はユーザーの自然言語から特定し、以下の対応表を参照して検査対象の製品リストを決定します。

製品名の認識マッピング

ユーザーの入力から製品キーワードを抽出し、対応する検査対象製品にマッピングします。同じ製品に複数の表現がある場合があります。すべて認識する必要があります。

製品 ID	ユーザーが使用する可能性のある表現
EIP	EIP、Elastic IP、Elastic Public IP、Public IP
CBWP	CBWP、Common Bandwidth Package、Shared Bandwidth、Bandwidth Package
NAT	NAT、NAT Gateway、NAT Gateway
CEN	CEN、Cloud Enterprise Network
TR	TR、Transit Router
PhysConn	Physical Connection、Express Connect、Dedicated Line
VBR	VBR、Virtual Border Router、Border Router
GA	GA、Global Accelerator
CLB	CLB、Classic Load Balancer、SLB（注：ユーザーが「SLB」と言う場合、通常はCLBを意味します）
ALB	ALB、Application Load Balancer
NLB	NLB、Network Load Balancer

特別なケースの処理：

• ユーザーが種類を指定せずに「ロードバランサー」と言った場合 → CLB、ALB、NLBの3種類すべてを検査します
• ユーザーが区別せずに「専用線」と言った場合 → Physical ConnectionとVBRを検査します（VBRは専用線のトラフィック監視のエントリーポイントです）
• ユーザーが「SLB」と言った場合 → CLBにマッピングします（Classic Load Balancer）

製品範囲の処理ロジック

1. ユーザーが製品を指定していない場合：ネットワーク製品の全11カテゴリを検査します（デフォルトの動作）

2. ユーザーが製品を指定した場合：ユーザーが言及した製品のみを検査し、言及されていない製品はスキップします

3. ユーザーが未対応の製品に言及した場合：この Skill では現在、その製品の検査がサポートされていないことを明示的にユーザーに伝えます。例：

   この Skill では現在、「VPN Gateway」の検査はサポートされていません。サポート対象のネットワーク製品カテゴリは、EIP、Common Bandwidth Package、NAT Gateway、Cloud Enterprise Network、Transit Router、Physical Connection、VBR、Global Accelerator、CLB、ALB、NLBの11種類です。

   伝えた後、ユーザーが言及した他のサポート対象製品があれば、検査を続けます。

必須パラメーターの確認ロジック

検査を開始する前に、ユーザーが期間とデータ集計期間の両方のパラメーターを指定していることを確認する必要があります。指定されていない場合は、次のように尋ねてください。

1. 期間が指定されていない場合は、次のように尋ねます。

   どのくらいの期間のデータを検査しますか？例：過去1日、過去3日、過去7日など。

2. データ集計期間が指定されていない場合は、その意味を説明したうえで、次のように尋ねます。

   監視データの集計期間はどれにしますか？集計期間は、監視データの各データポイント間の時間間隔を表します。

   • 60秒（1分）：1分ごとに1つのデータポイント。最も細かい解像度で、短期間のトラブルシューティングに適しています
   • 300秒（5分）：5分ごとに1つのデータポイント。解像度とデータ量のバランスが良好です
   • 900秒（15分）：15分ごとに1つのデータポイント。データ量が少なく、長期間の全体的な傾向の把握に適しています

   注：集計期間が短いほど、取得が必要なデータポイント数が増え、検査時間も大幅に長くなります。たとえば、7日間のデータを60秒間隔で検査する場合、メトリックごとに約10,080個のデータポイントが必要ですが、900秒間隔ではメトリックごとに約672個で済みます。

両方のパラメーターを確認した後、検査ワークフローに進みます。

対応する11のネットワーク製品カテゴリ

#	製品	スクリプト	Cloud Monitor 名前空間	主なメトリック
1	Elastic IP（EIP）	inspect_eip.py	acs_vpc_eip	アウトバウンド／インバウンド帯域幅、レート制限によるパケット損失
2	共通帯域幅パッケージ（CBWP）	inspect_cbwp.py	acs_bandwidth_package	アウトバウンド／インバウンド帯域幅、使用率、レート制限によるパケット損失
3	NAT Gateway	inspect_nat.py	acs_nat_gateway	アウトバウンド／インバウンド帯域幅、SNAT 接続数、接続パケット損失
4	Cloud Enterprise Network（CEN）	inspect_cen.py	acs_cen	リージョン間のアウトバウンド／インバウンド帯域幅、帯域幅パッケージ容量
5	Transit Router（TR）	inspect_tr.py	-	TR 接続ステータス、VPC／VBR アタッチメント数
6	物理接続	inspect_physconn.py	-	接続ステータス（トラフィックについては VBR を参照）
7	VBR	inspect_vbr.py	acs_physical_connection	アウトバウンド／インバウンド帯域幅、ヘルスチェックのレイテンシー／パケット損失
8	Global Accelerator（GA）	inspect_ga.py	acs_global_acceleration	アウトバウンド／インバウンド帯域幅、パケットレート
9	Classic Load Balancer（CLB）	inspect_clb.py	acs_slb_dashboard	トラフィック、接続数、QPS、パケット損失
10	Application Load Balancer（ALB）	inspect_alb.py	acs_alb	QPS、HTTP ステータスコード、接続数
11	Network Load Balancer（NLB）	inspect_nlb.py	acs_nlb	帯域幅、アクティブ接続数、新規接続数

重要な技術上の注意点

Cloud Monitor（CMS）のクエリに関する要点

1. CMS はグローバルサービスです：CMS エンドポイントのリージョンには常に cn-hangzhou を使用してください。監視データの所有先は、エンドポイントのリージョンとは関係なく、Dimensions の instanceId によって決まります
2. VBR の CMS 名前空間は acs_physical_connection です。acs_express_connect ではありません
3. CBWP のメトリック名：net_tx.rate／net_rx.rate ではなく、bwp_tx_rate／bwp_rx_rate を使用します
4. NAT Gateway のパケット損失メトリック：SessionLimitDropConnection ではなく、SessionLimitDropRate を使用します
5. VBR のヘルスチェックレイテンシー：VbrHealthyCheckLatency の単位はマイクロ秒（us）です。ミリ秒（ms）に変換するには、1000 で割る必要があります
6. VBR のパケット損失率：VbrHealthyCheckLossRate の戻り値はすでにパーセンテージであるため、100 を掛ける必要はありません
7. ALB／NLB の CMS ディメンションキー：instanceId ではなく、loadBalancerId を使用します
8. 物理接続には Cloud Monitor のメトリックがありません：物理接続のトラフィック監視は、関連付けられた VBR を通じて確認する必要があります

API 呼び出しの宣言

このスキル内のすべての API 呼び出しは読み取り専用のクエリであり、リソースの作成、変更、削除は行いません。

使用する読み取り専用 API の一覧：

• cms:DescribeMetricList - Cloud Monitor データを照会します
• vpc:DescribeEipAddresses - EIP の一覧を照会します
• vpc:DescribeCommonBandwidthPackages - 共通帯域幅パッケージの一覧を照会します
• vpc:DescribeNatGateways - NAT Gateway の一覧を照会します
• vpc:DescribePhysicalConnections - 物理接続の一覧を照会します
• vpc:DescribeVirtualBorderRouters - VBR の一覧を照会します
• cbn:DescribeCens - CEN の一覧を照会します
• cbn:DescribeCenBandwidthPackages - CEN 帯域幅パッケージを照会します
• cbn:ListTransitRouters - Transit Router の一覧を照会します
• cbn:ListTransitRouterVpcAttachments - TR VPC アタッチメントを照会します
• cbn:ListTransitRouterVbrAttachments - TR VBR アタッチメントを照会します
• cbn:ListTransitRouterRouteTables - TR ルートテーブルを照会します
• ga:ListAccelerators - Global Accelerator インスタンスの一覧を照会します
• slb:DescribeLoadBalancers - CLB の一覧を照会します
• alb:ListLoadBalancers - ALB の一覧を照会します
• nlb:ListLoadBalancers - NLB の一覧を照会します

aliyun CLI AI-Mode の設定

このスキル内の aliyun CLI 呼び出しはすべて、Python の検査スクリプトを介して実行します。スクリプトを実行する前に AI-Mode をグローバルに設定し、すべての CLI 呼び出しに正しい User-Agent ヘッダーが付与されるようにしてください。

# Enable AI-Mode (run once before any aliyun CLI usage)
aliyun configure ai-mode enable

# Set User-Agent to identify this Skill
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-network-health-inspection"

# Update plugins to ensure latest versions
aliyun plugin update 2>/dev/null || true

# Disable AI-Mode after all CLI calls are complete
aliyun configure ai-mode disable

実行ワークフロー

ステップ 1：環境と依存関係の確認

# Check aliyun CLI version
aliyun version 2>&1 | head -1

# Enable AI-Mode and set User-Agent (must run at the start of each Skill execution)
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-network-health-inspection"

# Update aliyun CLI plugins (ensure latest plugin versions)
aliyun plugin update 2>/dev/null || true

# Check Python and matplotlib
python3 -c "import matplotlib; print('matplotlib', matplotlib.__version__)" 2>&1

# If matplotlib is not installed, install it automatically
pip3 install matplotlib

AI-Mode の説明：AI-Mode を有効にすると、aliyun CLI がリクエストに User-Agent ヘッダーを含めるようになり、Alibaba Cloud プラットフォームが AI エージェントによって開始された読み取り専用クエリを識別できるようになります。スキルの実行が完了したら、aliyun configure ai-mode disable を実行して AI-Mode を無効にし、デフォルトの状態に戻してください。

ステップ 2：検査用作業ディレクトリの作成

INSPECT_DIR=$(mktemp -d /tmp/network_inspect_XXXXXX)
CHARTS_DIR="$INSPECT_DIR/charts"
mkdir -p "$CHARTS_DIR"
echo "Inspection data directory: $INSPECT_DIR"

ステップ 3：製品検査スクリプトを 1 つずつ実行

ユーザーが指定した製品に対応する検査スクリプトのみを実行してください。 ユーザーが製品の範囲を指定していない場合は、11 個すべてのスクリプトを実行してください。各スクリプトを順番に実行し、結果を JSON ファイルとして保存します。

SCRIPTS_DIR="<skill_path>/scripts"
REGIONS="cn-hangzhou"  # Based on user-specified region
DAYS=7                 # Based on user-specified time range
PERIOD=300             # Based on user-specified aggregation period (seconds)

# The following scripts are executed based on the user's product selection; unselected products are skipped

# 1. EIP inspection (Product ID: EIP)
python3 "$SCRIPTS_DIR/inspect_eip.py" --regions "$REGIONS" --days $DAYS --period $PERIOD > "$INSPECT_DIR/eip.json"

# 2. CBWP inspection (Product ID: CBWP)
python3 "$SCRIPTS_DIR/inspect_cbwp.py" --regions "$REGIONS" --days $DAYS --period $PERIOD > "$INSPECT_DIR/cbwp.json"

# 3. NAT Gateway inspection (Product ID: NAT)
python3 "$SCRIPTS_DIR/inspect_nat.py" --regions "$REGIONS" --days $DAYS --period $PERIOD > "$INSPECT_DIR/nat.json"

# 4. CEN inspection (Product ID: CEN, global resource, no Region needed)
python3 "$SCRIPTS_DIR/inspect_cen.py" --days $DAYS --period $PERIOD > "$INSPECT_DIR/cen.json"

# 5. Transit Router inspection (Product ID: TR, no Cloud Monitor metrics, no --period needed)
python3 "$SCRIPTS_DIR/inspect_tr.py" --regions "$REGIONS" --days $DAYS > "$INSPECT_DIR/tr.json"

# 6. Physical Connection inspection (Product ID: PhysConn, no Cloud Monitor metrics, no --period needed)
python3 "$SCRIPTS_DIR/inspect_physconn.py" --regions "$REGIONS" --days $DAYS > "$INSPECT_DIR/physconn.json"

# 7. VBR inspection (Product ID: VBR)
python3 "$SCRIPTS_DIR/inspect_vbr.py" --regions "$REGIONS" --days $DAYS --period $PERIOD > "$INSPECT_DIR/vbr.json"

# 8. Global Accelerator inspection (Product ID: GA, global resource)
python3 "$SCRIPTS_DIR/inspect_ga.py" --days $DAYS --period $PERIOD > "$INSPECT_DIR/ga.json"

# 9. CLB inspection (Product ID: CLB)
python3 "$SCRIPTS_DIR/inspect_clb.py" --regions "$REGIONS" --days $DAYS --period $PERIOD > "$INSPECT_DIR/clb.json"

# 10. ALB inspection (Product ID: ALB)
python3 "$SCRIPTS_DIR/inspect_alb.py" --regions "$REGIONS" --days $DAYS --period $PERIOD > "$INSPECT_DIR/alb.json"

# 11. NLB inspection (Product ID: NLB)
python3 "$SCRIPTS_DIR/inspect_nlb.py" --regions "$REGIONS" --days $DAYS --period $PERIOD > "$INSPECT_DIR/nlb.json"

オンデマンド実行ルール：ユーザーが選択した製品のスクリプトのみを実行してください。たとえば、ユーザーが「EIP と NAT Gateway」の検査のみを依頼した場合は、スクリプト 1 と 3 のみを実行し、残りの 9 個はスキップしてください。実行されなかった製品の JSON ファイルは生成されません。後続のステップ 4（グラフの生成）とステップ 5（レポートの生成）では、存在しない製品データは自動的に無視されます。

ステップ 4：モニタリンググラフの生成

注：レポートを生成する前にグラフを生成してください。レポートにはグラフへの参照が自動的に埋め込まれます。

# Generate charts for instances with monitoring data
python3 "$SCRIPTS_DIR/inspect_charts.py" \
  --dir "$INSPECT_DIR" \
  --days $DAYS \
  --period $PERIOD \
  --output-dir "$CHARTS_DIR"

ステップ 5：検査レポートの生成（グラフ参照付き）

# Generate Markdown inspection report; --charts-dir parameter embeds chart references in the report
python3 "$SCRIPTS_DIR/inspect_report.py" \
  --dir "$INSPECT_DIR" \
  --days $DAYS \
  --charts-dir "$CHARTS_DIR" \
  --output "$INSPECT_DIR/report.md"

DingTalk Docs に出力する必要がある場合は、まず表示用のローカル版レポートを生成してください。DingTalk 版レポートはステップ 7 で別途生成されます（--image-url-map パラメーターを使用して、ローカルパスをクラウド URL に置き換えます）。

ステップ 6：結果を提示する

1. レポートファイル全体を読み込む：Read ツールを使用して、$INSPECT_DIR/report.md の全内容を読み込みます。
2. レポートを全編提示する：以下を含む（ただし、これらに限定されない）Markdown レポートの全内容をユーザーに提示します。
   • エグゼクティブサマリーと健全性スコア
   • 検査概要テーブル
   • リージョン単位の統計情報
   • 注意が必要なインスタンス（警告／重大の理由を含む）
   • トラフィック分析
   • 各製品の詳細な検査結果（全 11 製品を表示）
   • 各製品の詳細分析（帯域幅分析、トラフィックパターン、パケット損失分析、コスト最適化など）
   • 各製品の監視チャートへの参照と分析（チャートはレポートの Markdown に埋め込まれているため、画像ファイルを個別に表示する必要はありません）
   • スケーリングの推奨事項と最適化の方向性
   • キャパシティプランニングの提案
   • 付録（リスクレベルの説明、仕様上限の参照情報、方法論に関する注記）
3. インスタンスが存在しない場合：レポートには「このアカウントの検査対象範囲内に XXX インスタンスは見つかりませんでした」と明記されます。

重要：レポートの内容を省略、短縮、要約してはいけません。レポート内のすべての単語、すべてのテーブル、すべての詳細分析セクションを完全に表示する必要があります。 注：監視チャートは最終レポート（ローカルレポートまたは DingTalk ドキュメント）に表示するだけで構いません。個別の PNG ファイルを読み込んで、会話内でユーザーに表示する必要はありません。

# Disable AI-Mode after inspection completes, restore default state
aliyun configure ai-mode disable

ステップ 7：DingTalk Docs に出力する（任意）

ユーザーがレポートの DingTalk Docs への出力を希望する場合は、DingTalk Docs MCP サービスを使用します。

基本原則：レポートは省略、欠落、短縮を一切せず、全内容を DingTalk Docs に書き込む必要があります。詳細分析、チャートへの参照、すべてのテーブルおよびすべてのテキストを例外なく含めてください。内容が長い場合は、複数のセグメントに分けて書き込む必要があります。長さを短くするために内容を削減することは固く禁止されています。

前提条件：DingTalk Docs MCP がインストールされているか確認する

現在の環境で DingTalk Docs MCP ツールが利用可能か確認します（create_document、update_document、get_doc_attachment_upload_info など、ドキュメント操作機能を持つ dingtalk を含むツール名）。 DingTalk Docs MCP がインストールされていない場合は、以下のインストール手順をユーザーに案内します。

1. DingTalk MCP サービスのインストールページを開きます：https://aihub.dingtalk.com/#/detail?instanceId=474175&detailType=instanceMcpDetail&mcpId=9629
2. ページの指示に従って、MCP サービスのインストールと認可設定を完了します。
3. MCP 環境変数 DINGTALK_MCP_DOCS_URL が正しく設定されていることを確認します。
4. インストール完了後、この Skill を再実行します。

DingTalk Docs MCP を使用してレポートを公開する完全なワークフロー：

7.1 DingTalk ドキュメントを作成する

DingTalk Docs MCP の create_document を使用して、対象フォルダーにドキュメントを作成します。ドキュメント名は「Alibaba Cloud Network Product Inspection Report YYYY-MM-DD」とします。返されたドキュメントの dentryUuid を記録します（以降のすべての操作で使用します）。

7.2 DingTalk Docs へのチャートの一括並列アップロード（画像 URL を取得）

$CHARTS_DIR 内のすべての PNG チャートファイルを、効率的に並列で DingTalk ドキュメントにアップロードします。

フェーズ 1：アップロード認証情報を一括取得する

すべての PNG ファイルについて、一度に get_doc_attachment_upload_info を呼び出し、次のパラメーターを指定します。

• dentryUuid：ステップ 7.1 で返されたドキュメント ID
• fileName：画像ファイル名（例：eip_eip-xxx_bandwidth.png）
• fileSize：ファイルサイズ（バイト単位）
• mediaType：image/png

パフォーマンス上の重要事項：すべての get_doc_attachment_upload_info MCP 呼び出しを1 回のメッセージで一括して実行してください（1 件ずつ呼び出し、各結果を待ってから次を呼び出すのではなく）。DingTalk MCP は並行呼び出しに対応しているため、すべての認証情報を並列で取得できます。 フェーズ 2：curl による並列アップロード

すべての curl -X PUT コマンドを1 回の Bash 呼び出しにまとめ、並列実行します。

# All curls execute in parallel, wait at the end for all to complete
curl -s -X PUT "<uploadUrl_1>" -H "Content-Type: image/png" --data-binary @"$CHARTS_DIR/file1.png" &
curl -s -X PUT "<uploadUrl_2>" -H "Content-Type: image/png" --data-binary @"$CHARTS_DIR/file2.png" &
curl -s -X PUT "<uploadUrl_3>" -H "Content-Type: image/png" --data-binary @"$CHARTS_DIR/file3.png" &
# ... all images ...
wait
echo "All uploads done"

注：画像が 20 枚を超える場合は、接続数が多くなりすぎないよう、2～3 回の並列バッチ（各バッチ 10～15 枚）に分割します。各バッチ内では並列実行し、バッチ間は順次実行します。

フェーズ 3：マッピングの作成

get_doc_attachment_upload_info から返されたすべての resourceUrl 値を収集し、image_url_map（{filename: resourceUrl} のマッピング）を作成して、$INSPECT_DIR/image_url_map.json に書き込みます。

image_url_map.json の例：

{
  "eip_eip-xxx_bandwidth.png": "<resourceUrl>",
  "nat_ngw-xxx_snat.png": "<resourceUrl>"
}

7.3 DingTalk 版レポートの生成（クラウド画像 URL を使用）

--image-url-map パラメーターを使用してレポートを再生成し、画像参照を DingTalk OSS の resourceUrls に置き換えます。

python3 "$SCRIPTS_DIR/inspect_report.py" \
  --dir "$INSPECT_DIR" \
  --days $DAYS \
  --charts-dir "$CHARTS_DIR" \
  --image-url-map "$INSPECT_DIR/image_url_map.json" \
  --output "$INSPECT_DIR/report_dingtalk.md"

生成された report_dingtalk.md 内のすべての ![xxx](...) 画像パスは、DingTalk OSS の resourceUrls に置き換えられているため、DingTalk Docs で正しく表示されます。

7.4 レポート全体を分割して DingTalk Docs に書き込む

レポートの内容は通常非常に長く（11 製品の詳細な分析、詳細分析、グラフを含む）、必ず分割して書き込む必要があります。

最適な書き込み方法（テスト済み・検証済み。そのまま使用し、調整しないでください）：

1. $INSPECT_DIR/report_dingtalk.md の内容をすべて読み込みます
2. ## の第 2 レベル見出しで複数のセグメントに分割します：## で始まる行を区切り文字として、レポートを複数のチャンクに分割します。最初のチャンクにはレポートのタイトルヘッダー（# Alibaba Cloud Network Product Comprehensive Inspection Report から最初の ## の直前まで）が含まれます。特に注意：## Product Inspection Details セクションには 11 製品すべての完全な内容が含まれており、他のセクションより大幅に大きいため、さらに ### の第 3 レベル見出しで分割し、製品ごとに 1 つの独立したチャンクにする必要があります。
3. 各製品は完全なチャンクとして書き込みます：各製品の ### セグメントには「詳細テーブル + 詳細分析 + 監視グラフ参照」が含まれており、これらを切り離すことはできません。![](url) の画像参照は単なる Markdown テキスト（それぞれ約 100 文字）であり、バイナリ画像ではないため、タイムアウトの原因にはなりません。画像参照を製品セグメントから切り離して個別に書き込まないでください。
4. 大きな製品を分割するルール：単一製品のチャンクが 10000 文字を超える場合（例：18 インスタンスの監視グラフを含む EIP）、#### Monitoring Charts の位置で 2 つのチャンクに分割します。
   • チャンク A：製品タイトル + 詳細テーブル + 詳細分析
   • チャンク B：#### Monitoring Charts とその下のすべてのグラフ参照
   • チャンク B も 10000 文字を超える場合は、さらに 8～10 インスタンスごとのバッチに分割します
   • チャンク A とチャンク B は連続して書き込む必要があります。間に他の製品の内容を挿入してはいけません
5. 小さなセグメントを積極的に統合します（API 呼び出しを減らすことが速度最適化の鍵です）：隣接する小さなセクション（例：インスタンスのない製品や、文字数の少ない製品セグメント）は、可能な限り統合する必要があります。統合後の結果が 10000 文字を超えない限り、1 つのチャンクにまとめます。典型的な例として、インスタンスのない複数の製品と、インスタンスの少ない 1～2 製品をまとめて 1 つのチャンクとして書き込めます。
6. 書き込み順序：
   • 1 番目のチャンク → update_document、mode: overwrite（上書き）
   • 2 番目から N 番目のチャンク → update_document、mode: append（追記）
   • update_document の呼び出し回数を最小限にします。目標は 8～12 回（20 回以上ではありません）。各呼び出しにはネットワークのオーバーヘッドがあるためです
7. レポートの最後までセグメントごとに書き込みます：付録を含むすべてのセクションを完全に書き込んでください

注：1 回の update_document 呼び出しで書き込む内容が大きすぎると、DingTalk HSFTimeOutException（3000ms タイムアウト）が発生することがあります。1 つのチャンクは 10000 文字以下にすることを推奨します。テストでは、10000 文字以下であればタイムアウトは発生しませんでした。 書き込み例（一般的なレポート。マージ後に呼び出し回数が大幅に減少したことに注目してください）：

書き込みバッチ	内容	モード	推定文字数
バッチ 1	レポートのタイトル + エグゼクティブサマリー + 検査の概要 + 注意が必要なインスタンス + トラフィック分析	overwrite	~5000-8000
バッチ 2	製品 1（EIP）の詳細 + 詳細分析（グラフを含めると 10000 文字を超える場合は、グラフを分割）	append	~6000-9000
バッチ 3	製品 1（EIP）のモニタリンググラフ（前のステップで分割した場合のみ）	append	~5000-8000
バッチ 4	製品 2（CBWP）+ 製品 3（NAT）の全内容（グラフへの参照を含む。書き込みを統合）	append	~6000-9000
バッチ 5	製品 4（CEN）+ 製品 5（TR）+ 製品 6（物理接続）+ 製品 7（VBR）（書き込みを統合）	append	~5000-8000
バッチ 6	製品 8（GA）+ 製品 9（CLB）の全内容（書き込みを統合）	append	~5000-8000
バッチ 7	製品 10（ALB）+ 製品 11（NLB）の全内容（書き込みを統合）	append	~5000-8000
バッチ 8	スケーリングに関する推奨事項 + 容量計画 + 付録（リスクの説明 + 仕様への参照 + 方法に関する注記 + 免責事項）	append	~4000-6000

重要なルール（必ず遵守してください）：

• 各製品のグラフへの参照は、その製品の本文の直後に記載してください。すべての製品のグラフをレポートの末尾にまとめないでください
• レポート形式の参照：各製品の #### Monitoring Charts の下に、インスタンスごとにグラフを記載します（**Instance ID (Name) — Metric:** + ![](url)）。モニタリングデータのないインスタンスには、テキストで説明を記載します
• すべての内容を省略せずに記載してください。セクション、表、詳細分析、画像への参照を省略してはいけません
• インスタンスのない製品（「No XXX instances found」）は、隣接するインスタンスのない製品とまとめて書き込むことができます
• 速度最適化の要点：積極的に統合して、update_document の呼び出し回数を 20 回以上から 8～12 回に減らします

7.5 ドキュメントリンクを返す

レポートの全内容（すべてのテキストとグラフを含む）が書き込まれたことを確認し、DingTalk ドキュメントのリンクをユーザーに返します。

リスクレベルの定義

レベル	マーク	基準
重大	[!!!]	使用率 >=90%、パケット損失が発生、VBR のレイテンシ >100ms またはパケット損失 >5%、ステータス異常
警告	[!]	使用率 >=70%、VBR のレイテンシ >50ms またはパケット損失 >1%、ALB の 5XX エラー率 >1%
OK	[OK]	使用率 <70%、すべてのメトリクスが正常
エラー	[ERR]	検査中に API エラーが発生

エラー処理

• aliyun CLI がインストールされていない：brew install aliyun-cli の実行、または GitHub からのダウンロードを促します
• 認証に失敗した：アクセス認証情報を設定するため、aliyun configure の実行を促します
• インスタンスが見つからない：「No XXX instances found within the inspection scope for this account」と明示的に出力します。黙ってスキップしてはいけません
• API 権限が不足している：その製品をスキップし、レポートでエラーとしてマークします。references/ram-policies.md を参照してください
• モニタリングデータがない：考えられる原因は、インスタンスが新規作成された、トラフィックがない、またはメトリクス名が一致しないことです
• matplotlib がインストールされていない：pip3 install matplotlib の実行を促します