返回技能市场
开发运维 安全

PAI工作空间生命周期管理

@aliyun/alibabacloud-pai-workspace-manage

提供PAI工作空间的生命周期管理，包括创建、查询。

云Skills门户 热度 37v0.0.2

PAI 工作空间管理

在阿里云人工智能（AI）平台（PAI）上创建、查询和列出工作空间。工作空间是用于 AI 模型训练、数据处理及相关任务的独立管理单元。

架构：PAI AIWorkSpace（工作空间）

工作空间模式：

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

---

安装

前置检查：要求阿里云 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

---

凭证验证

前置检查：必须具备阿里云凭证
安全规则：
- 严禁读取、回显或打印 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 格式脱敏
- [必须] 原始敏感数据不得出现在 stdout、执行日志、磁盘或对话中：执行框架会将所有命令的 stdout 记录到执行日志/转录记录中（例如 ran-scripts/executed-actions.log）。因此，每次执行 get-workspace 或 list-workspaces（包括不带 --verbose 的基本查询）时，都必须包含 | jq -r 管道过滤，因为返回结果中始终包含敏感字段 Creator。不得存在任何执行步骤使原始 API JSON 出现在命令输出中，即使作为中间步骤也不允许。| jq -r 管道必须是单条管道命令的一部分：
基本查询（不带 --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 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(", "))"'
```
原始 API 响应在管道内部流转，绝不会到达 shell 的 stdout。执行框架仅捕获 jq 的输出（其中的值已脱敏，键名使用自然语言）。以下行为全部禁止：
- 在不使用 | jq 管道过滤的情况下运行 CLI 命令——即使是基本查询也禁止（Creator 字段始终会返回且属于敏感字段）
- 两步处理——先运行 CLI 命令获取原始输出，再单独对其进行脱敏。应用脱敏前，原始 JSON 就会出现在执行记录中。| jq -r 必须是同一条管道命令的一部分
- 将原始输出捕获到 shell 变量中——例如，先执行 response=$(aliyun ...)，再执行 echo "$response" | jq ...。变量赋值会将原始数据记录到执行日志中
- 输出重定向（> file.json、>> file.log、| tee file）
- 通过已保存到磁盘的 shell 脚本执行命令（例如 ran-scripts/*.sh）
- 在任何脚本或代码文件中嵌入原始 API 响应数据——例如，编写 Python/shell 脚本，将原始 JSON 值作为字符串字面量、变量或数据结构包含在其中（如 ran_scripts/process_workspace_data.py）。所有数据处理必须完全在 | jq -r 管道内完成；禁止创建包含原始数据的中间处理脚本
- 在对话中显示原始 JSON 片段
- [必须] 原始 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 输出）。此规则适用于所有查询——基本查询、详细查询和列表查询。
```bash
aliyun configure list
```
检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。
如果不存在有效配置文件，请在此处停止。
1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证（通过在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 当 aliyun configure list 显示有效配置文件后，返回并重新运行

---

RAM 权限

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

[必须] 权限失败处理：执行期间的任何时候，如果任何命令或 API 调用因权限错误而失败，请遵循以下流程：
1. 阅读 references/ram-policies.md，获取此 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 指导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

---

参数确认

重要：参数确认——在执行任何命令或 API 调用之前，
所有用户可自定义参数（例如 RegionId、WorkspaceName、描述、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 开通检查

[必须] 不得使用默认地域：Agent 不得假定或使用默认地域，必须明确询问用户要使用哪个地域。
[必须] 首次使用某个地域时检查 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：输入参数验证

[必须] 参数格式验证：调用 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：名称存在性检查（先检查后操作的幂等模式）

[必须] 幂等性保证：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）

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

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

[必须] --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. stdout、执行日志、磁盘或输出中不得出现原始敏感数据——每次执行 get-workspace（无论是否使用 --verbose）或 list-workspaces，都必须使用追加了 | jq -r 的单条管道命令。Agent 严禁先运行 CLI 命令，再单独对输出进行脱敏——否则原始 JSON 会出现在执行记录中。不得进行两步处理，不得捕获变量（response=$(aliyun ...)），不得使用中间脚本。所有脱敏都必须在同一管道的 jq 过滤器中完成。模板请参见“敏感数据脱敏”部分和 references/related-commands.md
[必须] 404 错误处理：当 get-workspace 返回 StatusCode: 404, Code: 100400027, Message: Workspace not exists 时，该工作空间 ID 不存在。Agent 必须直接向用户报告工作空间不存在，并包含用户最初指定的 workspace-id。收到 404 后，不得回退到 list-workspaces 或其他 APIs 尝试“查找”工作空间。不得静默忽略该错误。如果用户随后提供新的 workspace-id，Agent 必须使用与初次调用相同的参数（包括 --verbose true 等）重试 get-workspace。

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

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

  • --workspace-name <name>——按名称模糊匹配
  • --workspace-ids <id1,id2,...>——按 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 配合使用）
[必须] API 选择规则：查询单个 ID 时，使用 get-workspace --workspace-id（GetWorkspace API）；在单次批量查询中查询多个 ID（2 个或更多）时，使用 list-workspaces --workspace-ids "id1,id2,..."（ListWorkspaces API）。不得为每个 ID 单独调用 get-workspace。
[必须] 批量查询结果即为最终结果：list-workspaces --workspace-ids 返回的 Workspaces 数组已包含每个工作空间的完整信息（Status、EnvTypes、GmtCreateTime 等）。不得为批量结果中的任何 ID 调用 get-workspace 以获取更多详情。如果响应中缺少某些 ID，则这些 ID 不存在——请直接向用户报告。
[必须] 枚举值区分大小写：--sort-by 必须是 GmtCreateTime 或 GmtModifiedTime（camelCase），--order 必须是 ASC 或 DESC（全部大写），--status 必须全部大写，例如 ENABLED。使用错误的大小写（例如 desc、gmtCreateTime、enabled）会导致 API 错误或非预期结果。
[必须] ListWorkspaces 敏感字段脱敏：list-workspaces 返回的每个工作空间对象都始终包含 Creator（创建者用户 ID）和 AdminNames（管理员账号列表），无需 --verbose true。Agent 在展示时必须对这些字段进行脱敏（Creator：仅显示后 4 位；AdminNames：首字符 + ***）。不得输出包含原始值的 JSON，也不得通过重定向（> file）或脚本将原始响应保存到文件中。

---

成功验证

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

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

---

清理（删除工作空间）

警告：删除工作空间是一项不可逆操作，会移除其中的所有资源。请谨慎操作。
注意：无法直接通过 CLI 删除工作空间（aiworkspace 插件目前不支持 delete-workspace）。请使用以下方法：
1. 控制台删除：登录 PAI 控制台 -> 工作空间列表 -> 选择工作空间 -> 删除
2. API 调用：使用 DELETE /api/v1/workspaces/{WorkspaceId} 端点（通过 SDK 或直接发起 HTTP 调用）

---

最佳实践

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

---

参考文档

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

qianwen skills install @aliyun/alibabacloud-pai-workspace-manage