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 — Agent Skill 执行需要 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 身份）。

如果不存在有效配置，请在此处停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在此会话之外配置凭证（在终端中使用 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并重新运行，直至 aliyun configure list 显示有效配置

RAM 策略

此技能需要 SAG 只读权限。完整的 JSON 策略请参阅 references/ram-policies.md。

[MUST] 权限失败处理： 执行期间，任何命令或 API 调用因权限错误而失败时，都必须遵循以下流程：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose 技能指导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

参数确认

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

参数	必填	说明	默认值
RegionId	是	目标地域，或用于完整扫描的“所有地域”	cn-shanghai
SmartAGId	条件必填	SAG 实例 ID（sag-xxxxx）。“所有实例”查询无需此项	—
Query Scope	是	要执行的模块/功能	所有适用项
Output Format	否	对话摘要和/或报告文件	两者

地域发现

查询所有地域时，始终从以下内容开始：

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 调用。

约定 A — 单实例完整配置查询

触发条件：用户询问某个具体 sag-xxx 实例的配置（包括「这个网关的配置」「看一下 xxx 的配置」「完整配置」「全部配置」「WAN/路由/DNAT 都查」「换网后对一下配置」「配置有没有问题」「检查 xxx 配置」等；即使同时提到「巡检/诊断/检查」，仍属于此场景，⛔ 严禁误用约定 D）。

必须调用以下全部 12 个 API（仅当实例为 sag-software 时，才跳过设备级 API——参见约定 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（区域级）
A10	describe-acls	ACL（区域级）
A11	describe-qoses	QoS（区域级）
A12	describe-sag-current-dns	设备级，需要 --smart-ag-sn

约定 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，按约定 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. 禁止串联：❌ 严禁使用 && / ; / || / | 拼接命令；每条 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. 自检：12 条调用完成后，必须运行 Self-check 断言，确保所有产物文件都非空；缺少任一文件即 exit 1。

约定 A 的 12 行 bash 骨架——仅用于「单实例 12 项完整配置查询」场景；⛔ 禁止与下方约定 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 — 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 无命中。

反模式：字段复用替代

❌ 绝对不要使用 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 § Anti-Pattern）：

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：配置查询

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

查询级别分类

查询分为两个级别。执行批量查询时，每个区域的区域级 API 仅调用一次，而非每个实例调用一次：

区域级（每个区域查询一次，结果供该区域内的所有实例共用）：

• #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；遇到这种情况，以 region unsupported 的形式跳过该项，不中断全局巡检

多 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 + 规则查询	规则：源/目标 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. 遵守查询级别：区域级 API（#5 CCN 列表、#6、#7、#9）每个区域仅调用一次
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. 在对话中展示关键发现，并提供生成的报告文件链接

巡检报告模板

报告需包含摘要（Normal/Attention/Critical 项数）、Critical Issues 表、Attention Items 表、Normal Items 列表和建议。详细报告模板与门限说明见 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 § 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.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 使用 --sag-id，而非 --smart-ag-id
InvalidApi.NotFound	当前版本中可能不存在此 API	妥善跳过，并在报告中说明

最佳实践

1. 查询前先对实例分类——跳过不适用的 API（sag-software 没有设备级查询）
2. 设备级调用前拆分多个 SN——传入逗号分隔的 SN 会导致 DeviceNotExist 错误
3. 区域级 API 每个区域调用一次——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——如果某种情况似乎需要调用它们，必须在报告中明确声明：「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	25+ 个 SAG API 的完整 OpenAPI 参数参考
references/contract-skeletons.md	详细 bash 骨架、Self-check、数据清洗规则（Contract A/B/C/D + Anti-Pattern + Sanitization）
references/ram-policies.md	必需的 RAM 权限（28 个只读操作）