插件对象与状态

插件发布、安装、账号连接和授权分别维护标识与版本。账号连接保存非敏感配置,凭据通过独立动作提交。

输入标识

示例变量

来源

AI_STUDIO_API_KEY、WORKSPACE_ID

当前环境的个人访问令牌及目标工作区。

RELEASE_NAMESPACE

选择 system 或 workspace;发布详情/列表与创建连接/安装使用同一选择。

RELEASE_ID

插件发布列表的 items[].id,格式为 pr_ 加 64 位十六进制串。

CONNECTION_REQUIREMENT、CONNECTION_PROFILE

发布详情的 connections.requirements 键及该要求 profiles 中的键。

CONNECTION_ID、CONNECTION_VERSION

创建连接或详情的 id、version;版本改变时重新复核授权尝试。

ATTEMPT_ID

授权动作返回的非空 attempt_id;browser_handoff 不提供可轮询尝试 ID。

GENERATION

最新授权状态的 generation,供断开动作使用。

INSTALLATION_ID、INSTALLATION_VERSION

安装响应或详情中的 id、version。

PLUGIN_BINDINGS_FILE

JSON 对象文件,按要求键保存完整 connection_id/profile/executor_id 绑定。

PLUGIN_SECRET_FIELDS_FILE

JSON 对象文件,按所选 profile 的字段声明保存凭据字符串;不将文件内容写入日志。

NEXT_OFFSET

原 offset 加当前 items 数,仅在小于 total 时继续翻页。

NEXT_CURSOR

搜索响应的 next_cursor,仅在 has_more 为 true 时继续。

PLUGIN_QUERY

需要检索的能力名称或描述文本。

CAPABILITY_REF

搜索返回的 capabilities[].capability_ref,按原值传入后续请求。

插件账号连接

字段

类型

说明

id

string

连接 ID。

workspace_id

string

所属工作区 ID。

name

string

服务端生成的 provider 与连接 ID 展示值。

description

string

创建时提交的账号说明;为空时可省略。

status

string

连接的启用状态;创建为 active,状态更新接受 active/disabled。

kind

string

插件连接为 plugin。

endpoint_uri

string

从发布配置导出的资源,不由创建请求自选。

auth_type

string

由所选驱动与配置导出的认证类型。

owner_user_id

string

连接所有者,返回时用于识别归属。

visibility

string

创建的账号连接为 private。

config

object

非敏感的发布与授权配置绑定。

config.provider

string

供应商。

config.auth_profile

string

授权配置键。

config.profile_digest

string

授权配置摘要,用于验证匹配关系。

config.release_workspace_id

string

发布所属空间。

config.release_id

string

发布 ID。

config.requirement

string

要求键。

config.executor_id

string

托管会话的实际执行器 ID,存在时用于后续安装绑定。

version

integer

连接元数据版本,供 expected_version 使用。

created_at

string

创建时间,RFC 3339 格式。

updated_at

string

更新时间,RFC 3339 格式。

capabilities

string(字符串数组)

可选能力列表。

labels

object

可选标签。

annotations

object

可选注释。

metadata

object

可选扩展信息。

last_test_status

string

最近测试状态。

last_tested_at

string

最近测试时间。

last_test_error

string

最近测试错误摘要。

created_by

string

创建账号。

updated_by

string

最近修改账号。

账号的授权状态由独立接口返回;active 不代表 OAuth 已完成。无需凭据的 none 配置不进入 OAuth 或提交凭据流程。

账号授权状态

字段

类型

说明

workspace_id

string

授权所属工作区 ID。

connection_id

string

账号连接 ID。

connection_version

integer

授权对应的连接版本。

status

string

当前授权状态。

generation

integer

授权代次;断开需读取最新值。

revision

integer

同一代次中的凭据修订。

external_subject

string

已确认的供应商账号标识,存在时返回。

account_display_name

string

部分托管账号的显示名称,存在时返回;不作为授权标识。

attempt_id

string

部分进行中托管会话返回的尝试 ID;不能假定所有 OAuth 都能由此恢复。

status

调用者处理

not_connected

尚无授权记录,代次与修订为 0;按配置发起适用的授权。

pending

按动作继续用户授权,必要时用原尝试 ID 检查。

ready

授权已就绪;实际调用仍受当前权限、配置和凭据有效性约束。

refreshing

OAuth 凭据正在刷新;不要自行复制或替换凭据。

retiring、expiring

托管会话正在清理或到期处理中,不能按 ready 处理。

reauthorize、disconnected

按当前配置重新授权;本地断开不保证供应商撤销已完成。

授权动作和检查结果

动作字段

类型

说明

grant

string

browser_handoff、authorization_code、device_code 或 managed_session。

attempt_id

string

具体尝试 ID;浏览器交接时为空字符串。

authorization_url

string

当前分支返回的用户操作页面。

user_code

string

设备授权需要时返回。

poll_after

integer

再次检查的等待秒数,适用时返回。

expires_at

string

当前动作的到期时间。

external 发起授权码配置时返回 browser_handoff。登录产品浏览器页面后,由浏览器发起实际授权码流程并保留安全证明 Cookie。浏览器证明不通过外部客户端传递。

检查结果字段

类型

说明

attempt_id

string

被检查的原尝试 ID。

status

string

pending/exchanging 表示继续等待;succeeded/failed/denied/expired/superseded 为该尝试的终态。

reason

string

失败或状态原因,存在时返回。

poll_after

integer

下次检查等待秒数,适用时返回。

next_action

object

需要继续用户操作时提供新的授权动作。

检查成功后再读取账号授权状态。没有尝试 ID 时不能构造轮询路径,也不能通过重复发起授权来代替状态查询。

插件发布

字段

类型

说明

id

string

发布 ID。

workspace_id

string

发布所属空间 ID;请求用 namespace 选择空间。

registry

string

注册来源。

publisher

string

发布者。

name

string

插件名称。

version

string

插件声明的版本文本,与安装/连接的整数版本不同。

digest

string

不可变发布摘要。

description

string

发布说明。

display_name

string

可选本地化名称。

display_description

string

可选本地化说明。

published_by

string

发布账号。

created_at

string

发布时间。

发布详情另外包含 manifest、connections、profile_digests、servers、operations、skills。manifest 保存插件包名称、版本、说明、可选作者/主页/仓库/许可/关键词和扩展。

连接要求字段

类型

说明

connections.requirements["要求键"].provider

string

账号供应商。

connections.requirements["要求键"].optional

boolean

要求是否可选,存在时返回。

connections.requirements["要求键"].profiles

object

可选择的授权配置映射。

connections.requirements["要求键"].profiles["配置键"].driver

string

none/secret/oauth/provider_issued/managed_session。

connections.requirements["要求键"].profiles["配置键"].resource

string

固定的账号资源。

connections.requirements["要求键"].profiles["配置键"].fields

object

凭据字段声明,包含 label/secret/required/multiline。

connections.requirements["要求键"].profiles["配置键"].oauth

object

OAuth 注册键、授权方式和范围。

connections.requirements["要求键"].profiles["配置键"].auth_type

string

静态凭据认证类型,适用时返回。

connections.requirements["要求键"].profiles["配置键"].verify

object

发布固定的凭据核验配置。

connections.requirements["要求键"].profiles["配置键"].injection

object(对象数组)

凭据字段注入规则。

connections.requirements["要求键"].profiles["配置键"].client_tls

object

TLS 证书和私钥的字段映射。

connections.requirements["要求键"].profiles["配置键"].adapter

string

适配器。

connections.requirements["要求键"].profiles["配置键"].scopes

string(字符串数组)

授权范围。

connections.components["能力ID"]

object[]

每项含 requirement 及允许的 profiles。

插件安装

字段

类型

说明

id

string

安装 ID。

workspace_id

string

当前工作区 ID。

release_workspace_id

string

发布所属空间。

release_id

string

发布 ID。

release_name

string

发布名称。

release_digest

string

发布摘要。

owner_user_id

string

安装所有者。

bindings

object

完整账号绑定映射;更新时替换,不合并。

bindings["要求键"].connection_id

string

所选账号连接 ID。

bindings["要求键"].profile

string

所选授权配置键。

bindings["要求键"].executor_id

string

托管会话要求的实际执行器 ID。

version

integer

安装版本;与连接 version 和授权 generation 分开。

created_at

string

创建时间。

updated_at

string

更新时间。

安装可以保存空绑定。后续能力是否可执行,还需检查所选组件的连接要求、当前授权和权限。卸载不自动删除账号连接;删除连接前须先移除相应安装绑定。

能力搜索与描述

搜索返回 candidates[]、has_more 和可选 next_cursor。每个候选包含 source、release、可选安装 ID/版本、capabilities[] 及 capabilities_truncated。每项能力由 capability 和完整的 capability_ref 组成。

能力对象包含 id/name/description/kind/side_effect/digest。kind 是 skill/mcp/http/command;side_effect 是 read/write/execute/dynamic。这些描述不代替当前权限或用户对执行动作的确认。

描述结果包含原引用、能力对象,并按能力返回 input_schema、skill_path、mcp_server 或 connections。mcp_server 的字段包括 type 及适用的 url/command/args/headers;它是发布声明,不是当前账号工具探测结果。

错误响应

插件业务层使用以下响应。以稳定的 details.reason 判断原因;message 随语言本地化。

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

HTTP 状态

常见 reason

处理

400

PLUGIN_REQUEST_INVALID

核对字段、命名空间、分页、配置及尝试标识。

404

PLUGIN_RESOURCE_NOT_FOUND

核对资源身份及可见范围。

409

PLUGIN_STATE_CONFLICT、PLUGIN_AUTH_IN_PROGRESS、PLUGIN_REAUTHORIZE_REQUIRED

回读当前连接、安装或授权;不盲目重试旧请求。

410

PLUGIN_AUTH_EXPIRED

原授权已过期,复核后重新授权。

422

PLUGIN_CREDENTIAL_REJECTED、PLUGIN_CREDENTIAL_NOT_PORTABLE

核对凭据或授权方式,不重复发布失效结果。

502/503

供应商、授权配置、执行器或服务不可用相关原因

保留安全的追踪信息,恢复后先核对当前状态。

鉴权或工作区准入层还可能返回字符串 code、msg 及追踪详情,例如 PLUGIN_ADMISSION_DENIED 或工作区成员资格错误。不能强制把所有错误解析成数字 code,也不能把 message 原文用作稳定判断值。没有 HTTP 响应时,不推断操作一定未生效。

最后更新于