飞书
飞书接入使用飞书开放平台长连接事件订阅，用户可私聊机器人或在群聊中 @ 机器人来查询状态、下发命令或提问；通道支持文本、富文本、图片和语音，但语音需要 ASR，否则会提示改用文本。
使用方式
| 方式 | 触发方式 | 说明 |
|---|---|---|
| 私聊机器人 | 直接向机器人发送消息 | 适合个人查询设备状态、下发控制命令。 |
| 群聊 @ 机器人 | 在群里 @ 机器人并输入问题 | 适合团队在同一个群里协作处理设备。 |
| 图片消息 | 发送图片，可附带说明文字 | 图片会作为视觉输入进入设备智能体。 |
| 语音消息 | 发送语音 | 需要先配置语音识别服务，语音会转成文本后进入对话。 |
在飞书后台准备应用
- 在飞书开放平台创建企业自建应用。
- 添加机器人能力。
- 在凭证与基础信息中复制
App ID和App Secret。 - 在事件订阅中选择长连接方式接收事件。
- 订阅
im.message.receive_v1。 - 按飞书消息事件要求开通读取消息、机器人发消息等权限。
- 发布应用，并把机器人加入需要使用的私聊或群聊。
如果事件订阅启用了加密或校验 token，需要同时保存 Encrypt Key 和 Verification Token，并在设备智能体控制台中填写。
在控制台填写配置
打开 设置 → IM 通道 → 飞书，填写以下字段：
| 字段 | .env | 说明 |
|---|---|---|
| 启用 | FEISHU_ENABLED | 是否启动飞书通道 |
| App ID | FEISHU_APP_ID | 飞书应用的 App ID，通常形如 cli_xxx |
| App Secret | FEISHU_APP_SECRET | 飞书应用的密钥 |
| Encrypt Key | FEISHU_ENCRYPT_KEY | 可选，事件订阅启用加密时填写 |
| Verification Token | FEISHU_VERIFICATION_TOKEN | 可选，事件订阅配置校验 token 时填写 |
| 白名单 | FEISHU_ALLOW_FROM | 可选，允许访问的飞书用户 open_id |
也可以在 .env 中配置：
bash
FEISHU_ENABLED=true
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=
FEISHU_VERIFICATION_TOKEN=
FEISHU_ALLOW_FROM=ou_xxx,ou_yyy保存后重启服务，配置才会生效。
验证接入
- 确认服务已重启。
- 日志中出现
Feishu: enabled和feishu channel started (WebSocket)。 - 私聊机器人发送一条消息，或在群里 @ 机器人。
- 如果启用了白名单，确认发送者的
open_id已写入白名单。
在群聊中使用时，需要 @ 机器人；私聊机器人时可以直接发送消息。图片消息会作为视觉输入进入设备智能体；语音消息会先转成文本，再进入对话。
常见检查项
- 没有回复：确认应用已发布，机器人已加入会话，且长连接事件订阅已启用。
- token 校验失败：确认飞书后台和设备智能体中的
Verification Token一致。 - 加密消息无法解析：确认
Encrypt Key完全一致，没有多余空格。 - 语音无法识别：先在 配置 中启用语音识别服务。