返回技能市场
开发运维 安全

智能接入网关SAG一键巡检

@aliyun/alibabacloud-smartag-pilot

SAG智能接入网关一键配置查询与健康巡检工具。支持配置信息查询（实例、设备、路由、ACL、QoS等）和健康巡检（设备在线、VPN隧道、带宽、丢包、到期预警等），自动生成健康报告，开箱即用。

云Skills门户 热度 73v0.0.1

SAG 助手 v1.0

SAG（Smart Access Gateway，智能接入网关）配置查询与状态巡检 skill。使用阿里云 CLI 插件模式。

架构：SAG Device/APP → CCN → CEN → VPC（只读巡检，不修改资源）

预检查

预检查：阿里云 CLI 版本必须 >= 3.3.3
运行 aliyun version，验证版本是否 >= 3.3.3。如果未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装/更新，
或参阅 references/cli-installation-guide.md 获取安装说明。
预检查：SAG 插件必须已安装且为最新版本
```bash
aliyun plugin install --names aliyun-cli-smartag
aliyun plugin update
aliyun configure set --auto-plugin-install true
```
[必须] 启用 AI-Mode——执行 Agent Skill 时必须启用 AI-mode。
在工作流开始时（调用任何 CLI 之前）：
```bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-smartag-pilot"
```
[必须] 在每个退出点禁用 AI-Mode——无论出于任何原因，在提交最终响应前
（成功、失败、错误或取消），始终必须先禁用 AI-mode：
```bash
aliyun configure ai-mode disable
```

身份认证

预检查：必须提供阿里云凭证
安全规则：
- 禁止读取、回显或打印 AK/SK 值（例如，严禁执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
- 禁止要求用户直接在对话或命令行中输入 AK/SK
- 禁止在 aliyun configure set 中使用明文凭证值
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效的凭证配置（AK、STS 或 OAuth 身份）。
如果不存在有效的凭证配置，请在此停止。
1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证（在终端中使用 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 待 aliyun configure list 显示有效的凭证配置后，返回并重新运行

RAM 策略

此 skill 需要 SAG 只读权限。完整的 JSON 策略请参见 [references/ram-policies.md](references/ram-policies.md)。

[必须] 权限失败处理：在执行过程中的任意阶段，如果任何命令或 API 调用因权限错误而失败，必须遵循以下流程：
1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose skill，引导用户申请必要权限
3. 暂停并等待，直至用户确认已授予所需权限

参数确认

重要：参数确认——执行任何命令或 API 调用前，
所有用户可自定义参数（例如 RegionId、SmartAGId、查询范围、输出格式）
都必须由用户确认。未经用户明确批准，不得假设或使用默认值。

| 参数 | 是否必需 | 描述 | 默认值 | |-----------|----------|-------------|---------| | RegionId | 是 | 目标地域，或选择“所有地域”进行完整扫描 | cn-shanghai | | SmartAGId | 条件必填 | SAG 实例 ID（sag-xxxxx）。“所有实例”查询不需要该参数 | — | | 查询范围 | 是 | 要执行的模块/功能 | 所有适用项 | | 输出格式 | 可选 | 对话摘要和/或报告文件 | 两者 |

地域发现

查询所有地域时，始终先执行以下命令：

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

该命令返回 SAG 支持的所有地域的权威列表（RegionId + RegionEndpoint）。使用返回的 RegionEndpoint 值构造后续逐地域查询所需的 --endpoint。不得猜测或硬编码地域 ID。

API 调用方式

阿里云 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 参数
  • 重要：端点路由必须使用 --endpoint（而非 --region）——插件的 --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）。

下列 APIs 共 12 个，必须全部调用（仅当实例为 sag-software 时才跳过设备级调用——参见 Contract C）：

| # | 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 (region-level) | | A10 | describe-acls | ACL (region-level) | | A11 | describe-qoses | QoS (region-level) | | A12 | describe-sag-current-dns | 设备级，需要 --smart-ag-sn |

Contract A — 关键规则要点（详细 12 行 bash 骨架与自检断言见 [references/contract-skeletons.md § Contract A](references/contract-skeletons.md#contract-a--single-instance-full-configuration-query)）：

  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. 禁止命令串联：❌ 严禁用 && / ; / || / | 拼接命令；每条 API 必须独立成行、独立重定向到 /tmp/sag_a*.json、独立捕获退出码。失败时单条重试 2 次（间隔 500ms），重试仍失败标 FAILED: 并继续执行后续，禁止中止执行。禁止 set -e。
  4. 禁止的捷径：❌ 禁止用 AclIds/AssociatedCcnId/HardwareVersion 字段替代 A3/A9/A10 调用；❌ 禁止 # TODO/... 占位略过任何一条；❌ 禁止把 --smart-ag-sn 错写为 --smart-ag-id。
  5. Self-check：12 条执行完毕后必须运行 Self-check 断言所有产物文件非空，缺一即 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——多区域资产盘点

触发条件：用户请求跨区域资产盘点（例如“资产盘点”、“全部区域”、“所有地域”、“区域发现”）。

必须：

  1. 必须首先调用 describe-regions——严禁在代码或对话文本中硬编码地域 ID。
  2. 使用变量（for region in ...）遍历返回的地域，并对每个地域调用：
  • describe-smart-access-gateways（支持分页的实例列表）
  • describe-cloud-connect-networks（CCN，每个地域调用一次，不得按实例调用）
  • describe-acls（每个地域调用一次）
  • describe-qoses（每个地域调用一次）
  1. 在报告中，必须使用 DescribeRegions 响应中的变量指代地域——不得在说明中将地域 ID 写为字面量。

Contract B — 关键规则要点（详细 按区域循环的 bash 骨架与自检断言见 [references/contract-skeletons.md § Contract B](references/contract-skeletons.md#contract-b--multi-region-asset-inventory)）：

  1. 骨架 + 循环内即时断言：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. 数据收集顺序：✅ for 循环内仅把原始 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 客户端查询（跳过设备级调用）

触发条件：HardwareVersion == "sag-software"（软件 APP 客户端，无物理设备）。

必须：

  1. 调用 describe-smart-access-gateway-client-users（APP 用户列表——第 11 项）。
  2. 仍必须调用地域级 APIs：describe-cloud-connect-networks、describe-acls、describe-qoses、describe-flow-logs。
  3. 必须跳过所有设备级 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. 任何调用均不得传入 --smart-ag-sn（sag-software 的 SN 字段为空）。

Contract C — 关键规则要点（详细 8 行 bash 骨架与自检见 [references/contract-skeletons.md § Contract C](references/contract-skeletons.md#contract-c--sag-software-client-query-skip-device-level)）：

  • 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 条独立执行，禁止 && / ; / || 拼接。
  • 自检：所有产物文件非空 + 无 not a valid api 错误（PascalCase 检测）。

Contract D——完整健康巡检（10 项）

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

Contract D 10 行 bash 骨架——仅用于「完整健康巡检 10 项」场景；⛔ 单实例 12 项配置查询请用上方 Contract A 12 行（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——参见“已知不可用的 APIs”）。

关键规则：

  1. API 必须 kebab-case：插件模式下 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. 唯一可正常跳过的例外：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 调用：

| 如果需要… | ❌ 不得使用 | ✅ 必须调用 | |---------------|-------------|-------------| | 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 调用失败时的处理闸门，详见 [contract-skeletons.md § 反模式](references/contract-skeletons.md#anti-pattern-field-reuse-substitutionexecution-blocking-rules)）：

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

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

强制自检模板（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 即视为契约执行失败，禁止用任何字段回退绕过断言。

模块 1：配置查询

根据用户请求执行查询。始终输出结构化摘要。

查询级别分类

查询分为两个级别。执行批量查询时，每个地域的地域级 APIs 仅调用一次，不得按实例调用：

地域级（每个地域查询一次，结果由该地域中的所有实例共享）：

  • #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（其中 设备级调用 按上述规则规避）
  • 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 规则）。

部分实例有主备双设备，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. 报告中按"主设备 / 备设备"分别展示结果。

可用的查询功能

| # | 功能 | 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 + 规则查询 | 规则：src/dst 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 | Top-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. 遵循查询层级：区域级 APIs（#5 CCN 列表、#6、#7、#9）每个区域仅调用一次
  6. 通过 CLI 调用对应的 API
  7. 以容错方式解析响应（参见 references/openapi-reference.md § 响应结构说明）
  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 — 完整健康巡检（行 199-212）。阈值与 Green/Yellow/Red 判定逻辑详见 [references/inspection-rules.md](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](references/status_inspection_template.py)
  3. 修改 [CUSTOMIZE] 部分以满足用户要求：
  • REPORT_OUTPUT_DIR → 用户的工作区路径
  • REGION_FILTER → "all" 或指定的地域列表
  • INSPECTION_ITEMS → "all" 或指定的巡检项编号（1-9）
  • THRESHOLDS → 如果用户指定了自定义阈值，则进行调整
  1. 将调整后的脚本写入工作区并执行
  2. 如果脚本执行失败：读取错误信息，修复相关函数，然后重试
  3. 在对话中提供关键发现，并附上已生成报告文件的链接

巡检报告模板

报告需包含摘要（正常/关注/严重项数）、严重问题表、关注项表、正常项列表、建议。详细报告模板与门阈说明见 [references/inspection-rules.md](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 报告之前必须执行三项强制数据清洗与自校验（详细 jq / date / awk 脚本见 [references/contract-skeletons.md § 数据清洗](references/contract-skeletons.md#data-sanitization--consistency-rules)）：

  1. 空值兜底 + 字段名探测：所有 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 中保留纪元时间原始值（需要原始数据另存 *_raw.csv）。
  3. 表头/明细一致性断言：Summary 声明的「共 X 个实例/X 个区域」必须与明细表实际行数严格一致；该数字必须由 wc -l/jq length 计算得到，禁止人肉估算；报告生成后的最后一步必须运行一致性断言，不一致则 exit 1。

错误处理

| 错误 | 原因 | 处理措施 | |-------|-------|--------| | InvalidRegionId | 地域错误 | 请用户确认地域，并列出常见的 SAG 地域 | | InvalidSmartAGId.NotFound | 实例在此地域中不存在 | 尝试其他地域，或请用户核实 | | 禁止访问 / NoPermission | RAM 权限策略不足 | 告知用户需要哪项权限（smartag:Describe*） | | 限流 | API 速率限制 | 等待，并按退避策略重试 | | MissingSmartAGSn | API 要求提供设备 SN，但未提供 | 跳过——实例未绑定物理设备 | | SmartAccessGatewayNotOnline | 设备已离线 | 记录状态，无法查询设备实时配置 | | Sag.DeviceNotExist | SN 不匹配，或未拆分多个 SN | 拆分以逗号分隔的 SN，并逐个重试 | | MissingSagId | describe-dnat-entries 参数有问题 | 使用 --sag-id 而不是 --smart-ag-id 作为此 API 的参数 | | InvalidApi.NotFound | 当前版本中可能不存在此 API | 妥善跳过，并在报告中注明 |

最佳实践

  1. 查询前对实例分类——跳过不适用的 APIs（sag-software 没有设备级查询）
  2. 执行设备级调用前拆分多个 SN——传入以逗号分隔的 SN 会导致 DeviceNotExist 错误
  3. 每个地域仅调用一次地域级 APIs——ACL/QoS/FlowLog/CCN 是共享资源，而非实例级资源
  4. 透明报告所有失败——禁止静默跳过；始终在报告中注明无法访问的内容及原因
  5. 禁止复用字段替代专用调用——禁止使用基础 describe-smart-access-gateways 响应中的字段（例如 AssociatedCcnId、AclIds 和 VpnStatus）来替代调用专用 API；基础响应是分类依据，而不是替代方案
  6. 将原始 JSON 保存到临时文件——将 CLI 响应重定向到 /tmp/sag_*.json（例如 aliyun smartag describe-xxx ... > /tmp/sag_<api>_<region>.json 2>&1），然后汇总特定字段；避免将完整的原始 JSON 直接输出到对话中

已知不可用的 APIs

以下 APIs 已知在当前 SAG API 版本（2018-03-13）中不可用。严禁调用它们——如果某个场景看似需要调用它们，必须在报告中明确声明：“API X 在当前版本中不可用；跳过此项”，或改用替代方案：

| API | 状态 | 替代方案 | |-----|--------|-------------| | describe-health-checks / describe-health-check-attribute | 返回 InvalidApi.NotFound | 跳过经典巡检中的第 10 项；在报告中注明 | | describe-sag-online-client-statistics | 返回 InvalidApi.NotFound | 使用 describe-smart-access-gateway-client-users 获取 APP 用户列表 |

参考链接

| 参考 | 说明 | |-----------|-------------| | [references/openapi-reference.md](references/openapi-reference.md) | 25+ 个 SAG APIs 的完整 OpenAPI 参数参考 | | [references/contract-skeletons.md](references/contract-skeletons.md) | 详细 bash 骨架、自检、数据清洗规则（Contract A/B/C/D + 反模式 + 数据清洗） | | [references/ram-policies.md](references/ram-policies.md) | 所需的 RAM 权限（28 个只读操作） |

qianwen skills install @aliyun/alibabacloud-smartag-pilot