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 |
|---|---|
|
Personal access token and target Workspace for the current environment. |
|
Choose |
|
|
|
A |
|
|
|
Nonempty |
|
|
|
|
|
JSON object file storing complete |
|
JSON object file storing credential strings according to the selected profile’s field declarations. Do not log its contents. |
|
Previous offset plus current items count. Continue only while less than total. |
|
next_cursor from the search response. Continue only when has_more is true. |
|
Capability name or description text to search for. |
|
|
Plugin account connections¶
Field |
Type |
Description |
|---|---|---|
|
string |
Connection ID. |
|
string |
Owning Workspace ID. |
|
string |
Server-generated display value combining provider and connection ID. |
|
string |
Account description submitted at creation; may be omitted when empty. |
|
string |
Connection enablement state. Created as |
|
string |
|
|
string |
Resource derived from release configuration, not chosen in the creation request. |
|
string |
Authentication type derived from the selected driver and configuration. |
|
string |
Connection owner, returned to identify ownership. |
|
string |
Created account connections are |
|
object |
Nonsensitive release and authorization configuration bindings. |
|
string |
Provider. |
|
string |
Authorization profile key. |
|
string |
Authorization profile digest, used to verify matching. |
|
string |
Workspace owning the release. |
|
string |
Release ID. |
|
string |
Requirement key. |
|
string |
Actual executor ID for a managed session, used for later installation binding when present. |
|
integer |
Connection metadata version, used as |
|
string |
Creation time in RFC 3339 format. |
|
string |
Update time in RFC 3339 format. |
|
string (array of strings) |
Optional capability list. |
|
object |
Optional labels. |
|
object |
Optional annotations. |
|
object |
Optional extension information. |
|
string |
Latest test status. |
|
string |
Latest test time. |
|
string |
Latest test error summary. |
|
string |
Creating account. |
|
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.
Plugin releases¶
Field |
Type |
Description |
|---|---|---|
|
string |
Release ID. |
|
string |
Workspace ID owning the release; requests select it with namespace. |
|
string |
Registry source. |
|
string |
Publisher. |
|
string |
Plugin name. |
|
string |
Version text declared by the plugin, distinct from integer installation/connection versions. |
|
string |
Immutable release digest. |
|
string |
Release description. |
|
string |
Optional localized name. |
|
string |
Optional localized description. |
|
string |
Publishing account. |
|
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 |
|---|---|---|
|
string |
Account provider. |
|
boolean |
Whether the requirement is optional, returned when present. |
|
object |
Map of selectable authorization profiles. |
|
string |
|
|
string |
Fixed account resource. |
|
object |
Credential field declarations, including |
|
object |
OAuth registration key, authorization method, and scopes. |
|
string |
Static credential authentication type, when applicable. |
|
object |
Credential verification configuration fixed by the release. |
|
object (array of objects) |
Credential field injection rules. |
|
object |
Field mappings for TLS certificates and private keys. |
|
string |
Adapter. |
|
string (array of strings) |
Authorization scopes. |
|
object[] |
Each item contains |
Plugin installations¶
Field |
Type |
Description |
|---|---|---|
|
string |
Installation ID. |
|
string |
Current Workspace ID. |
|
string |
Workspace owning the release. |
|
string |
Release ID. |
|
string |
Release name. |
|
string |
Release digest. |
|
string |
Installation owner. |
|
object |
Complete account binding map; updates replace rather than merge it. |
|
string |
Selected account connection ID. |
|
string |
Selected authorization profile key. |
|
string |
Actual executor ID required by a managed session. |
|
integer |
Installation version, separate from connection version and authorization generation. |
|
string |
Creation time. |
|
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.
{"code":4,"message":"请求的资源状态已改变","details":{"domain":"moi.agent-plugin","reason":"PLUGIN_STATE_CONFLICT"}}
HTTP status |
Common reason |
Handling |
|---|---|---|
400 |
|
Check fields, namespace, pagination, profiles, and attempt identifiers. |
404 |
|
Check resource identity and visibility. |
409 |
|
Read the current connection, installation, or authorization. Do not blindly retry an old request. |
410 |
|
The original authorization expired. Review and authorize again. |
422 |
|
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.