集成

Lark / 飞书集成配置指南

本文带你在Lark / 飞书开发者后台创建一个企业自建应用，完成机器人能力、API 权限、事件与回调订阅等配置，并在 Kocoro 中注册。完成后，团队成员就能在飞书的单聊或群聊中向机器人发消息或 @它，由你的智能体回复。

开始前的准备

一个具备「创建企业自建应用」权限的Lark / 飞书账号。
已安装并完成初始化的 Kocoro，并至少创建一个智能体。
能够正常访问Lark / 飞书开发者后台与 Kocoro 服务的网络环境。

1
创建企业自建应用
使用具备相应权限的账号登录 Lark / 飞书开发者后台（open.larksuite.com/app，飞书国内为 open.feishu.cn/app），点击「创建企业自建应用」。
图 1：在Lark / 飞书开发者后台点击「创建企业自建应用」。
2
填写应用信息并创建
在弹窗中填写应用名称、应用描述，选择或上传应用图标，然后点击「创建」。
图 2：填写应用名称、描述与图标后点击「创建」。
3
复制 App ID 与 App Secret
进入应用后台，在左侧「凭证与基础信息」页复制「App ID」与「App Secret」。这两个凭证用于 Kocoro 与Lark / 飞书建立连接。
请妥善保存 App Secret；如泄漏可在同一页面重置。
图 3：在「凭证与基础信息」页复制 App ID 与 App Secret。
4
在 Kocoro 中添加Lark / 飞书机器人
打开 Kocoro，进入「能力 → 连接器」，在「Lark（国际）」/「飞书（国内）」分组点击「添加机器人」。在弹窗（步骤 1/3）中填入上一步的「应用 ID」与「应用密钥」，点击「下一步」。
飞书暂不支持一键授权，请使用应用凭证连接。
图 4：在 Kocoro 中填入 App ID 与应用密钥（步骤 1/3）。
5
获取 Encrypt Key
进入「事件与回调 → 加密策略」，在「Encrypt Key」处点击「重置」生成密钥并填入 Kocoro。
图 5：在「事件与回调 → 加密策略」重置并复制 Encrypt Key。
6
添加「机器人」能力
回到Lark / 飞书开发者后台，进入「添加应用能力」，在「机器人」卡片上点击「添加」。这样应用才能以机器人身份在Lark / 飞书中收发消息。
图 6：在「添加应用能力」中为应用添加「机器人」能力。
7
开通 API 权限
进入「权限管理」，点击「开通权限」。在搜索框粘贴下方权限列表，全选后点击「确认开通权限」（共 10 项）。
im:resource,contact:contact.base:readonly,contact:user.base:readonly,im:message.group_at_msg:readonly,im:message.p2p_msg:readonly,im:message:send_as_bot,im:message,cardkit:card:write,im:message:readonly,im:message.reactions:read
也可以在 Kocoro 的添加机器人弹窗中点击「打开权限配置页面」，系统会自动带上这些权限。
图 7：在「权限管理 → 开通权限」中批量添加 10 项权限。
8
回到 Kocoro 完成注册
回到 Kocoro 的添加机器人弹窗（步骤 2/3）：将第 5 步复制的 Encrypt Key 粘贴到「获取 Encrypt Key」输入框；确认已完成「添加机器人」与「配置权限」（可点击对应链接核对）；在「选择智能体」中选择要响应消息的智能体，可选填显示名称，最后点击「注册机器人」。
图 8：在 Kocoro 中粘贴 Encrypt Key、选择智能体并注册机器人（步骤 2/3）。
9
配置事件订阅地址
进入「事件与回调 → 事件配置」，订阅方式选择「将事件发送至开发者服务器」，在「请求地址」中填入下方地址并保存。
https://api.shannon.run/api/v1/channels/feishu/events
图 9：事件配置选择「将事件发送至开发者服务器」并填入请求地址。
10
添加「接收消息」事件
在事件配置页点击「添加事件」，搜索并勾选「接收消息（im.message.receive_v1）」，点击「添加」。
im.message.receive_v1
图 10：添加「接收消息」事件。
11
配置回调订阅地址
切换到「回调配置」标签，订阅方式同样选择「将回调发送至开发者服务器」，在「请求地址」中填入与事件相同的地址并保存。
https://api.shannon.run/api/v1/channels/feishu/events
图 11：回调配置选择「将回调发送至开发者服务器」并填入请求地址。
12
添加「卡片回传交互」回调
在回调配置页点击「添加回调」，在「卡片」分类下勾选「卡片回传交互（card.action.trigger）」，点击「添加」。
card.action.trigger
图 12：添加「卡片回传交互」回调。
13
发布应用使配置生效
最后进入Lark / 飞书开发者后台的「版本管理与发布」，设置可用范围后点击「保存」创建版本并发布。应用发布（管理员审核通过）后，以上配置才会正式生效。
顶部若提示「应用发布后，当前配置方可生效」，即表示需要完成这一步。
图 13：在「版本管理与发布」保存并发布应用，使配置生效。