用途
feishu-binding 用于连接或断开用户的飞书（中国大陆）或 Lark（国际版）账号，让智能体能够通过飞书/Lark 应用与用户对话。feishu 工具本身是内置的，本 SKILL.md 是参考文档。
相关文档包括：config/context/references/messaging-channels.md（消息在各渠道间的路由方式）、skills/wechat-binding/SKILL.md（对应的微信流程）、skills/tg-bot-binding/SKILL.md（对应的 Telegram 流程）。
品牌选择
飞书与 Lark 使用不同域名：
- feishu：中国大陆，域名为 feishu.cn / accounts.feishu.cn
- lark：国际版，域名为 larksuite.com / accounts.larksuite.com
需询问用户使用哪个品牌，不清楚时默认 feishu。中文用户几乎都使用 feishu。
典型绑定流程
connect(brand) → 用户扫码/打开链接 → poll(device_code) → 完成
- 启动设备流：feishu(action="connect", brand="feishu")，返回 verification_uri、device_code，以及保存到工作区的二维码图片。
- 向用户同时展示两种方式：
- 扫码：使用结果中的 markdown_image 内联显示二维码图片（例如 ），用户用飞书/Lark 应用扫描。
- 直接链接：将 verification_url 作为可点击链接展示，用户在浏览器中打开、登录并确认。
- 等待用户确认，不要自动轮询，先等用户说“done”“confirmed”“已确认”或“scanned”。
- 轮询完成状态：feishu(action="poll", device_code=<来自第 1 步>, brand=<同一品牌>)。
- status: "done" → 绑定完成，向用户祝贺。
- status: "pending" → 询问用户是否已扫码或打开链接并确认。
- status: "expired" → 设备流已过期（通常 5 分钟），重新执行 connect。
- 向用户确认：“Feishu/Lark connected! You can now chat with your agent on Feishu/Lark.”
操作（Actions）
- status：无必填参数，查看当前飞书/Lark 应用状态，用于检查是否已连接。
- connect：brand（可选，默认 "feishu"），启动设备流，返回验证 URL 和 device_code。
- poll：device_code、brand，检查用户是否已确认授权，返回状态。
- disconnect：无必填参数，解绑飞书/Lark 应用（破坏性操作，需先与用户确认）。
按渠道展示二维码/链接
- Web：在回复中包含 file_path（二维码图片），前端会内联渲染，同时展示链接。
- Telegram：send_to_telegram(file_path=<qr_path>, message_type="photo")，并在说明中附上链接。
- WeChat：仅展示链接（用户无法在微信内扫码绑定飞书）。
- Feishu：用户已在飞书上，无需绑定，告知已连接或检查状态。
与微信 / Telegram 的关键区别
- 认证方式：飞书/Lark 使用设备流（URL）；微信使用二维码扫描；Telegram 使用机器人 token。
- 用户操作：飞书/Lark 打开 URL 并在应用内确认；微信扫码并确认；Telegram 通过 @BotFather 创建机器人。
- 凭据：飞书/Lark 无需凭据（设备流处理）；微信为 bot_token（来自二维码）；Telegram 为 bot_token（来自 BotFather）。
- 品牌选择：飞书/Lark 可选 feishu / lark；微信和 Telegram 无。
关键规则
- connect 后不要自动轮询，等待用户确认已打开链接并在飞书/Lark 中确认，自动轮询会浪费 API 调用。
- 设备流约 5 分钟后过期。若 poll 返回 expired，告知用户并重新 connect。
- disconnect 是破坏性操作，调用前需与用户确认，它会停止飞书/Lark 网关实例。
- 品牌很重要，feishu 与 lark 使用不同 API 域名，用错品牌会静默失败或跳转到错误登录页。
- 每个用户只能有一个飞书/Lark 应用。若想切换品牌，必须先断开，再用新品牌连接。
故障排查
- connect 返回错误：用户已有活跃应用。先调用 status，若已活跃则询问是否断开并重新绑定。
- poll 返回 expired：用户确认耗时过长。重新 connect。
- poll 持续返回 pending：用户尚未打开 URL。提醒其打开验证 URL。
- 用户说“找不到链接”：URL 在之前消息中。重新执行 connect 获取新 URL。