alibabacloud-pai-workspace-manage：提供PAI工作空间的生命周期管理，包括创建、查询。

PAI 工作空间管理

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

架构：PAI AIWorkSpace（Workspace）

工作空间模式：

• 简单模式：仅生产环境（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

凭证验证

预检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 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 响应数据——例如编写包含原始 JSON 值作为字符串字面量、变量或数据结构的 Python/shell 脚本（如 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
```
检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，请在此停止。
1. 从 阿里云控制台 获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 在 aliyun configure list 显示有效 profile 后返回并重新运行

RAM 权限

所需权限见 references/ram-policies.md（含 Policy JSON 和说明）。

[必须] 权限失败处理： 当任何命令或 API 调用在执行过程中因权限错误失败时，遵循以下流程：
1. 阅读 references/ram-policies.md 获取本 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请必要权限
3. 暂停并等待用户确认所需权限已授予

参数确认

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

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

超时配置

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

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

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

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

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 中的常用 Region 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 或其他 API 试图“找到”工作空间。不要静默忽略错误。如果用户随后提供新的 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（驼峰），--order 必须为 ASC 或 DESC（全大写），--status 必须全大写如 ENABLED。使用错误的大小写（例如 desc、gmtCreateTime、enabled）会导致 API 错误或意外结果。

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

成功验证

详细验证方法见 references/verification-method.md

清理（删除工作空间）

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

最佳实践

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

参考文档

文档 2 / 6：alibabacloud-polardbx-sql