飞书集成用于保存飞书或 Lark 自建应用的凭证、事件接收方式和运行状态。它只负责把飞书平台连接到 Xpert AI；要让消息进入某个数字专家，还必须在目标数字专家工作流中添加并发布 飞书触发器。
当前 @xpert-ai/plugin-lark 使用同一个集成提供方 lark，通过 连接方式 字段区分 Webhook 和长连接。
飞书属于通信类插件，必须在租户级别安装 @xpert-ai/plugin-lark。租户级安装会注册飞书系统集成提供方、Webhook/长连接入口和飞书触发器；如果只在组织、项目或个人范围安装，后续创建集成和触发器时可能找不到对应能力。
接入方式
| 接入方式 | 适合场景 | 需要公网回调 | 关键配置 |
|---|
| Webhook | 已有稳定公网 API 地址，且需要按飞书事件回调接收消息 | 需要 | App ID、App Secret、Verification Token、Encrypt Key |
| 长连接 | 推荐模式，本地调试或不方便暴露公网回调地址 | 不需要 | App ID、App Secret、connectionMode=long_connection |
connectionMode=long_connection）。只有在已经具备稳定公网 HTTPS 回调地址，或需要兼容 Webhook 回调部署时，再使用 Webhook。
Webhook 模式保存后会生成回调地址：
https://<your-api-domain>/api/lark/webhook/<integrationId>
准备飞书应用
- 登录 飞书开发者后台。
- 创建企业自建应用，并添加 机器人 能力。
- 在应用凭证中复制：
- 在事件与回调中选择接收方式：
- Webhook 模式：配置请求地址和事件订阅。
- 长连接模式：选择使用长连接接收事件。
- 按下面的“事件订阅”和“必需权限”开通应用能力。
- 发布应用版本，并把应用可用范围设置给需要使用的用户或部门。
事件订阅
| 事件 | 用途 |
|---|
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，但计划使用推荐的长连接，请手动切换到长连接。 |
长连接配置
| 配置项 | 说明 |
|---|
连接方式 | 选择 长连接（支持个人电脑调试，灵活且安全）。 |
国际版 | 使用国际版 Lark 时勾选；不勾选时访问中国版飞书开放平台。 |
首选语言 | 可选，影响错误提示和系统提示。 |
用户自动开通 | 可选，允许把飞书用户自动映射或创建为平台用户。 |
测试结果怎么看
集成测试成功后会返回当前模式：
- Webhook 模式返回
webhookUrl，用于填入飞书后台。
- 长连接模式返回
probe.connected、probe.state、probe.lastError 等探测结果。
如果测试失败，优先检查 App ID、App Secret、应用版本是否已发布、机器人能力是否启用，以及应用可用范围是否包含当前测试用户。
状态与会话页签
飞书集成详情页提供扩展页签：
- 状态：连接方式、状态、机器人用户、持有实例、最近连接时间和最近错误。
- 用户：展示插件记录或读取到的飞书用户，可用于触发器的指定用户选择。
- 会话：展示当前集成下的飞书会话绑定，包括会话类型、会话 ID、发送者 Open ID、数字专家 ID、对话 ID 和更新时间。
长连接模式下，状态页支持刷新、重连和断开。Webhook 模式主要依赖飞书回调可达性和事件订阅配置。
和飞书触发器配合
完成集成后，还需要：
- 打开目标数字专家工作流。
- 添加 飞书触发器。
- 选择这个飞书集成。
- 配置单聊范围、群聊范围、群内回复策略、会话超时和消息汇总时间。
- 发布数字专家。
没有发布触发器时，飞书事件即使能到达 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 是否属于同一个应用；
- 应用是否已发布且机器人能力已启用。
选择器无法列出群聊或用户
群聊选择器调用飞书群聊列表，用户选择器调用通讯录部门用户列表。请补齐飞书应用权限并重新发布应用。 
