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

> ```bash

> 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):

> ```bash

> 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:

> ```bash

> 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

>

> ```bash

> 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.

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..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):

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 "$REGION" --smart-ag-sn  "$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 "$REGION"                                    > /tmp/sag_d09.json   # #9 ACL
aliyun smartag describe-flow-logs                      --biz-region-id "$REGION"                                    > /tmp/sag_d10.json   # #10 FlowLog

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:

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:

判断逻辑:

• 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

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

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__.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:

Reference Links