# 插件对象与状态

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

## 输入标识

| 示例变量 | 来源 |
| --- | --- |
| `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` 随语言本地化。

```json
{"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 响应时，不推断操作一定未生效。
