飞书

通过 WebSocket 长连接模式将 GolemBot 助手接入飞书。无需公网 IP。

前置条件

bash

pnpm add @larksuiteoapi/node-sdk

权限 Scope	是否必需	用途	未开通时的影响
`im:message`	必需	向用户和群组发送消息	Bot 无法回复
`im:message:readonly`	必需	通过 WebSocket 事件接收消息	Bot 收不到任何消息
`im:message.group_at_msg:readonly`	必需	接收群聊中 @机器人的消息	Bot 在群聊中不可见
`contact:user.base:readonly`	必需	从通讯录 API 读取用户基本信息（显示名称）	Bot 无法识别用户名
`contact:contact.base:readonly`	必需	读取通讯录基础信息（需与上条配合使用）	Bot 无法识别用户名
`im:chat:readonly`	可选	获取群成员列表，用于回复中的 @mention 支持	回复中的 `@名字` 以纯文本发送，不触发飞书原生提及

TIP

未开通两个 contact: 权限时，Bot 仍可正常工作，但会将用户显示为 ou_xxxxx 形式的 ID，无法知道对方叫什么名字。

yaml

# golem.yaml
channels:
  feishu:
    appId: ${FEISHU_APP_ID}
    appSecret: ${FEISHU_APP_SECRET}

# .env
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxx

字段	类型	默认值	说明
`appId`	`string`	—	飞书 App ID（必填）
`appSecret`	`string`	—	飞书 App Secret（必填）

适配器自动检测 AI 回复是否包含 Markdown 格式：

纯文本 — 以 msg_type: "text" 发送（无转换）
Markdown — 以消息卡片发送（msg_type: "interactive"），使用飞书卡片 v2 原生 Markdown 渲染。支持标题、列表、加粗/斜体、带语法高亮的代码块、引用、表格和链接

标准 Markdown 语法自动转换，无需额外配置。

传输：通过 @larksuiteoapi/node-sdk 的 WSClient 建立 WebSocket 长连接
事件：监听 im.message.receive_v1 事件，处理 text、image、post、file、audio 五类消息
回复：通过 client.im.v1.message.create() 发送消息，根据内容自动选择格式
聊天类型：支持单聊（私信）和群聊
私聊上下文：私聊中 Gateway 会注入发送者的显示名称，让 bot 知道对方是谁
群聊 @mention 过滤：群聊中机器人只在被直接 @提及时才响应，@mention 的 key 会在传给引擎前自动从消息文本中剥除
回复中的 @mention：当 AI 回复包含 @名字 且匹配群内已知成员时，自动转换为飞书原生 @mention（蓝色可点击标签）。群成员通过 API 自动获取并缓存 10 分钟。需要 im:chat:readonly 权限

bash

golembot gateway --verbose

适配器启动时通过 WebSocket 连接飞书。--verbose 模式下消息日志带 [feishu] 前缀。

飞书适配器支持追踪用户是否已读机器人发送的消息。当用户打开包含未读 bot 消息的聊天时，适配器会收到 im.message.message_read_v1 事件，包含阅读者 ID、消息 ID 列表和阅读时间戳。

启用已读回执：

这是一个被动追踪功能——告诉你用户是否看过 bot 的消息。无需额外权限，现有的 im:message scope 即可。