Add Feishu channel extension support

Author: cuericlee

README.md

@@ -80,6 +80,21 @@ res = asyncio.run(agent.run("hello!"))
 print(res)
 ```
 
+## Feishu bot channel
+
+VeADK now provides `veadk.extensions.FeishuChannelExtension` for bridging a Feishu bot with a `Runner`. It maps `union_id` to `user_id`, and `thread_id` / `chat_id` to `session_id`, so VeADK memory and tracing can work directly in Feishu conversations.
+
+```python
+from veadk import Agent, Runner
+from veadk.extensions import FeishuChannelExtension
+
+agent = Agent()
+runner = Runner(agent=agent, app_name="feishu_demo")
+channel = FeishuChannelExtension(runner=runner)
+```
+
+Configure credentials with `TOOL_FEISHU_CHANNEL_APP_ID` and `TOOL_FEISHU_CHANNEL_APP_SECRET`, or in `config.yaml` under `tool.feishu_channel`.
+
 ## Command line tools
 
 VeADK provides several useful command line tools for faster deployment and optimization, such as:

config.yaml.full

@@ -56,6 +56,11 @@ tool:
     endpoint:   # `app_id`
     api_key:    # `app_secret`
     token:      # `user_token`
+  # [optional] for Feishu bot channel extension based on lark_oapi.channel
+  feishu_channel:
+    app_id:
+    app_secret:
+    transport: ws  # `ws` | `webhook`
   # [optional] for Volcengine Lake AI Service https://www.volcengine.com/product/las
   mobile_use:
     tool_id: #https://console.volcengine.com/ACEP

docs/docs/configuration.md

@@ -60,6 +60,9 @@ volcengine:
 | Lark       | `TOOL_LARK_ENDPOINT`    | Lark 应用 ID（app_id）    |
 |            | `TOOL_LARK_API_KEY`     | Lark 应用密钥（app_secret） |
 |            | `TOOL_LARK_TOKEN`       | Lark 用户 token         |
+| Feishu Channel | `TOOL_FEISHU_CHANNEL_APP_ID` | 飞书机器人应用 ID（app_id） |
+|            | `TOOL_FEISHU_CHANNEL_APP_SECRET` | 飞书机器人应用密钥（app_secret） |
+|            | `TOOL_FEISHU_CHANNEL_TRANSPORT` | Channel 传输模式，默认 `ws` |
 | LAS        | `TOOL_LAS_URL`          | LAS SSE 服务地址（含 token） |
 |            | `TOOL_LAS_DATASET_ID`   | LAS 数据集 ID            |
 | VOD        | `TOOL_VOD_GROUPS`   | 视频编辑能力组               |

docs/docs/tools/feishu-channel.md

@@ -0,0 +1,53 @@
+# 飞书 Channel 扩展
+
+`veadk.extensions.FeishuChannelExtension` 用于把飞书机器人的入站消息桥接到 VeADK `Runner`。
+
+它默认基于 `lark_oapi.channel.FeishuChannel` 的 `message` 事件工作，并按下面的规则映射会话身份：
+
+- `sender.union_id -> Runner.user_id`
+- `conversation.thread_id -> Runner.session_id`
+- 如果线程 ID 不存在，则回退到 `chat_id -> Runner.session_id`
+
+这样做的好处是，VeADK 现有的短期记忆、长期记忆、Tracing 和多租户隔离能力可以直接复用。
+
+## 安装
+
+```bash
+pip install veadk-python[extensions]
+```
+
+如果你只想安装这个能力，也可以单独安装：
+
+```bash
+pip install lark-oapi
+```
+
+## 配置
+
+环境变量：
+
+- `TOOL_FEISHU_CHANNEL_APP_ID`
+- `TOOL_FEISHU_CHANNEL_APP_SECRET`
+- `TOOL_FEISHU_CHANNEL_TRANSPORT`，默认 `ws`
+
+或在 `config.yaml` 中配置：
+
+```yaml title="config.yaml"
+tool:
+  feishu_channel:
+    app_id: cli_xxx
+    app_secret: xxx
+    transport: ws
+```
+
+## 最小示例
+
+```python
+--8<-- "examples/channel/feishu_bot.py"
+```
+
+## 说明
+
+- 默认使用飞书 `Channel` 的 WebSocket 模式，因此只要机器人已订阅消息事件，就可以直接启动连接。
+- 默认回复会使用 `reply_to=原消息 message_id`，让 VeADK 输出继续挂在当前飞书消息线程下。
+- 你可以通过 `session_id_factory` 和 `user_id_factory` 覆盖默认映射逻辑。

docs/examples/channel/feishu_bot.py

@@ -0,0 +1,32 @@
+import asyncio
+
+from veadk import Agent, Runner
+from veadk.extensions import FeishuChannelExtension
+from veadk.memory.short_term_memory import ShortTermMemory
+
+agent = Agent(
+    name="feishu_agent",
+    instruction="你是一个通过飞书机器人与用户沟通的助手。",
+)
+
+runner = Runner(
+    agent=agent,
+    app_name="veadk_feishu_demo",
+    user_id="veadk_feishu_default_user",
+    short_term_memory=ShortTermMemory(),
+)
+
+channel = FeishuChannelExtension(
+    runner=runner,
+    channel_kwargs={
+        "transport": "ws",
+    },
+)
+
+
+async def main():
+    await channel.connect()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/mkdocs.yml

@@ -55,6 +55,7 @@ nav:
       # - 最佳实践（记忆相关）: memory/best-practice-memory.md
     - 连接能力源——工具:
       - 内置工具: tools/builtin.md
+      - 飞书 Channel 扩展: tools/feishu-channel.md
       - 自定义工具: tools/function.md
       - 护栏工具: tools/guardrail.md
     - 连接数据源——知识库:

pyproject.toml

@@ -53,6 +53,7 @@ extensions = [
     "llama-index-vector-stores-redis>=0.6.1",               # For Redis database
     "llama-index-vector-stores-opensearch==0.6.1",          # For Opensearch database
     "opensearch-py==2.8.0",
+    "lark-oapi",
 ]
 database = [
     "redis>=5.0",                   # For Redis database
@@ -97,4 +98,4 @@ include-package-data = true
 exclude = [
     "veadk/integrations/ve_faas/template/*",
     "veadk/integrations/ve_faas/web_template/*"
-]
+]

tests/test_feishu_channel_extension.py

@@ -0,0 +1,118 @@
+from types import SimpleNamespace
+
+import pytest
+
+from veadk.extensions.feishu_channel import FeishuChannelExtension
+
+
+class FakeChannel:
+    def __init__(self):
+        self.handlers = {}
+        self.sent_messages = []
+
+    def on(self, event_name, handler):
+        self.handlers[event_name] = handler
+
+    async def send(self, chat_id, body, options=None):
+        self.sent_messages.append((chat_id, body, options))
+
+
+class FakeRunner:
+    def __init__(self):
+        self.calls = []
+
+    async def run(self, messages, user_id="", session_id="", **kwargs):
+        self.calls.append(
+            {
+                "messages": messages,
+                "user_id": user_id,
+                "session_id": session_id,
+            }
+        )
+        return f"echo:{messages}"
+
+
+def build_message(**overrides):
+    message = SimpleNamespace(
+        id="om_001",
+        message_id="om_001",
+        chat_id="oc_chat",
+        chat_type="p2p",
+        thread_id="",
+        reply_to_message_id="",
+        content_text="你好",
+        sender_id="ou_sender",
+        sender=SimpleNamespace(
+            union_id="on_union",
+            open_id="ou_sender",
+            user_id="u_sender",
+        ),
+        conversation=SimpleNamespace(
+            chat_id="oc_chat",
+            chat_type="p2p",
+            thread_id="",
+        ),
+        reply=SimpleNamespace(message_id=""),
+    )
+    for key, value in overrides.items():
+        setattr(message, key, value)
+    return message
+
+
+@pytest.mark.asyncio
+async def test_extension_uses_union_id_and_thread_id():
+    runner = FakeRunner()
+    channel = FakeChannel()
+    extension = FeishuChannelExtension(runner=runner, channel=channel)
+
+    message = build_message(
+        thread_id="thread_1",
+        conversation=SimpleNamespace(
+            chat_id="oc_chat",
+            chat_type="group",
+            thread_id="thread_1",
+        ),
+    )
+
+    await extension._on_message(message)
+
+    assert runner.calls == [
+        {
+            "messages": "你好",
+            "user_id": "on_union",
+            "session_id": "thread_1",
+        }
+    ]
+    assert channel.sent_messages == [
+        ("oc_chat", {"text": "echo:你好"}, {"reply_to": "om_001"})
+    ]
+
+
+@pytest.mark.asyncio
+async def test_extension_falls_back_to_chat_id_when_thread_missing():
+    runner = FakeRunner()
+    channel = FakeChannel()
+    extension = FeishuChannelExtension(runner=runner, channel=channel)
+
+    message = build_message(
+        sender=SimpleNamespace(union_id="", open_id="ou_fallback", user_id="u_sender")
+    )
+
+    await extension._on_message(message)
+
+    assert runner.calls[0]["user_id"] == "ou_fallback"
+    assert runner.calls[0]["session_id"] == "oc_chat"
+
+
+@pytest.mark.asyncio
+async def test_extension_ignores_empty_message_by_default():
+    runner = FakeRunner()
+    channel = FakeChannel()
+    extension = FeishuChannelExtension(runner=runner, channel=channel)
+
+    message = build_message(content_text="   ")
+
+    await extension._on_message(message)
+
+    assert runner.calls == []
+    assert channel.sent_messages == []

veadk/extensions/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from veadk.extensions.feishu_channel import FeishuChannelExtension
+
+__all__ = ["FeishuChannelExtension"]