xiantong 文档
消息

Lark / Feishu

将 Lark 或飞书 bot 连接到 xiantong，支持长连接、富文本、交互卡片和附件

将 Lark 或飞书 bot 连接到 xiantong，支持长连接模式、富文本回复、交互卡片和附件。

Lark（国际版）与飞书（中国）是同一平台在不同域名下的形态：Lark 使用 open.larksuite.com，飞书使用 open.feishu.cn。它们共享 SDK、消息类型和事件协议。一个自建应用注册在其中一个区域，请按您的租户选择。

xiantong 使用官方 @larksuiteoapi/node-sdk 的长连接（WebSocket）模式，无需公网 webhook URL 或反向隧道。

两种设置方式#

方式说明
推荐：面向 Agent 的快速创建在开放平台创建应用页面，如果看到 “Built for agents. Ready to connect” 入口，可直接创建带正确权限和事件设置的应用
手动设置自行创建自建应用并配置权限和事件，适合无法看到快速创建入口或需要显式控制授权的场景

无论哪种方式，您仍需要复制 App ID 和 App Secret，并粘贴到 xiantong 中。

创建应用#

  1. 打开开放平台：
  1. 使用工作或租户账号登录。
  2. 在 Developer Console 中创建 Custom App，设置名称和图标。
  3. 在应用首页复制 App ID（通常以 cli_ 开头）和 App Secret。请像密码一样保护 Secret。
  4. 在 Permissions & Scopes 中启用：
  • im:message — 读取消息事件
  • im:message.group_at_msg — 接收群组 @ 消息
  • im:message:send_as_bot — 以 bot 身份发送消息
  1. 在 Events & Callbacks 中将投递方式设为 Long connection mode，并订阅：
  • im.message.receive_v1

长连接模式不使用 webhook payload 加密，请不要填写 Encrypt Key，否则可能导致入站事件失败。

  1. 发布应用版本或启用开发租户模式，使 bot 能接收消息。

在应用中连接#

  1. 打开 设置 → 消息。
  2. 点击 Lark / Feishu 卡片上的 连接。
  3. 选择区域：Lark（国际版）或飞书（中国）。
  4. 粘贴 App ID 与 App Secret，点击 测试。xiantong 会换取 tenant_access_token；成功后显示绿色状态，失败时显示平台返回的错误。
  5. 点击 保存。凭据会存入工作区密钥链，Lark/Feishu 适配器会启动长连接。

第一次对话#

  1. 在 Lark / 飞书中搜索您的 bot，并给它发私聊。
  2. 发送 /pair，bot 会返回使用提示。
  3. 在 xiantong 中打开任意会话菜单，选择 Pair with Messaging → Lark，复制 6 位代码。
  4. 在 Lark / 飞书中发送配对命令。
  5. 绑定创建后，继续发送任意消息，Agent 回复会回到同一聊天。

群聊#

在群组中，bot 只会接收被 @提及 的消息。这是 Lark/飞书默认权限行为；未 @ bot 的消息不会在服务端投递给适配器。

富文本#

Agent 回复中的常见 Markdown 会尽量转换为 Lark post 富文本：

  • 粗体、斜体、删除线 可原生渲染
  • 链接可点击
  • 围栏代码块会带语言标签
  • 段落换行会保留

不完全支持的内容会以纯文本形式发送：

  • 标题（#、## 等）
  • 项目符号和编号列表
  • 表格
  • 行内代码

如果工作流重度依赖表格，可让 Agent 改用文字摘要。

交互卡片#

当 Agent 需要您在流程中输入选择（例如计划审批）时，按钮会渲染为 Lark 交互卡片。点击按钮后，Agent 会收到选择并继续。处理完成后，卡片会自动清理。

当前限制：

  • 每张卡片最多 10 个按钮
  • 按钮标签超过 30 个字符会被截断

附件#

私聊和群组 @ 提及中均支持附件：

  • 入站：向 bot 发送图片和文件，它们会被下载并提供给 Agent 使用。
  • 出站：Agent 可以把图片和文档发回聊天；文件说明会作为后续文本消息发送。

适配器限制：

  • 单个附件上限：20 MB
  • 音频、视频和贴纸暂不支持，会记录为 unsupported attachment

限制#

  • Lark 与飞书分属不同域名，一个 bot 只属于其中一个区域。
  • 群组中 bot 只接收 @ 提及消息。
  • 24 小时前的消息编辑可能被平台静默丢弃。
  • Markdown 标题、列表和表格在 post 中会降级为纯文本。

故障排除#

Bot 收不到消息#

确认已启用 im:message 权限，并在 Events & Callbacks 中订阅 im.message.receive_v1。同时检查投递方式是 Long connection，不是 webhook。

测试连接失败#

如果 App Secret 被重新生成，请复制新值。如果切换过租户，旧凭据可能已失效。

私聊可用，但群聊无响应#

bot 需要 im:message.group_at_msg 权限，并且群消息必须 @ bot。

卡片能显示但按钮无效#

确认应用已发布，或租户处于开发模式。草稿应用可能能显示卡片，但无法回传按钮事件。

文件超过 20 MB 无法发送#

请压缩或拆分文件。

查看日志#

日志位置：~/.xiantong/logs/messaging-gateway.log。可搜索 component:"lark-adapter" 或 event:"lark_*"。

上一页WhatsApp