@xpert-ai/plugin-lark 使用同一个集成提供方 lark，通过 连接方式 字段区分 Webhook 和长连接。
接入方式
默认推荐使用 长连接（
connectionMode=long_connection）。只有在已经具备稳定公网 HTTPS 回调地址，或需要兼容 Webhook 回调部署时，再使用 Webhook。
Webhook 模式保存后会生成回调地址：
准备飞书应用
- 登录 飞书开发者后台。
- 创建企业自建应用，并添加 机器人 能力。
- 在应用凭证中复制：
- App ID
- App Secret
- 在事件与回调中选择接收方式：
- Webhook 模式：配置请求地址和事件订阅。
- 长连接模式：选择使用长连接接收事件。
- 按下面的“事件订阅”和“必需权限”开通应用能力。
- 发布应用版本，并把应用可用范围设置给需要使用的用户或部门。
事件订阅
长连接配置卡片回传交互
使用长连接时，还需要在飞书开放平台订阅卡片回传交互：- 打开 飞书开放平台，进入与当前飞书集成对应的自建应用。
- 在左侧进入 开发配置 -> 事件与回调。
- 打开 回调配置 页签。
- 在 订阅方式 中选择 使用长连接接收回调。
- 在 已订阅的回调 区域点击 添加回调。
- 搜索并添加 卡片回传交互，对应的事件名称必须是
card.action.trigger。不要选择旧版的card.action.trigger_v1，旧版不支持长连接。 - 保存配置。
- 进入 应用发布 -> 版本管理与发布。
- 创建新版本并发布。如果企业要求管理员审批，还需要完成审批，否则配置不会对线上机器人生效。
- 回到 Xpert AI，确认飞书集成的长连接状态为
connected，然后让机器人重新发送一张新卡片，再点击 End 测试。
必需权限
在飞书开放平台的 权限管理 中按权限名搜索并申请。申请后必须发布应用版本，并让用户或部门重新获得新版本权限。在 Xpert AI 创建集成
先切换到要使用飞书机器人的目标组织，再进入 设置 -> 系统集成，创建提供方为 飞书 的集成。系统集成是组织级别创建的，后续飞书触发器只能选择当前组织下已有的集成。必填配置
Webhook 配置
保存或测试集成后，复制测试结果中的 Webhook URL，填入飞书事件订阅的请求地址。Webhook 模式会拒绝长连接集成的回调请求，因此如果切换连接方式，需要同步调整飞书后台配置。
长连接配置
长连接测试会先校验 App 凭证和机器人信息，再探测飞书长连接端点。新创建的长连接集成如果保存后没有自动连接，可能需要等待插件运行时刷新或重启插件服务。
测试结果怎么看
集成测试成功后会返回当前模式：- Webhook 模式返回
webhookUrl，用于填入飞书后台。 - 长连接模式返回
probe.connected、probe.state、probe.lastError等探测结果。
状态与会话页签
飞书集成详情页提供扩展页签：- 状态：连接方式、状态、机器人用户、持有实例、最近连接时间和最近错误。
- 用户：展示插件记录或读取到的飞书用户，可用于触发器的指定用户选择。
- 会话：展示当前集成下的飞书会话绑定，包括会话类型、会话 ID、发送者 Open ID、数字专家 ID、对话 ID 和更新时间。
和飞书触发器配合
完成集成后，还需要：- 打开目标数字专家工作流。
- 添加 飞书触发器。
- 选择这个飞书集成。
- 配置单聊范围、群聊范围、群内回复策略、会话超时和消息汇总时间。
- 发布数字专家。
常见问题
Webhook URL 校验失败
检查：API_BASE_URL是否是公网可访问的 HTTPS 地址；- 反向代理是否把
/api/lark/webhook/<integrationId>转发到 Xpert API 服务； - 飞书后台的 Verification Token 和集成中的
Verification Token是否一致； - 启用加密事件时
Encrypt Key是否一致。
长连接一直不是 connected
检查：- 飞书后台是否选择长连接接收事件；
- 服务端是否能访问飞书开放平台长连接端点；
- App ID/App Secret 是否属于同一个应用；
- 应用是否已发布且机器人能力已启用。