v0.4.0 to v0.7.0

+ version: 0.7.0

+ description: Search, install, publish, review, and update Marketplace plugins — Skills, MCP connectors, and Experts/Squads (专家/专家团) — through the unified plugin API. Load after octo-shared.

+ # octo-marketplace — unified plugin catalog

+ The marketplace is one backend with a single catalog surface: every asset is a

+ **plugin** with a `plugin_type`. All commands authenticate with the active

+ credential and send its Space context; a `bf_*` User Bot is resolved to its owner

+ and authoritative Bot Space by the backend. Unified catalog operations use

+ `/market/api/v1/plugins*`; helper operations such as categories, uploads, probes,

+ and icon presigns use other routes under `/market/api/v1/*`.

+ | plugin_type | was | read via |

+ |---|---|---|

+ | `skill` | Skill ZIP | [`skills.md`](skills.md) |

+ | `connector` | MCP listing | [`mcp.md`](mcp.md) |

+ | `expert` | Expert (专家) | [`expert.md`](expert.md) |

+ | `expert_team` | Squad (专家团) | [`expert.md`](expert.md) |

+ ```bash

+ octo-cli marketplace plugin list --scene-code default --plugin-type skill --q "<kw>"

+ octo-cli marketplace plugin get --plugin-id <id> --include-relations

+ ```

+ `scene-code` is `default`. Catalog listing requires `--scene-code` and

+ `--plugin-type`; the owned all-types view is the exception:

+

+ ```bash

+ octo-cli marketplace plugin list --scene-code default --mode mine

+ ```

+

+ Use immutable `plugin_id` and `review_id` values, never names.

+

+ ## Save, publish, and review lifecycle

+

+ Creating with `plugin upsert` or skill `plugin import` saves a **draft** and a

+ version snapshot; it does not expose the plugin to the Space catalog. Updates

+ preserve the current listing state: draft/delisted content remains editable,

+ published private content remains owner-only, and published Space content

+ rejects direct edits and must use review. Version labels use

+ `MAJOR.MINOR.PATCH` (each numeric component is 1–9 digits) and may not move

+ backward.

+

+ After verifying a saved draft, publish it explicitly:

+

+ ```bash

+ octo-cli marketplace plugin publish --plugin-id <plugin-id> \

+ --version 1.2.0 --changelog "What changed"

+ ```

+

+ - A `private` plugin's listing state becomes published immediately, but it stays

+ owner-only and is not exposed in the Space catalog.

+ - A `space` plugin opens a review request and remains a draft until a Space

+ owner/admin approves it. Save the returned `review_id`.

+ - Read `display_status` as the user-facing state: `draft`, `pending_review`,

+ `published`, `rejected`, or `delisted`. `listing_state` is the lower-level

+ listing axis.

+

+ Applicants can inspect or cancel their requests:

+

+ ```bash

+ octo-cli marketplace plugin review-request list --mode mine --status pending

+ octo-cli marketplace plugin review-request get <review-id>

+ octo-cli marketplace plugin review-request cancel <review-id>

+ ```

+

+ Space owners/admins review the frozen submission, not mutable live draft data:

+

+ ```bash

+ octo-cli marketplace plugin review-request list --mode space --status pending

+ octo-cli marketplace plugin review-request get <review-id>

+ octo-cli marketplace plugin review-request approve <review-id>

+ octo-cli marketplace plugin review-request reject <review-id> --reason "Explain the required correction"

+ ```

+

+ A Space owner/admin can take published Space content down; this leaves the

+ plugin editable and eligible for a later publish:

+

+ ```bash

+ octo-cli marketplace plugin delist --plugin-id <plugin-id> --reason "Policy or maintenance reason"

+ ```

+

+ An already-published Space plugin cannot be edited through `upsert` or skill

+ `import`; the backend rejects that bypass. Submit the full frozen upgrade with

+ `review-request create`: a listed upgrade must carry either `parse_task_id` for

+ a freshly parsed skill archive or both `manifest_json` + `plugin_json` for

+ declared documents. Only an unlisted Space-intent first submission may omit

+ content and snapshot its live draft. A present `relations` array replaces the

+ frozen graph; omitting it inherits the live graph.

+

+ ## Retry and recovery

+

+ Marketplace mutations are not transport-retried. A gateway failure may mean the

+ server committed the operation, so `RESULT_UNKNOWN` must be resolved by reading

+ state before retrying:

+

+ - create: walk `plugin list --scene-code default --mode mine --q "<name>"`

+ through every page;

+ - update/import of an existing id: `plugin get --plugin-id <id>` and compare the

+ intended version, hashes, and content; use `plugin version list` where useful;

+ - publish: `plugin get --plugin-id <id>` and inspect `display_status` /

+ `review_id`, then list owned review requests;

+ - review decisions: re-read the review request;

+ - delist/delete: re-read the plugin.

+

+ `--q` matches `plugin_name` substrings only and a page defaults to 20 rows. Stop

+ only after an exact match or a short page.

+

+ ## Pagination and filtering

+

+ `plugin list` uses `--page` / `--page-size` (default 20, max 100); there is no

+ `--page-all`. Filters are `--category-id`, `--q`, repeatable `--tag`, `--mode

+ mine`, and `--sort` (`newest`, `oldest`, `updated`, `name`, `placement`, `views`,

+ `installs`, `downloads`, `comprehensive`).

+

+ `plugin-category list` requires `--scene-code` and `--plugin-type`.

+ `plugin-tag list` accepts optional `--scene-code`, `--plugin-type`, `--q`,

+ `--mode mine`, and `--limit` (default 50, max 100).

+

+ Load only the reference matching the task: connector `mcp.json` + probe,

+ skill attachment tree + upload/import, or expert/team `AGENTS.md` + relations.

+

+ For a non-paginated command, normalize before reading fields:

+ payload=$(octo-cli marketplace plugin get --plugin-id <id> | jq -c '.data.data // .data')

+ Do not apply that to `{data:[...], pagination:{...}}`; the CLI exposes items at

+ `.data` and pagination at `._pagination`.

+ - Show the target and intended mutation before create, update, publish, review

+ decision, delist, install, or delete; continue only after explicit user

+ confirmation.

+ - Never print presigned URLs, tokens, secret-bearing headers, or raw secret

+ values. Connector secrets use `${VAR}` placeholders.

+ - Do not modify a plugin or review request outside the user-selected target.

+ - Preserve the prior runtime configuration if installation fails.