huawei-cloud-cloudrobo-workspace

Windows / PowerShell： 示例使用 bash 语法。在 Windows PowerShell 中运行：

• 将 \ 行续接符合并为单行，或在行尾添加反引号。
• 使用 $env:NAME="value" 设置环境变量，而不是使用 export NAME="value"。
• 单引号括起来的 JSON '{"a":"b"}' 可直接使用。

概览 概述

cloudrobo-workspace 技能管理 CloudRobo 工作空间的完整生命周期。工作空间是基础资源容器——所有其他 CloudRobo 操作（数据集处理、模型训练、评估、推理等）都需要有效的 workspace_id。此技能涵盖工作空间 CRUD、成员管理（添加／列出／更新角色／删除）、工作空间概览统计，以及工作空间上下文切换（use／current）。

适用场景：

• 工作空间管理 — 创建、列出、查看、更新或删除工作空间
• 成员管理 — 添加成员、列出成员、更新成员角色、删除成员
• 上下文切换 — 通过 use 切换活动工作空间，通过 current 确认当前工作空间；其他所有技能（数据集、训练、评估、推理）都会从 ~/.cloudrobo/workspace.json 读取活动工作空间
• 概览与配额 — 查看工作空间容量、已用数量、可用数量和成员数量
• 入门设置 — 首次设置：创建工作空间 → 切换到该工作空间 → 开始使用其他技能

架构：

Agent / LLM
    │
    ├── CLI  →  cloudrobo workspace <command>
    ├── SDK  →  WorkspaceClient (Python)
                    │
                    ▼
              cloudrobo-service (REST API)
              /v1/workspaces/*
              /v1/workspaces/{workspace_id}/members/*
              /v1/workspaces/statistic/overview

所有操作都针对 cloudrobo-service 后端。工作空间是领域级（账户级）资源——工作空间操作本身无需 --workspace-id 覆盖选项。活动工作空间上下文存储在 ~/.cloudrobo/workspace.json 中，供其他所有技能使用。

前置条件 前置条件

CLI 安装、AK/SK 身份验证和初始配置请参阅 references/cli-installation-guide.md。工作空间是入门设置时首先使用的技能——请先创建工作空间并运行 cloudrobo workspace use，再使用其他任何 cloudrobo 技能。

工作流 工作流

入门工作流（首次设置）首次设置

1. 验证凭据 — 确保已设置 HUAWEI_CLOUD_AK／HUAWEI_CLOUD_SK
2. 列出现有工作空间 — cloudrobo workspace list（可能已存在默认工作空间）
3. 创建工作空间（如有需要）— cloudrobo workspace create --name <name> --default-obs-path <obs://...>
4. 切换到工作空间 — cloudrobo workspace use --workspace-id <id>（验证并保存上下文）
5. 验证 — cloudrobo workspace current（显示活动工作空间配置）
6. 继续 — 现在，其他技能（数据集、训练、评估、推理）将使用活动工作空间

标准工作流（工作空间 CRUD）工作空间管理

1. 创建 — cloudrobo workspace create --name <name> --default-obs-path <obs://...> [--description ...] [--tags ...] [--member-list ...]
2. 列出 — cloudrobo workspace list [--limit N] [--offset N]（返回工作空间 + page_info + last_count）
3. 查看 — cloudrobo workspace show --workspace-id <id>（返回完整详情，包括 asset_catalog_id）
4. 更新 — cloudrobo workspace update --workspace-id <id> [--name ...] [--description ...] [--tags ...] [--owner-id ...]
5. 删除 — cloudrobo workspace delete --workspace-id <id>（不可撤销；会触发异步清理）

成员管理工作流 成员管理

1. 列出成员 — cloudrobo workspace list-members --workspace-id <id>
2. 添加成员 — cloudrobo workspace add-members --workspace-id <id> --member-list '<json>'
3. 更新成员角色 — cloudrobo workspace update-member --workspace-id <id> --user-id <uid> --role-ids <r1,r2>
4. 删除成员 — cloudrobo workspace delete-members --workspace-id <id> --user-ids <u1,u2>

概览工作流 概览统计

1. 获取概览 — cloudrobo workspace overview（返回 workspace_capacity、workspace_used、workspace_available、member_capacity、member_count）

工作空间切换工作流

1. 切换 — cloudrobo workspace use --workspace-id <id>（验证工作空间，并将其保存到 ~/.cloudrobo/workspace.json）
2. 验证 — cloudrobo workspace current（显示已保存的工作空间配置）

CLI 命令格式标准

cloudrobo workspace <command> [OPTIONS]

功能	描述	示例
命令组	workspace	cloudrobo workspace
子命令	kebab-case	create、list、show、add-members
工作空间 ID	--workspace-id <id>	--workspace-id c1d2e3f4-a5b6-7890-cdef-901234567890
输出格式	JSON 输出到 stdout	out(result)
试运行	--dry-run（create/update/delete）	执行前预览
OBS 策略绑定	--bind-obs-policy（仅 update）	仅绑定 OBS 存储桶策略；不更新其他字段
逗号分隔列表	--user-ids id1,id2,id3	--user-ids aaa,bbb
JSON 字符串	--member-list '<json>'	--member-list '[{"user_id":"u1","role_ids":["r1"]}]'
标签	--tags tag1,tag2（以逗号分隔）	--tags dev,internal

核心命令

工作空间管理

创建工作空间

cloudrobo workspace create --name <workspace-name> --default-obs-path <obs://bucket/path> [--description <description>] [--tags <tag1,tag2>] [--member-list '<json>'] [--dry-run]

• SDK： client.create_workspace(req: dict)
• API： POST /v1/workspaces

必填字段：name（3-64 个字符，格式：^[\u4e00-\u9fa5a-zA-Z0-9-_./]{3,64}$）、 default_obs_path（obs:// 协议，最多 512 个字符）。可选字段：description（最多 512 个字符）、 tags（最多 10 个，每个 1-16 个字符）、member_list（最多 100 位成员）。完整的字段映射和验证规则请参阅 references/workspace-config-catalog.md。

创建时的服务端操作：检查名称是否唯一 → 检查工作空间配额 → 创建工作空间实体 → 绑定 OBS 存储桶策略 → 创建资源目录 → 写入数据库 → 添加管理员（如果是非 root 用户）→ 创建默认配额 → 添加成员（如果提供）。

列出工作空间

cloudrobo workspace list [--limit <n>] [--offset <n>]

• SDK： client.list_workspaces(limit=..., offset=...)
• API： GET /v1/workspaces?limit=<n>&offset=<n>

返回：workspaces（列表）、page_info（total、current_count、offset）、last_count （剩余工作空间配额）。如果不存在名为 "default" 的默认工作空间，则首次列出时会自动创建。

显示工作空间详情

cloudrobo workspace show --workspace-id <workspace-id>

• SDK： client.show_workspace(workspace_id: str)
• API： GET /v1/workspaces/{workspace_id}

返回：完整的工作空间详情，包括 workspace_id、name、description、 asset_catalog_id、default_obs_path、domain_id、owner_id、owner（名称）、 create_at、update_at、tags、role_ids、repository_id。

更新工作空间

cloudrobo workspace update --workspace-id <workspace-id> [--name <new-name>] [--description <new-description>] [--tags <tag1,tag2>] [--owner-id <user-id>] [--default-obs-path <obs://...>] [--bind-obs-policy] [--dry-run]

• SDK： client.update_workspace(workspace_id: str, req: dict)
• API： PUT /v1/workspaces/{workspace_id}

可更新字段：name、description、tags（整体替换）、owner_id（转移所有权）、default_obs_path、bind_obs_policy（布尔标志——仅绑定 OBS 存储桶策略，不更新其他工作空间字段）。默认工作空间的 default_obs_path 只能设置一次（首次设置）；不允许对默认工作空间进行其他更新。

删除工作空间

cloudrobo workspace delete --workspace-id <workspace-id> [--dry-run]

• SDK： client.delete_workspace(workspace_id: str)
• API： DELETE /v1/workspaces/{workspace_id}

删除操作不可撤销。只有 root 用户或工作空间所有者可以删除。默认工作空间无法删除。删除时，服务端会创建异步清理任务。

成员管理

列出工作空间成员

cloudrobo workspace list-members --workspace-id <workspace-id>

• SDK： client.list_workspace_members(workspace_id: str)
• API： GET /v1/workspaces/{workspace_id}/members

返回：members（列表，包含 workspace_id、user_id、username、roles（role_id + role_name）、is_owner）、remain_count（剩余成员配额）。root 用户始终以 super_administrator 身份列出。

添加工作空间成员

cloudrobo workspace add-members --workspace-id <workspace-id> --member-list '<json>'

• SDK： client.add_workspace_members(workspace_id: str, req: dict)
• API： POST /v1/workspaces/{workspace_id}/members

必填：member_list JSON 数组，其中每个条目都包含 user_id（32 位十六进制，采用 IAM 项目 ID 格式）和 role_ids（UUID 列表，最多 10 个）。不能将根用户添加为成员。重复成员将被拒绝。默认工作空间不支持成员操作。

更新成员角色

cloudrobo workspace update-member --workspace-id <workspace-id> --user-id <user-id> --role-ids <role-id-1,role-id-2>

• SDK： client.update_workspace_member(workspace_id: str, req: dict)
• API： PUT /v1/workspaces/{workspace_id}/members

必填：user_id 和 role_ids。无法更新工作空间所有者的角色。默认工作空间不支持成员操作。

删除工作空间成员

cloudrobo workspace delete-members --workspace-id <workspace-id> --user-ids <user-id-1,user-id-2>

• SDK： client.delete_workspace_members(workspace_id: str, user_ids: list)
• API： DELETE /v1/workspaces/{workspace_id}/members?user_ids=<ids>

无法删除工作空间所有者。默认工作空间不支持成员操作。每次请求最多包含 20 个用户 ID（API 限制）／100 个用户 ID（CLI 限制）。

概览与统计

获取工作空间概览

cloudrobo workspace overview

• SDK： client.get_workspace_overview()
• API： GET /v1/workspaces/statistic/overview

返回：workspace_capacity（工作空间数量上限）、workspace_used（当前数量）、workspace_available（剩余数量）、member_capacity（成员数量上限，需要 BASIC 资源 SKU）、member_count（当前成员数，包含根用户）。

工作空间上下文

切换活动工作空间

cloudrobo workspace use --workspace-id <workspace-id>

验证工作空间是否存在且可访问，然后将以下信息保存到 ~/.cloudrobo/workspace.json：workspace_id、name、asset_catalog_id、default_obs_path。其他所有技能都会读取此文件以确定活动工作空间。

显示当前工作空间

cloudrobo workspace current

显示 ~/.cloudrobo/workspace.json 中保存的工作空间配置。如果未配置工作空间，则输出“未配置工作空间”。

参考文档

• CLI 安装指南 — cloudrobo CLI 的安装和配置
• IAM 策略 — 最小权限凭证模型
• API 路径 — 通过 SDK 源码发现的 REST API 路径
• 工作空间配置参考 — 字段映射、验证规则、角色系统、成员格式
• 数据流图 — Mermaid 数据流图
• 验证方法 — 验证方法详情
• 验收标准 — 验收标准

边界情况

场景	处理方式
缺少 workspace_id	操作因验证错误而失败；使用 cloudrobo workspace list 查找有效 ID
未找到工作空间	服务返回 WORKSPACE_NOT_EXIST_ERROR；通过 workspace list 验证 ID
默认工作空间	首次执行 list 时自动创建；无法删除；仅支持首次更新 default_obs_path；不支持添加、更新或删除成员
工作空间名称冲突	服务返回 WORKSPACE_NAME_EXIST 错误；同一域中的名称不区分大小写且必须唯一
工作空间配额超限	服务返回 WORKSPACE_EXCEED_NUM_LIMIT；通过 overview 检查容量；列表响应中的 last_count 显示剩余数量
将根用户设为成员	服务返回 ADD_ADMINISTRATOR_LIMIT_ERROR；根用户始终是 super_administrator
更新／删除工作空间所有者	服务返回 REQUEST_FORBIDDEN_ERROR；无法更改所有者的角色，也无法将所有者从成员中移除
转移所有权	update --owner-id <new-owner> — 新所有者必须是现有 IAM 用户；如果不是根用户，则必须是或成为具有 administrator 角色的工作空间成员
default_obs_path 格式	必须符合 ^obs://[a-z0-9\-]{3,63}/[^\s]+$；禁止使用 s3://
workspace_id 格式	必须是 UUID：^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
user_id 格式	必须是 32 位小写十六进制（IAM 项目 ID）：^[0-9a-z]{32}$
role_ids 格式	必须是 UUID 格式；根据角色缓存进行验证；每个成员最多 10 个
成员已存在	服务返回 WORKSPACE_MEMBER_HAS_EXIST
未找到成员	服务返回 WORKSPACE_MEMBER_NOT_EXIST
未设置 AK/SK	操作在 HTTP 签名步骤失败；设置 HUAWEI_CLOUD_AK/HUAWEI_CLOUD_SK
对无效 ID 执行 workspace use	CLI 捕获错误，输出“切换失败: ...”并以代码 1 退出
未配置时执行 workspace current	输出“未配置工作空间”（未配置工作空间）
标签完全替换	update --tags 会替换所有标签；要移除所有标签，请传入空字符串
删除会触发清理	服务会创建异步清理任务（CleanupService）；工作空间资源（OBS、目录、配额）将异步清理
asset_catalog_id	创建工作空间时自动创建（或为默认工作空间首次设置 default_obs_path 时创建）；存储在工作空间实体中；供资产／数据集技能使用
角色系统	有 3 个角色：super_administrator（sort=0，仅根用户）、administrator（sort=1）、member（sort=2）；role_ids 是从服务获取的动态 UUID
成员排序	成员按以下顺序排序：所有者优先，然后按角色排序值（super_administrator > administrator > member）
内部 API	/v1/internal/workspaces 用于服务间调用（无需 IAM 身份验证）；CLI/SDK 不使用
对象存储路径	必须使用 obs:// 协议；禁止使用 s3://
API 路径	来源于 SDK 源代码（client.py 中的 _url() 调用），而非推断得出
修改操作	create/update/delete/add-members/update-member/delete-members 应由用户确认
跨技能调用	此技能不会按名称调用其他技能；它为所有其他技能提供基础工作空间上下文
workspace.json 权限	文件以 0o600 权限创建（仅所有者可读写）
创建时的成员列表	使用 member_list 创建工作空间时，会自动排除创建者（不重复添加）

验证方法

规范合规验证

bash scripts/test-cli-commands.sh -s . -e cli

功能测试

# CLI / SDK (read-only cases TC-01..TC-10 / TC-19..TC-22 run automatically)
bash scripts/test-cli-commands.sh -s . -e {cli|sdk}

# Include mutation cases (TC-11..TC-18, TC-23..TC-28) — each prompts for confirmation
bash scripts/test-cli-commands.sh -s . -e {cli|sdk} -m

API 级验证需手动进行 — 在 API Explorer 中重放 references/api-paths.md 里的路径。

测试用例

完整的测试用例列表见 templates/test-vars.json，涵盖工作空间 CRUD、成员管理、概览和上下文切换场景。

验证清单

• 创建工作区后，通过 show --workspace-id <id> 验证 asset_catalog_id 已填充
• 执行 use --workspace-id <id> 后，验证 current 输出了正确的工作区配置
• 添加成员后，通过 list-members 验证新成员是否显示且角色正确
• 删除工作区后，验证它不再显示在 list 结果中
• 验证 overview 返回的 workspace_used 数量与 list 结果一致

最佳实践

• 创建新工作区前，始终先运行 workspace list 检查现有工作区
• 使用 create／update／delete 时，先添加 --dry-run 预览操作，再执行
• 创建工作区后，立即运行 workspace use --workspace-id <id> 切换上下文
• 删除工作区前，确认工作区 ID，以避免不可逆的删除
• 添加成员时，先使用 list-members 检查现有成员，避免重复添加
• 默认工作区（“default”）有特殊限制；生产环境中建议创建命名工作区
• 定期检查 workspace overview，监控工作区和成员配额的使用情况
• 运行其他 cloudrobo 命令前，可通过 workspace current 快速确认当前工作区
• 谨慎转移所有权：新所有者将获得工作区的完全控制权
• 更新时，标签会被完全替换，而非合并；请在更新命令中包含所有所需标签