Skip to main content
agentscope-extensions-channel-feishu 通过事件订阅 v2 回调机制将你的 Agent 接入飞书 / Lark。一个 Spring @RestController 接收 webhook 回调,可选地解密加密载荷,然后通过 Gateway 分发消息。

适用场景

  • Agent 需要响应飞书机器人消息(单聊和群 @提醒)。
  • 你的应用已经运行 Spring Boot(回调控制器自动注册)。

添加依赖

前置准备

  1. 飞书开发者后台创建一个自建应用
  2. 启用机器人能力。
  3. 配置事件订阅回调地址指向你的应用: https://your-host/api/channels/feishu/{channelId}/callback
  4. 记下 App IDApp Secret。可选地配置 Encrypt KeyVerification Token

快速开始

FeishuCallbackController 是一个 Spring @RestController,自动注册在 /api/channels/feishu/{channelId}/callback,并自动处理 URL 验证握手。

配置属性

加密

配置 encryptKey 后,回调 body 以 {"encrypt":"<base64>"} 形式到达。适配器自动解密(AES-256-CBC + SHA-256 密钥派生)并校验 X-Lark-Signature 头。

消息流转

入站: FeishuCallbackController → 可选解密 → URL 验证检查 → event_id 去重 → FeishuInboundMapper(当前仅支持文本消息) → 防循环 → Gateway。 出站: FeishuOutboundClient 通过 POST /open-apis/im/v1/messages 发送回复,使用 FeishuAccessTokenProvider 获取 tenant_access_token。Token 自动缓存并在约 80% TTL 时主动刷新。