> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 飞书集成

飞书集成用于保存飞书或 Lark 自建应用的凭证、事件接收方式和运行状态。它只负责把飞书平台连接到 Xpert AI；要让消息进入某个数字专家，还必须在目标数字专家工作流中添加并发布 [飞书触发器](../trigger/lark-trigger/)。

当前 `@xpert-ai/plugin-lark` 使用同一个集成提供方 `lark`，通过 **连接方式** 字段区分 Webhook 和长连接。

<Tip>
  飞书属于通信类插件，必须在**租户级别**安装 `@xpert-ai/plugin-lark`。租户级安装会注册飞书系统集成提供方、Webhook/长连接入口和飞书触发器；如果只在组织、项目或个人范围安装，后续创建集成和触发器时可能找不到对应能力。
</Tip>

## 接入方式

| 接入方式    | 适合场景                         | 需要公网回调 | 关键配置                                                     |
| ------- | ---------------------------- | ------ | -------------------------------------------------------- |
| Webhook | 已有稳定公网 API 地址，且需要按飞书事件回调接收消息 | 需要     | `App ID`、`App Secret`、`Verification Token`、`Encrypt Key` |
| 长连接     | 推荐模式，本地调试或不方便暴露公网回调地址        | 不需要    | `App ID`、`App Secret`、`connectionMode=long_connection`   |

默认推荐使用 **长连接**（`connectionMode=long_connection`）。只有在已经具备稳定公网 HTTPS 回调地址，或需要兼容 Webhook 回调部署时，再使用 Webhook。

Webhook 模式保存后会生成回调地址：

```text theme={null}
https://<your-api-domain>/api/lark/webhook/<integrationId>
```

长连接模式不会使用上面的回调地址，而是由 Xpert AI 服务端主动连接飞书开放平台事件通道。

## 准备飞书应用

1. 登录 [飞书开发者后台](https://open.feishu.cn/app)。
2. 创建企业自建应用，并添加 **机器人** 能力。
3. 在应用凭证中复制：
   * **App ID**
   * **App Secret**
4. 在事件与回调中选择接收方式：
   * Webhook 模式：配置请求地址和事件订阅。
   * 长连接模式：选择使用长连接接收事件。
5. 按下面的“事件订阅”和“必需权限”开通应用能力。
6. 发布应用版本，并把应用可用范围设置给需要使用的用户或部门。

### 事件订阅

| 事件                      | 用途                                   |
| ----------------------- | ------------------------------------ |
| `im.message.receive_v1` | 接收单聊和群聊消息。没有这个事件时，飞书消息不会进入 Xpert AI。 |

### 必需权限

在飞书开放平台的 **权限管理** 中按权限名搜索并申请。申请后必须发布应用版本，并让用户或部门重新获得新版本权限。

| 权限                                             | 用途                                 |
| ---------------------------------------------- | ---------------------------------- |
| `im:message.group_at_msg.include_bot:readonly` | 获取群组中其他机器人和用户 @ 当前机器人的消息。          |
| `im:message.group_at_msg:readonly`             | 获取群组中用户 @ 机器人的消息。                  |
| `im:message.p2p_msg:readonly`                  | 读取用户发给机器人的单聊消息。                    |
| `im:message.reactions:write_only`              | 发送、删除消息表情回复。                       |
| `im:message:send_as_bot`                       | 以机器人身份发送回复消息。缺少时，机器人可能能收到消息，但无法回复。 |

## 在 Xpert AI 创建集成

先切换到要使用飞书机器人的目标组织，再进入 **设置 -> 系统集成**，创建提供方为 **飞书** 的集成。系统集成是组织级别创建的，后续飞书触发器只能选择当前组织下已有的集成。

### 必填配置

| 配置项          | 说明                                                                  |
| ------------ | ------------------------------------------------------------------- |
| `App ID`     | 飞书/Lark 自建应用的 App ID。                                               |
| `App Secret` | 飞书/Lark 自建应用的 App Secret。保存后测试会用它换取 `tenant_access_token` 并读取机器人信息。 |

### Webhook 配置

| 配置项                  | 说明                                                              |
| -------------------- | --------------------------------------------------------------- |
| `Verification Token` | 飞书事件订阅中配置的校验 Token。Webhook 收到 `url_verification` 时会校验它。         |
| `Encrypt Key`        | 飞书事件订阅中的加密密钥。启用加密事件时必须填写。                                       |
| `连接方式`               | 选择 `Webhook（传统连接方式，稳定）`。如果页面默认值是 Webhook，但计划使用推荐的长连接，请手动切换到长连接。 |

保存或测试集成后，复制测试结果中的 Webhook URL，填入飞书事件订阅的请求地址。Webhook 模式会拒绝长连接集成的回调请求，因此如果切换连接方式，需要同步调整飞书后台配置。

### 长连接配置

| 配置项      | 说明                              |
| -------- | ------------------------------- |
| `连接方式`   | 选择 `长连接（支持个人电脑调试，灵活且安全）`。       |
| `国际版`    | 使用国际版 Lark 时勾选；不勾选时访问中国版飞书开放平台。 |
| `首选语言`   | 可选，影响错误提示和系统提示。                 |
| `用户自动开通` | 可选，允许把飞书用户自动映射或创建为平台用户。         |

长连接测试会先校验 App 凭证和机器人信息，再探测飞书长连接端点。新创建的长连接集成如果保存后没有自动连接，可能需要等待插件运行时刷新或重启插件服务。

## 测试结果怎么看

集成测试成功后会返回当前模式：

* Webhook 模式返回 `webhookUrl`，用于填入飞书后台。
* 长连接模式返回 `probe.connected`、`probe.state`、`probe.lastError` 等探测结果。

如果测试失败，优先检查 App ID、App Secret、应用版本是否已发布、机器人能力是否启用，以及应用可用范围是否包含当前测试用户。

## 状态与会话页签

飞书集成详情页提供扩展页签：

* **状态**：连接方式、状态、机器人用户、持有实例、最近连接时间和最近错误。
* **用户**：展示插件记录或读取到的飞书用户，可用于触发器的指定用户选择。
* **会话**：展示当前集成下的飞书会话绑定，包括会话类型、会话 ID、发送者 Open ID、数字专家 ID、对话 ID 和更新时间。

长连接模式下，状态页支持刷新、重连和断开。Webhook 模式主要依赖飞书回调可达性和事件订阅配置。

## 和飞书触发器配合

完成集成后，还需要：

1. 打开目标数字专家工作流。
2. 添加 [飞书触发器](../trigger/lark-trigger/)。
3. 选择这个飞书集成。
4. 配置单聊范围、群聊范围、群内回复策略、会话超时和消息汇总时间。
5. 发布数字专家。

没有发布触发器时，飞书事件即使能到达 Xpert AI，也不会路由到目标数字专家。

## 常见问题

### Webhook URL 校验失败

检查：

* `API_BASE_URL` 是否是公网可访问的 HTTPS 地址；
* 反向代理是否把 `/api/lark/webhook/<integrationId>` 转发到 Xpert API 服务；
* 飞书后台的 Verification Token 和集成中的 `Verification Token` 是否一致；
* 启用加密事件时 `Encrypt Key` 是否一致。

### 长连接一直不是 connected

检查：

* 飞书后台是否选择长连接接收事件；
* 服务端是否能访问飞书开放平台长连接端点；
* App ID/App Secret 是否属于同一个应用；
* 应用是否已发布且机器人能力已启用。

### 选择器无法列出群聊或用户

群聊选择器调用飞书群聊列表，用户选择器调用通讯录部门用户列表。请补齐飞书应用权限并重新发布应用。