alibabacloud-smartag-pilot

name	alibabacloud-smartag-pilot
description	Query SAG (Smart Access Gateway / 智能接入网关) configurations and perform status inspections via Alibaba Cloud OpenAPI. Generates inspection report files. Use when the user mentions SAG, smart access gateway, 智能接入网关, or asks to check SAG instance status, query SAG configs, inspect SAG health, troubleshoot SAG connectivity, perform SAG device inspections, 网关巡检, 查询SAG配置, SAG状态巡检, or SAG健康检查.

SAG Pilot v1.0

SAG (Smart Access Gateway / 智能接入网关) configuration query and status inspection skill. Uses aliyun CLI plugin mode.

Architecture: SAG Device/APP → CCN → CEN → VPC (read-only inspection, no resource modification)

Pre-checks

Pre-check: Aliyun CLI >= 3.3.3 required Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update, or see references/cli-installation-guide.md for installation instructions.

Pre-check: SAG plugin installed and up-to-date

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

[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. At the start of the workflow (before any CLI invocation):

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

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason (success, failure, error, cancellation), always disable AI-mode first:

aliyun configure ai-mode disable

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

RAM Policy

This skill requires read-only SAG permissions. See references/ram-policies.md for full JSON policy.

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, SmartAGId, query scope, output format) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Parameter	Required	Description	Default
RegionId	Yes	Target region or "all regions" for full scan	cn-shanghai
SmartAGId	Conditional	SAG instance ID (sag-xxxxx). Not needed for "all instances" queries	—
Query Scope	Yes	Which modules/functions to execute	All applicable
Output Format	Optional	Conversation summary and/or report file	Both

Region Discovery

When querying all regions, always start with:

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

This returns the authoritative list of all SAG-supported regions (RegionId + RegionEndpoint). Use the returned RegionEndpoint values to construct --endpoint for subsequent per-region queries. Do NOT guess or hardcode region IDs.

API Invocation Method

Aliyun CLI (Plugin Mode)

SAG plugin provides native command support with parameter validation and auto-completion:

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

Template for any SAG CLI call:

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

Naming conventions:

• API names: kebab-case (e.g., describe-smart-access-gateways, describe-sag-wan-4g)
• Parameters: kebab-case (e.g., --smart-ag-id, --smart-ag-sn, --page-size)
• Endpoint routing: --endpoint smartag.<RegionId>.aliyuncs.com controls which regional endpoint the request is sent to (REQUIRED for cross-region queries)
• Business region: --biz-region-id is the API's RegionId parameter
• IMPORTANT: Must use --endpoint (not --region) for endpoint routing — the plugin's --region mapping is incomplete and fails for eu-west-1, us-east-1, cn-zhangjiakou-spe
• Special: describe-regions only needs --endpoint (no --biz-region-id)

Mandatory Call Contracts

These are hard requirements — for each scenario below you MUST satisfy the full API set listed. Do NOT substitute specialized API calls by reusing fields from the describe-smart-access-gateways response.

Contract A — Single-Instance Full Configuration Query

Trigger: 用户针对具体某个 sag-xxx 实例询问配置（含「这个网关的配置」「看一下 xxx 的配置」「完整配置」「全部配置」「WAN/路由/DNAT 都查」「换网后对一下配置」「配置有没有问题」「检查 xxx 配置」等；即使夹带「巡检/诊断/检查」字样仍属本场景，⛔ 严禁误用 Contract D）。

You MUST call all 12 APIs below (skip device-level ones only if the instance is sag-software — see Contract C):

#	API	Notes
A1	describe-smart-access-gateways	Instance basic info + classification
A2	describe-smart-access-gateway-attribute	VPN status + detailed attributes
A3	describe-sag-device-info	Device-level, needs --smart-ag-sn
A4	describe-sag-wan-list	Device-level, needs --smart-ag-sn
A5	describe-sag-static-route-list	Static routes
A6	describe-sag-route-list	Full route table
A7	describe-dnat-entries	MUST use --sag-id (NOT --smart-ag-id)
A8	describe-snat-entries	Uses --smart-ag-id
A9	describe-cloud-connect-networks	CCN (region-level)
A10	describe-acls	ACL (region-level)
A11	describe-qoses	QoS (region-level)
A12	describe-sag-current-dns	Device-level, needs --smart-ag-sn

Contract A — 关键规则要点（详细 12-line 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 或 --smart-ag-id is required 时必须对照 A1-A12 参数表立即修正后重试 2 次；❗严禁将 CLI 参数错误误归为 VPN 故障 / 网络异常 / 实例不存在而跳过该 API。
3. No-Chaining：❌ 严禁用 && / ; / || / | 拼接命令；每条 API 必须独立成行、独立重定向到 /tmp/sag_a*.json、独立捕获 exit code。失败时单条重试 2 次（间隔 500ms），重试仍失败标 FAILED: 并继续执行后续，禁止 abort。禁止 set -e。
4. Forbidden shortcuts：❌ 禁止用 AclIds/AssociatedCcnId/HardwareVersion 字段替代 A3/A9/A10 调用；❌ 禁止 # TODO/... 占位略过任何一条；❌ 禁止把 --smart-ag-sn 错写为 --smart-ag-id。
5. Self-check：12 条执行完毕后必须运行 Self-check 断言所有产物文件非空，缺一即 exit 1。

Contract A 12-line bash 骨架——仅用于「单实例 12 项完整配置查询」场景；⛔ 禁止与下方 Contract D 10-line 混用（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  --smart-ag-sn       > /tmp/sag_a12.json

Contract B — Multi-Region Asset Inventory

Trigger: user asks for inventory across regions (e.g. "资产盘点", "全部区域", "所有地域", "region discovery").

You MUST:

1. Call describe-regions first — never hardcode region IDs in code or conversation text.
2. Iterate the returned regions via a variable (for region in ...) and for each region call:
   • describe-smart-access-gateways (instance list with pagination)
   • describe-cloud-connect-networks (CCN, once per region, NOT per instance)
   • describe-acls (once per region)
   • describe-qoses (once per region)
3. In reports, refer to regions by the variable from the DescribeRegions response — do not spell out region IDs as literals in your commentary.

Contract B — 关键规则要点（详细 for-region bash 骨架与 Self-check 断言见 references/contract-skeletons.md § Contract B）：

1. Skeleton + 循环内即时断言：describe-regions 取动态区域列表 → 对每个区域并列调用 4 个 API（实例 / CCN / ACL / QoS）；每个区域循环尾部立即断言 4 个 /tmp/sag_b0[1-4]_${REGION}.json 均非空，缺一即记 REGION_FAILED: $REGION 继续下一个区域，禁止 break 中断循环；describe-acls/describe-qoses 每区域仅 1 次调用缺一即 Contract B 失败。
2. Data Collection Order：✅ for 循环内仅把 raw JSON 落盘到 /tmp/sag_*_${REGION}.json；✅ 循环结束后再统一 jq 聚合 + 写最终 CSV；❌ 严禁边查边 >> file.csv 追加。
3. 零实例占位：每个区域在最终 CSV 中必须至少出现一行；空实例区域写占位行（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 Client Query (skip device-level)

Trigger: HardwareVersion == "sag-software" (software APP client, no physical device).

You MUST:

1. Call describe-smart-access-gateway-client-users (APP user list — Item #11).
2. Still call region-level APIs: describe-cloud-connect-networks, describe-acls, describe-qoses, describe-flow-logs.
3. Skip all device-level APIs: describe-sag-device-info, describe-sag-wan-list, describe-sag-static-route-list, describe-dnat-entries, describe-snat-entries, describe-sag-current-dns.
4. Do NOT pass --smart-ag-sn on any call (the SN field is empty for sag-software).

Contract C — 关键规则要点（详细 8-line 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 — Complete Health Inspection (10 items)

Trigger: 用户未指定具体实例而要求账号级/批量「完整巡检」「10 项巡检」「健康巡检」「全套巡检」；⛔ 用户问具体 sag-xxx 实例配置（即使含「诊断/对一下/检查」字样）一律走 Contract A 12-line，禁用本契约。

Contract D 10-line 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                                     > /tmp/sag_d09.json   
aliyun smartag describe-flow-logs                      --biz-region-id                                     > /tmp/sag_d10.json   

Do NOT call describe-health-checks (returns InvalidApi.NotFound — see Known Unavailable APIs).

关键规则：

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 无命中。

Anti-Pattern: Field-Reuse Substitution

❌ NEVER use the response of describe-smart-access-gateways as a substitute for specialized API calls:

If you need …	❌ Don't use	✅ Must call
VPN tunnel state	Status from basic info	describe-smart-access-gateway-attribute → VpnStatus
CCN binding details	AssociatedCcnId field	describe-cloud-connect-networks
ACL bound to instance	AclIds field	describe-acls
QoS policies	(no such field)	describe-qoses
Device hardware	HardwareVersion alone	describe-sag-device-info

The basic-info response is a classifier (what to call next), not a substitute (for what to skip calling).

Execution Blocking Rules（专用 API 调用失败时的处理闸门，详见 contract-skeletons.md § Anti-Pattern）：

1. ✅ 失败必须在报告中标注 FAILED: <错误原因> 或 SKIPPED: <跳过原因>。
2. ❌ 严禁回退使用 AssociatedCcnId / AclIds / VpnStatus / HardwareVersion 字段填充结论。
3. ❌ 严禁静默跳过；必须在报告中保留该项的状态位。
4. ✅ kebab-case/PascalCase 误用必须重新调用修正后的命令，不可跳过。

违反任意一条（尤其第 2 条字段回退）直接判为 Anti-Pattern 触发，评测会认为契约失败。

Mandatory Self-check Template（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; }

违反 Self-check 即视为契约执行失败，禁止用任何字段回退绕过断言。

Module 1: Configuration Query

Execute queries based on user's request. Always output a structured summary.

Query Level Classification

Queries are classified into two levels. When performing batch queries, call region-level APIs only ONCE per region, not per instance:

Region-Level (query once per region, results shared across all instances in that region):

• #5 CCN list: describe-cloud-connect-networks
• #6 ACL rules: describe-acls
• #7 QoS policies: describe-qoses
• #9 Flow logs: describe-flow-logs

Instance-Level (query per instance):

• All other functions (#1-4, #5 GrantRules/VBR, #8, #10-12)

Feature Applicability Matrix

Not all queries apply to all instance types. MUST skip inapplicable queries to avoid wasted API calls:

#	Function	sag-1000/100wm (有SN)	sag-1000/100wm (无SN)	sag-software
1	Instance info	✅	✅	✅
2	Device hardware	✅	❌	❌
3	WAN config	✅	❌	❌
4	Routing	✅	❌	❌
5	CCN/CEN bindings	✅	✅	✅
6	ACL rules	✅ (region)	✅ (region)	✅ (region)
7	QoS policies	✅ (region)	✅ (region)	✅ (region)
8	DNAT/SNAT	✅	✅	❌
9	Flow logs	✅ (region)	✅ (region)	✅ (region)
10	Packet drop (DropTopN)	✅	✅	✅ (region)
11	SAG APP clients	❌	❌	✅
12	DNS config	✅	❌	❌

判断逻辑:

• HardwareVersion == "sag-software" → 软件客户端，仅查 #1, #5, #6, #7, #9, #11（即 Contract C），禁止传 --smart-ag-sn
• SerialNumber 为空 → 硬件设备未绑定，跳过 #2, #3, #4, #12
• 用户请求“完整配置”或已确定单实例 → 需调用 Contract A 列出的 12 个 API（其中 device-level 按上述规则规避）
• describe-health-checks 在 2018-03-13 版本返回 InvalidApi.NotFound，当前不可用，请在报告中显式标注 skipped
• describe-sag-drop-topn 在主流区域（cn-shanghai/cn-hangzhou 等）可用，在边缘区域（如 cn-zhangjiakou-spe）可能返回 SAG_QUERY_TOPN_ERROR，这种情况下以 region unsupported 的形式跳过单项，不中断全局巡检

Multi-SN Handling & Parameter Pre-check

Scope: 仅适用于 Contract A 硬件设备场景；Contract C (sag-software) 场景禁用本段的 --smart-ag-sn 传参（会触发 forbidden 规则）。

部分实例有主备双设备，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，严禁因 --smart-ag-sn is required 报错中断后续 API 调用。
2. 检测 SN 中是否包含逗号；多 SN 时拆分后对每个 SN 分别调用设备级 API（#2, #3, #4, #12）。
3. 报告中按"主设备 / 备设备"分别展示结果。

Available Query Functions

#	Function	API	Key Output
1	Instance info	describe-smart-access-gateways / describe-smart-access-gateway-attribute	Status, bandwidth, expiry, CCN/CEN bindings, device SN
2	Device hardware	describe-sag-device-info / describe-smart-access-gateway-versions	Model, software version, latest version, 4G status
3	WAN config	describe-sag-wan-list / describe-sag-wan-4g	WAN IP/gateway/DNS, 4G signal status
4	Routing	describe-sag-static-route-list / describe-sag-route-list / describe-sag-route-protocol-bgp / describe-sag-route-protocol-ospf	Static routes, BGP/OSPF config, route table
5	CCN/CEN bindings	describe-cloud-connect-networks / describe-grant-sag-rules / describe-sag-vbr-relations	CCN info, CEN authorization, VBR relations
6	ACL rules	describe-acls + rule queries	Rules: src/dst IP, port, protocol, action
7	QoS policies	describe-qoses + rule queries	Rate limits (CIR/PIR), traffic classifiers
8	DNAT/SNAT	describe-dnat-entries / describe-snat-entries	Port mapping, address translation rules
9	Flow logs	describe-flow-logs	Status, SLS project, bound instances
10	Packet drop	describe-sag-drop-topn	Top-N packet drop statistics (use --size 10, graceful skip on SAG_QUERY_TOPN_ERROR)
11	SAG APP clients	describe-smart-access-gateway-client-users	APP user list, client type, bandwidth quota (describe-sag-online-client-statistics is deprecated — do not call)

Query Workflow

1. Identify which config the user wants to query
2. Confirm RegionId and SmartAGId (ask if not provided)
3. Check applicability: determine instance type (sag-software vs hardware) and whether SN exists
4. Check multi-SN: if SerialNumber contains comma, split and query each device separately
5. Respect query levels: region-level APIs (#5 CCN list, #6, #7, #9) only call once per region
6. Call the corresponding API via CLI
7. Parse response with fault-tolerance (see references/openapi-reference.md § Response Structure Notes)
8. Present structured summary
9. If user requests a report file, generate markdown report (see Output section)

Query Output Template

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

Module 2: Status Inspection (状态巡检)

Perform comprehensive status inspections. Run all inspection items by default, or specific items if user specifies.

Inspection Items

10 项巡检项及其 API 映射见上表 Contract D — Complete Health Inspection（行 199-212）。阈值与 Green/Yellow/Red 判定逻辑详见 references/inspection-rules.md。

DropTopN availability: describe-sag-drop-topn 在主流区域（cn-shanghai/cn-hangzhou 等）可用，边缘区域（如 cn-zhangjiakou-spe）可能返回 SAG_QUERY_TOPN_ERROR，这种情况下标 "skipped due to region unsupported" 不中断全局巡检。describe-health-checks 返回 InvalidApi.NotFound，在当前版本不可用。

Inspection Workflow

1. Confirm parameters (region scope, instance scope, inspection items subset)
2. Read references/status_inspection_template.py
3. Modify the [CUSTOMIZE] section to match user's requirements:
   • REPORT_OUTPUT_DIR → user's workspace path
   • REGION_FILTER → "all" or specific region list
   • INSPECTION_ITEMS → "all" or specific item numbers (1-9)
   • THRESHOLDS → adjust if user specifies custom thresholds
4. Write adapted script to workspace and execute
5. If script fails: read error, fix the relevant function, retry
6. Present key findings in conversation + link to generated report file

Inspection Report Template

报告需包含 Summary（Normal/Attention/Critical 项数）、Critical Issues 表、Attention Items 表、Normal Items 列表、Recommendations。详细报告模板与门阈说明见 references/inspection-rules.md。

Output Format

Always provide:

1. Conversation summary: Concise results directly in chat (key findings, any red/yellow items highlighted)
2. Report file (when inspection or multi-item query): Generate a markdown file saved to user's workspace

Report File Generation

Use a deterministic filename based on instance ID and date (overwrite if re-run same day):

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)

Data Sanitization & Consistency Rules

生成 CSV / Markdown 报告之前必须执行三项强制数据清洗与自校验（详细 jq / date / awk 脚本见 references/contract-skeletons.md § Data Sanitization）：

1. Null 值兜底 + 字段名探测：所有 jq 取字段处必须加 // "N/A" 兜底；带宽字段必须用 fallback 链 .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。

Error Handling

Error	Cause	Action
InvalidRegionId	Wrong region	Ask user to confirm region, list common SAG regions
InvalidSmartAGId.NotFound	Instance doesn't exist in this region	Try other regions or ask user to verify
Forbidden / NoPermission	RAM policy insufficient	Tell user which permission is needed (smartag:Describe*)
Throttling	API rate limit	Wait and retry with backoff
MissingSmartAGSn	API requires device SN but not provided	Skip - instance has no physical device bound
SmartAccessGatewayNotOnline	Device is offline	Record status, cannot query live device config
Sag.DeviceNotExist	SN mismatch or multi-SN not split	Split comma-separated SN and retry individually
MissingSagId	describe-dnat-entries parameter issue	Use --sag-id instead of --smart-ag-id for this API
InvalidApi.NotFound	API may not exist in current version	Skip gracefully, note in report

Best Practices

1. Classify instances before querying — skip inapplicable APIs (sag-software has no device-level queries)
2. Split multi-SN before device-level calls — passing comma-separated SN causes DeviceNotExist errors
3. Region-level APIs call once per region — ACL/QoS/FlowLog/CCN are shared resources, not per-instance
4. Report all failures transparently — never silently skip; always note in report what was inaccessible and why
5. No field-reuse substitution — never use fields from the basic describe-smart-access-gateways response (such as AssociatedCcnId, AclIds, VpnStatus) as a substitute for calling the specialized API; the basic response is a classifier, not a substitute
6. Save raw JSON to temp files — redirect CLI responses to /tmp/sag_*.json (e.g. aliyun smartag describe-xxx ... > /tmp/sag_<api>_<region>.json 2>&1) and then summarize specific fields; avoid dumping full raw JSON into the conversation

Known Unavailable APIs

The following APIs are known unavailable in the current SAG API version (2018-03-13). You MUST NOT call them — if a scenario appears to require them, explicitly declare in the report: "API X is unavailable in the current version; skipping this item" or substitute with the alternative:

API	Status	Alternative
describe-health-checks / describe-health-check-attribute	Returns InvalidApi.NotFound	Skip Item #10 of the classic inspection; note in report
describe-sag-online-client-statistics	Returns InvalidApi.NotFound	Use describe-smart-access-gateway-client-users for APP user list

Reference Links

Reference	Description
references/openapi-reference.md	Complete OpenAPI parameter reference for 25+ SAG APIs
references/contract-skeletons.md	详细 bash 骨架、Self-check、数据清洗规则（Contract A/B/C/D + Anti-Pattern + Sanitization）
references/ram-policies.md	Required RAM permissions (28 read-only actions)