/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** > ```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](https://ram.console.aliyun.com/manage/ak) > 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](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` 实例**询问配置（含「这个网关的配置」「看一下