# 消息通道与插件连接

使用 `moi-cli agent` 的消息通道与插件连接子命令，为智能体或团队建立入站消息接收连接、维护外部渠道实例与回调规则，以及完成外部插件账号的 OAuth 授权与解绑。执行前请先完成 [配置与身份认证](../configuration-authentication.md)。

(cli-message-connections)=

## 连接入站消息通道

外部聊天平台的应用创建与权限配置见 [IM 双向通信](../../../guides/ai-studio/agents/manage-agents/im-connection/index.md)。在终端创建入站连接前，先查询当前部署开放的接入能力组合（`provider`、`channel_type`、`receive_mode`）以及目标智能体已有的连接：

```bash
moi-cli -auth pat -o agent list-ingress-capabilities --workspace-id "$WORKSPACE_ID"

moi-cli -auth pat -o agent list-ingress-connections \
  --workspace-id "$WORKSPACE_ID" \
  --target-kind agent \
  --target-workspace-id "$AGENT_WORKSPACE_ID" \
  --target-id "$AGENT_ID"
```

若当前部署支持 `slack`、`slack_app` 与 `managed_stream` 组合且尚无可用连接，将目标智能体、可用模型及 Slack 凭据写入受权限保护的本地文件 `ingress.json`（可通过 `moi-cli schema agent create-ingress-connection` 核对输入结构）：

```json
{
  "target": {
    "kind": "agent",
    "workspace_id": "<agent-workspace-id>",
    "id": "<agent-id>"
  },
  "provider": "slack",
  "channel_type": "slack_app",
  "receive_mode": "managed_stream",
  "agent_model": "<available-model>",
  "managed_stream": {
    "app_id": "<slack-app-id>",
    "app_token": "<slack-app-token>",
    "bot_token": "<slack-bot-token>"
  }
}
```

创建连接并读取运行状态：

```bash
INGRESS_JSON="$(moi-cli -auth pat -o agent create-ingress-connection \
  --workspace-id "$WORKSPACE_ID" \
  --json-file ingress.json)"

export CONNECTION_ID="$(printf '%s' "$INGRESS_JSON" | jq -r '.id')"

moi-cli -auth pat -o agent get-ingress-connection \
  --workspace-id "$WORKSPACE_ID" \
  --connection-id "$CONNECTION_ID"
```

创建 Slack 托管长连接后，服务端自动启动接收器。再次运行 `get-ingress-connection` 检查 `desired_state`、`observed_state` 与 `last_error_code`：

- 处于 `starting` 或 `reconnecting` 时继续有限次观察状态收敛。
- 出现 `auth_failed` 或 `config_invalid` 时先核正外部应用令牌与权限配置。
- 状态正常后，在 Slack 向应用发送一条验证消息，核对目标智能体运行记录与会话回复以确认收发链路就绪。

| 维护场景 | 命令与说明 |
| --- | --- |
| 校验回调模式连接 | `agent verify-ingress-connection` 仅用于回调接收模式，Slack `managed_stream` 长连接无需调用该命令。 |
| 回调或邮件轮询接入 | 回调模式与邮件轮询模式引用已创建的 `channel_instance_id`，与 `managed_stream` 内联凭据结构相互独立。 |
| 停用或删除入站连接 | 停用时通过 `agent update-ingress-connection` 提交 `enabled: false` 及最新两项版本号并回读状态；移除连接使用 `agent delete-ingress-connection`。 |

## 管理渠道实例与回调规则

使用以下子命令维护工具渠道实例与外部回调路由规则（复杂请求体可通过 `moi-cli schema agent <subcommand>` 查看，凭据配置统一保存为受保护的 `--json-file`）：

| 场景 | 子命令 | 说明 |
| --- | --- | --- |
| 查看连接器目录与维护渠道实例 | `list-connector-catalog`、`create-channel-instance`、`list-channel-instances`、`get-channel-instance`、`update-channel-instance`、`disable-channel-instance`、`bind-channel` | 修改或停用前先运行 `get-channel-instance` 读取当前配置与绑定关系。 |
| 测试渠道配置与实例连通性 | `test-channel-configuration`、`test-channel-instance` | 会向目标外部平台发起实际网络请求以验证凭据与连通性。 |
| 管理回调规则 | `create-callback-rule`、`list-callback-rules`、`get-callback-rule`、`update-callback-rule`、`delete-callback-rule` | 配置或更新外部事件回调到工作区目标的路由规则。 |

(cli-agent-plugin-releases)=

## 连接插件账号与完成 OAuth 授权

控制台界面授权说明见 [连接插件账号与恢复授权](../../../guides/ai-studio/agents/tools/plugin-connections.md)。在 CLI 中先列出插件发布与当前工作区已有的插件连接，再读取目标发布的 `connections` 声明：

```bash
moi-cli -auth pat -o agent list-plugin-releases --workspace-id "$WORKSPACE_ID" --namespace system
moi-cli -auth pat -o agent list-plugin-connections --workspace-id "$WORKSPACE_ID"

moi-cli -auth pat -o agent get-plugin-release \
  --workspace-id "$WORKSPACE_ID" \
  --release-id "$RELEASE_ID" \
  --namespace "$RELEASE_NAMESPACE"
```

若工作区已有匹配连接，直接跳至下方授权状态检查；需要新建连接时，从 `get-plugin-release` 输出的 `connections` 中选取驱动类型为 `oauth` 的条目，记录其 `requirement` 与 `profile` 并准备 `connection.json`（无需在此请求中填写外部平台账号密码）：

```json
{
  "release_namespace": "system",
  "release_id": "<plugin-release-id>",
  "requirement": "<connection-requirement-key>",
  "profile": "<oauth-profile-key>",
  "name": "我的插件账号"
}
```

创建插件连接并记录返回的连接 `id` 与 `version`：

```bash
CONN_JSON="$(moi-cli -auth pat -o agent create-plugin-connection \
  --workspace-id "$WORKSPACE_ID" \
  --json-file connection.json)"

export CONNECTION_ID="$(printf '%s' "$CONN_JSON" | jq -r '.id')"
export CONNECTION_VERSION="$(printf '%s' "$CONN_JSON" | jq -r '.version')"
```

### 发起并推进 OAuth 授权

查询当前授权状态后，传入 `--expected-version` 发起 OAuth 流程：

```bash
moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"

moi-cli -auth pat -o agent begin-plugin-oauth \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --expected-version "$CONNECTION_VERSION"
```

根据 `begin-plugin-oauth` 返回的 `grant` 类型分别完成授权：

- **`browser_handoff`**：在浏览器打开返回的 `authorization_url` 完成外部平台登录确认，随后重新运行 `get-plugin-authorization` 核对状态（该模式不返回可供 CLI 轮询的 `attempt_id`）。
- **返回非空 `attempt_id` 的授权模式**（如设备码授权，需先按提示在外部页面输入 `user_code`）：保存 `ATTEMPT_ID`，按响应 `poll_after` 指定的间隔与总超时上限调用 `poll-plugin-oauth`：

```bash
moi-cli -auth pat -o agent poll-plugin-oauth \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --attempt-id "$ATTEMPT_ID" \
  --expected-version "$CONNECTION_VERSION"

moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"
```

:::{warning}
每次 `poll-plugin-oauth` 仅推进单次状态检查，请按返回的 `status`、`reason`、`next_action` 与 `poll_after` 控制轮询节奏：
- `get-plugin-authorization` 返回结果中的 `attempt_id` 可能为空，中途恢复轮询时继续使用已保存的 `ATTEMPT_ID`。
- 若连接 `version` 发生变化，应立即停止旧尝试并重新读取连接与授权详情，切勿将新版本号直接拼入旧 `ATTEMPT_ID` 继续轮询。
:::

完成账号授权后，若尚未安装插件或需将该账号绑定到插件安装项，使用 `install-plugin`、`update-plugin-installation` 与 `get-plugin-installation` 将 `CONNECTION_ID` 和所选 `profile` 绑定至对应的连接 `requirement`。

(cli-plugin-disconnect)=

### 断开插件账号连接

先从最新 `get-plugin-authorization` 输出中读取当前 `generation`，确认影响范围后执行断开并回读验证：

```bash
moi-cli -auth pat -o agent disconnect-plugin-connection \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --expected-generation "$GENERATION"

moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"
```

断开连接后，依赖该外部账号的插件工具调用需重新完成授权方可继续运行。

## 限制和注意事项

- 请妥善限制 `ingress.json` 等包含外部平台 App Token、Bot Token 文件的本地读写权限（如 `chmod 600`），切勿将真实令牌、授权 URL、OAuth 回调参数或密钥写入版本库与公开日志。
- 入站连接就绪、插件账号授权成功与插件安装绑定分属独立状态，排障时请分别通过 `get-ingress-connection`、`get-plugin-authorization` 和 `get-plugin-installation` 核实。
