📦 Alibabacloud Pai Workspace Manage — 管理PAI工作区

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

架构：PAI AIWorkSpace（工作空间） 工作空间模式：

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

安装

前置检查：需要 Aliyun CLI >= 3.3.1
运行 aliyun version 确认版本 >= 3.3.1。如未安装或版本过低，
请参考 references/cli-installation-guide.md 进行安装。
然后【必须】执行 aliyun configure set --auto-plugin-install true 以启用自动插件安装。

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

凭证校验

前置检查：需要阿里云凭证

安全规则：
- 禁止 读取、回显或打印 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）：

> aliyun aiworkspace get-workspace --workspace-id  --region  \
--user-agent AlibabaCloud-Agent-Skills \
| 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  --verbose true --region  \
--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(", "))"'

原始 API 响应仅在管道内部流转，永不进入 shell stdout。只有 jq 的输出（已脱敏且使用自然语言键）被框架捕获。以下行为全部禁止：
- 不带 | jq 管道直接执行 CLI 命令 —— 即使基础查询也返回敏感 Creator
- 两步处理 —— 先执行 CLI 获取原始输出，再单独脱敏。原始 JSON 会在脱敏前被记录到执行抄本
- 将原始输出捕获到变量 —— 如 response=$(aliyun ...) 再 echo "$response" | jq ...。变量赋值会把原始数据写入日志
- 输出重定向（> file.json、>> file.log、| tee file）
- 通过磁盘脚本执行命令（如 ran-scripts/.sh）
- 在任何脚本或代码文件中嵌入原始 API 响应数据 —— 例如编写 Python/shell 脚本时，将原始 JSON 作为字符串字面量、变量或数据结构（如 ran_scripts/process_workspace_data.py）。所有数据处理必须完全在 | jq -r 管道内完成；不得创建包含原始数据的中间处理脚本
- 在对话中展示原始 JSON 片段
- 【必须】禁止使用原始 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

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

若无有效 profile，请在此停止。
1. 前往阿里云控制台获取凭证
2. 在会话外配置凭证（终端执行 aliyun configure 或在 shell 配置文件里设置环境变量）
3. 返回并重新执行，直到 aliyun configure list 显示有效 profile

RAM 权限

请参考 references/ram-policies.md 获取所需权限（含 Policy JSON 及操作说明）。

【必须】权限失败处理： 任何时候因权限错误导致命令或 API 调用失败，按以下流程处理：
1. 读取 references/ram-policies.md 获取本 SKILL 所需的全部权限列表
2. 使用 ram-permission-diagnose 技能引导用户申请所需权限
3. 暂停并等待用户确认权限已授予后再继续

参数确认

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

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

aliyun aiworkspace list-products \
--region  \
--product-codes PAI_share \
--verbose true \
--user-agent AlibabaCloud-Agent-Skills

【必须】--verbose true 触发规则：--verbose true 会返回 Owner（UserKp、UserId、UserName、DisplayName）及 AdminNames（管理员账号列表）。Agent 须遵守以下规则：

1. 触发条件 —— 当用户请求包含以下关键词时，构造命令必须追加 --verbose true（在调用前判定，不依赖 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 模板

【必须】404 错误处理：当 get-workspace 返回 StatusCode: 404, Code: 100400027, Message: Workspace not exists 时，表示该工作空间 ID 不存在。Agent 必须直接向用户报告工作空间不存在，并附带用户最初提供的 workspace-id。不得回退到 list-workspaces 或其他 API 去“查找”工作空间。不得静默忽略该错误。若用户随后提供新的 workspace-id，Agent 必须使用与初次调用相同参数（含 --verbose true 等）重新执行 get-workspace。

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

使用 aliyun aiworkspace list-workspaces 列出工作空间。支持以下过滤与排序参数：

• --workspace-name —— 按名称模糊匹配
• --workspace-ids —— 按 ID 列表批量查询，逗号分隔（例：--workspace-ids "123,456,789"）
• --status —— 按状态过滤，枚举值（全大写）：ENABLED | INITIALIZING | FAILURE | DISABLED | FROZEN | UPDATING
• --sort-by —— 排序字段（区分大小写）：GmtCreateTime（默认）| GmtModifiedTime
• --order —— 排序方向（全大写）：ASC（默认）| DESC
• --page-number / --page-size —— 分页参数
• --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} 端点（通过 SDK 或直接 HTTP 请求）

最佳实践

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

参考文档