alibabacloud-pai-workspace-manage

PAI 工作空间管理

在 Alibaba Cloud Platform for AI（PAI）上创建、查询和列出工作空间。工作空间是用于 AI 模型训练、数据处理及相关任务的隔离管理单元。

架构：PAI AIWorkSpace（工作空间）

工作空间模式：

• 简单模式：仅生产环境（prod）
• 标准模式：开发环境（dev）+ 生产环境（prod）

---

安装

预检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装/更新， 或参阅 references/cli-installation-guide.md 获取安装说明。 然后[必须]运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 然后[必须]运行 aliyun plugin update，确保本地计算机上的所有现有插件始终保持最新。

[必须] CLI User-Agent — 每次调用 aliyun CLI 命令时都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

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

---

凭证验证

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝对不要读取、回显或打印 AK/SK 值（例如，禁止执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝对不要要求用户在对话或命令行中直接输入 AK/SK
• 绝对不要使用 aliyun configure set 设置明文凭证值
• 只能使用 aliyun configure list 检查凭证状态

敏感数据屏蔽：

• API 响应中的以下字段包含个人身份信息，向用户显示前必须屏蔽：

  • Owner.UserId / Creator — 仅显示末尾 4 位，例如 ****1234
  • Owner.UserKp — 绝不显示，完全省略
  • Owner.UserName / Owner.DisplayName — 仅显示首字符 + ***，例如 z***
  • AdminNames 中的账号 — 按 u***@example.com 格式屏蔽

• [MUST] 原始敏感数据绝不能出现在 stdout、执行日志、磁盘或对话中：执行框架会将所有命令 stdout 记录到执行日志/转录记录中（例如 ran-scripts/executed-actions.log）。因此，每次执行 get-workspace 或 list-workspaces（包括不带 --verbose 的基本查询）都必须包含 | jq -r 管道过滤，因为响应中始终会返回敏感的 Creator。任何执行步骤都不得让原始 API JSON 出现在命令输出中，即使只是中间步骤。| jq -r 管道必须包含在单条管道命令中：

  基本查询（不带 --verbose）：

  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 true）：

  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(", "))"'
  

  原始 API 响应会在管道内部流转，不会到达 shell stdout。执行框架只会捕获 jq 的输出（包含屏蔽后的值和自然语言键名）。以下行为均为禁止：

  • 运行 CLI 命令时不使用 | jq 管道过滤，即使是基本查询也不行（Creator 字段始终会返回，且属于敏感信息）
  • 分两步处理——先运行 CLI 命令获取原始输出，再单独进行屏蔽。原始 JSON 会在屏蔽之前出现在执行转录记录中。| jq -r 必须包含在同一条管道命令中
  • 将原始输出存入 shell 变量——例如，先执行 response=$(aliyun ...)，再执行 echo "$response" | jq ...。变量赋值会将原始数据记录到执行日志中
  • 输出重定向（> file.json、>> file.log、| tee file）
  • 通过保存到磁盘的 shell 脚本执行命令（例如 ran-scripts/*.sh）
  • 在任何脚本或代码文件中嵌入原始 API 响应数据——例如，编写包含作为字符串字面值、变量或数据结构的原始 JSON 值的 Python/shell 脚本（如 ran_scripts/process_workspace_data.py）。所有数据处理都必须完全在 | jq -r 管道中完成；不要创建包含原始数据的中间处理脚本
  • 在对话中显示原始 JSON 片段

• [MUST] 输出键不得使用原始 API 字段名：即使值已屏蔽，在任何输出（对话或文件）中，也禁止将原始 API 字段名（例如 UserId、UserName、UserKp、AdminNames）用作 JSON 键或结构化输出的键名。请改用自然语言键名：

  • UserId / Creator → Owner ID 或 Creator ID
  • UserName → Username
  • DisplayName → Display Name
  • AdminNames → Administrators

  正确做法：每次执行 get-workspace 或 list-workspaces 时，都必须使用追加了 | jq -r 的单条管道命令。Agent 绝不能先运行 CLI 命令，再在单独步骤中处理输出——原始 JSON 会在屏蔽之前出现在执行转录记录中。所有数据提取、屏蔽和格式化都必须在 jq 过滤器中完成。如果要保存到文件，请在管道末尾使用 > file.md 重定向 jq 输出（而不是 CLI 输出）。此规则适用于所有查询——基本查询、详细查询和列表查询。

aliyun configure list

检查输出中是否存在有效配置（AK、STS 或 OAuth 身份）。

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

1. 从 Alibaba Cloud 控制台 获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell 配置文件中的环境变量）
3. 返回并在 aliyun configure list 显示有效配置后重新运行

---

RAM 权限

有关所需权限（包括策略 JSON 和说明），请参阅 references/ram-policies.md。

**[MUST] 权限失败处理：**在执行过程中，任何命令或 API 调用因权限错误而失败时，请按以下流程处理：

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

---

参数确认

重要：参数确认 — 执行任何命令或 API 调用之前， 必须与用户确认所有可由用户自定义的参数（例如，RegionId、WorkspaceName、Description、EnvTypes 等）。不要在未经用户明确批准的情况下假设或使用默认值。

参数	必需/可选	说明	示例
--region	必需	区域 ID（全局参数），必须由用户指定，不要使用默认值	cn-hangzhou
--workspace-name	必需	工作空间名称：3-23 个字符，以字母开头，可包含字母/数字/下划线，在区域内必须唯一	myworkspace
--description	必需	工作空间描述，最多 80 个字符	My AI workspace
--env-types	必需	环境类型（列表格式）：prod（简单模式）或 dev prod（标准模式）	prod
--display-name	可选	显示名称，默认为 WorkspaceName	My Workspace
--resource-group-id	可选	资源组 ID；如果未指定，则使用默认资源组	rg-xxxxxxxx

注意：设置 --resource-group-id 后，无法通过 CLI/代码修改。如需更改，请使用控制台或重新创建工作空间。

---

超时配置

API 调用支持配置超时时间（秒）：

选项 1：命令行参数（仅适用于当前命令）：

• --connect-timeout <seconds> — 连接超时
• --read-timeout <seconds> — I/O 读取超时

选项 2：持久化配置（全局生效，写入当前配置文件）：

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

命令行参数优先于持久化配置。如果未设置，CLI 将使用内置默认值。遇到 timeout 或 context deadline exceeded 错误时，请增大 --read-timeout（例如 30-60 秒）。

---

核心工作流

有关所有 CLI 命令模板和参数详情，请参阅 references/related-commands.md。

前提条件：区域选择和 PAI 激活检查

[MUST] 不要使用默认区域：Agent 不得假设或使用默认区域，必须明确询问用户要使用哪个区域。

[MUST] 首次使用某个区域时检查 PAI 激活状态：用户指定区域后（或会话中首次使用某个区域时），Agent 必须先调用 list-products，检查该区域是否已激活 PAI，然后才能执行后续工作空间操作。

步骤 1：确认区域

询问用户要使用哪个区域。如果用户尚未指定，请提供常见区域列表供其选择（请参阅 references/related-commands.md 中的“常见区域 ID”表）。不要自动选择默认区域。

步骤 2：检查 PAI 激活状态

使用 aliyun aiworkspace list-products 检查用户指定区域中的 PAI 及其依赖产品是否已激活：

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

步骤 3：处理检查结果

检查返回的 Products 数组，找到匹配的产品条目：

判断逻辑：

1. IsPurchased == true → PAI 已激活，继续后续工作流
2. IsPurchased == false → PAI 未激活，引导用户激活：
   • 检查 HasPermissionToPurchase 字段：
     • true → 用户有权限。显示 PurchaseUrl 链接，并提示用户先在控制台完成激活，再继续操作
     • false → 用户没有权限（需要主账号或拥有 pai:CreateOrder 权限的 RAM 用户）。告知用户联系主账号管理员
   • PAI 未激活时，不要继续创建或查询工作空间

工作流 1：创建工作空间（CreateWorkspace）

使用 aliyun aiworkspace create-workspace 创建工作空间。必需参数：--region、--workspace-name、--description、--env-types。简单模式使用 --env-types prod，标准模式使用 --env-types dev prod。也可以选择添加 --display-name 和 --resource-group-id。

步骤 1：输入参数验证

[MUST] 参数格式验证：调用 API 前，Agent 必须按以下要求验证用户提供的参数。如果验证失败，请提示用户修正输入。不要提交不符合要求的参数：

参数	验证规则	示例
--workspace-name	3–23 个字符，必须以字母开头，且只能包含字母、数字和下划线（_）。不允许使用连字符（-）、空格、中文字符和其他特殊字符	my_workspace_01
--description	最多 80 个字符；如果包含特殊字符，请用引号括起来	"My AI workspace"
--env-types	必须为 prod 或 dev prod，列表格式	prod
--display-name	可选，没有严格的格式限制	My Workspace

步骤 2：检查名称是否存在（先检查后操作的幂等模式）

[MUST] 幂等性保证：CreateWorkspace API 不支持 ClientToken，因此通过先检查后操作的模式确保幂等性。创建前，必须调用 list-workspaces --option CheckWorkspaceExists --workspace-name <name> 检查名称是否已存在。

判断逻辑：

• TotalCount == 0 → 名称可用，继续步骤 3 创建
• TotalCount >= 1 → 名称已存在，执行以下操作：
  1. 从返回的 Workspaces[0] 中提取现有的 WorkspaceId
  2. 调用 get-workspace --workspace-id <id> 获取完整详情
  3. 将现有工作空间的关键参数（EnvTypes、Description 等）与当前请求参数进行比较
  4. 匹配 → 视为已创建，直接返回现有的 WorkspaceId，不要重新创建
  5. 不匹配 → 告知用户该名称已被占用，且配置不同，请用户选择其他名称

步骤 3：执行创建

参数验证通过且名称不存在后，执行 create-workspace 命令。成功后将返回 WorkspaceId。如果创建时返回 WorkspaceNameAlreadyExists 错误（并发场景），请按照步骤 2 中 TotalCount >= 1 的逻辑处理。

工作流 2：获取工作空间详情（GetWorkspace）

[MUST] 查询单个工作空间时必须使用 get-workspace：查询一个特定工作空间的详情时，必须使用 aliyun aiworkspace get-workspace --workspace-id <id>。不得使用 list-workspaces --workspace-ids 替代。get-workspace 会调用 GetWorkspace API，并返回单个工作空间的完整详情。

仅接受 --workspace-id（必填）和 --verbose（可选）。通过全局参数 --region 指定地域。Status 为 ENABLED 表示工作空间已就绪。

[MUST] --verbose true 触发规则：--verbose true 会返回 Owner（UserKp、UserId、UserName、DisplayName）和 AdminNames（管理员账号列表）。Agent 必须遵循以下规则：

1. 触发条件 — 用户请求中涉及以下任一关键词时，构造命令时必须追加 --verbose true（在调用 API 前判定，不取决于 API 是否调用成功）：
   • 中文关键词：所有者、拥有者、创建者、管理员、负责人、归属
   • 英文关键词：owner、admin、administrator、verbose
   • 字段名称：Owner、AdminNames
2. 未触发时 — 用户仅查询基本信息（状态、环境类型等）时，不追加 --verbose
3. 脱敏规则 — UserId/Creator：仅显示最后 4 位（****1234）；UserKp：完全省略；UserName/DisplayName：仅显示首字符（z***）；AdminNames 条目：u***@example.com
4. 标准输出、执行日志、磁盘或输出中不得出现未脱敏的敏感数据 — 每一次执行 get-workspace（无论是否带 --verbose）或 list-workspaces，都必须是追加 | jq -r 的单条管道命令。Agent 绝不能先运行 CLI 命令，再单独对输出进行脱敏——原始 JSON 会出现在执行记录中。不得分两步处理，不得捕获变量（response=$(aliyun ...)），也不得使用中间脚本。所有脱敏都必须在同一管道的 jq 过滤器中完成。模板请参阅“敏感数据脱敏”部分和 references/related-commands.md

[MUST] 404 错误处理：当 get-workspace 返回 StatusCode: 404, Code: 100400027, Message: Workspace not exists 时，表示该工作空间 ID 不存在。Agent 必须直接告知用户工作空间不存在，并包含用户指定的原始 workspace-id。收到 404 后，不得回退到 list-workspaces 或其他 API 来尝试“查找”该工作空间。不得默默忽略错误。如果用户随后提供新的 workspace-id，Agent 必须使用与首次调用相同的参数（包括 --verbose true 等）重新调用 get-workspace。

工作流 3：列出工作空间（ListWorkspaces）

使用 aliyun aiworkspace list-workspaces 列出工作空间。支持以下筛选和排序参数：

• --workspace-name <name> — 按名称模糊匹配
• --workspace-ids <id1,id2,...> — 按 ID 列表批量查询，多个 ID 以逗号分隔（例如，--workspace-ids "123,456,789"）
• --status <STATUS> — 按状态筛选，枚举值（全部大写）：ENABLED | INITIALIZING | FAILURE | DISABLED | FROZEN | UPDATING
• --sort-by <Field> — 排序字段（区分大小写）：GmtCreateTime（默认）| GmtModifiedTime
• --order <ORDER> — 排序方向（全部大写）：ASC（默认）| DESC
• --page-number <n> / --page-size <n> — 分页参数
• --option GetResourceLimits — 获取资源限制信息，而不是工作空间列表
• --option CheckWorkspaceExists — 检查是否已存在指定名称的工作空间（创建前检查，与 --workspace-name 配合使用）

[MUST] API 选择规则：查询单个 ID 时，使用 get-workspace --workspace-id（GetWorkspace API）；在一次批量查询中查询多个 ID（2 个或更多）时，使用 list-workspaces --workspace-ids "id1,id2,..."（ListWorkspaces API）。不要针对每个 ID 单独调用 get-workspace。

[MUST] 批量查询结果即为最终结果：list-workspaces --workspace-ids 返回的 Workspaces 数组已包含每个工作空间的完整信息（Status、EnvTypes、GmtCreateTime 等）。不要为了获取更多详情而对批量结果中的任何 ID 调用 get-workspace。如果响应中未包含某些 ID，则这些 ID 不存在——直接告知用户。

[MUST] 枚举值区分大小写：--sort-by 必须为 GmtCreateTime 或 GmtModifiedTime（驼峰命名），--order 必须为 ASC 或 DESC（全部大写），--status 必须全部大写，例如 ENABLED。大小写不正确（例如 desc、gmtCreateTime、enabled）会导致 API 错误或意外结果。

[MUST] ListWorkspaces 敏感字段脱敏：list-workspaces 返回的每个工作空间对象始终包含 Creator（创建者用户 ID）和 AdminNames（管理员账号列表）——无需使用 --verbose true。Agent 显示这些字段时必须进行脱敏（Creator：仅显示末 4 位；AdminNames：仅显示首字符，其余替换为 ***）。不要输出包含原始值的 JSON，也不要通过重定向（> file）或脚本将原始响应保存到文件。

---

成功验证

验证目标	方法	成功标准
已返回 WorkspaceId	解析创建命令的响应	WorkspaceId 不为空
工作空间状态正常	get-workspace 命令	Status == "ENABLED"
控制台中可见	登录 PAI Console 并手动验证	新工作空间显示在列表中

详细验证方法请参阅 references/verification-method.md

---

清理（删除工作空间）

警告：删除工作空间是不可逆操作，会移除其中的所有资源。请谨慎操作。

注意：无法直接通过 CLI 删除工作空间（aiworkspace 插件目前不支持 delete-workspace）。请使用以下方法：

1. 通过控制台删除：登录 PAI Console -> 工作空间列表 -> 选择工作空间 -> 删除
2. 调用 API：使用 DELETE /api/v1/workspaces/{WorkspaceId} 端点（通过 SDK 或直接发起 HTTP 调用）

---

最佳实践

1. 命名约定：WorkspaceName 使用项目名称或团队标识前缀，例如 nlp_prod、cv_dev（注意：不支持连字符，请使用下划线）
2. 环境选择：生产项目使用标准模式（dev + prod），以分隔开发和生产资源
3. 描述：描述应说明用途、团队或项目，以便于管理
4. 地域选择：选择最靠近数据存储位置的地域，以尽量降低数据传输延迟
5. 资源组管理：在多项目场景中使用不同的资源组，以便进行成本分配和权限管理
6. DisplayName：DisplayName 使用便于业务识别的名称，WorkspaceName 使用英文标识符

---

参考文档

文档	描述
references/ram-policies.md	RAM 权限策略、Policy JSON 和说明
references/related-commands.md	完整的 CLI 命令模板、参数表、枚举值和返回字段
references/verification-method.md	验证步骤和脚本
references/acceptance-criteria.md	CLI 命令验收标准（正确/错误模式）
references/cli-installation-guide.md	Aliyun CLI 安装和配置
ListWorkspaces API Doc	ListWorkspaces API 参考
CreateWorkspace API Doc	CreateWorkspace API 参考
GetWorkspace API Doc	GetWorkspace API 参考
ListProducts API Doc	ListProducts API 参考（产品激活状态检查）