feishu skill

feishu-binding/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: feishu-binding
+version: 1.0.0
+description: |
+  Feishu/Lark binding: device flow authorization, connect, disconnect, status check.
+
+  Use when setting up or managing Feishu/Lark connection (e.g. connect Feishu, connect Lark, bind 飞书, check Feishu status, disconnect Lark).
+author: starchild
+tags: [feishu, lark, binding, connection, device-flow]
+
+metadata:
+  starchild:
+    emoji: "💬"
+    skillKey: feishu-binding
+
+user-invocable: true
+disable-model-invocation: false
+
+---
+
+# 📱 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.
+
+## See also
+- `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
+
+---
+
+## 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`.
+
+---
+
+## Typical binding flow
+
+```
+connect(brand) → user scans QR / opens link → poll(device_code) → done
+```
+
+1. **Start device flow:** `feishu(action="connect", brand="feishu")` — returns `verification_uri`, `device_code`, and a QR code image saved to workspace.
+2. **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.
+3. **Wait for the user to confirm.** Don't auto-poll — let them say "done" / "confirmed" / "已确认" / "scanned" first.
+4. **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`.
+5. **Confirm to user:** "Feishu/Lark connected! You can now chat with your agent on Feishu/Lark."
+
+---
+
+## 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). |
+
+---
+
+## 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`.) |
+
+---
+
+## Key differences from WeChat / 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 |
+
+---
+
+## 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.
+
+---
+
+## 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 |

skills.json

@@ -217,6 +217,12 @@
       "version": "1.2.1",
       "description": "Ethena staking: stake USDe for sUSDe yield, unstake with cooldown, view rates.\n\nUse when farming stablecoin yield via Ethena (e.g. stake 1000 USDe, check sUSDe APY, unstake my position, current cooldown)."
     },
+    {
+      "name": "feishu-binding",
+      "path": "feishu-binding/SKILL.md",
+      "version": "1.0.0",
+      "description": "Feishu/Lark binding: device flow authorization, connect, disconnect, status check.\n\nUse when setting up or managing Feishu/Lark connection (e.g. connect Feishu, connect Lark, bind 飞书, check Feishu status, disconnect Lark)."
+    },
     {
       "name": "futu",
       "path": "futu/SKILL.md",