Windows / PowerShell: Examples use bash syntax. To run on Windows PowerShell:
Flatten \ line continuations to a single line, or end lines with a backtick.
Set env vars with $env:NAME="value" instead of export NAME="value".
Single-quoted JSON '{"a":"b"}' works as-is.
Overview 概述
The cloudrobo-asset skill manages the full lifecycle of CloudRobo platform assets. It
covers repository and catalog queries, asset CRUD (create/list/show/update/delete/batch-delete),
version CRUD, tag management, Action CRUD, permission checks, marketplace search,
official/community asset listing, asset lineage, and local-to-OBS import/export.
All operations target the cloudrobo-asset-manager backend. Import/export additionally
requires a cloudrobo-obs endpoint for OBS file transfer.
Prerequisites 前置条件
See references/cli-installation-guide.md for CLI installation, AK/SK authentication, and
configuration. Import/export operations require the cloudrobo-obs endpoint to be configured in
~/.cloudrobo/config.yaml or via the CLOUDROBO_ENDPOINT_cloudrobo-obs environment variable.
Workflow 工作流
Prerequisite: Get catalog_id 前置步骤
Multiple scenarios require a catalog_id. Only execute when the user has not provided it:
Get from current workspace (preferred):cloudrobo workspace current → read
asset_catalog_id field (the catalog bound to the current workspace)
Fallback — list repositories and catalogs: If no workspace is configured or
asset_catalog_id is empty:
cloudrobo asset list-repositories → get repository_id
cloudrobo asset list-catalogs --repository-id <repo-id> → get catalog_id
Scenario 1: Import Local Asset 导入资产
Import local files (models, datasets, etc.) into the CloudRobo asset repository.
Fast path: If local-path/README.md exists with valid frontmatter (e.g., from a previous
export-asset), only --catalog-id (for new asset) or --asset-id (for new version) is needed
— all other metadata is read from frontmatter. Without frontmatter, catalog_id, name, type
(and sub_type for simulation) must be provided via CLI.
(Only when creating new asset and catalog_id is missing) Execute "Prerequisite: Get catalog_id"
Frontmatter values override CLI parameters (except catalog_id, CLI only); fields missing from both trigger errors
--ext-metadata CLI param also supported (frontmatter overrides it)
ext_metadata pre-validated by type before API call (model→model_type, dataset→annotation_status,
algorithm→engine+command, image→arch+device_type, simulation (sub_type=robot)→robot_type+robot_manufacturer)
Auto-creates asset + version + uploads to OBS
Existing asset new version: add --asset-id <existing-asset-id>
Reuse existing version for upload retry: add --asset-id <id> --version-id <vid> (uploads files directly; same-name OBS objects are overwritten idempotently)
Type constraints:
image type is NOT supported by import-asset — image is a SWR reference with no local code upload semantics; use create-asset instead (CLI raises UsageError otherwise)
algorithm type IS supported — importing an algorithm uploads local code to the OBS code_dir:
bash
# Mode 1: new asset
cloudrobo asset import-asset --catalog-id <id> --name <name> --type algorithm --tags "Train" --ext-metadata '{"engine":{"image_url":"swr...","image_source":"custom"},"command":"python train.py"}' --local-path ./algo-dir
# Mode 2: new version for existing algorithm asset (no --catalog-id needed)
cloudrobo asset import-asset --asset-id <existing-algo-asset-id> --type algorithm --tags "Train" --ext-metadata '{"engine":{"image_url":"swr...","image_source":"custom"},"command":"python train.py"}' --local-path ./algo-dir
Error recovery: If import fails at OBS upload (asset and version created but files not
uploaded, version stays in CREATING status), do NOT create a new version. Two recovery strategies:
Reuse version (recommended):list-versions --asset-id <id> to find the failed version,
re-run import-asset --asset-id <id> --version-id <vid> to upload directly (retries all files;
the version transitions to DRAFT once upload succeeds)
Delete and retry:delete-version --asset-id <id> --version-id <vid> then re-run
import-asset --asset-id <id>
Export after search: Only when the user requests export. Before downloading, check that the
current account holds data_read permission on the asset version; --version-id is required —
if the user did not provide one, resolve the latest version ID via list-versions --asset-id <id>, then run:
cloudrobo asset check-permission --asset-id <id> --version-id <version-id> --permissions data_read
If the verdict is deny, do not run the export and inform the user: "当前账号无该资产数据读取
权限,仅能导出元数据(README),无法下载数据文件". Only when data_read is granted, run
cloudrobo asset export-asset --asset-id <id> --local-path <path> (default latest version; add
--version-id for specific version). Export automatically generates README.md with YAML frontmatter
containing asset metadata, enabling seamless re-import with minimal CLI parameters.
Scenario 3: List Workspace Assets 列举空间资产
(Only when catalog_id is missing) Execute "Prerequisite: Get catalog_id"
Task scenario tag constraints (algorithm/image types):
--tags is required at creation (at least 1 task scenario tag)
algorithm tags allowed: Data Processing, Train
image tags allowed: Data Processing, Notebook, Online Deployment, Train
When an algorithm references an image (ext_metadata.engine.asset_id), the algorithm tags must be a subset of the image tags (SDK validates; raises ValidationError otherwise)
List return structure (unified): All list commands — list-repositories, list-catalogs,
list-assets, list-versions, list-publication-assets, list-tags — return a unified JSON
shape with a data array plus a page_info pagination object:
Note:--tags is required for algorithm/image types (task scenario tag).
algorithm tags: Data Processing, Train
image tags: Data Processing, Notebook, Online Deployment, Train
When algorithm references an image (engine.asset_id), algorithm tags must be a subset of image tags (SDK validates; raises ValidationError otherwise)
--sub-type applies to simulation only; for algorithm/image it is ignored (client drops it before the API call)
List assets
bash
cloudrobo asset list-assets [--repository-id <id>] [--catalog-id <id>] [--type <type>] [--sub-type <sub-type>] [--status <status>] [--name <name>] [--tags "tag1,tag2"] [--mine] [--offset <n>] [--limit <n>]
# Either --repository-id OR --catalog-id filters the list. Full parameter list: see references/api-paths.md → List Assets
SDK:client.list_assets(**params)
API:GET /v1/assets
Return structure: same unified list shape as Repository & Catalog — top-level data array
plus page_info ({"page_info": {"total": N}, "data": [...]}). list-versions and
list-publication-assets also follow this structure. Read records from data and totals from
page_info.total.
Note:repository-id and catalog-id — at least one must be provided; both provided =
AND filter.
Note:update-asset only supports modifying name/description/status/tags/
ext-metadata — the CLI exposes no parameters for catalog_id, type, sub_type,
url, parent_asset_version_id, or generation_method, so these fields are immutable.
Note:update-version only supports modifying version/description/status/
ext-metadata — the CLI exposes no parameters for url, parent_asset_version_id, or
generation_method, so these fields are immutable.
image type NOT supported — CLI raises UsageError; use create-asset
algorithm type supported (Mode 1 & Mode 2) — imports local code to {catalog.url}/{asset_id}/{version_id}/, code_dir placeholder {catalog.url}/pending at creation then updated to actual path on both asset-level and version-level; user must NOT provide code_dir/boot_file; Mode 2 gets catalog_id from asset detail (no --catalog-id needed)
Mode 3 (--asset-id --version-id) NOT supported for algorithm — raises ValueError
Priority: frontmatter overrides CLI parameters (except catalog_id, CLI only); fields missing from both trigger errors
Required fields for new asset: catalog_id (CLI only), name (frontmatter or CLI), type (frontmatter or CLI)
Required for new version (--asset-id): ext_metadata (backend requires it for model/dataset/image/simulation; pass via --ext-metadata or frontmatter)
ext_metadata pre-validation: model/dataset/algorithm/image/simulation types validated before API call (robot is a sub_type of simulation)
Modes:
No --asset-id: Create new asset + version + upload to OBS; after upload, if version status is CREATING, auto-update to DRAFT
--asset-id only: Create new version for existing asset + upload to OBS; ext_metadata is required (backend validates for model/dataset/image/simulation; pass via --ext-metadata or frontmatter); after upload, if version status is CREATING, auto-update to DRAFT
--asset-id + --version-id: Reuse existing version, upload files directly to OBS (same-name objects are overwritten idempotently); after upload, if version status is CREATING, auto-update to DRAFT; NOT supported for algorithm assets (raises ValueError)
Status flow: When no --status is specified, the backend creates the version with status CREATING. After a successful OBS upload, if the version status is still CREATING, the SDK automatically calls update-version to set it to DRAFT. If the user explicitly specifies a status (e.g., RELEASE via frontmatter), the upload succeeds but the status is not auto-modified.
Export asset
bash
cloudrobo asset check-permission --asset-id <id> --version-id <version-id> --permissions data_read
# verify verdict; only proceed with export when verdict=allow
cloudrobo asset export-asset --asset-id <id> --local-path <local-folder> [--version-id <version-id>] [--dry-run]
Permission pre-check (required): Before exporting an asset the current account may not own
(e.g. marketplace/published assets), always run check-permission --asset-id <id> --version-id <vid> --permissions data_read first (--version-id required; resolve via list-versions --asset-id <id> if unknown).
If the verdict is deny, do not run export-asset and inform the user: "当前账号无该资产数据读取
权限,仅能导出元数据(README),无法下载数据文件" — otherwise the CLI would return a misleading
status:exported result with missing data files (OBS 403).
Type constraints:
image type is NOT supported — raises ValueError (SWR reference, no downloadable files); use create-asset instead
algorithm type IS supported — downloads code from ext_metadata.code_dir OBS path; if code_dir is missing, raises RuntimeError with recovery guidance
Path requirement:--local-path must be an existing directory (raises FileNotFoundError if not found, ValueError if it's a file). The SDK creates a subdirectory {local-path}/{asset_id}/ inside it for the downloaded files.
README.md generation:
Creates <local-path>/<asset-id>/README.md with YAML frontmatter
Parent version UUID (create-asset/create-version only)
d4e5f6a7-...
Mutating operations (create/update/delete/import/export/batch-delete) should be confirmed
by the user before execution. --dry-run can be used to preview the operation safely.
Key edge cases include: missing catalog_id, import OBS upload failure recovery, export
permission checks, immutable field validation, built-in vs workspace asset distinction,
and capabilities filter mapping. See Edge Cases for the
full table.
Verification Method 验证方法
bash
# Specification compliance + functional testing (read-only + --dry-run rehearsal; no side effects)
bash scripts/test-cli-commands.sh -s . -e {cli|sdk}
# Key lifecycle real execution (create→update→tag→version→delete; confirms each mutation):
# RUN_LIFECYCLE=1 REPOSITORY_ID=... CATALOG_ID=... ASSET_ID=... VERSION_ID=... bash scripts/test-cli-commands.sh -s . -e cli
Test cases: see templates/test-vars.json for the full list covering all asset operations.
Verification Checklist 验证清单
After create/update/import: verify via show-asset/show-version/list-actions that changes took effect
After list/search/check-permission: verify results match filter criteria and verdict contains allow/deny
Before delete: confirm with user — deletion is irreversible
Before export: run check-permission --asset-id <id> --version-id <vid> --permissions data_read first (version-id required; resolve via list-versions if unknown); deny → inform user, do not export
After export: check local directory file structure matches OBS source
Best Practices 最佳实践
Use --dry-run with create/update/delete/import/export to validate parameters before execution
Before creating assets with ext_metadata, consult references/validation-rules.md for required fields by type
Use import-asset (not create-asset) for most scenarios — it handles the full flow (asset + version + OBS upload)
For failed imports, reuse the existing version with --asset-id --version-id to avoid accumulating empty versions
Query predefined tags via list-tags before adding tags to ensure they are valid
Use export-asset followed by import-asset for seamless asset migration — export generates
README.md with frontmatter, import auto-reads it to fill metadata
For import without frontmatter, provide --ext-metadata for model/dataset/simulation types to
pass pre-validation