alibabacloud-pai-dsw-manage：提供 PAI-DSW 实例的生命周期管理，包括创建、查询、更新、停止和启动。

PAI DSW 实例管理

管理阿里云 PAI DSW（数据科学工作台）实例的全生命周期——从开通到配置变更、状态监控和启停操作。也支持查询可用的 ECS 计算规格。

架构：PAI 工作空间 + DSW 实例 + ECS 规格 + 镜像 + VPC + 数据集

API 版本：pai-dsw/2022-01-01

安装

前置检查：需要 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 CLI 插件
[必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[必须] 运行 aliyun plugin update 确保已有插件始终为最新版本。

macOS（推荐）

brew install aliyun-cli

验证版本（>= 3.3.3）

aliyun version

启用插件自动安装

aliyun configure set --auto-plugin-install true

更新已有插件

aliyun plugin update

安装 pai-dsw 插件

aliyun plugin install --names pai-dsw

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

---

鉴权

前置检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用字面凭证值运行 aliyun configure set
- 只使用 aliyun configure list 检查凭证状态
```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。

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

参数确认

重要：参数确认 —— 执行任何命令或 API 调用前，所有用户可自定义的参数（例如 RegionId、实例名、CIDR 块、密码、域名、资源规格等）都必须与用户确认。未经用户明确批准，不要假设或使用默认值。

如何获取 WorkspaceId：如果用户不知道其工作空间 ID，运行：
```bash
aliyun aiworkspace list-workspaces --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage
```
这将返回用户可访问的所有工作空间。根据 WorkspaceName 选择合适的，或请用户确认。
参考：创建和管理工作空间

核心工作流

完整命令语法和参数细节：references/related-commands.md。

1. 查询可用 ECS 规格

运行 aliyun pai-dsw list-ecs-specs --accelerator-type <CPU|GPU> --region <region> 列出可用计算规格。

[必须] 地域确认：--region 参数必填。规格可用性因地域而异——查询前始终与用户确认地域。

[必须] 正确判断加速器类型：
- 用户提到规格名（例如 ecs.hfc6.10xlarge）：查询 CPU 和 GPU 两种类型，然后匹配结果中的 InstanceType。用返回的 AcceleratorType 字段确认分类。
- 用户指定镜像类型：GPU 镜像 URL（含 -gpu- 或 cu）→ 查询 GPU 规格；CPU 镜像 URL → 查询 CPU 规格。
- 用户仅描述用例：GPU 用于大模型训练 / 深度学习，CPU 用于数据分析 / 轻量任务。如有歧义，始终与用户确认。
- [重要] 不要从规格名前缀猜测 —— 命名约定不可靠。始终通过 API 响应验证。

[必须] 根据用户需求选择加速器类型：
- 默认推荐：GPU 用于大模型训练 / 深度学习，CPU 用于数据分析 / 轻量任务
- 匹配镜像类型（强指示）：如果用户指定 GPU 镜像 URL（含 -gpu- 或 cu），查询 GPU 规格。如果是 CPU 镜像，查询 CPU 规格。
- 规格名需要验证：如果用户提到规格名，查询两种类型并在结果中找到匹配
- 如果用例有歧义且未提供规格名，查询前始终与用户确认

关键响应字段：

• InstanceType：规格名（例如 ecs.hfc6.10xlarge）
• AcceleratorType：CPU 或 GPU —— 来自 API 的实际分类
• IsAvailable：主要指标 —— true 表示该规格可用于按量付费 / 包年包月
• SpotStockStatus：次要指标 —— 仅用于抢占式实例：WithStock（可用）或 NoStock（不可用）
• CPU / Memory / GPU / GPUType：硬件详情
• Price：以人民币计的每小时价格

[必须] 可用性检查逻辑：
- 对于按量付费 / 包年包月：检查 IsAvailable == true
- 对于抢占式实例：检查 IsAvailable == true 且 SpotStockStatus == "WithStock"
- 不要仅用 SpotStockStatus 判断可用性——许多规格 IsAvailable: true 但 SpotStockStatus: "NoStock"
- 示例：ecs.hfc6.10xlarge 带 IsAvailable: true, SpotStockStatus: "NoStock" → 可用于按量付费

2. 创建实例（先检查后执行）

[必须] 幂等性保证：CreateInstance API 不支持 ClientToken，因此通过先检查后执行模式保证幂等性。创建前，你必须调用 list-instances --instance-name <name> 检查名称是否已存在。

步骤 2.1 —— 检查是否存在

aliyun pai-dsw list-instances \
  --instance-name <name> \
  --region <region> \
  --resource-id ALL \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage

决策逻辑：

• TotalCount == 0 → 名称可用，进入步骤 2.2 创建
• TotalCount >= 1 → [必须] 验证精确名称匹配：

1. 遍历返回的 Instances 数组
2. 对每个实例，将其 InstanceName 字段与目标名称逐字符比较（大小写敏感，精确字符串匹配）
3. 找到精确匹配（instance.InstanceName === targetName）→ 名称已存在：

• 从匹配实例提取 InstanceId
• 调用 get-instance --instance-id <id> 获取完整详情
• 比较关键参数（EcsSpec、ImageUrl、Accessibility 等）
• 匹配 → 返回现有 InstanceId，不要重建
• 不匹配 → 请用户选择其他名称

1. 未找到精确匹配（没有实例的 InstanceName === targetName）→ 名称可用，进入步骤 2.2 创建

[警告] 关键：需要精确名称匹配
--instance-name 过滤可能返回部分匹配。例如：
- 查询：--instance-name llm_train_001
- 响应可能包含：llm_train_001、llm_train_001_v2、llm_train_001_backup
你必须验证精确匹配，通过检查：
```
for instance in response.Instances:
if instance.InstanceName == targetName: # 精确字符串相等
# 名称已存在——不要创建
```
不要因为 TotalCount > 0 但你"认为"没有精确匹配就假设名称可用。如果 TotalCount >= 1，仔细检查每个实例的 InstanceName 字段。

步骤 2.2 —— 开通

运行 aliyun pai-dsw create-instance，带必需参数：--workspace-id、--instance-name、--ecs-spec、--region，以及 --image-url 或 --image-id 之一。

[必须] 地域确认：--region 参数必填，且必须与用户确认。未经用户明确批准，不要使用 CLI 默认地域。规格可用性和定价因地域而异。

[必须] 将 EcsSpec 与镜像类型匹配：
- GPU 镜像 URL（含 -gpu- 或 cu）→ 必须选择 GPU 规格（例如 ecs.gn6v-c4g1.xlarge）
- CPU 镜像 URL（含 -cpu-）→ 必须选择 CPU 规格（例如 ecs.c6.large）
- 规格类型必须匹配镜像类型，否则实例将无法启动
- 用例（大模型训练 / 数据分析）仅供参考，镜像类型是决定性指标

数据集挂载（可选）：如果用户指定要挂载的数据集，使用 CLI 列表格式的 --datasets 参数：
```bash
--datasets DatasetId=<dataset-id> MountPath=<mount-path> MountAccess=RO
```
[必须] 数据集参数需要用户明确确认——不要假设或自动生成数据集配置。
官方镜像：references/common-images.md。
高级用法（VPC、数据集）：references/related-commands.md。

响应：{"InstanceId": "dsw-xxxxx", ...}

[重要] 创建后立即返回：create-instance 返回 InstanceId 后，不要阻塞等待 Running 状态。而是：
1. 立即将 InstanceId 和当前状态（Creating）返回给用户
2. 向用户提供稍后检查状态的命令：
```bash
aliyun pai-dsw get-instance --instance-id <instance-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage
```
3. 告知用户实例启动通常需要 2–5 分钟
为什么重要：阻塞轮询会阻止 agent 响应其他用户请求。DSW 实例创建是长时间运行操作；agent 应及时将控制权交还用户。

3. 列出实例

运行 aliyun pai-dsw list-instances。按 --workspace-id 或 --status 过滤；用 --page-number / --page-size 分页。

4. 获取实例详情

运行 aliyun pai-dsw get-instance --instance-id <id> 检查实例状态和详情。

何时轮询：仅当用户明确要求等待状态变化时（例如"等到它运行"）才轮询。否则立即返回当前状态。
超时限制：最多 60 次轮询（共 30 分钟）。超过则停止并提示用户手动检查。
轮询间隔：调用之间 10–30 秒。
CLI 超时：对于长时间运行操作，增加读取超时：
```bash
aliyun pai-dsw get-instance --instance-id <id> --read-timeout 30 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage
```
一旦 Status == "Running"，通过 InstanceUrl 访问实例。
完整状态转换见 references/related-commands.md 中的 Instance Status Values。

5. 停止实例

运行 aliyun pai-dsw stop-instance --instance-id <id>。

状态转换：Running → Stopping → Stopped
保存环境镜像：要在停止前将环境保存为自定义镜像，使用 PAI 控制台。说明见 创建 DSW 实例镜像。

6. 更新实例

运行 aliyun pai-dsw update-instance --instance-id <id> 修改 --instance-name、--ecs-spec、--image-id、--accessibility、--datasets 等。

[必须] 更新前：
1. 调用 get-instance 检查当前状态和配置
2. 检查是否需要更新：
- 对于 --ecs-spec：比较当前 EcsSpec 与目标规格。若已相等，跳过更新并告知用户
- 对于 --image-id/--image-url：比较当前 ImageId/ImageUrl 与目标
- 对于 --instance-name：比较当前 InstanceName 与目标
3. 若已处于目标配置，返回当前实例信息——不要调用 update-instance
4. 若需要更新，用 --start-instance true 在更新后自动启动
[重要] 始终按其 InstanceId 更新指定实例。不要用另一个已有目标规格的实例替代——用户的请求是升级特定实例，不是找替代方案。

7. 启动实例

运行 aliyun pai-dsw start-instance --instance-id <id>，然后轮询（步骤 4）直到 Running。

前置条件：实例必须处于 Stopped 或 Failed 状态。启动前调用 get-instance 确认。

成功验证

完整验证步骤：references/verification-method.md。

快速检查：get-instance 应返回 Status == "Running" 且 InstanceUrl 非空。

清理

本 Skill 不暴露实例删除（不可逆操作——使用控制台）。
要停止产生费用，通过步骤 5（stop-instance）停止实例。

最佳实践

1. 创建前始终先检查后执行 —— 用 list-instances --instance-name <name> 避免重复实例错误。
2. 优先 PRIVATE 可见性 —— 防止其他工作空间用户误操作。
3. 更新前检查实例状态 —— 先调用 get-instance；某些参数需要 Stopped 状态，另一些可在 Running 时更新。
4. list-instances 用 --resource-id ALL —— 默认只返回后付费实例。
5. 遵守轮询超时限制 —— 超时和间隔指引见步骤 4。
6. 开通前验证规格可用性 —— 运行 list-ecs-specs 确认规格在目标地域可用。
7. 用 Labels 标记实例 —— 简化批量查询和生命周期管理。

参考