feishu-binding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

📱 Feishu/Lark Binding

📱 Feishu/Lark绑定

Connect / disconnect the user's Feishu (飞书) or Lark account so the agent can chat via the Feishu/Lark app.

The

feishu

tool stays built-in. This SKILL.md is the reference doc.

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

feishu

工具为内置工具。本SKILL.md为参考文档。

另请参阅

config/context/references/messaging-channels.md

— how messages are routed across channels

```
skills/wechat-binding/SKILL.md
```
— analogous WeChat flow
```
skills/tg-bot-binding/SKILL.md
```
— analogous Telegram flow

config/context/references/messaging-channels.md

— 消息跨渠道路由方式说明

```
skills/wechat-binding/SKILL.md
```
— 类似的微信绑定流程
```
skills/tg-bot-binding/SKILL.md
```
— 类似的Telegram绑定流程

Brand selection

品牌选择

Brand	Region	Domain
`feishu`	China mainland (中国大陆)	feishu.cn / accounts.feishu.cn
`lark`	International	larksuite.com / accounts.larksuite.com

Ask the user which brand they use. Default to

feishu

if unclear. Chinese-speaking users almost always use

feishu

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

询问用户使用的品牌。若不明确，默认使用

feishu

。中文用户几乎都会使用

feishu

。

Typical binding flow

典型绑定流程

connect(brand) → user scans QR / opens link → poll(device_code) → done

Start device flow:
```
feishu(action="connect", brand="feishu")
```
— returns
```
verification_uri
```
,
```
device_code
```
, and a QR code image saved to workspace.
Show BOTH options to the user:
- QR code scan: Display the QR code image inline using the
```
markdown_image
```
  from the result (e.g.
```
![Feishu QR Code](feishu_qrcode_xxx.png)
```
  ). The user scans it with their Feishu/Lark app.
- Direct link: Show the
```
verification_url
```
  as a clickable link. The user opens it in their browser, logs in to Feishu/Lark, and confirms.
Wait for the user to confirm. Don't auto-poll — let them say "done" / "confirmed" / "已确认" / "scanned" first.
Poll for completion:
```
feishu(action="poll", device_code=<from step 1>, brand=<same brand>)
```
.
- ```
status: "done"
```
  → binding complete, congratulate the user.
- ```
status: "pending"
```
  → ask the user if they've scanned the QR code or opened the link and confirmed.
- ```
status: "expired"
```
  → the device flow expired (typically 5 minutes). Start over with
```
connect
```
  .
Confirm to user: "Feishu/Lark connected! You can now chat with your agent on Feishu/Lark."

connect(brand) → 用户扫描二维码/打开链接 → poll(device_code) → 完成

启动设备流：
```
feishu(action="connect", brand="feishu")
```
— 返回
```
verification_uri
```
、
```
device_code
```
，并将二维码图片保存至工作区。
向用户展示两种选项：
- 扫码： 使用返回结果中的
```
markdown_image
```
  （例如
```
![Feishu二维码](feishu_qrcode_xxx.png)
```
  ）在页面内显示二维码图片。用户使用Feishu/Lark应用扫码。
- 直接链接： 将
```
verification_url
```
  显示为可点击链接。用户在浏览器中打开链接，登录Feishu/Lark并确认授权。
等待用户确认。 不要自动轮询 — 等待用户发送“完成”/“已确认”/“scanned”等指令后再进行下一步。
轮询完成状态：
```
feishu(action="poll", device_code=<步骤1获取的代码>, brand=<同一品牌>)
```
。
- ```
status: "done"
```
  → 绑定完成，向用户表示祝贺。
- ```
status: "pending"
```
  → 询问用户是否已扫码或打开链接并确认授权。
- ```
status: "expired"
```
  → 设备流已过期（通常为5分钟）。重新执行
```
connect
```
  步骤。
向用户确认： "Feishu/Lark已连接！您现在可以在Feishu/Lark上与您的Agent聊天了。"

Actions

操作指令

action	required params	purpose
`status`	—	Current Feishu/Lark app state. Use to check if already connected.
`connect`	`brand` (optional, default "feishu")	Start device flow. Returns verification URL + device_code.
`poll`	`device_code` , `brand`	Check if user has confirmed authorization. Returns status.
`disconnect`	—	Unbind Feishu/Lark app (destructive — confirm with user first).

操作	必填参数	用途
`status`	—	查询当前Feishu/Lark应用状态。用于检查是否已连接。
`connect`	`brand` （可选，默认值"feishu"）	启动设备流。返回验证URL和device_code。
`poll`	`device_code` , `brand`	检查用户是否已确认授权。返回状态。
`disconnect`	—	解绑Feishu/Lark应用（此操作不可逆 — 执行前需与用户确认）。

Channel-aware QR / link display

适配不同渠道的二维码/链接展示方式

User channel	How to show
Web	Include `file_path` (QR image) in your reply — frontend renders it inline. Also show the link.
Telegram	`send_to_telegram(file_path=<qr_path>, message_type="photo")` + include the link in the caption
WeChat	Show the link only (user can't scan a QR inside WeChat for Feishu)
Feishu	(User is already on Feishu — they don't need to bind. Tell them it's already connected or check `status` .)

用户渠道	展示方式
Web	在回复中包含 `file_path` （二维码图片路径）—— 前端会将其内嵌显示。同时展示链接。
Telegram	`send_to_telegram(file_path=<二维码路径>, message_type="photo")` + 在图片说明中包含链接
微信	仅展示链接（用户无法在微信内扫描Feishu二维码）
Feishu	（用户已在Feishu上 — 无需绑定。告知用户已连接或调用 `status` 检查状态。）

Key differences from WeChat / Telegram

与微信/Telegram的主要差异

Aspect	Feishu/Lark	WeChat	Telegram
Auth method	Device flow (URL)	QR code scan	Bot token
User action	Open URL + confirm in app	Scan QR + confirm	Create bot via @BotFather
Credential	None (device flow handles it)	bot_token (from QR)	bot_token (from BotFather)
Brand choice	feishu / lark	N/A	N/A

维度	Feishu/Lark	微信	Telegram
授权方式	设备流（URL）	扫码	Bot令牌
用户操作	打开URL + 在应用内确认	扫码 + 确认	通过@BotFather创建Bot
凭证	无（设备流自动处理）	bot_token（来自扫码）	bot_token（来自@BotFather）
品牌选择	feishu / lark	无	无

Critical rules

重要规则

Don't auto-poll after
```
connect
```
. Wait for user confirmation that they've opened the link and confirmed in Feishu/Lark. Auto-polling wastes API calls.
Device flow expires in ~5 minutes. If
```
poll
```
returns
```
expired
```
, tell the user and start a new
```
connect
```
.
disconnect
is destructive — confirm with the user before calling it. It will stop the Feishu/Lark gateway instance.
Brand matters —
```
feishu
```
and
```
lark
```
use different API domains. Using the wrong brand will fail silently or redirect to the wrong login page.
One app per user — a user can only have one Feishu/Lark app at a time. If they want to switch brands, they must
```
disconnect
```
first, then
```
connect
```
with the new brand.

不要自动轮询：执行
```
connect
```
后不要自动轮询。等待用户确认已打开链接并在Feishu/Lark内完成授权。自动轮询会浪费API调用次数。
设备流过期：设备流约5分钟后过期。若
```
poll
```
返回
```
expired
```
，告知用户并重新执行
```
connect
```
。
disconnect
操作不可逆：执行前需与用户确认。此操作会停止Feishu/Lark网关实例。
品牌至关重要：
```
feishu
```
和
```
lark
```
使用不同的API域名。使用错误品牌会导致静默失败或跳转到错误的登录页面。
单用户单应用：一个用户同一时间只能绑定一个Feishu/Lark应用。若用户想要切换品牌，必须先执行
```
disconnect
```
，再使用新品牌执行
```
connect
```
。

Troubleshooting

故障排查

Symptom	Likely cause	Fix
`connect` returns error	User already has an active app	Call `status` first; if active, ask if they want to `disconnect` and rebind
`poll` returns `expired`	User took too long to confirm	Start a new `connect`
`poll` returns `pending` repeatedly	User hasn't opened the URL yet	Remind them to open the verification URL
User says "I can't find the link"	URL was in a previous message	Re-run `connect` to get a fresh URL

症状	可能原因	解决方法
`connect` 返回错误	用户已有活跃的应用	先调用 `status` 检查；若已活跃，询问用户是否要 `disconnect` 并重新绑定
`poll` 返回 `expired`	用户确认授权耗时过长	重新执行 `connect`
`poll` 反复返回 `pending`	用户尚未打开URL	提醒用户打开验证URL
用户反馈“找不到链接”	链接在之前的消息中	重新执行 `connect` 获取新的URL