feishu-binding

📱 Feishu/Lark 連携

ユーザーの Feishu (飞书) または Lark アカウントを接続/切断し、エージェントが Feishu/Lark アプリ経由でチャットできるようにします。

feishu ツールは組み込みのままです。この SKILL.md はリファレンスドキュメントです。

関連項目

• config/context/references/messaging-channels.md — チャネル間でメッセージがどのようにルーティングされるか
• skills/wechat-binding/SKILL.md — 類似の WeChat フロー
• 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、およびワークスペースに保存された QR コード画像を返します。
2. ユーザーに両方の選択肢を提示する:
   • QR コードのスキャン: 結果の markdown_image を使用して QR コード画像をインラインで表示します (例: ![Feishu QR Code](feishu_qrcode_xxx.png))。ユーザーは Feishu/Lark アプリでこれをスキャンします。
   • 直接リンク: verification_url をクリック可能なリンクとして表示します。ユーザーはブラウザでこれを開き、Feishu/Lark にログインして確認します。
3. ユーザーが確認するのを待ちます。 自動ポーリングはしないでください — まずユーザーに「done」/「confirmed」/「已确认」/「scanned」と言ってもらいましょう。
4. 完了をポーリング: feishu(action="poll", device_code=<from step 1>, brand=<same brand>)。
   • status: "done" → 連携完了です。ユーザーにお祝いを伝えましょう。
   • status: "pending" → ユーザーが QR コードをスキャンしたか、リンクを開いて確認したかを尋ねてください。
   • status: "expired" → デバイスフローが期限切れになりました (通常 5 分)。connect でやり直してください。
5. ユーザーに確認: 「Feishu/Lark に接続しました! Feishu/Lark 上でエージェントとチャットできるようになりました。」

---

アクション

action	必須パラメータ	目的
status	—	現在の Feishu/Lark アプリの状態。すでに接続済みかどうかの確認に使用します。
connect	brand (任意、デフォルト "feishu")	デバイスフローを開始します。検証 URL + device_code を返します。
poll	device_code, brand	ユーザーが認可を確認したかどうかをチェックします。ステータスを返します。
disconnect	—	Feishu/Lark アプリのバインドを解除します (破壊的 — まずユーザーに確認してください)。

---

チャネルに応じた QR / リンクの表示

ユーザーチャネル	表示方法
Web	返信に file_path (QR 画像) を含めます — フロントエンドがインラインでレンダリングします。リンクも表示します。
Telegram	send_to_telegram(file_path=<qr_path>, message_type="photo") + キャプションにリンクを含めます
WeChat	リンクのみを表示します (ユーザーは WeChat 内から Feishu 用の QR をスキャンできません)
Feishu	(ユーザーはすでに Feishu 上にいます — バインドする必要はありません。すでに接続済みであることを伝えるか、status を確認してください。)

---

WeChat / Telegram との主な違い

項目	Feishu/Lark	WeChat	Telegram
認証方式	デバイスフロー (URL)	QR コードのスキャン	Bot トークン
ユーザーの操作	URL を開いてアプリで確認	QR をスキャンして確認	@BotFather でボットを作成
認証情報	なし (デバイスフローが処理)	bot_token (QR から)	bot_token (BotFather から)
ブランドの選択	feishu / lark	N/A	N/A

---

重要なルール

• connect の後に自動ポーリングしないでください。 ユーザーがリンクを開き、Feishu/Lark で確認したという確認を待ちます。自動ポーリングは API 呼び出しを無駄にします。
• デバイスフローは約 5 分で期限切れになります。 poll が expired を返した場合は、ユーザーに伝えて新しい connect を開始してください。
• disconnect は破壊的です — 呼び出す前にユーザーに確認してください。Feishu/Lark ゲートウェイインスタンスが停止します。
• ブランドが重要です — feishu と lark は異なる API ドメインを使用します。誤ったブランドを使用すると、サイレントに失敗するか、誤ったログインページにリダイレクトされます。
• 1 ユーザーにつき 1 アプリ — ユーザーは同時に 1 つの Feishu/Lark アプリしか持てません。ブランドを切り替えたい場合は、まず disconnect してから、新しいブランドで connect する必要があります。

---

トラブルシューティング

症状	考えられる原因	対処法
connect がエラーを返す	ユーザーがすでにアクティブなアプリを持っている	まず status を呼び出します。アクティブな場合は、disconnect して再バインドしたいか確認します
poll が expired を返す	ユーザーの確認に時間がかかりすぎた	新しい connect を開始します
poll が繰り返し pending を返す	ユーザーがまだ URL を開いていない	確認 URL を開くよう促します
ユーザーが「リンクが見つからない」と言う	URL が以前のメッセージにあった	connect を再実行して新しい URL を取得します