📱 Feishu/Lark Binding

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.

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

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."

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).

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` .)

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

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.

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