huawei-cloud-cloudrobo-robot

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

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

概要

cloudrobo-robot スキルは、CloudRobo ロボットインスタンスのライフサイクル全体を管理します。ロボットは、具現化知能タスクを実行する物理的な担い手であり、HUMANOID（人形）、QUADRUPED（四足）、ARM（ロボットアーム）、OPERATION（作業）、WHEELED（車輪型）、OTHER（その他）の6種類をカバーします。このスキルでは、ロボットの登録、一覧／詳細の照会、メタデータの更新、オフラインデバイスの削除、証明書のエクスポート（ロボット側からプラットフォームへ安全にアクセスするため）、および最新のロボット側 SDK パッケージの取得（ソフトウェアのアップグレード用）を行います。

対象シナリオ：

• ロボット登録 — 新しいロボットを登録します（作成 → 一覧表示 → 詳細表示）。タイプ／モデル／ワークスペースを確認します
• ロボット検索／運用保守 — 稼働中／オフラインのロボットを照会します。list → show の順に実行して、ステータスと属性を確認します
• 証明書のエクスポートとアクセス — ロボットを表示し、export-certificate でロボットの アクセス設定 をエクスポートします → zip バンドルをファイルに書き込み、安全に保管してロボット側のオンボーディングに使用します
• SDK アップグレードの照会 — show-sdk で最新のロボット側 SDK パッケージを取得します（file_name/version/signed_url）
• スキル間の連携 — 登録済みのロボットは、後から robo-dispatcher（タスクのディスパッチには robot_id が必要です）や、cloudrobo-infer を通じてデプロイされた具現化サービスを実行するロボットから参照できます。

アーキテクチャ：

Agent / LLM
    │
    ├── CLI  →  cloudrobo robot <command>
    └── SDK  →  RobotClient (Python)
                    │
                    ▼
              cloudrobo-service (REST API)
              /v1/robots/*

すべての操作は cloudrobo-service バックエンドを対象とし、有効な workspace_id が必要です（明示的に指定しない限り、デフォルトのワークスペースが使用されます）。ロボットのメタデータ管理はアセットレベルの操作のみであり、コンピューティング料金は発生しません。証明書のエクスポートでは、ユーザーが指定したパスワードで保護されたバイナリコンテンツが返されます。

前提条件

• CLI のインストール、AK/SK 認証、ワークスペースの設定については、references/cli-installation-guide.md を参照してください。
• ロボットの作成／一覧表示／更新には、有効な workspace_id（デフォルトのワークスペース、または明示的に指定した --workspace-id）が必要です。
• ロボットには r2c_sdk が適用されている必要があります。export-certificate を使用して、ロボット側のオンボーディングに使う アクセス設定（アクセス設定 zip／認証情報バンドル） を生成します。本体設定 はすでに r2c_sdk に組み込まれているか、ロボットアダプターとともに配布されます。これは export-certificate がダウンロードするものではありません。

ワークフロー

自然言語優先の原則

以下の各ワークフローは、手動で CLI/SDK を操作する方法ではなく、ユーザーの意図（1～2文）から始まります。その後、このスキルが対応するコマンドチェーンを実行し、状態を報告します。

ロボット登録ワークフロー（モジュール + ワークスペース + アセット）

シナリオ：ユーザーが新しいロボットを登録してオンボーディングする場合です。

1. ロボットの識別情報を確認 — 名前、タイプ（HUMANOID/QUADRUPED/ARM/OPERATION/WHEELED/OTHER）、メーカー、robot_model が指定されていない場合はそれらをユーザーに尋ねます。robot_type が有効な大文字の列挙値であることを確認します。
2. ワークスペースを特定 — cloudrobo workspace current でワークスペースを確認するか、ユーザーに workspace_id を尋ねます。ロボットの作成／一覧表示にはワークスペースのコンテキストが必要です（ワークスペースは基盤となるリソースコンテナです）。
3. ロボットを登録 — cloudrobo robot create --name <name> --type <TYPE> --manufacturer <mfg> --robot-model <model> --workspace-id <ws>。送信前に設定を確認します。返された robot_id を出力します。
4. 確認 — cloudrobo robot list --name <name> または cloudrobo robot show --robot-id <id> を実行し、登録と現在のステータスを確認します。
5. 案内 — 登録後、オンボーディングの手順として、証明書のエクスポートとロボット SDK の提供を提案します。

アセットに関する注意：robot_model/manufacturer はロボットのモデルを一意に識別します。これらをハードコードしないでください。ユーザーまたは以前の照会結果から取得してください。

ロボットの検索／運用・保守ワークフロー（モジュール＋ワークスペース）

シナリオ：「検査ロボットはオンラインですか？」／「このワークスペース内のすべてのロボットを一覧表示してください。」

1. ロボットの一覧表示 — cloudrobo robot list [--workspace-id <ws>] [--status <status>] [--type <TYPE>] ページネーション（--limit／--offset）と並べ替え（--sort）に対応した概要を取得します。
2. 絞り込み — 必要に応じて、--name、--manufacturer、--robot-model、--type、 --status、--user-id、--user-nameで絞り込みます。
3. 詳細の表示 — cloudrobo robot show --robot-id <id>で設定の完全なスナップショット（ハードウェアモデル、現在のステータス）を取得します。クライアントはバックエンドのステータス（REGISTERED/OFFLINE/ONLINE...）をそのまま返します。 ローカルのステートマシンは保持しません。
4. 報告 — ステータスと主要な属性（type、manufacturer、robot_model、status）をユーザーに出力します。
5. 案内 — ステータスに基づき、オフラインのロボットには更新または削除を提案し、オンラインのロボットはディスパッチ／実行の対象として利用できます。

ロボットの更新ワークフロー（モジュール）

シナリオ：「ロボット X の名前を変更してください」／「説明を更新してください。」

1. ロボットの確認 — cloudrobo robot show --robot-id <id>で存在を確認し、現在のメタデータを取得します。
2. 更新 — cloudrobo robot update --robot-id <id> [--name <name>] [--description <desc>] [--workspace-id <ws>]を実行します。実行前に確認してください（変更を伴う操作）。
3. 確認 — cloudrobo robot show --robot-id <id>でフィールドが変更されたことを確認します。

証明書／アクセス設定のエクスポートワークフロー（モジュール＋セキュリティ）

「配置ファイルをエクスポートする」= 接続設定（証明書）をエクスポートすることです。ロボットには2 種類の設定があります。

• 本体設定（ロボット本体／メイン設定） — r2c_sdk に組み込まれているか、ほかのロボットとともにロボットアダプターに同梱されています。これは「設定のダウンロード／エクスポート」が指すものではありません。
• 接続設定（アクセス設定） — プラットフォームへの接続に使用するロボットのアクセス認証情報一式です。ダウンロード／エクスポートするのはこちらで、export-certificate によって生成されます。

ダウンロードしたアクセス設定は zip パッケージです。機密性の高い認証情報一式として扱い、安全に保管してください（ソース管理、共有ドライブ、暗号化されていない場所への保存は避けてください）。

シナリオ：「セキュアなオンボーディングのために、このロボットのアクセス証明書／接続設定ファイルをエクスポートする」

1. ロボットをリアルタイムで確認する — cloudrobo robot show --robot-id <id> を実行して、ロボットの存在を確認し、現在の status を調べます。エクスポートは単発のジョブであるため、エクスポート時にロボットで実行中のジョブがあってはなりません。ロボットの状態は動的です。以前は INACTIVE／アイドル状態だったロボットが、現在は OFFLINE／ONLINE になっていたり、実行中のジョブがあったりする場合があるため、エクスポートの直前に必ず show で再確認してください。
2. アクセス設定（証明書）をエクスポートする — cloudrobo robot export-certificate --robot-id <id> [--password <pwd>] --output <directory>。 バックエンドはアクセス設定の zip バイナリを返します。CLI はファイル名を cert_config_{robot_name}_{timestamp}.zip として自動生成し（名前には show_robot を照会し、タイムスタンプには datetime.now().strftime("%Y%m%d%H%M%S") を使用）、--output ディレクトリにバイナリ（wb）モードで書き込みます。--password は任意、--output は必須で、既存のディレクトリを指定する必要があります。
   • エクスポート時に CloudRobo.04010007 "The robot can only have one running job." が返された場合（HTTP 400。エラーコードはローカル SDK ではなくバックエンドの動作に基づくもので、バックエンドでは検証済み、実環境での確認待ち）： 現在、ロボットでジョブ（ディスパッチ／デバッグタスク）が実行中か、その他の理由で新しいエクスポートジョブを開始できない状態です。状態は動的であるため、以前は問題なくエクスポートできたロボット（たとえば INACTIVE だったロボット）も、今回は実行中のジョブがある OFFLINE／ONLINE 状態になって失敗する場合があります。show で再確認し、実行中のジョブがないロボット（たとえば INACTIVE／アイドル状態のロボット）を選ぶか、現在のジョブが完了するまで待ってから再試行してください。エクスポートの失敗を「証明書が利用できない」とみなして、空または不完全なファイルを使い続けてはいけません。使用前に、出力ファイルが空でない zipであることを確認してください。
3. 安全に保管する — エクスポート後、ダウンロードした zip を安全な保管場所（保護されたディレクトリ、シークレットマネージャー、またはロボット側のオンボーディング用の場所）に移動します。共有パスや誰でも読み取れるパスに置いたままにしないでください。この zip は、SDK またはアダプターにすでに含まれている本体設定とともに、ロボット側（たとえば r2c_sdk ／R2C クライアント）で使用されます。
4. フィードバック — アクセス設定の zip が指定されたファイルに書き込まれたこと、およびロボット側のアクセス設定（たとえば r2c_sdk.cloudroboclient を使用）に利用できることをユーザーに伝えます。
5. セキュリティに関する注意 — 実行手順書では機密情報（パスワード／パス）をマスキングします。パスワードをそのまま出力せず、エクスポートした zip は認証情報として扱ってください。

ロボット SDK のアップグレードワークフロー（モジュール）

シナリオ：「ロボット側 SDK の最新バージョンを教えてください」

1. SDK を照会する — cloudrobo robot show-sdk（パラメーターなし）。
2. 報告する — ロボットがアップグレードパッケージを取得するための file_name、version、signed_url を出力します。

複合ワークフロー A — ロボットを登録 → モデルをデプロイ → タスクを割り当てる（ロボット + 推論 + 割り当て）

シナリオ：「ロボットを登録し、認識モデルを推論サービスとしてデプロイして、そのモデルを使用するタスクをロボットで実行します。」

1. Robot Registration Workflow の手順に従ってロボットを登録し、返された robot_id を記録します。
2. ロボットがオンラインであることを確認します（robot show --robot-id <id>）。
3. cloudrobo-infer を介してモデルを推論サービスとしてデプロイします（infer deploy-and-wait）。 service_id / exec_model_id を記録します。
4. robot_id とモデルを robo-dispatcher に渡します：cloudrobo dispatch create-task --session-id <sid> --name <name> --task "<task>" --constraints-json '{"model":{"exec_model_id":"<exec_model_id>"},"robot_id":"<robot_id>","exec_constraints":{"max_run_time":10,"max_iter_num":100}}'。

   このスキルは cloudrobo-infer / dispatch を名前で呼び出しません。エージェントは、まずここで robot_id を取得し、次に推論と割り当てのスキルを使用して、スキル間のオーケストレーションを行います。

クリーンアップワークフロー（モジュール）

シナリオ：「この廃止されたロボットを削除します。」

1. ロボットを確認します — cloudrobo robot show --robot-id <id> を実行して、安全に削除できることを確認します（削除は取り消せません。バックエンドは実行状態と業務上の依存関係を検証します）。
2. 削除します — cloudrobo robot delete --robot-id <id>。実行前に確認してください。
3. 検証します — cloudrobo robot show --robot-id <id> → ResourceNotFoundError / not found が返ることを確認します。

CLI コマンド形式の標準

cloudrobo robot <command> [OPTIONS]

機能	説明	例
コマンドグループ	robot（エントリーポイント経由で登録）	cloudrobo robot
サブコマンド	ケバブケース	create、export-certificate、show-sdk
ワークスペース	--workspace-id <id>（create/list/update）	--workspace-id abc-123
出力形式	標準出力への JSON	out(result)
JSON パラメーター	個別のフラグとして渡します（例：--name、--type、--manufacturer、--robot-model）	create --name r1 --type HUMANOID --manufacturer M --robot-model X
ドライラン	--dry-run（create/update/delete/export-certificate で使用）	実行せずにプレビュー
バイナリー出力	--output <directory>（export-certificate）	ディレクトリ内に cert_config_{name}_{timestamp}.zip を自動生成

完全な網羅性：SDK には 7 つのメソッドが公開されており、CLI には 7 つのコマンドがあります（不足なし）。 網羅性の全体表については、references/robot-config-catalog.md を参照してください。

コアコマンド

SDK の直接呼び出し：CLI が不便な場合（動的な JSON、パッケージをまたぐクエリ）は、Python SDK を直接使用します。RobotClient は以下の 7 つのメソッドを公開しています。

ロボットの作成／登録

cloudrobo robot create --name <robot-name> --type HUMANOID --manufacturer "Manufacturer A" --robot-model "Model X" --workspace-id <workspace-id> [--description "inspection robot"] [--dry-run]

# SDK
from cloudrobo_core.sdk import Config, HttpClient
from cloudrobo_robot import RobotClient

config = Config()
http_client = HttpClient(config)
client = RobotClient(http_client)

robot = client.create_robot({
    "name": "inspection-robot-001",
    "type": "HUMANOID",
    "manufacturer": "Manufacturer A",
    "robot_model": "Model X",
    "workspace_id": config.workspace_id,
    "description": "inspection robot for factory floor"
})
print(robot)  # includes robot_id

ロボット一覧の取得

cloudrobo robot list [--limit 10] [--offset 0] [--status <status>] [--type <TYPE>] [--workspace-id <ws>]

robots = client.list_robots(name="inspection-robot-001")
for r in robots.get("items", []):
    print(r["name"], r["type"], r["status"])

ロボットの詳細表示

cloudrobo robot show --robot-id <robot-id>

robot = client.show_robot("<robot-id>")
print(robot["name"], robot["type"], robot["manufacturer"], robot["status"])

ロボットの更新

cloudrobo robot update --robot-id <robot-id> --description "new description" [--dry-run]

client.update_robot("<robot-id>", {"description": "new description"})

ロボットの削除

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

client.delete_robot("<robot-id>")

ロボット接続設定／証明書のエクスポート

cloudrobo robot export-certificate --robot-id <robot-id> [--password <password>] --output <directory> [--dry-run]
# Output: <directory>/cert_config_{robot_name}_{timestamp}.zip

# Returns the access-config zip binary content
cert = client.export_robot_certificate("<robot-id>", {"password": "<password>"})
# CLI auto-generates filename and writes binary to --output directory in wb mode

このコマンドは、ロボットがプラットフォームへの接続に使用する認証情報一式である、ロボットの 接続設定（access config / certificate） をエクスポートします。これは zip パッケージです。CLI はファイル名を cert_config_{robot_name}_{timestamp}.zip として自動生成し、--output ディレクトリに書き込みます。zip ファイルは安全に保管してください。--password（一式を暗号化する）は任意です。--output（エクスポート先ディレクトリ。存在している必要があります）は必須です。Certificate / Access-Config Export Workflow を参照してください。

最新のロボット SDK の表示

cloudrobo robot show-sdk

sdk = client.show_sdk()
print(sdk["file_name"], sdk["version"], sdk["signed_url"])

パラメーターの確認

パラメーター	入力元	必須	確認事項
--name	ユーザー	はい（作成時）	作成前に一意性と説明の分かりやすさを確認
--type	ユーザー	はい（作成時）	大文字の列挙値：HUMANOID/QUADRUPED/ARM/OPERATION/WHEELED/OTHER
--manufacturer / --robot-model	ユーザー	はい（作成時）	ロボットモデルを一意に特定
--workspace-id	ユーザーまたはデフォルトのワークスペース	はい（作成／一覧表示／更新時）	—
--robot-id	ユーザーまたは以前のコマンド出力	はい（表示／更新／削除／エクスポート時）	更新／削除の前に確認
--password	ユーザー	いいえ（export-certificate、デフォルトは None）	任意。アクセス設定の zip を暗号化します。マスクされ、エコーバックされません
--output	ユーザー	はい（export-certificate）	必須。自動生成される cert_config_{name}_{timestamp}.zip の書き込み先ディレクトリ
--status/--type フィルター	ユーザー	いいえ（一覧表示）	—
--dry-run	—	いいえ	送信せずにプレビュー

変更を伴う操作（create/update/delete/export-certificate）の実行前に、ユーザーに確認を求める必要があります。

参考資料

• CLI インストールガイド — cloudrobo CLI のインストールと設定
• IAM ポリシー — 最小権限の認証情報とアクセスモデル
• 検証方法 — 検証方法の詳細
• データフロー図 — Mermaid データフロー図
• 受け入れ基準 — 受け入れ基準
• ロボット設定リファレンス — RobotDto のフィールド、type 列挙値、ステータス、証明書のエクスポート、SDK 情報、SDK／CLI 対応マトリックス

エッジケース

シナリオ	対応
workspace_id がない	create/list/update はデフォルトのワークスペースにフォールバックできます。存在しない場合は、提案を添えてエラーになります
無効な robot_type	create は HUMANOID/QUADRUPED/ARM/OPERATION/WHEELED/OTHER 以外の値を拒否します
ロボットが見つからない	show/update/delete は ResourceNotFoundError を返します。robot_id を確認してください
パストラバーサル	validate_safe_id(robot_id) は ../ の入力をブロックします
証明書のエクスポート失敗	パスワードが正しいこと、およびロボットに有効な証明書があることを確認してください。CloudRobo.04010007 "The robot can only have one running job"（バックエンドで確認済み、実環境での確認待ち）の場合、ロボットで実行中のジョブがあります。実行中のジョブがない INACTIVE／アイドル状態のロボットで再試行するか、現在のジョブが終了するまで待ってください
証明書出力の破損	CLI は wb モードでバイナリを書き込みます。テキストエンコードで書き込まないでください
アクセス設定（zip）の保管	エクスポートされるアクセス設定はzip 形式の認証情報バンドルです。安全に保管し、コミットしたり一般公開したりしないでください
SDK の取得失敗	バックエンドで SDK パッケージが公開されていることを確認し、show-sdk を再試行してください
ワークスペースのテナント間アクセス	API は workspace_id を渡し、バックエンドが所有権を検証します
実行中のロボットの削除	バックエンドはステータスと業務上の依存関係を検証します。拒否される場合があります
削除は取り消し不可	削除前に必ず robot_id を確認してください
AK/SK が未設定	HTTP 署名の段階で操作が失敗します。HUAWEI_CLOUD_AK/HUAWEI_CLOUD_SK を設定してください
robot_id／モデルの値	ハードコードせず、ユーザーまたは list/show の結果から取得してください
API パス	推測せず、OpenAPI YAML（robo-operations.yaml）と機能設計から取得します
スキル間の呼び出し	このスキルは他のスキルを名前で呼び出しません。dispatch/infer が使用する可能性のある robot_id を生成するだけです
変更を伴う操作	create/update/delete/export-certificate はユーザーに確認してください

検証方法

仕様準拠の検証

bash scripts/test-cli-commands.sh

機能テスト

bash scripts/test-cli-commands.sh

テストケース

登録、検索、更新、削除、証明書のエクスポート、SDK の照会、安全性のシナリオを網羅するテストケースの一覧は、templates/test-vars.json を参照してください。

検証チェックリスト

• create の実行後、list --name ／ show --robot-id で、ロボットが正しい種類とステータスで表示されることを確認します
• update の実行後、show に変更後の名前と説明が反映されていることを確認します
• delete の実行後、show が「見つかりません」を返すことを確認します
• export-certificate の実行後、出力ディレクトリに、アクセス設定バイナリを含む自動生成ファイル cert_config_{name}_{timestamp}.zip があることを確認します
• show-sdk が file_name/version/signed_url を返すことを確認します
• パストラバーサル（../）が validate_safe_id によってブロックされることを確認します
• 変更を伴う操作では、実行前にユーザーへの確認を求めます

ベストプラクティス

• create／update／delete／export-certificate の前に、必ず robot_id と設定全体を確認します
• 実際に送信する前に --dry-run を使用して、create/update/export のパラメーターを検証します
• パストラバーサルを防ぐため、validate_safe_id を利用する CLI を使用します。ユーザー入力をそのままパスに埋め込まないでください
• すべてのランブックとログで、password と機密情報をマスキングします
• アクセス設定をエクスポートするには --output <directory> を使用します（ディレクトリが存在している必要があります）。CLI はファイル名 cert_config_{robot_name}_{timestamp}.zip を自動生成し、バイナリ（wb）モードで ZIP ファイルを書き込みます。ZIP ファイルは安全に保管してください
• 「导出配置文件」は、export-certificate による 接入配置（アクセス設定）のエクスポートを意味することに注意してください。 本体の設定は r2c_sdk に組み込まれるか、アダプターとともに配布されるため、ここではエクスポートされません
• 登録後、返された robot_id を記録し、後で dispatch/infer から参照できるようにします
• ワークスペース全体を確認するには cloudrobo robot list を使用し、--limit／--offset でページネーションします
• ワークスペース（cloudrobo workspace current）およびアセットのスキルと組み合わせ、ロボットを作成したり dispatch に接続したりする前に、ワークスペース／モデルのコンテキストを解決します