Alibabacloud Pai Workspace Manage

PAI Workspace Management

Create, query, and list workspaces on Alibaba Cloud Platform for AI (PAI). Workspaces serve as isolated management units for AI model training, data processing, and related tasks.

Architecture: PAI AIWorkSpace (Workspace)

Workspace Modes:

• Simple Mode: Production environment only (prod)
• Standard Mode: Development (dev) + Production (prod) environments

---

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.

Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

Then [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

aliyun version
aliyun configure set --auto-plugin-install true
aliyun plugin update

---

Credential Verification

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

>

Sensitive Data Masking:

- The following fields in API responses contain personally identifiable information and MUST be masked before displaying to the user:

- Owner.UserId / Creator — Show only last 4 digits, e.g., ****1234

- Owner.UserKp — Never display, omit entirely

- Owner.UserName / Owner.DisplayName — Show only first character + ***, e.g., z***

- Accounts in AdminNames — Mask as u***@example.com format

- [MUST] Raw sensitive data MUST NOT appear in stdout, execution logs, on disk, or in the conversation: The execution framework logs ALL command stdout to execution logs/transcripts (e.g., ran-scripts/executed-actions.log). Therefore, EVERY execution of get-workspace or list-workspaces (including basic queries without --verbose) must include | jq -r pipe filtering — because Creator is always returned and is sensitive. There must be NO execution step where the raw API JSON appears in command output, even as an intermediate step. The | jq -r pipe must be part of a single pipeline command:

>

Basic query (without --verbose):

```bash

aliyun aiworkspace get-workspace --workspace-id <ID> --region <RegionId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage \

| jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))

Status: \(.Status)

Environment: \(.EnvTypes | join(", "))

Created: \(.GmtCreateTime)

Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)"'

```

>

Verbose query (with --verbose true):

```bash

aliyun aiworkspace get-workspace --workspace-id <ID> --verbose true --region <RegionId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage \

| jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))

Status: \(.Status)

Owner: \(.Owner.UserName // "" | if length > 0 then .[0:1] + "*" else "N/A" end) (ID: \(.Owner.UserId // "" | if length > 0 then "**" + .[-4:] else "N/A" end))

Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)

Administrators: \(.AdminNames // [] | map(.[0:1] + "***") | join(", "))"'

```

>

The raw API response flows through the pipe internally and never reaches shell stdout. Only jq's output (with masked values and natural language keys) is captured by the execution framework. The following are all prohibited:

- Running the CLI command without | jq pipe filtering — even for basic queries (the Creator field is always returned and sensitive)

- Two-step processing — running the CLI command first to get raw output, then separately masking it. The raw JSON would appear in the execution transcript before masking is applied. The | jq -r MUST be part of the same single pipeline command

- Capturing raw output to shell variables — e.g., response=$(aliyun ...) then echo "$response" | jq .... The variable assignment captures raw data into the execution log

- Output redirection (> file.json, >> file.log, | tee file)

- Executing commands via shell scripts saved to disk (e.g., ran-scripts/*.sh)

- Embedding raw API response data in any script or code file — e.g., writing a Python/shell script that contains raw JSON values as string literals, variables, or data structures (such as ran_scripts/process_workspace_data.py). All data processing must be done entirely within the | jq -r pipe; do NOT create intermediate processing scripts that contain raw data

- Displaying raw JSON snippets in the conversation

- [MUST] Original API field names MUST NOT be used as output keys: Even when values are masked, using original API field names (such as UserId, UserName, UserKp, AdminNames) as JSON keys or structured output key names in any output (conversation or files) is prohibited. Use natural language key names instead:

- UserId / Creator → Owner ID or Creator ID

- UserName → Username

- DisplayName → Display Name

- AdminNames → Administrators

>

Correct approach: EVERY execution of get-workspace or list-workspaces must be a single pipeline command with | jq -r appended. The Agent must NEVER run the CLI command first and then process the output in a separate step — the raw JSON would appear in the execution transcript before masking is applied. All data extraction, masking, and formatting must happen inside the jq filter. If saving to a file, redirect the jq output (not the CLI output) using > file.md at the end of the pipeline. This rule applies to ALL queries — basic, verbose, and list.

>

```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 Permissions

See references/ram-policies.md for required permissions (including Policy JSON and instructions).

[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, WorkspaceName, Description, EnvTypes, etc.)

MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Note: Once --resource-group-id is set, it cannot be modified via CLI/code. To change it, use the console or recreate the workspace.

---

Timeout Configuration

API calls support timeout configuration (in seconds):

Option 1: Command-line parameters (applies to the current command only):

• --connect-timeout <seconds> — Connection timeout
• --read-timeout <seconds> — I/O read timeout

Option 2: Persistent configuration (applies globally, written to current profile):

aliyun configure set --connect-timeout 10 --read-timeout 30

Command-line parameters take precedence over persistent configuration. If not set, the CLI uses built-in defaults. When encountering timeout or context deadline exceeded errors, increase --read-timeout (e.g., 30-60 seconds).

---

Core Workflow

See references/related-commands.md for all CLI command templates and parameter details.

Prerequisite: Region Selection and PAI Activation Check

[MUST] Do not use a default region: The Agent must not assume or use a default region. It must explicitly ask the user which region to use.

>

[MUST] Check PAI activation on first use of a region: After the user specifies a region (or the first time a region is used in a session), the Agent must call list-products to check whether PAI is activated in that region before executing any subsequent workspace operations.

Step 1: Confirm Region

Ask the user which region to use. If the user has not specified one, provide the list of common regions for selection (see the Common Region IDs table in references/related-commands.md). Do not automatically select a default region.

Step 2: Check PAI Activation Status

Use aliyun aiworkspace list-products to check whether PAI and its dependent products are activated in the user-specified region:

aliyun aiworkspace list-products \
  --region <UserSpecifiedRegionId> \
  --product-codes PAI_share \
  --verbose true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Step 3: Handle Check Results

Inspect the returned Products array for the matching product entry:

Decision logic:

>

1. `IsPurchased == true` → PAI is activated, proceed with subsequent workflows

2. `IsPurchased == false` → PAI is not activated, guide the user to activate:

- Check the HasPermissionToPurchase field:

- true → User has permission. Show the PurchaseUrl link and prompt the user to complete activation in the console before continuing

- false → User lacks permission (requires the primary account or a RAM user with pai:CreateOrder permission). Inform the user to contact the primary account administrator

- Do not proceed with creating/querying workspaces when PAI is not activated

Workflow 1: Create Workspace (CreateWorkspace)

Use aliyun aiworkspace create-workspace to create a workspace. Required parameters: --region, --workspace-name, --description, --env-types. Simple mode uses --env-types prod, standard mode uses --env-types dev prod. Optionally add --display-name and --resource-group-id.

Step 1: Input Parameter Validation

[MUST] Parameter format validation: Before calling the API, the Agent must validate user-provided parameters as follows. If validation fails, prompt the user to correct the input. Do not submit non-compliant parameters:

>

| Parameter | Validation Rules | Example |

|-----------|-----------------|---------|

| --workspace-name | 3-23 characters, must start with a letter, may only contain letters, digits, and underscores (_). Hyphens (-), spaces, Chinese characters, and other special characters are not allowed | my_workspace_01 |

| --description | Max 80 characters, wrap with quotes if containing special characters | "My AI workspace" |

| --env-types | Must be prod or dev prod, list format | prod |

| --display-name | Optional, no strict format restrictions | My Workspace |

Step 2: Name Existence Check (check-then-act idempotency pattern)

[MUST] Idempotency guarantee: The CreateWorkspace API does not support ClientToken, so idempotency is ensured via a check-then-act pattern. Before creating, you must call list-workspaces --option CheckWorkspaceExists --workspace-name <name> to check if the name already exists.

>

Decision logic:

- TotalCount == 0 → Name is available, proceed to Step 3 to create

- TotalCount >= 1 → Name already exists, perform the following:

1. Extract the existing WorkspaceId from the returned Workspaces[0]

2. Call get-workspace --workspace-id <id> to get full details

3. Compare the existing workspace's key parameters (EnvTypes, Description, etc.) with the current request parameters

4. Match → Treat as already created, return the existing WorkspaceId directly, do not recreate

5. Mismatch → Inform the user that the name is already taken with a different configuration, ask the user to choose a different name

Step 3: Execute Creation

After parameter validation passes and the name does not exist, execute the create-workspace command. On success, a WorkspaceId is returned. If the creation returns a WorkspaceNameAlreadyExists error (concurrent scenario), handle it using the TotalCount >= 1 logic from Step 2.

Workflow 2: Get Workspace Details (GetWorkspace)

[MUST] Single workspace queries must use `get-workspace`: When querying the details of one specific workspace, you must use aliyun aiworkspace get-workspace --workspace-id <id>. Do not use list-workspaces --workspace-ids as a substitute. get-workspace calls the GetWorkspace API and returns the complete details of a single workspace.

Only accepts --workspace-id (required) and --verbose (optional). The region is specified via the global --region parameter. A Status of ENABLED indicates the workspace is ready.

[MUST] `--verbose true` trigger rules: --verbose true returns Owner (UserKp, UserId, UserName, DisplayName) and AdminNames (admin account list). The Agent must follow these rules:

>

1. Trigger conditions — When the user's request involves any of the following keywords, --verbose true must be appended when constructing the command (determined before calling the API, not dependent on API success):

- Chinese keywords: 所有者, 拥有者, 创建者, 管理员, 负责人, 归属

- English keywords: owner, admin, administrator, verbose

- Field names: Owner, AdminNames

2. When not triggered — When the user only queries basic info (status, environment types, etc.), do not append --verbose

3. Masking rules — UserId/Creator: last 4 digits only (****1234); UserKp: omit entirely; UserName/DisplayName: first character only (z***); AdminNames entries: u***@example.com

4. No raw sensitive data in stdout, execution logs, on disk, or in output — EVERY execution of get-workspace (with or without --verbose) or list-workspaces must be a single pipeline command with | jq -r appended. The Agent must NEVER run the CLI command first and then mask the output separately — the raw JSON would appear in the execution transcript. No two-step processing, no variable capture (response=$(aliyun ...)), no intermediate scripts. All masking must happen inside the jq filter of the same pipeline. See the Sensitive Data Masking section and references/related-commands.md for templates

[MUST] 404 error handling: When get-workspace returns StatusCode: 404, Code: 100400027, Message: Workspace not exists, the workspace ID does not exist. The Agent must directly report to the user that the workspace does not exist, including the original workspace-id specified by the user. Do not fall back to list-workspaces or other APIs to try to "find" the workspace after receiving a 404. Do not silently ignore the error. If the user subsequently provides a new workspace-id, the Agent must retry get-workspace with the same parameters as the initial call (including --verbose true, etc.).

Workflow 3: List Workspaces (ListWorkspaces)

Use aliyun aiworkspace list-workspaces to list workspaces. Supports the following filter and sort parameters:

• --workspace-name <name> — Fuzzy match by name
• --workspace-ids <id1,id2,...> — Batch query by ID list, comma-separated (e.g., --workspace-ids "123,456,789")
• --status <STATUS> — Filter by status, enum values (all uppercase): ENABLED | INITIALIZING | FAILURE | DISABLED | FROZEN | UPDATING
• --sort-by <Field> — Sort field (case-sensitive): GmtCreateTime (default) | GmtModifiedTime
• --order <ORDER> — Sort direction (all uppercase): ASC (default) | DESC
• --page-number <n> / --page-size <n> — Pagination parameters
• --option GetResourceLimits — Get resource limit information instead of workspace list
• --option CheckWorkspaceExists — Check if a workspace with the specified name already exists (pre-creation check, use with --workspace-name)

[MUST] API selection rules: Use get-workspace --workspace-id (GetWorkspace API) for querying a single ID; use list-workspaces --workspace-ids "id1,id2,..." for querying multiple IDs (2 or more) in a single batch query (ListWorkspaces API). Do not call get-workspace individually for each ID.

>

[MUST] Batch query results are final: The Workspaces array returned by list-workspaces --workspace-ids already contains complete information for each workspace (Status, EnvTypes, GmtCreateTime, etc.). Do not call get-workspace for any ID in the batch results to get additional details. If some IDs are not in the response, those IDs do not exist — report this to the user directly.

[MUST] Enum values are case-sensitive: --sort-by must be GmtCreateTime or GmtModifiedTime (camelCase), --order must be ASC or DESC (all uppercase), --status must be all uppercase like ENABLED. Using incorrect casing (e.g., desc, gmtCreateTime, enabled) will cause API errors or unexpected results.

[MUST] ListWorkspaces sensitive field masking: Each workspace object returned by list-workspaces always contains Creator (creator user ID) and AdminNames (admin account list) — no `--verbose true` needed. The Agent must mask these fields when displaying (Creator: last 4 digits only; AdminNames: first character + ***). Do not output JSON containing the raw values, and do not save raw responses to files via redirection (> file) or scripts.

---

Success Verification

See references/verification-method.md for detailed verification methods

---

Cleanup (Delete Workspace)

Warning: Deleting a workspace is an irreversible operation that removes all resources within it. Proceed with caution.

>

Note: Workspace deletion cannot be performed directly via CLI (the aiworkspace plugin does not currently support delete-workspace). Use the following methods:

1. Console deletion: Log in to PAI Console -> Workspace List -> Select workspace -> Delete

2. API call: Use the DELETE /api/v1/workspaces/{WorkspaceId} endpoint (via SDK or direct HTTP call)

---

Best Practices

1. Naming conventions: Use project names or team identifier prefixes for WorkspaceName, e.g., nlp_prod, cv_dev (note: hyphens are not supported, use underscores) 2. Environment selection: Use standard mode (dev + prod) for production projects to separate development and production resources 3. Description: Description should indicate the purpose, team, or project for easier management 4. Region selection: Choose the region closest to your data storage to minimize data transfer latency 5. Resource group management: Use different resource groups for multi-project scenarios to facilitate cost allocation and permission management 6. DisplayName: Use business-friendly names as the display name while using English identifiers for WorkspaceName

---

Reference Documentation

Acceptance Criteria — alibabacloud-pai-workspace-manage

Scenario: Create, query, and list PAI workspaces Purpose: Skill testing acceptance criteria to ensure CLI commands and parameter patterns are correct

---

General Rules

1. Product Name

CORRECT

aliyun aiworkspace <action> ...

INCORRECT

aliyun AIWorkSpace CreateWorkspace ...   # Traditional API format, not plugin mode
aliyun paiworkspace create-workspace ... # Incorrect product name
aliyun pai create-workspace ...          # Incorrect product name

2. Action Format

CORRECT — kebab-case plugin mode

create-workspace | get-workspace | list-workspaces

INCORRECT

CreateWorkspace   # PascalCase
createWorkspace   # camelCase

3. Region Parameter

CORRECT — global parameter --region

--region cn-hangzhou

INCORRECT

--region-id cn-hangzhou   # Non-existent parameter name

3a. Region Selection — Do Not Use Default Region

CRITICAL: The Agent must not assume or use a default region. The user must explicitly specify the region.

CORRECT — Ask the user and use their specified region

Agent: "Please select a region (e.g., cn-hangzhou, cn-shanghai, cn-beijing)"
User: "cn-shanghai"
Agent: Uses --region cn-shanghai

INCORRECT — Automatically use a default region

# Prohibited: Auto-selecting cn-hangzhou or any default value when user has not specified a region
aliyun aiworkspace create-workspace --region cn-hangzhou ...
# Must ask the user which region to use first

3b. PAI Activation Check — Must Check on First Use of a Region

CRITICAL: After the user specifies a region (or the first time a region is used in a session), the Agent must call list-products to check whether PAI is activated before executing any workspace operations.

CORRECT — Check activation status before executing operations

# Step 1: User specifies region
User: "Create a workspace in cn-shanghai"

# Step 2: Check PAI activation status
aliyun aiworkspace list-products --region cn-shanghai --product-codes PAI_share --verbose true --user-agent AlibabaCloud-Agent-Skills

# Step 3a: IsPurchased == true → Proceed with subsequent operations
aliyun aiworkspace create-workspace --region cn-shanghai ...

# Step 3b: IsPurchased == false, HasPermissionToPurchase == true → Guide user to activate
Agent: "PAI is not activated in this region. Please visit the following link to activate: <PurchaseUrl>"

# Step 3c: IsPurchased == false, HasPermissionToPurchase == false → Inform user
Agent: "PAI is not activated in this region, and the current account lacks permission to activate. Please contact the primary account administrator (requires primary account or pai:CreateOrder permission)"

INCORRECT — Skip activation check and execute operations directly

# Prohibited: Creating/querying workspaces without checking PAI activation status
User: "Create a workspace in cn-shanghai"
aliyun aiworkspace create-workspace --region cn-shanghai ...
# Must call list-products to check if PAI is activated first

INCORRECT — Continue executing operations when PAI is not activated

# Prohibited: Continuing operations after list-products returns IsPurchased == false
aliyun aiworkspace list-products --region cn-shanghai --product-codes PAI_share --verbose true ...
# Returns: IsPurchased: false
aliyun aiworkspace create-workspace --region cn-shanghai ...
# Prohibited: Must wait for user to confirm activation before continuing

4. user-agent Identifier

Every aliyun command must include:

--user-agent AlibabaCloud-Agent-Skills

---

CreateWorkspace Acceptance

5. EnvTypes Format — list format, not JSON array

CORRECT

--env-types prod           # Simple mode
--env-types dev prod       # Standard mode

INCORRECT

--env-types '["prod"]'        # JSON array format
--env-types '["dev","prod"]'  # JSON array format
--env-types "prod"            # Unnecessary quotes

6. Parameter Names — kebab-case

CORRECT

--workspace-name | --description | --env-types | --display-name | --resource-group-id

INCORRECT

--WorkspaceName | --workspaceName | --EnvTypes | --env_types

7. WorkspaceName Value Rules — Input Validation

CRITICAL: The Agent must validate the WorkspaceName format before calling the API. If validation fails, prompt the user to correct the input. Do not submit non-compliant parameters.

Rules: 3-23 characters, must start with a letter, may only contain letters, digits, and underscores (_).

CORRECT

myworkspace | my_workspace | myWorkspace123 | abc

INCORRECT — Agent must reject the following inputs and prompt user to correct

123workspace        # Starts with a digit
_myworkspace        # Starts with an underscore
my-workspace        # Contains hyphen (not allowed)
ab                  # Less than 3 characters
averylongworkspacename123  # Exceeds 23 characters
my workspace        # Contains space (not allowed)
test@ws!            # Contains special characters (not allowed)

8. Description Length — Input Validation

The Agent must check that Description length does not exceed 80 characters before calling the API. If it exceeds, prompt the user to shorten it. Wrap parameter values with quotes when they contain special characters.

8a. Pre-creation Name Existence Check

CRITICAL: Before creating a workspace, you must call list-workspaces --option CheckWorkspaceExists --workspace-name <name> to check if the name already exists.

CORRECT — Check name before creating

# Step 1: Check name
aliyun aiworkspace list-workspaces --region cn-hangzhou --option CheckWorkspaceExists --workspace-name myworkspace --user-agent AlibabaCloud-Agent-Skills
# Returns TotalCount == 0 → Name is available
# Step 2: Create
aliyun aiworkspace create-workspace --region cn-hangzhou --workspace-name myworkspace ...

INCORRECT — Create without checking

# Prohibited: Skipping name check and creating directly
aliyun aiworkspace create-workspace --region cn-hangzhou --workspace-name myworkspace ...

9. Success Response

{"RequestId": "xxx", "WorkspaceId": "1234"}

Verification: WorkspaceId is not empty.

10. Common Errors

10a. Idempotency Guarantee (check-then-act pattern)

CRITICAL: The CreateWorkspace API does not support ClientToken. The Agent must ensure idempotency via the check-then-act pattern to avoid duplicate creation.

CORRECT — Reuse when name exists and configuration matches

# Step 1: CheckWorkspaceExists returns TotalCount >= 1
# Step 2: Call get-workspace to get existing workspace details
# Step 3: Compare EnvTypes, Description, and other parameters — they match the current request
# Step 4: Return existing WorkspaceId directly, do not recreate
Agent behavior: "Workspace 'myworkspace' already exists (ID: 1234), configuration matches, no need to recreate"

CORRECT — Prompt when name exists but configuration differs

Agent behavior: "Name 'myworkspace' is already taken (ID: 1234), but EnvTypes differ (existing: prod, requested: dev prod). Please choose a different name"

CORRECT — Received WorkspaceNameAlreadyExists error during creation

# Concurrent scenario: Did not exist during check, conflict during creation
# Agent should handle using TotalCount >= 1 logic: query existing workspace and compare parameters

INCORRECT — Create again directly when name already exists

# Prohibited: Calling create-workspace without checking, causing duplicate creation or errors

---

GetWorkspace Acceptance

11. API Selection Rules — Single ID Must Use GetWorkspace

CRITICAL: When querying a single workspace, you must use get-workspace --workspace-id (GetWorkspace API). Do not use list-workspaces --workspace-ids as a substitute. list-workspaces --workspace-ids is only for querying multiple IDs (2 or more) in batch scenarios.

CORRECT — Single ID uses get-workspace

aliyun aiworkspace get-workspace --workspace-id <WorkspaceId> --user-agent AlibabaCloud-Agent-Skills

INCORRECT — Single ID uses list-workspaces

aliyun aiworkspace list-workspaces --workspace-ids "<WorkspaceId>" --user-agent AlibabaCloud-Agent-Skills
# Prohibited: Single ID queries must not use list-workspaces --workspace-ids instead of get-workspace

12. Parameter Constraints

Only accepts --workspace-id (required) and --verbose (optional). No other action-specific parameters.

CORRECT

--workspace-id 1234
--workspace-id 1234 --verbose true

INCORRECT

--region-id cn-hangzhou --workspace-id 1234   # --region-id parameter does not exist
--WorkspaceId 1234                            # PascalCase format
--workspace_id 1234                           # Underscore format

13. Success Response

Status of ENABLED indicates the workspace is operational. WorkspaceId should match the query parameter.

13a. 404 Error Handling — Workspace Does Not Exist

CRITICAL: When get-workspace returns StatusCode: 404, Code: 100400027, Message: Workspace not exists, the Agent must directly report to the user that the workspace ID does not exist. Do not fall back to list-workspaces or other APIs to try to find the workspace after receiving a 404.

>

Parameter preservation: If the user subsequently provides a new workspace-id, the Agent must retry get-workspace with the same parameters as the initial call (including --verbose true, etc.).

CORRECT — Report not found directly after receiving 404

Call: aliyun aiworkspace get-workspace --workspace-id <ID> --verbose true --user-agent AlibabaCloud-Agent-Skills
Result: 404 Workspace not exists <ID>
Agent behavior: Report to user "Workspace <ID> does not exist"

CORRECT — Preserve original parameters when user provides a new ID (including --verbose true)

# After initial call returns 404, user provides a new workspace-id
# Agent must retry get-workspace with the same parameters as the initial call
Call: aliyun aiworkspace get-workspace --workspace-id <NewID> --verbose true --user-agent AlibabaCloud-Agent-Skills
# --verbose true and other parameters must be preserved, must not be dropped when ID changes

INCORRECT — Lose original parameters after user corrects ID

# Initial call: get-workspace --workspace-id <ID> --verbose true → 404
# After user correction: get-workspace --workspace-id <NewID> → 200 (missing --verbose true)
# Prohibited: User's original request included owner/admin query intent, --verbose true must be preserved after ID correction

INCORRECT — Fall back to other APIs after receiving 404

Call: aliyun aiworkspace get-workspace --workspace-id <ID> ...  → 404
Then: aliyun aiworkspace list-workspaces --region cn-hangzhou ...  → Lists all workspaces
# Prohibited: Must not use ListWorkspaces to try to find the workspace after GetWorkspace 404

13b. --verbose true Trigger Rules and Sensitive Data Masking

CRITICAL: --verbose true returns Owner (containing UserKp, UserId, UserName, DisplayName) and AdminNames, which contain PII. The Agent must correctly identify trigger conditions and mask all sensitive data while prohibiting raw JSON output.

Trigger Conditions

When the user's request involves any of the following keywords, --verbose true must be appended when constructing the command (determined before calling the API, not dependent on API success):

• Chinese keywords: 所有者, 拥有者, 创建者, 管理员, 负责人, 归属
• English keywords: owner, admin, administrator, verbose
• Field names: Owner, AdminNames

Output Format Requirements

• Do not output raw JSON containing "UserId", "UserName", "UserKp", or "AdminNames" key names in the conversation or files
• Must parse the API-returned JSON, mask sensitive values, then present in natural language or table format
• The Creator field (always returned) also contains a user ID and must be masked when displayed (last 4 digits only)

CORRECT — Use --verbose true and display with masking when user requests owner/admin info

User: "Show the owner and admin info for workspace <ID>"

# Must pipe through jq -r to prevent raw data from reaching stdout/execution logs
aliyun aiworkspace get-workspace \
  --workspace-id <ID> \
  --verbose true \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills \
  | jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))
Status: \(.Status)
Owner: \(.Owner.UserName // "" | if length > 0 then .[0:1] + "***" else "N/A" end) (ID: \(.Owner.UserId // "" | if length > 0 then "****" + .[-4:] else "N/A" end))
Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)
Administrators: \(.AdminNames // [] | map(.[0:1] + "***") | join(", "))"'

# Output (natural language, only masked values):
#   Workspace: myworkspace (ID: 12345)
#   Status: ENABLED
#   Owner: z*** (ID: ****7890)
#   Creator ID: ****7890
#   Administrators: a***, b***

CORRECT — Do not add --verbose when user does not request Owner/Admin (but still pipe through jq)

User: "Check the status of workspace <ID>"
# Even basic queries return Creator (sensitive), so | jq -r is always required
aliyun aiworkspace get-workspace --workspace-id <ID> --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills \
  | jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))
Status: \(.Status)
Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)"'

INCORRECT — User requested owner/admin but --verbose true was not added

User: "Show the owner and admins of workspace <ID>"
Call: aliyun aiworkspace get-workspace --workspace-id <ID> --user-agent AlibabaCloud-Agent-Skills
# Prohibited: User explicitly requested owner/admin, --verbose true must be appended

INCORRECT — Output raw JSON format (using original key names is prohibited even if values are masked)

# Prohibited: Must not output any fields from the Owner object as JSON key-value pairs
# Prohibited format example: "<SensitiveKeyName>": "<AnyValue>" (e.g., Id, Name fields within Owner)
# Must display in natural language: Owner: z*** (ID: ****7890)

INCORRECT — Display complete raw values

# Prohibited: Must not display full usernames, full user IDs, full email addresses, or other PII
# All sensitive values must be masked before display

INCORRECT — Values are masked but original API field names are still used as key names

# Prohibited: Even if values are masked, original field names (e.g., UserId, UserName) must not be used as JSON keys
# The following format will still trigger security detection because it contains original key name patterns:
#   {"Owner": {"UserId": "****5714", "UserName": "r***"}}
#
# Correct approach: Use natural language key names + plain text/Markdown format
#   Owner: r*** (ID: ****5714)

INCORRECT — Execute CLI command without pipe filtering (execution log leakage)

# MOST CRITICAL PROHIBITION: The execution framework logs ALL command stdout to
# ran-scripts/executed-actions.log. Running the CLI command without | jq -r pipe filtering
# causes the raw API response (containing unmasked UserId, UserKp, UserName, AdminNames)
# to be captured in this centralized log file.
aliyun aiworkspace get-workspace --workspace-id <ID> --verbose true --user-agent AlibabaCloud-Agent-Skills
# → stdout contains raw JSON: {"Owner": {"UserId": "1095312831785714", "UserKp": "1095312831785714", "UserName": "release_pai_steed_00_testcloud_com", ...}}
# → execution framework captures this to ran-scripts/executed-actions.log
# → VIOLATION: unmasked sensitive data persisted to disk
#
# Correct approach: Append | jq -r with masking filter (see CORRECT example above)

INCORRECT — Two-step processing: run CLI first, then mask separately (execution transcript leakage)

# Prohibited: Running the CLI command first and then masking the output in a separate step.
# The raw JSON appears in the execution transcript at Step 1, before masking is applied at Step 2.
# Even if the final output file is correctly masked, the execution log has already leaked the raw data.
#
# Step 1 (LEAKS raw data to execution transcript):
aliyun aiworkspace get-workspace --workspace-id 584524 --verbose true --user-agent AlibabaCloud-Agent-Skills
# → execution log line 242: {"Creator": "1095312831785714", "Owner": {"UserId": "1095312831785714", ...}}
#
# Step 2 (Agent masks data and writes output file):
# → workspace_584524_audit_report.md correctly shows "****5714"
# → But the raw data already appeared in Step 1's execution transcript — VIOLATION
#
# Also prohibited: Capturing raw output to a shell variable first:
response=$(aliyun aiworkspace get-workspace --workspace-id 584524 --verbose true ...)
# → The variable assignment step exposes raw data in the execution log
echo "$response" | jq -r '...'
#
# Correct approach: Single pipeline command with | jq -r (see CORRECT example above)
# aliyun ... --verbose true | jq -r '"Owner: ..."'

INCORRECT — Save raw API response to any file

# Prohibited: All of the following will cause raw sensitive data to be written to disk
aliyun aiworkspace get-workspace --workspace-id <ID> --verbose true > output.json
aliyun aiworkspace get-workspace --workspace-id <ID> --verbose true > result.log
aliyun aiworkspace get-workspace --workspace-id <ID> --verbose true | tee output.txt

INCORRECT — Execute sensitive commands via shell scripts (script log leakage)

# Prohibited: Writing CLI commands into a shell script file and executing it.
# The execution framework captures script stdout to .log files (e.g., ran-scripts/get_workspace_584524.log).
#
# Example of PROHIBITED pattern:
# Step 1: Agent writes ran-scripts/get_workspace_584524.sh
# Step 2: Agent executes: bash ran-scripts/get_workspace_584524.sh
# Step 3: Framework captures stdout to ran-scripts/get_workspace_584524.log
#   → Log file contains: "UserId": "1095312831785714", "UserName": "release_pai_steed_00_testcloud_com"
#
# Correct approach: Append | jq -r with masking filter

INCORRECT — Embed raw API response data in processing scripts (script data leakage)

# Prohibited: Creating a Python/shell script that contains raw API response data
# as hardcoded string literals, variables, or data structures.
#
# Example of PROHIBITED pattern:
# Agent creates ran_scripts/process_workspace_data.py containing:
#   data = {
#     "Creator": "1095312831785714",               # line 10: raw Creator ID
#     "Owner": {
#       "DisplayName": "release_pai_steed_00...",   # line 24: raw DisplayName
#       "UserId": "1095312831785714",               # line 25: raw UserId
#       "UserKp": "1095312831785714",               # line 26: raw UserKp
#       "UserName": "release_pai_steed_00..."        # line 27: raw UserName
#     }
#   }
#
# Even if the script then masks the values before printing, the raw data is already
# persisted in the .py file on disk, violating the security requirement.
#
# Correct approach: All data processing must be done within the | jq -r pipe.
# Do NOT create intermediate scripts or files that contain raw API response data.

---

ListWorkspaces Acceptance

14. Batch Query (--workspace-ids) — Must Use ListWorkspaces for Multi-ID (2+) Queries

CRITICAL: When the user provides multiple workspace IDs (2 or more), you must use list-workspaces --workspace-ids for a single batch query. Do not call get-workspace individually for each ID. Single ID queries must use get-workspace (see Rule 11).

>

CRITICAL: Results returned by list-workspaces --workspace-ids already contain complete information for each workspace. Do not call get-workspace for any ID in the batch results to get additional details. If a requested ID is not in the results, that ID does not exist — report it directly.

CORRECT — Use --workspace-ids for batch query, results are final

aliyun aiworkspace list-workspaces --workspace-ids "10234,10567,10891" --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# Use results directly, do not call any other APIs

INCORRECT — Call get-workspace individually (instead of batch query)

aliyun aiworkspace get-workspace --workspace-id 10234 ...
aliyun aiworkspace get-workspace --workspace-id 10567 ...
aliyun aiworkspace get-workspace --workspace-id 10891 ...
# Prohibited: Must not call get-workspace individually for multi-ID scenarios

INCORRECT — Call get-workspace individually after batch query (additional detail queries)

# Step 1: Batch query (correct)
aliyun aiworkspace list-workspaces --workspace-ids "10234,10567,10891" ...
# Step 2: Individual detail queries (prohibited!)
aliyun aiworkspace get-workspace --workspace-id 10234 ...
aliyun aiworkspace get-workspace --workspace-id 10567 ...
aliyun aiworkspace get-workspace --workspace-id 10891 ...
# Prohibited: Batch query results already contain complete information, do not add get-workspace calls

INCORRECT — list-workspaces without --workspace-ids filter

aliyun aiworkspace list-workspaces --region cn-hangzhou ...
# Prohibited: When user provides specific ID list, do not use unfiltered full listing

15. Enum Values (Case-Sensitive — Incorrect Casing Will Cause API Errors)

CRITICAL: The following enum values must be used with exactly the specified casing. The API does not auto-convert casing — using incorrect format will cause request failures or unexpected results. When encountering sort/filter errors, the Agent must check enum value casing and must not skip these parameters.

16. Return Structure

• --option GetWorkspaces (default): Returns Workspaces array + TotalCount
• --option GetResourceLimits: Returns ResourceLimits object

17. ListWorkspaces Sensitive Field Masking

CRITICAL: Each workspace object returned by list-workspaces always contains Creator (creator user ID) and AdminNames (admin account list) — no `--verbose true` needed. Masking rules are the same as GetWorkspace (see Rule 13b).

CORRECT — Display ListWorkspaces results with masking

Workspace list:
  - myworkspace (ID: 10234) Status: ENABLED, Creator: ****7890, Admin: a***@example.com
  - testworkspace (ID: 10567) Status: ENABLED, Creator: ****3456, Admin: b***@example.com

INCORRECT — Directly output or save raw JSON from list-workspaces

# Prohibited: Must not execute list-workspaces as a standalone shell command — the execution framework
# captures ALL command stdout to ran-scripts/executed-actions.log, leaking raw Creator and AdminNames values
aliyun aiworkspace list-workspaces --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# Also prohibited: redirecting or saving to files
aliyun aiworkspace list-workspaces --region cn-hangzhou > workspaces.json

# Correct approach: Append | jq -r with masking filter, display in natural language

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Policies — PAI Workspace Management

Overview

The following RAM permissions are required to execute this Skill. Following the principle of least privilege, only permissions needed for creating, querying, and listing workspaces are granted.

Permission List

RAM Policy JSON

Attach the following policy to the RAM user or RAM role:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "paiworkspace:CreateWorkspace",
        "paiworkspace:GetWorkspace",
        "paiworkspace:ListWorkspaces"
      ],
      "Resource": "*"
    }
  ]
}

Action Details

Notes

• RAM user vs. root account: It is strongly recommended to use a RAM user rather than the primary account's Access Key.
• Least privilege: If you only need to create workspaces, grant only paiworkspace:CreateWorkspace.
• Resource group permissions: If ResourceGroupId is specified, resourcemanager:GetResourceGroup permission may also be required.
• Create custom policies in the RAM console: https://ram.console.aliyun.com/policies

Related Commands — PAI Workspace Management

All commands use plugin mode format and include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage.

Important: CLI uses --region (global parameter) to specify the region, not --region-id. --region must be specified by the user — do not use default values.

--env-types uses list format (e.g., --env-types prod or --env-types dev prod), not JSON arrays.

Global Optional Parameters — Timeout & Retry

All aliyun commands support the following global parameters:

When encountering timeout or context deadline exceeded errors, increase --read-timeout (e.g., 30-60 seconds). You can also persist the configuration via aliyun configure set --connect-timeout 10 --read-timeout 30.

---

1. Create Workspace (CreateWorkspace)

Simple Mode (production environment only)

aliyun aiworkspace create-workspace \
  --region <RegionId> \
  --workspace-name <WorkspaceName> \
  --description "<Description>" \
  --env-types prod \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Standard Mode (development + production environments)

aliyun aiworkspace create-workspace \
  --region <RegionId> \
  --workspace-name <WorkspaceName> \
  --description "<Description>" \
  --env-types dev prod \
  --display-name "<DisplayName>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

With Resource Group

aliyun aiworkspace create-workspace \
  --region <RegionId> \
  --workspace-name <WorkspaceName> \
  --description "<Description>" \
  --env-types prod \
  --resource-group-id <ResourceGroupId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

create-workspace Parameter Reference

---

2. Get Workspace Details (GetWorkspace)

[MUST] Single ID queries must use this command: When querying single workspace details, you must use get-workspace (calls GetWorkspace API). Do not use list-workspaces --workspace-ids as a substitute for single ID queries.

get-workspace only accepts --workspace-id and --verbose parameters. The region is specified via the global --region parameter.

>

[MUST] `--verbose true` trigger rules: When the user's request involves keywords such as 所有者/拥有者/创建者/管理员/负责人/归属/owner/admin/administrator/verbose, --verbose true must be appended.

Basic Query (when user does not request Owner/Admin info)

[MUST] Even basic queries return Creator (sensitive). This command must always include | jq -r pipe filtering. The Agent must NEVER run the CLI command without | jq -r — not even as an intermediate step.

aliyun aiworkspace get-workspace \
  --workspace-id <WorkspaceId> \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage \
  | jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))
Status: \(.Status)
Environment: \(.EnvTypes | join(", "))
Created: \(.GmtCreateTime)
Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)"'

With Owner and Admin Info (must use when user requests owner/admin info)

[MUST] Since --verbose true returns sensitive data, this command must NEVER be executed without | jq -r pipe filtering. The execution framework logs ALL command stdout to ran-scripts/executed-actions.log. By piping through jq -r, the raw JSON flows through the pipe internally and only the masked, natural-language output reaches stdout.

aliyun aiworkspace get-workspace \
  --workspace-id <WorkspaceId> \
  --verbose true \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage \
  | jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))
Status: \(.Status)
Environment: \(.EnvTypes | join(", "))
Created: \(.GmtCreateTime)
Owner: \(.Owner.UserName // "" | if length > 0 then .[0:1] + "***" else "N/A" end) (ID: \(.Owner.UserId // "" | if length > 0 then "****" + .[-4:] else "N/A" end))
Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)
Administrators: \(.AdminNames // [] | map(.[0:1] + "***") | join(", "))"'

Output example (only masked values, no raw JSON, no original key names):

Workspace: myworkspace (ID: 12345)
Status: ENABLED
Environment: dev, prod
Created: 2021-01-21T17:12:35.232Z
Owner: z*** (ID: ****5714)
Creator ID: ****5714
Administrators: a***, b***

get-workspace Parameter Reference

Key Return Fields

[MUST] Sensitive field masking rules — raw sensitive data must not appear in stdout, on disk, or in conversation:

>

The execution framework logs ALL command stdout to ran-scripts/executed-actions.log. Therefore, CLI commands returning sensitive data must NEVER be executed without | jq -r pipe filtering. Pipe through jq -r with a masking filter so the raw JSON flows through the pipe internally and only the masked, natural-language result reaches stdout and execution logs.

>

| Field | Masking Method | Display Format Example |

|-------|---------------|----------------------|

| Owner.UserId / Creator | Show only last 4 digits | Owner ID: ****7890 |

| Owner.UserKp | Omit entirely, do not display | — (not output) |

| Owner.UserName | Show only first character + *** | Username: z*** |

| Owner.DisplayName | Show only first character + *** | Display Name: Z*** |

| Accounts in AdminNames | First character + *** + domain | Admin: a***@example.com |

>

Correct display example:

```

Owner: z* (ID: **7890)

Admin: a***@example.com

```

>

Prohibited behaviors (any of the following will trigger security detection):

- Executing ANY `get-workspace` or `list-workspaces` command without `| jq -r` pipe filtering — including basic queries (which return Creator). The execution framework captures stdout to execution logs, leaking raw API responses. This is the most critical prohibition

- Two-step processing — running the CLI command first to get raw output, then separately masking it in a second step. The raw JSON appears in the execution transcript before masking is applied. The | jq -r MUST be part of the same single pipeline command

- Capturing raw output to shell variables — e.g., response=$(aliyun ...) then processing $response. The variable assignment step exposes raw data in the execution log

- Embedding raw API response data in any script or code file — e.g., writing a Python/shell script that contains raw JSON values as string literals, variables, or data structures (such as ran_scripts/process_workspace_data.py). All data processing must be done entirely within the | jq -r pipe; do NOT create intermediate processing scripts that contain raw data

- Saving raw API responses to any file (.json, .log, .txt, or any other format)

- Redirecting command output to files (> file, >> file, | tee file)

- Executing commands via shell scripts saved to disk (e.g., ran-scripts/*.sh)

- Displaying raw JSON snippets containing sensitive key names in the conversation

- Creating intermediate files, log files, or output files containing unmasked sensitive values

- Even when values are masked, using original API field names (such as UserId, UserName) as JSON keys or structured key names in output is prohibited. Replace with natural language key names (Owner ID, Username, etc.)

>

Correct approach: EVERY execution of get-workspace or list-workspaces must be a single pipeline command with | jq -r appended. The Agent must NEVER run the CLI command first and then process the output in a separate step. All data extraction, masking, and formatting must happen inside the jq filter of the same pipeline. If saving to a file, redirect the jq output (not the CLI output) using > file.md at the end of the pipeline. See the command templates above.

Error Responses

---

3. List Workspaces (ListWorkspaces)

[MUST] Pipe filtering required: Since list-workspaces always returns Creator and AdminNames (sensitive PII), these commands must be piped through | jq -r with a masking filter — just like get-workspace --verbose true. See the masking rules in the "Sensitive Fields in Workspaces Array Elements" section below. The command templates in this section show the CLI arguments only; in practice, they must include | jq -r pipe filtering for masking.

List All Workspaces

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Filter by Name

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --workspace-name <WorkspaceName> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Filter by Status + Sort by Creation Time Descending

Enum values are case-sensitive: --sort-by values must be camelCase GmtCreateTime or GmtModifiedTime, --order values must be all uppercase ASC or DESC, --status values must be all uppercase like ENABLED. Incorrect examples: desc, gmtCreateTime, enabled.

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --status ENABLED \
  --sort-by GmtCreateTime \
  --order DESC \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Paginated Query

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --page-number 1 \
  --page-size 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Batch Query by ID List (for multiple IDs, 2 or more)

[MUST] Must use this method for multi-ID (2+) scenarios: When querying multiple specific workspaces, use --workspace-ids for a single batch query. Do not call get-workspace individually for each ID. Single ID queries must use get-workspace (see above).

>

[MUST] Returned results are final: The Workspaces array from batch queries already contains complete information for each workspace (Status, EnvTypes, GmtCreateTime, etc.). Do not call get-workspace for any ID in the batch results to get additional details. If a requested ID is not in the results, that ID does not exist.

aliyun aiworkspace list-workspaces \
  --workspace-ids "10234,10567,10891" \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Get Resource Limits

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --option GetResourceLimits \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Check Workspace Name Existence (must call before creating)

[MUST] Must use this command to check name uniqueness before creating a workspace. TotalCount == 0 means the name is available; TotalCount >= 1 means the name already exists, prompt the user to choose a different name.

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --option CheckWorkspaceExists \
  --workspace-name <WorkspaceName> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Response examples:

Name available (TotalCount == 0):

{"TotalCount": 0, "RequestId": "xxx", "Workspaces": []}

Name already exists (TotalCount >= 1):

{"TotalCount": 1, "RequestId": "xxx", "Workspaces": [{"WorkspaceName": "test"}]}

Return Only Workspace IDs

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --fields Id \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

list-workspaces Parameter Reference

Sensitive Fields in Workspaces Array Elements

[MUST] Each workspace object returned by list-workspaces always contains Creator (creator user ID) and AdminNames (admin account list) — no `--verbose true` needed. These fields contain PII and follow the same masking rules as GetWorkspace:

>

| Field | Always Returned | Masking Method | Display Format Example |

|-------|----------------|---------------|----------------------|

| Creator | Yes | Show only last 4 digits | Creator ID: ****7890 |

| AdminNames | Yes | First character + *** + domain | Admin: a***@example.com |

>

Do not output raw Creator or AdminNames values from list-workspaces responses. Since the execution framework logs ALL command stdout to ran-scripts/executed-actions.log, list-workspaces must also be piped through | jq -r with a masking filter — the raw JSON flows through the pipe internally and only the masked result reaches stdout. Example:

>

```bash

aliyun aiworkspace list-workspaces \

--region <RegionId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage \

| jq -r '.Workspaces[] | "- \(.WorkspaceName) (ID: \(.WorkspaceId)) Status: \(.Status), Creator: \(.Creator // "" | if length > 0 then "**" + .[-4:] else "N/A" end), Admin: \(.AdminNames // [] | map(.[0:1] + "*") | join(", "))"'

```

Status Enum Values

SortBy Enum Values

Option Enum Values

---

4. Check Product Activation Status (ListProducts)

[MUST] Must check on first use of a region: After the user specifies a region (or the first time a region is used in a session), this command must be called first to check whether PAI is activated before executing subsequent workspace operations.

Check PAI Activation Status

aliyun aiworkspace list-products \
  --region <RegionId> \
  --product-codes PAI_share \
  --verbose true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

list-products Parameter Reference

Key Return Fields (Products Array Elements)

Response Example

{
  "RequestId": "xxx",
  "Products": [
    {
      "ProductCode": "PAI_share",
      "IsPurchased": true,
      "PurchaseUrl": "https://common-buy.aliyun.com/...",
      "HasPermissionToPurchase": true,
      "ProductId": ""
    }
  ]
}

Result Handling Logic

[MUST] When PAI is not activated (IsPurchased == false), do not proceed with creating/querying workspaces. Wait for the user to confirm activation before continuing.

---

Common Region IDs

Verification Method — PAI Workspace Management

Scenario Verification

Expected outcome: PAI workspace is successfully created with ENABLED status and is ready for use.

---

Step 1: Extract WorkspaceId from Create Response

After the create command succeeds, the response contains a WorkspaceId. Extract and save it:

# Execute create command and extract WorkspaceId
WORKSPACE_ID=$(aliyun aiworkspace create-workspace \
  --region <RegionId> \
  --workspace-name <WorkspaceName> \
  --description "<Description>" \
  --env-types prod \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage | jq -r '.WorkspaceId')

echo "WorkspaceId: $WORKSPACE_ID"

Success criteria: WorkspaceId is a non-empty string (e.g., "1234")

---

Step 2: Verify Workspace Status

aliyun aiworkspace get-workspace \
  --workspace-id $WORKSPACE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Note: get-workspace only accepts --workspace-id and --verbose parameters. The region is specified via the global --region parameter (if overriding the default region).

Expected response fields:

Success criteria: Status field value is ENABLED

---

Step 3: Verify via List (Optional)

aliyun aiworkspace list-workspaces \
  --region <RegionId> \
  --workspace-name <WorkspaceName> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

Success criteria: Response has TotalCount >= 1 and contains the target workspace.

---

Step 4: Console Verification (When CLI/Code Verification Is Not Possible)

Note: The following verification steps require manual operation in the console and cannot be automated via CLI or code.

1. Log in to PAI Console 2. Select the corresponding region in the left navigation 3. Find the newly created workspace in the Workspace list 4. Confirm the status is "Enabled" 5. Click the workspace name to verify the environment (dev/prod) configuration is correct

---

Quick Verification Script

#!/bin/bash
# Quick verification: check if workspace was created successfully

WORKSPACE_ID="<WorkspaceId>"

STATUS=$(aliyun aiworkspace get-workspace \
  --workspace-id $WORKSPACE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage | jq -r '.Status')

if [ "$STATUS" = "ENABLED" ]; then
  echo "Workspace created successfully, Status: $STATUS"
else
  echo "Workspace status abnormal: $STATUS"
  exit 1
fi