飞书接入指南

将飞书机器人连接到 Elisi Agent

完成连接后，你可以直接在飞书中私聊自己的企业机器人，让 Elisi Agent 帮你记录和查询 任务、清单等内容。

开始前

你需要：

• 一个 Elisi 账号。
• 飞书企业自建应用的创建和发布权限。
• 企业管理员批准应用权限（如果企业要求审批）。

1. 创建飞书应用

1. 打开飞书开放平台，进入开发者后台。
2. 创建一个“企业自建应用”。
3. 在“添加应用能力”中启用“机器人”。
4. 在“权限管理”中添加：
   • 获取用户发给机器人的单聊消息。
   • 以应用身份发送消息。
   • 如需在群聊中使用，再添加接收群聊中机器人被 @ 消息的权限。

记下应用的 App ID 和 App Secret。

2. 在 Elisi 中连接机器人

1. 打开 Elisi 的“设置”。
2. 在“Elisi AI”区域选择“飞书 / Lark 机器人”。
3. 平台选择“飞书”。使用国际版 Lark 时选择“Lark”。
4. 填写机器人名称（可选）、App ID、App Secret 和飞书后台显示的 Verification Token。
5. 点击“连接机器人”。

Elisi 验证成功后会显示：

• 事件回调 URL。
• 一次性绑定命令。

App Secret 不会再次显示。Elisi 会加密保存它，不会将其发送给 Agent。

3. 配置事件回调

回到飞书开放平台：

1. 打开“事件与回调”或“事件订阅”。

2. 选择“将事件发送至开发者服务器”。

3. 复制 Elisi 显示的“事件回调 URL”，粘贴为请求地址。

4. Encrypt Key 必须留空。

5. 保存 URL，等待飞书提示校验成功。

6. 点击“添加事件”，添加：

   接收消息（im.message.receive_v1）
   

仅通过 URL 校验还不够，必须另外添加 im.message.receive_v1。

4. 发布并安装应用

1. 在飞书开放平台创建新版本。
2. 确认新版本包含刚添加的权限和消息事件。
3. 提交审核并发布；需要管理员审批时，先完成审批。
4. 将应用安装到企业，并确保你的飞书账号位于应用可用范围内。

每次修改权限或事件订阅后，都需要重新发布版本，否则修改不会生效。

5. 绑定 Elisi 账号

配置和发布通常会超过 15 分钟。发布完成后，建议先回到 Elisi：

1. 在机器人卡片中点击“生成新绑定码”。

2. 复制完整的一次性命令，例如：

   /elisi-bind AbCdEf123
   

3. 在 15 分钟内打开与机器人的一对一私聊并发送该命令。

4. 看到绑定成功提示后，回到 Elisi 刷新状态。

状态从“等待绑定”变为“已连接”即表示配置完成。首次绑定不能在群聊中进行。

6. 开始使用

• 私聊：直接向机器人发送文本。
• 群聊：必须由已绑定的用户 @ 机器人后发送消息。
• 解除连接：在 Elisi 的机器人卡片中点击“解除连接”。

当前版本支持文本消息，不支持 Encrypt Key 加密回调、附件、交互卡片或多人共享同一个 Elisi 账号。

常见问题

问题	处理方法
回调 URL 校验失败，未返回 challenge	确认 URL 完整、Verification Token 一致，并将 Encrypt Key 清空后重新保存。
URL 校验成功，但私聊机器人没有反应	确认已添加 im.message.receive_v1，并在添加事件和权限后重新发布、审批和安装最新版本。
Elisi 一直显示“等待绑定”	点击“生成新绑定码”，在 15 分钟内通过一对一私聊发送完整命令。旧绑定码会失效。
绑定成功但机器人不回复	检查是否已批准“以应用身份发送消息”权限，并确认该权限已包含在最新发布版本中。
群聊中机器人不响应	先通过私聊完成绑定，再由已绑定用户在群聊中 @ 机器人。
找不到机器人或无法私聊	检查应用是否已安装，以及当前账号是否在应用可用范围内。

仍无法使用时，可先在飞书开放平台的“事件推送记录”中确认是否产生了 im.message.receive_v1。没有推送记录通常表示事件、权限、发布版本或应用可用范围尚未生效。