插件对象与状态¶
插件发布、安装、账号连接和授权分别维护标识与版本。账号连接保存非敏感配置,凭据通过独立动作提交。
输入标识¶
示例变量 |
来源 |
|---|---|
|
当前环境的个人访问令牌及目标工作区。 |
|
选择 |
|
插件发布列表的 |
|
发布详情的 |
|
创建连接或详情的 |
|
授权动作返回的非空 |
|
最新授权状态的 |
|
安装响应或详情中的 |
|
JSON 对象文件,按要求键保存完整 |
|
JSON 对象文件,按所选 profile 的字段声明保存凭据字符串;不将文件内容写入日志。 |
|
原 offset 加当前 items 数,仅在小于 total 时继续翻页。 |
|
搜索响应的 next_cursor,仅在 has_more 为 true 时继续。 |
|
需要检索的能力名称或描述文本。 |
|
搜索返回的 |
插件账号连接¶
字段 |
类型 |
说明 |
|---|---|---|
|
string |
连接 ID。 |
|
string |
所属工作区 ID。 |
|
string |
服务端生成的 provider 与连接 ID 展示值。 |
|
string |
创建时提交的账号说明;为空时可省略。 |
|
string |
连接的启用状态;创建为 |
|
string |
插件连接为 |
|
string |
从发布配置导出的资源,不由创建请求自选。 |
|
string |
由所选驱动与配置导出的认证类型。 |
|
string |
连接所有者,返回时用于识别归属。 |
|
string |
创建的账号连接为 |
|
object |
非敏感的发布与授权配置绑定。 |
|
string |
供应商。 |
|
string |
授权配置键。 |
|
string |
授权配置摘要,用于验证匹配关系。 |
|
string |
发布所属空间。 |
|
string |
发布 ID。 |
|
string |
要求键。 |
|
string |
托管会话的实际执行器 ID,存在时用于后续安装绑定。 |
|
integer |
连接元数据版本,供 |
|
string |
创建时间,RFC 3339 格式。 |
|
string |
更新时间,RFC 3339 格式。 |
|
string(字符串数组) |
可选能力列表。 |
|
object |
可选标签。 |
|
object |
可选注释。 |
|
object |
可选扩展信息。 |
|
string |
最近测试状态。 |
|
string |
最近测试时间。 |
|
string |
最近测试错误摘要。 |
|
string |
创建账号。 |
|
string |
最近修改账号。 |
账号的授权状态由独立接口返回;active 不代表 OAuth 已完成。无需凭据的 none 配置不进入 OAuth 或提交凭据流程。
账号授权状态¶
字段 |
类型 |
说明 |
|---|---|---|
|
string |
授权所属工作区 ID。 |
|
string |
账号连接 ID。 |
|
integer |
授权对应的连接版本。 |
|
string |
当前授权状态。 |
|
integer |
授权代次;断开需读取最新值。 |
|
integer |
同一代次中的凭据修订。 |
|
string |
已确认的供应商账号标识,存在时返回。 |
|
string |
部分托管账号的显示名称,存在时返回;不作为授权标识。 |
|
string |
部分进行中托管会话返回的尝试 ID;不能假定所有 OAuth 都能由此恢复。 |
|
调用者处理 |
|---|---|
|
尚无授权记录,代次与修订为 0;按配置发起适用的授权。 |
|
按动作继续用户授权,必要时用原尝试 ID 检查。 |
|
授权已就绪;实际调用仍受当前权限、配置和凭据有效性约束。 |
|
OAuth 凭据正在刷新;不要自行复制或替换凭据。 |
|
托管会话正在清理或到期处理中,不能按 ready 处理。 |
|
按当前配置重新授权;本地断开不保证供应商撤销已完成。 |
授权动作和检查结果¶
动作字段 |
类型 |
说明 |
|---|---|---|
|
string |
|
|
string |
具体尝试 ID;浏览器交接时为空字符串。 |
|
string |
当前分支返回的用户操作页面。 |
|
string |
设备授权需要时返回。 |
|
integer |
再次检查的等待秒数,适用时返回。 |
|
string |
当前动作的到期时间。 |
external 发起授权码配置时返回 browser_handoff。登录产品浏览器页面后,由浏览器发起实际授权码流程并保留安全证明 Cookie。浏览器证明不通过外部客户端传递。
检查结果字段 |
类型 |
说明 |
|---|---|---|
|
string |
被检查的原尝试 ID。 |
|
string |
|
|
string |
失败或状态原因,存在时返回。 |
|
integer |
下次检查等待秒数,适用时返回。 |
|
object |
需要继续用户操作时提供新的授权动作。 |
检查成功后再读取账号授权状态。没有尝试 ID 时不能构造轮询路径,也不能通过重复发起授权来代替状态查询。
插件发布¶
字段 |
类型 |
说明 |
|---|---|---|
|
string |
发布 ID。 |
|
string |
发布所属空间 ID;请求用 namespace 选择空间。 |
|
string |
注册来源。 |
|
string |
发布者。 |
|
string |
插件名称。 |
|
string |
插件声明的版本文本,与安装/连接的整数版本不同。 |
|
string |
不可变发布摘要。 |
|
string |
发布说明。 |
|
string |
可选本地化名称。 |
|
string |
可选本地化说明。 |
|
string |
发布账号。 |
|
string |
发布时间。 |
发布详情另外包含 manifest、connections、profile_digests、servers、operations、skills。manifest 保存插件包名称、版本、说明、可选作者/主页/仓库/许可/关键词和扩展。
连接要求字段 |
类型 |
说明 |
|---|---|---|
|
string |
账号供应商。 |
|
boolean |
要求是否可选,存在时返回。 |
|
object |
可选择的授权配置映射。 |
|
string |
|
|
string |
固定的账号资源。 |
|
object |
凭据字段声明,包含 |
|
object |
OAuth 注册键、授权方式和范围。 |
|
string |
静态凭据认证类型,适用时返回。 |
|
object |
发布固定的凭据核验配置。 |
|
object(对象数组) |
凭据字段注入规则。 |
|
object |
TLS 证书和私钥的字段映射。 |
|
string |
适配器。 |
|
string(字符串数组) |
授权范围。 |
|
object[] |
每项含 |
插件安装¶
字段 |
类型 |
说明 |
|---|---|---|
|
string |
安装 ID。 |
|
string |
当前工作区 ID。 |
|
string |
发布所属空间。 |
|
string |
发布 ID。 |
|
string |
发布名称。 |
|
string |
发布摘要。 |
|
string |
安装所有者。 |
|
object |
完整账号绑定映射;更新时替换,不合并。 |
|
string |
所选账号连接 ID。 |
|
string |
所选授权配置键。 |
|
string |
托管会话要求的实际执行器 ID。 |
|
integer |
安装版本;与连接 version 和授权 generation 分开。 |
|
string |
创建时间。 |
|
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 |
|
核对字段、命名空间、分页、配置及尝试标识。 |
404 |
|
核对资源身份及可见范围。 |
409 |
|
回读当前连接、安装或授权;不盲目重试旧请求。 |
410 |
|
原授权已过期,复核后重新授权。 |
422 |
|
核对凭据或授权方式,不重复发布失效结果。 |
502/503 |
供应商、授权配置、执行器或服务不可用相关原因 |
保留安全的追踪信息,恢复后先核对当前状态。 |
鉴权或工作区准入层还可能返回字符串 code、msg 及追踪详情,例如 PLUGIN_ADMISSION_DENIED 或工作区成员资格错误。不能强制把所有错误解析成数字 code,也不能把 message 原文用作稳定判断值。没有 HTTP 响应时,不推断操作一定未生效。