Diagnose whether the enterprise network path through the SASE cluster to office applications is connected, providing link-level visibility and problem localization.
Architecture: SASE Client → POP Entry Point → Connector/CEN/VPN → VPC → Origin Server
Diagnosis Types
Type
Description
Use Case
FullLink
Diagnose the full path: Endpoint → POP → Origin
Troubleshoot end-to-end connectivity issues
Application
Diagnose POP → Origin path only
Troubleshoot SASE cluster to origin network issues
Limitations
The following features cannot be implemented via CLI or SDK and require the SASE Console:
Feature
Reason
Workaround
Visual link diagram
Console-only UI feature
Analyze NetworkLinkInfo JSON data from API response
Delete diagnosis task
No public API available
Operate in Console: Private Access > Network Diagnosis
Retry diagnosis task
No public API available
Re-create a new task with the same parameters
List diagnosis tasks
No list API available
Record DiagnoseId and query individually
SASE App version check
Client-side capability
Ensure SASE App >= 4.4.1
Diagnosis task concurrency limit
Max 5 concurrent running tasks
Wait and retry on DiagnosisTask.NumberExceedsLimit error
Prerequisites
SASE App version >= 4.4.1
Network tunnel established (VPC/CEN/Connector/VPN)
Office application added and zero-trust policy configured
Installation
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: Aliyun CLI plugin update required
[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.
bash
aliyun configure set --auto-plugin-install true
aliyun plugin update
CLI invocation rule: Use Aliyun CLI plugin mode only. Commands MUST use lowercase kebab-case actions and parameters, for example aliyun csas create-pa-diagnosis-task --diagnose-type FullLink ....
Do NOT use PascalCase OpenAPI action names in CLI invocations, and do NOT use --force generic mode for these diagnosis APIs.
Environment Variables
No skill-specific environment variables are required. Use an existing Aliyun CLI credential profile and verify it with aliyun configure list.
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).
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
Read references/ram-policies.md to get the full list of permissions required by this SKILL
Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
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, instance names, CIDR blocks,
passwords, domain names, resource specifications, etc.) MUST be confirmed with the
user. Do NOT assume or use default values without explicit user approval.
Parameter Name
Required/Optional
Description
Default Value
--diagnose-type
Required
Diagnosis type: FullLink / Application
—
--host
Required
Target address (IP or domain)
—
--port
Required
Target port
—
--protocol
Required
Protocol: TCP / UDP
—
--username
Conditional
Username (required for FullLink)
—
--dev-tag
Conditional
Device ID (required for FullLink)
—
--user-group-id
Conditional
User group ID (required for Application)
—
--pop-mode
Required
POP selection mode: AutoSelect / ManualSelect
—
--pop-id
Conditional
POP entry point ID (required when --pop-mode ManualSelect)
—
--udp-extra-configs
Optional
UDP probe config object, for example RequestContent=<request_content> ExpectedResponse=<expected_response>
—
Core Workflow
[MUST] Enable AI-Mode at the start of Core Workflow (before any CLI invocation):
AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation in this skill:
[MUST] Disable AI-Mode at EVERY exit point:
Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
bash
aliyun configure ai-mode disable
CLI invocation rule: Use plugin mode commands only: create-pa-diagnosis-task, get-pa-diagnosis-task, and list-user-devices.
Do not use PascalCase API names or --force generic mode.
Task 0: Query User Device DevTag (FullLink prerequisite)
FullLink diagnosis requires DevTag (device ID), but users typically only know the username or hostname.
Use list-user-devices to query the device list and filter for eligible devices to obtain DeviceTag.
Device selection criteria (ALL must be satisfied):
Version check: The API does not support filtering by version. Check the AppVersion field in results to verify >= 4.4.1.
If the version does not meet requirements, prompt the user to upgrade SASE App first.
Multiple devices handling: A user may have multiple devices; the result is a list.
If only 1 device with a valid version, use its DeviceTag directly
If multiple devices, display the list and ask the user to confirm which device to use
If no eligible devices found, inform the user to check: device online status, device type support, and version compliance
[IMPORTANT] Diagnosis task concurrency limit is 5. When the number of running tasks reaches the limit, create-pa-diagnosis-task returns the following error:
text
ErrorCode: DiagnosisTask.NumberExceedsLimit
Message: The number of running diagnosis tasks exceeds the limit of 5.
Please wait for the tasks to complete.
When this error occurs, use bounded incremental backoff and retry:
Retry task creation up to 5 times.
Wait longer before each retry: 30 seconds, 60 seconds, 90 seconds, 120 seconds, then 150 seconds.
If any retry succeeds, extract DiagnoseId and continue to polling. Do not skip the polling and result analysis steps after a successful create.
If all 5 retries fail, clearly tell the user that the SASE diagnosis concurrency limit is still full. Ask the user to open the SASE Console and manually end idle diagnosis tasks, or confirm whether to retry with another --diagnose-type (FullLink <-> Application) after providing the parameters required by that diagnosis type.
If the user cannot clear tasks or switch diagnosis type, run aliyun configure ai-mode disable and terminate the current workflow.
Note: Do NOT expose the raw error message to the user. Instead, explain: "Other diagnosis tasks are currently running and the concurrency limit (5) has been reached. Waiting and retrying..."
Poll manually with a bounded loop until Status contains Finished or Failed.
The CLI output may contain quotes, whitespace, or line breaks, so do not rely on exact string equality.
bash
MAX_POLLS=20
POLL_INTERVAL=10
POLL_COUNT=0
STATUS=""
while [ "$POLL_COUNT" -lt "$MAX_POLLS" ]; do
sleep "$POLL_INTERVAL"
POLL_COUNT=$((POLL_COUNT + 1))
STATUS=$(aliyun csas get-pa-diagnosis-task \
--diagnose-id <diagnose_id> \
--cli-query 'DiagnosisTask.Status' --quiet 2>/dev/null | tr -d '[:space:]"')
echo "Current status: $STATUS"
if echo "$STATUS" | grep -qE 'Finished|Failed'; then
break
fi
done
if ! echo "$STATUS" | grep -qE 'Finished|Failed'; then
echo "Polling timed out after $((MAX_POLLS * POLL_INTERVAL)) seconds; retrieve the full task result once and explain that the task may still be running or status parsing failed."
fi
Polling safety: Never poll more than MAX_POLLS times in one workflow. If polling times out, retrieve the full task result once with get-pa-diagnosis-task, summarize the current status, then stop or ask the user whether to continue waiting.
Task 5: Retrieve Full Diagnosis Result and Analyze
[IMPORTANT] Must retrieve the complete result before performing comprehensive analysis.
The Success field only indicates whether the diagnosis task itself completed normally — it does NOT indicate whether the network link is healthy.
Actual network issue information is distributed across NetworkLinkInfo.Nodes, NetworkLinkInfo.Links, PolicyInfo, and other fields.
Example: Success=true but a Node has Success=false with Error containing zero-trust policy block info means the diagnosis process ran fine but the network is actually blocked.
Step 1: Retrieve the full diagnosis result (single call to get all fields):
Step 2: Comprehensively analyze the following fields from the full result:
Field Path
Meaning
Analysis Points
DiagnosisTask.Status
Task status
Must be Finished; Failed means diagnosis itself errored
DiagnosisTask.Result.Success
Whether diagnosis flow completed
true only means the diagnosis process executed normally
DiagnosisTask.Result.ErrorMessage
Diagnosis-level error
Non-empty indicates diagnosis process error
DiagnosisTask.Result.NetworkLinkInfo.Nodes
Status of each network node
Check each Node's Success and Error fields to locate which link segment has issues
DiagnosisTask.Result.NetworkLinkInfo.Links
Inter-node link connectivity
Check each Link's status
DiagnosisTask.Result.NetworkLinkInfo.Dns
DNS resolution result
Verify domain resolves correctly
DiagnosisTask.Result.PolicyInfo
Zero-trust policy match
Check if policy allows access, block reason
Analysis principle: Even when Success=true, you MUST iterate through every Node's Success and Error fields in Nodes.
When a node-level Success=false with non-empty Error, explain the specific issue for that link segment to the user (e.g., policy block, connection timeout, etc.).
