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