@oiioii/cli 0.1.6 → 0.1.8

package/README.md

@@ -17,13 +17,18 @@ human-readable output and a stable JSON envelope for AI agents and automation.
 | `auth logout` | Remove locally persisted authentication without exposing the API Key | Implemented |
 | `workspace create/set/current/rename` | Create, configure, inspect, and rename workspaces | Implemented |
 | `workspace assets list/download` | List workspace assets and download ready resources | Implemented |
+| `workspace canvas create` | Create ordered blank nodes, prompts, references, and groups without client-side layout | Implemented |
+| `workspace canvas node update` | Update prompt, generation parameters, and references on an empty canvas node | Implemented |
+| `workspace canvas group create` | Group two or more existing canvas nodes without changing their layout | Implemented |
+| `library create/list/search/members` | Create and query role, scene, item, and collection assets, including collection members | Implemented |
 | `image text` | Text-to-image generation | Implemented |
 | `image edit` | Image-to-image editing | Implemented |
 | `video text` | Text-to-video generation | Implemented |
 | `video image` | Image-to-video generation | Implemented |
 | `video generate` | Model-validated mixed image/video/audio reference generation | Implemented |
 | `audio generate` | Seed Audio and Suno audio/music generation | Implemented |
-| `upload file` | Upload local image/video/audio resources | Implemented |
+| `upload resource` | Upload image/video/audio resources without a workspace | Implemented |
+| `upload file` | Upload image/video/audio and attach it to a workspace | Implemented |
 | `record get/open` | Query generation metadata and download resources | Implemented |
 | `inspect capabilities/models` | Inspect declared capabilities and live backend models | Implemented |
 | `preview latest/bundle` | Read local preview bundles created by generation commands | Implemented |
@@ -34,21 +39,22 @@ human-readable output and a stable JSON envelope for AI agents and automation.
 Important current limitations:
 
 - API keys are stored in `~/.oiioii/config.json` after `oiioii auth login`; the file is owner-readable only (`0600`).
-- Generation submits `submit_async_media_generation` and returns immediately with the authoritative backend `task_id` plus a `local_task_id`.
+- Generation submits `POST /v1/media/generations` by default and returns immediately with the authoritative backend `task_id` plus a `local_task_id`.
 - The backend task ID, workspace, media type, asset ID, progress, and terminal outputs are cached in the owner-only local task store.
-- `task status/wait` query `query_async_media_generation` for non-terminal cached tasks and accept either the backend or local task ID.
+- `task status/wait` query the stored task transport for non-terminal cached tasks and accept either the backend or local task ID.
 - If submission times out or disconnects before the backend task ID is received, the task remains `submitting`; `task retry <local_task_id>` resends the saved request with the original idempotency key.
 - REST metadata requests time out after 30 seconds; raw resource uploads/downloads use a 5-minute transfer timeout, and VOD transcode polling has a 10-minute overall deadline.
 - Image, video, and audio generation create local preview bundles after a queried task reaches a terminal state.
 - `inspect capabilities` is local metadata; `inspect models` requires authentication and queries the active backend.
-- Asset search/update/delete and style-library commands are not available. Workspace-scoped asset listing and download are available.
+- Style-library mutation commands are not available. Reusable asset creation, query, update, deletion, collection membership management, and workspace-scoped asset listing/download are available.
 
 ## Requirements
 
 - Node.js 18.18 or newer when running from source or the npm package.
 - A Hogi account for browser authorization, or an existing Hogi MCP API Key.
-- A workspace ID for image/video/audio generation and resource upload. It can be
+- A workspace ID for image/video/audio generation and `upload file`. It can be
   created with `oiioii workspace create` or supplied from an existing project.
+  `upload resource` does not require a workspace.
 - `npm` is the repository package manager.
 
 The hosted installer uses Node.js 18.18 or newer when available. If no compatible
@@ -275,6 +281,138 @@ oiioii workspace assets download <asset_id> --output ./downloads --json
 identity to the asset's downloadable `uri`; loading, uploading, empty, failed,
 or URI-less assets fail before the download request.
 
+Create blank canvas nodes and groups from a JSON file. The file contains only
+composition data; select the workspace with the normal root option, environment
+variable, local default, or the optional command argument:
+
+```json
+{
+  "nodes": [
+    {
+      "client_id": "cover",
+      "type": "image",
+      "title": "Cover",
+      "prompt": "A cat based on @图片1 in a neon street",
+      "generation_config": {
+        "mcp_method_name": "generate_image_nanopro",
+        "model_version": "nano-banana-pro",
+        "ratio": "16:9",
+        "resolution": "2k",
+        "quality": "high"
+      },
+      "references": [
+        { "kind": "media", "media_type": "image", "uri": "hogi://image/cat.png" }
+      ]
+    },
+    { "client_id": "motion", "type": "video", "title": "Motion" }
+  ],
+  "groups": [
+    {
+      "client_id": "story",
+      "title": "Story",
+      "members": [
+        { "client_node_id": "motion" },
+        { "client_node_id": "cover" }
+      ]
+    }
+  ]
+}
+```
+
+```bash
+oiioii workspace canvas create --input ./composition.json --json
+oiioii workspace canvas create <workspace_id> \
+  --input ./composition.json \
+  --idempotency-key canvas-request-1 \
+  --json
+```
+
+Node order follows `nodes`; `groups[].members` controls group membership order.
+The CLI does not accept coordinates or compute layout. Use the same explicit
+idempotency key only when replaying the same uncertain request. Optional
+`generation_config` caches the empty node's model selection and generation
+parameters for the existing Web editor. It accepts `mcp_method_name`,
+`model_version`, `ratio`, `duration`, `resolution`, and `quality`; a
+`model_version` requires a matching `mcp_method_name`.
+For create and node update, indexed prompt mentions are converted by the CLI to
+the self-contained protocol used by the Web canvas before the request is sent.
+`@图N` / `@图片N` address image and role/scene/item references, while
+`@音频N` and `@视频N` address their own media reference sequences. For example,
+`@图片1` with `hogi://image/cat.png` becomes `[Image:image/cat.png]`.
+Unresolved indexes remain unchanged. OpenAPI/curl callers must send the
+self-contained protocol directly; this shorthand is a CLI-only capability.
+
+Group two or more existing canvas nodes by their asset IDs:
+
+```bash
+oiioii workspace canvas group create <asset_id_1> <asset_id_2> \
+  --title "Story" \
+  --workspace-id <workspace_id> \
+  --idempotency-key group-request-1 \
+  --json
+```
+
+The command rejects duplicate members and nodes that already belong to another
+group. It changes group membership only: it does not move nodes, compute a
+layout, or accept coordinates. Reuse an idempotency key only for the identical
+workspace, member order, and title.
+
+Update an existing empty node with explicit field options:
+
+```bash
+oiioii workspace canvas node update <asset_id> \
+  --workspace-id <workspace_id> \
+  --prompt "Use @图片1: a cat looking through a rainy window" \
+  --model "Nano Pro" \
+  --variant "nano-banana-pro" \
+  --ratio "16:9" \
+  --quality high \
+  --reference 'hogi://image/<reference-id>' 'hogi://role_asset/<role-id>' \
+  --json
+```
+
+`--model` and optional `--variant` resolve through the active model catalog;
+`--model-id` selects the catalog row directly. Use `--clear-prompt`,
+`--clear-model`, `--clear-ratio`, `--clear-duration`, `--clear-resolution`,
+`--clear-quality`, or `--clear-references` for explicit clears. Omitted options
+keep their existing values. The server accepts this operation only when the
+global `enable_cli_empty_canvas_node_update` flag is enabled for the caller and
+the current asset status is `empty`. URI, status, type, position, title, group,
+and raw metadata updates are not accepted. Completed, loading, uploading, and
+failed nodes are rejected.
+
+Create, query, or search reusable library assets before generation:
+
+```bash
+oiioii library create role --name "Hero" --emo-image 'hogi://image/<expression-id>' --json
+oiioii library create collection --name "Cast" --member 'hogi://role_asset/<id>' 'group:<id>' --json
+oiioii library create scene --input ./scene.json --idempotency-key scene-import-001 --json
+oiioii library list role --limit 20 --json
+oiioii library list collection --limit 20 --json
+oiioii library search role "球球" --limit 20 --json
+oiioii library search collection "主要角色" --limit 20 --json
+oiioii library search scene "森林" --cursor '<next_cursor>' --json
+oiioii library members <collection-id> --type role --keyword "主角" --limit 20 --json
+oiioii library members <collection-id> --cursor '<next_cursor>' --json
+oiioii library add-members <collection-id> 'hogi://role_asset/<id>' 'group:<id>' --json
+oiioii library remove-members <collection-id> 'hogi://role_asset/<id>' 'group:<id>' --json
+```
+
+Collection list items use their `asset_id` as the stable identity and return
+`asset_uri: null`. They include `member_count` without expanding the complete
+member list. Use `next_cursor` with `--cursor` to continue pagination.
+`library members` returns normalized role, scene, item, and group entries. Each
+entry includes an `asset_ref` that can be passed directly to collection member
+commands (`hogi://<type>_asset/<id>` or `group:<id>`).
+`library remove-members` is idempotent and applies removals against the latest
+Backend collection state instead of fetching and replacing the full member list
+from the CLI.
+
+Use the returned `asset_uri` with `--asset`, or bind a prompt mention explicitly
+with `--bind <name=asset-uri>`. Explicit bindings avoid silently selecting the
+wrong asset when the library contains duplicate display names.
+Reuse the returned `idempotency_key` when retrying an uncertain create request.
+
 Workspace resolution order is:
 
 1. Root `--workspace <id>` option.
@@ -291,6 +429,11 @@ oiioii image text \
   --model seedream45 \
   --resolution 2K \
   --json
+
+oiioii image text \
+  --prompt "让@球球坐在窗边" \
+  --bind 球球=hogi://role_asset/<role_id> \
+  --json
 ```
 
 Image editing:
@@ -304,15 +447,22 @@ oiioii image edit \
   --json
 ```
 
+For GPT Image 2, add `--transparent` to either `image text` or `image edit`
+to request a transparent-background PNG. Other models reject this option.
+
+```bash
+oiioii image text --prompt "an isolated sticker" --model gpt-image2 --transparent --json
+```
+
 Current behavior:
 
 - Accepts `--model-id <id>` from `inspect models` for exact backend model
   selection, or `--model <key> --variant <variant>` as an alternative.
-- Calls `POST /mcp/genai/sse` with JSON-RPC `tools/call` and `submit_async_media_generation`.
+- Calls `POST /v1/media/generations` with Bearer authentication and an idempotency header.
 - Authenticates with `x-hogi-api-key`.
 - Requires an active workspace.
 - Returns after submission; use `task status` or `task wait` to query progress and terminal `hogi://image/...` output.
-- Image editing adapts the source URI to the async service's `referenceImages` contract.
+- Image editing sends the source URI through the structured `references` contract.
 - When image shape options are omitted, the CLI uses the exact selected model
   catalog row's first aspect ratio and resolution (falling back only when the
   catalog leaves those fields empty).
@@ -359,6 +509,13 @@ oiioii video generate \
   --duration 8 \
   --resolution 720p \
   --json
+
+oiioii video generate \
+  --prompt "小猫跳舞@球球" \
+  --bind 球球=hogi://role_asset/<role_id> \
+  --asset hogi://scene_asset/<scene_id> \
+  --model seedance25 \
+  --json
 ```
 
 When video duration, aspect ratio, or resolution is omitted, the CLI resolves
@@ -370,15 +527,20 @@ Current behavior:
 
 - Accepts `--model-id <id>` from `inspect models` for exact backend model
   selection, or `--model <key> --variant <variant>` as an alternative.
-- Calls `submit_async_media_generation` through `/mcp/genai/sse` with `x-hogi-api-key` authentication.
+- Calls `POST /v1/media/generations` with Bearer authentication.
 - Returns after submission; terminal video URI validation happens during `task status/wait`.
 - Text-to-video sends `prompt`, `duration`, `aspectRatio`, `resolution`, and
   `workspace_id`.
-- Model-specific `imageUrl`/`images` fields are validated locally, then adapted
-  to the async service's `referenceImages` field with `generateMode` preserved.
+- Model-specific reference fields are validated locally, then sent through the
+  structured OpenAPI `references` list with `generateMode` preserved.
 - `video generate` accepts zero or more `--image`, `--video`, and `--audio`
   references in the same request. `--mode auto` derives `text2Video` or
   `omni2Video`; frame semantics can be selected explicitly with `--mode`.
+- Seedance 2.5 omni requests accept `--task-type reference|edit|extend`.
+- `--asset` adds role/scene/item assets as visual references. `--bind` also
+  rewrites an exact `@name` occurrence to `[Role:<id>]`, `[Scene:<id>]`, or
+  `[Item:<id>]`. Workspace-asset references use OpenAPI so the backend can apply
+  visibility checks, main-image resolution, and Seedance role head-combo selection.
 - Reference fields, combinations, and limits are validated against an exact
   backend-tool contract before MCP submission. The current mixed-input matrix is:
   Seedance 2.0/2.5 (image + video + audio), MiniMax H3
@@ -433,17 +595,16 @@ unbounded automated loops, and do not retry failures blindly.
 
 ## Async Generation and Workspace Assets
 
-Image, video, and audio commands submit through:
+Image, video, and audio commands submit through OpenAPI by default:
 
 ```text
-POST /mcp/genai/sse
-method: tools/call
-name: submit_async_media_generation
+POST /v1/media/generations
+GET /v1/media/generations/:task_id
 ```
 
 The backend creates the loading workspace asset and returns its `assetId` and
-authoritative `taskId`. The CLI caches both IDs. `task status/wait` calls
-`query_async_media_generation`, reconciles progress/error/output into the local
+authoritative `taskId`. The CLI caches both IDs and the selected transport.
+`task status/wait` queries the same transport, reconciles progress/error/output into the local
 record, and creates the terminal preview bundle. The CLI does not issue a second
 `create_asset` call, which avoids duplicate workspace assets.
 
@@ -452,6 +613,12 @@ record, and creates the terminal preview bundle. The CLI does not issue a second
 Upload image, video, or audio bytes:
 
 ```bash
+# Pure resource upload for library/collection inputs; no workspace required
+oiioii upload resource ./image.png --json
+oiioii upload resource ./clip.mp4 --json
+oiioii upload resource ./voice.mp3 --json
+
+# Upload and attach to the active workspace
 oiioii upload file ./image.png --json
 oiioii upload file ./clip.mp4 --json
 oiioii upload file ./voice.mp3 --json
@@ -474,6 +641,11 @@ oiioii upload file ./voice.mp3 --after-asset-id <asset_id> --json
 
 Upload behavior:
 
+- `upload resource` uploads small media through `POST /v1/res/uploadFile` and returns
+  only the reusable resource URI; it does not read or update a workspace.
+- MOV files and videos of 10 MB or larger use the standalone VOD flow for
+  `upload resource`: `media_uploads/prepare` -> direct VOD upload -> `commit` -> `status`.
+- `upload file` preserves the original workspace-bound behavior below.
 - Images, audio, and videos smaller than 10 MB use raw `application/octet-stream` bytes at
   `POST /v1/workspace/uploadAsset` with `workspace_id`, `file_type`, and optional
   `file_name` / `after_asset_id` query parameters.
@@ -494,7 +666,7 @@ Upload behavior:
 - `--attach` is retained as a no-op compatibility flag because uploads are now
   always attached.
 - A storage or workspace-write failure fails the upload command.
-- Arbitrary documents and URL uploads are outside the current scope.
+- Arbitrary URL uploads are outside the current scope.
 
 Supported extensions:
 
@@ -916,6 +1088,10 @@ Environment variables:
 |---|---|
 | `OIIOII_CONFIG_DIR` | Override the local configuration directory |
 | `OIIOII_BASE_URL` | Override the backend URL at runtime |
+| `OIIOII_GENERATION_TRANSPORT` | Select `openapi` (default) or the `mcp` rollback transport |
+
+The MCP rollback transport preserves the legacy media-reference payload. Prompt
+references to role, scene, or item workspace assets require the default OpenAPI transport.
 | `OIIOII_WORKSPACE_ID` | Override the active workspace |
 | `OIIOII_BUILD_ENV` | Select `production`, `test`, or `local` while building |
 | `OIIOII_PRODUCTION_BASE_URL` | Optional override for the production build's canonical backend URL |