feat(gateway): add Feishu/Lark platform support (#3817)

Adds Feishu (ByteDance's enterprise messaging platform) as a gateway
platform adapter with full feature parity: WebSocket + webhook transports,
message batching, dedup, rate limiting, rich post/card content parsing,
media handling (images/audio/files/video), group @mention gating,
reaction routing, and interactive card button support.

Cherry-picked from PR #1793 by penwyp with:
- Moved to current main (PR was 458 commits behind)
- Fixed _send_with_retry shadowing BasePlatformAdapter method (renamed to
  _feishu_send_with_retry to avoid signature mismatch crash)
- Fixed import structure: aiohttp/websockets imported independently of
  lark_oapi so they remain available when SDK is missing
- Fixed get_hermes_home import (hermes_constants, not hermes_cli.config)
- Added skip decorators for tests requiring lark_oapi SDK
- All 16 integration points added surgically to current main

New dependency: lark-oapi>=1.5.3,<2 (optional, pip install hermes-agent[feishu])

Fixes #1788

Co-authored-by: penwyp <penwyp@users.noreply.github.com>

website/docs/user-guide/messaging/feishu.md

@@ -0,0 +1,129 @@
+---
+sidebar_position: 11
+title: "Feishu / Lark"
+description: "Set up Hermes Agent as a Feishu or Lark bot"
+---
+
+# Feishu / Lark Setup
+
+Hermes Agent integrates with Feishu and Lark as a full-featured bot. Once connected, you can chat with the agent in direct messages or group chats, receive cron job results in a home chat, and send text, images, audio, and file attachments through the normal gateway flow.
+
+The integration supports both connection modes:
+
+- `websocket` — recommended; Hermes opens the outbound connection and you do not need a public webhook endpoint
+- `webhook` — useful when you want Feishu/Lark to push events into your gateway over HTTP
+
+## How Hermes Behaves
+
+| Context | Behavior |
+|---------|----------|
+| Direct messages | Hermes responds to every message. |
+| Group chats | Hermes responds when the bot is addressed in the chat. |
+| Shared group chats | By default, session history is isolated per user inside a shared chat. |
+
+This shared-chat behavior is controlled by `config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+Set it to `false` only if you explicitly want one shared conversation per chat.
+
+## Step 1: Create a Feishu / Lark App
+
+1. Open the Feishu or Lark developer console:
+   - Feishu: <https://open.feishu.cn/>
+   - Lark: <https://open.larksuite.com/>
+2. Create a new app.
+3. In **Credentials & Basic Info**, copy the **App ID** and **App Secret**.
+4. Enable the **Bot** capability for the app.
+
+:::warning
+Keep the App Secret private. Anyone with it can impersonate your app.
+:::
+
+## Step 2: Choose a Connection Mode
+
+### Recommended: WebSocket mode
+
+Use WebSocket mode when Hermes runs on your laptop, workstation, or a private server. No public URL is required.
+
+```bash
+FEISHU_CONNECTION_MODE=websocket
+```
+
+### Optional: Webhook mode
+
+Use webhook mode only when you already run Hermes behind a reachable HTTP endpoint.
+
+```bash
+FEISHU_CONNECTION_MODE=webhook
+```
+
+In webhook mode, Hermes serves a Feishu endpoint at:
+
+```text
+/feishu/webhook
+```
+
+## Step 3: Configure Hermes
+
+### Option A: Interactive Setup
+
+```bash
+hermes gateway setup
+```
+
+Select **Feishu / Lark** and fill in the prompts.
+
+### Option B: Manual Configuration
+
+Add the following to `~/.hermes/.env`:
+
+```bash
+FEISHU_APP_ID=cli_xxx
+FEISHU_APP_SECRET=secret_xxx
+FEISHU_DOMAIN=feishu
+FEISHU_CONNECTION_MODE=websocket
+
+# Optional but strongly recommended
+FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
+FEISHU_HOME_CHANNEL=oc_xxx
+```
+
+`FEISHU_DOMAIN` accepts:
+
+- `feishu` for Feishu China
+- `lark` for Lark international
+
+## Step 4: Start the Gateway
+
+```bash
+hermes gateway
+```
+
+Then message the bot from Feishu/Lark to confirm that the connection is live.
+
+## Home Chat
+
+Use `/set-home` in a Feishu/Lark chat to mark it as the home channel for cron job results and cross-platform notifications.
+
+You can also preconfigure it:
+
+```bash
+FEISHU_HOME_CHANNEL=oc_xxx
+```
+
+## Security
+
+For production use, set an allowlist:
+
+```bash
+FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
+```
+
+If you leave the allowlist empty, anyone who can reach the bot may be able to use it.
+
+## Toolset
+
+Feishu / Lark uses the `hermes-feishu` platform preset, which includes the same core tools as Telegram and other gateway-based messaging platforms.

website/docs/user-guide/messaging/index.md

@@ -6,7 +6,7 @@ description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal,
 
 # Messaging Gateway
 
-Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
+Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
 
 For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/docs/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/docs/guides/use-voice-mode-with-hermes).
 
@@ -27,6 +27,7 @@ flowchart TB
             mm[Mattermost]
             mx[Matrix]
             dt[DingTalk]
+    fs[Feishu/Lark]
             api["API Server<br/>(OpenAI-compatible)"]
             wh[Webhooks]
         end
@@ -328,6 +329,7 @@ Each platform has its own toolset:
 | Mattermost | `hermes-mattermost` | Full tools including terminal |
 | Matrix | `hermes-matrix` | Full tools including terminal |
 | DingTalk | `hermes-dingtalk` | Full tools including terminal |
+| Feishu/Lark | `hermes-feishu` | Full tools including terminal |
 | API Server | `hermes` (default) | Full tools including terminal |
 | Webhooks | `hermes-webhook` | Full tools including terminal |
 
@@ -344,5 +346,6 @@ Each platform has its own toolset:
 - [Mattermost Setup](mattermost.md)
 - [Matrix Setup](matrix.md)
 - [DingTalk Setup](dingtalk.md)
+- [Feishu/Lark Setup](feishu.md)
 - [Open WebUI + API Server](open-webui.md)
 - [Webhooks](webhooks.md)