huawei-cloud-cloudrobo-workspace

Windows／PowerShell： 例では bash の構文を使用しています。Windows PowerShell で実行するには：

• \ による行継続を削除して1行にするか、行末にバッククォートを付けます。
• export NAME="value" の代わりに、$env:NAME="value" で環境変数を設定します。
• シングルクォートで囲んだ JSON '{"a":"b"}' はそのまま使用できます。

概要

cloudrobo-workspace スキルは、CloudRobo ワークスペースのライフサイクル全体を管理します。ワークスペースは基盤となるリソースコンテナーです。データセット処理、モデルのトレーニング、評価、推論など、その他すべての CloudRobo 操作には有効な workspace_id が必要です。このスキルでは、ワークスペースの CRUD、メンバー管理（追加／一覧表示／ロール更新／削除）、ワークスペースの概要統計、ワークスペースコンテキストの切り替え（use／current）を扱います。

適用シナリオ：

• ワークスペース管理 — ワークスペースの作成、一覧表示、詳細表示、更新、削除
• メンバー管理 — メンバーの追加、一覧表示、メンバーのロール更新、削除
• コンテキストの切り替え — use でアクティブなワークスペースを切り替え、current で現在のワークスペースを確認します。その他すべてのスキル（dataset、train、eval、infer）は、アクティブなワークスペースを ~/.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 スキルを使用する前に、ワークスペースを作成し、cloudrobo workspace use を実行してください。

ワークフロー

オンボーディングワークフロー（初回セットアップ）

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. 続行 — これで、その他のスキル（dataset、train、eval、infer）がアクティブなワークスペースを使用します

標準ワークフロー（ワークスペース 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	out(result)
ドライラン	--dry-run（作成／更新／削除）	実行せずにプレビューします
OBS ポリシーのバインド	--bind-obs-policy（更新のみ）	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 を参照してください。

作成時にサーバー側で実行される処理：名前の重複を確認 → ワークスペースのクォータを確認 → Workspace エンティティを作成 → 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 文字の 16 進数、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>

ワークスペース所有者は削除できません。デフォルトのワークスペースではメンバー操作をサポートして いません。1 リクエストあたり最大 20 個のユーザー ID（API の制約）／100 個（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 が未指定	操作は検証エラーで失敗します。有効な ID を確認するには、cloudrobo workspace list を使用してください
ワークスペースが見つからない	サーバーは 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 文字の小文字の 16 進数（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 です
メンバーの並べ替え	メンバーは、所有者を先頭にし、その後ロールの sort 値（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 に記載されたパスを再実行してください。

テストケース

ワークスペースの CRUD、メンバー管理、概要、コンテキスト切り替えのシナリオを網羅したテストケースの全リストについては、templates/test-vars.json を参照してください。

検証チェックリスト

• ワークスペースの作成後、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 を確認します
• workspace current は、ほかの cloudrobo コマンドを実行する前にアクティブなワークスペースを確認する手軽な方法です
• 所有権の移譲は慎重に行ってください。新しい所有者はワークスペースを完全に制御できるようになります
• 更新時にタグは統合されず、すべて置き換えられます。更新コマンドには、設定したいタグをすべて含めてください