# 连接插件账号

为插件的连接要求创建外部账号连接，完成 OAuth，并将连接用于插件安装。服务地址和个人访问令牌按[调用前准备](../../api-call-basics.md)配置。

## 创建连接

先从插件发布列表选择发布版本，读取其连接要求和授权配置；已有连接时直接查询授权状态。将相应值保存到 `connection.json`：

```json
{"release_namespace":"system","release_id":"<发布ID>","requirement":"<连接要求键>","profile":"<配置键>","name":"我的插件账号"}
```

```shell
curl -X POST "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/plugin-connections" \
  -H "X-API-Key: $PRODUCT_API_KEY" -H "X-Workspace-ID: $WORKSPACE_ID" -H 'Content-Type: application/json' \
  --data-binary @connection.json
```

保存业务响应中连接的 `id`、`version`。连接不包含外部账号密码；OAuth 按所选发布配置交接。

## 授权与回读

所有下列路径相对 Product API Endpoint。`id` 为同一连接的 ID，有尝试 ID 时保存授权动作返回的 `attempt_id`；授权状态不保证返回该字段。

| 方法与路径 | 输入与结果 |
| --- | --- |
| `GET /workspaces/{workspace_id}/plugin-releases?namespace=system` | 选择可见发布；工作区发布使用 `namespace=workspace`。 |
| `GET /workspaces/{workspace_id}/plugin-releases/{release_id}` | 读取连接要求；按发布的命名空间传查询参数。 |
| `GET /workspaces/{workspace_id}/plugin-connections` | 选择已有连接。 |
| `GET /workspaces/{workspace_id}/plugin-connections/{id}` | 读取当前连接与版本。 |
| `GET /workspaces/{workspace_id}/plugin-connections/{id}/authorization` | 授权状态、连接版本与授权代次（`generation`）；部分托管会话状态还会提供当前尝试 ID。 |
| `POST /workspaces/{workspace_id}/plugin-connections/{id}/oauth` | JSON 包含当前 `expected_version` 与 `initiator:"external"`；返回浏览器交接或设备授权动作。 |
| `POST /workspaces/{workspace_id}/plugin-connections/{id}/oauth/{attempt_id}/poll` | JSON 包含当前 `expected_version`；执行一次检查，返回状态及等待间隔。 |
| `POST /workspaces/{workspace_id}/plugin-connections/{id}/disconnect` | JSON 包含授权状态的 `expected_generation`，断开后再次回读。 |

按返回的 `grant` 继续：`browser_handoff` 表示转到产品浏览器页面完成授权，此响应的 `attempt_id` 为空。打开 `authorization_url` 后回读授权状态；不要用空 ID 调用轮询。`device_code` 和 `managed_session` 等返回有效尝试 ID 时，保存该 ID；需要用户码时使用 `user_code`，并遵守 `poll_after` 和总等待上限。

中断后，结合已保存的尝试 ID 和最新状态继续。状态未返回 `attempt_id` 不表示原尝试已经失效。版本改变时先停止旧尝试，核对当前连接和授权，不能仅把新版本号套到旧尝试上。账号显示名称只用于展示，后续操作使用连接标识。

账号授权后，再将连接和授权配置绑定到插件安装的对应连接要求，并读取安装结果。SDK 与 CLI 的实际调用示例分别见 SDK [连接插件账号](../../../sdk/ai-studio/智能体/连接插件账号.md) 和 CLI [消息通道与插件连接](../../../cli/tasks/channels-plugins.md#cli-agent-plugin-releases)。
