# 飞书

飞书接入使用飞书开放平台长连接事件订阅，用户可私聊机器人或在群聊中 @ 机器人来查询状态、下发命令或提问；通道支持文本、富文本、图片和语音，但语音需要 ASR，否则会提示改用文本。

## 使用方式

| 方式 | 触发方式 | 说明 |
| --- | --- | --- |
| 私聊机器人 | 直接向机器人发送消息 | 适合个人查询设备状态、下发控制命令。 |
| 群聊 @ 机器人 | 在群里 @ 机器人并输入问题 | 适合团队在同一个群里协作处理设备。 |
| 图片消息 | 发送图片，可附带说明文字 | 图片会作为视觉输入进入设备智能体。 |
| 语音消息 | 发送语音 | 需要先配置语音识别服务，语音会转成文本后进入对话。 |

## 在飞书后台准备应用

1. 在飞书开放平台创建企业自建应用。
2. 添加机器人能力。
3. 在凭证与基础信息中复制 `App ID` 和 `App Secret`。
4. 在事件订阅中选择长连接方式接收事件。
5. 订阅 `im.message.receive_v1`。
6. 按飞书消息事件要求开通读取消息、机器人发消息等权限。
7. 发布应用，并把机器人加入需要使用的私聊或群聊。

如果事件订阅启用了加密或校验 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
```

保存后重启服务，配置才会生效。

## 验证接入

1. 确认服务已重启。
2. 日志中出现 `Feishu: enabled` 和 `feishu channel started (WebSocket)`。
3. 私聊机器人发送一条消息，或在群里 @ 机器人。
4. 如果启用了白名单，确认发送者的 `open_id` 已写入白名单。

在群聊中使用时，需要 @ 机器人；私聊机器人时可以直接发送消息。图片消息会作为视觉输入进入设备智能体；语音消息会先转成文本，再进入对话。

## 常见检查项

- 没有回复：确认应用已发布，机器人已加入会话，且长连接事件订阅已启用。
- token 校验失败：确认飞书后台和设备智能体中的 `Verification Token` 一致。
- 加密消息无法解析：确认 `Encrypt Key` 完全一致，没有多余空格。
- 语音无法识别：先在 [配置](../../operate-reference/configuration.md) 中启用语音识别服务。