xinyin025/LangBot

Fork 0

mirror of https://github.com/langbot-app/LangBot.git synced 2026-06-02 03:55:55 +00:00

Files

Junyan Qin e4a471af18 docs: add eba feedback event design

2026-05-07 16:25:39 +08:00

9.2 KiB

Raw Blame History

Event Based Agents 架构设计总览

1. 背景与动机

当前架构的局限性

LangBot 当前的平台适配器架构围绕消息事件单一场景设计：

事件层面：只监听 FriendMessage（私聊消息）和 GroupMessage（群消息）两种事件
API 层面：只暴露 send_message 和 reply_message 两个平台 API
处理层面：所有消息统一进入 Pipeline 流水线处理，无法为不同事件类型配置不同处理逻辑
适配器结构：每个适配器是单个 Python 文件（200-800 行），随着功能增加难以维护

这导致以下问题：

无法处理非消息事件：新成员入群、好友请求、消息撤回、消息编辑等大部分平台都支持的事件被完全忽略
平台能力未充分利用：编辑消息、撤回消息、获取群成员列表、管理群组等 API 无法使用
插件能力受限：插件只能监听消息事件、只能发送/回复消息，无法实现更丰富的交互
处理逻辑不灵活：所有消息走同一条 Pipeline，无法为入群欢迎、好友自动通过等场景配置独立的处理流程

设计目标

Event Based Agents（EBA）架构旨在将 LangBot 从"消息处理平台"升级为"事件驱动的智能代理平台"：

丰富事件：支持消息、群组、好友、Bot 状态等多种事件类型
丰富 API：支持消息编辑/撤回、群组管理、用户信息查询等通用 API，以及适配器特有 API 的透传调用
灵活编排：用户可在 WebUI 上为每个 Bot 的每种事件类型配置不同的处理器
可扩展：适配器可声明自己支持的事件和 API，平台特有能力通过标准机制暴露
向后兼容：现有插件无需修改即可在新架构下运行

2. 架构对比

现有架构

消息平台 (Telegram/Discord/...)
    │
    ▼
平台适配器 (单文件, 只处理消息)
    │ FriendMessage / GroupMessage
    ▼
RuntimeBot (注册 on_friend_message / on_group_message 回调)
    │
    ▼
MessageAggregator (消息聚合)
    │
    ▼
QueryPool → Controller → Pipeline (固定阶段链)
    │                         │
    │                         ▼
    │                    RequestRunner (local-agent / dify / n8n / ...)
    │
    ▼
adapter.reply_message() / adapter.send_message()

关键代码路径：

适配器基类：langbot-plugin-sdk/.../abstract/platform/adapter.py — AbstractMessagePlatformAdapter
事件定义：langbot-plugin-sdk/.../builtin/platform/events.py — 仅 FriendMessage / GroupMessage
Bot 管理：LangBot/src/langbot/pkg/platform/botmgr.py — RuntimeBot 只注册两个消息回调
流水线控制：LangBot/src/langbot/pkg/pipeline/controller.py — 从 QueryPool 消费并执行 Pipeline

新架构（Event Based Agents）

消息平台 (Telegram/Discord/...)
    │
    ▼
平台适配器 (独立目录, 监听所有事件, 实现丰富 API)
    │ MessageReceived / MemberJoined / FriendRequest / ...
    ▼
EventBus (统一事件总线)
    │
    ▼
EventRouter (事件路由引擎, 读取 Bot 的 event_handlers 配置)
    │
    ├─→ PipelineHandler   — 现有流水线（完整 Stage 链）
    ├─→ AgentHandler      — 直接调用 RequestRunner（轻量 AI 处理）
    ├─→ WebhookHandler    — POST 到外部服务（Dify/n8n webhook 等）
    └─→ PluginHandler     — 分发给插件 EventListener
    │
    ▼
统一平台 API
  send / reply / edit / delete / getGroupInfo / getUserInfo / callPlatformApi / ...

3. 核心概念

3.1 统一事件体系

所有平台事件统一为命名空间式的事件类型：

命名空间	事件	说明
`message.*`	`message.received`, `message.edited`, `message.deleted`, `message.reaction`	消息相关
`feedback.*`	`feedback.received`	用户对 Bot 回复的点赞、点踩、取消反馈等评价事件
`group.*`	`group.member_joined`, `group.member_left`, `group.member_banned`, `group.info_updated`	群组相关
`friend.*`	`friend.request_received`, `friend.added`, `friend.removed`	好友相关
`bot.*`	`bot.invited_to_group`, `bot.removed_from_group`, `bot.muted`, `bot.unmuted`	Bot 状态
`platform.*`	`platform.{adapter}.{action}`	适配器特有事件

详见 01-event-system.md。

3.2 统一平台 API

扩展适配器基类，提供通用 API + 透传机制：

类别	API	必需/可选
消息	`send_message`, `reply_message`, `edit_message`, `delete_message`, `forward_message`	send/reply 必需，其余可选
群组	`get_group_info`, `get_group_member_list`, `get_group_member_info`, `mute_member`, `kick_member`	全部可选
用户	`get_user_info`, `get_friend_list`	全部可选
媒体	`upload_file`, `get_file_url`	全部可选
透传	`call_platform_api(action, params)`	可选

详见 02-platform-api.md。

3.3 适配器新结构

每个适配器从单文件迁移到独立目录：

pkg/platform/adapters/
├── _base/                    # 基类和通用定义
│   ├── adapter.py
│   ├── events.py
│   ├── entities.py
│   └── api.py
├── telegram/
│   ├── __init__.py
│   ├── adapter.py            # 主适配器类
│   ├── event_converter.py    # 事件转换（多种事件类型）
│   ├── message_converter.py  # 消息链转换
│   ├── api_impl.py           # 通用 API 实现
│   ├── platform_api.py       # 平台特有 API
│   ├── types.py              # 平台特有类型
│   └── manifest.yaml
├── discord/
│   └── ...

详见 03-adapter-structure.md。

3.4 事件处理器（Event Handler）

四种处理器类型，用户在 WebUI 的 Bot 管理页面配置：

类型	说明	适用场景
pipeline	现有流水线机制，完整的多 Stage 处理链（PreProcessor → MessageProcessor → PostProcessor 等）	复杂消息处理，需要完整的预处理/后处理流程
agent	直接调用 RequestRunner（local-agent / dify / n8n / coze / dashscope / langflow / tbox），从 Pipeline 中解耦	轻量级 AI 处理、直接对接外部 LLMOps 平台处理各类事件
webhook	将事件 POST 到外部 URL，根据响应执行动作	对接自建服务、Dify/n8n 的 Webhook 触发器、自定义后端
plugin	分发给插件 EventListener 处理	插件自定义逻辑

配置存储在 Bot 表的 event_handlers JSON 字段中，通过 WebUI 编排面板管理。

详见 04-event-routing.md。

3.5 插件 SDK 改造

新事件类型全部暴露给插件
新 API 全部通过 LangBotAPIProxy 暴露
兼容层保证现有插件零修改运行

详见 05-plugin-sdk.md。

4. 关键设计决策

#	决策点	选择	理由
1	事件处理器配置粒度	每个 Bot 独立配置	Bot 是用户操作的核心单元，不同 Bot 可能对接不同业务场景
2	适配器特有 API	统一抽象 + `call_platform_api` 透传	通用 API 覆盖大部分场景，透传机制保证灵活性，避免每个适配器导出独立的类型化 API 包
3	向后兼容策略	兼容层适配	保留旧事件类型和 API 作为新系统的 alias/wrapper，现有插件无需修改
4	处理器配置存储	Bot 表新增 `event_handlers` JSON 字段	简单直接，避免新增关联表；替代现有 `use_pipeline_uuid`
5	Agent 处理器定位	从 Pipeline 中解耦 RequestRunner	不是所有事件都需要完整 Pipeline Stage 链；Agent 处理器提供轻量级 AI 处理路径，支持所有现有 Runner
6	事件命名方式	命名空间式（`message.received`）	清晰的分类层级，便于通配匹配（`message.*`），与 WebUI 配置天然对应

5. 文档索引

文档	内容
01-event-system.md	统一事件体系：事件分类、定义、生命周期
02-platform-api.md	统一平台 API：通用 API、透传 API、实体定义
03-adapter-structure.md	适配器新结构：目录布局、基类、注册机制
04-event-routing.md	事件路由与编排：路由引擎、处理器类型、WebUI 数据模型
05-plugin-sdk.md	插件 SDK 改造：新事件/API、兼容层
06-migration-plan.md	分阶段迁移计划

6. 涉及的代码仓库

仓库	改动范围
langbot-plugin-sdk	事件定义、实体模型、API 接口、适配器基类、通信协议扩展
LangBot（后端）	适配器实现、事件路由引擎、Bot 实体扩展、数据库迁移、RequestRunner 解耦
LangBot（前端）	Bot 事件处理器编排面板
langbot-wiki	新架构文档、插件开发指南更新、适配器开发指南
langbot-plugin-demo	示例更新（使用新事件和 API）

9.2 KiB Raw Blame History Unescape Escape