# Plugin objects and states

Plugin releases, installations, account connections, and authorizations maintain separate identifiers and versions. Account connections store nonsensitive configuration; credentials are submitted through separate operations.

## Input identifiers

| Example variable | Source |
| --- | --- |
| `AI_STUDIO_API_KEY`、`WORKSPACE_ID` | Personal access token and target Workspace for the current environment. |
| `RELEASE_NAMESPACE` | Choose `system` or `workspace`. Use the same choice for release details/lists and connection/installation creation. |
| `RELEASE_ID` | `items[].id` from the plugin release list, formatted as `pr_` followed by 64 hexadecimal characters. |
| `CONNECTION_REQUIREMENT`、`CONNECTION_PROFILE` | A `connections.requirements` key from release details and a key in that requirement's `profiles`. |
| `CONNECTION_ID`、`CONNECTION_VERSION` | `id` and `version` from connection creation or details. Recheck authorization attempts when the version changes. |
| `ATTEMPT_ID` | Nonempty `attempt_id` returned by an authorization operation. `browser_handoff` provides no pollable attempt ID. |
| `GENERATION` | `generation` from the latest authorization state, used for disconnection. |
| `INSTALLATION_ID`、`INSTALLATION_VERSION` | `id` and `version` from an installation response or details. |
| `PLUGIN_BINDINGS_FILE` | JSON object file storing complete `connection_id/profile/executor_id` bindings by requirement key. |
| `PLUGIN_SECRET_FIELDS_FILE` | JSON object file storing credential strings according to the selected profile's field declarations. Do not log its contents. |
| `NEXT_OFFSET` | Previous offset plus current items count. Continue only while less than total. |
| `NEXT_CURSOR` | next_cursor from the search response. Continue only when has_more is true. |
| `PLUGIN_QUERY` | Capability name or description text to search for. |
| `CAPABILITY_REF` | `capabilities[].capability_ref` from search; pass its original value to later requests. |

## Plugin account connections

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Connection ID. |
| `workspace_id` | string | Owning Workspace ID. |
| `name` | string | Server-generated display value combining provider and connection ID. |
| `description` | string | Account description submitted at creation; may be omitted when empty. |
| `status` | string | Connection enablement state. Created as `active`; status updates accept `active/disabled`. |
| `kind` | string | `plugin` for plugin connections. |
| `endpoint_uri` | string | Resource derived from release configuration, not chosen in the creation request. |
| `auth_type` | string | Authentication type derived from the selected driver and configuration. |
| `owner_user_id` | string | Connection owner, returned to identify ownership. |
| `visibility` | string | Created account connections are `private`. |
| `config` | object | Nonsensitive release and authorization configuration bindings. |
| `config.provider` | string | Provider. |
| `config.auth_profile` | string | Authorization profile key. |
| `config.profile_digest` | string | Authorization profile digest, used to verify matching. |
| `config.release_workspace_id` | string | Workspace owning the release. |
| `config.release_id` | string | Release ID. |
| `config.requirement` | string | Requirement key. |
| `config.executor_id` | string | Actual executor ID for a managed session, used for later installation binding when present. |
| `version` | integer | Connection metadata version, used as `expected_version`. |
| `created_at` | string | Creation time in RFC 3339 format. |
| `updated_at` | string | Update time in RFC 3339 format. |
| `capabilities` | string (array of strings) | Optional capability list. |
| `labels` | object | Optional labels. |
| `annotations` | object | Optional annotations. |
| `metadata` | object | Optional extension information. |
| `last_test_status` | string | Latest test status. |
| `last_tested_at` | string | Latest test time. |
| `last_test_error` | string | Latest test error summary. |
| `created_by` | string | Creating account. |
| `updated_by` | string | Account that last modified the resource. |

Account authorization state is returned by a separate API. `active` does not mean OAuth is complete. A credential-free `none` profile does not enter OAuth or credential submission flows.

## Account authorization state

| Field | Type | Description |
| --- | --- | --- |
| `workspace_id` | string | Workspace ID owning the authorization. |
| `connection_id` | string | Account connection ID. |
| `connection_version` | integer | Connection version associated with the authorization. |
| `status` | string | Current authorization state. |
| `generation` | integer | Authorization generation. Read the latest value before disconnecting. |
| `revision` | integer | Credential revision within the same generation. |
| `external_subject` | string | Confirmed provider account identifier, returned when present. |
| `account_display_name` | string | Display name for some managed accounts, returned when present; not an authorization identifier. |
| `attempt_id` | string | Attempt ID returned by some ongoing managed sessions. Do not assume it can recover every OAuth flow. |

| `status` | Caller action |
| --- | --- |
| `not_connected` | No authorization record yet; generation and revision are 0. Initiate the applicable authorization for the configuration. |
| `pending` | Continue user authorization according to the action, checking the original attempt ID when needed. |
| `ready` | Authorization is ready; actual calls remain subject to current permissions, configuration, and credential validity. |
| `refreshing` | OAuth credentials are refreshing. Do not copy or replace them yourself. |
| `retiring`、`expiring` | The managed session is being cleaned up or expiring; do not treat it as ready. |
| `reauthorize`、`disconnected` | Authorize again using current configuration. Local disconnection does not guarantee provider revocation is complete. |

## Authorization actions and check results

| Action field | Type | Description |
| --- | --- | --- |
| `grant` | string | `browser_handoff`, `authorization_code`, `device_code`, or `managed_session`. |
| `attempt_id` | string | Specific attempt ID; an empty string for browser handoff. |
| `authorization_url` | string | User action page returned by the current branch. |
| `user_code` | string | Returned when device authorization requires it. |
| `poll_after` | integer | Seconds to wait before checking again, when applicable. |
| `expires_at` | string | Expiration time of the current action. |

Initiating an authorization-code profile through `external` returns `browser_handoff`. After signing into the product in a browser, the browser starts the actual authorization-code flow and retains the security proof Cookie. Browser proof is not passed through external clients.

| Check result field | Type | Description |
| --- | --- | --- |
| `attempt_id` | string | Original attempt ID being checked. |
| `status` | string | `pending/exchanging` means keep waiting. `succeeded/failed/denied/expired/superseded` are terminal attempt states. |
| `reason` | string | Failure or state reason, returned when present. |
| `poll_after` | integer | Seconds to wait before the next check, when applicable. |
| `next_action` | object | A new authorization action when further user interaction is required. |

Read account authorization state after a successful check. Without an attempt ID, do not construct a polling path or repeatedly initiate authorization in place of querying state.

## Plugin releases

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Release ID. |
| `workspace_id` | string | Workspace ID owning the release; requests select it with namespace. |
| `registry` | string | Registry source. |
| `publisher` | string | Publisher. |
| `name` | string | Plugin name. |
| `version` | string | Version text declared by the plugin, distinct from integer installation/connection versions. |
| `digest` | string | Immutable release digest. |
| `description` | string | Release description. |
| `display_name` | string | Optional localized name. |
| `display_description` | string | Optional localized description. |
| `published_by` | string | Publishing account. |
| `created_at` | string | Publication time. |

Release details also include `manifest`, `connections`, `profile_digests`, `servers`, `operations`, and `skills`. `manifest` stores the package name, version, description, optional author/homepage/repository/license/keywords, and extensions.

| Connection requirement field | Type | Description |
| --- | --- | --- |
| `connections.requirements["要求键"].provider` | string | Account provider. |
| `connections.requirements["要求键"].optional` | boolean | Whether the requirement is optional, returned when present. |
| `connections.requirements["要求键"].profiles` | object | Map of selectable authorization profiles. |
| `connections.requirements["要求键"].profiles["配置键"].driver` | string | `none/secret/oauth/provider_issued/managed_session`。 |
| `connections.requirements["要求键"].profiles["配置键"].resource` | string | Fixed account resource. |
| `connections.requirements["要求键"].profiles["配置键"].fields` | object | Credential field declarations, including `label/secret/required/multiline`. |
| `connections.requirements["要求键"].profiles["配置键"].oauth` | object | OAuth registration key, authorization method, and scopes. |
| `connections.requirements["要求键"].profiles["配置键"].auth_type` | string | Static credential authentication type, when applicable. |
| `connections.requirements["要求键"].profiles["配置键"].verify` | object | Credential verification configuration fixed by the release. |
| `connections.requirements["要求键"].profiles["配置键"].injection` | object (array of objects) | Credential field injection rules. |
| `connections.requirements["要求键"].profiles["配置键"].client_tls` | object | Field mappings for TLS certificates and private keys. |
| `connections.requirements["要求键"].profiles["配置键"].adapter` | string | Adapter. |
| `connections.requirements["要求键"].profiles["配置键"].scopes` | string (array of strings) | Authorization scopes. |
| `connections.components["能力ID"]` | object[] | Each item contains `requirement` and allowed `profiles`. |

## Plugin installations

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Installation ID. |
| `workspace_id` | string | Current Workspace ID. |
| `release_workspace_id` | string | Workspace owning the release. |
| `release_id` | string | Release ID. |
| `release_name` | string | Release name. |
| `release_digest` | string | Release digest. |
| `owner_user_id` | string | Installation owner. |
| `bindings` | object | Complete account binding map; updates replace rather than merge it. |
| `bindings["要求键"].connection_id` | string | Selected account connection ID. |
| `bindings["要求键"].profile` | string | Selected authorization profile key. |
| `bindings["要求键"].executor_id` | string | Actual executor ID required by a managed session. |
| `version` | integer | Installation version, separate from connection version and authorization generation. |
| `created_at` | string | Creation time. |
| `updated_at` | string | Update time. |

Installations can save empty bindings. Whether a capability can subsequently execute also depends on the selected component's connection requirements, current authorization, and permissions. Uninstalling does not automatically delete account connections. Remove the corresponding installation bindings before deleting a connection.

## Capability search and description

Search returns `candidates[]`, `has_more`, and optional `next_cursor`. Each candidate contains `source`, `release`, optional installation ID/version, `capabilities[]`, and `capabilities_truncated`. Each capability consists of `capability` and a complete `capability_ref`.

Capability objects contain `id/name/description/kind/side_effect/digest`. `kind` is `skill/mcp/http/command`; `side_effect` is `read/write/execute/dynamic`. These descriptions do not replace current permissions or user confirmation for execution.

Description results include the original reference, the capability object, and applicable `input_schema`, `skill_path`, `mcp_server`, or `connections`. `mcp_server` fields include `type` and applicable `url/command/args/headers`. It is a release declaration, not a tool-probing result for the current account.

## Error responses

The plugin business layer uses the following responses. Use stable `details.reason` values to identify causes; `message` is localized.

```json
{"code":4,"message":"请求的资源状态已改变","details":{"domain":"moi.agent-plugin","reason":"PLUGIN_STATE_CONFLICT"}}
```

| HTTP status | Common reason | Handling |
| --- | --- | --- |
| 400 | `PLUGIN_REQUEST_INVALID` | Check fields, namespace, pagination, profiles, and attempt identifiers. |
| 404 | `PLUGIN_RESOURCE_NOT_FOUND` | Check resource identity and visibility. |
| 409 | `PLUGIN_STATE_CONFLICT`、`PLUGIN_AUTH_IN_PROGRESS`、`PLUGIN_REAUTHORIZE_REQUIRED` | Read the current connection, installation, or authorization. Do not blindly retry an old request. |
| 410 | `PLUGIN_AUTH_EXPIRED` | The original authorization expired. Review and authorize again. |
| 422 | `PLUGIN_CREDENTIAL_REJECTED`、`PLUGIN_CREDENTIAL_NOT_PORTABLE` | Check credentials or authorization method. Do not repeatedly publish an invalid result. |
| 502/503 | Reasons related to unavailable providers, authorization profiles, executors, or services | Retain safe tracing information and check current state first after recovery. |

Authentication or Workspace admission may also return string `code`, `msg`, and trace details, such as `PLUGIN_ADMISSION_DENIED` or Workspace membership errors. Do not force every error into a numeric `code` or use literal `message` text as a stable discriminator. No HTTP response does not establish that the operation had no effect.
