huawei-cloud-cloudrobo-robot

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

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

概览

cloudrobo-robot 技能用于管理 CloudRobo 机器人实例的完整生命周期。机器人是执行具身智能任务的物理载体，分为六种类型：HUMANOID（人形）、QUADRUPED（四足）、ARM（机械臂）、OPERATION（作业）、WHEELED（轮式）和 OTHER（其他）。此技能涵盖机器人注册、列表／详情查询、元数据更新、离线设备删除、证书导出（用于机器人安全接入平台），以及获取最新的机器人端 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 下载的内容。

工作流

自然语言优先原则

以下每个工作流都从用户意图（1 至 2 句话）开始，而非手动编排 CLI／SDK。随后，技能会执行匹配的命令链并报告状态反馈。

机器人注册工作流（模块 + 工作空间 + 资产）

场景：用户想注册并接入一台新机器人。

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. 报告 — 向用户输出状态和关键属性（类型、制造商、robot_model、状态）。
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> 确认字段已更改。

证书／接入配置导出工作流（模块 + 安全）

“导出配置文件” = 导出接入配置（证书）。机器人有两种配置：

• 本体配置（机器人本体／主配置） — 内置于 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") 生成时间戳），然后以二进制（wb）模式将其写入 --output 目录。--password 为可选项；--output 为必填项，且必须是已存在的目录。
   • 如果导出返回 CloudRobo.04010007 "The robot can only have one running job."（HTTP 400；错误代码来自后端行为，本地 SDK 中没有该代码——已通过后端验证，待实时确认）： 说明机器人当前有正在运行的任务（调度／调试任务），或因其他原因无法启动新的导出任务。由于状态是动态的，之前能成功导出的机器人（例如当时处于 INACTIVE 状态），现在可能变为 OFFLINE／ONLINE 并正在运行任务，导致本次导出失败——请重新执行 show 确认状态，并选择没有正在运行任务的机器人（例如处于 INACTIVE／空闲状态的机器人），或等待当前任务完成后重试。不要将导出失败当作“证书不可用”，也不要继续使用空文件或不完整文件——使用前请确认输出文件是非空 zip 文件。
3. 安全存储 — 导出后，将下载的 zip 放入安全存储位置（受保护的目录、密钥管理器或机器人侧的接入配置目录）。不要将其留在共享／全局可读路径中。机器人侧会使用此 zip（例如通过 r2c_sdk／R2C 客户端），并与 SDK 或适配器中已有的本体配置配合使用。
4. 反馈 — 告知用户接入配置 zip 已写入指定文件，可用于机器人侧接入配置（例如通过 r2c_sdk.cloudroboclient）。
5. 安全说明 — 操作手册会对敏感内容（密码／路径）进行脱敏；不要回显密码，并将导出的 zip 视为凭据。

机器人 SDK 升级工作流（模块）

场景：“机器人侧 SDK 的最新版本是什么？”

1. 查询 SDK — 执行 cloudrobo robot show-sdk（无需参数）。
2. 报告 — 输出 file_name、version 和 signed_url，供机器人拉取升级包。

组合工作流 A — 注册机器人 → 部署模型 → 派发任务（机器人 + 推理 + 派发）

场景：“注册机器人，将感知模型部署为推理服务，并使用该模型在机器人上运行任务。”

1. 按照机器人注册工作流注册机器人；记录返回的 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；Agent 会跨技能协调，先在此处获取 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
子命令	kebab-case	create、export-certificate、show-sdk
工作区	--workspace-id <id>（create/list/update）	--workspace-id abc-123
输出格式	将 JSON 输出到 stdout	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

此命令会导出机器人的接入配置（接入配置 / 证书） — 机器人用于连接平台的凭据包。它是一个 zip 包：CLI 会自动将文件命名为 cert_config_{robot_name}_{timestamp}.zip，并写入 --output 目录。请妥善保管 zip 文件。--password（用于加密凭据包）是可选项；--output（导出目录，必须已存在）是必需项；请参阅证书 / 接入配置导出工作流。

查看最新机器人 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 字段、类型枚举、状态、证书导出、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

测试用例

完整测试用例列表见 templates/test-vars.json，涵盖注册、查询、更新、删除、证书导出、SDK 查询和安全场景。

验证清单

• 执行 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 参数
• 使用基于 validate_safe_id 的 CLI 防止路径遍历；切勿将原始用户输入嵌入路径
• 在所有运行手册和日志中遮蔽 password 和敏感值
• 导出接入配置时，使用 --output <directory>（目录必须存在）；CLI 会自动生成文件名 cert_config_{robot_name}_{timestamp}.zip，并以二进制（wb）模式写入 zip 文件——请妥善保管 zip 文件
• 请记住：“导出配置文件”指通过 export-certificate 导出接入配置（access config）—— 机身配置内置于 r2c_sdk 中，或随适配器分发，不会在此处导出
• 注册后记录返回的 robot_id，以便后续在 dispatch/infer 中引用
• 工作区范围概览优先使用 cloudrobo robot list；使用 --limit/--offset 翻页
• 创建机器人或将其接入 dispatch 前，结合工作区（cloudrobo workspace current）和资产技能解析工作区/模型上下文