mcpField
F
feishu-binding

feishu-binding

github.com/starchild-ai-agent生产力301.4k 次安装6 天前更新
代码仓库

关于 feishu-binding

用于绑定或解绑用户 Feishu 或 Lark 账号的 Skill，使 Agent 能通过对应消息应用交流。它说明了设备授权流程，包括品牌选择、确认状态轮询，以及按渠道展示二维码或链接。

主要功能

  1. 01连接 Feishu 或 Lark 账号
  2. 02检查连接状态
  3. 03轮询设备授权
  4. 04解绑账号
  5. 05按渠道展示二维码或链接

适用场景

  1. 01绑定 Feishu 账号以便与 Agent 聊天
  2. 02连接国际版 Lark 账号
  3. 03检查账号是否已连接
  4. 04先解绑再切换品牌并重新连接

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/starchild-ai-agent/official-skills --skill feishu-binding

安装后在 Claude Code 中输入/feishu-binding确认已加载。

详细介绍

📱 飞书/Lark 绑定

连接/断开用户的飞书（飞书）或 Lark 账号，使 Agent 可以通过飞书/Lark 应用聊天。

feishu 工具保持内置。此 SKILL.md 是参考文档。

另请参阅

  • config/context/references/messaging-channels.md — 消息如何在不同渠道间路由
  • skills/wechat-binding/SKILL.md — 类似的微信流程
  • skills/tg-bot-binding/SKILL.md — 类似的 Telegram 流程

品牌选择

品牌地区域名
feishu中国大陆（中国大陆）feishu.cn / accounts.feishu.cn
lark国际larksuite.com / accounts.larksuite.com

询问用户使用哪个品牌。如不明确，默认使用 feishu。中文用户几乎总是使用 feishu。

典型绑定流程

connect(brand) → user scans QR / opens link → poll(device_code) → done
  1. 启动设备授权流程： feishu(action="connect", brand="feishu") — 返回 verification_uri、device_code，以及保存到工作区的二维码图片。
  2. 向用户展示两种选项：
    • 扫描二维码： 使用结果中的 markdown_image 在消息中显示二维码图片（例如 ![Feishu QR Code](feishu_qrcode_xxx.png)）。用户使用飞书/Lark 应用扫描。
    • 直接链接： 将 verification_url 显示为可点击链接。用户在浏览器中打开链接，登录飞书/Lark 并确认。
  3. 等待用户确认。 不要自动轮询——先让用户说“完成”/“已确认”/“已确认”/“已扫描”。
  4. 轮询是否完成： feishu(action="poll", device_code=<from step 1>, brand=<same brand>)。
    • status: "done" → 绑定完成，向用户表示祝贺。
    • status: "pending" → 询问用户是否已扫描二维码或打开链接并确认。
    • status: "expired" → 设备授权流程已过期（通常为 5 分钟）。使用 connect 重新开始。
  5. 向用户确认：“Feishu/Lark 已连接！现在可以在 Feishu/Lark 上与 Agent 聊天了。”

操作

action必需参数用途
status—当前 Feishu/Lark 应用状态。用于检查是否已连接。
connectbrand（可选，默认 "feishu"）启动设备授权流程。返回验证 URL 和 device_code。
polldevice_code、brand检查用户是否已确认授权。返回状态。
disconnect—解除 Feishu/Lark 应用绑定（具有破坏性——先与用户确认）。

根据渠道显示二维码/链接

用户渠道显示方式
Web在回复中包含 file_path（二维码图片）——前端会将其直接显示。也显示链接。
Telegramsend_to_telegram(file_path=<qr_path>, message_type="photo") + 在说明文字中包含链接
WeChat仅显示链接（用户无法在 WeChat 内扫描用于 Feishu 的二维码）
Feishu（用户已经在 Feishu 上——无需绑定。告知用户已连接，或检查 status。）

与 WeChat/Telegram 的主要区别

方面Feishu/LarkWeChatTelegram
认证方式设备授权流程（URL）扫描二维码Bot token
用户操作打开 URL 并在应用中确认扫描二维码并确认通过 @BotFather 创建 Bot
凭据无（设备授权流程会处理）bot_token（来自二维码）bot_token（来自 BotFather）
品牌选择feishu / lark不适用不适用

重要规则

  • connect 后不要自动轮询。请等待用户确认已打开链接并在 Feishu/Lark 中完成确认。自动轮询会浪费 API 调用。
  • 设备授权流程约 5 分钟后过期。如果 poll 返回 expired，请告知用户并重新执行 connect。
  • disconnect 具有破坏性——调用前请先征得用户确认。该操作会停止 Feishu/Lark 网关实例。
  • 品牌很重要——feishu 和 lark 使用不同的 API 域名。使用错误的品牌会静默失败，或跳转到错误的登录页面。
  • 每位用户只能使用一个应用——用户一次只能使用一个 Feishu/Lark 应用。如果要切换品牌，必须先执行 disconnect，然后使用新品牌执行 connect。

故障排查

症状可能原因解决方法
connect 返回错误用户已有一个活跃应用先调用 status；如果应用处于活跃状态，询问用户是否要执行 disconnect 并重新绑定
poll 返回 expired用户确认所用时间过长重新执行 connect
poll 反复返回 pending用户尚未打开 URL提醒用户打开验证 URL
用户说“我找不到链接”URL 在之前的消息中重新执行 connect 以获取新的 URL

评论

支持 Markdown