feat(officialaccount): add eba adapter

- TelegramAdapter inherits AbstractPlatformAdapter with all capabilities
- TelegramEventConverter handles all Update types: message, edited_message,
  chat_member, my_chat_member, callback_query, message_reaction
- TelegramAPIMixin implements: edit_message, delete_message, forward_message,
  get_group_info, get_group_member_list/info, get_user_info, get_file_url,
  mute/unmute/kick_member, leave_group
- PLATFORM_API_MAP for call_platform_api: pin/unpin message, set chat title/desc,
  get admins, send chat action, create invite link, answer callback query
- Full backward compat: legacy FriendMessage/GroupMessage listeners still work
- Preserves all existing functionality: stream output, markdown card, forum topics
- Old sources/telegram.py untouched for gradual migration

docs/event-based-agents/00-overview.md

@@ -0,0 +1,197 @@
+# Event Based Agents 架构设计总览
+
+## 1. 背景与动机
+
+### 当前架构的局限性
+
+LangBot 当前的平台适配器架构围绕**消息事件**单一场景设计：
+
+- **事件层面**：只监听 `FriendMessage`（私聊消息）和 `GroupMessage`（群消息）两种事件
+- **API 层面**：只暴露 `send_message` 和 `reply_message` 两个平台 API
+- **处理层面**：所有消息统一进入 Pipeline 流水线处理，无法为不同事件类型配置不同处理逻辑
+- **适配器结构**：每个适配器是单个 Python 文件（200-800 行），随着功能增加难以维护
+
+这导致以下问题：
+
+1. **无法处理非消息事件**：新成员入群、好友请求、消息撤回、消息编辑等大部分平台都支持的事件被完全忽略
+2. **平台能力未充分利用**：编辑消息、撤回消息、获取群成员列表、管理群组等 API 无法使用
+3. **插件能力受限**：插件只能监听消息事件、只能发送/回复消息，无法实现更丰富的交互
+4. **处理逻辑不灵活**：所有消息走同一条 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](./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](./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](./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](./04-event-routing.md)。
+
+### 3.5 插件 SDK 改造
+
+- 新事件类型全部暴露给插件
+- 新 API 全部通过 `LangBotAPIProxy` 暴露
+- 兼容层保证现有插件零修改运行
+
+详见 [05-plugin-sdk.md](./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](./01-event-system.md) | 统一事件体系：事件分类、定义、生命周期 |
+| [02-platform-api.md](./02-platform-api.md) | 统一平台 API：通用 API、透传 API、实体定义 |
+| [03-adapter-structure.md](./03-adapter-structure.md) | 适配器新结构：目录布局、基类、注册机制 |
+| [04-event-routing.md](./04-event-routing.md) | 事件路由与编排：路由引擎、处理器类型、WebUI 数据模型 |
+| [05-plugin-sdk.md](./05-plugin-sdk.md) | 插件 SDK 改造：新事件/API、兼容层 |
+| [06-migration-plan.md](./06-migration-plan.md) | 分阶段迁移计划 |
+
+## 6. 涉及的代码仓库
+
+| 仓库 | 改动范围 |
+|------|----------|
+| **langbot-plugin-sdk** | 事件定义、实体模型、API 接口、适配器基类、通信协议扩展 |
+| **LangBot**（后端） | 适配器实现、事件路由引擎、Bot 实体扩展、数据库迁移、RequestRunner 解耦 |
+| **LangBot**（前端） | Bot 事件处理器编排面板 |
+| **langbot-wiki** | 新架构文档、插件开发指南更新、适配器开发指南 |
+| **langbot-plugin-demo** | 示例更新（使用新事件和 API） |

docs/event-based-agents/01-event-system.md

@@ -0,0 +1,561 @@
+# 统一事件体系
+
+## 1. 设计原则
+
+- **命名空间分类**：事件类型采用 `{namespace}.{action}` 格式，如 `message.received`
+- **通用优先**：大部分平台都支持的事件抽象为通用事件，定义统一的字段格式
+- **平台特有事件标准化**：各适配器的独有事件通过 `PlatformSpecificEvent` 承载，保留原始数据
+- **向后兼容**：现有 `FriendMessage` / `GroupMessage` 通过兼容层映射到新的 `message.received` 事件
+
+## 2. 事件基类层次
+
+```
+Event (事件基类)
+├── MessageEvent (消息相关事件)
+│   ├── MessageReceivedEvent       # message.received
+│   ├── MessageEditedEvent         # message.edited
+│   ├── MessageDeletedEvent        # message.deleted
+│   └── MessageReactionEvent       # message.reaction
+├── FeedbackEvent (用户反馈事件)
+│   └── FeedbackReceivedEvent      # feedback.received
+├── GroupEvent (群组相关事件)
+│   ├── MemberJoinedEvent          # group.member_joined
+│   ├── MemberLeftEvent            # group.member_left
+│   ├── MemberBannedEvent          # group.member_banned
+│   ├── MemberUnbannedEvent        # group.member_unbanned
+│   └── GroupInfoUpdatedEvent      # group.info_updated
+├── FriendEvent (好友相关事件)
+│   ├── FriendRequestReceivedEvent # friend.request_received
+│   ├── FriendAddedEvent           # friend.added
+│   └── FriendRemovedEvent         # friend.removed
+├── BotEvent (Bot 状态事件)
+│   ├── BotInvitedToGroupEvent     # bot.invited_to_group
+│   ├── BotRemovedFromGroupEvent   # bot.removed_from_group
+│   ├── BotMutedEvent              # bot.muted
+│   └── BotUnmutedEvent            # bot.unmuted
+└── PlatformSpecificEvent          # platform.{adapter}.{action}
+```
+
+## 3. 通用事件定义
+
+### 3.1 事件基类
+
+```python
+class Event(pydantic.BaseModel):
+    """事件基类"""
+
+    type: str
+    """事件类型标识，如 'message.received'"""
+
+    timestamp: float
+    """事件发生的时间戳"""
+
+    bot_uuid: str
+    """接收到此事件的 Bot UUID"""
+
+    adapter_name: str
+    """产生此事件的适配器名称"""
+
+    source_platform_object: typing.Optional[typing.Any] = None
+    """原始平台事件对象，供适配器内部使用"""
+```
+
+### 3.2 消息事件
+
+#### MessageReceivedEvent (`message.received`)
+
+收到新消息。这是最核心的事件，替代现有的 `FriendMessage` / `GroupMessage`。
+
+```python
+class MessageReceivedEvent(Event):
+    """收到新消息"""
+
+    type: str = "message.received"
+
+    message_id: typing.Union[int, str]
+    """消息 ID"""
+
+    message_chain: MessageChain
+    """消息内容"""
+
+    sender: User
+    """发送者"""
+
+    chat_type: ChatType  # "private" | "group"
+    """会话类型"""
+
+    chat_id: typing.Union[int, str]
+    """会话 ID（私聊为对方用户 ID，群聊为群 ID）"""
+
+    group: typing.Optional[Group] = None
+    """群信息（仅群聊时存在）"""
+```
+
+与现有类型的映射关系：
+- `chat_type == "private"` → 等价于现有 `FriendMessage`
+- `chat_type == "group"` → 等价于现有 `GroupMessage`
+
+`ChatType` 枚举：
+
+```python
+class ChatType(str, Enum):
+    PRIVATE = "private"
+    GROUP = "group"
+```
+
+#### MessageEditedEvent (`message.edited`)
+
+消息被编辑。
+
+```python
+class MessageEditedEvent(Event):
+    """消息被编辑"""
+
+    type: str = "message.edited"
+
+    message_id: typing.Union[int, str]
+    """被编辑的消息 ID"""
+
+    new_content: MessageChain
+    """编辑后的新内容"""
+
+    editor: User
+    """编辑者"""
+
+    chat_type: ChatType
+    chat_id: typing.Union[int, str]
+    group: typing.Optional[Group] = None
+```
+
+#### MessageDeletedEvent (`message.deleted`)
+
+消息被删除/撤回。
+
+```python
+class MessageDeletedEvent(Event):
+    """消息被删除/撤回"""
+
+    type: str = "message.deleted"
+
+    message_id: typing.Union[int, str]
+    """被删除的消息 ID"""
+
+    operator: typing.Optional[User] = None
+    """操作者（可能是发送者自己撤回，也可能是管理员删除）"""
+
+    chat_type: ChatType
+    chat_id: typing.Union[int, str]
+    group: typing.Optional[Group] = None
+```
+
+#### MessageReactionEvent (`message.reaction`)
+
+消息收到表情回应。
+
+```python
+class MessageReactionEvent(Event):
+    """消息收到表情回应"""
+
+    type: str = "message.reaction"
+
+    message_id: typing.Union[int, str]
+    """被回应的消息 ID"""
+
+    user: User
+    """回应者"""
+
+    reaction: str
+    """回应的表情标识（emoji 或平台特定表情 ID）"""
+
+    is_add: bool
+    """True 为添加回应，False 为移除回应"""
+
+    chat_type: ChatType
+    chat_id: typing.Union[int, str]
+    group: typing.Optional[Group] = None
+```
+
+### 3.3 用户反馈事件
+
+#### FeedbackReceivedEvent (`feedback.received`)
+
+用户对 Bot 回复提交反馈。该事件用于承载平台提供的点赞、点踩、取消反馈以及点踩原因等评价信息；典型来源包括企业微信 AI Bot 的 `feedback_event`、飞书卡片按钮回调、Web Embed 的反馈入口等。
+
+```python
+class FeedbackReceivedEvent(Event):
+    """收到用户反馈"""
+
+    type: str = "feedback.received"
+
+    feedback_id: str
+    """平台侧反馈 ID，用于幂等记录或取消反馈"""
+
+    feedback_type: int
+    """1 = like, 2 = dislike, 3 = cancel/remove feedback"""
+
+    feedback_content: typing.Optional[str] = None
+    """用户填写的自由文本反馈"""
+
+    inaccurate_reasons: typing.Optional[list[str]] = None
+    """点踩时平台提供的预设不准确原因"""
+
+    user_id: typing.Optional[str] = None
+    """提交反馈的用户 ID"""
+
+    session_id: typing.Optional[str] = None
+    """会话 ID，例如 person_xxx 或 group_xxx"""
+
+    message_id: typing.Optional[str] = None
+    """被评价的 Bot 回复消息 ID"""
+
+    stream_id: typing.Optional[str] = None
+    """流式回复 ID，用于关联 streaming response"""
+```
+
+设计约定：
+
+- `feedback_id` 是幂等键；同一个 `feedback_id` 的后续事件应更新已有记录。
+- `feedback_type == 3` 表示用户取消/移除反馈，处理器可删除对应记录或标记为取消。
+- 如果平台只能给出原始回调 payload，差异字段保留在 `source_platform_object` 或 `PlatformSpecificEvent.data` 中；通用字段仍优先映射到 `FeedbackReceivedEvent`。
+- 该事件保留向后兼容映射：EBA 事件可转换为旧的 `FeedbackEvent`，字段语义保持一致。
+
+### 3.4 群组事件
+
+#### MemberJoinedEvent (`group.member_joined`)
+
+新成员加入群组。
+
+```python
+class MemberJoinedEvent(Event):
+    """新成员加入群组"""
+
+    type: str = "group.member_joined"
+
+    group: Group
+    """群组"""
+
+    member: User
+    """加入的成员"""
+
+    inviter: typing.Optional[User] = None
+    """邀请者（如有）"""
+
+    join_type: typing.Optional[str] = None
+    """加入方式：'invite' / 'request' / 'direct' / None"""
+```
+
+#### MemberLeftEvent (`group.member_left`)
+
+成员离开群组。
+
+```python
+class MemberLeftEvent(Event):
+    """成员离开群组"""
+
+    type: str = "group.member_left"
+
+    group: Group
+    member: User
+
+    is_kicked: bool = False
+    """是否被踢出"""
+
+    operator: typing.Optional[User] = None
+    """操作者（踢出时为管理员）"""
+```
+
+#### MemberBannedEvent (`group.member_banned`)
+
+成员被禁言。
+
+```python
+class MemberBannedEvent(Event):
+    """成员被禁言"""
+
+    type: str = "group.member_banned"
+
+    group: Group
+    member: User
+    operator: typing.Optional[User] = None
+    duration: typing.Optional[int] = None
+    """禁言时长（秒），None 表示永久"""
+```
+
+#### MemberUnbannedEvent (`group.member_unbanned`)
+
+成员被解除禁言。
+
+```python
+class MemberUnbannedEvent(Event):
+    """成员被解除禁言"""
+
+    type: str = "group.member_unbanned"
+
+    group: Group
+    member: User
+    operator: typing.Optional[User] = None
+```
+
+#### GroupInfoUpdatedEvent (`group.info_updated`)
+
+群组信息被修改。
+
+```python
+class GroupInfoUpdatedEvent(Event):
+    """群组信息被修改"""
+
+    type: str = "group.info_updated"
+
+    group: Group
+    """更新后的群组信息"""
+
+    operator: typing.Optional[User] = None
+    """操作者"""
+
+    changed_fields: list[str] = []
+    """发生变更的字段名列表，如 ['name', 'description']"""
+```
+
+### 3.5 好友事件
+
+#### FriendRequestReceivedEvent (`friend.request_received`)
+
+收到好友请求。
+
+```python
+class FriendRequestReceivedEvent(Event):
+    """收到好友请求"""
+
+    type: str = "friend.request_received"
+
+    request_id: typing.Union[int, str]
+    """请求 ID，用于后续 approve/reject 操作"""
+
+    user: User
+    """请求者"""
+
+    message: typing.Optional[str] = None
+    """验证消息"""
+```
+
+#### FriendAddedEvent (`friend.added`)
+
+成功添加好友。
+
+```python
+class FriendAddedEvent(Event):
+    """成功添加好友"""
+
+    type: str = "friend.added"
+
+    user: User
+    """新好友"""
+```
+
+#### FriendRemovedEvent (`friend.removed`)
+
+好友被移除。
+
+```python
+class FriendRemovedEvent(Event):
+    """好友被移除"""
+
+    type: str = "friend.removed"
+
+    user: User
+    """被移除的好友"""
+```
+
+### 3.6 Bot 状态事件
+
+#### BotInvitedToGroupEvent (`bot.invited_to_group`)
+
+Bot 被邀请加入群组。
+
+```python
+class BotInvitedToGroupEvent(Event):
+    """Bot 被邀请加入群组"""
+
+    type: str = "bot.invited_to_group"
+
+    group: Group
+    inviter: typing.Optional[User] = None
+
+    request_id: typing.Optional[typing.Union[int, str]] = None
+    """邀请请求 ID，某些平台需要 Bot 确认才加入"""
+```
+
+#### BotRemovedFromGroupEvent (`bot.removed_from_group`)
+
+Bot 被移出群组。
+
+```python
+class BotRemovedFromGroupEvent(Event):
+    """Bot 被移出群组"""
+
+    type: str = "bot.removed_from_group"
+
+    group: Group
+    operator: typing.Optional[User] = None
+```
+
+#### BotMutedEvent / BotUnmutedEvent (`bot.muted` / `bot.unmuted`)
+
+Bot 被禁言/解除禁言。
+
+```python
+class BotMutedEvent(Event):
+    """Bot 被禁言"""
+
+    type: str = "bot.muted"
+
+    group: Group
+    operator: typing.Optional[User] = None
+    duration: typing.Optional[int] = None
+
+
+class BotUnmutedEvent(Event):
+    """Bot 被解除禁言"""
+
+    type: str = "bot.unmuted"
+
+    group: Group
+    operator: typing.Optional[User] = None
+```
+
+### 3.7 平台特有事件
+
+对于无法抽象为通用事件的平台特有事件，使用统一的 `PlatformSpecificEvent` 承载：
+
+```python
+class PlatformSpecificEvent(Event):
+    """平台特有事件
+
+    适配器无法映射到通用事件类型时，使用此类型承载。
+    插件可以通过 adapter_name + action 来识别和处理。
+    """
+
+    type: str = "platform.specific"
+
+    action: str
+    """平台特有的事件动作标识，如 'channel_created', 'pin_message'"""
+
+    data: dict = {}
+    """事件数据，结构由具体适配器定义"""
+```
+
+事件类型字符串格式为 `platform.{adapter_name}.{action}`，例如：
+- `platform.telegram.chat_member_updated` — Telegram 的群成员信息更新
+- `platform.discord.channel_created` — Discord 的频道创建
+- `platform.discord.voice_state_update` — Discord 的语音状态变更
+- `platform.slack.app_home_opened` — Slack 的 App Home 打开
+
+## 4. 各平台事件支持矩阵
+
+下表标注各通用事件在主要平台上的支持情况：
+
+| 事件 | Telegram | Discord | OneBot(QQ) | 飞书 | 钉钉 | Slack | 微信 | LINE | KOOK |
+|------|----------|---------|-----------|------|------|-------|------|------|------|
+| `message.received` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `message.edited` | Y | Y | N | Y | N | Y | N | N | Y |
+| `message.deleted` | Y | Y | Y | Y | N | Y | Y | N | Y |
+| `message.reaction` | Y | Y | Y | Y | Y | Y | N | N | Y |
+| `feedback.received` | N | N | N | Y | N | N | Y | N | N |
+| `group.member_joined` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `group.member_left` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `group.member_banned` | Y | Y | Y | N | N | N | N | N | N |
+| `group.info_updated` | Y | Y | Y | Y | Y | Y | N | N | Y |
+| `friend.request_received` | N | Y | Y | N | N | N | Y | Y | Y |
+| `friend.added` | N | Y | Y | N | N | N | Y | Y | N |
+| `bot.invited_to_group` | Y | Y | Y | Y | Y | Y | Y | N | Y |
+| `bot.removed_from_group` | Y | Y | Y | Y | N | N | Y | N | Y |
+| `bot.muted` | Y | N | Y | N | N | N | N | N | N |
+| `bot.unmuted` | Y | N | Y | N | N | N | N | N | N |
+| `platform.specific` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+
+> 注：此表为初步评估，具体以各平台 SDK/API 文档为准，实施时逐个确认。
+
+## 5. 事件生命周期
+
+```
+1. 平台 SDK 回调触发
+      │
+2. 适配器 EventConverter.target2yiri(raw_event)
+      │  将平台原生事件转换为统一 Event 对象
+      │  无法映射的事件 → PlatformSpecificEvent
+      │
+3. 适配器回调注册的 listener(event, adapter)
+      │
+4. RuntimeBot 接收事件
+      │
+5. EventBus 分发
+      │
+6. EventRouter 查询 Bot 的 event_handlers 配置
+      │  匹配事件类型 → 找到对应的 Handler
+      │  支持通配符：'message.*' 匹配所有消息事件
+      │  未匹配到 → 走默认 Handler（plugin，保持向后兼容）
+      │
+7. Handler 处理事件
+      │  PipelineHandler → 进入 Pipeline 流水线
+      │  AgentHandler    → 调用 RequestRunner
+      │  WebhookHandler  → POST 到外部 URL
+      │  PluginHandler   → 分发给插件 EventListener
+      │
+8. Handler 执行完毕，可能通过 API 执行响应动作
+      （发消息、编辑消息、踢人、同意好友请求等）
+```
+
+## 6. 与现有事件类型的兼容映射
+
+为保证现有插件不受影响，建立以下映射关系：
+
+| 新事件 | 条件 | 旧事件 |
+|--------|------|--------|
+| `MessageReceivedEvent` (chat_type=private) | — | `FriendMessage` |
+| `MessageReceivedEvent` (chat_type=group) | — | `GroupMessage` |
+
+在插件 SDK 层面：
+
+| 新事件 | 旧插件事件 |
+|--------|-----------|
+| `MessageReceivedEvent` (chat_type=private, 非命令) | `PersonNormalMessageReceived` |
+| `MessageReceivedEvent` (chat_type=group, 非命令) | `GroupNormalMessageReceived` |
+| `MessageReceivedEvent` (chat_type=private, 命令) | `PersonCommandSent` |
+| `MessageReceivedEvent` (chat_type=group, 命令) | `GroupCommandSent` |
+| `MessageReceivedEvent` (处理完毕后) | `NormalMessageResponded` |
+
+兼容层在事件分发给插件 EventListener 时自动生成旧格式事件，确保监听旧事件类型的插件仍能正常工作。
+
+## 7. 事件类型注册表
+
+适配器在 manifest.yaml 中声明自己支持的事件类型：
+
+```yaml
+kind: MessagePlatformAdapter
+metadata:
+  name: telegram
+spec:
+  supported_events:
+    - message.received
+    - message.edited
+    - message.deleted
+    - message.reaction
+    - feedback.received
+    - group.member_joined
+    - group.member_left
+    - group.member_banned
+    - group.info_updated
+    - bot.invited_to_group
+    - bot.removed_from_group
+    - bot.muted
+    - bot.unmuted
+    - platform.specific
+  platform_specific_events:
+    - chat_member_updated
+    - chat_join_request
+```
+
+这份声明用于：
+1. WebUI 在配置事件处理器时，只显示当前 Bot 的适配器支持的事件类型
+2. EventRouter 在路由时校验事件类型有效性
+3. 文档自动生成

docs/event-based-agents/02-platform-api.md

@@ -0,0 +1,546 @@
+# 统一平台 API 与实体定义
+
+## 1. 设计原则
+
+- **通用 API 抽象**：大部分平台都支持的操作（发消息、获取群信息等）定义为通用 API 方法
+- **required / optional 标记**：每个 API 标记为必需或可选，适配器未实现可选 API 时抛出 `NotSupportedError`
+- **透传机制**：适配器特有的操作通过 `call_platform_api(action, params)` 统一入口透传调用
+- **能力声明**：适配器在 manifest 中声明自己支持的 API 列表，供 WebUI 和插件查询
+- **实体统一**：通用实体（User、Group 等）在 SDK 层面统一定义，适配器负责转换
+
+## 2. 通用实体定义
+
+### 2.1 现有实体回顾
+
+当前 SDK 已有以下实体（`langbot_plugin/api/entities/builtin/platform/entities.py`）：
+
+```python
+Entity(id)
+├── Friend(id, nickname, remark)
+├── Group(id, name, permission)
+└── GroupMember(id, member_name, permission, group, special_title)
+```
+
+### 2.2 新实体设计
+
+扩展实体体系，保持向后兼容：
+
+```python
+class User(pydantic.BaseModel):
+    """用户实体（统一表示）"""
+
+    id: typing.Union[int, str]
+    """用户 ID"""
+
+    nickname: str = ""
+    """昵称"""
+
+    avatar_url: typing.Optional[str] = None
+    """头像 URL"""
+
+    is_bot: bool = False
+    """是否为 Bot"""
+
+    # 以下为可选的扩展信息，不同平台可能部分为空
+    username: typing.Optional[str] = None
+    """用户名（如 Telegram 的 @username）"""
+
+    remark: typing.Optional[str] = None
+    """备注名"""
+
+
+class Group(pydantic.BaseModel):
+    """群组实体"""
+
+    id: typing.Union[int, str]
+    """群组 ID"""
+
+    name: str = ""
+    """群组名称"""
+
+    description: typing.Optional[str] = None
+    """群组描述"""
+
+    member_count: typing.Optional[int] = None
+    """成员数量"""
+
+    avatar_url: typing.Optional[str] = None
+    """群组头像 URL"""
+
+    owner_id: typing.Optional[typing.Union[int, str]] = None
+    """群主 ID"""
+
+
+class GroupMember(pydantic.BaseModel):
+    """群成员实体"""
+
+    user: User
+    """用户信息"""
+
+    group_id: typing.Union[int, str]
+    """所属群组 ID"""
+
+    role: MemberRole
+    """群内角色"""
+
+    display_name: typing.Optional[str] = None
+    """群内显示名"""
+
+    joined_at: typing.Optional[float] = None
+    """加入群组的时间戳"""
+
+    title: typing.Optional[str] = None
+    """群头衔/特殊称号"""
+
+
+class MemberRole(str, Enum):
+    """群成员角色"""
+    OWNER = "owner"
+    ADMIN = "admin"
+    MEMBER = "member"
+```
+
+### 2.3 与现有实体的兼容映射
+
+| 新实体 | 旧实体 | 映射方式 |
+|--------|--------|----------|
+| `User` | `Friend` | `User(id=friend.id, nickname=friend.nickname, remark=friend.remark)` |
+| `Group` | `Group`（旧） | `Group(id=old.id, name=old.name)` + `permission` 字段弃用 |
+| `GroupMember` | `GroupMember`（旧） | `GroupMember(user=User(...), role=..., display_name=old.member_name)` |
+| `MemberRole` | `Permission` | `OWNER↔Owner`, `ADMIN↔Administrator`, `MEMBER↔Member` |
+
+旧实体类保留，标记为 `@deprecated`，内部通过转换方法桥接到新实体。
+
+## 3. 通用 API 定义
+
+### 3.1 API 方法一览
+
+#### 消息 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `send_message(target_type, target_id, message)` | **必需** | 主动发送消息 |
+| `reply_message(event, message, quote_origin)` | **必需** | 回复一个消息事件 |
+| `edit_message(chat_type, chat_id, message_id, new_content)` | 可选 | 编辑已发送的消息 |
+| `delete_message(chat_type, chat_id, message_id)` | 可选 | 删除/撤回消息 |
+| `forward_message(from_chat, message_id, to_chat_type, to_chat_id)` | 可选 | 转发消息到另一个会话 |
+| `get_message(chat_type, chat_id, message_id)` | 可选 | 获取指定消息的内容 |
+
+#### 群组 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `get_group_info(group_id)` | 可选 | 获取群组信息 |
+| `get_group_list()` | 可选 | 获取 Bot 加入的群组列表 |
+| `get_group_member_list(group_id)` | 可选 | 获取群成员列表 |
+| `get_group_member_info(group_id, user_id)` | 可选 | 获取指定群成员信息 |
+| `set_group_name(group_id, name)` | 可选 | 修改群名称 |
+| `mute_member(group_id, user_id, duration)` | 可选 | 禁言群成员 |
+| `unmute_member(group_id, user_id)` | 可选 | 解除禁言 |
+| `kick_member(group_id, user_id)` | 可选 | 踢出群成员 |
+| `leave_group(group_id)` | 可选 | Bot 退出群组 |
+
+#### 用户 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `get_user_info(user_id)` | 可选 | 获取用户信息 |
+| `get_friend_list()` | 可选 | 获取好友列表 |
+| `approve_friend_request(request_id, approve, remark)` | 可选 | 处理好友请求 |
+| `approve_group_invite(request_id, approve)` | 可选 | 处理入群邀请 |
+
+#### 媒体 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `upload_file(file_data, filename)` | 可选 | 上传文件，返回可引用的文件 ID 或 URL |
+| `get_file_url(file_id)` | 可选 | 获取文件下载 URL |
+
+#### 透传 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `call_platform_api(action, params)` | 可选 | 调用适配器特有 API |
+
+### 3.2 API 方法签名详解
+
+```python
+class AbstractPlatformAdapter(pydantic.BaseModel, metaclass=abc.ABCMeta):
+    """平台适配器基类（新版）"""
+
+    # ======== 必需方法 ========
+
+    @abc.abstractmethod
+    async def send_message(
+        self,
+        target_type: str,          # "private" | "group"
+        target_id: typing.Union[int, str],
+        message: MessageChain,
+    ) -> MessageResult:
+        """主动发送消息
+
+        Returns:
+            MessageResult: 包含 message_id 等发送结果
+        """
+        ...
+
+    @abc.abstractmethod
+    async def reply_message(
+        self,
+        event: MessageReceivedEvent,
+        message: MessageChain,
+        quote_origin: bool = False,
+    ) -> MessageResult:
+        """回复一个消息事件"""
+        ...
+
+    # ======== 可选消息方法 ========
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: MessageChain,
+    ) -> None:
+        """编辑已发送的消息"""
+        raise NotSupportedError("edit_message")
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """删除/撤回消息"""
+        raise NotSupportedError("delete_message")
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> MessageResult:
+        """转发消息"""
+        raise NotSupportedError("forward_message")
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> MessageReceivedEvent:
+        """获取指定消息"""
+        raise NotSupportedError("get_message")
+
+    # ======== 可选群组方法 ========
+
+    async def get_group_info(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> Group:
+        """获取群组信息"""
+        raise NotSupportedError("get_group_info")
+
+    async def get_group_list(self) -> list[Group]:
+        """获取 Bot 加入的群组列表"""
+        raise NotSupportedError("get_group_list")
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[GroupMember]:
+        """获取群成员列表"""
+        raise NotSupportedError("get_group_member_list")
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> GroupMember:
+        """获取指定群成员信息"""
+        raise NotSupportedError("get_group_member_info")
+
+    async def set_group_name(
+        self,
+        group_id: typing.Union[int, str],
+        name: str,
+    ) -> None:
+        """修改群名称"""
+        raise NotSupportedError("set_group_name")
+
+    async def mute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        """禁言群成员，duration 为秒数，0 表示永久"""
+        raise NotSupportedError("mute_member")
+
+    async def unmute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """解除禁言"""
+        raise NotSupportedError("unmute_member")
+
+    async def kick_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """踢出群成员"""
+        raise NotSupportedError("kick_member")
+
+    async def leave_group(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> None:
+        """Bot 退出群组"""
+        raise NotSupportedError("leave_group")
+
+    # ======== 可选用户方法 ========
+
+    async def get_user_info(
+        self,
+        user_id: typing.Union[int, str],
+    ) -> User:
+        """获取用户信息"""
+        raise NotSupportedError("get_user_info")
+
+    async def get_friend_list(self) -> list[User]:
+        """获取好友列表"""
+        raise NotSupportedError("get_friend_list")
+
+    async def approve_friend_request(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        """处理好友请求"""
+        raise NotSupportedError("approve_friend_request")
+
+    async def approve_group_invite(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+    ) -> None:
+        """处理入群邀请"""
+        raise NotSupportedError("approve_group_invite")
+
+    # ======== 可选媒体方法 ========
+
+    async def upload_file(
+        self,
+        file_data: bytes,
+        filename: str,
+    ) -> str:
+        """上传文件，返回文件 ID 或 URL"""
+        raise NotSupportedError("upload_file")
+
+    async def get_file_url(
+        self,
+        file_id: str,
+    ) -> str:
+        """获取文件下载 URL"""
+        raise NotSupportedError("get_file_url")
+
+    # ======== 透传 API ========
+
+    async def call_platform_api(
+        self,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """调用适配器特有 API
+
+        Args:
+            action: 平台特有的 API 动作标识
+            params: 参数字典
+
+        Returns:
+            dict: 返回结果
+
+        Examples:
+            # Telegram: pin 消息
+            await adapter.call_platform_api("pin_message", {
+                "chat_id": 123456,
+                "message_id": 789
+            })
+
+            # Discord: 创建频道
+            await adapter.call_platform_api("create_channel", {
+                "guild_id": "...",
+                "name": "new-channel",
+                "type": "text"
+            })
+        """
+        raise NotSupportedError("call_platform_api")
+
+    # ======== 流式输出（保留现有机制） ========
+
+    async def reply_message_chunk(
+        self,
+        event: MessageReceivedEvent,
+        bot_message: dict,
+        message: MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        """流式回复消息"""
+        raise NotSupportedError("reply_message_chunk")
+
+    async def is_stream_output_supported(self) -> bool:
+        """是否支持流式输出"""
+        return False
+
+    # ======== 生命周期方法（保留现有） ========
+
+    @abc.abstractmethod
+    async def run_async(self):
+        """启动适配器"""
+        ...
+
+    @abc.abstractmethod
+    async def kill(self) -> bool:
+        """停止适配器"""
+        ...
+
+    @abc.abstractmethod
+    def register_listener(self, event_type, callback):
+        """注册事件监听器"""
+        ...
+
+    @abc.abstractmethod
+    def unregister_listener(self, event_type, callback):
+        """注销事件监听器"""
+        ...
+```
+
+### 3.3 返回值类型
+
+```python
+class MessageResult(pydantic.BaseModel):
+    """消息发送结果"""
+
+    message_id: typing.Optional[typing.Union[int, str]] = None
+    """发送成功后的消息 ID"""
+
+    raw: typing.Optional[dict] = None
+    """平台原始返回数据"""
+
+
+class NotSupportedError(Exception):
+    """适配器未实现此 API"""
+
+    def __init__(self, api_name: str):
+        self.api_name = api_name
+        super().__init__(f"API not supported by this adapter: {api_name}")
+```
+
+## 4. API 能力声明
+
+适配器在 manifest.yaml 中声明支持的 API：
+
+```yaml
+kind: MessagePlatformAdapter
+metadata:
+  name: telegram
+spec:
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - edit_message
+      - delete_message
+      - get_group_info
+      - get_group_member_list
+      - get_user_info
+      - upload_file
+      - get_file_url
+      - call_platform_api
+  platform_specific_apis:
+    - action: pin_message
+      description: "Pin a message in a chat"
+      params_schema:
+        chat_id: { type: "string", required: true }
+        message_id: { type: "string", required: true }
+    - action: unpin_message
+      description: "Unpin a message"
+      params_schema:
+        chat_id: { type: "string", required: true }
+        message_id: { type: "string", required: true }
+```
+
+用途：
+1. **WebUI**：在配置界面展示当前 Bot 可用的 API 能力
+2. **插件**：插件可查询某个 Bot 是否支持特定 API，据此决定行为
+3. **文档**：自动生成各适配器的 API 支持矩阵
+
+## 5. 各平台 API 支持矩阵
+
+| API | Telegram | Discord | OneBot(QQ) | 飞书 | 钉钉 | Slack | 微信 | LINE | KOOK |
+|-----|----------|---------|-----------|------|------|-------|------|------|------|
+| `send_message` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `reply_message` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `edit_message` | Y | Y | N | Y | N | Y | N | N | Y |
+| `delete_message` | Y | Y | Y | Y | N | Y | Y | N | Y |
+| `forward_message` | Y | N | Y | Y | N | N | Y | N | N |
+| `get_group_info` | Y | Y | Y | Y | Y | Y | N | Y | Y |
+| `get_group_member_list` | Y | Y | Y | Y | Y | Y | N | Y | Y |
+| `get_user_info` | Y | Y | Y | Y | Y | Y | N | Y | Y |
+| `get_friend_list` | N | Y | Y | N | N | N | Y | N | N |
+| `mute_member` | Y | Y | Y | N | N | N | N | N | N |
+| `kick_member` | Y | Y | Y | N | N | N | N | N | Y |
+| `upload_file` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `call_platform_api` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+
+> 注：此表为初步评估，具体以各平台 SDK/API 文档为准。
+
+## 6. MessageChain 扩展
+
+### 6.1 保留的通用组件
+
+以下 MessageComponent 类型保持不变，继续作为通用消息元素：
+
+- `Source` — 消息元信息
+- `Plain` — 纯文本
+- `Quote` — 引用回复
+- `At` / `AtAll` — @提及
+- `Image` — 图片
+- `Voice` — 语音
+- `File` — 文件
+- `Forward` — 合并转发
+- `Face` — 表情
+- `Unknown` — 未知类型
+
+### 6.2 平台特有组件处理
+
+当前 MessageChain 中存在大量微信特有的组件类型（`WeChatMiniPrograms`, `WeChatEmoji`, `WeChatLink` 等）。在新架构下：
+
+- 这些类型**继续保留**在 SDK 中以保持兼容
+- 新增的平台特有消息组件统一使用 `PlatformComponent` 基类：
+
+```python
+class PlatformComponent(MessageComponent):
+    """平台特有的消息组件"""
+
+    type: str = "Platform"
+
+    platform: str
+    """平台标识"""
+
+    component_type: str
+    """组件类型"""
+
+    data: dict = {}
+    """组件数据"""
+```
+
+适配器在转换消息链时，对于无法映射到通用组件的平台特有内容，使用 `PlatformComponent` 承载。

docs/event-based-agents/03-adapter-structure.md

@@ -0,0 +1,483 @@
+# 适配器新目录结构
+
+## 1. 设计目标
+
+- **模块化**：每个适配器从单文件拆分到独立目录，各模块职责清晰
+- **可维护**：随着事件和 API 的增加，代码量会显著增长，目录结构有助于管理复杂度
+- **一致性**：所有适配器遵循相同的目录布局和文件命名约定
+- **兼容现有发现机制**：保持 YAML manifest + ComponentDiscoveryEngine 的注册体系
+
+## 2. 新目录布局
+
+### 2.1 整体结构
+
+```
+pkg/platform/
+├── __init__.py
+├── botmgr.py                  # PlatformManager + RuntimeBot（重构）
+├── event_bus.py               # EventBus（新增）
+├── event_router.py            # EventRouter（新增）
+├── logger.py                  # EventLogger（保留）
+├── webhook_pusher.py          # WebhookPusher（重构为 WebhookHandler）
+│
+├── adapters/                  # 适配器（新目录）
+│   ├── __init__.py
+│   │
+│   ├── telegram/
+│   │   ├── __init__.py
+│   │   ├── adapter.py         # TelegramAdapter 主类
+│   │   ├── event_converter.py # 平台事件 → 统一事件
+│   │   ├── message_converter.py # MessageChain 互转
+│   │   ├── api_impl.py        # 通用 API 实现
+│   │   ├── platform_api.py    # call_platform_api 的动作映射
+│   │   ├── types.py           # 平台特有类型定义
+│   │   └── manifest.yaml      # 适配器清单
+│   │
+│   ├── discord/
+│   │   ├── __init__.py
+│   │   ├── adapter.py
+│   │   ├── event_converter.py
+│   │   ├── message_converter.py
+│   │   ├── api_impl.py
+│   │   ├── platform_api.py
+│   │   ├── types.py
+│   │   ├── voice.py           # Discord 语音连接管理（特有）
+│   │   └── manifest.yaml
+│   │
+│   ├── aiocqhttp/             # OneBot v11 (QQ)
+│   │   └── ...
+│   ├── qqofficial/
+│   │   └── ...
+│   ├── lark/                  # 飞书
+│   │   └── ...
+│   ├── dingtalk/
+│   │   └── ...
+│   ├── slack/
+│   │   └── ...
+│   ├── wechatpad/
+│   │   └── ...
+│   ├── officialaccount/       # 微信公众号
+│   │   └── ...
+│   ├── wecom/                 # 企业微信
+│   │   └── ...
+│   ├── wecombot/
+│   │   └── ...
+│   ├── wecomcs/
+│   │   └── ...
+│   ├── kook/
+│   │   └── ...
+│   ├── line/
+│   │   └── ...
+│   ├── satori/
+│   │   └── ...
+│   ├── websocket/             # 内置 WebSocket 适配器
+│   │   ├── __init__.py
+│   │   ├── adapter.py
+│   │   ├── manager.py         # WebSocket 连接管理
+│   │   └── manifest.yaml
+│   │
+│   └── legacy/                # 旧版适配器（保留一段时间后移除）
+│       ├── gewechat/
+│       ├── nakuru/
+│       └── qqbotpy/
+│
+└── handlers/                  # 事件处理器实现（新增）
+    ├── __init__.py
+    ├── base.py                # AbstractEventHandler 基类
+    ├── pipeline_handler.py    # PipelineHandler
+    ├── agent_handler.py       # AgentHandler
+    ├── webhook_handler.py     # WebhookHandler
+    └── plugin_handler.py      # PluginHandler
+```
+
+### 2.2 适配器目录内各文件职责
+
+以 Telegram 为例：
+
+| 文件 | 职责 | 关键类/函数 |
+|------|------|------------|
+| `adapter.py` | 主入口，继承 `AbstractPlatformAdapter`，组装其他模块 | `TelegramAdapter` |
+| `event_converter.py` | 将 Telegram 原生事件转换为统一事件类型 | `TelegramEventConverter` — 支持 Message/Edit/Delete/Reaction/MemberJoin 等所有事件 |
+| `message_converter.py` | `MessageChain` 与 Telegram 消息格式互转 | `TelegramMessageConverter.yiri2target()` / `target2yiri()` |
+| `api_impl.py` | 实现通用 API 方法（edit_message, delete_message, get_group_info 等） | 各 API 方法的 Telegram 实现 |
+| `platform_api.py` | 实现 `call_platform_api` 的动作分发表 | `PLATFORM_API_MAP = {"pin_message": ..., "unpin_message": ...}` |
+| `types.py` | 平台特有的类型定义 | Telegram 特有的枚举、配置结构等 |
+| `manifest.yaml` | 适配器清单：名称、配置 schema、支持的事件和 API 列表 | — |
+
+## 3. 新基类设计
+
+### 3.1 AbstractPlatformAdapter
+
+新基类继承自现有 `AbstractMessagePlatformAdapter` 并扩展，位于 `langbot-plugin-sdk` 中：
+
+```python
+# langbot_plugin/api/definition/abstract/platform/adapter.py
+
+class AbstractPlatformAdapter(pydantic.BaseModel, metaclass=abc.ABCMeta):
+    """平台适配器基类（EBA 版本）
+
+    相比旧版 AbstractMessagePlatformAdapter：
+    - 新增通用 API 方法（edit_message, delete_message, get_group_info 等）
+    - 新增透传 API（call_platform_api）
+    - 新增能力声明（get_supported_events, get_supported_apis）
+    - 事件监听器支持所有事件类型，不仅限于消息事件
+    """
+
+    bot_account_id: str = ""
+    config: dict
+    logger: AbstractEventLogger = pydantic.Field(exclude=True)
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    # ---- 能力声明 ----
+
+    def get_supported_events(self) -> list[str]:
+        """返回此适配器支持的事件类型列表
+
+        默认实现从 manifest.yaml 读取。
+        适配器也可以 override 此方法动态声明。
+        """
+        return ["message.received"]
+
+    def get_supported_apis(self) -> list[str]:
+        """返回此适配器支持的 API 列表
+
+        默认实现从 manifest.yaml 读取。
+        """
+        return ["send_message", "reply_message"]
+
+    # ---- 必需方法（抽象） ----
+
+    @abc.abstractmethod
+    async def send_message(self, target_type, target_id, message) -> MessageResult:
+        ...
+
+    @abc.abstractmethod
+    async def reply_message(self, event, message, quote_origin=False) -> MessageResult:
+        ...
+
+    @abc.abstractmethod
+    async def run_async(self):
+        ...
+
+    @abc.abstractmethod
+    async def kill(self) -> bool:
+        ...
+
+    @abc.abstractmethod
+    def register_listener(self, event_type, callback):
+        ...
+
+    @abc.abstractmethod
+    def unregister_listener(self, event_type, callback):
+        ...
+
+    # ---- 可选方法（默认抛 NotSupportedError） ----
+    # edit_message, delete_message, forward_message,
+    # get_group_info, get_group_member_list, ...
+    # call_platform_api, ...
+    # （完整签名见 02-platform-api.md）
+
+    # ---- 流式输出（保留） ----
+
+    async def reply_message_chunk(self, event, bot_message, message,
+                                   quote_origin=False, is_final=False):
+        raise NotSupportedError("reply_message_chunk")
+
+    async def is_stream_output_supported(self) -> bool:
+        return False
+
+    # ---- 消息卡片（保留） ----
+
+    async def create_message_card(self, message_id, event) -> bool:
+        return False
+
+    async def is_muted(self, group_id) -> bool:
+        return False
+```
+
+### 3.2 AbstractMessagePlatformAdapter 兼容
+
+旧的 `AbstractMessagePlatformAdapter` 保留为 `AbstractPlatformAdapter` 的类型别名：
+
+```python
+# 向后兼容
+AbstractMessagePlatformAdapter = AbstractPlatformAdapter
+```
+
+现有适配器代码中的 `AbstractMessagePlatformAdapter` 引用不需要立即修改。
+
+### 3.3 EventConverter 新设计
+
+现有 `AbstractEventConverter` 只有 `target2yiri` 和 `yiri2target` 两个静态方法，且只处理消息事件。
+
+新设计支持多种事件类型：
+
+```python
+class AbstractEventConverter:
+    """事件转换器基类（EBA 版本）
+
+    适配器需要实现此转换器，将平台原生事件转换为统一事件。
+    """
+
+    @staticmethod
+    def target2yiri(raw_event: typing.Any) -> typing.Optional[Event]:
+        """将平台原生事件转换为统一事件
+
+        Args:
+            raw_event: 平台 SDK 回调传入的原始事件对象
+
+        Returns:
+            统一 Event 对象，如果无法转换或不需要处理则返回 None
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def yiri2target(event: Event) -> typing.Any:
+        """将统一事件转换为平台原生事件（一般不需要）"""
+        raise NotImplementedError
+```
+
+具体适配器的 EventConverter 实现会是一个分发式的结构：
+
+```python
+class TelegramEventConverter(AbstractEventConverter):
+    """Telegram 事件转换器"""
+
+    @staticmethod
+    def target2yiri(update: telegram.Update) -> typing.Optional[Event]:
+        # 消息事件
+        if update.message:
+            return TelegramEventConverter._convert_message(update)
+        # 消息编辑
+        if update.edited_message:
+            return TelegramEventConverter._convert_edited_message(update)
+        # 成员变动
+        if update.chat_member:
+            return TelegramEventConverter._convert_chat_member(update)
+        # 回调查询（按钮点击等）
+        if update.callback_query:
+            return TelegramEventConverter._convert_callback_query(update)
+        # 其他 → PlatformSpecificEvent
+        return TelegramEventConverter._convert_platform_specific(update)
+
+    @staticmethod
+    def _convert_message(update) -> MessageReceivedEvent:
+        ...
+
+    @staticmethod
+    def _convert_edited_message(update) -> MessageEditedEvent:
+        ...
+
+    @staticmethod
+    def _convert_chat_member(update) -> typing.Union[
+        MemberJoinedEvent, MemberLeftEvent, ...
+    ]:
+        ...
+
+    @staticmethod
+    def _convert_platform_specific(update) -> PlatformSpecificEvent:
+        ...
+```
+
+## 4. Manifest 文件格式扩展
+
+现有 manifest.yaml 只声明 `kind`, `metadata`, `spec.config`, `execution`。
+
+新增 `spec.supported_events` 和 `spec.supported_apis`：
+
+```yaml
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: telegram
+  label:
+    en_US: Telegram
+    zh_Hans: Telegram
+  icon: telegram.svg
+  description:
+    en_US: Telegram Bot adapter
+    zh_Hans: Telegram Bot 适配器
+
+spec:
+  config:
+    # 现有配置 schema（保持不变）
+    - key: token
+      label: { en_US: "Bot Token", zh_Hans: "Bot Token" }
+      type: string
+      required: true
+      sensitive: true
+    # ...
+
+  supported_events:
+    - message.received
+    - message.edited
+    - message.deleted
+    - message.reaction
+    - feedback.received
+    - group.member_joined
+    - group.member_left
+    - group.member_banned
+    - group.info_updated
+    - bot.invited_to_group
+    - bot.removed_from_group
+    - bot.muted
+    - bot.unmuted
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - edit_message
+      - delete_message
+      - get_group_info
+      - get_group_member_list
+      - get_group_member_info
+      - get_user_info
+      - upload_file
+      - get_file_url
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: pin_message
+      description: { en_US: "Pin a message", zh_Hans: "置顶消息" }
+    - action: unpin_message
+      description: { en_US: "Unpin a message", zh_Hans: "取消置顶" }
+    - action: get_chat_administrators
+      description: { en_US: "Get chat admins", zh_Hans: "获取群管理员列表" }
+
+execution:
+  python:
+    path: pkg/platform/adapters/telegram/adapter.py
+    attr: TelegramAdapter
+```
+
+## 5. 适配器注册与发现
+
+### 5.1 Blueprint 更新
+
+`templates/components.yaml` 中更新扫描路径：
+
+```yaml
+kind: Blueprint
+spec:
+  components:
+    MessagePlatformAdapter:
+      fromDirs:
+        - path: pkg/platform/adapters/     # 新路径
+```
+
+`ComponentDiscoveryEngine` 的递归扫描逻辑不变——它会扫描所有子目录中的 `.yaml` 文件。因此每个适配器目录下的 `manifest.yaml` 会被自动发现。
+
+### 5.2 PlatformManager 适配
+
+`PlatformManager.initialize()` 的核心逻辑基本不变：
+
+```python
+async def initialize(self):
+    # 1. 发现适配器组件（自动扫描新目录结构）
+    self.adapter_components = self.ap.discover.get_components_by_kind('MessagePlatformAdapter')
+
+    # 2. 动态导入适配器类
+    for component in self.adapter_components:
+        self.adapter_dict[component.metadata.name] = component.get_python_component_class()
+
+    # 3. 从数据库加载 Bot 并实例化适配器（不变）
+    await self.load_bots_from_db()
+```
+
+变更点：
+- `execution.python.path` 从 `pkg/platform/sources/telegram.py` 变为 `pkg/platform/adapters/telegram/adapter.py`
+- `get_python_component_class()` 正常工作，因为它按路径动态导入
+
+## 6. RuntimeBot 重构
+
+### 6.1 现有问题
+
+当前 `RuntimeBot.initialize()` 硬编码注册了两个回调：
+
+```python
+# 现有代码
+self.adapter.register_listener(platform_events.FriendMessage, on_friend_message)
+self.adapter.register_listener(platform_events.GroupMessage, on_group_message)
+```
+
+### 6.2 新设计
+
+`RuntimeBot` 改为注册一个通用的事件回调：
+
+```python
+class RuntimeBot:
+    async def initialize(self):
+        # 注册通用事件回调，接收所有事件类型
+        self.adapter.register_listener(Event, self._on_event)
+
+    async def _on_event(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+    ):
+        """统一事件入口"""
+
+        # 1. 设置事件的 bot_uuid 和 adapter_name
+        event.bot_uuid = self.bot_entity.uuid
+        event.adapter_name = self.bot_entity.adapter
+
+        # 2. 日志记录
+        await self._log_event(event)
+
+        # 3. 提交给 EventBus
+        await self.ap.event_bus.emit(event, adapter)
+```
+
+适配器侧的 `register_listener` 实现也需调整：
+- 当 `event_type` 为 `Event`（基类）时，注册为"接收所有事件"的通配回调
+- 适配器在收到平台原生事件时，通过 `EventConverter.target2yiri()` 转换后，调用所有匹配的回调
+
+## 7. 从现有单文件适配器迁移
+
+### 7.1 迁移模式
+
+以 Telegram 为例，从 `sources/telegram.py`（445 行）拆分：
+
+| 原代码位置 | → 新文件 |
+|-----------|----------|
+| `TelegramMessageConverter` 类 | `telegram/message_converter.py` |
+| `TelegramEventConverter` 类 | `telegram/event_converter.py`（扩展，支持更多事件） |
+| `TelegramAdapter.__init__` / `run_async` / `kill` / `register_listener` | `telegram/adapter.py` |
+| `TelegramAdapter.send_message` / `reply_message` / `reply_message_chunk` | `telegram/adapter.py`（消息方法保留在主类）+ `telegram/api_impl.py`（新增 API） |
+| 新增代码 | `telegram/api_impl.py`（edit_message, delete_message, get_group_info 等） |
+| 新增代码 | `telegram/platform_api.py`（pin_message, unpin_message 等的映射） |
+| `telegram.yaml` | `telegram/manifest.yaml`（扩展 supported_events/apis） |
+
+### 7.2 迁移顺序建议
+
+1. **Telegram** — 功能最完整的适配器之一，适合作为模板
+2. **Discord** — 第二个迁移，验证模式的通用性
+3. **AioCQHTTP (OneBot)** — 国内最常用，确保兼容
+4. **其他适配器** — 按使用频率排序
+
+### 7.3 渐进式迁移
+
+不需要一次性迁移所有适配器。可以采用渐进策略：
+
+1. 先在 `adapters/` 下建立新适配器
+2. `Blueprint` 同时扫描 `sources/` 和 `adapters/` 两个目录
+3. 旧适配器在 `sources/` 中继续工作
+4. 逐个迁移到新结构
+5. 全部迁移完成后移除 `sources/` 目录
+
+```yaml
+# 过渡期的 Blueprint
+kind: Blueprint
+spec:
+  components:
+    MessagePlatformAdapter:
+      fromDirs:
+        - path: pkg/platform/sources/      # 旧路径（尚未迁移的适配器）
+        - path: pkg/platform/adapters/      # 新路径（已迁移的适配器）
+```

docs/event-based-agents/04-event-routing.md

@@ -0,0 +1,743 @@
+# 事件路由与编排
+
+## 1. 概述
+
+事件路由是 EBA 架构的核心机制：事件从适配器产生后，经由 EventBus 进入 EventRouter，由 EventRouter 根据 Bot 的配置将事件分发到对应的处理器（Handler）。
+
+**配置方式**：用户在 WebUI 的 Bot 管理页面通过可视化编排面板管理事件处理器配置，配置数据存储在数据库的 Bot 表 `event_handlers` JSON 字段中。
+
+## 2. 数据模型
+
+### 2.1 Bot 实体扩展
+
+在 `bots` 表新增 `event_handlers` 字段：
+
+```python
+class Bot(Base):
+    __tablename__ = "bots"
+
+    uuid: str               # 主键
+    name: str
+    description: str
+    adapter: str
+    adapter_config: dict    # JSON
+    enable: bool
+
+    # 新增
+    event_handlers: list    # JSON — 事件处理器配置列表
+
+    # 保留（过渡期后弃用）
+    use_pipeline_name: str  # deprecated
+    use_pipeline_uuid: str  # deprecated
+
+    created_at: datetime
+    updated_at: datetime
+```
+
+### 2.2 EventHandler 配置结构
+
+`event_handlers` 字段存储一个 JSON 数组，每个元素定义一条事件路由规则：
+
+```python
+class EventHandlerConfig(pydantic.BaseModel):
+    """单条事件处理器配置"""
+
+    event_type: str
+    """匹配的事件类型
+
+    支持精确匹配和通配符：
+    - "message.received"       — 精确匹配
+    - "message.*"              — 匹配 message 命名空间下所有事件
+    - "group.*"                — 匹配 group 命名空间下所有事件
+    - "*"                      — 匹配所有事件（兜底）
+    """
+
+    handler_type: str
+    """处理器类型: "pipeline" | "agent" | "webhook" | "plugin" """
+
+    handler_config: dict = {}
+    """处理器的具体配置，结构取决于 handler_type"""
+
+    enabled: bool = True
+    """是否启用此规则"""
+
+    priority: int = 0
+    """优先级，数字越大越先匹配（同一事件类型有多条规则时）"""
+
+    description: str = ""
+    """规则描述（供 WebUI 显示）"""
+```
+
+### 2.3 各 Handler 类型的 handler_config 结构
+
+#### pipeline
+
+```json
+{
+    "handler_type": "pipeline",
+    "handler_config": {
+        "pipeline_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    }
+}
+```
+
+将事件作为消息事件传入现有 Pipeline 流水线。仅适用于 `message.received` 事件。
+
+#### agent
+
+```json
+{
+    "handler_type": "agent",
+    "handler_config": {
+        "runner": "local-agent",
+        "runner_config": {
+            "model_uuid": "...",
+            "prompt": "你是一个群组助理，请处理以下事件：{event_summary}",
+            "tools_enabled": true
+        }
+    }
+}
+```
+
+```json
+{
+    "handler_type": "agent",
+    "handler_config": {
+        "runner": "dify-service-api",
+        "runner_config": {
+            "base_url": "https://api.dify.ai/v1",
+            "api_key": "...",
+            "app_type": "agent"
+        }
+    }
+}
+```
+
+直接调用 RequestRunner 处理事件。可用的 runner 包括：
+- `local-agent` — 内置 LLM Agent
+- `dify-service-api` — Dify 平台
+- `n8n-service-api` — n8n 工作流
+- `coze-api` — Coze (扣子)
+- `dashscope-app-api` — 阿里百炼
+- `langflow-api` — Langflow
+- `tbox-app-api` — 蚂蚁 Tbox
+
+Agent 处理器不经过 Pipeline 的多 Stage 流程，而是直接构建上下文并调用 Runner。适用于所有事件类型。
+
+**Agent Handler 与 Pipeline 的关系**：
+- Pipeline 是完整的多 Stage 处理链（PreProcessor → MessageProcessor(内含Runner) → PostProcessor → ...），适合复杂消息处理
+- Agent Handler 是轻量级的，直接调用 Runner，跳过 PreProcessor/PostProcessor 等阶段
+- Pipeline 内部的 AI Stage 仍然使用 Runner，所以 Runner 本身被两种 Handler 共享
+- 用户可以根据场景选择：消息处理用 Pipeline（更多控制），其他事件用 Agent（更直接）
+
+#### webhook
+
+```json
+{
+    "handler_type": "webhook",
+    "handler_config": {
+        "url": "https://example.com/webhook/langbot-events",
+        "method": "POST",
+        "headers": {
+            "Authorization": "Bearer xxx"
+        },
+        "timeout": 30,
+        "retry_count": 3,
+        "retry_interval": 5,
+        "response_actions": true
+    }
+}
+```
+
+将事件序列化为 JSON POST 到外部 URL。支持的特性：
+- **认证**：通过 headers 配置（Bearer Token、API Key 等）
+- **重试**：配置重试次数和间隔
+- **响应动作**：如果 `response_actions` 为 true，解析响应 JSON 中的 `actions` 字段并执行（如发送消息、同意好友请求等）
+
+Webhook 请求体格式：
+
+```json
+{
+    "event": {
+        "type": "group.member_joined",
+        "timestamp": 1700000000.0,
+        "bot_uuid": "...",
+        "adapter_name": "telegram",
+        "group": { "id": "...", "name": "..." },
+        "member": { "id": "...", "nickname": "..." }
+    },
+    "bot": {
+        "uuid": "...",
+        "name": "...",
+        "adapter": "telegram"
+    }
+}
+```
+
+响应体格式（当 `response_actions` 为 true 时）：
+
+```json
+{
+    "actions": [
+        {
+            "type": "send_message",
+            "params": {
+                "target_type": "group",
+                "target_id": "123456",
+                "message": [{ "type": "Plain", "text": "欢迎新成员！" }]
+            }
+        },
+        {
+            "type": "call_platform_api",
+            "params": {
+                "action": "pin_message",
+                "params": { "chat_id": "123456", "message_id": "789" }
+            }
+        }
+    ]
+}
+```
+
+#### plugin
+
+```json
+{
+    "handler_type": "plugin",
+    "handler_config": {
+        "plugin_filter": []
+    }
+}
+```
+
+将事件分发给插件的 EventListener 处理。
+
+- `plugin_filter`：可选的插件名过滤列表，为空表示分发给所有插件
+- 沿用现有的插件事件分发机制（按优先级遍历插件，支持 `prevent_postorder`）
+
+### 2.4 完整配置示例
+
+一个 Bot 的 `event_handlers` 配置示例：
+
+```json
+[
+    {
+        "event_type": "message.received",
+        "handler_type": "pipeline",
+        "handler_config": {
+            "pipeline_uuid": "default-pipeline-uuid"
+        },
+        "enabled": true,
+        "priority": 10,
+        "description": "消息事件使用默认流水线处理"
+    },
+    {
+        "event_type": "group.member_joined",
+        "handler_type": "agent",
+        "handler_config": {
+            "runner": "local-agent",
+            "runner_config": {
+                "model_uuid": "gpt-4o-mini",
+                "prompt": "有新成员 {member_name} 加入了群组 {group_name}，请生成一条欢迎消息。"
+            }
+        },
+        "enabled": true,
+        "priority": 0,
+        "description": "新成员入群时用 AI 生成欢迎消息"
+    },
+    {
+        "event_type": "friend.request_received",
+        "handler_type": "webhook",
+        "handler_config": {
+            "url": "https://my-server.com/api/friend-request",
+            "response_actions": true
+        },
+        "enabled": true,
+        "priority": 0,
+        "description": "好友请求转发到自建服务处理"
+    },
+    {
+        "event_type": "*",
+        "handler_type": "plugin",
+        "handler_config": {},
+        "enabled": true,
+        "priority": -100,
+        "description": "所有事件兜底发给插件处理"
+    }
+]
+```
+
+## 3. EventBus 设计
+
+EventBus 是事件的中转站，接收来自各个 RuntimeBot 的事件，交由 EventRouter 处理。
+
+```python
+class EventBus:
+    """事件总线"""
+
+    def __init__(self, ap: Application):
+        self.ap = ap
+        self.event_router = EventRouter(ap)
+
+    async def emit(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+    ):
+        """接收并分发事件
+
+        Args:
+            event: 统一事件对象
+            adapter: 产生此事件的适配器实例
+        """
+        # 1. 全局事件日志
+        self.ap.logger.debug(
+            f"EventBus: {event.type} from bot {event.bot_uuid}"
+        )
+
+        # 2. 交由 EventRouter 路由处理
+        await self.event_router.route(event, adapter)
+```
+
+## 4. EventRouter 设计
+
+EventRouter 是事件路由引擎，根据 Bot 的 `event_handlers` 配置决定事件的处理方式。
+
+```python
+class EventRouter:
+    """事件路由引擎"""
+
+    def __init__(self, ap: Application):
+        self.ap = ap
+        self.handlers: dict[str, AbstractEventHandler] = {
+            "pipeline": PipelineHandler(ap),
+            "agent": AgentHandler(ap),
+            "webhook": WebhookHandler(ap),
+            "plugin": PluginHandler(ap),
+        }
+
+    async def route(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+    ):
+        """路由事件到对应处理器"""
+
+        # 1. 获取 Bot 配置
+        bot = await self.ap.platform_mgr.get_bot_by_uuid(event.bot_uuid)
+        if not bot:
+            return
+
+        # 2. 获取事件处理器配置
+        event_handlers = bot.bot_entity.event_handlers or []
+
+        # 3. 匹配规则（按 priority 降序排列）
+        matched_handlers = self._match_handlers(event.type, event_handlers)
+
+        if not matched_handlers:
+            # 未匹配到任何规则 → 默认交给插件处理（向后兼容）
+            await self.handlers["plugin"].handle(event, adapter, {})
+            return
+
+        # 4. 执行第一个匹配的 Handler
+        #    （未来可扩展为多个 Handler 串行/并行执行）
+        handler_config = matched_handlers[0]
+        handler = self.handlers.get(handler_config.handler_type)
+
+        if handler:
+            await handler.handle(event, adapter, handler_config.handler_config)
+        else:
+            self.ap.logger.warning(
+                f"Unknown handler type: {handler_config.handler_type}"
+            )
+
+    def _match_handlers(
+        self,
+        event_type: str,
+        handlers: list[EventHandlerConfig],
+    ) -> list[EventHandlerConfig]:
+        """匹配事件类型到处理器配置
+
+        匹配规则：
+        1. 精确匹配：event_type == handler.event_type
+        2. 命名空间通配：handler.event_type 为 "message.*" 时匹配所有 "message.xxx"
+        3. 全局通配：handler.event_type 为 "*" 时匹配所有事件
+        4. 按 priority 降序排列
+        5. 只返回 enabled=True 的规则
+        """
+        matched = []
+        for handler in handlers:
+            if not handler.enabled:
+                continue
+            if self._event_type_matches(event_type, handler.event_type):
+                matched.append(handler)
+
+        matched.sort(key=lambda h: h.priority, reverse=True)
+        return matched
+
+    @staticmethod
+    def _event_type_matches(event_type: str, pattern: str) -> bool:
+        """判断事件类型是否匹配模式"""
+        if pattern == "*":
+            return True
+        if pattern == event_type:
+            return True
+        if pattern.endswith(".*"):
+            namespace = pattern[:-2]
+            return event_type.startswith(namespace + ".")
+        return False
+```
+
+## 5. 事件处理器（Handler）实现
+
+### 5.1 Handler 基类
+
+```python
+class AbstractEventHandler(abc.ABC):
+    """事件处理器基类"""
+
+    def __init__(self, ap: Application):
+        self.ap = ap
+
+    @abc.abstractmethod
+    async def handle(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+        config: dict,
+    ) -> None:
+        """处理事件
+
+        Args:
+            event: 统一事件对象
+            adapter: 适配器实例（用于调用平台 API 发送响应）
+            config: handler_config 配置
+        """
+        ...
+```
+
+### 5.2 PipelineHandler
+
+将消息事件注入现有 Pipeline 流水线处理。
+
+```python
+class PipelineHandler(AbstractEventHandler):
+    """Pipeline 处理器 — 将事件送入现有 Pipeline 流水线"""
+
+    async def handle(self, event, adapter, config):
+        pipeline_uuid = config.get("pipeline_uuid")
+
+        if not isinstance(event, MessageReceivedEvent):
+            self.ap.logger.warning(
+                f"PipelineHandler only supports MessageReceivedEvent, "
+                f"got {event.type}"
+            )
+            return
+
+        # 将 MessageReceivedEvent 转换为现有的 Query 并投入 QueryPool
+        # 复用现有的 MessageAggregator + QueryPool + Pipeline 机制
+        launcher_type = (
+            LauncherTypes.PERSON
+            if event.chat_type == ChatType.PRIVATE
+            else LauncherTypes.GROUP
+        )
+
+        await self.ap.msg_aggregator.add_message(
+            bot_uuid=event.bot_uuid,
+            launcher_type=launcher_type,
+            launcher_id=event.chat_id,
+            sender_id=event.sender.id,
+            message_event=event.to_legacy_event(),  # 转换为 FriendMessage/GroupMessage
+            message_chain=event.message_chain,
+            adapter=adapter,
+            pipeline_uuid=pipeline_uuid,
+        )
+```
+
+### 5.3 AgentHandler
+
+直接调用 RequestRunner 处理事件，不经过 Pipeline Stage 链。
+
+```python
+class AgentHandler(AbstractEventHandler):
+    """Agent 处理器 — 直接调用 RequestRunner 处理事件"""
+
+    async def handle(self, event, adapter, config):
+        runner_name = config.get("runner", "local-agent")
+        runner_config = config.get("runner_config", {})
+
+        # 1. 查找 Runner 类
+        runner_cls = None
+        for r in preregistered_runners:
+            if r.name == runner_name:
+                runner_cls = r
+                break
+
+        if not runner_cls:
+            self.ap.logger.error(f"Runner not found: {runner_name}")
+            return
+
+        # 2. 构建事件上下文（将事件信息整理为 Runner 可处理的格式）
+        event_context = self._build_event_context(event, runner_config)
+
+        # 3. 实例化并调用 Runner
+        runner = runner_cls(self.ap, self._build_runner_pipeline_config(config))
+
+        response_messages = []
+        async for result in runner.run(event_context):
+            response_messages.append(result)
+
+        # 4. 发送响应（如果 Runner 产生了回复）
+        if response_messages and isinstance(event, MessageReceivedEvent):
+            # 将 Runner 输出转换为 MessageChain 并回复
+            reply_chain = self._build_reply_chain(response_messages)
+            await adapter.reply_message(event, reply_chain)
+
+    def _build_event_context(self, event, runner_config):
+        """将事件构建为 Runner 可处理的上下文
+
+        对于消息事件，直接使用消息内容。
+        对于其他事件，根据 runner_config 中的 prompt 模板生成描述文本。
+        """
+        ...
+
+    def _build_runner_pipeline_config(self, config):
+        """将 handler_config 转换为 Runner 需要的 pipeline_config 格式"""
+        ...
+```
+
+### 5.4 WebhookHandler
+
+将事件 POST 到外部 URL。
+
+```python
+class WebhookHandler(AbstractEventHandler):
+    """Webhook 处理器 — 将事件 POST 到外部 URL"""
+
+    async def handle(self, event, adapter, config):
+        url = config.get("url")
+        method = config.get("method", "POST")
+        headers = config.get("headers", {})
+        timeout = config.get("timeout", 30)
+        retry_count = config.get("retry_count", 3)
+        response_actions = config.get("response_actions", False)
+
+        # 1. 构建请求体
+        bot = await self.ap.platform_mgr.get_bot_by_uuid(event.bot_uuid)
+        payload = {
+            "event": event.model_dump(),
+            "bot": {
+                "uuid": bot.bot_entity.uuid,
+                "name": bot.bot_entity.name,
+                "adapter": bot.bot_entity.adapter,
+            }
+        }
+
+        # 2. 发送请求（带重试）
+        response = await self._send_with_retry(
+            url, method, headers, payload, timeout, retry_count
+        )
+
+        # 3. 处理响应动作
+        if response_actions and response:
+            await self._execute_response_actions(
+                response, adapter, event
+            )
+
+    async def _execute_response_actions(self, response, adapter, event):
+        """执行响应中的动作列表"""
+        actions = response.get("actions", [])
+        for action in actions:
+            action_type = action.get("type")
+            params = action.get("params", {})
+
+            if action_type == "send_message":
+                chain = MessageChain.model_validate(params.get("message", []))
+                await adapter.send_message(
+                    params["target_type"],
+                    params["target_id"],
+                    chain,
+                )
+            elif action_type == "reply":
+                chain = MessageChain.model_validate(params.get("message", []))
+                await adapter.reply_message(event, chain)
+            elif action_type == "call_platform_api":
+                await adapter.call_platform_api(
+                    params["action"],
+                    params.get("params", {}),
+                )
+            elif action_type == "approve_friend_request":
+                await adapter.approve_friend_request(
+                    params["request_id"],
+                    params.get("approve", True),
+                )
+            # ... 更多动作类型
+```
+
+### 5.5 PluginHandler
+
+将事件分发给插件的 EventListener。
+
+```python
+class PluginHandler(AbstractEventHandler):
+    """Plugin 处理器 — 分发给插件 EventListener"""
+
+    async def handle(self, event, adapter, config):
+        plugin_filter = config.get("plugin_filter", [])
+
+        # 复用现有的插件事件分发机制
+        # 通过 plugin_connector 将事件发送给 Plugin Runtime
+        await self.ap.plugin_connector.emit_event(
+            event=event,
+            adapter=adapter,
+            plugin_filter=plugin_filter,
+        )
+```
+
+## 6. use_pipeline_uuid 迁移
+
+### 6.1 自动迁移
+
+数据库迁移脚本将现有的 `use_pipeline_uuid` 自动转换为 `event_handlers`：
+
+```python
+# 迁移逻辑
+for bot in all_bots:
+    if bot.use_pipeline_uuid and not bot.event_handlers:
+        bot.event_handlers = [
+            {
+                "event_type": "message.received",
+                "handler_type": "pipeline",
+                "handler_config": {
+                    "pipeline_uuid": bot.use_pipeline_uuid
+                },
+                "enabled": True,
+                "priority": 10,
+                "description": "Auto-migrated from use_pipeline_uuid"
+            },
+            {
+                "event_type": "*",
+                "handler_type": "plugin",
+                "handler_config": {},
+                "enabled": True,
+                "priority": -100,
+                "description": "Default plugin handler"
+            }
+        ]
+```
+
+### 6.2 过渡期兼容
+
+在过渡期内，如果 `event_handlers` 为空且 `use_pipeline_uuid` 非空，EventRouter 自动回退到旧行为：
+
+```python
+# EventRouter.route() 中的兼容逻辑
+if not event_handlers and bot.bot_entity.use_pipeline_uuid:
+    # 回退：消息事件走 Pipeline，其他事件走 Plugin
+    if isinstance(event, MessageReceivedEvent):
+        await self.handlers["pipeline"].handle(
+            event, adapter,
+            {"pipeline_uuid": bot.bot_entity.use_pipeline_uuid}
+        )
+    else:
+        await self.handlers["plugin"].handle(event, adapter, {})
+    return
+```
+
+## 7. WebUI 编排面板数据模型
+
+### 7.1 交互设计概要
+
+在 WebUI 的 Bot 管理页面，新增"事件处理器"标签页（或区域），呈现为一个**规则列表**：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  事件处理器                                       [+ 添加规则]  │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─ 规则 1 ─────────────────────────────────── [启用] [删除] ─┐ │
+│  │  事件类型: [message.received    ▾]                         │ │
+│  │  处理器:   [Pipeline           ▾]                         │ │
+│  │  Pipeline: [默认流水线          ▾]                         │ │
+│  │  优先级:   [10]                                           │ │
+│  │  描述:     消息事件使用默认流水线处理                         │ │
+│  └──────────────────────────────────────────────────────────┘ │
+│                                                             │
+│  ┌─ 规则 2 ─────────────────────────────────── [启用] [删除] ─┐ │
+│  │  事件类型: [group.member_joined ▾]                         │ │
+│  │  处理器:   [Agent              ▾]                         │ │
+│  │  Runner:   [local-agent        ▾]                         │ │
+│  │  模型:     [gpt-4o-mini        ▾]                         │ │
+│  │  Prompt:   [有新成员加入...]                                │ │
+│  │  优先级:   [0]                                            │ │
+│  └──────────────────────────────────────────────────────────┘ │
+│                                                             │
+│  ┌─ 规则 3 (兜底) ──────────────────────────── [启用] [删除] ─┐ │
+│  │  事件类型: [*                   ▾]                         │ │
+│  │  处理器:   [Plugin             ▾]                         │ │
+│  │  优先级:   [-100]                                         │ │
+│  └──────────────────────────────────────────────────────────┘ │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 前端数据结构
+
+```typescript
+interface EventHandlerRule {
+  event_type: string;       // 下拉选择，选项从适配器 manifest 的 supported_events 获取
+  handler_type: string;     // "pipeline" | "agent" | "webhook" | "plugin"
+  handler_config: Record<string, any>;  // 根据 handler_type 动态渲染不同的配置表单
+  enabled: boolean;
+  priority: number;
+  description: string;
+}
+
+// Bot 编辑接口扩展
+interface BotConfig {
+  uuid: string;
+  name: string;
+  adapter: string;
+  adapter_config: Record<string, any>;
+  enable: boolean;
+  event_handlers: EventHandlerRule[];  // 新增
+}
+```
+
+### 7.3 事件类型下拉选项
+
+从 Bot 关联的适配器 manifest 中获取 `supported_events`，加上通配符选项：
+
+```
+- message.received
+- message.edited
+- message.deleted
+- message.reaction
+- feedback.received
+- group.member_joined
+- group.member_left
+- group.member_banned
+- group.info_updated
+- friend.request_received
+- friend.added
+- bot.invited_to_group
+- bot.removed_from_group
+- bot.muted
+- bot.unmuted
+- platform.specific
+─────────────────
+- message.*          (所有消息事件)
+- feedback.*         (所有反馈事件)
+- group.*            (所有群组事件)
+- friend.*           (所有好友事件)
+- bot.*              (所有 Bot 事件)
+- *                  (所有事件)
+```
+
+### 7.4 HTTP API
+
+```
+GET    /api/v1/bots/{uuid}/event-handlers         获取 Bot 的事件处理器配置
+PUT    /api/v1/bots/{uuid}/event-handlers         更新 Bot 的事件处理器配置
+GET    /api/v1/adapters/{name}/supported-events    获取适配器支持的事件类型
+GET    /api/v1/adapters/{name}/supported-apis      获取适配器支持的 API
+```

docs/event-based-agents/05-plugin-sdk.md

@@ -0,0 +1,738 @@
+# 插件 SDK 改造
+
+## 1. 概述
+
+插件 SDK 需要配合 EBA 架构进行以下改造：
+
+1. **新事件类型**：将所有通用事件暴露给插件
+2. **新 API**：将新增的平台 API 通过 `LangBotAPIProxy` 暴露给插件
+3. **兼容层**：保证现有插件零修改运行
+4. **通信协议扩展**：新增 action 枚举支持新 API
+
+## 2. 新事件类型暴露
+
+### 2.1 插件事件模型扩展
+
+当前插件 SDK 的事件模型（`api/entities/events.py`）只有消息相关事件。需要新增所有通用事件的插件级包装：
+
+```python
+# api/entities/events.py — 新增事件
+
+# ---- 消息事件（扩展） ----
+
+class MessageEditedReceived(BaseEventModel):
+    """消息被编辑事件"""
+    launcher_type: str
+    launcher_id: typing.Union[int, str]
+    message_id: typing.Union[int, str]
+    editor_id: typing.Union[int, str]
+    new_content: MessageChain
+    chat_type: str  # "private" | "group"
+
+class MessageDeletedReceived(BaseEventModel):
+    """消息被删除/撤回事件"""
+    launcher_type: str
+    launcher_id: typing.Union[int, str]
+    message_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    chat_type: str
+
+class MessageReactionReceived(BaseEventModel):
+    """消息表情回应事件"""
+    launcher_type: str
+    launcher_id: typing.Union[int, str]
+    message_id: typing.Union[int, str]
+    user_id: typing.Union[int, str]
+    reaction: str
+    is_add: bool
+
+# ---- 用户反馈事件 ----
+
+class FeedbackReceived(BaseEventModel):
+    """用户对 Bot 回复提交反馈"""
+    feedback_id: str
+    feedback_type: int  # 1=like, 2=dislike, 3=cancel/remove feedback
+    feedback_content: typing.Optional[str] = None
+    inaccurate_reasons: typing.Optional[list[str]] = None
+    user_id: typing.Optional[str] = None
+    session_id: typing.Optional[str] = None
+    message_id: typing.Optional[str] = None
+    stream_id: typing.Optional[str] = None
+
+# ---- 群组事件 ----
+
+class GroupMemberJoined(BaseEventModel):
+    """新成员加入群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    member_id: typing.Union[int, str]
+    member_name: str
+    inviter_id: typing.Optional[typing.Union[int, str]] = None
+    join_type: typing.Optional[str] = None
+
+class GroupMemberLeft(BaseEventModel):
+    """成员离开群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    member_id: typing.Union[int, str]
+    member_name: str
+    is_kicked: bool = False
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+class GroupMemberBanned(BaseEventModel):
+    """成员被禁言"""
+    group_id: typing.Union[int, str]
+    member_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    duration: typing.Optional[int] = None
+
+class GroupMemberUnbanned(BaseEventModel):
+    """成员被解除禁言"""
+    group_id: typing.Union[int, str]
+    member_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+class GroupInfoUpdated(BaseEventModel):
+    """群组信息被修改"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    changed_fields: list[str] = []
+
+# ---- 好友事件 ----
+
+class FriendRequestReceived(BaseEventModel):
+    """收到好友请求"""
+    request_id: typing.Union[int, str]
+    user_id: typing.Union[int, str]
+    user_name: str
+    message: typing.Optional[str] = None
+
+class FriendAdded(BaseEventModel):
+    """成功添加好友"""
+    user_id: typing.Union[int, str]
+    user_name: str
+
+class FriendRemoved(BaseEventModel):
+    """好友被移除"""
+    user_id: typing.Union[int, str]
+    user_name: str
+
+# ---- Bot 状态事件 ----
+
+class BotInvitedToGroup(BaseEventModel):
+    """Bot 被邀请加入群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    inviter_id: typing.Optional[typing.Union[int, str]] = None
+    request_id: typing.Optional[typing.Union[int, str]] = None
+
+class BotRemovedFromGroup(BaseEventModel):
+    """Bot 被移出群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+class BotMuted(BaseEventModel):
+    """Bot 被禁言"""
+    group_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    duration: typing.Optional[int] = None
+
+class BotUnmuted(BaseEventModel):
+    """Bot 被解除禁言"""
+    group_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+# ---- 平台特有事件 ----
+
+class PlatformSpecificEventReceived(BaseEventModel):
+    """平台特有事件"""
+    adapter_name: str
+    action: str
+    data: dict = {}
+```
+
+### 2.2 EventListener 注册方式
+
+插件的 EventListener 继续使用 `@self.handler(EventType)` 装饰器注册，只是可以注册的事件类型大幅增加：
+
+```python
+class MyEventListener(EventListener):
+    def __init__(self, host):
+        super().__init__(host)
+
+        # 现有方式（继续工作）
+        @self.handler(PersonNormalMessageReceived)
+        async def on_person_message(ctx: EventContext):
+            ...
+
+        # 新事件类型
+        @self.handler(GroupMemberJoined)
+        async def on_member_joined(ctx: EventContext):
+            group_name = ctx.event.group_name
+            member_name = ctx.event.member_name
+            await ctx.reply(MessageChain([
+                Plain(f"欢迎 {member_name} 加入 {group_name}！")
+            ]))
+
+        @self.handler(FriendRequestReceived)
+        async def on_friend_request(ctx: EventContext):
+            # 自动通过好友请求
+            await ctx.approve_friend_request(
+                ctx.event.request_id, approve=True
+            )
+
+        @self.handler(FeedbackReceived)
+        async def on_feedback(ctx: EventContext):
+            if ctx.event.feedback_type == 2:
+                await self.log_warning(
+                    f"用户点踩了回复: {ctx.event.feedback_content or ''}"
+                )
+
+        @self.handler(PlatformSpecificEventReceived)
+        async def on_platform_event(ctx: EventContext):
+            if ctx.event.adapter_name == "telegram" and ctx.event.action == "chat_join_request":
+                ...
+```
+
+## 3. 新 API 暴露
+
+### 3.1 LangBotAPIProxy 扩展
+
+在 `LangBotAPIProxy` 中新增以下方法，插件通过 `self.xxx()` 调用（在 BasePlugin 中继承）：
+
+```python
+class LangBotAPIProxy:
+    # ---- 现有方法（保留） ----
+    # get_langbot_version, get_bots, get_bot_info,
+    # send_message, invoke_llm, get/set/delete_plugin_storage, ...
+
+    # ---- 新增消息 API ----
+
+    async def edit_message(
+        self,
+        bot_uuid: str,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: MessageChain,
+    ) -> None:
+        """编辑已发送的消息"""
+        ...
+
+    async def delete_message(
+        self,
+        bot_uuid: str,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """删除/撤回消息"""
+        ...
+
+    async def forward_message(
+        self,
+        bot_uuid: str,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> dict:
+        """转发消息"""
+        ...
+
+    async def get_message(
+        self,
+        bot_uuid: str,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> dict:
+        """获取指定消息"""
+        ...
+
+    # ---- 新增群组 API ----
+
+    async def get_group_info(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+    ) -> dict:
+        """获取群组信息"""
+        ...
+
+    async def get_group_list(
+        self,
+        bot_uuid: str,
+    ) -> list[dict]:
+        """获取 Bot 加入的群组列表"""
+        ...
+
+    async def get_group_member_list(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+    ) -> list[dict]:
+        """获取群成员列表"""
+        ...
+
+    async def get_group_member_info(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> dict:
+        """获取指定群成员信息"""
+        ...
+
+    async def mute_member(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        """禁言群成员"""
+        ...
+
+    async def unmute_member(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """解除禁言"""
+        ...
+
+    async def kick_member(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """踢出群成员"""
+        ...
+
+    # ---- 新增用户 API ----
+
+    async def get_user_info(
+        self,
+        bot_uuid: str,
+        user_id: typing.Union[int, str],
+    ) -> dict:
+        """获取用户信息"""
+        ...
+
+    async def get_friend_list(
+        self,
+        bot_uuid: str,
+    ) -> list[dict]:
+        """获取好友列表"""
+        ...
+
+    async def approve_friend_request(
+        self,
+        bot_uuid: str,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        """处理好友请求"""
+        ...
+
+    async def approve_group_invite(
+        self,
+        bot_uuid: str,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+    ) -> None:
+        """处理入群邀请"""
+        ...
+
+    # ---- 新增透传 API ----
+
+    async def call_platform_api(
+        self,
+        bot_uuid: str,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """调用适配器特有 API
+
+        Examples:
+            # Telegram: pin 消息
+            result = await self.call_platform_api(
+                bot_uuid, "pin_message",
+                {"chat_id": 123456, "message_id": 789}
+            )
+
+            # Discord: 创建频道
+            result = await self.call_platform_api(
+                bot_uuid, "create_channel",
+                {"guild_id": "...", "name": "new-channel"}
+            )
+        """
+        ...
+
+    # ---- 新增能力查询 API ----
+
+    async def get_supported_events(
+        self,
+        bot_uuid: str,
+    ) -> list[str]:
+        """获取指定 Bot 的适配器支持的事件类型"""
+        ...
+
+    async def get_supported_apis(
+        self,
+        bot_uuid: str,
+    ) -> list[str]:
+        """获取指定 Bot 的适配器支持的 API"""
+        ...
+```
+
+### 3.2 QueryBasedAPIProxy 扩展
+
+在事件处理上下文中（EventContext），通过 `QueryBasedAPIProxy` 新增便捷方法：
+
+```python
+class QueryBasedAPIProxy:
+    # ---- 现有方法（保留） ----
+    # reply, get_bot_uuid, set_query_var, get_query_var,
+    # create_new_conversation, ...
+
+    # ---- 新增便捷方法 ----
+
+    async def edit_message(
+        self,
+        message_id: typing.Union[int, str],
+        new_content: MessageChain,
+    ) -> None:
+        """在当前会话中编辑消息（自动使用当前 bot_uuid 和 chat 信息）"""
+        ...
+
+    async def delete_message(
+        self,
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """在当前会话中删除消息"""
+        ...
+
+    async def approve_friend_request(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        """处理好友请求（上下文中自动获取 bot_uuid）"""
+        ...
+
+    async def approve_group_invite(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+    ) -> None:
+        """处理入群邀请"""
+        ...
+
+    async def get_group_info(self) -> dict:
+        """获取当前群组信息（仅群聊事件中可用）"""
+        ...
+
+    async def get_group_member_list(self) -> list[dict]:
+        """获取当前群组成员列表（仅群聊事件中可用）"""
+        ...
+
+    async def call_platform_api(
+        self,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """调用平台特有 API（自动使用当前 bot_uuid）"""
+        ...
+```
+
+## 4. 兼容层设计
+
+### 4.1 事件兼容层
+
+当 PluginHandler 将新的 `MessageReceivedEvent` 分发给插件时，需要同时生成旧格式事件：
+
+```python
+class PluginEventCompatLayer:
+    """插件事件兼容层
+
+    将新的统一事件转换为旧的插件事件格式，
+    确保监听旧事件类型的插件仍能正常工作。
+    """
+
+    @staticmethod
+    def convert_to_legacy_events(
+        event: Event,
+    ) -> list[BaseEventModel]:
+        """将统一事件转换为旧插件事件列表
+
+        一个统一事件可能生成多个旧插件事件。
+        例如 MessageReceivedEvent 会同时生成：
+        - PersonMessageReceived / GroupMessageReceived（总是生成）
+        - PersonNormalMessageReceived / GroupNormalMessageReceived（非命令时）
+        - PersonCommandSent / GroupCommandSent（命令时）
+        """
+        legacy_events = []
+
+        if isinstance(event, MessageReceivedEvent):
+            if event.chat_type == ChatType.PRIVATE:
+                legacy_events.append(
+                    PersonMessageReceived(
+                        launcher_type="person",
+                        launcher_id=event.chat_id,
+                        sender_id=event.sender.id,
+                        message_event=event.to_legacy_friend_message(),
+                        message_chain=event.message_chain,
+                    )
+                )
+                # 命令检测后还会生成 PersonNormalMessageReceived
+                # 或 PersonCommandSent，在 Pipeline 阶段处理
+            elif event.chat_type == ChatType.GROUP:
+                legacy_events.append(
+                    GroupMessageReceived(
+                        launcher_type="group",
+                        launcher_id=event.chat_id,
+                        sender_id=event.sender.id,
+                        message_event=event.to_legacy_group_message(),
+                        message_chain=event.message_chain,
+                    )
+                )
+
+        # 新事件类型没有旧的对应物，不生成兼容事件
+        # 只有监听了新事件类型的插件才会收到
+
+        return legacy_events
+```
+
+### 4.2 分发流程
+
+```
+统一事件 (MessageReceivedEvent)
+    │
+    ├─→ 转换为旧格式 (PersonMessageReceived / GroupMessageReceived)
+    │   └─→ 分发给监听旧事件类型的插件 EventListener
+    │
+    └─→ 直接分发为新格式 (MessageReceivedEvent → 对应的插件事件)
+        └─→ 分发给监听新事件类型的插件 EventListener
+```
+
+插件 Runtime 在分发事件时检查每个 EventListener 注册的事件类型：
+- 如果注册的是旧类型（`PersonMessageReceived` 等），发送兼容层生成的旧格式事件
+- 如果注册的是新类型（`GroupMemberJoined` 等），发送新格式事件
+- 两者可以共存，同一个插件可以同时监听新旧类型
+
+### 4.3 API 兼容层
+
+现有插件使用的 API 不受影响：
+
+| 现有 API | 新架构行为 |
+|---------|----------|
+| `self.send_message(bot_uuid, target_type, target_id, message_chain)` | 不变，直接调用适配器的 `send_message` |
+| `ctx.reply(message_chain, quote_origin)` | 不变，在 MessageReceivedEvent 上下文中调用适配器的 `reply_message` |
+| `self.get_bots()` | 不变 |
+| `self.get_bot_info(bot_uuid)` | 不变 |
+
+新 API 只是额外新增的方法，不影响现有方法。
+
+## 5. 通信协议扩展
+
+### 5.1 新增 Action 枚举
+
+在 `entities/io/actions/enums.py` 中新增 action：
+
+```python
+class PluginToRuntimeAction(str, Enum):
+    # ---- 现有 actions（保留） ----
+    REGISTER_PLUGIN = "register_plugin"
+    REPLY = "reply"
+    SEND_MESSAGE = "send_message"
+    # ...
+
+    # ---- 新增消息 API ----
+    EDIT_MESSAGE = "edit_message"
+    DELETE_MESSAGE = "delete_message"
+    FORWARD_MESSAGE = "forward_message"
+    GET_MESSAGE = "get_message"
+
+    # ---- 新增群组 API ----
+    GET_GROUP_INFO = "get_group_info"
+    GET_GROUP_LIST = "get_group_list"
+    GET_GROUP_MEMBER_LIST = "get_group_member_list"
+    GET_GROUP_MEMBER_INFO = "get_group_member_info"
+    MUTE_MEMBER = "mute_member"
+    UNMUTE_MEMBER = "unmute_member"
+    KICK_MEMBER = "kick_member"
+
+    # ---- 新增用户 API ----
+    GET_USER_INFO = "get_user_info"
+    GET_FRIEND_LIST = "get_friend_list"
+    APPROVE_FRIEND_REQUEST = "approve_friend_request"
+    APPROVE_GROUP_INVITE = "approve_group_invite"
+
+    # ---- 新增透传 API ----
+    CALL_PLATFORM_API = "call_platform_api"
+
+    # ---- 新增能力查询 ----
+    GET_SUPPORTED_EVENTS = "get_supported_events"
+    GET_SUPPORTED_APIS = "get_supported_apis"
+
+
+class RuntimeToPluginAction(str, Enum):
+    # ---- 现有 actions（保留） ----
+    EMIT_EVENT = "emit_event"
+    # ...
+    # EMIT_EVENT 的 data 结构扩展以支持新事件类型
+```
+
+### 5.2 新增 Action 的请求/响应格式
+
+以 `EDIT_MESSAGE` 为例：
+
+```json
+// 请求 (Plugin → Runtime)
+{
+    "action": "edit_message",
+    "seq_id": 12345,
+    "data": {
+        "bot_uuid": "...",
+        "chat_type": "group",
+        "chat_id": "123456",
+        "message_id": "789",
+        "new_content": [
+            { "type": "Plain", "text": "edited message" }
+        ]
+    }
+}
+
+// 响应 (Runtime → Plugin)
+{
+    "seq_id": 12345,
+    "code": 0,
+    "message": "ok",
+    "data": {}
+}
+```
+
+以 `GET_GROUP_MEMBER_LIST` 为例：
+
+```json
+// 请求
+{
+    "action": "get_group_member_list",
+    "seq_id": 12346,
+    "data": {
+        "bot_uuid": "...",
+        "group_id": "123456"
+    }
+}
+
+// 响应
+{
+    "seq_id": 12346,
+    "code": 0,
+    "message": "ok",
+    "data": {
+        "members": [
+            {
+                "user": { "id": "111", "nickname": "Alice" },
+                "group_id": "123456",
+                "role": "admin",
+                "display_name": "管理员Alice"
+            },
+            ...
+        ]
+    }
+}
+```
+
+以 `CALL_PLATFORM_API` 为例：
+
+```json
+// 请求
+{
+    "action": "call_platform_api",
+    "seq_id": 12347,
+    "data": {
+        "bot_uuid": "...",
+        "action": "pin_message",
+        "params": {
+            "chat_id": "123456",
+            "message_id": "789"
+        }
+    }
+}
+
+// 响应
+{
+    "seq_id": 12347,
+    "code": 0,
+    "message": "ok",
+    "data": {
+        "result": { ... }
+    }
+}
+```
+
+### 5.3 LangBot 侧 Handler 实现
+
+在 `ControlConnectionHandler`（LangBot → Runtime 侧）和 `PluginConnectionHandler`（Runtime → Plugin 侧）中新增对应的 action 处理逻辑：
+
+```python
+# PluginConnectionHandler 中新增
+async def _handle_edit_message(self, data):
+    bot_uuid = data["bot_uuid"]
+    bot = await self.ap.platform_mgr.get_bot_by_uuid(bot_uuid)
+    await bot.adapter.edit_message(
+        chat_type=data["chat_type"],
+        chat_id=data["chat_id"],
+        message_id=data["message_id"],
+        new_content=MessageChain.model_validate(data["new_content"]),
+    )
+    return {}
+
+async def _handle_call_platform_api(self, data):
+    bot_uuid = data["bot_uuid"]
+    bot = await self.ap.platform_mgr.get_bot_by_uuid(bot_uuid)
+    result = await bot.adapter.call_platform_api(
+        action=data["action"],
+        params=data.get("params", {}),
+    )
+    return {"result": result}
+```
+
+## 6. 插件开发者迁移指南
+
+### 6.1 无需迁移（零修改运行）
+
+以下场景的现有插件**不需要任何修改**：
+
+- 使用 `PersonNormalMessageReceived` / `GroupNormalMessageReceived` 监听消息
+- 使用 `PersonCommandSent` / `GroupCommandSent` 处理命令
+- 使用 `ctx.reply()` 回复消息
+- 使用 `self.send_message()` 主动发消息
+- 使用 LLM / 存储 / RAG 等现有 API
+
+### 6.2 推荐迁移（获得新能力）
+
+如果插件希望利用新功能，可以：
+
+1. **监听新事件类型**：在 EventListener 中注册新事件类型的 handler
+2. **使用新 API**：调用 `self.edit_message()`, `self.get_group_info()` 等
+3. **使用透传 API**：调用 `self.call_platform_api()` 使用平台特有功能
+
+### 6.3 SDK 版本号
+
+新功能通过提升 SDK minor 版本发布：
+
+- 现有版本：`langbot-plugin-sdk >= x.y.z`
+- 新版本：`langbot-plugin-sdk >= x.(y+1).0`
+
+插件的 `manifest.yaml` 中的 `min_sdk_version` 决定是否能使用新 API。使用旧 SDK 版本的插件在新 LangBot 上正常运行（兼容层保证），只是无法调用新 API。

docs/event-based-agents/06-migration-plan.md

@@ -0,0 +1,429 @@
+# 分阶段迁移计划
+
+## 1. 概述
+
+EBA 架构涉及 langbot-plugin-sdk、LangBot 后端、LangBot 前端、文档和示例插件等多个仓库的改动。为降低风险、保证系统稳定性，采用分阶段渐进式迁移策略。
+
+### 1.1 阶段总览
+
+| 阶段 | 名称 | 范围 | 依赖 |
+|------|------|------|------|
+| Phase 1 | SDK 实体层 | langbot-plugin-sdk | 无 |
+| Phase 2 | 适配器重构 | LangBot 后端 | Phase 1 |
+| Phase 3 | 核心系统 | LangBot 后端 | Phase 2 |
+| Phase 4 | 插件 SDK 集成 | langbot-plugin-sdk + LangBot | Phase 3 |
+| Phase 5 | WebUI 编排面板 | LangBot 前端 | Phase 3 |
+| Phase 6 | 文档与示例 | langbot-wiki + langbot-plugin-demo | Phase 4, 5 |
+
+### 1.2 核心原则
+
+- **每个阶段结束后系统可运行**：任何阶段完成后，现有功能不受影响
+- **向后兼容贯穿全程**：旧接口在整个迁移期间保持可用
+- **先 SDK 后实现**：先定义好接口和模型，再做具体实现
+- **先核心适配器后边缘**：优先迁移用户量大的适配器
+
+---
+
+## 2. Phase 1：SDK 实体层
+
+**目标**：在 langbot-plugin-sdk 中定义新的事件体系、通用实体、API 接口和适配器基类。
+
+**仓库**：`langbot-plugin-sdk`
+
+### 2.1 任务清单
+
+| # | 任务 | 文件/模块 | 说明 |
+|---|------|----------|------|
+| 1.1 | 定义通用事件基类层次 | `api/entities/builtin/platform/events.py` | 新增 `MessageReceivedEvent`, `MessageEditedEvent`, `GroupMemberJoinedEvent` 等，保留现有 `FriendMessage`/`GroupMessage` |
+| 1.2 | 定义平台特有事件基类 | `api/entities/builtin/platform/events.py` | 新增 `PlatformSpecificEvent` |
+| 1.3 | 扩展通用实体 | `api/entities/builtin/platform/entities.py` | 新增 `User`（统一 Friend/GroupMember 的基础）、`Channel` 等，保留现有实体 |
+| 1.4 | 清理消息组件 | `api/entities/builtin/platform/message.py` | 将 `WeChatMiniPrograms` 等 WeChat 特有组件标记为 platform-specific，不再作为通用组件 |
+| 1.5 | 定义新适配器基类 | `api/definition/abstract/platform/adapter.py` | 新增 `AbstractPlatformAdapter`（继承现有 `AbstractMessagePlatformAdapter` 并扩展通用 API 方法），保留旧基类 |
+| 1.6 | 定义 API 能力声明 | `api/definition/abstract/platform/capabilities.py`（新文件） | `AdapterCapabilities` 数据类，声明适配器支持的事件和 API |
+| 1.7 | 定义 `NotSupportedError` | `api/entities/builtin/platform/errors.py`（新文件） | 可选 API 未实现时抛出的异常 |
+
+### 2.2 关键设计约束
+
+- 所有新增定义以**新增文件或新增类**的方式引入，**不修改**现有类的字段和方法签名
+- 现有 `AbstractMessagePlatformAdapter` 保留不动，新基类 `AbstractPlatformAdapter` 继承它
+- 新事件类与旧事件类并存，通过 `event_type` 字段（命名空间字符串）区分
+
+### 2.3 验收标准
+
+- [ ] 所有新增类可正常 import 且通过类型检查
+- [ ] 现有 `FriendMessage`, `GroupMessage`, `AbstractMessagePlatformAdapter` 等类行为不变
+- [ ] 新增单元测试覆盖事件序列化/反序列化、实体构造
+- [ ] SDK 版本号 minor bump（如 `0.x.0` → `0.x+1.0`）
+
+---
+
+## 3. Phase 2：适配器重构
+
+**目标**：将现有单文件适配器迁移到独立目录结构，实现新事件监听和通用 API。
+
+**仓库**：`LangBot`（后端）
+
+### 3.1 适配器迁移优先级
+
+根据用户量和代表性，建议按以下顺序迁移：
+
+| 优先级 | 适配器 | 理由 |
+|--------|--------|------|
+| P0 | **Telegram** | 用户量大，API 最完善，适合作为参考实现 |
+| P0 | **Discord** | 国际用户主要平台，事件类型丰富 |
+| P1 | **aiocqhttp**（OneBot v11） | 国内 QQ 用户主要适配器 |
+| P1 | **Satori** | 通用协议适配器，覆盖多个平台 |
+| P2 | **Lark** / **DingTalk** / **Slack** | 企业平台，用户量中等 |
+| P2 | **qqofficial** / **WeChat 系列** | 国内用户 |
+| P3 | **Kook** / **LINE** / **WeCom 系列** | 用户量较小 |
+| P3 | **WebSocket** | 内置适配器，相对简单 |
+| P4 | **legacy/*** | 遗留适配器，按需决定是否迁移或废弃 |
+
+### 3.2 单个适配器迁移步骤（以 Telegram 为例）
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 2.1 | 创建目录结构 | `pkg/platform/adapters/telegram/` 下创建 `__init__.py`, `adapter.py`, `event_converter.py`, `message_converter.py`, `api_impl.py`, `types.py`, `manifest.yaml` |
+| 2.2 | 迁移消息转换器 | 将 `TelegramMessageConverter` 从 `sources/telegram.py` 搬到 `adapters/telegram/message_converter.py`，逻辑不变 |
+| 2.3 | 重写事件转换器 | 新的 `TelegramEventConverter` 支持将 Telegram Update 转换为所有通用事件类型（不只是消息），不支持的事件转为 `PlatformSpecificEvent` |
+| 2.4 | 实现通用 API | 在 `api_impl.py` 中实现 `edit_message`, `delete_message`, `get_group_info` 等 Telegram 支持的通用 API |
+| 2.5 | 实现透传 API | 在 `adapter.py` 中实现 `call_platform_api`，将 action 映射到 Telegram Bot API 调用 |
+| 2.6 | 声明能力 | 在 `manifest.yaml` 或适配器类中声明支持的事件和 API 列表 |
+| 2.7 | 新建 Adapter 主类 | `TelegramAdapter` 继承 `AbstractPlatformAdapter`（新基类），委托各模块实现 |
+| 2.8 | 更新 manifest.yaml | 更新 `execution.python.path` 指向新位置 |
+| 2.9 | 验证 | 确保新适配器通过现有消息收发流程的测试 |
+
+### 3.3 基础设施任务
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 2.A | 创建 `adapters/_base/` | 将 SDK 中新基类的运行时辅助代码放在此处（如事件分发辅助函数） |
+| 2.B | 更新 ComponentDiscovery | 使 `discover_blueprint` 支持扫描 `adapters/` 子目录中的 YAML |
+| 2.C | 更新 `templates/components.yaml` | 将 `fromDirs` 从 `pkg/platform/sources/` 改为 `pkg/platform/adapters/`（过渡期两个都扫描） |
+| 2.D | 保留旧 sources/ | 过渡期不删除旧文件，通过 manifest 的 `deprecated: true` 标记 |
+
+### 3.4 验收标准
+
+- [ ] 已迁移的适配器在新目录结构下正常启动和收发消息
+- [ ] 新事件（如 `message.edited`）在支持的平台上正确触发
+- [ ] 通用 API（如 `edit_message`）在支持的平台上正确执行
+- [ ] 未迁移的适配器（仍在 `sources/`）继续正常工作
+- [ ] ComponentDiscovery 同时扫描新旧目录
+
+---
+
+## 4. Phase 3：核心系统
+
+**目标**：实现 EventBus、EventRouter 和事件处理器框架，将事件从适配器分发到不同的处理器。
+
+**仓库**：`LangBot`（后端）
+
+### 4.1 任务清单
+
+| # | 任务 | 文件/模块 | 说明 |
+|---|------|----------|------|
+| 3.1 | 实现 EventBus | `pkg/platform/event_bus.py`（新文件） | 事件总线：接收适配器事件，进行日志记录，分发给 EventRouter |
+| 3.2 | 实现 EventRouter | `pkg/platform/event_router.py`（新文件） | 事件路由引擎：读取 Bot 的 `event_handlers` 配置，匹配事件类型，分发到对应 Handler |
+| 3.3 | 实现 PipelineHandler | `pkg/platform/handlers/pipeline_handler.py` | 将 `message.received` 事件转为现有 Query，进入 Pipeline 流水线 |
+| 3.4 | 实现 AgentHandler | `pkg/platform/handlers/agent_handler.py` | 直接调用 RequestRunner 处理事件，不经过 Pipeline 多 Stage 流程 |
+| 3.5 | 实现 WebhookHandler | `pkg/platform/handlers/webhook_handler.py` | 将事件 POST 到外部 URL，解析响应执行动作（重构现有 WebhookPusher） |
+| 3.6 | 实现 PluginHandler | `pkg/platform/handlers/plugin_handler.py` | 将事件分发给插件 EventListener（复用现有 plugin_connector 机制） |
+| 3.7 | Bot 实体扩展 | `pkg/entity/persistence/bot.py` | 新增 `event_handlers` JSON 字段 |
+| 3.8 | 数据库迁移 | `pkg/persistence/migrations/` | 新增迁移脚本：添加 `event_handlers` 列，将现有 `use_pipeline_uuid` 数据迁移为 `event_handlers` 格式 |
+| 3.9 | 重构 RuntimeBot | `pkg/platform/botmgr.py` | 将 `initialize()` 中硬编码的 `on_friend_message`/`on_group_message` 回调替换为通过 EventBus 分发所有事件 |
+| 3.10 | 重构 MessageAggregator | `pkg/pipeline/aggregator.py` | 从 RuntimeBot 解耦，作为 PipelineHandler 的内部机制（只对 `message.received` 事件生效） |
+| 3.11 | Agent Handler 中 RequestRunner 解耦 | `pkg/provider/runner.py` + handlers | RequestRunner 需要能独立于 Pipeline Stage 运行，为 Agent Handler 提供轻量调用路径 |
+| 3.12 | HTTP API 扩展 | `pkg/api/http/controller/` | 新增/更新 Bot API 端点以支持 `event_handlers` 的 CRUD |
+
+### 4.2 数据迁移策略
+
+现有 Bot 表有 `use_pipeline_uuid` 字段，需要自动迁移为 `event_handlers`：
+
+```python
+# 迁移逻辑伪代码
+for bot in all_bots:
+    if bot.use_pipeline_uuid:
+        bot.event_handlers = [
+            {
+                "event_type": "message.received",
+                "handler_type": "pipeline",
+                "handler_config": {
+                    "pipeline_uuid": bot.use_pipeline_uuid
+                }
+            }
+        ]
+    else:
+        bot.event_handlers = []
+```
+
+### 4.3 RuntimeBot 重构要点
+
+当前 `RuntimeBot.initialize()` 硬编码注册两个回调：
+
+```python
+# 现有代码 (botmgr.py)
+self.adapter.register_listener(FriendMessage, on_friend_message)
+self.adapter.register_listener(GroupMessage, on_group_message)
+```
+
+重构后改为注册通用事件回调：
+
+```python
+# 新代码
+async def on_event(event: Event, adapter: AbstractPlatformAdapter):
+    await self.event_bus.emit(
+        bot_uuid=self.bot_entity.uuid,
+        event=event,
+        adapter=adapter,
+    )
+
+# 注册所有事件类型的统一回调
+self.adapter.register_listener(Event, on_event)
+```
+
+EventBus 接收事件后，调用 EventRouter 按配置分发。
+
+### 4.4 事件处理器执行流程
+
+```
+EventBus.emit(bot_uuid, event, adapter)
+    │
+    ▼
+EventRouter.route(bot_uuid, event)
+    │ 查询 bot.event_handlers 配置
+    │ 匹配 event_type（精确匹配 > 通配符 *）
+    ▼
+匹配到的 Handler(s)
+    │
+    ├── PipelineHandler.handle(event, adapter)
+    │   │ 仅支持 message.received
+    │   │ 构造 Query → MessageAggregator → QueryPool → Pipeline
+    │   └── 沿用现有完整流水线机制
+    │
+    ├── AgentHandler.handle(event, adapter)
+    │   │ 根据 handler_config 选择 RequestRunner
+    │   │ 直接调用 runner.run() 处理事件
+    │   └── 将结果通过 adapter API 回复
+    │
+    ├── WebhookHandler.handle(event, adapter)
+    │   │ 序列化事件为 JSON
+    │   │ POST 到 handler_config.url
+    │   └── 解析响应，执行动作（回复消息、调用 API 等）
+    │
+    └── PluginHandler.handle(event, adapter)
+        │ 通过 plugin_connector 分发给插件
+        └── 插件 EventListener 处理
+```
+
+### 4.5 验收标准
+
+- [ ] `message.received` 事件通过 PipelineHandler 正确进入现有 Pipeline（与旧行为一致）
+- [ ] 新增事件（如 `group.member_joined`）能通过 PluginHandler 分发给插件
+- [ ] AgentHandler 能直接调用 RequestRunner（至少 `local-agent`）处理事件并回复
+- [ ] WebhookHandler 能将事件 POST 到外部 URL
+- [ ] 数据库迁移正确执行，`use_pipeline_uuid` 数据迁移到 `event_handlers`
+- [ ] 现有 Bot 在不修改配置的情况下行为不变（自动迁移保证）
+
+---
+
+## 5. Phase 4：插件 SDK 集成
+
+**目标**：将新事件和 API 通过插件 SDK 暴露给插件开发者，同时实现兼容层。
+
+**仓库**：`langbot-plugin-sdk` + `LangBot`
+
+### 5.1 任务清单
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 4.1 | 新增插件事件包装 | 在 `api/entities/events.py` 中为每个通用事件新增插件级事件类（如 `MessageEditedReceived`, `MemberJoinedReceived`） |
+| 4.2 | 兼容层实现 | `PersonMessageReceived` / `GroupMessageReceived` 由新的 `MessageReceivedEvent` 自动生成，旧事件作为新事件的 alias |
+| 4.3 | 新 API 暴露 | 在 `LangBotAPIProxy` 中新增方法：`edit_message`, `delete_message`, `get_group_info`, `get_user_info`, `call_platform_api` 等 |
+| 4.4 | 通信协议扩展 | 在 `entities/io/actions/enums.py` 中新增 action 枚举（如 `EDIT_MESSAGE`, `DELETE_MESSAGE`, `GET_GROUP_INFO`, `CALL_PLATFORM_API`） |
+| 4.5 | Runtime Handler 扩展 | 在 PluginConnectionHandler / ControlConnectionHandler 中添加新 action 的处理逻辑 |
+| 4.6 | EventListener 扩展 | 确保 `@handler()` 装饰器支持注册新事件类型 |
+| 4.7 | QueryBasedAPI 扩展 | 在 `QueryBasedAPIProxy` 中新增事件上下文相关的 API（如 `get_event_source_adapter`） |
+
+### 5.2 兼容层详细设计
+
+```
+新事件系统                         旧事件系统（兼容层）
+─────────────                    ─────────────────
+MessageReceivedEvent             ┌→ PersonMessageReceived (chat_type == "private")
+  (chat_type: "private"|"group") ┤
+                                 └→ GroupMessageReceived  (chat_type == "group")
+```
+
+**实现方式**：在 RuntimeEventDispatcher 中，当分发 `MessageReceivedEvent` 给插件时，同时生成对应的旧事件类实例。插件可以用新事件类或旧事件类注册 handler，都能收到。
+
+### 5.3 验收标准
+
+- [ ] 现有插件（使用旧事件和 API）无需修改即可运行
+- [ ] 新插件可以使用新事件类型（如 `MemberJoinedReceived`）注册 handler
+- [ ] 新 API（如 `edit_message`）可通过 `self.edit_message()` 或 `event_context.edit_message()` 调用
+- [ ] 透传 API `call_platform_api` 可正常调用适配器特有功能
+- [ ] 所有新 action 的通信协议正确工作（stdio / WebSocket）
+
+---
+
+## 6. Phase 5：WebUI 编排面板
+
+**目标**：在 WebUI 的 Bot 管理页面实现事件处理器的可视化编排。
+
+**仓库**：`LangBot`（前端 `web/`）
+
+### 6.1 任务清单
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 5.1 | Bot 编辑页面扩展 | 在 Bot 编辑页面新增「事件处理」面板 |
+| 5.2 | 事件处理器列表组件 | 可视化展示当前 Bot 的 `event_handlers` 列表，支持增删改排序 |
+| 5.3 | 事件类型选择器 | 下拉选择事件类型（命名空间分组展示），支持通配符 `*` |
+| 5.4 | Handler 类型选择与配置 | 选择 handler 类型后展示对应的配置表单（Pipeline 选择器、Runner 选择器、Webhook URL 等） |
+| 5.5 | Pipeline Handler 配置 | 复用现有的 Pipeline 选择 UI（从现有 `use_pipeline_uuid` 选择器迁移） |
+| 5.6 | Agent Handler 配置 | Runner 选择器（local-agent / dify / n8n / coze 等）+ Runner 参数配置表单 |
+| 5.7 | Webhook Handler 配置 | URL 输入、认证方式选择、Header 配置 |
+| 5.8 | Plugin Handler 配置 | 通常无需额外配置，分发给所有匹配的插件 EventListener |
+| 5.9 | HTTP API 对接 | 前端调用后端 API 保存/读取 `event_handlers` 配置 |
+| 5.10 | 迁移提示 | 对于从旧版本升级的用户，如果检测到 `use_pipeline_uuid` 已自动迁移，展示提示说明 |
+
+### 6.2 UI 交互设计概要
+
+```
+┌─ Bot 编辑页面 ─────────────────────────────────────┐
+│                                                     │
+│  基本信息  │  适配器配置  │  ★ 事件处理  │           │
+│                                                     │
+│  ┌─ 事件处理器列表 ────────────────────────────┐    │
+│  │                                              │    │
+│  │  ① message.received → Pipeline: "主流水线"   │    │
+│  │     [编辑] [删除]                            │    │
+│  │                                              │    │
+│  │  ② group.member_joined → Agent: local-agent  │    │
+│  │     [编辑] [删除]                            │    │
+│  │                                              │    │
+│  │  ③ * (默认) → Plugin                         │    │
+│  │     [编辑] [删除]                            │    │
+│  │                                              │    │
+│  │  [+ 添加事件处理器]                           │    │
+│  │                                              │    │
+│  └──────────────────────────────────────────────┘    │
+│                                                     │
+│                              [保存]  [取消]          │
+└─────────────────────────────────────────────────────┘
+```
+
+### 6.3 验收标准
+
+- [ ] 用户可以在 WebUI 上为 Bot 添加/编辑/删除事件处理器
+- [ ] 四种 Handler 类型均有对应的配置表单
+- [ ] 配置保存后正确写入数据库 `event_handlers` 字段
+- [ ] 旧版本升级后，自动迁移的配置在 UI 上正确展示
+- [ ] Pipeline Handler 的行为与旧的 `use_pipeline_uuid` 完全一致
+
+---
+
+## 7. Phase 6：文档与示例
+
+**目标**：更新所有面向开发者的文档和示例。
+
+**仓库**：`langbot-wiki`, `langbot-plugin-demo`
+
+### 7.1 任务清单
+
+| # | 任务 | 仓库 | 说明 |
+|---|------|------|------|
+| 6.1 | EBA 架构概览文档 | langbot-wiki | 面向用户的新架构说明 |
+| 6.2 | 适配器开发指南更新 | langbot-wiki | 如何开发一个新的适配器（新目录结构、新基类、事件转换等） |
+| 6.3 | 插件开发指南更新 | langbot-wiki | 新事件类型、新 API 的使用说明 |
+| 6.4 | 插件迁移指南 | langbot-wiki | 现有插件如何迁移到新事件/API（如果需要使用新能力） |
+| 6.5 | 事件处理器配置指南 | langbot-wiki | WebUI 上如何配置事件处理器 |
+| 6.6 | 示例插件更新 | langbot-plugin-demo | HelloPlugin 增加新事件监听示例、新 API 调用示例 |
+| 6.7 | 新示例插件 | langbot-plugin-demo | 新建一个示例展示非消息事件处理（如入群欢迎） |
+
+---
+
+## 8. 风险评估与缓解
+
+### 8.1 技术风险
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| 适配器迁移中断现有功能 | 高 | 中 | 新旧目录并存，ComponentDiscovery 同时扫描两个目录，逐个适配器迁移验证 |
+| 事件模型不兼容导致插件崩溃 | 高 | 低 | 兼容层保证旧事件类型继续工作，新增类不修改旧类 |
+| 数据库迁移失败 | 高 | 低 | 迁移脚本做前置校验，`use_pipeline_uuid` 在过渡期保留不删除 |
+| RequestRunner 解耦破坏 Pipeline | 高 | 中 | Agent Handler 调用 Runner 的路径独立于 Pipeline，不修改现有 Pipeline Stage 中的 Runner 调用逻辑 |
+| 性能回退（EventBus 额外开销） | 中 | 低 | EventBus 在进程内同步分发，无额外序列化/网络开销 |
+| 各平台事件差异大难以统一 | 中 | 中 | 通用事件只抽象最大公约数字段，差异部分保留在 `source_platform_object`；不支持的事件走 `PlatformSpecificEvent` |
+
+### 8.2 兼容性风险
+
+| 风险 | 缓解措施 |
+|------|----------|
+| 现有插件使用旧事件类 | 兼容层自动将新事件转为旧事件分发，两种事件类都能注册 handler |
+| 现有插件调用 `reply()` / `send_message()` | 这两个 API 保持不变，只是底层实现可能微调 |
+| 第三方基于 `AbstractMessagePlatformAdapter` 开发的适配器 | 旧基类保留，新基类继承旧基类，第三方适配器无需立即迁移 |
+| 用户自定义 Pipeline 配置 | Pipeline 机制完整保留，PipelineHandler 只是入口变了（从 RuntimeBot 硬编码变为 EventRouter 配置） |
+
+### 8.3 回滚策略
+
+每个 Phase 独立可回滚：
+
+- **Phase 1**（SDK 新增类）：删除新增文件，回退 SDK 版本号
+- **Phase 2**（适配器目录）：恢复 `components.yaml` 的 `fromDirs` 指向旧目录，旧 sources/ 未删除
+- **Phase 3**（核心系统）：回退数据库迁移，恢复 RuntimeBot 旧的硬编码回调
+- **Phase 4**（插件集成）：回退 SDK 版本，插件使用旧版 SDK
+- **Phase 5**（WebUI）：前端回退，Bot 编辑页面隐藏事件处理面板
+
+---
+
+## 9. 里程碑与时间线建议
+
+| 里程碑 | 阶段 | 预期产出 |
+|--------|------|----------|
+| M1 | Phase 1 完成 | SDK 新版本发布，包含新事件/实体/基类定义 |
+| M2 | Phase 2 首批适配器（Telegram + Discord） | 两个参考实现，验证目录结构和事件/API 体系 |
+| M3 | Phase 3 核心系统 | EventBus + EventRouter + 四种 Handler 可用 |
+| M4 | Phase 2 剩余适配器 | 所有活跃适配器迁移完成 |
+| M5 | Phase 4 插件集成 | 新 SDK 发布，插件可使用新事件和 API |
+| M6 | Phase 5 WebUI | 事件处理器编排面板上线 |
+| M7 | Phase 6 文档 | 开发者文档和示例更新完毕 |
+
+建议 M1-M3 作为第一个大版本发布（如 v5.0），M4-M7 在后续小版本迭代中完成。
+
+---
+
+## 10. 开发指引
+
+### 10.1 分支策略
+
+建议在主仓库创建 `feature/eba` 长期特性分支，各 Phase 在子分支上开发后合入特性分支：
+
+```
+main
+  └── feature/eba
+        ├── feature/eba-sdk-entities      (Phase 1)
+        ├── feature/eba-adapter-telegram   (Phase 2)
+        ├── feature/eba-adapter-discord    (Phase 2)
+        ├── feature/eba-core-system        (Phase 3)
+        ├── feature/eba-plugin-sdk         (Phase 4)
+        └── feature/eba-webui              (Phase 5)
+```
+
+### 10.2 测试策略
+
+| 层次 | 测试内容 | 工具 |
+|------|----------|------|
+| 单元测试 | 事件序列化/反序列化、实体构造、API 调用 mock | pytest |
+| 集成测试 | EventBus → EventRouter → Handler 全链路 | pytest + asyncio |
+| 适配器测试 | 各适配器的事件转换、消息转换、API 调用 | pytest + mock SDK |
+| 端到端测试 | 从模拟平台事件到完整处理流程 | staging 环境 |
+| 插件兼容性测试 | 旧插件在新系统下的行为 | langbot-plugin-demo |
+
+### 10.3 代码审查关注点
+
+- 新增代码是否影响现有行为
+- 兼容层是否正确映射所有旧事件/API 场景
+- 数据库迁移是否可逆
+- 新 API 的错误处理（`NotSupportedError`）是否一致
+- 事件模型的序列化在 stdio/WebSocket 通信中是否正确

docs/event-based-agents/adapters/00-index.md

@@ -0,0 +1,37 @@
+# EBA Adapter Migration Records
+
+This directory records adapter-level migration details for the Event-Based Agents architecture. Each adapter document should be kept close to the implementation and must answer four questions:
+
+1. What changed in the adapter structure.
+2. Which configuration fields are required.
+3. Which events and APIs are supported.
+4. What has been verified end to end.
+
+## Adapter Documents
+
+General acceptance checklist: [EBA Adapter Acceptance Checklist](./acceptance-checklist.md)
+
+Current acceptance report: [EBA Adapter Acceptance Report](./acceptance-report.md)
+
+| Adapter | Status | Document |
+|---------|--------|----------|
+| Telegram | Migrated; partial plugin E2E, real UI inbound image/file verified | [Telegram](./telegram.md) |
+| Discord | Migrated; partial plugin E2E, media-inbound gaps remain | [Discord](./discord.md) |
+| OneBot v11 / aiocqhttp | Migrated; Matcha UI plus protocol-level multi-component coverage | [OneBot v11 / aiocqhttp](./aiocqhttp.md) |
+| DingTalk | Migrated; partial plugin E2E, real UI inbound image/file verified; group gap remains | [DingTalk](./dingtalk.md) |
+| Lark / Feishu | Migrated; partial live text E2E, media-inbound gap remains | [Lark / Feishu](./lark.md) |
+| WeCom | Migrated; private text plugin E2E verified, media/group gaps remain | [WeCom](./wecom.md) |
+| WeComBot | Migrated; private text and outbound/API plugin E2E verified, feedback/group gaps remain | [WeComBot](./wecombot.md) |
+| Official Account | Migrated; private text plugin E2E verified, proactive outbound not supported | [Official Account](./officialaccount.md) |
+
+## Documentation Checklist
+
+When migrating a new adapter, add one document here with:
+
+- Configuration table matching the adapter manifest.
+- Supported event list.
+- Supported common API list.
+- Supported `call_platform_api` action list.
+- Known unsupported APIs and the reason.
+- Live test notes, including platform, channel type, destructive operations, and residual risks.
+- A clear distinction between real UI inbound media, protocol-level injected inbound media, and bot outbound media.

docs/event-based-agents/adapters/acceptance-checklist.md

@@ -0,0 +1,208 @@
+# EBA Adapter Acceptance Checklist
+
+This checklist is the architecture-level acceptance standard for every Event-Based Agents platform adapter. It is not platform-specific. Adapter migration is not complete until the adapter has a written result against this checklist.
+
+## Evidence Levels
+
+Use these evidence levels consistently in adapter records:
+
+| Level | Meaning | Can Mark Complete |
+|-------|---------|-------------------|
+| `plugin-e2e-ui` | Real SDK plugin running through standalone runtime, LangBot core, the migrated adapter, and a real platform/simulator UI action. | Yes |
+| `plugin-e2e-protocol` | Real SDK plugin running through standalone runtime, LangBot core, and the migrated adapter from a protocol-boundary event injection, such as a OneBot reverse WebSocket event. | Partial; must not be claimed as UI coverage |
+| `plugin-e2e-outbound` | Real SDK plugin calls an API and the bot output is visible in the real platform/simulator UI. | Yes for send/API coverage only |
+| `adapter-live` | Direct adapter probe connected to a real or simulator platform endpoint, bypassing plugin runtime. | No, auxiliary only |
+| `unit` | Unit/API-shape tests with mocked platform SDK objects or mocked APIs. | No, auxiliary only |
+| `not-supported` | Platform protocol or SDK has no equivalent capability. Must include reason and source. | Yes, as explicitly unsupported |
+| `blocked` | Intended capability could not be verified because of credentials, permissions, endpoint gaps, or simulator gaps. | No |
+
+The primary acceptance path must be `plugin-e2e-ui` for inbound UI-triggered behavior and `plugin-e2e-outbound` for bot send/API behavior. `adapter-live`, `plugin-e2e-protocol`, and `unit` tests are useful, but they must be labelled precisely.
+
+## Required Architecture Path
+
+Every adapter must prove this full path:
+
+```text
+Real platform / simulator UI
+  -> platform SDK native event
+  -> adapter event converter
+  -> unified EBA event/entity/message types
+  -> LangBot core event dispatch
+  -> standalone SDK runtime
+  -> real test plugin listener
+  -> plugin calls platform APIs through SDK
+  -> LangBot core API dispatch
+  -> adapter API implementation
+  -> real platform / simulator UI
+```
+
+The test plugin must record JSONL evidence containing:
+
+- event class and `event.type`
+- `bot_uuid` and `adapter_name` as received by the plugin
+- adapter name
+- chat type and chat ID
+- sender/user/group IDs with secrets redacted
+- message component list for received messages
+- API action name, input summary, result or error
+- raw unsupported/blocked reason when an item is skipped
+
+## Required Message Receive Tests
+
+For every adapter, inbound message conversion must be tested through `plugin-e2e-ui` for each component the platform can receive. If a protocol-level injection is used, label it `plugin-e2e-protocol`; it proves the adapter/core/plugin path, but it does not prove that the user-facing platform UI can send that component. If the platform UI/simulator cannot create a component, record it as `blocked` with the endpoint limitation.
+
+| Component | Required Receive Assertion |
+|-----------|----------------------------|
+| `Source` | Message ID and timestamp are present and stable enough for reply/get/delete APIs. |
+| `Plain` | Text is preserved exactly, including spaces and multi-line content. |
+| `At` | Mentioned user ID is converted to common `At.target`. |
+| `AtAll` | Broadcast mention is converted to common `AtAll`, if platform supports it. |
+| `Image` | Image ID, URL, path, or base64 is represented without leaking platform-native segment shape. |
+| `Voice` | Voice/audio component is represented as `Voice` when the platform exposes it. |
+| `File` | File name, ID/URL, and size are represented as `File` when available. |
+| `Quote` | Reply/quote source ID and origin content are represented when the platform exposes it. |
+| `Face` | Native emoji/sticker/dice/rps-like components are represented as `Face` or documented as platform-specific. |
+| `Forward` | Merged/forwarded messages are represented as `Forward` when the platform exposes structured content. |
+| `Unknown` | Unsupported native segments become `Unknown` or `PlatformSpecificEvent` data, not crashes. |
+| Mixed chain | A message containing multiple component types preserves order. |
+
+The plugin must subscribe to `MessageReceivedEvent` and assert that `message_chain` contains common `langbot_plugin.api.entities.builtin.platform.message` components, not platform-native SDK objects.
+
+## Required Message Send Tests
+
+For every adapter, outbound message conversion must be tested through `plugin-e2e-outbound` by having the plugin call SDK platform APIs and verifying the platform UI/simulator receives the expected message.
+
+| Component | Required Send Assertion |
+|-----------|-------------------------|
+| `Plain` | Text appears exactly on the platform. |
+| `At` | User mention renders as a mention or platform equivalent. |
+| `AtAll` | Broadcast mention renders or is explicitly unsupported. |
+| `Image` | URL, path, or base64 image sends and renders/downloads correctly. |
+| `Voice` | Voice/audio sends when supported. |
+| `File` | File sends with name and content/link when supported. |
+| `Quote` | Quoted reply points to the original message when supported. |
+| `Face` | Native emoji/sticker/dice/rps sends or is explicitly unsupported. |
+| `Forward` | Forward/merged-forward sends when supported; otherwise fallback behavior is documented. |
+| Mixed chain | A mixed chain preserves component order as closely as the platform allows. |
+
+If a platform supports a component only in one direction, the adapter record must say so explicitly.
+
+## Required Event Tests
+
+The plugin must subscribe to every event declared in `manifest.yaml -> spec.supported_events` and record one of `plugin-e2e-ui`, `plugin-e2e-protocol`, `not-supported`, or `blocked`.
+
+| Event | Required Assertion |
+|-------|--------------------|
+| `message.received` | Real message reaches plugin as `MessageReceivedEvent`. |
+| `message.edited` | Edited message reaches plugin with message ID and new content, if declared. |
+| `message.deleted` | Deleted/recalled message reaches plugin with message ID and operator when available, if declared. |
+| `message.reaction` | Reaction add/remove reaches plugin with message ID, user, reaction, and direction, if declared. |
+| `feedback.received` | Feedback payload reaches plugin with feedback type and message/session IDs, if declared. |
+| `group.member_joined` | Join event reaches plugin with group and member. |
+| `group.member_left` | Leave/kick event reaches plugin with group, member, and kick flag. |
+| `group.member_banned` | Mute/ban event reaches plugin with group, member, operator, and duration. |
+| `group.info_updated` | Group metadata update reaches plugin with changed fields, if declared. |
+| `friend.request_received` | Friend request reaches plugin with request ID and message. |
+| `friend.added` | Friend-added event reaches plugin. |
+| `friend.removed` | Friend-removed event reaches plugin, if declared. |
+| `bot.invited_to_group` | Bot invite/join request reaches plugin with group and inviter/request ID. |
+| `bot.removed_from_group` | Bot removal reaches plugin with group and operator when available. |
+| `bot.muted` | Bot mute reaches plugin with duration. |
+| `bot.unmuted` | Bot unmute reaches plugin. |
+| `platform.specific` | At least one unmapped native event is delivered as structured platform-specific data, if declared. |
+
+Do not declare an event in the manifest unless there is an implementation path and an acceptance entry.
+
+## Required Common API Tests
+
+The plugin must call every common API declared in `manifest.yaml -> spec.supported_apis.required` and `optional`. Each call must be recorded with input summary and result.
+
+| API | Required Assertion |
+|-----|--------------------|
+| `send_message` | Plugin sends to private and group/channel targets where supported. |
+| `reply_message` | Plugin replies to the triggering message, with quoted mode tested when supported. |
+| `edit_message` | Plugin edits a bot-sent message, if declared. |
+| `delete_message` | Plugin deletes/recalls a bot-sent message, if declared and permissions allow. |
+| `forward_message` | Plugin forwards or emulates forwarding a real message, if declared. |
+| `get_message` | Plugin retrieves a real message and receives common `MessageReceivedEvent` shape. |
+| `get_group_info` | Plugin receives `UserGroup` with ID/name/count where available. |
+| `get_group_list` | Plugin receives joined groups/channels list where supported. |
+| `get_group_member_list` | Plugin receives list of `UserGroupMember` where supported. |
+| `get_group_member_info` | Plugin receives one member with role/display name where available. |
+| `set_group_name` | Plugin changes and restores a disposable group name, if declared. |
+| `mute_member` | Plugin mutes a disposable target, if declared. |
+| `unmute_member` | Plugin unmutes the same target, if declared. |
+| `kick_member` | Plugin kicks a disposable target only in destructive test mode, if declared. |
+| `leave_group` | Plugin leaves only in destructive test mode and only at the end, if declared. |
+| `get_user_info` | Plugin receives common `User` shape. |
+| `get_friend_list` | Plugin receives friend/contact list where supported. |
+| `approve_friend_request` | Plugin accepts/rejects a disposable friend request, if declared. |
+| `approve_group_invite` | Plugin accepts/rejects a disposable group invite, if declared. |
+| `upload_file` | Plugin uploads a real small file, if declared. |
+| `get_file_url` | Plugin resolves a real file ID to a URL, if declared. |
+| `call_platform_api` | Plugin calls every declared platform-specific action with safe parameters. |
+
+Destructive APIs must be opt-in and documented with the exact target used.
+
+The SDK must expose a plugin-side platform API escape hatch for adapter-specific actions. The acceptance plugin should call it from the same EBA event handler that received the real platform event, so the evidence proves both directions of the path:
+
+```text
+plugin -> SDK call_platform_api -> LangBot core -> adapter call_platform_api -> platform SDK/API
+```
+
+The result must be serialized into JSON-safe values before it is returned to the plugin runtime.
+
+## Platform-Specific API Tests
+
+Every action listed in `manifest.yaml -> spec.platform_specific_apis` must have one acceptance entry:
+
+- `plugin-e2e-ui` or `plugin-e2e-outbound`: called by the plugin against the live/simulator endpoint.
+- `plugin-e2e-protocol`: called by the plugin after a protocol-boundary injected event; useful for endpoint-specific simulators but must be labelled.
+- `not-supported`: removed from manifest or explained if the platform SDK exposes it but this adapter intentionally does not.
+- `blocked`: endpoint did not implement it, permissions missing, or safe fixture unavailable.
+
+Do not leave a platform-specific API in the manifest without a corresponding test record.
+
+## Required Compatibility Tests
+
+Each migrated adapter must also prove:
+
+- Manifest supported events match `adapter.get_supported_events()`.
+- Manifest supported APIs match `adapter.get_supported_apis()`.
+- Manifest platform-specific actions match `PLATFORM_API_MAP`.
+- Legacy `FriendMessage` / `GroupMessage` listeners still work when the core registers them.
+- EBA listener dispatch prefers the most specific event class, then `EBAEvent`, then base `Event`.
+- Self-message filtering prevents bot echo loops without dropping edit/delete/moderation events needed for API tests.
+- `source_platform_object` is present for reply/debug but not required by plugins for common behavior.
+
+## Required Documentation Per Adapter
+
+Each adapter document must include:
+
+- adapter directory and manifest name
+- config table
+- supported event table with evidence level per event
+- supported common API table with evidence level per API
+- platform-specific API table with evidence level per action
+- receive component table with evidence level per component
+- send component table with evidence level per component
+- exact test date
+- exact platform endpoint or simulator used
+- standalone runtime command
+- plugin path/name used for testing
+- evidence JSONL path
+- destructive operations performed or explicitly skipped
+- blocked items and reasons
+
+## Acceptance Rule
+
+An adapter can be marked migrated only when:
+
+1. All declared events have `plugin-e2e-ui`, justified `plugin-e2e-protocol`, or `not-supported` evidence.
+2. All declared APIs have `plugin-e2e-outbound` or `not-supported` evidence.
+3. All platform-supported receive components have `plugin-e2e-ui` evidence; protocol-only receive coverage keeps the status partial.
+4. All platform-supported send components have `plugin-e2e-outbound` evidence.
+5. Unit tests cover conversion and API-shape boundaries.
+6. The adapter document lists every blocked or skipped item honestly.
+
+If any declared capability is only covered by `adapter-live` or `unit`, the adapter status must remain partial.

docs/event-based-agents/adapters/acceptance-report.md

@@ -0,0 +1,164 @@
+# EBA Adapter Acceptance Report
+
+Date: May 10, 2026
+
+Scope:
+
+- `telegram-eba`
+- `discord-eba`
+- `aiocqhttp-eba`
+- `dingtalk-eba`
+- `lark-eba`
+- `wecom-eba`
+- `wecombot-eba`
+- `wecomcs-eba`
+- `officialaccount-eba`
+
+This report follows `acceptance-checklist.md`. Evidence levels are intentionally strict:
+
+- `plugin-e2e-ui`: real platform or simulator UI event reached LangBot, standalone runtime, and `EBAEventProbe`.
+- `plugin-e2e-protocol`: real adapter endpoint event reached LangBot, standalone runtime, and `EBAEventProbe`, but the event was injected at the platform protocol boundary rather than sent through the UI.
+- `plugin-e2e-outbound`: the plugin called SDK APIs and the resulting bot message was visible on the platform.
+- `unit`: mocked converter/API coverage only.
+- `blocked`: not completed, either because the platform/simulator/client could not trigger it or because a safe disposable fixture was unavailable.
+- `not-supported`: the platform has no equivalent capability.
+
+## Summary
+
+| Adapter | Status | Honest acceptance summary |
+|---------|--------|---------------------------|
+| Telegram | Partial EBA acceptance | Real Telegram UI covered private text, group mention text, bot invite, inbound private image/file, outbound component sweep, safe SDK APIs, and safe Telegram platform APIs. Real UI inbound voice/quote was not completed in the latest plugin run. |
+| Discord | Partial EBA acceptance | Real Discord UI covered group text, outbound image/file/quote/mention components, safe SDK APIs, and safe Discord platform APIs. Real UI inbound attachment/image/file/reply/mention was not completed. A later UI retry was blocked because the Discord client kept the send button disabled. |
+| OneBot v11 / aiocqhttp | Partial EBA acceptance | Matcha UI covered real group text and outbound supported components/APIs. Multi-component inbound `Source/Plain/At/Face/Image/Voice/File/Quote` was verified through the real OneBot reverse WebSocket adapter endpoint, but not through Matcha UI upload/send. Matcha blocks file-send and merged-forward APIs. |
+| DingTalk | Partial EBA acceptance | Real DingTalk UI covered private text, emoji-as-text inbound, private inbound image/file, outbound image/file/quote/mention fallback components, safe SDK APIs, and safe DingTalk platform APIs. Real UI inbound voice/quote and group trigger were not completed. |
+| Lark / Feishu | Partial EBA acceptance | EBA adapter structure, self-built/store app config, WebSocket/Webhook mode handling, converters, common APIs, platform APIs, and unit tests are in place. One real LangBot organization WebSocket private text event reached `EBAEventProbe`; outbound component sweep was visible in Feishu. Latest real UI image/file sends did not reach local plugin evidence, so media receive remains blocked. |
+| WeCom | Partial EBA acceptance | Regular WeCom application-message adapter is split into the EBA directory with manifest, converters, API mixin, platform API map, and unit tests. Private text reached `EBAEventProbe` through standalone runtime and the real WeCom client; safe plugin APIs passed. Real inbound media and broader event coverage remain pending. |
+| WeComBot | Partial EBA acceptance | WeCom AI Bot is split into the EBA directory with WebSocket long connection mode and optional webhook mode, EBA message/feedback/platform-specific conversion, cache-backed common APIs, platform API map, unit tests, and a direct live probe. Private text, outbound component sweep, safe common APIs, and all declared WeComBot platform APIs reached `EBAEventProbe`; group, real inbound media, and feedback callback evidence remain pending. |
+| WeCom Customer Service | Partial EBA acceptance | WeCom Customer Service is split into the EBA directory with manifest, converters, API mixin, platform API map, unit tests, docs, and a direct live probe scaffold. Real WeChat customer-side UI text reached `EBAEventProbe`; plugin outbound text/image and safe cache-backed common APIs passed. Inbound media and platform-specific API live coverage remain pending; later fallback text sends were blocked by WeCom `95001 send msg count limit`. |
+| Official Account | Partial EBA acceptance | WeChat Official Account is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, and a direct live probe scaffold. Real WeChat Official Account UI private text reached `EBAEventProbe`; safe cache-backed common APIs and declared platform APIs passed. Proactive outbound `send_message` is not supported because replies must be tied to inbound webhook windows; inbound image/voice live UI evidence remains pending. |
+
+Telegram and DingTalk now have real user-side UI image/file upload evidence in plugin JSONL. Discord and aiocqhttp do not yet have real UI inbound image/file evidence.
+
+## Evidence Files
+
+| Adapter | Endpoint | Evidence |
+|---------|----------|----------|
+| Telegram private | Telegram Lite, `@rockchinq_bot` private chat | `data/temp/telegram-plugin-e2e-rerun.jsonl` |
+| Telegram private media | Telegram Lite, `@rockchinq_bot` private chat | `data/temp/telegram-plugin-e2e-media-ui.jsonl` |
+| Telegram group | Telegram Lite, `Rock'sBotGroup` | `data/temp/telegram-plugin-e2e-group.jsonl` |
+| Discord | Discord client, LangBot server, `#debugging` | `data/temp/discord-plugin-e2e-20260510-final.jsonl` |
+| aiocqhttp UI | local Matcha, group `test group` | `data/temp/aiocqhttp-plugin-e2e-20260510-multiformat.jsonl` |
+| aiocqhttp protocol | OneBot reverse WebSocket endpoint `127.0.0.1:2280/ws` | `data/temp/aiocqhttp-plugin-e2e-20260510-multiformat.jsonl` |
+| DingTalk | DingTalk Mac, `LangBot Team` org private chat | `data/temp/dingtalk-plugin-e2e-20260510-rerun.jsonl` |
+| DingTalk private media | DingTalk Mac, `LangBot Team` org private chat | `data/temp/dingtalk-plugin-e2e-media-ui.jsonl` |
+| Lark / Feishu unit | local mocked Feishu SDK/client paths | `tests/unit_tests/platform/test_lark_eba_adapter.py` |
+| Lark / Feishu partial live | Feishu Mac, LangBot organization `LangBotDev` private chat | `data/temp/lark-plugin-e2e-ws.jsonl` |
+| WeCom Customer Service | WeChat customer-side UI, `客服消息 -> 浪波智能客服` on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/wecomcs_eba_plugin_probe.jsonl` |
+| Official Account | WeChat desktop client, subscribed Official Account on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/officialaccount_eba_plugin_probe.jsonl` |
+
+All plugin runs used SDK standalone runtime ports `5400/5401`, LangBot `--standalone-runtime`, and the real plugin at `langbot-plugin-demo/EBAEventProbe`.
+
+## Unified Shape Verification
+
+All four adapters deliver common SDK entities to plugins before LangBot core/plugin logic handles the event.
+
+| Requirement | Telegram | Discord | aiocqhttp | DingTalk | Lark / Feishu |
+|-------------|----------|---------|-----------|----------|---------------|
+| `bot_uuid` filled | plugin-e2e | plugin-e2e | plugin-e2e | plugin-e2e | live plugin-e2e pending |
+| `adapter_name` filled | `telegram` | `discord` | `aiocqhttp` | `dingtalk` | `lark-eba` in current unit/code; older live text evidence recorded `lark` before the naming fix |
+| common `MessageChain` delivered | `Plain`, group `At + Plain`, private `Image`, private `File` | `Source + Plain` | UI `Source + Plain`; protocol `Source + Plain + At + Face + Image + Voice + File + Quote + Plain` | `Source + Plain`, private `Source + Image`, private `Source + File` | live private `Source + Plain`; unit `Source + Plain + At/Image/File`; latest live image/file blocked |
+| common user/group entities | plugin-e2e | plugin-e2e | plugin-e2e | plugin-e2e private user; group not completed | live private user; unit private/group |
+| raw native object isolation | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` |
+
+## Message Receive Components
+
+| Component | Telegram | Discord | aiocqhttp | DingTalk | Lark / Feishu |
+|-----------|----------|---------|-----------|----------|---------------|
+| `Source` | design gap: event has message id but chain omits `Source` | plugin-e2e-ui | plugin-e2e-ui/protocol | plugin-e2e-ui | plugin-e2e-ui private text |
+| `Plain` | plugin-e2e-ui private/group | plugin-e2e-ui | plugin-e2e-ui/protocol | plugin-e2e-ui | plugin-e2e-ui private text |
+| `At` | plugin-e2e-ui group mention | unit; real UI mention not completed in latest run | plugin-e2e-protocol; unit | unit; group trigger not completed | unit; group trigger not completed |
+| `AtAll` | not-supported | unit only | unit only | unit/send fallback only | unit only |
+| `Image` | plugin-e2e-ui private | converter/unit; real UI attachment not completed | plugin-e2e-protocol, not Matcha UI | plugin-e2e-ui private | unit; real UI image sent but not observed in plugin evidence |
+| `Voice` | converter/unit; real UI inbound not completed | not-supported as native voice; audio is attachment/file | plugin-e2e-protocol, not Matcha UI | converter/unit; real UI inbound not completed | unit; real UI inbound not completed |
+| `File` | plugin-e2e-ui private | converter/unit; real UI attachment not completed | plugin-e2e-protocol, not Matcha UI | plugin-e2e-ui private | unit; real UI file sent but not observed in plugin evidence |
+| `Quote` | converter/unit; real UI reply not completed | unit; real UI reply not completed | plugin-e2e-protocol | converter/unit; real UI quote not completed | unit/API-backed quote lookup; real UI quote not completed |
+| `Face` | not-supported as common `Face` | not-supported as common `Face` | plugin-e2e-protocol | UI emoji becomes `Plain` (`[smile]` text), not `Face` | not-supported as common `Face` |
+| `Forward` | not-supported inbound | not-supported inbound | unit; Matcha forward UI/action blocked | not-supported inbound | not-supported inbound |
+| Mixed chain | group `At + Plain`; media tested as separate messages | not completed inbound | plugin-e2e-protocol | media tested as separate messages; mixed inbound not completed | unit only |
+
+## Message Send Components
+
+| Component | Telegram | Discord | aiocqhttp | DingTalk | Lark / Feishu |
+|-----------|----------|---------|-----------|----------|---------------|
+| `Plain` | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound |
+| `At` | plugin-e2e-outbound equivalent | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound fallback/equivalent | plugin-e2e-outbound |
+| `AtAll` | plugin-e2e-outbound fallback | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound fallback | unit; group live not completed |
+| `Image` | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound |
+| `Voice` | not-supported in current send converter | not-supported as native voice | converter path; not completed against Matcha UI | fallback as file/text depending DingTalk media support | converter path; live not completed |
+| `File` | plugin-e2e-outbound | plugin-e2e-outbound | blocked by Matcha endpoint error | plugin-e2e-outbound | plugin-e2e-outbound |
+| `Quote` | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound fallback | plugin-e2e-outbound fallback |
+| `Face` | not-supported | not-supported | plugin-e2e-outbound attempted in mixed chain | fallback text | not-supported |
+| `Forward` | flattened fallback | flattened fallback | blocked by Matcha unsupported action | flattened fallback | plugin-e2e-outbound flattened fallback |
+| Mixed chain | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound except blocked file/forward | plugin-e2e-outbound | plugin-e2e-outbound |
+
+## Event Acceptance
+
+| Event category | Telegram | Discord | aiocqhttp | DingTalk |
+|----------------|----------|---------|-----------|----------|
+| `message.received` | plugin-e2e-ui | plugin-e2e-ui | plugin-e2e-ui and plugin-e2e-protocol | plugin-e2e-ui private |
+| `message.edited` | implemented/unit, not plugin-e2e-ui | historical/direct only, not latest plugin-e2e | unit | not declared |
+| `message.deleted` | implemented/unit, not plugin-e2e-ui | historical/direct only, not latest plugin-e2e | unit | not declared |
+| `message.reaction` | implemented/unit, not plugin-e2e-ui | historical/direct only, not latest plugin-e2e | not-supported in standard OneBot message path | not declared |
+| member join/left/ban | implemented/unit or blocked without disposable users | blocked without disposable users | unit; Matcha fixture unavailable | not declared |
+| bot invited/removed | invite plugin-e2e-ui for Telegram; removal blocked | invite historical/plugin-series; removal blocked | unit; Matcha fixture unavailable | not declared |
+| requests/friend events | not applicable | not applicable | unit; Matcha fixture unavailable | not declared |
+| `platform.specific` | implemented; not latest plugin-e2e | not latest plugin-e2e | adapter lifecycle observed; plugin focus was message path | declared for fallback; not reproduced in UI run |
+
+## Common API Acceptance
+
+| API area | Telegram | Discord | aiocqhttp | DingTalk |
+|----------|----------|---------|-----------|----------|
+| send/reply | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound, with Matcha file/forward gaps | plugin-e2e-outbound |
+| edit/delete | historical/direct or unit; destructive/current UI not repeated | historical/direct; destructive/current UI not repeated | unit/destructive blocked | not declared or blocked |
+| message lookup | not-supported | not-supported | plugin-e2e | inbound cache-backed where available; limited live coverage |
+| group info/member info | plugin-e2e safe subset | plugin-e2e safe subset | plugin-e2e safe subset | private path only; group not completed |
+| user/friend info | plugin-e2e where platform allows | plugin-e2e where platform allows | plugin-e2e | plugin-e2e private user |
+| moderation/leave | blocked without disposable safe targets | blocked without disposable safe targets | blocked without disposable safe targets | blocked/not declared |
+| `get_file_url` | implemented; latest inbound `File` carried downloadable file data in plugin evidence | URL passthrough for attachments; inbound attachment not completed | not portable/endpoint-dependent | implemented through DingTalk media API; latest inbound `File` carried a platform file URL |
+| `call_platform_api` | plugin-e2e safe actions | plugin-e2e safe actions | plugin-e2e safe actions, Matcha gaps documented | plugin-e2e safe `check_access_token` |
+
+## Platform-Specific API Acceptance
+
+| Adapter | plugin-e2e verified | Blocked or not reproduced |
+|---------|---------------------|---------------------------|
+| Telegram | safe chat/admin/member count/chat-action actions | mutating actions and callback-only actions were not repeated |
+| Discord | safe channel/guild/role/typing actions | mutating pin/reaction/invite actions were not repeated in the latest plugin run; inbound attachment paths not completed |
+| aiocqhttp | safe OneBot actions such as status/version/can-send checks | `get_group_honor_info` unsupported by Matcha; admin/card/title/ban/record/file/forward require better endpoint fixtures |
+| DingTalk | `check_access_token`; real inbound file produced a file URL in the common `File` component | separate media-download replay APIs and group actions need a working follow-up fixture |
+
+## SDK API Acceptance
+
+`EBAEventProbe` exercised the standalone runtime path for:
+
+- bot discovery and bot info lookup
+- send message
+- component sweep where enabled
+- platform API sweep where enabled
+- plugin storage
+- workspace storage
+- plugin/command/tool/knowledge-base list APIs
+
+The probe logs set `ok=true` when the sweep completed with only expected unsupported/blocked items. Individual call details are stored in the JSONL evidence files.
+
+## Residual Risks And Required Follow-Up
+
+- Discord still requires real UI inbound image/file upload evidence before it can be called media-complete.
+- aiocqhttp has rich inbound component evidence only at the OneBot reverse WebSocket boundary; Matcha UI did not provide image/file upload coverage.
+- DingTalk group trigger remains unclosed; current evidence is private chat only.
+- Lark / Feishu requires a clean follow-up live pass: the latest LangBot organization WebSocket run connected, but UI-sent text/image/file after the loop-scheduling fix did not append plugin events.
+- Discord UI retry on May 10, 2026 was blocked by the client keeping the send button disabled even after text was entered.
+- Destructive moderation and leave APIs are intentionally blocked until disposable users/groups are available.
+
+## Conclusion
+
+The EBA conversion path is implemented and partially proven for the migrated adapters. Telegram and DingTalk now have real UI private-chat image/file inbound evidence. Discord, aiocqhttp, and Lark / Feishu still have explicit UI-level media gaps, so the overall adapter set remains partial acceptance rather than production-complete media acceptance.

docs/event-based-agents/adapters/aiocqhttp.md

@@ -0,0 +1,162 @@
+# OneBot v11 / aiocqhttp EBA Adapter
+
+## Status
+
+OneBot v11 has been migrated to the EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/aiocqhttp/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+├── types.py
+└── onebot.svg
+```
+
+The EBA adapter is registered as `aiocqhttp-eba`. The legacy adapter remains at `src/langbot/pkg/platform/sources/aiocqhttp.py`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `host` | Yes | `0.0.0.0` | Host for the reverse WebSocket server that the OneBot endpoint connects to. |
+| `port` | Yes | `2280` | Reverse WebSocket listen port. |
+| `access-token` | No | `""` | OneBot access token, if the endpoint is configured to use one. |
+
+## Events
+
+The adapter declares these EBA events:
+
+- `message.received`
+- `message.deleted`
+- `group.member_joined`
+- `group.member_left`
+- `group.member_banned`
+- `friend.request_received`
+- `friend.added`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `bot.muted`
+- `bot.unmuted`
+- `platform.specific`
+
+`platform.specific` is used for OneBot notice/request/meta events that do not yet have a common EBA event type, such as group admin changes, group file uploads, pokes, honor changes, and group join requests from non-bot users.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported | Supports private and group text, mentions, images, voice, files, faces, and flattened forwards. Group merged forwards are sent through OneBot forward APIs when possible. |
+| `reply_message` | Supported | Uses the original OneBot event and can prepend a reply segment. |
+| `edit_message` | Not supported | OneBot v11 has no standard message edit action. |
+| `delete_message` | Supported | Uses `delete_msg`; permission depends on endpoint and group role. |
+| `forward_message` | Supported | Emulates forward by fetching the source message with `get_msg` and sending its content to the target chat. |
+| `get_message` | Supported | Uses `get_msg` and converts the response into `MessageReceivedEvent`. |
+| `get_group_info` | Supported | Uses `get_group_info`. |
+| `get_group_list` | Supported | Uses `get_group_list`. |
+| `get_group_member_list` | Supported | Uses `get_group_member_list`. |
+| `get_group_member_info` | Supported | Uses `get_group_member_info`. |
+| `set_group_name` | Supported | Uses `set_group_name`; may be unsupported by mock endpoints. |
+| `get_user_info` | Supported | Uses `get_stranger_info`. |
+| `get_friend_list` | Supported | Uses `get_friend_list`. |
+| `approve_friend_request` | Supported | Uses `set_friend_add_request`. |
+| `approve_group_invite` | Supported | Uses `set_group_add_request` with `sub_type=invite`. |
+| `upload_file` | Not supported | OneBot v11 has endpoint-specific file upload extensions but no portable standalone upload action. |
+| `get_file_url` | Not supported | OneBot v11 file URL resolution is endpoint-specific. Use `call_platform_api("get_image")`, `get_record`, or endpoint extensions when available. |
+| `mute_member` | Supported | Uses `set_group_ban`. |
+| `unmute_member` | Supported | Uses `set_group_ban` with duration `0`. |
+| `kick_member` | Supported | Destructive; test only with disposable members. |
+| `leave_group` | Supported | Destructive; should run last in live tests. |
+| `call_platform_api` | Supported | See below. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `get_login_info`
+- `get_status`
+- `get_version_info`
+- `get_group_honor_info`
+- `set_group_card`
+- `set_group_special_title`
+- `set_group_admin`
+- `set_group_whole_ban`
+- `send_group_forward_msg`
+- `get_forward_msg`
+- `get_record`
+- `get_image`
+- `can_send_image`
+- `can_send_record`
+
+## Message Conversion Notes
+
+Incoming OneBot segments are converted into common `MessageChain` components before LangBot core/plugin dispatch:
+
+- `text` -> `Plain`
+- `at` -> `At` / `AtAll`
+- `image` -> `Image` or `Face` for OneBot emoji-package images
+- `record` -> `Voice`
+- `file` -> `File`
+- `reply` -> `Quote`
+- `face`, `rps`, `dice` -> `Face`
+- unsupported segments -> `Unknown`
+
+Outgoing `MessageChain` components are converted back into `aiocqhttp.Message` segments. Base64 media strings are normalized to OneBot `base64://...` format.
+
+## Live Test Record
+
+The direct live probe is:
+
+```bash
+PYTHONPATH=/Users/qinjunyan/code/projects/langbot/langbot-plugin-sdk/src \
+uv run python tests/e2e/live_aiocqhttp_eba_probe.py --host 127.0.0.1 --port 2280
+```
+
+It starts the reverse WebSocket adapter directly, records observed EBA events to `data/temp/aiocqhttp_eba_live_probe.jsonl`, waits for a real Matcha or OneBot message, then tries reply/send/get/delete/group/user/platform API calls as far as the endpoint supports them.
+
+Verified on May 10, 2026 with local Matcha connected to `ws://127.0.0.1:2280/ws`:
+
+- Real inbound group message converted to `MessageReceivedEvent`.
+- Real lifecycle connection converted to `PlatformSpecificEvent`.
+- Real reply API succeeded and rendered a quoted bot reply in Matcha.
+- Real proactive send API succeeded and rendered a bot group message in Matcha.
+- Real outgoing component sweep succeeded for text, `At`, `AtAll`, `Face`, and base64 `Image`.
+- Real `get_message`, `get_group_info`, `get_login_info`, `get_status`, `get_version_info`, `can_send_image`, and `can_send_record` calls succeeded against Matcha.
+- Unit conversion and API-shape tests passed for `Plain`, `At`, `AtAll`, `Image`, `Voice`, `File`, `Quote`, `Face`, `rps`, `dice`, `Forward`, `Unknown`, private/group message events, delete notices, group join/leave/ban notices, bot mute notices, friend requests, group invites, friend added notices, dispatch specificity, send, reply, delete, forward, get message, group APIs, user APIs, request approval APIs, moderation APIs, leave group, unsupported file APIs, and all declared `call_platform_api` actions.
+
+Skipped or residual live-test items:
+
+- `edit_message`: not implemented because OneBot v11 has no standard edit action.
+- `upload_file` and `get_file_url`: not implemented as common APIs because portable OneBot v11 file upload/download URL semantics are endpoint-specific.
+- `kick_member` and `leave_group`: destructive; run only with explicit `--destructive` and disposable Matcha/OneBot state.
+- `group.info_updated`, message reactions, and message edits are not declared because OneBot v11 does not provide standard equivalents for them.
+- Matcha returned `ActionFailed` for outgoing `File` segment rendering and did not support merged-forward actions in this run. The adapter keeps the conversion/API implementations because they are valid OneBot/NapCat-style capabilities, but the Matcha live probe records them as skipped.
+- Matcha returned an empty `get_group_member_list` for the test group, so `get_group_member_info`, mute/unmute, kick, and leave were covered by unit/API-shape tests only in this run.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 10, 2026 with `EBAEventProbe`, SDK standalone runtime, LangBot `--standalone-runtime`, local Matcha, and group `测试群`.
+
+Evidence:
+
+- Plugin JSONL: `data/temp/aiocqhttp-plugin-e2e-20260510-multiformat.jsonl`
+
+Observed and verified:
+
+- A real Matcha group message reached the plugin as `MessageReceived` with `bot_uuid=eba-aiocqhttp-matcha`, `adapter_name=aiocqhttp`, common `Source`/`Plain` message components, common sender, and common group identifiers.
+- A protocol-level OneBot reverse WebSocket event reached the plugin as `MessageReceived` with a mixed common chain: `Source`, `Plain`, `At`, `Face`, `Image`, `Voice`, `File`, `Quote`, and trailing `Plain`. This proves the real adapter + LangBot + standalone runtime + plugin path for mixed inbound OneBot payloads, but it was not sent through Matcha UI.
+- SDK API calls succeeded: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage, workspace storage, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Outbound component sweep succeeded for plain text plus `At`/`Face`, `AtAll`, base64 `Image`, and quoted reply.
+- Common APIs succeeded through the plugin path: `get_message`, `get_user_info`, `get_friend_list`, `get_group_info`, `get_group_list`, `get_group_member_list`, and `get_group_member_info`.
+- Safe OneBot platform APIs succeeded through `call_platform_api`: `get_login_info`, `get_status`, `get_version_info`, `can_send_image`, and `can_send_record`.
+
+Documented Matcha limits in this E2E run:
+
+- Matcha UI did not provide a completed image/file upload/send path for inbound media. The rich inbound media evidence is `plugin-e2e-protocol`, not UI-level media upload evidence.
+- Outbound `File` failed in Matcha even after the adapter emitted an official `file` segment shape.
+- Outbound `Forward` failed because Matcha returned unsupported action for merged-forward.
+- `get_group_honor_info` failed because Matcha returned unsupported action.
+- Destructive/admin APIs such as mute, unmute, kick, leave, group rename, card/title/admin/whole-ban changes, and request approvals were not run without disposable fixtures.

docs/event-based-agents/adapters/dingtalk.md

@@ -0,0 +1,114 @@
+# DingTalk EBA Adapter Migration Record
+
+Status: migrated with partial plugin E2E evidence.
+
+Adapter directory: `src/langbot/pkg/platform/adapters/dingtalk/`
+
+## What Changed
+
+The DingTalk adapter now has an Event-Based Agents adapter package with:
+
+- `manifest.yaml` for adapter metadata, configuration, events, common APIs, and platform-specific APIs.
+- `adapter.py` for DingTalk client startup, native callback handling, legacy compatibility, and EBA dispatch.
+- `event_converter.py` for native DingTalk events to common EBA events.
+- `message_converter.py` for DingTalk message payloads to/from common `MessageChain` components.
+- `api_impl.py` for common EBA API implementations.
+- `platform_api.py` for DingTalk-specific `call_platform_api` actions.
+
+The legacy DingTalk HTTP client now returns successful JSON response bodies from proactive send methods and raises with response details on non-200 responses.
+
+## Configuration
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `client-id` | yes | DingTalk robot/client identifier. |
+| `client-secret` | yes | DingTalk client secret. |
+| `robot-code` | yes | Robot code used for send APIs. |
+| `robot-name` | no | Used for bot mention/self filtering and display. |
+| `encrypt-key` | no | DingTalk callback encryption key when configured. |
+| `verification-token` | no | DingTalk callback verification token when configured. |
+
+## Supported Events
+
+| Event | Support | Evidence |
+|-------|---------|----------|
+| `message.received` | implemented | `plugin-e2e-ui` private text and emoji-as-text. |
+| `platform.specific` | implemented | Not reproduced in the latest UI run. |
+
+## Receive Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Source` | supported | `plugin-e2e-ui` private message. |
+| `Plain` | supported | `plugin-e2e-ui` private text. DingTalk emoji currently arrives as plain text such as `[smile]`. |
+| `At` | converter path | Group trigger was not completed in the latest run. |
+| `AtAll` | fallback/send-side only | Not completed inbound. |
+| `Image` | supported | Real DingTalk Mac private-chat image upload reached the plugin as common `Image`. |
+| `Voice` | converter path | Real UI inbound voice was not completed. |
+| `File` | supported | Real DingTalk Mac private-chat file upload reached the plugin as common `File`. |
+| `Quote` | converter path | Real UI inbound quote was not completed. |
+| `Face` | not native common mapping | DingTalk emoji was observed as `Plain`, not `Face`. |
+| `Forward` | not-supported inbound | DingTalk does not expose a portable structured forward event in this adapter. |
+
+## Send Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Plain` | supported | `plugin-e2e-outbound`. |
+| `At` | supported or text fallback | `plugin-e2e-outbound`. |
+| `AtAll` | fallback | `plugin-e2e-outbound`. |
+| `Image` | supported | `plugin-e2e-outbound`. |
+| `File` | supported | `plugin-e2e-outbound`. |
+| `Quote` | fallback | `plugin-e2e-outbound`. |
+| `Face` | fallback | `plugin-e2e-outbound` as text fallback. |
+| `Forward` | flattened fallback | `plugin-e2e-outbound`. |
+| `Voice` | fallback/endpoint-dependent | Not separately verified as a native DingTalk voice send. |
+
+## Common APIs
+
+| API | Support | Notes |
+|-----|---------|-------|
+| `send_message` | supported | Verified through `EBAEventProbe`. |
+| `reply_message` | supported | Verified through quoted/fallback send path. |
+| `get_message` | cache-backed | Requires the message to have been observed by this adapter process. |
+| `get_group_info` | cache-backed/API-backed where available | Group path not completed in latest UI run. |
+| `get_group_list` | supported where DingTalk API allows | Limited live coverage. |
+| `get_group_member_info` | supported where DingTalk API allows | Limited live coverage. |
+| `get_user_info` | supported | Private sender path verified. |
+| `get_friend_list` | limited | DingTalk does not expose a portable friend-list equivalent. |
+| `get_file_url` | supported with media/file identifiers | Real inbound file yielded a platform file URL in the converted `File` component. |
+| `call_platform_api` | supported | Safe action `check_access_token` verified. |
+
+## Platform-Specific APIs
+
+| Action | Support | Evidence |
+|--------|---------|----------|
+| `check_access_token` | supported | `plugin-e2e`. |
+| `refresh_access_token` | supported | Implemented; not separately reproduced in the latest plugin run. |
+| `get_file_url` | supported | Real inbound file yielded a platform file URL in the converted `File` component. |
+| `get_audio_base64` | supported | Needs real inbound audio/media ID. |
+| `download_image_base64` | supported | Real inbound image reached the plugin as `Image`; separate image-download API replay was not completed. |
+
+## End-to-End Evidence
+
+Evidence files:
+
+- Text/API/component JSONL: `data/temp/dingtalk-plugin-e2e-20260510-rerun.jsonl`
+- Real UI inbound media JSONL: `data/temp/dingtalk-plugin-e2e-media-ui.jsonl`
+
+Verified:
+
+- DingTalk Mac private chat in the `LangBot Team` organization produced `MessageReceived` through LangBot standalone runtime and `EBAEventProbe`.
+- The common chain was `Source + Plain` for normal text.
+- DingTalk emoji was received as `Source + Plain`, not common `Face`.
+- Real DingTalk Mac private-chat image upload was received as `Source + Image`.
+- Real DingTalk Mac private-chat file upload was received as `Source + File`.
+- The plugin sent outbound text, mention/fallback, image, quote/fallback, file, and forward/fallback messages visible in DingTalk.
+- The plugin called safe SDK and DingTalk platform APIs.
+
+Not completed:
+
+- Real UI inbound voice.
+- Real UI inbound quote.
+- Group trigger with a real robot mention.
+- Destructive or organization-mutating APIs.

docs/event-based-agents/adapters/discord.md

@@ -0,0 +1,147 @@
+# Discord EBA Adapter
+
+## Status
+
+Discord has been migrated from the legacy source adapter:
+
+```text
+src/langbot/pkg/platform/sources/discord.py
+src/langbot/pkg/platform/sources/discord.yaml
+```
+
+EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/discord/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+├── types.py
+└── voice.py
+```
+
+The adapter is registered as `discord-eba`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `client_id` | Yes | `""` | Discord application client ID. |
+| `token` | Yes | `""` | Discord bot token. |
+
+The bot needs gateway permissions and intents for the target test server. Message Content intent is required for message bodies, Server Members intent is required for member APIs/events, and reaction events require the Reactions intent and channel permissions.
+
+## Events
+
+Discord declares these EBA events:
+
+- `message.received`
+- `message.edited`
+- `message.deleted`
+- `message.reaction`
+- `group.member_joined`
+- `group.member_left`
+- `group.member_banned`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `platform.specific`
+
+Discord-specific events that do not map cleanly to common events should be surfaced as `platform.specific`.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|-----------------|-------|
+| `send_message` | Supported | Supports text, image, file, and mixed message chains through Discord messages and attachments. |
+| `reply_message` | Supported | Uses Discord message references when replying to a received EBA message event. |
+| `edit_message` | Supported | Bot can edit its own messages. File edits are implemented by clearing old attachments and sending replacement files when needed. |
+| `delete_message` | Supported | Requires message management permissions for non-bot messages. |
+| `forward_message` | Emulated | Discord has no native forward API; the adapter copies content and attachments. |
+| `get_group_info` | Supported | Maps Discord guild metadata to EBA group info. |
+| `get_group_member_list` | Supported | Requires member cache or the Server Members intent/fetch permission. |
+| `get_group_member_info` | Supported | Maps Discord roles/permissions into EBA member roles. |
+| `get_user_info` | Supported | Uses Discord user fetch/cache. |
+| `upload_file` | Not supported | Discord uploads files as message attachments; standalone upload raises `NotSupportedError`. |
+| `get_file_url` | Supported | Discord attachment URLs are already downloadable URLs, so the adapter returns the input URL. |
+| `mute_member` | Supported where possible | Uses Discord timeout API and requires guild moderation permission. |
+| `unmute_member` | Supported where possible | Clears timeout and requires guild moderation permission. |
+| `kick_member` | Supported | Destructive; test only with a disposable account/bot. |
+| `leave_group` | Supported | Bot leaves a guild; destructive and should run last. |
+| `call_platform_api` | Supported | Discord-specific actions live here. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `get_channel`
+- `get_guild`
+- `get_guild_channels`
+- `get_guild_roles`
+- `create_invite`
+- `pin_message`
+- `unpin_message`
+- `add_reaction`
+- `remove_reaction`
+- `typing`
+
+Voice helpers are intentionally kept Discord-specific:
+
+- `join_voice_channel`
+- `leave_voice_channel`
+- `get_voice_connection_status`
+- `list_active_voice_connections`
+- `get_voice_channel_info`
+
+## Live Test Record
+
+The live probe is:
+
+```bash
+uv run python tests/e2e/live_discord_eba_probe.py --help
+```
+
+Verified on May 7, 2026 with a newly created Discord application/bot named `LangBot EBA Test 0507`, the LangBot Discord server, and the `#🐞-debugging` channel:
+
+- SDK standalone runtime started with WebSocket control/debug ports, and the `EBAEventProbe` plugin connected through `lbp run`.
+- Plugin runtime received real Discord events through LangBot: `BotInvitedToGroup`, `MessageReceived`, `MessageReactionReceived` add/remove, `MessageEdited`, and `MessageDeleted`.
+- Plugin runtime API calls succeeded through the standalone runtime: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage APIs, workspace storage APIs, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Direct live adapter probe observed `message.received`, `message.edited`, `message.deleted`, and `bot.removed_from_group`.
+- Message APIs verified: send, reply, edit, delete, forward, text/image/file mixed message chains.
+- User and guild APIs verified: `get_user_info`, `get_group_info`, `get_group_member_list`, `get_group_member_info`.
+- Platform-specific APIs verified: `get_channel`, `get_guild`, `get_guild_channels`, `get_guild_roles`, `create_invite`, `typing`, `pin_message`, `unpin_message`, `add_reaction`, `remove_reaction`.
+- Unsupported API behavior verified: `upload_file` raises `NotSupportedError`.
+- Destructive API verified at the end: `leave_group`, which emitted `bot.removed_from_group`.
+
+Not verified in the shared LangBot server live run: `mute_member`, `unmute_member`, and `kick_member`, because the run did not use a disposable target member. They are implemented through Discord timeout/kick APIs and should only be exercised against a disposable account or bot.
+
+The test fixed one real test-fixture issue: `EBAEventProbe` previously assumed `get_bots()` returned UUID strings. The current standalone runtime returns bot dictionaries, so the probe now selects an enabled bot dictionary and passes its `uuid` to `get_bot_info` and `send_message`. The probe also now subscribes to `MessageDeleted`.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified again on May 10, 2026 with SDK standalone runtime, LangBot `--standalone-runtime`, Discord web client, the LangBot server, and `#🐞-debugging`.
+
+Evidence:
+
+- Main plugin JSONL: `data/temp/discord-plugin-e2e-20260510-final.jsonl`
+- LangBot runtime log: `data/temp/discord-langbot-e2e-20260510-rerun.log`
+
+Observed and verified:
+
+- A newly invited Discord bot connected to the LangBot server and received a real web-client message in `#🐞-debugging`.
+- `MessageReceived` reached the plugin with `bot_uuid=eba-discord-live`, `adapter_name=discord`, common `Source`/`Plain` message components, common `User`, and common `UserGroup` for the guild.
+- SDK API calls succeeded: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage, workspace storage, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Outbound component sweep succeeded: plain text plus user mention, `AtAll`/`@everyone`, base64 image, quoted reply, file attachment, and flattened forward fallback.
+- Common APIs succeeded: `get_user_info`, `get_group_info`, `get_group_member_list`, and `get_group_member_info`.
+- Discord platform APIs succeeded through `call_platform_api`: `get_channel`, `typing`, `get_guild`, `get_guild_channels`, and `get_guild_roles`.
+
+Documented limits in this E2E run:
+
+- Real Discord UI inbound attachment/image/file, reply/quote, and fresh mention-chain messages were not completed in the plugin E2E evidence. Outbound image/file attachments from the bot do not prove inbound attachment conversion.
+- A later May 10 UI retry could write text into the Discord message box, but the client kept the send button disabled and did not send the message, so it produced no new plugin evidence.
+- `get_message`, `get_friend_list`, and `get_group_list` are not supported by this Discord adapter.
+- Destructive moderation and guild-leave APIs were not repeated against the shared LangBot server.
+- Native Discord voice is not represented as common `Voice`; audio-like payloads are treated as file attachments.
+- `create_invite`, pin/unpin, and reaction mutation were covered by prior direct live probes but were not repeated by the final plugin run to avoid extra shared-server side effects.

docs/event-based-agents/adapters/lark.md

@@ -0,0 +1,135 @@
+# Lark / Feishu EBA Adapter Migration Record
+
+Status: migrated with unit coverage and partial live plugin E2E. WebSocket text reached the standalone runtime once in the LangBot organization test app, but the latest real UI image/file inbound attempts did not reach the local adapter log, so media receive is not release-complete yet.
+
+Adapter directory: `src/langbot/pkg/platform/adapters/lark/`
+
+## What Changed
+
+The Lark/Feishu adapter now has an Event-Based Agents adapter package with:
+
+- `manifest.yaml` for adapter metadata, configuration, events, common APIs, platform-specific APIs, app type, and communication mode.
+- `adapter.py` for self-built/store app token handling, WebSocket long connection startup, Webhook callback handling, card feedback, streaming-card replies, and EBA dispatch.
+- `event_converter.py` for native Feishu events to common EBA events.
+- `message_converter.py` for Feishu text/post/image/file/audio payloads to/from common `MessageChain` components.
+- `api_impl.py` for common EBA API implementations.
+- `platform_api.py` for Feishu-specific `call_platform_api` actions.
+
+The legacy `lark` adapter remains available while the EBA adapter is registered separately as `lark-eba`.
+
+## Configuration
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `app_id` | yes | Feishu/Lark application App ID. |
+| `app_secret` | yes | Feishu/Lark application App Secret. |
+| `bot_name` | yes | Must match the bot name so group mentions can be recognized. |
+| `enable-webhook` | yes | `false` uses WebSocket long connection; `true` uses Request URL/Webhook callbacks. |
+| `webhook_url` | no | Generated callback URL for Webhook mode. |
+| `encrypt-key` | no | Webhook decrypt key when event encryption is enabled. |
+| `enable-stream-reply` | yes | Enables streaming replies through an updating Feishu card. |
+| `app_type` | no | `self` for self-built apps; `isv` for store apps. |
+| `bot_added_welcome` | no | Optional group welcome message sent after bot-added events. |
+
+## Application And Communication Modes
+
+| Mode | Support | Implementation |
+|------|---------|----------------|
+| Self-built application | implemented | Uses standard app credentials and tenant token behavior from the Feishu SDK client. |
+| Store application | implemented | Builds an ISV client, requests app tickets, and resolves app/tenant access tokens with per-tenant caching. |
+| WebSocket long connection | implemented | Registers `im.message.receive_v1` and card-action callbacks through `lark_oapi.ws.Client`. |
+| Webhook Request URL | implemented | Handles URL verification, encrypted payloads, message events, app-ticket events, bot-added events, and card-action feedback. |
+
+## Supported Events
+
+| Event | Support | Evidence |
+|-------|---------|----------|
+| `message.received` | implemented | Unit coverage for private and group native events to common EBA events. |
+| `bot.invited_to_group` | implemented | Webhook bot-added event maps to common bot invite event and optional welcome send. |
+| `platform.specific` | implemented | Unknown callback events are preserved as `platform.specific`. |
+| `FeedbackEvent` | compatibility event | Card button feedback is still dispatched through the existing SDK `FeedbackEvent` type. |
+
+## Receive Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Source` | supported | Unit coverage; live private text evidence. |
+| `Plain` | supported | Text and post payloads convert to common text; live private text evidence. |
+| `At` | supported | Feishu mentions map to common `At` with user ID and display name. |
+| `AtAll` | supported | `user_id=all` maps to common `AtAll`. |
+| `Image` | supported | Image payloads download through message resource API and map to common `Image`; real UI image send attempted, but not observed in local plugin evidence yet. |
+| `Voice` | supported | Audio payloads download through message resource API and map to common `Voice`. |
+| `File` | supported | File payloads download through message resource API and map to common `File`; real UI file send attempted, but not observed in local plugin evidence yet. |
+| `Quote` | supported | Parent/thread reply lookup maps quoted content into common `Quote`. |
+| `Face` | not native common mapping | Feishu emoji/stickers are not exposed as a portable common `Face` component here. |
+| `Forward` | not-supported inbound | Feishu does not expose a portable structured forward event in this adapter. |
+
+## Send Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Plain` | supported | Unit coverage; sends Feishu `text`. |
+| `At` | supported | Unit coverage; sends Feishu `post` at element. |
+| `AtAll` | supported | Unit coverage; sends Feishu `post` at-all element. |
+| `Image` | supported | Uploads image resource and sends Feishu `image`. |
+| `Voice` | supported | Uploads OPUS/audio resource and sends Feishu `audio`. |
+| `File` | supported | Uploads file resource and sends Feishu `file`. |
+| `Quote` | supported/fallback | Sends quote marker plus origin content. |
+| `Face` | not-supported | No portable send mapping. |
+| `Forward` | flattened fallback | Flattens forward nodes into text/media messages. |
+
+## Common APIs
+
+| API | Support | Notes |
+|-----|---------|-------|
+| `send_message` | supported | Supports private/open_id and group/chat_id targets; live plugin outbound component sweep produced visible Feishu messages. |
+| `reply_message` | supported | Replies to the source Feishu message; fixed to recover the native Feishu message ID from legacy-wrapped source events. |
+| `get_message` | cache-backed/API-backed | Returns cached inbound event where possible and converts uncached Feishu message API items into common `MessageReceivedEvent`. |
+| `get_group_info` | supported | Uses cached group or Feishu chat metadata. |
+| `get_group_member_info` | limited | Uses cached user data when available. |
+| `get_user_info` | limited | Uses cached user data when available. |
+| `get_file_url` | limited | Returns `file://` paths from downloaded inbound resources; remote Feishu resource download uses platform-specific API params. |
+| `call_platform_api` | supported | See below. |
+
+## Platform-Specific APIs
+
+| Action | Support | Evidence |
+|--------|---------|----------|
+| `check_tenant_access_token` | supported | Unit coverage. |
+| `refresh_app_access_token` | supported | Store-app token path implemented. |
+| `refresh_tenant_access_token` | supported | Store-app tenant token path implemented. |
+| `get_chat` | supported | Feishu chat metadata API wrapper. |
+| `get_message` | supported | Feishu message API wrapper with JSON-safe return values for plugin calls. |
+| `get_message_resource` | supported | Feishu message resource download wrapper. |
+
+## End-to-End Evidence
+
+Current code-level evidence:
+
+- `tests/unit_tests/platform/test_lark_eba_adapter.py`
+- `PYTHONPATH=../langbot-plugin-sdk/src uv run pytest tests/unit_tests/platform/test_lark_eba_adapter.py -q`
+
+Live evidence collected on May 11, 2026:
+
+- Standalone runtime: `uv run lbp rt --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check`
+- LangBot: `uv run main.py --standalone-runtime --debug`
+- Plugin: `LangBot__EBAEventProbe`
+- Feishu org/app: LangBot organization, `LangBotDev` private chat.
+- Observed plugin JSONL: one private `MessageReceived` event with `Source + Plain`; plugin API probe then exercised bot discovery, bot info, `send_message`, outbound component sweep, storage/list APIs, and safe platform API calls.
+- Real UI sends attempted after the fixes: private text, local file, and image/video image upload. These appeared in the Feishu client but did not append new `EBAEventProbe` records in the local JSONL during this run.
+- Fixes from live testing: reply path now extracts the native Feishu `message_id` from legacy-wrapped source events; WebSocket callbacks are scheduled onto the adapter event loop instead of assuming the SDK callback has a running asyncio loop; platform API results are converted to JSON-safe values.
+
+Live E2E items still required before marking release-complete:
+
+- WebSocket self-built app in LangBot organization: repeat private text after callback-loop fix, plus private image/file/audio and group mention message received by `EBAEventProbe`.
+- Webhook self-built app in LangBot organization: URL verification plus text/image/file message received by `EBAEventProbe`.
+- Store app token path: at least token acquisition/tenant-token safe API through `call_platform_api`; full message E2E if a LangBot organization store-app fixture is available.
+- Outbound component sweep: text, mention, at-all, image, file, voice where Feishu accepts the fixture, quote/fallback, and forward/fallback.
+- Safe platform API sweep: token check, chat metadata, message lookup, and message resource download using real inbound IDs.
+
+## Known Limits
+
+- Store-app live E2E requires a real ISV app ticket/tenant installation fixture.
+- Current LangBot organization WebSocket run connected successfully but did not deliver the latest UI-sent image/file attempts to local plugin evidence; this blocks release-complete media acceptance.
+- Feishu native emoji/sticker semantics are not represented as common `Face`.
+- Destructive org or chat mutations are not declared in this adapter.

docs/event-based-agents/adapters/officialaccount.md

@@ -0,0 +1,101 @@
+# OfficialAccount EBA Adapter
+
+Adapter directory: `src/langbot/pkg/platform/adapters/officialaccount/`
+
+Manifest name: `officialaccount-eba`
+
+Status: partial migration. Unit/API-shape coverage is present, and private text `plugin-e2e-ui` plus safe API evidence has been verified against the `dev.rockchin.top` Official Account fixture. Proactive outbound `send_message` remains not supported by this adapter because WeChat Official Account replies must be tied to inbound webhook windows.
+
+## Config
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `webhook_url` | no | Generated by LangBot and copied into the Official Account callback settings. |
+| `token` | yes | WeChat callback token. |
+| `EncodingAESKey` | yes | WeChat message encryption key. |
+| `AppID` | yes | Official Account app ID. |
+| `AppSecret` | yes | Official Account app secret. |
+| `Mode` | yes | `drop` waits for an in-callback reply; `passive` returns the loading text first and queues the answer for the user's next message. |
+| `LoadingMessage` | no | Only used by `passive` mode. |
+| `api_base_url` | no | Optional API base URL for proxy deployments. |
+
+## Events
+
+| Event | Evidence | Notes |
+| --- | --- | --- |
+| `message.received` | plugin-e2e-ui, unit | Text UI message verified through WeChat Official Account on `dev.rockchin.top`; image and voice webhook payloads are covered by unit tests. |
+| `platform.specific` | unit | Subscribe/menu/etc. native events are emitted as structured `PlatformSpecificEvent`. |
+
+## Common APIs
+
+| API | Evidence | Notes |
+| --- | --- | --- |
+| `reply_message` | unit | Queues/passively returns text through the inbound webhook source event. |
+| `get_message` | plugin-e2e-ui, unit | Cached inbound message retrieved by `EBAEventProbe` platform API sweep. |
+| `get_user_info` | plugin-e2e-ui, unit | Cached inbound sender retrieved by `EBAEventProbe` platform API sweep. |
+| `get_friend_list` | plugin-e2e-ui, unit | Cached inbound sender list retrieved by `EBAEventProbe` platform API sweep. |
+| `call_platform_api` | plugin-e2e-ui, unit | Safe diagnostic actions verified through `get_mode` and `get_cached_response_status`. |
+| `send_message` | not-supported | Official Account customer-service proactive messaging is not implemented by the existing SDK adapter; only webhook reply is supported here. |
+
+## Platform APIs
+
+| Action | Evidence | Notes |
+| --- | --- | --- |
+| `get_mode` | plugin-e2e-ui, unit | Returned `{"mode": "drop", "longer_response": false}` in live probe. |
+| `get_cached_response_status` | plugin-e2e-ui, unit | Returned `{"pending": false}` in live probe. |
+
+## Components
+
+| Receive Component | Evidence | Notes |
+| --- | --- | --- |
+| `Source` | plugin-e2e-ui, unit | Uses `MsgId` and `CreateTime`; live UI text message included `Source`. |
+| `Plain` | plugin-e2e-ui, unit | Live UI text message mapped to `Plain`. |
+| `Image` | unit | `PicUrl` and `MediaId` map to common `Image`. |
+| `Voice` | unit | `MediaId` maps to common `Voice`. |
+| `Unknown` | unit | Unsupported message/event types do not crash. |
+| `At`, `AtAll`, `File`, `Quote`, `Face`, `Forward`, mixed chain | not-supported | WeChat Official Account inbound webhook payloads used by the current SDK do not expose these as common structured components. |
+
+| Send Component | Evidence | Notes |
+| --- | --- | --- |
+| `Plain` | unit | Sent as webhook reply text. |
+| `Image`, `Voice`, `File`, `Quote`, `At`, `AtAll`, `Face`, `Forward`, mixed chain | not-supported | Existing SDK reply path is text XML only; non-text components degrade to readable placeholders in tests and are not declared as supported outbound components. |
+
+## Verification Record
+
+Test date: 2026-05-28
+
+Endpoint/simulator: `dev.rockchin.top` with WeChat desktop client and a real subscribed Official Account conversation. The running EBA test stack used SDK standalone runtime ports `5400/5401`, LangBot from `/home/wgc/LangBotxg/LangBotEbaTest`, and `EBAEventProbe`.
+
+Verified UI message: `EBA officialaccount single probe 2026-05-28 16:53`
+
+Observed event/API evidence:
+
+- `MessageReceived`: `bot_uuid=d7c46880-a9f8-431a-9172-5d3e0d663dbc`, `adapter_name=officialaccount-eba`, `chat_type=private`, `chat_id=ovH9L7OW6hNpWZWvp_NMmypVh26w`, `message_chain=[Source, Plain]`.
+- Common safe APIs through probe platform sweep: `get_message`, `get_user_info`, `get_friend_list`.
+- Platform APIs through `call_platform_api`: `get_mode`, `get_cached_response_status`.
+- `send_message` and outbound component sweep returned explicit `NotSupportedError: send_message:official_account_requires_inbound_webhook_reply`, as expected for this adapter.
+
+Standalone runtime command:
+
+```bash
+cd langbot-plugin-sdk
+uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
+```
+
+Probe plugin: `data/plugins/LangBot__EBAEventProbe` when live credentials are available.
+
+Adapter live probe:
+
+```bash
+uv run python -m py_compile tests/e2e/live_officialaccount_eba_probe.py
+OFFICIALACCOUNT_TOKEN=... OFFICIALACCOUNT_ENCODING_AES_KEY=... OFFICIALACCOUNT_APP_SECRET=... OFFICIALACCOUNT_APP_ID=... uv run python tests/e2e/live_officialaccount_eba_probe.py
+```
+
+Evidence JSONL path: `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/officialaccount_eba_plugin_probe.jsonl` for plugin E2E, or `data/temp/officialaccount_eba_probe.jsonl` for direct adapter live probe.
+
+Destructive operations: none.
+
+Blocked items:
+
+- `plugin-e2e-outbound`: proactive `send_message` is not supported for this adapter; Official Account responses must be produced through the inbound webhook reply window.
+- Inbound image and voice live UI evidence remains pending; webhook conversion is covered by unit tests.

docs/event-based-agents/adapters/telegram.md

@@ -0,0 +1,139 @@
+# Telegram EBA Adapter
+
+## Status
+
+Telegram has been migrated to the EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/telegram/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `telegram-eba`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `token` | Yes | `""` | Telegram Bot API token from BotFather. |
+| `markdown_card` | No | `true` | Whether to render Markdown card style replies. |
+| `enable-stream-reply` | Yes | `false` | Whether to use Telegram streaming reply mode. |
+
+## Events
+
+Telegram declares these EBA events:
+
+- `message.received`
+- `message.edited`
+- `message.reaction`
+- `group.member_joined`
+- `group.member_left`
+- `group.member_banned`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `bot.muted`
+- `bot.unmuted`
+- `platform.specific`
+
+`platform.specific` is currently used for Telegram-only callback and chat-member update payloads that do not yet have a more specific common event type.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported | Supports text, image, file, and mixed message chains. |
+| `reply_message` | Supported | Supports quoted replies through the original message event. |
+| `edit_message` | Supported | Uses Telegram message editing APIs. |
+| `delete_message` | Supported | Deletes messages where bot permissions allow it. |
+| `forward_message` | Supported | Forwards a message between Telegram chats. |
+| `get_group_info` | Supported | Uses Telegram chat metadata. |
+| `get_group_member_list` | Supported | Telegram only exposes administrators through the Bot API; this returns the available member set. |
+| `get_group_member_info` | Supported | Maps Telegram member status to EBA member roles. |
+| `get_user_info` | Supported | Uses Telegram `get_chat` for user chat metadata. |
+| `upload_file` | Not supported | Telegram has no standalone upload endpoint; files are uploaded as part of messages. The adapter raises `NotSupportedError`. |
+| `get_file_url` | Supported | Returns the Bot API file URL. Test output redacts the bot token. |
+| `mute_member` | Supported | Requires a supergroup and bot moderation permission. |
+| `unmute_member` | Supported | Uses current `telegram.ChatPermissions` fields. |
+| `kick_member` | Supported | Destructive; should only be run against disposable users/bots in tests. |
+| `leave_group` | Supported | Destructive; should run at the end of a live test. |
+| `call_platform_api` | Supported | See below. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `pin_message`
+- `unpin_message`
+- `unpin_all_messages`
+- `get_chat_administrators`
+- `set_chat_title`
+- `set_chat_description`
+- `get_chat_member_count`
+- `send_chat_action`
+- `create_chat_invite_link`
+- `answer_callback_query`
+
+## Live Test Record
+
+The live probe is:
+
+```bash
+uv run python tests/e2e/live_telegram_eba_probe.py --help
+```
+
+It supports private chat tests, group/supergroup tests, moderation tests, destructive tests, and a callback-only mode.
+
+Verified on May 7, 2026:
+
+- Private chat message APIs: send, reply, edit, delete, forward.
+- Private chat media APIs: image/file sending and `get_file_url`.
+- User API: `get_user_info`.
+- Supergroup APIs: group info, member list, member info, administrators, member count, invite link.
+- Supergroup mutation APIs: pin, unpin, unpin all, set title, restore title, set description, restore description.
+- Moderation APIs: mute and unmute against a non-owner target bot.
+- Destructive APIs: kick a disposable target bot, then make the test bot leave the test group.
+- Event conversion observed for `message.received`, `group.member_banned`, `group.member_left`, `bot.removed_from_group`, and Telegram-specific chat-member updates.
+
+The test fixed one real compatibility issue: `unmute_member` previously used Telegram's removed `can_send_media_messages` permission field. It now uses the split media permission fields required by current `python-telegram-bot`.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 10, 2026 with `EBAEventProbe`, SDK standalone runtime, Telegram Lite, `@rockchinq_bot`, and `Rock'sBotGroup`.
+
+Evidence:
+
+- Private chat JSONL: `data/temp/telegram-plugin-e2e-rerun.jsonl`
+- Group chat JSONL: `data/temp/telegram-plugin-e2e-group.jsonl`
+- Private media JSONL: `data/temp/telegram-plugin-e2e-media-ui.jsonl`
+
+Observed and verified:
+
+- `MessageReceived` reached the plugin with `bot_uuid=eba-telegram-live`, `adapter_name=telegram`, common sender/chat fields, and common `MessageChain` content.
+- `BotInvitedToGroup` reached the plugin after adding the bot to `Rock'sBotGroup`.
+- SDK API calls succeeded: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage, workspace storage, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Outbound component sweep succeeded in private and group chats: plain text, mention text/equivalent, base64 image, quoted reply, file/document, and flattened forward fallback. Group mode also covered `AtAll` fallback behavior.
+- Real Telegram Lite private-chat inbound media was verified through the plugin path: a sent document arrived as common `File`, and a sent photo arrived as common `Image`.
+- Telegram platform API sweep succeeded for safe group actions: `get_chat_administrators`, `get_chat_member_count`, and `send_chat_action`.
+- Common group/user APIs succeeded in group mode: `get_user_info`, `get_group_info`, `get_group_member_list`, and `get_group_member_info`.
+
+Documented limits in this E2E run:
+
+- Real Telegram UI inbound voice, sticker/emoji-as-common-component, and reply/quote messages were not completed in the plugin E2E evidence.
+- `get_message`, `get_friend_list`, and `get_group_list` are not supported by this Telegram adapter.
+- Mutating/destructive Telegram-specific actions such as pin/unpin, title/description changes, invite-link creation, moderation, kick, and leave were not repeated in the plugin run. They remain opt-in live-probe cases.
+- Telegram does not expose a portable common `Face` component for native sticker/emoji semantics in the current adapter.
+
+## Notes for Future Adapters
+
+Telegram is the reference implementation for:
+
+- Keeping platform-specific actions behind `call_platform_api`.
+- Treating unsupported common APIs as explicit `NotSupportedError`.
+- Marking destructive live test operations behind CLI flags.
+- Redacting access tokens from live probe output.

docs/event-based-agents/adapters/wecom.md

@@ -0,0 +1,130 @@
+# WeCom EBA Adapter
+
+## Status
+
+WeCom application messages now have an EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/wecom/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `wecom-eba`.
+
+This record covers the regular WeCom application-message adapter. WeCom AI Bot (`wecombot-eba`) uses a different protocol flow and is documented separately in `wecombot.md`. WeCom Customer Service (`wecomcs`) remains a separate follow-up migration.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `webhook_url` | No | `""` | Unified webhook URL copied into the WeCom application callback settings. |
+| `corpid` | Yes | `""` | WeCom corporate ID. |
+| `secret` | Yes | `""` | WeCom application secret. |
+| `token` | Yes | `""` | WeCom callback token. |
+| `EncodingAESKey` | Yes | `""` | WeCom callback encryption key. |
+| `contacts_secret` | No | `""` | Contacts secret for contact-list based helper APIs. |
+| `api_base_url` | No | `https://qyapi.weixin.qq.com/cgi-bin` | WeCom API base URL, overrideable for proxy/private-network deployments. |
+
+## Events
+
+WeCom declares these EBA events:
+
+- `message.received`
+- `platform.specific`
+
+`message.received` currently covers text and image application callbacks. Other WeCom callback types are surfaced as `platform.specific` so plugins can inspect the raw structured payload without crashing the common message path.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported | Private/person target only. `target_id` must be `user_id|agent_id`. Supports text, image, voice, file, flattened forward, and quote fallback. |
+| `reply_message` | Supported | Replies to the original WeCom sender and application agent from `source_platform_object`. |
+| `get_message` | Supported from cache | Returns cached inbound `MessageReceivedEvent` by message ID. |
+| `get_user_info` | Supported | Uses cached event users first, then WeCom `user/get`. |
+| `get_friend_list` | Partial | Returns users seen by this adapter instance. Full contacts listing is not declared as common coverage. |
+| `call_platform_api` | Supported | See below. |
+| `edit_message` | Not supported | WeCom application messages do not expose a general edit endpoint for sent messages. |
+| `delete_message` | Not supported | WeCom application messages do not expose a general delete endpoint for sent messages. |
+| `get_group_info` / member APIs | Not supported | Regular WeCom application callbacks handled here are private user messages, not group-chat bot messages. |
+| `upload_file` / `get_file_url` | Not supported as common APIs | WeCom media upload is used internally while sending image/voice/file components; no portable standalone common file URL is exposed. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `check_access_token`
+- `refresh_access_token`
+- `get_user_info`
+- `send_to_all`
+
+`send_to_all` requires a configured `contacts_secret` with suitable contact visibility and should be treated as a broad-send operation in live testing.
+
+## Unit Verification
+
+Covered by:
+
+```bash
+uv run pytest tests/unit_tests/platform/test_wecom_eba_adapter.py
+```
+
+The unit tests cover:
+
+- Manifest events/APIs/platform actions match adapter declarations.
+- Outbound component conversion for text, image, voice, file, quote fallback, and byte-safe text splitting.
+- Text callback conversion to `MessageReceivedEvent`.
+- Legacy `FriendMessage` compatibility.
+- EBA listener dispatch and inbound message/user cache.
+- `send_message`, `reply_message`, and safe platform API dispatch against a mocked WeCom client.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 27, 2026 with `EBAEventProbe`, SDK standalone runtime, LangBot core, and a real WeCom desktop client against the server test environment.
+
+```bash
+cd langbot-plugin-sdk
+uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
+
+cd LangBot
+uv run main.py --standalone-runtime
+
+cd data/plugins/LangBot__EBAEventProbe
+EBA_PROBE_API=1 EBA_PROBE_COMPONENT_SWEEP=1 EBA_PROBE_PLATFORM_API=1 \
+uv --project /absolute/path/to/langbot-plugin-sdk run python -m langbot_plugin.cli.__init__ run
+```
+
+Evidence:
+
+- JSONL: `data/temp/wecom_eba_plugin_probe.jsonl`
+- Bot: `wecom-eba`
+- Client: real WeCom desktop client
+- Environment: `dev.rockchin.top` test server
+
+Observed and verified:
+
+- A real private WeCom user message reached the plugin as `MessageReceived` with `adapter_name=wecom-eba`, common sender/chat fields, and `Source + Plain`.
+- SDK API calls succeeded through the standalone runtime, including `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin/workspace storage, and manifest/list APIs.
+- Safe adapter API checks succeeded through the plugin path for cached message/user data and declared safe platform API actions.
+
+Still required for stricter acceptance:
+
+- Send a private image and confirm common `Image` reaches the plugin.
+- Have the plugin call `send_message` and `reply_message` for text and one media component, then verify the WeCom client receives the bot output.
+- Exercise `send_to_all` only with a disposable visible-contact scope.
+- Trigger one non-text/image callback, if available, and confirm it becomes `PlatformSpecificEventReceived`.
+
+## Current Acceptance
+
+Current status is **partial EBA acceptance**.
+
+Blocked items:
+
+- Real inbound image/voice/file evidence was not completed in this run.
+- Inbound voice/file callback parsing is not present in the legacy `WecomClient.get_message()` path, so the EBA adapter does not claim those receive components yet.
+- Group/member/moderation APIs do not apply to this regular WeCom application-message adapter.

docs/event-based-agents/adapters/wecombot.md

@@ -0,0 +1,148 @@
+# WeComBot EBA Adapter
+
+## Status
+
+WeCom AI Bot now has an EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/wecombot/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `wecombot-eba`.
+
+This is separate from regular WeCom internal applications (`wecom-eba`). WeComBot supports WebSocket long connection mode, which does not require a webhook URL. Webhook mode remains available when `enable-webhook=true`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `BotId` | Yes for WebSocket mode | `""` | WeCom AI Bot ID. |
+| `robot_name` | Yes | `""` | Bot display name used to strip bot mentions from incoming group text. |
+| `enable-webhook` | Yes | `false` | `false` uses WebSocket long connection mode; `true` uses webhook callback mode. |
+| `webhook_url` | No | `""` | Unified webhook URL, only needed when webhook mode is enabled. |
+| `Secret` | Yes for WebSocket mode | `""` | WeCom AI Bot secret for long connection mode. |
+| `Corpid` | Yes for webhook mode | `""` | WeCom corporate ID for webhook callback mode. |
+| `Token` | Yes for webhook mode | `""` | WeCom callback token. |
+| `EncodingAESKey` | Yes for webhook mode; optional for WebSocket media decrypt | `""` | Message encryption/decryption key. |
+| `enable-stream-reply` | No | `true` | Enables WeComBot streaming replies. |
+
+## Events
+
+WeComBot declares these EBA events:
+
+- `message.received`
+- `feedback.received`
+- `platform.specific`
+
+`message.received` covers private and group messages from the WeComBot SDK. `feedback.received` covers WeComBot like/dislike feedback callbacks. Native SDK events without a common EBA equivalent are emitted as `platform.specific`.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported in WebSocket mode | Sends proactive markdown/text to a person or group chat ID. Webhook mode raises `NotSupportedError` because the platform callback flow has no proactive send path here. |
+| `reply_message` | Supported | Replies through native `req_id` in WebSocket mode or stream finalization/cache in webhook mode. |
+| `get_message` | Supported from cache | Returns cached inbound `MessageReceivedEvent` by message ID. |
+| `get_user_info` | Supported from cache | WeComBot events carry user info; no full user lookup endpoint is declared. |
+| `get_friend_list` | Partial | Returns users observed by this adapter instance. |
+| `get_group_info` | Supported from cache | Returns groups observed from inbound group messages. |
+| `get_group_member_info` | Supported from cache | Returns observed sender/group-member pairs. |
+| `get_group_member_list` | Partial | Returns observed members for the cached group only. |
+| `call_platform_api` | Supported | See below. |
+| `edit_message` / `delete_message` / `forward_message` | Not supported | WeComBot does not expose portable common APIs for these operations in the current SDK wrapper. |
+| `upload_file` / `get_file_url` | Not supported as common APIs | Media is represented inside messages; no portable standalone file upload/URL API is declared. |
+| moderation / leave APIs | Not supported | WeComBot does not expose equivalent common moderation operations through this adapter. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `is_websocket_mode`
+- `get_stream_session_status`
+- `send_markdown`
+
+`send_markdown` is only available in WebSocket mode.
+
+## Unit Verification
+
+Covered by:
+
+```bash
+PYTHONPATH=/Users/wangqiang/code/python/langbot-plugin-sdk/src uv run pytest tests/unit_tests/platform/test_wecombot_eba_adapter.py
+```
+
+The unit tests cover:
+
+- Manifest events/APIs/platform actions match adapter declarations.
+- Outbound common components flatten to WeComBot markdown/text.
+- Private and group native events become `MessageReceivedEvent`.
+- Inbound image, file, voice, and quote components map to common `MessageChain`.
+- Legacy `FriendMessage`/`GroupMessage` compatibility.
+- EBA listener dispatch, message/user/group/member cache, reply, send, streaming chunk, feedback, and platform API calls.
+
+## Live Probe
+
+The direct adapter probe is:
+
+```bash
+PYTHONPATH=/absolute/path/to/langbot-plugin-sdk/src uv run python tests/e2e/live_wecombot_eba_probe.py --help
+```
+
+Default mode is WebSocket long connection and requires:
+
+- `WECOMBOT_BOT_ID`
+- `WECOMBOT_SECRET`
+- `WECOMBOT_ROBOT_NAME`
+- optional `WECOMBOT_ENCODING_AES_KEY`
+
+Webhook mode uses `--webhook` and requires:
+
+- `WECOMBOT_TOKEN`
+- `WECOMBOT_ENCODING_AES_KEY`
+- `WECOMBOT_CORPID`
+
+The probe writes JSONL evidence to `data/temp/wecombot_eba_live_probe.jsonl`, waits for a real WeComBot message, records common EBA event fields and message components, then runs safe cached/common/platform API checks.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 27, 2026 with `EBAEventProbe`, SDK standalone runtime, LangBot core, and the real WeCom desktop client in a WeCom AI Bot private chat.
+
+Evidence:
+
+- JSONL: `data/temp/wecombot_eba_plugin_probe.jsonl`
+- Bot UUID: `9f5d4125-7b6d-4c98-8ca2-111111111111`
+- Adapter: `wecombot-eba`
+- Client: real WeCom desktop client, private `LangBot` BOT chat
+- Mode: WebSocket long connection (`enable-webhook=false`)
+
+Observed and verified:
+
+- A real user-side message reached the plugin as `MessageReceived` with `adapter_name=wecombot-eba`, common sender/chat fields, and `Source + Plain`.
+- SDK API calls succeeded through the standalone runtime: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin/workspace storage, manifest/list APIs, and safe cached common platform APIs.
+- Outbound component sweep was visible in the WeCom client and returned `errcode=0`: plain/mention/face fallback, base64 image marker, quote fallback, file marker, and flattened forward fallback.
+- Declared WeComBot platform APIs succeeded through `plugin.call_platform_api`: `is_websocket_mode`, `get_stream_session_status`, and `send_markdown`.
+- The `send_markdown` platform API produced visible bot output in the WeCom client.
+
+Not completed:
+
+- Clicking the visible WeCom AI feedback button did not produce a `FeedbackReceived` JSONL entry in this run, so `feedback.received` remains unverified at plugin E2E level.
+- Group chat inbound and group cache/member coverage still need a real group-side trigger.
+- Real inbound image/file/voice from the WeCom client was not exercised.
+
+## Current Acceptance
+
+Current status is **partial EBA acceptance**.
+
+Blocked or limited items:
+
+- `feedback.received` is implemented and unit-covered, but real plugin E2E feedback evidence was not observed from the desktop client click.
+- Outbound image/voice/file are flattened as textual markers because the WeComBot SDK reply/proactive path used here is markdown/text oriented.
+- Group member APIs are cache-backed and only know members observed in received messages.
+- Destructive or moderation APIs are not declared because the current WeComBot protocol surface does not provide safe common equivalents.

docs/event-based-agents/adapters/wecomcs.md

@@ -0,0 +1,161 @@
+# WeCom Customer Service EBA Adapter
+
+## Status
+
+WeCom Customer Service now has an EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/wecomcs/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `wecomcs-eba`. It is separate from regular WeCom application messages (`wecom-eba`) and WeCom AI Bot (`wecombot-eba`).
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `webhook_url` | No | `""` | Unified webhook URL copied into the WeCom Customer Service callback settings. |
+| `corpid` | Yes | `""` | WeCom corporate ID. |
+| `secret` | Yes | `""` | Customer Service secret used for access tokens. |
+| `token` | Yes | `""` | Customer Service callback token. |
+| `EncodingAESKey` | Yes | `""` | Customer Service callback encryption key. |
+| `api_base_url` | No | `https://qyapi.weixin.qq.com/cgi-bin` | WeCom API base URL, overrideable for proxy/private-network deployments. |
+
+## Events
+
+| Event | Status | Notes |
+|-------|--------|-------|
+| `message.received` | Plugin E2E UI covered for text | Text, image, file, and voice payloads convert to common EBA message components in unit tests. Real WeChat customer-side UI text reached `EBAEventProbe` on May 27, 2026. |
+| `platform.specific` | Unit covered | Non-message or unknown Customer Service payloads become structured `PlatformSpecificEvent` records. |
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Plugin E2E outbound covered | Private/person target only. `target_id` must be `external_userid|open_kfid`. Text and image are implemented; voice/file are explicitly unsupported. |
+| `reply_message` | Plugin E2E partial | Replies through Customer Service `kf/send_msg` using the original `source_platform_object`. The pipeline reply path reached the send API, but the dev account later hit WeCom `95001 send msg count limit`. |
+| `get_message` | Plugin E2E covered from cache | Returns cached inbound `MessageReceivedEvent` by message ID. |
+| `get_user_info` | Plugin E2E covered | Uses cached event users first, then Customer Service `customer/batchget`. |
+| `get_friend_list` | Plugin E2E covered, partial | Returns customer users seen by this adapter instance. |
+| `call_platform_api` | Unit covered | See platform-specific APIs below. |
+| `edit_message` / `delete_message` | Not supported | WeCom Customer Service does not expose a general edit/delete endpoint for bot-sent messages in this adapter. |
+| Group/member/moderation APIs | Not supported | Customer Service conversations handled here are private customer sessions, not group chats. |
+| `upload_file` / `get_file_url` | Not supported | Media upload is used internally for outbound image; no portable file URL common API is exposed. |
+
+## Platform-Specific APIs
+
+| Action | Status | Notes |
+|--------|--------|-------|
+| `check_access_token` | Unit covered | Checks whether the current access token is present. |
+| `refresh_access_token` | Unit covered | Refreshes the Customer Service access token. |
+| `get_customer_info` | Unit covered | Calls Customer Service customer lookup by `external_userid`. |
+
+## Message Components
+
+Receive:
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `Source` | Unit covered | Uses Customer Service `msgid` and `send_time`. |
+| `Plain` | Unit covered | Text payload content is preserved. |
+| `Image` | Unit covered | Uses the base64 data URL produced by the existing SDK image download path. |
+| `Voice` | Unit covered | Maps exposed voice media ID to common `Voice.voice_id`; live UI evidence pending. |
+| `File` | Unit covered | Maps exposed file media ID/name/size to common `File`; live UI evidence pending. |
+| `Quote`, `At`, `AtAll`, `Face`, `Forward` | Not supported inbound | The current Customer Service SDK event model does not expose these as structured inbound fields. |
+| `Unknown` | Unit covered | Unsupported message types become `Unknown` in message conversion or `platform.specific` at event level. |
+
+Send:
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `Plain` | Plugin E2E outbound covered | Sends through `kf/send_msg` text. |
+| `Image` | Plugin E2E outbound covered | Uploads media as WeCom image media and sends through `kf/send_msg` image. |
+| `Quote`, `At`, `AtAll`, `Forward` | Unit covered fallback, live partially blocked | Flattened to text where possible. In the May 27 sweep, later text sends hit WeCom `95001 send msg count limit` after the successful text/image sends. |
+| `Voice`, `File`, `Face` | Not supported | The adapter raises `NotSupportedError`; no tested Customer Service send path is implemented. |
+
+## Unit Verification
+
+Covered by:
+
+```bash
+PYTHONPATH=/Users/wangqiang/code/python/langbot-plugin-sdk/src uv run pytest tests/unit_tests/platform/test_wecomcs_eba_adapter.py
+```
+
+Result on May 27, 2026: `10 passed`.
+
+The local `PYTHONPATH` is required in this workspace because the installed SDK package in the LangBot venv does not contain the newer `langbot_plugin.api.entities.builtin.platform.errors` module; the existing EBA adapter tests need the same SDK override.
+
+## Live Probe
+
+Auxiliary direct adapter probe:
+
+```bash
+PYTHONPATH=/path/to/langbot-plugin-sdk/src uv run python -m py_compile tests/e2e/live_wecomcs_eba_probe.py
+
+WECOMCS_CORPID=... \
+WECOMCS_SECRET=... \
+WECOMCS_TOKEN=... \
+WECOMCS_ENCODING_AES_KEY=... \
+PYTHONPATH=/path/to/langbot-plugin-sdk/src \
+uv run python tests/e2e/live_wecomcs_eba_probe.py \
+  --path /wecomcs/callback \
+  --log data/temp/wecomcs_eba_live_probe.jsonl
+```
+
+This probe is diagnostic only. Final EBA acceptance still requires the standalone SDK runtime plus `EBAEventProbe` plugin path.
+
+## Standalone Runtime Plugin E2E Record
+
+Completed partial plugin E2E on May 27, 2026 against `dev.rockchin.top` and the WeChat customer-side UI entry `微信 -> 客服消息 -> 浪波智能客服`.
+
+Evidence:
+
+- Server JSONL: `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/wecomcs_eba_plugin_probe.jsonl`
+- Trigger text: `EBA wecomcs dedupe probe 2026-05-27`
+- `bot_uuid`: `cc810d2c-91f3-4f92-8f27-e1bf9f7b6cb4`
+- `adapter_name`: `wecomcs-eba`
+- Observed common event: `MessageReceived`, `event.type=message.received`
+- Observed message chain: `Source + Plain`
+- Observed chat: `chat_type=private`, `chat_id=external_userid|open_kfid`
+- Observed sender: customer `User` with nickname/avatar from Customer Service lookup
+- Plugin API probe: `send_message`, `get_message`, `get_user_info`, `get_friend_list`, plugin/workspace storage, and manifest/list APIs succeeded
+- Component sweep: outbound `Plain` and `Image` succeeded; `Face` and `File` returned explicit `NotSupportedError`; later quote/forward fallback sends were blocked by WeCom `95001 send msg count limit`
+
+Command shape used:
+
+```bash
+cd langbot-plugin-sdk
+uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
+
+cd LangBot
+PYTHONPATH=/absolute/path/to/langbot-plugin-sdk/src uv run main.py --standalone-runtime
+
+cd data/plugins/LangBot__EBAEventProbe
+DEBUG_RUNTIME_WS_URL=ws://127.0.0.1:5401/plugin/ws \
+EBA_PROBE_LOG=/absolute/path/to/LangBot/data/temp/wecomcs_eba_plugin_probe.jsonl \
+EBA_PROBE_API=1 \
+EBA_PROBE_COMPONENT_SWEEP=1 \
+EBA_PROBE_PLATFORM_API=1 \
+uv --project /absolute/path/to/langbot-plugin-sdk run python -m langbot_plugin.cli.__init__ run
+```
+
+Required real UI trigger: send a Customer Service message from the WeCom/WeChat customer-side UI to the configured `dev.rockchin.top` Customer Service account.
+
+## Current Acceptance
+
+Current status is **partial EBA acceptance**.
+
+Blocked or pending items:
+
+- Inbound UI media (`Image`, `Voice`, `File`) was not sent from the real WeChat customer UI during this run, so receive-side media remains unit-covered only.
+- Pipeline auto-reply reached `kf/send_msg`, but the test account hit WeCom `95001 send msg count limit` after successful plugin outbound text/image sends. This is recorded as an account/platform rate-limit block, not a conversion or API-shape failure.
+- The current `EBAEventProbe` run did not call the adapter-specific `call_platform_api` actions (`check_access_token`, `refresh_access_token`, `get_customer_info`); the platform API map remains unit-covered.
+- Inbound voice/file depends on whether the real Customer Service callback plus `sync_msg` endpoint returns those fields in the shape the local SDK models.
+- Group, member, edit, delete, moderation, and standalone file URL APIs are intentionally not declared because this Customer Service protocol path does not provide tested common equivalents.

pyproject.toml

@@ -117,7 +117,7 @@ requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-package-data = { "langbot" = ["templates/**", "pkg/provider/modelmgr/requesters/*", "pkg/platform/sources/*", "web/dist/**", "pkg/persistence/alembic/**"] }
+package-data = { "langbot" = ["templates/**", "pkg/provider/modelmgr/requesters/*", "pkg/platform/sources/*", "pkg/platform/adapters/**", "web/dist/**", "pkg/persistence/alembic/**"] }
 
 [dependency-groups]
 dev = [
@@ -221,4 +221,3 @@ skip-magic-trailing-comma = false
 
 # Like Black, automatically detect the appropriate line ending.
 line-ending = "auto"
-

src/langbot/libs/dingtalk_api/api.py

@@ -438,8 +438,13 @@ class DingTalkClient:
         try:
             async with httpx.AsyncClient() as client:
                 response = await client.post(url, headers=headers, json=data)
+                try:
+                    body = response.json()
+                except Exception:
+                    body = {'text': response.text}
                 if response.status_code == 200:
-                    return
+                    return body
+                raise Exception(f'Error: {response.status_code}, {body}')
         except Exception:
             await self.logger.error(f'failed to send proactive massage to person: {traceback.format_exc()}')
             raise Exception(f'failed to send proactive massage to person: {traceback.format_exc()}')
@@ -464,8 +469,13 @@ class DingTalkClient:
         try:
             async with httpx.AsyncClient() as client:
                 response = await client.post(url, headers=headers, json=data)
+                try:
+                    body = response.json()
+                except Exception:
+                    body = {'text': response.text}
                 if response.status_code == 200:
-                    return
+                    return body
+                raise Exception(f'Error: {response.status_code}, {body}')
         except Exception:
             await self.logger.error(f'failed to send proactive massage to group: {traceback.format_exc()}')
             raise Exception(f'failed to send proactive massage to group: {traceback.format_exc()}')

src/langbot/libs/official_account_api/api.py

@@ -93,15 +93,30 @@ class OAClient:
                 raise Exception('msg_signature不在请求体中')
 
             if req.method == 'GET':
-                # 校验签名
+                if msg_signature:
+                    wxcpt = WXBizMsgCrypt(self.token, self.aes, self.appid)
+                    ret, reply_echo = wxcpt.VerifyURL(msg_signature, timestamp, nonce, echostr)
+                    if ret == 0:
+                        return reply_echo
+                    await self.logger.error(
+                        'OfficialAccount encrypted URL verification failed: '
+                        f'ret={ret}, timestamp_present={bool(timestamp)}, nonce_present={bool(nonce)}, '
+                        f'echostr_present={bool(echostr)}'
+                    )
+
+                # Plaintext callback verification.
                 check_str = ''.join(sorted([self.token, timestamp, nonce]))
                 check_signature = hashlib.sha1(check_str.encode('utf-8')).hexdigest()
 
                 if check_signature == signature:
                     return echostr  # 验证成功返回echostr
                 else:
-                    await self.logger.error('拒绝请求')
+                    await self.logger.error(
-                    raise Exception('拒绝请求')
+                        'OfficialAccount plaintext URL verification failed: '
+                        f'signature_present={bool(signature)}, timestamp_present={bool(timestamp)}, '
+                        f'nonce_present={bool(nonce)}, echostr_present={bool(echostr)}'
+                    )
+                    return 'signature verification failed', 403
             elif req.method == 'POST':
                 encryt_msg = await req.data
                 wxcpt = WXBizMsgCrypt(self.token, self.aes, self.appid)
@@ -279,9 +294,27 @@ class OAClientForLongerResponse:
                 raise Exception('msg_signature不在请求体中')
 
             if req.method == 'GET':
+                if msg_signature:
+                    wxcpt = WXBizMsgCrypt(self.token, self.aes, self.appid)
+                    ret, reply_echo = wxcpt.VerifyURL(msg_signature, timestamp, nonce, echostr)
+                    if ret == 0:
+                        return reply_echo
+                    await self.logger.error(
+                        'OfficialAccount encrypted URL verification failed: '
+                        f'ret={ret}, timestamp_present={bool(timestamp)}, nonce_present={bool(nonce)}, '
+                        f'echostr_present={bool(echostr)}'
+                    )
+
                 check_str = ''.join(sorted([self.token, timestamp, nonce]))
                 check_signature = hashlib.sha1(check_str.encode('utf-8')).hexdigest()
-                return echostr if check_signature == signature else '拒绝请求'
+                if check_signature == signature:
+                    return echostr
+                await self.logger.error(
+                    'OfficialAccount plaintext URL verification failed: '
+                    f'signature_present={bool(signature)}, timestamp_present={bool(timestamp)}, '
+                    f'nonce_present={bool(nonce)}, echostr_present={bool(echostr)}'
+                )
+                return 'signature verification failed', 403
 
             elif req.method == 'POST':
                 encryt_msg = await req.data

src/langbot/libs/wecom_ai_bot_api/api.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 import base64
 import json
@@ -7,7 +9,7 @@ import uuid
 import xml.etree.ElementTree as ET
 from dataclasses import dataclass, field
 import re
-from typing import Any, Callable, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Optional, Tuple
 from urllib.parse import unquote
 
 import httpx
@@ -16,7 +18,9 @@ from quart import Quart, request, Response, jsonify
 
 from langbot.libs.wecom_ai_bot_api import wecombotevent
 from langbot.libs.wecom_ai_bot_api.WXBizMsgCrypt3 import WXBizMsgCrypt
-from langbot.pkg.platform.logger import EventLogger
+
+if TYPE_CHECKING:
+    from langbot.pkg.platform.logger import EventLogger
 
 
 @dataclass

src/langbot/libs/wecom_ai_bot_api/ws_client.py

@@ -15,13 +15,15 @@ import json
 import secrets
 import time
 import traceback
-from typing import Any, Callable, Optional
+from typing import TYPE_CHECKING, Any, Callable, Optional
 
 import aiohttp
 
 from langbot.libs.wecom_ai_bot_api import wecombotevent
 from langbot.libs.wecom_ai_bot_api.api import parse_wecom_bot_message, StreamSession
-from langbot.pkg.platform.logger import EventLogger
+
+if TYPE_CHECKING:
+    from langbot.pkg.platform.logger import EventLogger
 
 DEFAULT_WS_URL = 'wss://openws.work.weixin.qq.com'
 

src/langbot/libs/wecom_customer_service_api/api.py

@@ -207,7 +207,33 @@ class WecomCSClient:
                 return await self.send_text_msg(open_kfid, external_userid, msgid, content)
             if data['errcode'] != 0:
                 await self.logger.error(f'发送消息失败：{data}')
-                raise Exception('Failed to send message')
+                raise Exception(f'Failed to send message: {data}')
+            return data
+
+    async def send_image_msg(self, open_kfid: str, external_userid: str, msgid: str, media_id: str):
+        if not await self.check_access_token():
+            self.access_token = await self.get_access_token(self.secret)
+
+        url = f'{self.base_url}/kf/send_msg?access_token={self.access_token}'
+        payload = {
+            'touser': external_userid,
+            'open_kfid': open_kfid,
+            'msgid': msgid,
+            'msgtype': 'image',
+            'image': {
+                'media_id': media_id,
+            },
+        }
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(url, json=payload)
+            data = response.json()
+            if data['errcode'] == 40014 or data['errcode'] == 42001:
+                self.access_token = await self.get_access_token(self.secret)
+                return await self.send_image_msg(open_kfid, external_userid, msgid, media_id)
+            if data['errcode'] != 0:
+                await self.logger.error(f'发送图片消息失败：{data}')
+                raise Exception('Failed to send image message')
             return data
 
     async def handle_callback_request(self):
@@ -322,7 +348,7 @@ class WecomCSClient:
         if not await self.check_access_token():
             self.access_token = await self.get_access_token(self.secret)
 
-        url = self.base_url + '/media/upload?access_token=' + self.access_token + '&type=file'
+        url = self.base_url + '/media/upload?access_token=' + self.access_token + '&type=image'
         file_bytes = None
         file_name = 'uploaded_file.txt'
 
@@ -368,7 +394,7 @@ class WecomCSClient:
                 self.access_token = await self.get_access_token(self.secret)
                 media_id = await self.upload_to_work(image)
             if data.get('errcode', 0) != 0:
-                raise Exception('failed to upload file')
+                raise Exception(f'failed to upload image: {data}')
 
             media_id = data.get('media_id')
             return media_id

src/langbot/pkg/api/http/service/bot.py

@@ -5,6 +5,7 @@ import sqlalchemy
 import typing
 
 from ....core import app
+from ....discover import engine
 from ....entity.persistence import bot as persistence_bot
 from ....entity.persistence import pipeline as persistence_pipeline
 
@@ -17,6 +18,24 @@ class BotService:
     def __init__(self, ap: app.Application) -> None:
         self.ap = ap
 
+    def _get_adapter_component(self, adapter_name: str) -> engine.Component | None:
+        """Return the discovered platform adapter component for an adapter name."""
+        for component in self.ap.discover.get_components_by_kind('MessagePlatformAdapter'):
+            if component.metadata.name == adapter_name:
+                return component
+        return None
+
+    def _adapter_declares_webhook_url(self, adapter_name: str) -> bool:
+        """Whether the adapter manifest declares a generated webhook URL config item."""
+        component = self._get_adapter_component(adapter_name)
+        if component is None:
+            return False
+
+        for config_item in component.spec.get('config', []):
+            if config_item.get('type') == 'webhook-url':
+                return True
+        return False
+
     async def get_bots(self, include_secret: bool = True) -> list[dict]:
         """获取所有机器人"""
         result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(persistence_bot.Bot))
@@ -58,17 +77,10 @@ class BotService:
         if runtime_bot is not None:
             adapter_runtime_values['bot_account_id'] = runtime_bot.adapter.bot_account_id
 
-        # Webhook URL for unified webhook adapters (independent of bot running state)
+        # Webhook URL for adapters that declare a generated webhook config item.
-        if persistence_bot['adapter'] in [
+        # This is manifest-driven so EBA adapters do not need to be mirrored in a
-            'wecom',
+        # second hard-coded list.
-            'wecombot',
+        if self._adapter_declares_webhook_url(persistence_bot['adapter']):
-            'officialaccount',
-            'qqofficial',
-            'slack',
-            'wecomcs',
-            'LINE',
-            'lark',
-        ]:
             webhook_prefix = self.ap.instance_config.data['api'].get('webhook_prefix', 'http://127.0.0.1:5300')
             extra_webhook_prefix = self.ap.instance_config.data['api'].get('extra_webhook_prefix', '')
             webhook_url = f'/bots/{bot_uuid}'

src/langbot/pkg/discover/engine.py

@@ -241,12 +241,14 @@ class ComponentDiscoveryEngine:
                 return
 
             for file in importutil.list_resource_files(path):
-                if (not os.path.isdir(os.path.join(path, file))) and (file.endswith('.yaml') or file.endswith('.yml')):
+                file_path = os.path.join(path, file)
-                    comp = self.load_component_manifest(os.path.join(path, file), owner, no_save)
+                is_dir = importutil.is_resource_dir(file_path)
+                if (not is_dir) and (file.endswith('.yaml') or file.endswith('.yml')):
+                    comp = self.load_component_manifest(file_path, owner, no_save)
                     if comp is not None:
                         components.append(comp)
-                elif os.path.isdir(os.path.join(path, file)):
+                elif is_dir:
-                    recursive_load_component_manifests_in_dir(os.path.join(path, file), depth + 1)
+                    recursive_load_component_manifests_in_dir(file_path, depth + 1)
 
         recursive_load_component_manifests_in_dir(path)
         return components

src/langbot/pkg/pipeline/preproc/preproc.py

@@ -163,13 +163,21 @@ class PreProcessor(stage.PipelineStage):
 
         plain_text = ''
         quote_msg = query.pipeline_config['trigger'].get('misc', '').get('combine-quote-message')
+        local_agent_without_vision = (
+            selected_runner == 'local-agent'
+            and llm_model
+            and not llm_model.model_entity.abilities.__contains__('vision')
+        )
 
         for me in query.message_chain:
             if isinstance(me, platform_message.Plain):
                 content_list.append(provider_message.ContentElement.from_text(me.text))
                 plain_text += me.text
             elif isinstance(me, platform_message.Image):
-                if selected_runner != 'local-agent' or (
+                if local_agent_without_vision:
+                    content_list.append(provider_message.ContentElement.from_text('[Image]'))
+                    plain_text += '[Image]'
+                elif selected_runner != 'local-agent' or (
                     llm_model and llm_model.model_entity.abilities.__contains__('vision')
                 ):
                     if me.base64 is not None:
@@ -190,7 +198,10 @@ class PreProcessor(stage.PipelineStage):
                     if isinstance(msg, platform_message.Plain):
                         content_list.append(provider_message.ContentElement.from_text(msg.text))
                     elif isinstance(msg, platform_message.Image):
-                        if selected_runner != 'local-agent' or (
+                        if local_agent_without_vision:
+                            content_list.append(provider_message.ContentElement.from_text('[Image]'))
+                            plain_text += '[Image]'
+                        elif selected_runner != 'local-agent' or (
                             llm_model and llm_model.model_entity.abilities.__contains__('vision')
                         ):
                             if msg.base64 is not None:

src/langbot/pkg/platform/adapters/aiocqhttp/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from langbot.pkg.platform.adapters.aiocqhttp.adapter import AiocqhttpAdapter
+
+__all__ = ['AiocqhttpAdapter']

src/langbot/pkg/platform/adapters/aiocqhttp/adapter.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import asyncio
+import traceback
+import typing
+
+import aiocqhttp
+import pydantic
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot.pkg.platform.adapters.aiocqhttp.api_impl import AiocqhttpAPIMixin
+from langbot.pkg.platform.adapters.aiocqhttp.event_converter import AiocqhttpEventConverter
+from langbot.pkg.platform.adapters.aiocqhttp.message_converter import AiocqhttpMessageConverter
+from langbot.pkg.platform.adapters.aiocqhttp.platform_api import PLATFORM_API_MAP
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class AiocqhttpAdapter(AiocqhttpAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    bot: aiocqhttp.CQHttp = pydantic.Field(exclude=True)
+
+    message_converter: AiocqhttpMessageConverter = AiocqhttpMessageConverter()
+    event_converter: AiocqhttpEventConverter = AiocqhttpEventConverter()
+
+    config: dict
+    listeners: dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = {}
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        run_config = dict(config)
+
+        async def shutdown_trigger_placeholder():
+            while True:
+                await asyncio.sleep(1)
+
+        run_config['shutdown_trigger'] = shutdown_trigger_placeholder
+        access_token = run_config.pop('access-token', '') or None
+        bot = aiocqhttp.CQHttp(access_token=access_token)
+
+        super().__init__(
+            config=run_config,
+            logger=logger,
+            bot=bot,
+            bot_account_id='',
+            listeners={},
+        )
+        self._register_native_handlers()
+
+    def get_supported_events(self) -> list[str]:
+        return [
+            'message.received',
+            'message.deleted',
+            'group.member_joined',
+            'group.member_left',
+            'group.member_banned',
+            'friend.request_received',
+            'friend.added',
+            'bot.invited_to_group',
+            'bot.removed_from_group',
+            'bot.muted',
+            'bot.unmuted',
+            'platform.specific',
+        ]
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'send_message',
+            'reply_message',
+            'delete_message',
+            'forward_message',
+            'get_message',
+            'get_group_info',
+            'get_group_list',
+            'get_group_member_list',
+            'get_group_member_info',
+            'set_group_name',
+            'get_user_info',
+            'get_friend_list',
+            'approve_friend_request',
+            'approve_group_invite',
+            'mute_member',
+            'unmute_member',
+            'kick_member',
+            'leave_group',
+            'call_platform_api',
+        ]
+
+    async def call_platform_api(self, action: str, params: dict = {}) -> dict:
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            raise NotSupportedError(f'call_platform_api:{action}')
+        return await handler(self.bot, params)
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        registered = self.listeners.get(event_type)
+        if registered is callback:
+            self.listeners.pop(event_type, None)
+
+    async def run_async(self):
+        await self.bot._server_app.run_task(**self.config)
+
+    async def kill(self) -> bool:
+        return False
+
+    def _register_native_handlers(self):
+        @self.bot.on_message()
+        async def on_message(event: aiocqhttp.Event):
+            await self._handle_native_event(event)
+
+        @self.bot.on_notice()
+        async def on_notice(event: aiocqhttp.Event):
+            await self._handle_native_event(event)
+
+        @self.bot.on_request()
+        async def on_request(event: aiocqhttp.Event):
+            await self._handle_native_event(event)
+
+        @self.bot.on_websocket_connection
+        async def on_websocket_connection(event: aiocqhttp.Event):
+            self.bot_account_id = str(getattr(event, 'self_id', '') or self.bot_account_id)
+            await self.logger.info(f'WebSocket connection established, bot id: {self.bot_account_id}')
+            await self._dispatch_native_event(event)
+
+    async def _handle_native_event(self, event: aiocqhttp.Event):
+        self.bot_account_id = str(getattr(event, 'self_id', '') or self.bot_account_id)
+        if getattr(event, 'type', None) == 'message' and str(getattr(event, 'user_id', '')) == self.bot_account_id:
+            return
+        try:
+            if getattr(event, 'type', None) == 'message' and (
+                platform_events.FriendMessage in self.listeners or platform_events.GroupMessage in self.listeners
+            ):
+                legacy_event = await self.event_converter.target2legacy(event, self.bot)
+                if legacy_event:
+                    callback = self.listeners.get(type(legacy_event))
+                    if callback:
+                        await callback(legacy_event, self)
+            await self._dispatch_native_event(event)
+        except Exception:
+            await self.logger.error(f'Error in aiocqhttp native event: {traceback.format_exc()}')
+
+    async def _dispatch_native_event(self, event: aiocqhttp.Event):
+        eba_event = await self.event_converter.target2yiri(event, self.bot, self.bot_account_id)
+        if eba_event:
+            await self._dispatch_eba_event(eba_event)
+
+    async def _dispatch_eba_event(self, event: platform_events.EBAEvent):
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return

src/langbot/pkg/platform/adapters/aiocqhttp/api_impl.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import typing
+
+import aiocqhttp
+
+from langbot.pkg.platform.adapters.aiocqhttp.event_converter import AiocqhttpEventConverter
+from langbot.pkg.platform.adapters.aiocqhttp.message_converter import AiocqhttpMessageConverter
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class AiocqhttpAPIMixin:
+    bot: aiocqhttp.CQHttp
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ) -> platform_events.MessageResult:
+        forward = message.get_first(platform_message.Forward)
+        if forward and target_type == 'group':
+            raw = await self._send_forward_message(int(target_id), typing.cast(platform_message.Forward, forward))
+            return platform_events.MessageResult(message_id=raw.get('message_id'), raw=raw)
+
+        aiocq_msg, _, _ = await AiocqhttpMessageConverter.yiri2target(message)
+        if target_type == 'group':
+            raw = await self.bot.send_group_msg(group_id=int(target_id), message=aiocq_msg)
+        elif target_type in ('person', 'private'):
+            raw = await self.bot.send_private_msg(user_id=int(target_id), message=aiocq_msg)
+        else:
+            raise ValueError(f'Unsupported aiocqhttp target_type: {target_type}')
+        return platform_events.MessageResult(message_id=(raw or {}).get('message_id'), raw=raw or {})
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ) -> platform_events.MessageResult:
+        assert isinstance(message_source.source_platform_object, aiocqhttp.Event)
+        aiocq_msg, _, _ = await AiocqhttpMessageConverter.yiri2target(message)
+        if quote_origin:
+            source_id = getattr(message_source, 'message_id', None) or message_source.message_chain.message_id
+            aiocq_msg = aiocqhttp.MessageSegment.reply(source_id) + aiocq_msg
+        raw = await self.bot.send(message_source.source_platform_object, aiocq_msg)
+        return platform_events.MessageResult(message_id=(raw or {}).get('message_id'), raw=raw or {})
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        await self.bot.delete_msg(message_id=int(message_id))
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> platform_events.MessageResult:
+        raw_message = await self.bot.get_msg(message_id=int(message_id))
+        target_message = aiocqhttp.Message(raw_message.get('message', []))
+        if to_chat_type == 'group':
+            raw = await self.bot.send_group_msg(group_id=int(to_chat_id), message=target_message)
+        elif to_chat_type in ('person', 'private'):
+            raw = await self.bot.send_private_msg(user_id=int(to_chat_id), message=target_message)
+        else:
+            raise ValueError(f'Unsupported aiocqhttp to_chat_type: {to_chat_type}')
+        return platform_events.MessageResult(message_id=(raw or {}).get('message_id'), raw=raw or {})
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> platform_events.MessageReceivedEvent:
+        raw = await self.bot.get_msg(message_id=int(message_id))
+        message_type = raw.get('message_type') or chat_type
+        event = aiocqhttp.Event.from_payload(
+            {
+                'post_type': 'message',
+                'message_type': 'group' if message_type == 'group' else 'private',
+                'sub_type': raw.get('sub_type', 'normal'),
+                'time': raw.get('time', 0),
+                'self_id': self.bot_account_id or 0,
+                'message_id': raw.get('message_id', message_id),
+                'user_id': raw.get('sender', {}).get('user_id') or raw.get('user_id') or chat_id,
+                'group_id': raw.get('group_id') or (chat_id if message_type == 'group' else None),
+                'message': raw.get('message', []),
+                'raw_message': raw.get('raw_message', ''),
+                'sender': raw.get('sender', {}),
+            }
+        )
+        return await AiocqhttpEventConverter.message_to_eba(event, self.bot)
+
+    async def get_group_info(self, group_id: typing.Union[int, str]) -> platform_entities.UserGroup:
+        raw = await self.bot.get_group_info(group_id=int(group_id))
+        return platform_entities.UserGroup(
+            id=raw.get('group_id', group_id),
+            name=raw.get('group_name', ''),
+            member_count=raw.get('member_count'),
+        )
+
+    async def get_group_list(self) -> list[platform_entities.UserGroup]:
+        raw_list = await self.bot.get_group_list()
+        return [
+            platform_entities.UserGroup(
+                id=item.get('group_id', ''),
+                name=item.get('group_name', ''),
+                member_count=item.get('member_count'),
+            )
+            for item in raw_list
+        ]
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        raw_list = await self.bot.get_group_member_list(group_id=int(group_id))
+        return [self._member_to_entity(item, group_id) for item in raw_list]
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        raw = await self.bot.get_group_member_info(group_id=int(group_id), user_id=int(user_id), no_cache=True)
+        return self._member_to_entity(raw, group_id)
+
+    async def set_group_name(self, group_id: typing.Union[int, str], name: str) -> None:
+        await self.bot.set_group_name(group_id=int(group_id), group_name=name)
+
+    async def mute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        await self.bot.set_group_ban(group_id=int(group_id), user_id=int(user_id), duration=int(duration))
+
+    async def unmute_member(self, group_id: typing.Union[int, str], user_id: typing.Union[int, str]) -> None:
+        await self.bot.set_group_ban(group_id=int(group_id), user_id=int(user_id), duration=0)
+
+    async def kick_member(self, group_id: typing.Union[int, str], user_id: typing.Union[int, str]) -> None:
+        await self.bot.set_group_kick(group_id=int(group_id), user_id=int(user_id), reject_add_request=False)
+
+    async def leave_group(self, group_id: typing.Union[int, str]) -> None:
+        await self.bot.set_group_leave(group_id=int(group_id), is_dismiss=False)
+
+    async def get_user_info(self, user_id: typing.Union[int, str]) -> platform_entities.User:
+        raw = await self.bot.get_stranger_info(user_id=int(user_id), no_cache=True)
+        return platform_entities.User(
+            id=raw.get('user_id', user_id),
+            nickname=raw.get('nickname', ''),
+            avatar_url=raw.get('avatar_url'),
+        )
+
+    async def get_friend_list(self) -> list[platform_entities.User]:
+        raw_list = await self.bot.get_friend_list()
+        return [
+            platform_entities.User(
+                id=item.get('user_id', ''),
+                nickname=item.get('nickname', ''),
+                remark=item.get('remark'),
+            )
+            for item in raw_list
+        ]
+
+    async def approve_friend_request(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        await self.bot.set_friend_add_request(flag=str(request_id), approve=approve, remark=remark or '')
+
+    async def approve_group_invite(self, request_id: typing.Union[int, str], approve: bool = True) -> None:
+        await self.bot.set_group_add_request(flag=str(request_id), sub_type='invite', approve=approve, reason='')
+
+    async def upload_file(self, file_data: bytes, filename: str) -> str:
+        raise NotSupportedError('upload_file')
+
+    async def get_file_url(self, file_id: str) -> str:
+        raise NotSupportedError('get_file_url')
+
+    @staticmethod
+    def _member_to_entity(raw: dict, group_id: typing.Union[int, str]) -> platform_entities.UserGroupMember:
+        role = platform_entities.MemberRole.MEMBER
+        if raw.get('role') == 'owner':
+            role = platform_entities.MemberRole.OWNER
+        elif raw.get('role') == 'admin':
+            role = platform_entities.MemberRole.ADMIN
+        return platform_entities.UserGroupMember(
+            user=platform_entities.User(
+                id=raw.get('user_id', ''),
+                nickname=raw.get('nickname', ''),
+                remark=raw.get('card') or raw.get('remark'),
+            ),
+            group_id=group_id,
+            role=role,
+            display_name=raw.get('card') or raw.get('nickname'),
+            joined_at=float(raw['join_time']) if raw.get('join_time') else None,
+            title=raw.get('title'),
+        )
+
+    async def _send_forward_message(self, group_id: int, forward: platform_message.Forward) -> dict:
+        messages = []
+        for node in forward.node_list:
+            if not node.message_chain:
+                continue
+            content, _, _ = await AiocqhttpMessageConverter.yiri2target(node.message_chain)
+            if not content:
+                continue
+            messages.append(
+                {
+                    'type': 'node',
+                    'data': {
+                        'user_id': str(node.sender_id or self.bot_account_id or '10000'),
+                        'nickname': node.sender_name or 'LangBot',
+                        'content': list(content),
+                    },
+                }
+            )
+        if not messages:
+            return {}
+        try:
+            return await self.bot.call_action(
+                'send_forward_msg', group_id=group_id, user_id=str(self.bot_account_id), messages=messages
+            )
+        except Exception:
+            return await self.bot.call_action('send_group_forward_msg', group_id=group_id, messages=messages)

src/langbot/pkg/platform/adapters/aiocqhttp/event_converter.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import typing
+
+import aiocqhttp
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot.pkg.platform.adapters.aiocqhttp.message_converter import AiocqhttpMessageConverter
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+
+
+class AiocqhttpEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    @staticmethod
+    async def yiri2target(event: platform_events.Event, bot_account_id: int | str | None = None):
+        return getattr(event, 'source_platform_object', None)
+
+    @staticmethod
+    async def target2yiri(
+        event: aiocqhttp.Event,
+        bot: aiocqhttp.CQHttp | None = None,
+        bot_user_id: int | str | None = None,
+    ) -> platform_events.Event | None:
+        event_type = getattr(event, 'type', None)
+        if event_type == 'message':
+            return await AiocqhttpEventConverter.message_to_eba(event, bot)
+        if event_type == 'notice':
+            return AiocqhttpEventConverter.notice_to_eba(event, bot_user_id)
+        if event_type == 'request':
+            return AiocqhttpEventConverter.request_to_eba(event)
+        if event_type == 'meta_event':
+            return AiocqhttpEventConverter.platform_specific(event, f'meta.{getattr(event, "detail_type", "")}')
+        return None
+
+    @staticmethod
+    async def target2legacy(
+        event: aiocqhttp.Event,
+        bot: aiocqhttp.CQHttp | None = None,
+    ) -> platform_events.FriendMessage | platform_events.GroupMessage | None:
+        eba_event = await AiocqhttpEventConverter.message_to_eba(event, bot)
+        if eba_event:
+            return eba_event.to_legacy_event()
+        return None
+
+    @staticmethod
+    async def message_to_eba(
+        event: aiocqhttp.Event,
+        bot: aiocqhttp.CQHttp | None = None,
+    ) -> platform_events.MessageReceivedEvent:
+        message_chain = await AiocqhttpMessageConverter.target2yiri(
+            getattr(event, 'message', []),
+            getattr(event, 'message_id', -1),
+            getattr(event, 'time', None),
+            bot,
+        )
+        message_type = getattr(event, 'message_type', getattr(event, 'detail_type', 'private'))
+        group = None
+        chat_type = platform_entities.ChatType.PRIVATE
+        chat_id = getattr(event, 'user_id', '')
+        if message_type == 'group':
+            chat_type = platform_entities.ChatType.GROUP
+            chat_id = getattr(event, 'group_id', '')
+            group = AiocqhttpEventConverter.group_from_event(event)
+
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name='aiocqhttp',
+            message_id=getattr(event, 'message_id', ''),
+            message_chain=message_chain,
+            sender=AiocqhttpEventConverter.user_from_sender(event),
+            chat_type=chat_type,
+            chat_id=chat_id,
+            group=group,
+            timestamp=float(getattr(event, 'time', 0) or 0),
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    def notice_to_eba(
+        event: aiocqhttp.Event,
+        bot_user_id: int | str | None = None,
+    ) -> platform_events.EBAEvent:
+        notice_type = getattr(event, 'notice_type', getattr(event, 'detail_type', ''))
+        if notice_type in ('group_recall', 'friend_recall'):
+            return platform_events.MessageDeletedEvent(
+                type='message.deleted',
+                adapter_name='aiocqhttp',
+                message_id=getattr(event, 'message_id', ''),
+                operator=AiocqhttpEventConverter.user(getattr(event, 'operator_id', None)),
+                chat_type=platform_entities.ChatType.GROUP
+                if notice_type == 'group_recall'
+                else platform_entities.ChatType.PRIVATE,
+                chat_id=getattr(event, 'group_id', getattr(event, 'user_id', '')),
+                group=AiocqhttpEventConverter.group_from_event(event) if notice_type == 'group_recall' else None,
+                timestamp=float(getattr(event, 'time', 0) or 0),
+                source_platform_object=event,
+            )
+        if notice_type == 'group_increase':
+            group = AiocqhttpEventConverter.group_from_event(event)
+            user = AiocqhttpEventConverter.user(getattr(event, 'user_id', ''))
+            inviter_id = getattr(event, 'operator_id', None)
+            if AiocqhttpEventConverter._is_bot_user(getattr(event, 'user_id', None), bot_user_id, event):
+                return platform_events.BotInvitedToGroupEvent(
+                    type='bot.invited_to_group',
+                    adapter_name='aiocqhttp',
+                    group=group,
+                    inviter=AiocqhttpEventConverter.user(inviter_id) if inviter_id else None,
+                    timestamp=float(getattr(event, 'time', 0) or 0),
+                    source_platform_object=event,
+                )
+            return platform_events.MemberJoinedEvent(
+                type='group.member_joined',
+                adapter_name='aiocqhttp',
+                group=group,
+                member=user,
+                inviter=AiocqhttpEventConverter.user(inviter_id) if inviter_id else None,
+                join_type=getattr(event, 'sub_type', None) or 'direct',
+                timestamp=float(getattr(event, 'time', 0) or 0),
+                source_platform_object=event,
+            )
+        if notice_type == 'group_decrease':
+            group = AiocqhttpEventConverter.group_from_event(event)
+            operator = AiocqhttpEventConverter.user(getattr(event, 'operator_id', None))
+            if AiocqhttpEventConverter._is_bot_user(getattr(event, 'user_id', None), bot_user_id, event):
+                return platform_events.BotRemovedFromGroupEvent(
+                    type='bot.removed_from_group',
+                    adapter_name='aiocqhttp',
+                    group=group,
+                    operator=operator,
+                    timestamp=float(getattr(event, 'time', 0) or 0),
+                    source_platform_object=event,
+                )
+            return platform_events.MemberLeftEvent(
+                type='group.member_left',
+                adapter_name='aiocqhttp',
+                group=group,
+                member=AiocqhttpEventConverter.user(getattr(event, 'user_id', '')),
+                is_kicked=getattr(event, 'sub_type', '') in ('kick', 'kick_me'),
+                operator=operator,
+                timestamp=float(getattr(event, 'time', 0) or 0),
+                source_platform_object=event,
+            )
+        if notice_type == 'group_ban':
+            group = AiocqhttpEventConverter.group_from_event(event)
+            duration = int(getattr(event, 'duration', 0) or 0)
+            operator = AiocqhttpEventConverter.user(getattr(event, 'operator_id', None))
+            if AiocqhttpEventConverter._is_bot_user(getattr(event, 'user_id', None), bot_user_id, event):
+                event_cls = platform_events.BotMutedEvent if duration > 0 else platform_events.BotUnmutedEvent
+                kwargs: dict[str, typing.Any] = {
+                    'type': 'bot.muted' if duration > 0 else 'bot.unmuted',
+                    'adapter_name': 'aiocqhttp',
+                    'group': group,
+                    'operator': operator,
+                    'timestamp': float(getattr(event, 'time', 0) or 0),
+                    'source_platform_object': event,
+                }
+                if duration > 0:
+                    kwargs['duration'] = duration
+                return event_cls(**kwargs)
+            if duration > 0:
+                return platform_events.MemberBannedEvent(
+                    type='group.member_banned',
+                    adapter_name='aiocqhttp',
+                    group=group,
+                    member=AiocqhttpEventConverter.user(getattr(event, 'user_id', '')),
+                    operator=operator,
+                    duration=duration,
+                    timestamp=float(getattr(event, 'time', 0) or 0),
+                    source_platform_object=event,
+                )
+        if notice_type == 'friend_add':
+            return platform_events.FriendAddedEvent(
+                type='friend.added',
+                adapter_name='aiocqhttp',
+                user=AiocqhttpEventConverter.user(getattr(event, 'user_id', '')),
+                timestamp=float(getattr(event, 'time', 0) or 0),
+                source_platform_object=event,
+            )
+        return AiocqhttpEventConverter.platform_specific(event, f'notice.{notice_type}')
+
+    @staticmethod
+    def request_to_eba(event: aiocqhttp.Event) -> platform_events.EBAEvent:
+        request_type = getattr(event, 'request_type', getattr(event, 'detail_type', ''))
+        if request_type == 'friend':
+            return platform_events.FriendRequestReceivedEvent(
+                type='friend.request_received',
+                adapter_name='aiocqhttp',
+                request_id=getattr(event, 'flag', ''),
+                user=AiocqhttpEventConverter.user(getattr(event, 'user_id', '')),
+                message=getattr(event, 'comment', None),
+                timestamp=float(getattr(event, 'time', 0) or 0),
+                source_platform_object=event,
+            )
+        if request_type == 'group' and getattr(event, 'sub_type', '') == 'invite':
+            return platform_events.BotInvitedToGroupEvent(
+                type='bot.invited_to_group',
+                adapter_name='aiocqhttp',
+                group=AiocqhttpEventConverter.group_from_event(event),
+                inviter=AiocqhttpEventConverter.user(getattr(event, 'user_id', '')),
+                request_id=getattr(event, 'flag', ''),
+                timestamp=float(getattr(event, 'time', 0) or 0),
+                source_platform_object=event,
+            )
+        return AiocqhttpEventConverter.platform_specific(event, f'request.{request_type}')
+
+    @staticmethod
+    def user_from_sender(event: aiocqhttp.Event) -> platform_entities.User:
+        sender = getattr(event, 'sender', {}) or {}
+        nickname = sender.get('card') or sender.get('nickname') or ''
+        return platform_entities.User(
+            id=sender.get('user_id', getattr(event, 'user_id', '')),
+            nickname=nickname,
+            remark=sender.get('remark'),
+        )
+
+    @staticmethod
+    def user(user_id: typing.Union[int, str, None], nickname: str = '') -> platform_entities.User | None:
+        if user_id is None or user_id == '':
+            return None
+        return platform_entities.User(id=user_id, nickname=nickname)
+
+    @staticmethod
+    def group_from_event(event: aiocqhttp.Event) -> platform_entities.UserGroup:
+        return platform_entities.UserGroup(
+            id=getattr(event, 'group_id', ''),
+            name=getattr(event, 'group_name', '') or '',
+            member_count=getattr(event, 'member_count', None),
+        )
+
+    @staticmethod
+    def platform_specific(event: aiocqhttp.Event, action: str) -> platform_events.PlatformSpecificEvent:
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            adapter_name='aiocqhttp',
+            action=action,
+            data={key: value for key, value in dict(event).items() if key not in {'message'}},
+            timestamp=float(getattr(event, 'time', 0) or 0),
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    def _is_bot_user(user_id: typing.Any, bot_user_id: typing.Any, event: aiocqhttp.Event) -> bool:
+        candidate = bot_user_id or getattr(event, 'self_id', None)
+        return candidate is not None and user_id is not None and str(user_id) == str(candidate)

src/langbot/pkg/platform/adapters/aiocqhttp/manifest.yaml

@@ -0,0 +1,131 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: aiocqhttp-eba
+  label:
+    en_US: OneBot v11 (EBA)
+    zh_Hans: OneBot v11 (EBA)
+    zh_Hant: OneBot v11 (EBA)
+  description:
+    en_US: OneBot v11 adapter for QQ-compatible protocol endpoints (EBA architecture)
+    zh_Hans: OneBot v11 适配器，用于接入 QQ 兼容协议端（EBA 架构版本）
+    zh_Hant: OneBot v11 適配器，用於接入 QQ 相容協定端（EBA 架構版本）
+  icon: onebot.svg
+
+spec:
+  categories:
+    - protocol
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/aiocqhttp
+    en: https://link.langbot.app/en/platforms/aiocqhttp
+    ja: https://link.langbot.app/ja/platforms/aiocqhttp
+  config:
+    - name: host
+      label:
+        en_US: Host
+        zh_Hans: 主机
+        zh_Hant: 主機
+      description:
+        en_US: The host that OneBot v11 listens on for reverse WebSocket connections. Unless you know what you're doing, use 0.0.0.0
+        zh_Hans: OneBot v11 反向 WebSocket 监听主机，除非你知道自己在做什么，否则请写 0.0.0.0
+        zh_Hant: OneBot v11 反向 WebSocket 監聽主機，除非你知道自己在做什麼，否則請填 0.0.0.0
+      type: string
+      required: true
+      default: 0.0.0.0
+    - name: port
+      label:
+        en_US: Port
+        zh_Hans: 端口
+        zh_Hant: 連接埠
+      description:
+        en_US: Reverse WebSocket listen port
+        zh_Hans: 反向 WebSocket 监听端口
+        zh_Hant: 反向 WebSocket 監聽連接埠
+      type: integer
+      required: true
+      default: 2280
+    - name: access-token
+      label:
+        en_US: Access Token
+        zh_Hans: 访问令牌
+        zh_Hant: 存取令牌
+      description:
+        en_US: Custom connection token for the protocol endpoint. Leave empty if the endpoint has no token configured
+        zh_Hans: 自定义的协议端连接令牌；若协议端未设置，则不填
+        zh_Hant: 自訂的協定端連線令牌；若協定端未設定，則不填
+      type: string
+      required: false
+      default: ""
+
+  supported_events:
+    - message.received
+    - message.deleted
+    - group.member_joined
+    - group.member_left
+    - group.member_banned
+    - friend.request_received
+    - friend.added
+    - bot.invited_to_group
+    - bot.removed_from_group
+    - bot.muted
+    - bot.unmuted
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - delete_message
+      - forward_message
+      - get_message
+      - get_group_info
+      - get_group_list
+      - get_group_member_list
+      - get_group_member_info
+      - set_group_name
+      - get_user_info
+      - get_friend_list
+      - approve_friend_request
+      - approve_group_invite
+      - mute_member
+      - unmute_member
+      - kick_member
+      - leave_group
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: get_login_info
+      description: { en_US: "Get current bot account information", zh_Hans: "获取当前机器人账号信息" }
+    - action: get_status
+      description: { en_US: "Get endpoint status", zh_Hans: "获取协议端状态" }
+    - action: get_version_info
+      description: { en_US: "Get endpoint version information", zh_Hans: "获取协议端版本信息" }
+    - action: get_group_honor_info
+      description: { en_US: "Get group honor information", zh_Hans: "获取群荣誉信息" }
+    - action: set_group_card
+      description: { en_US: "Set a member group card", zh_Hans: "设置群名片" }
+    - action: set_group_special_title
+      description: { en_US: "Set a member special title", zh_Hans: "设置群专属头衔" }
+    - action: set_group_admin
+      description: { en_US: "Set group administrator status", zh_Hans: "设置群管理员" }
+    - action: set_group_whole_ban
+      description: { en_US: "Enable or disable whole-group mute", zh_Hans: "设置全员禁言" }
+    - action: send_group_forward_msg
+      description: { en_US: "Send a merged forward message", zh_Hans: "发送合并转发消息" }
+    - action: get_forward_msg
+      description: { en_US: "Get merged forward message content", zh_Hans: "获取合并转发消息内容" }
+    - action: get_record
+      description: { en_US: "Get voice file", zh_Hans: "获取语音文件" }
+    - action: get_image
+      description: { en_US: "Get image file", zh_Hans: "获取图片文件" }
+    - action: can_send_image
+      description: { en_US: "Check whether images can be sent", zh_Hans: "检查是否可以发送图片" }
+    - action: can_send_record
+      description: { en_US: "Check whether voice messages can be sent", zh_Hans: "检查是否可以发送语音" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: AiocqhttpAdapter

src/langbot/pkg/platform/adapters/aiocqhttp/message_converter.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import datetime
+import typing
+
+import aiocqhttp
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+FACE_NAMES = {
+    '14': '微笑',
+    '21': '可爱',
+    '23': '傲慢',
+    '24': '饥饿',
+    '25': '困',
+    '26': '惊恐',
+    '27': '流汗',
+    '28': '憨笑',
+    '29': '悠闲',
+    '30': '奋斗',
+    '32': '疑问',
+    '33': '嘘',
+    '34': '晕',
+    '38': '敲打',
+    '39': '再见',
+    '42': '爱情',
+    '43': '跳跳',
+    '49': '拥抱',
+    '53': '蛋糕',
+    '63': '玫瑰',
+    '66': '爱心',
+    '74': '太阳',
+    '75': '月亮',
+    '76': '赞',
+    '78': '握手',
+    '79': '胜利',
+    '85': '飞吻',
+    '89': '西瓜',
+    '96': '冷汗',
+    '97': '擦汗',
+    '98': '抠鼻',
+    '99': '鼓掌',
+    '100': '糗大了',
+    '101': '坏笑',
+    '102': '左哼哼',
+    '103': '右哼哼',
+    '104': '哈欠',
+    '106': '委屈',
+    '111': '可怜',
+    '120': '拳头',
+    '122': '爱你',
+    '123': 'NO',
+    '124': 'OK',
+    '129': '挥手',
+    '144': '喝彩',
+    '147': '棒棒糖',
+    '171': '茶',
+    '173': '泪奔',
+    '174': '无奈',
+    '175': '卖萌',
+    '179': 'doge',
+    '180': '惊喜',
+    '182': '笑哭',
+    '201': '点赞',
+    '203': '托脸',
+    '212': '托腮',
+    '264': '捂脸',
+    '271': '吃瓜',
+    '285': '摸鱼',
+}
+
+
+class AiocqhttpMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    async def yiri2target(
+        message_chain: platform_message.MessageChain,
+    ) -> tuple[aiocqhttp.Message, typing.Union[int, str, None], datetime.datetime | None]:
+        target = aiocqhttp.Message()
+        source_id: typing.Union[int, str, None] = None
+        source_time: datetime.datetime | None = None
+
+        for component in message_chain:
+            if isinstance(component, platform_message.Source):
+                source_id = component.id
+                source_time = component.time
+            elif isinstance(component, platform_message.Plain):
+                target.append(aiocqhttp.MessageSegment.text(component.text))
+            elif isinstance(component, platform_message.At):
+                target.append(aiocqhttp.MessageSegment.at(component.target))
+            elif isinstance(component, platform_message.AtAll):
+                target.append(aiocqhttp.MessageSegment.at('all'))
+            elif isinstance(component, platform_message.Image):
+                file_arg = AiocqhttpMessageConverter._file_arg(component)
+                if file_arg:
+                    target.append(aiocqhttp.MessageSegment.image(file_arg))
+            elif isinstance(component, platform_message.Voice):
+                file_arg = AiocqhttpMessageConverter._file_arg(component)
+                if file_arg:
+                    target.append(aiocqhttp.MessageSegment.record(file_arg))
+            elif isinstance(component, platform_message.File):
+                file_arg = component.url or component.path or component.base64 or component.id
+                target.append(
+                    aiocqhttp.MessageSegment(
+                        type_='file',
+                        data={
+                            'file': file_arg,
+                            'name': component.name or 'file',
+                        },
+                    )
+                )
+            elif isinstance(component, platform_message.Face):
+                if component.face_type == 'rps':
+                    target.append(aiocqhttp.MessageSegment.rps())
+                elif component.face_type == 'dice':
+                    target.append(aiocqhttp.MessageSegment.dice())
+                else:
+                    target.append(aiocqhttp.MessageSegment.face(component.face_id))
+            elif isinstance(component, platform_message.Forward):
+                for node in component.node_list:
+                    if node.message_chain:
+                        node_message, _, _ = await AiocqhttpMessageConverter.yiri2target(node.message_chain)
+                        target.extend(node_message)
+            elif isinstance(component, platform_message.Quote) and component.id is not None:
+                target.append(aiocqhttp.MessageSegment.reply(component.id))
+            else:
+                target.append(aiocqhttp.MessageSegment.text(str(component)))
+
+        return target, source_id, source_time
+
+    @staticmethod
+    async def target2yiri(
+        message: typing.Any,
+        message_id: typing.Union[int, str] = -1,
+        timestamp: float | None = None,
+        bot: aiocqhttp.CQHttp | None = None,
+    ) -> platform_message.MessageChain:
+        target = aiocqhttp.Message(message)
+        message_time = datetime.datetime.fromtimestamp(timestamp) if timestamp else datetime.datetime.now()
+        components: list[platform_message.MessageComponent] = [
+            platform_message.Source(id=message_id, time=message_time),
+        ]
+
+        for segment in target:
+            if segment.type == 'text':
+                components.append(platform_message.Plain(text=segment.data.get('text', '')))
+            elif segment.type == 'at':
+                qq = str(segment.data.get('qq', ''))
+                components.append(platform_message.AtAll() if qq == 'all' else platform_message.At(target=qq))
+            elif segment.type == 'image':
+                if segment.data.get('emoji_package_id'):
+                    components.append(
+                        platform_message.Face(
+                            face_id=int(segment.data.get('emoji_package_id') or 0),
+                            face_name=segment.data.get('summary', ''),
+                        )
+                    )
+                else:
+                    components.append(
+                        platform_message.Image(
+                            image_id=str(segment.data.get('file', '')),
+                            url=segment.data.get('url') or segment.data.get('file') or '',
+                        )
+                    )
+            elif segment.type == 'record':
+                components.append(
+                    platform_message.Voice(
+                        voice_id=str(segment.data.get('file', '')),
+                        url=segment.data.get('url') or segment.data.get('file') or '',
+                    )
+                )
+            elif segment.type == 'file':
+                components.append(
+                    platform_message.File(
+                        id=str(segment.data.get('file_id') or segment.data.get('file') or ''),
+                        name=segment.data.get('name') or segment.data.get('file') or '',
+                        size=int(segment.data.get('size') or segment.data.get('file_size') or 0),
+                        url=segment.data.get('url') or segment.data.get('file_url') or '',
+                    )
+                )
+            elif segment.type == 'reply':
+                quote = await AiocqhttpMessageConverter._quote_from_reply_segment(segment, bot)
+                components.append(quote)
+            elif segment.type == 'face':
+                face_id = str(segment.data.get('id', 0))
+                face_name = ''
+                raw = segment.data.get('raw')
+                if isinstance(raw, dict):
+                    face_name = str(raw.get('faceText') or '')
+                components.append(
+                    platform_message.Face(
+                        face_id=int(face_id or 0),
+                        face_name=face_name.replace('/', '') or FACE_NAMES.get(face_id, ''),
+                    )
+                )
+            elif segment.type == 'rps':
+                components.append(
+                    platform_message.Face(
+                        face_type='rps',
+                        face_id=int(segment.data.get('result') or 0),
+                        face_name='猜拳',
+                    )
+                )
+            elif segment.type == 'dice':
+                components.append(
+                    platform_message.Face(
+                        face_type='dice',
+                        face_id=int(segment.data.get('result') or 0),
+                        face_name='骰子',
+                    )
+                )
+            else:
+                components.append(platform_message.Unknown(text=f'{segment.type}:{segment.data}'))
+
+        return platform_message.MessageChain(components)
+
+    @staticmethod
+    def _file_arg(component: platform_message.Image | platform_message.Voice) -> str:
+        if component.base64:
+            _, _, payload = component.base64.partition(',')
+            return f'base64://{payload or component.base64}'
+        if component.url:
+            return component.url
+        if component.path:
+            return str(component.path)
+        return ''
+
+    @staticmethod
+    async def _quote_from_reply_segment(
+        segment: aiocqhttp.MessageSegment,
+        bot: aiocqhttp.CQHttp | None,
+    ) -> platform_message.Quote:
+        reply_id = segment.data.get('id')
+        origin = platform_message.MessageChain([])
+        sender_id = None
+        group_id = None
+        target_id = None
+        if bot is not None and reply_id is not None:
+            try:
+                message_data = await bot.get_msg(message_id=int(reply_id))
+                sender_id = message_data.get('sender', {}).get('user_id') or message_data.get('user_id')
+                group_id = message_data.get('group_id')
+                target_id = group_id or sender_id
+                origin = await AiocqhttpMessageConverter.target2yiri(
+                    message_data.get('message', []),
+                    message_data.get('message_id', reply_id),
+                    message_data.get('time'),
+                    bot=None,
+                )
+            except Exception:
+                origin = platform_message.MessageChain([])
+        return platform_message.Quote(
+            id=reply_id,
+            group_id=group_id,
+            sender_id=sender_id,
+            target_id=target_id,
+            origin=origin,
+        )

src/langbot/pkg/platform/adapters/aiocqhttp/onebot.svg

@@ -0,0 +1,7 @@
+<svg width="96" height="96" viewBox="0 0 96 96" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="96" height="96" rx="20" fill="#16A34A"/>
+  <path d="M24 33C24 25.268 30.268 19 38 19H58C65.732 19 72 25.268 72 33V51C72 58.732 65.732 65 58 65H41.5L29 77V64.059C26.024 61.514 24 57.729 24 51V33Z" fill="white"/>
+  <circle cx="39" cy="42" r="5" fill="#16A34A"/>
+  <circle cx="57" cy="42" r="5" fill="#16A34A"/>
+  <path d="M39 53C44.5 57 51.5 57 57 53" stroke="#16A34A" stroke-width="5" stroke-linecap="round"/>
+</svg>

src/langbot/pkg/platform/adapters/aiocqhttp/platform_api.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import typing
+
+import aiocqhttp
+
+
+async def _call(bot: aiocqhttp.CQHttp, action: str, params: dict[str, typing.Any]) -> dict:
+    result = await bot.call_action(action, **params)
+    return result or {}
+
+
+async def get_login_info(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'get_login_info', params)
+
+
+async def get_status(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'get_status', params)
+
+
+async def get_version_info(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'get_version_info', params)
+
+
+async def get_group_honor_info(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'get_group_honor_info', params)
+
+
+async def set_group_card(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'set_group_card', params)
+
+
+async def set_group_special_title(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'set_group_special_title', params)
+
+
+async def set_group_admin(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'set_group_admin', params)
+
+
+async def set_group_whole_ban(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'set_group_whole_ban', params)
+
+
+async def send_group_forward_msg(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'send_group_forward_msg', params)
+
+
+async def get_forward_msg(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'get_forward_msg', params)
+
+
+async def get_record(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'get_record', params)
+
+
+async def get_image(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'get_image', params)
+
+
+async def can_send_image(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'can_send_image', params)
+
+
+async def can_send_record(bot: aiocqhttp.CQHttp, params: dict) -> dict:
+    return await _call(bot, 'can_send_record', params)
+
+
+PLATFORM_API_MAP = {
+    'get_login_info': get_login_info,
+    'get_status': get_status,
+    'get_version_info': get_version_info,
+    'get_group_honor_info': get_group_honor_info,
+    'set_group_card': set_group_card,
+    'set_group_special_title': set_group_special_title,
+    'set_group_admin': set_group_admin,
+    'set_group_whole_ban': set_group_whole_ban,
+    'send_group_forward_msg': send_group_forward_msg,
+    'get_forward_msg': get_forward_msg,
+    'get_record': get_record,
+    'get_image': get_image,
+    'can_send_image': can_send_image,
+    'can_send_record': can_send_record,
+}

src/langbot/pkg/platform/adapters/aiocqhttp/types.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import typing
+
+import aiocqhttp
+
+
+TargetMessage = typing.Union[str, list, dict, aiocqhttp.Message]
+OneBotResponse = dict[str, typing.Any] | None

src/langbot/pkg/platform/adapters/dingtalk/__init__.py

@@ -0,0 +1 @@
+"""DingTalk EBA platform adapter."""

src/langbot/pkg/platform/adapters/dingtalk/adapter.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import traceback
+import typing
+
+import pydantic
+
+from langbot.libs.dingtalk_api.api import DingTalkClient
+from langbot.libs.dingtalk_api.dingtalkevent import DingTalkEvent
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot.pkg.platform.adapters.dingtalk.api_impl import DingTalkAPIMixin
+from langbot.pkg.platform.adapters.dingtalk.event_converter import DingTalkEventConverter
+from langbot.pkg.platform.adapters.dingtalk.message_converter import DingTalkMessageConverter
+from langbot.pkg.platform.adapters.dingtalk.platform_api import PLATFORM_API_MAP
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class DingTalkAdapter(DingTalkAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    bot: DingTalkClient = pydantic.Field(exclude=True)
+
+    message_converter: DingTalkMessageConverter = DingTalkMessageConverter()
+    event_converter: DingTalkEventConverter = DingTalkEventConverter()
+
+    config: dict
+    listeners: dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = {}
+    card_instance_id_dict: dict = {}
+    _message_cache: dict[str, platform_events.MessageReceivedEvent] = {}
+    _user_cache: dict[str, platform_entities.User] = {}
+    _group_cache: dict[str, platform_entities.UserGroup] = {}
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        required_keys = ['client_id', 'client_secret', 'robot_name', 'robot_code']
+        missing_keys = [key for key in required_keys if key not in config]
+        if missing_keys:
+            raise Exception('钉钉缺少相关配置项，请查看文档或联系管理员')
+
+        bot = DingTalkClient(
+            client_id=config['client_id'],
+            client_secret=config['client_secret'],
+            robot_name=config['robot_name'],
+            robot_code=config['robot_code'],
+            markdown_card=config.get('markdown_card', True),
+            logger=logger,
+        )
+        super().__init__(
+            config=config,
+            logger=logger,
+            card_instance_id_dict={},
+            bot_account_id=config['robot_name'],
+            bot=bot,
+            listeners={},
+            _message_cache={},
+            _user_cache={},
+            _group_cache={},
+        )
+        self._register_native_handlers()
+
+    def get_supported_events(self) -> list[str]:
+        return [
+            'message.received',
+            'platform.specific',
+        ]
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'send_message',
+            'reply_message',
+            'get_message',
+            'get_group_info',
+            'get_group_list',
+            'get_group_member_info',
+            'get_user_info',
+            'get_friend_list',
+            'get_file_url',
+            'call_platform_api',
+        ]
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ) -> platform_events.MessageResult:
+        markdown_enabled = self.config.get('markdown_card', False)
+        content, _ = await DingTalkMessageConverter.yiri2target(message, markdown_enabled)
+        if target_type in ('person', 'private'):
+            raw = await self.bot.send_proactive_message_to_one(target_id, content)
+        elif target_type == 'group':
+            raw = await self.bot.send_proactive_message_to_group(target_id, content)
+        else:
+            raise ValueError(f'Unsupported dingtalk target_type: {target_type}')
+        return platform_events.MessageResult(raw=raw if isinstance(raw, dict) else {'result': raw})
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ) -> platform_events.MessageResult:
+        assert isinstance(message_source.source_platform_object, DingTalkEvent)
+        incoming_message = message_source.source_platform_object.incoming_message
+        markdown_enabled = self.config.get('markdown_card', False)
+        content, at = await DingTalkMessageConverter.yiri2target(message, markdown_enabled)
+        raw = await self.bot.send_message(content, incoming_message, at)
+        return platform_events.MessageResult(
+            message_id=getattr(incoming_message, 'message_id', None),
+            raw=raw if isinstance(raw, dict) else {'result': raw},
+        )
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        message_id = bot_message.resp_message_id
+        msg_seq = bot_message.msg_sequence
+        if (msg_seq - 1) % 8 != 0 and not is_final:
+            return
+
+        markdown_enabled = self.config.get('markdown_card', False)
+        content, _ = await DingTalkMessageConverter.yiri2target(message, markdown_enabled)
+        card_instance, card_instance_id = self.card_instance_id_dict[message_id]
+        if not content and bot_message.content:
+            content = bot_message.content
+        if content:
+            await self.bot.send_card_message(card_instance, card_instance_id, content, is_final)
+        if is_final and bot_message.tool_calls is None:
+            self.card_instance_id_dict.pop(message_id)
+
+    async def create_message_card(self, message_id, event):
+        card_template_id = self.config['card_template_id']
+        incoming_message = event.source_platform_object.incoming_message
+        card_auto_layout = self.config.get('card_auto_layout', False)
+        card_instance, card_instance_id = await self.bot.create_and_card(
+            card_template_id,
+            incoming_message,
+            card_auto_layout=card_auto_layout,
+        )
+        self.card_instance_id_dict[message_id] = (card_instance, card_instance_id)
+        return True
+
+    async def is_stream_output_supported(self) -> bool:
+        return bool(self.config.get('enable-stream-reply', False))
+
+    async def call_platform_api(self, action: str, params: dict = {}) -> dict:
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            raise NotSupportedError(f'call_platform_api:{action}')
+        return await handler(self.bot, params)
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        registered = self.listeners.get(event_type)
+        if registered is callback:
+            self.listeners.pop(event_type, None)
+
+    async def run_async(self):
+        await self.logger.info('DingTalk EBA adapter starting')
+        await self.bot.start()
+
+    async def kill(self) -> bool:
+        await self.bot.stop()
+        return True
+
+    async def is_muted(self, group_id: int | None = None) -> bool:
+        return False
+
+    def _register_native_handlers(self):
+        async def on_message(event: DingTalkEvent):
+            await self._handle_native_event(event)
+
+        self.bot.on_message('FriendMessage')(on_message)
+        self.bot.on_message('GroupMessage')(on_message)
+
+    async def _handle_native_event(self, event: DingTalkEvent):
+        try:
+            await self.logger.debug(
+                'DingTalk EBA event received: '
+                f'conversation={event.conversation}, message_id={getattr(event.incoming_message, "message_id", None)}'
+            )
+            if platform_events.FriendMessage in self.listeners or platform_events.GroupMessage in self.listeners:
+                legacy_event = await self.event_converter.target2legacy(event, self.config['robot_name'])
+                if legacy_event:
+                    callback = self.listeners.get(type(legacy_event))
+                    if callback:
+                        await callback(legacy_event, self)
+
+            eba_event = await self.event_converter.target2yiri(event, self.config['robot_name'])
+            if eba_event:
+                self._cache_event(eba_event)
+                await self._dispatch_eba_event(eba_event)
+        except Exception:
+            await self.logger.error(f'Error in dingtalk native event: {traceback.format_exc()}')
+
+    async def _dispatch_eba_event(self, event: platform_events.EBAEvent):
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return
+
+    def _cache_event(self, event: platform_events.Event):
+        if not isinstance(event, platform_events.MessageReceivedEvent):
+            return
+        self._message_cache[str(event.message_id)] = event
+        self._user_cache[str(event.sender.id)] = event.sender
+        if event.group:
+            self._group_cache[str(event.group.id)] = event.group

src/langbot/pkg/platform/adapters/dingtalk/api_impl.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import typing
+
+from langbot.libs.dingtalk_api.api import DingTalkClient
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class DingTalkAPIMixin:
+    bot: DingTalkClient
+    _message_cache: dict[str, platform_events.MessageReceivedEvent]
+    _user_cache: dict[str, platform_entities.User]
+    _group_cache: dict[str, platform_entities.UserGroup]
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> platform_events.MessageReceivedEvent:
+        event = self._message_cache.get(str(message_id))
+        if event is None:
+            raise NotSupportedError('get_message:message_not_cached')
+        return event
+
+    async def get_group_info(self, group_id: typing.Union[int, str]) -> platform_entities.UserGroup:
+        return self._group_cache.get(str(group_id)) or platform_entities.UserGroup(id=group_id, name='')
+
+    async def get_group_list(self) -> list[platform_entities.UserGroup]:
+        return list(self._group_cache.values())
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        raise NotSupportedError('get_group_member_list')
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        user = self._user_cache.get(str(user_id))
+        if user is None:
+            raise NotSupportedError('get_group_member_info:user_not_cached')
+        return platform_entities.UserGroupMember(
+            user=user,
+            group_id=group_id,
+            role=platform_entities.MemberRole.MEMBER,
+            display_name=user.nickname,
+        )
+
+    async def get_user_info(self, user_id: typing.Union[int, str]) -> platform_entities.User:
+        return self._user_cache.get(str(user_id)) or platform_entities.User(id=user_id, nickname='')
+
+    async def get_friend_list(self) -> list[platform_entities.User]:
+        return list(self._user_cache.values())
+
+    async def upload_file(self, file_data: bytes, filename: str) -> str:
+        raise NotSupportedError('upload_file')
+
+    async def get_file_url(self, file_id: str) -> str:
+        return await self.bot.get_file_url(file_id)

src/langbot/pkg/platform/adapters/dingtalk/dingtalk.svg

@@ -0,0 +1,7 @@
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+
+<!-- Uploaded to: SVG Repo, www.svgrepo.com, Transformed by: SVG Repo Mixer Tools -->
+<svg fill="#4aa4f8" width="800px" height="800px" viewBox="0 0 1024 1024" xmlns="http://www.w3.org/2000/svg" class="icon" stroke="#4aa4f8">
+
+<g id="SVGRepo_bgCarrier" stroke-width="0"/>
+

src/langbot/pkg/platform/adapters/dingtalk/event_converter.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import typing
+
+from langbot.libs.dingtalk_api.dingtalkevent import DingTalkEvent
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot.pkg.platform.adapters.dingtalk.message_converter import DingTalkMessageConverter
+from langbot.pkg.platform.adapters.dingtalk.types import ADAPTER_NAME
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+
+
+class DingTalkEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    @staticmethod
+    async def yiri2target(event: platform_events.Event):
+        return getattr(event, 'source_platform_object', None)
+
+    @staticmethod
+    async def target2yiri(event: DingTalkEvent, bot_name: str) -> platform_events.Event | None:
+        if event.conversation in {'FriendMessage', 'GroupMessage'}:
+            return await DingTalkEventConverter.message_to_eba(event, bot_name)
+        return DingTalkEventConverter.platform_specific(event, f'message.{event.conversation or "unknown"}')
+
+    @staticmethod
+    async def target2legacy(
+        event: DingTalkEvent,
+        bot_name: str,
+    ) -> platform_events.FriendMessage | platform_events.GroupMessage | None:
+        eba_event = await DingTalkEventConverter.message_to_eba(event, bot_name)
+        if eba_event:
+            return eba_event.to_legacy_event()
+        return None
+
+    @staticmethod
+    async def message_to_eba(event: DingTalkEvent, bot_name: str) -> platform_events.MessageReceivedEvent:
+        incoming_message = event.incoming_message
+        message_chain = await DingTalkMessageConverter.target2yiri(event, bot_name)
+        sender = DingTalkEventConverter.user_from_event(event)
+        chat_type = platform_entities.ChatType.PRIVATE
+        chat_id = getattr(incoming_message, 'sender_staff_id', '')
+        group = None
+        if event.conversation == 'GroupMessage':
+            chat_type = platform_entities.ChatType.GROUP
+            chat_id = getattr(incoming_message, 'conversation_id', '')
+            group = DingTalkEventConverter.group_from_event(event)
+
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name=ADAPTER_NAME,
+            message_id=getattr(incoming_message, 'message_id', ''),
+            message_chain=message_chain,
+            sender=sender,
+            chat_type=chat_type,
+            chat_id=chat_id,
+            group=group,
+            timestamp=DingTalkEventConverter._timestamp(incoming_message),
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    def user_from_event(event: DingTalkEvent) -> platform_entities.User:
+        incoming_message = event.incoming_message
+        return platform_entities.User(
+            id=getattr(incoming_message, 'sender_staff_id', ''),
+            nickname=getattr(incoming_message, 'sender_nick', '') or '',
+        )
+
+    @staticmethod
+    def group_from_event(event: DingTalkEvent) -> platform_entities.UserGroup:
+        incoming_message = event.incoming_message
+        return platform_entities.UserGroup(
+            id=getattr(incoming_message, 'conversation_id', ''),
+            name=getattr(incoming_message, 'conversation_title', '') or '',
+        )
+
+    @staticmethod
+    def platform_specific(event: DingTalkEvent, action: str) -> platform_events.PlatformSpecificEvent:
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            adapter_name=ADAPTER_NAME,
+            action=action,
+            data={
+                key: value for key, value in dict(event).items() if key not in {'IncomingMessage', 'Picture', 'Audio'}
+            },
+            timestamp=DingTalkEventConverter._timestamp(event.incoming_message),
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    def _timestamp(incoming_message: typing.Any) -> float:
+        value = getattr(incoming_message, 'create_at', None)
+        if isinstance(value, (int, float)):
+            timestamp = float(value)
+            return timestamp / 1000 if timestamp > 10_000_000_000 else timestamp
+        if hasattr(value, 'timestamp'):
+            return float(value.timestamp())
+        return 0.0

src/langbot/pkg/platform/adapters/dingtalk/manifest.yaml

@@ -0,0 +1,126 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: dingtalk-eba
+  label:
+    en_US: DingTalk (EBA)
+    zh_Hans: 钉钉 (EBA)
+    zh_Hant: 釘釘 (EBA)
+  description:
+    en_US: DingTalk adapter (EBA architecture)
+    zh_Hans: 钉钉适配器（EBA 架构版本）
+    zh_Hant: 釘釘適配器（EBA 架構版本）
+  icon: dingtalk.svg
+
+spec:
+  categories:
+    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/dingtalk
+    en: https://link.langbot.app/en/platforms/dingtalk
+    ja: https://link.langbot.app/ja/platforms/dingtalk
+  config:
+    - name: client_id
+      label:
+        en_US: Client ID
+        zh_Hans: 客户端ID
+        zh_Hant: 用戶端ID
+      type: string
+      required: true
+      default: ""
+    - name: client_secret
+      label:
+        en_US: Client Secret
+        zh_Hans: 客户端密钥
+        zh_Hant: 用戶端密鑰
+      type: string
+      required: true
+      default: ""
+    - name: robot_code
+      label:
+        en_US: Robot Code
+        zh_Hans: 机器人代码
+        zh_Hant: 機器人代碼
+      type: string
+      required: true
+      default: ""
+    - name: robot_name
+      label:
+        en_US: Robot Name
+        zh_Hans: 机器人名称
+        zh_Hant: 機器人名稱
+      type: string
+      required: true
+      default: ""
+    - name: markdown_card
+      label:
+        en_US: Markdown Card
+        zh_Hans: 是否使用 Markdown 卡片
+        zh_Hant: 是否使用 Markdown 卡片
+      type: boolean
+      required: false
+      default: true
+    - name: enable-stream-reply
+      label:
+        en_US: Enable Stream Reply Mode
+        zh_Hans: 启用钉钉卡片流式回复模式
+        zh_Hant: 啟用釘釘卡片串流回覆模式
+      description:
+        en_US: If enabled, the bot will use DingTalk card streaming replies.
+        zh_Hans: 如果启用，将使用钉钉卡片流式方式来回复内容
+        zh_Hant: 如果啟用，將使用釘釘卡片串流方式來回覆內容
+      type: boolean
+      required: true
+      default: false
+    - name: card_auto_layout
+      label:
+        en_US: Card Auto Layout
+        zh_Hans: 卡片宽屏自动布局
+        zh_Hant: 卡片寬螢幕自動佈局
+      type: boolean
+      required: false
+      default: false
+    - name: card_template_id
+      label:
+        en_US: Card Template ID
+        zh_Hans: 卡片模板ID
+        zh_Hant: 卡片範本ID
+      type: string
+      required: true
+      default: "填写你的卡片template_id"
+
+  supported_events:
+    - message.received
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - get_message
+      - get_group_info
+      - get_group_list
+      - get_group_member_info
+      - get_user_info
+      - get_friend_list
+      - get_file_url
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: check_access_token
+      description: { en_US: "Check whether the current DingTalk access token is usable", zh_Hans: "检查当前钉钉 access token 是否可用" }
+    - action: refresh_access_token
+      description: { en_US: "Refresh the DingTalk access token", zh_Hans: "刷新钉钉 access token" }
+    - action: get_file_url
+      description: { en_US: "Resolve a DingTalk download code to a file URL", zh_Hans: "将钉钉 downloadCode 解析为文件 URL" }
+    - action: get_audio_base64
+      description: { en_US: "Download DingTalk audio as base64 by download code", zh_Hans: "通过 downloadCode 下载钉钉语音并转为 base64" }
+    - action: download_image_base64
+      description: { en_US: "Download DingTalk image as base64 by download code", zh_Hans: "通过 downloadCode 下载钉钉图片并转为 base64" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: DingTalkAdapter

src/langbot/pkg/platform/adapters/dingtalk/message_converter.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import datetime
+import typing
+
+from langbot.libs.dingtalk_api.dingtalkevent import DingTalkEvent
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class DingTalkMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    def _format_image_as_markdown(msg: platform_message.Image) -> str:
+        if msg.url:
+            return f'\n![image]({msg.url})\n'
+        if msg.base64:
+            if msg.base64.startswith('data:'):
+                return f'\n![image]({msg.base64})\n'
+            return f'\n![image](data:image/png;base64,{msg.base64})\n'
+        return ''
+
+    @staticmethod
+    def _component_text_fallback(component: platform_message.MessageComponent) -> str:
+        if isinstance(component, platform_message.At):
+            return f'@{component.display or component.target}'
+        if isinstance(component, platform_message.AtAll):
+            return '@所有人'
+        if isinstance(component, platform_message.File):
+            if component.url:
+                return f'\n[{component.name or "file"}]({component.url})\n'
+            return f'\n[File]{component.name or component.id or "file"}\n'
+        if isinstance(component, platform_message.Voice):
+            return component.url or '[Voice]'
+        if isinstance(component, platform_message.Face):
+            return str(component)
+        if isinstance(component, platform_message.Unknown):
+            return component.text
+        return str(component)
+
+    @staticmethod
+    async def yiri2target(
+        message_chain: platform_message.MessageChain,
+        markdown_enabled: bool = True,
+    ) -> tuple[str, bool]:
+        content = ''
+        at = False
+        for msg in message_chain:
+            if isinstance(msg, platform_message.Source):
+                continue
+            if isinstance(msg, platform_message.Plain):
+                content += msg.text
+            elif isinstance(msg, platform_message.At):
+                at = True
+                content += DingTalkMessageConverter._component_text_fallback(msg)
+            elif isinstance(msg, platform_message.AtAll):
+                content += DingTalkMessageConverter._component_text_fallback(msg)
+            elif isinstance(msg, platform_message.Image):
+                if markdown_enabled:
+                    content += DingTalkMessageConverter._format_image_as_markdown(msg)
+                else:
+                    content += '[Image]'
+            elif isinstance(msg, platform_message.File):
+                content += DingTalkMessageConverter._component_text_fallback(msg)
+            elif isinstance(msg, platform_message.Voice):
+                content += DingTalkMessageConverter._component_text_fallback(msg)
+            elif isinstance(msg, platform_message.Quote):
+                if msg.id is not None:
+                    content += f'[引用消息 {msg.id}] '
+                if msg.origin:
+                    quote_content, quote_at = await DingTalkMessageConverter.yiri2target(msg.origin, markdown_enabled)
+                    content += quote_content
+                    at = at or quote_at
+            elif isinstance(msg, platform_message.Forward):
+                for node in msg.node_list:
+                    sender = node.sender_name or node.sender_id or ''
+                    if sender:
+                        content += f'\n[{sender}] '
+                    if node.message_chain:
+                        forwarded_content, forwarded_at = await DingTalkMessageConverter.yiri2target(
+                            node.message_chain, markdown_enabled
+                        )
+                        content += forwarded_content
+                        at = at or forwarded_at
+            else:
+                content += DingTalkMessageConverter._component_text_fallback(msg)
+        return content, at
+
+    @staticmethod
+    async def target2yiri(event: DingTalkEvent, bot_name: str) -> platform_message.MessageChain:
+        incoming_message = event.incoming_message
+        components: list[platform_message.MessageComponent] = [
+            platform_message.Source(
+                id=getattr(incoming_message, 'message_id', ''),
+                time=DingTalkMessageConverter._message_time(incoming_message),
+            )
+        ]
+
+        for at_user in getattr(incoming_message, 'at_users', []) or []:
+            if getattr(at_user, 'dingtalk_id', None) == getattr(incoming_message, 'chatbot_user_id', None):
+                components.append(platform_message.At(target=bot_name, display=bot_name))
+
+        rich_content = event.rich_content
+        if rich_content:
+            for element in rich_content.get('Elements') or []:
+                if element.get('Type') == 'text':
+                    text = DingTalkMessageConverter._strip_bot_mention(element.get('Content', ''), bot_name)
+                    if text.strip():
+                        components.append(platform_message.Plain(text=text))
+                elif element.get('Type') == 'image' and element.get('Picture'):
+                    components.append(platform_message.Image(base64=element['Picture']))
+        else:
+            if event.content and event.type != 'audio':
+                components.append(
+                    platform_message.Plain(
+                        text=DingTalkMessageConverter._strip_bot_mention(event.content, bot_name),
+                    )
+                )
+            if event.picture:
+                components.append(platform_message.Image(base64=event.picture))
+
+        if event.file:
+            components.append(platform_message.File(url=event.file, name=event.name or 'file'))
+        if event.audio:
+            if event.content and event.type == 'audio':
+                components.append(platform_message.Plain(text=event.content))
+            else:
+                components.append(platform_message.Voice(base64=event.audio))
+
+        quote = DingTalkMessageConverter._quote_component(event)
+        if quote:
+            components.append(quote)
+
+        return platform_message.MessageChain(components)
+
+    @staticmethod
+    def _quote_component(event: DingTalkEvent) -> platform_message.Quote | None:
+        quote_info = event.quoted_message
+        if not quote_info:
+            return None
+        origin_components: list[platform_message.MessageComponent] = []
+        msg_type = quote_info.get('msg_type', '')
+        if msg_type == 'file' and quote_info.get('file_url'):
+            origin_components.append(
+                platform_message.File(url=quote_info['file_url'], name=quote_info.get('file_name', 'file'))
+            )
+        elif msg_type == 'picture' and quote_info.get('picture'):
+            origin_components.append(platform_message.Image(base64=quote_info['picture']))
+        elif msg_type == 'audio' and quote_info.get('audio'):
+            origin_components.append(platform_message.Voice(base64=quote_info['audio']))
+        elif quote_info.get('content'):
+            origin_components.append(platform_message.Plain(text=str(quote_info['content'])))
+
+        incoming_message = event.incoming_message
+        return platform_message.Quote(
+            id=quote_info.get('message_id') or None,
+            group_id=getattr(incoming_message, 'conversation_id', None),
+            sender_id=quote_info.get('sender_id') or None,
+            target_id=getattr(incoming_message, 'conversation_id', None)
+            or getattr(incoming_message, 'sender_staff_id', None),
+            origin=platform_message.MessageChain(origin_components),
+        )
+
+    @staticmethod
+    def _strip_bot_mention(text: str, bot_name: str) -> str:
+        return text.replace('@' + bot_name, '')
+
+    @staticmethod
+    def _message_time(incoming_message: typing.Any) -> datetime.datetime:
+        value = getattr(incoming_message, 'create_at', None)
+        if isinstance(value, datetime.datetime):
+            return value
+        if isinstance(value, (int, float)):
+            timestamp = float(value)
+            if timestamp > 10_000_000_000:
+                timestamp = timestamp / 1000
+            return datetime.datetime.fromtimestamp(timestamp)
+        return datetime.datetime.now()

src/langbot/pkg/platform/adapters/dingtalk/platform_api.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import typing
+
+from langbot.libs.dingtalk_api.api import DingTalkClient
+
+
+async def check_access_token(bot: DingTalkClient, params: dict) -> dict:
+    return {'valid': await bot.check_access_token()}
+
+
+async def refresh_access_token(bot: DingTalkClient, params: dict) -> dict:
+    await bot.get_access_token()
+    return {'ok': bool(bot.access_token)}
+
+
+async def get_file_url(bot: DingTalkClient, params: dict) -> dict:
+    download_code = params.get('download_code') or params.get('downloadCode') or params.get('file_id')
+    if not download_code:
+        raise ValueError('download_code is required')
+    return {'url': await bot.get_file_url(str(download_code))}
+
+
+async def get_audio_base64(bot: DingTalkClient, params: dict) -> dict:
+    download_code = params.get('download_code') or params.get('downloadCode') or params.get('file_id')
+    if not download_code:
+        raise ValueError('download_code is required')
+    return {'base64': await bot.get_audio_url(str(download_code))}
+
+
+async def download_image_base64(bot: DingTalkClient, params: dict) -> dict:
+    download_code = params.get('download_code') or params.get('downloadCode') or params.get('file_id')
+    if not download_code:
+        raise ValueError('download_code is required')
+    return {'base64': await bot.download_image(str(download_code))}
+
+
+PLATFORM_API_MAP: dict[str, typing.Callable[[DingTalkClient, dict], typing.Awaitable[dict]]] = {
+    'check_access_token': check_access_token,
+    'refresh_access_token': refresh_access_token,
+    'get_file_url': get_file_url,
+    'get_audio_base64': get_audio_base64,
+    'download_image_base64': download_image_base64,
+}

src/langbot/pkg/platform/adapters/dingtalk/types.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+ADAPTER_NAME = 'dingtalk'

src/langbot/pkg/platform/adapters/discord/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from langbot.pkg.platform.adapters.discord.adapter import DiscordAdapter
+
+__all__ = ['DiscordAdapter']

src/langbot/pkg/platform/adapters/discord/adapter.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import os
+import traceback
+import typing
+
+import discord
+import pydantic
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot.pkg.platform.adapters.discord.api_impl import DiscordAPIMixin
+from langbot.pkg.platform.adapters.discord.event_converter import DiscordEventConverter
+from langbot.pkg.platform.adapters.discord.message_converter import DiscordMessageConverter
+from langbot.pkg.platform.adapters.discord.platform_api import PLATFORM_API_MAP
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class DiscordAdapter(DiscordAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    bot: discord.Client = pydantic.Field(exclude=True)
+
+    message_converter: DiscordMessageConverter = DiscordMessageConverter()
+    event_converter: DiscordEventConverter = DiscordEventConverter()
+
+    config: dict
+    listeners: dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = {}
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        adapter_self = self
+
+        class LangBotDiscordClient(discord.Client):
+            async def on_ready(self: discord.Client):
+                adapter_self.bot_account_id = str(self.user.id) if self.user else ''
+                await adapter_self.logger.info(f'Discord adapter running as {self.user}')
+
+            async def on_message(self: discord.Client, message: discord.Message):
+                if self.user and message.author.id == self.user.id:
+                    return
+                if message.author.bot:
+                    return
+                try:
+                    if (
+                        platform_events.FriendMessage in adapter_self.listeners
+                        or platform_events.GroupMessage in adapter_self.listeners
+                    ):
+                        legacy_event = await adapter_self.event_converter.target2legacy(message)
+                        callback = adapter_self.listeners.get(type(legacy_event))
+                        if callback:
+                            await callback(legacy_event, adapter_self)
+
+                    eba_event = await adapter_self.event_converter.target2yiri(
+                        message, self.user.id if self.user else None
+                    )
+                    if eba_event:
+                        await adapter_self._dispatch_eba_event(eba_event)
+                except Exception:
+                    await adapter_self.logger.error(f'Error in discord on_message: {traceback.format_exc()}')
+
+            async def on_message_edit(self: discord.Client, before: discord.Message, after: discord.Message):
+                await adapter_self._dispatch_gateway_tuple(
+                    'message_edit', (before, after), self.user.id if self.user else None
+                )
+
+            async def on_message_delete(self: discord.Client, message: discord.Message):
+                await adapter_self._dispatch_gateway_tuple(
+                    'message_delete', message, self.user.id if self.user else None
+                )
+
+            async def on_raw_message_delete(self: discord.Client, payload: discord.RawMessageDeleteEvent):
+                await adapter_self._dispatch_gateway_tuple(
+                    'raw_message_delete',
+                    payload,
+                    self.user.id if self.user else None,
+                )
+
+            async def on_reaction_add(
+                self: discord.Client, reaction: discord.Reaction, user: discord.User | discord.Member
+            ):
+                if self.user and user.id == self.user.id:
+                    return
+                await adapter_self._dispatch_gateway_tuple(
+                    'reaction_add', (reaction, user), self.user.id if self.user else None
+                )
+
+            async def on_reaction_remove(
+                self: discord.Client, reaction: discord.Reaction, user: discord.User | discord.Member
+            ):
+                if self.user and user.id == self.user.id:
+                    return
+                await adapter_self._dispatch_gateway_tuple(
+                    'reaction_remove', (reaction, user), self.user.id if self.user else None
+                )
+
+            async def on_raw_reaction_add(self: discord.Client, payload: discord.RawReactionActionEvent):
+                if self.user and payload.user_id == self.user.id:
+                    return
+                await adapter_self._dispatch_gateway_tuple(
+                    'raw_reaction_add',
+                    payload,
+                    self.user.id if self.user else None,
+                )
+
+            async def on_raw_reaction_remove(self: discord.Client, payload: discord.RawReactionActionEvent):
+                if self.user and payload.user_id == self.user.id:
+                    return
+                await adapter_self._dispatch_gateway_tuple(
+                    'raw_reaction_remove',
+                    payload,
+                    self.user.id if self.user else None,
+                )
+
+            async def on_member_join(self: discord.Client, member: discord.Member):
+                await adapter_self._dispatch_gateway_tuple('member_join', member, self.user.id if self.user else None)
+
+            async def on_member_remove(self: discord.Client, member: discord.Member):
+                await adapter_self._dispatch_gateway_tuple('member_remove', member, self.user.id if self.user else None)
+
+            async def on_guild_join(self: discord.Client, guild: discord.Guild):
+                await adapter_self._dispatch_gateway_tuple('guild_join', guild, self.user.id if self.user else None)
+
+            async def on_guild_remove(self: discord.Client, guild: discord.Guild):
+                await adapter_self._dispatch_gateway_tuple('guild_remove', guild, self.user.id if self.user else None)
+
+        intents = discord.Intents.default()
+        intents.message_content = True
+        intents.members = True
+        intents.reactions = True
+
+        args = {}
+        if os.getenv('http_proxy'):
+            args['proxy'] = os.getenv('http_proxy')
+        bot = LangBotDiscordClient(intents=intents, **args)
+
+        super().__init__(
+            config=config,
+            logger=logger,
+            bot_account_id=config.get('client_id', ''),
+            listeners={},
+            bot=bot,
+        )
+
+    def get_supported_events(self) -> list[str]:
+        return [
+            'message.received',
+            'message.edited',
+            'message.deleted',
+            'message.reaction',
+            'group.member_joined',
+            'group.member_left',
+            'bot.invited_to_group',
+            'bot.removed_from_group',
+            'platform.specific',
+        ]
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'send_message',
+            'reply_message',
+            'edit_message',
+            'delete_message',
+            'forward_message',
+            'get_group_info',
+            'get_group_member_list',
+            'get_group_member_info',
+            'get_user_info',
+            'get_file_url',
+            'mute_member',
+            'unmute_member',
+            'kick_member',
+            'leave_group',
+            'call_platform_api',
+        ]
+
+    async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain):
+        content, files = await self.message_converter.yiri2target(message)
+        channel = await self._get_channel(target_id)
+        kwargs = {'content': content}
+        if files:
+            kwargs['files'] = files
+        sent = await channel.send(**kwargs)
+        return platform_events.MessageResult(message_id=sent.id, raw={'message_id': sent.id})
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ):
+        assert isinstance(message_source.source_platform_object, discord.Message)
+        content, files = await self.message_converter.yiri2target(message)
+        kwargs = {'content': content}
+        if files:
+            kwargs['files'] = files
+        if quote_origin:
+            kwargs['reference'] = message_source.source_platform_object
+            kwargs['mention_author'] = any(isinstance(component, platform_message.At) for component in message.root)
+        sent = await message_source.source_platform_object.channel.send(**kwargs)
+        return platform_events.MessageResult(message_id=sent.id, raw={'message_id': sent.id})
+
+    async def _dispatch_gateway_tuple(self, kind: str, payload, bot_user_id: int | None):
+        try:
+            event = await self.event_converter.target2yiri((kind, payload), bot_user_id)
+            if event:
+                await self._dispatch_eba_event(event)
+        except Exception:
+            await self.logger.error(f'Error in discord {kind}: {traceback.format_exc()}')
+
+    async def _dispatch_eba_event(self, event: platform_events.EBAEvent):
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners.pop(event_type, None)
+
+    async def call_platform_api(self, action: str, params: dict = {}) -> dict:
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+            raise NotSupportedError(f'call_platform_api:{action}')
+        return await handler(self.bot, params)
+
+    async def run_async(self):
+        await self.bot.start(self.config['token'], reconnect=True)
+
+    async def kill(self) -> bool:
+        await self.bot.close()
+        return True

src/langbot/pkg/platform/adapters/discord/api_impl.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import datetime
+import typing
+
+import discord
+
+from langbot.pkg.platform.adapters.discord.event_converter import DiscordEventConverter
+from langbot.pkg.platform.adapters.discord.message_converter import DiscordMessageConverter
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class DiscordAPIMixin:
+    bot: discord.Client
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: platform_message.MessageChain,
+    ) -> None:
+        channel = await self._get_channel(chat_id)
+        message = await channel.fetch_message(int(message_id))
+        content, files = await DiscordMessageConverter.yiri2target(new_content)
+        if files:
+            await message.edit(content=content, attachments=[])
+            await channel.send(content=content, files=files)
+            return
+        await message.edit(content=content)
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        channel = await self._get_channel(chat_id)
+        message = await channel.fetch_message(int(message_id))
+        await message.delete()
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> platform_events.MessageResult:
+        from_channel = await self._get_channel(from_chat_id)
+        to_channel = await self._get_channel(to_chat_id)
+        message = await from_channel.fetch_message(int(message_id))
+        files = [await attachment.to_file() for attachment in message.attachments]
+        sent = await to_channel.send(content=message.content, files=files)
+        return platform_events.MessageResult(message_id=sent.id, raw={'message_id': sent.id})
+
+    async def get_group_info(self, group_id: typing.Union[int, str]) -> platform_entities.UserGroup:
+        guild = await self._get_guild(group_id)
+        return DiscordEventConverter.group_from_guild(guild)
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        guild = await self._get_guild(group_id)
+        members = guild.members or [member async for member in guild.fetch_members(limit=None)]
+        return [self._member_to_entity(member) for member in members]
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        guild = await self._get_guild(group_id)
+        member = guild.get_member(int(user_id)) or await guild.fetch_member(int(user_id))
+        return self._member_to_entity(member)
+
+    async def get_user_info(self, user_id: typing.Union[int, str]) -> platform_entities.User:
+        user = self.bot.get_user(int(user_id)) or await self.bot.fetch_user(int(user_id))
+        return DiscordEventConverter.user_from_author(user)
+
+    async def upload_file(self, file_data: bytes, filename: str) -> str:
+        from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+        raise NotSupportedError('upload_file')
+
+    async def get_file_url(self, file_id: str) -> str:
+        return file_id
+
+    async def mute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        guild = await self._get_guild(group_id)
+        member = guild.get_member(int(user_id)) or await guild.fetch_member(int(user_id))
+        until = None
+        if duration > 0:
+            until = datetime.datetime.now(datetime.UTC) + datetime.timedelta(seconds=duration)
+        await member.timeout(until, reason='LangBot EBA mute_member')
+
+    async def unmute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        guild = await self._get_guild(group_id)
+        member = guild.get_member(int(user_id)) or await guild.fetch_member(int(user_id))
+        await member.timeout(None, reason='LangBot EBA unmute_member')
+
+    async def kick_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        guild = await self._get_guild(group_id)
+        member = guild.get_member(int(user_id)) or await guild.fetch_member(int(user_id))
+        await member.kick(reason='LangBot EBA kick_member')
+
+    async def leave_group(self, group_id: typing.Union[int, str]) -> None:
+        guild = await self._get_guild(group_id)
+        await guild.leave()
+
+    async def _get_channel(self, channel_id: typing.Union[int, str]) -> discord.abc.Messageable:
+        channel = self.bot.get_channel(int(channel_id))
+        if channel is None:
+            channel = await self.bot.fetch_channel(int(channel_id))
+        return channel
+
+    async def _get_guild(self, guild_id: typing.Union[int, str]) -> discord.Guild:
+        guild = self.bot.get_guild(int(guild_id))
+        if guild is None:
+            guild = await self.bot.fetch_guild(int(guild_id))
+        return guild
+
+    @staticmethod
+    def _member_to_entity(member: discord.Member) -> platform_entities.UserGroupMember:
+        role = platform_entities.MemberRole.MEMBER
+        if member.guild.owner_id == member.id:
+            role = platform_entities.MemberRole.OWNER
+        elif member.guild_permissions.administrator or member.guild_permissions.manage_guild:
+            role = platform_entities.MemberRole.ADMIN
+        return platform_entities.UserGroupMember(
+            user=DiscordEventConverter.user_from_author(member),
+            group_id=member.guild.id,
+            role=role,
+            display_name=member.display_name,
+            joined_at=member.joined_at.timestamp() if member.joined_at else None,
+            title=member.top_role.name if member.top_role else None,
+        )

src/langbot/pkg/platform/adapters/discord/discord.svg

@@ -0,0 +1,7 @@
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+
+<!-- Uploaded to: SVG Repo, www.svgrepo.com, Transformed by: SVG Repo Mixer Tools -->
+<svg width="80px" height="80px" viewBox="0 -28.5 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid" fill="#000000">
+
+<g id="SVGRepo_bgCarrier" stroke-width="0"/>
+

src/langbot/pkg/platform/adapters/discord/event_converter.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import typing
+
+import discord
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot.pkg.platform.adapters.discord.message_converter import DiscordMessageConverter
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+
+
+class DiscordEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    @staticmethod
+    async def yiri2target(event: platform_events.Event) -> discord.Message:
+        raise NotImplementedError
+
+    @staticmethod
+    async def target2yiri(event: typing.Any, bot_user_id: int | None = None) -> platform_events.Event | None:
+        if isinstance(event, discord.Message):
+            return await DiscordEventConverter.message_to_eba(event)
+        if isinstance(event, tuple) and len(event) == 2:
+            kind, payload = event
+            if kind == 'message_edit':
+                before, after = payload
+                return await DiscordEventConverter.message_edit_to_eba(before, after)
+            if kind == 'message_delete':
+                return await DiscordEventConverter.message_delete_to_eba(payload)
+            if kind == 'raw_message_delete':
+                return DiscordEventConverter.raw_message_delete_to_eba(payload)
+            if kind == 'reaction_add':
+                reaction, user = payload
+                return DiscordEventConverter.reaction_to_eba(reaction, user, True)
+            if kind == 'reaction_remove':
+                reaction, user = payload
+                return DiscordEventConverter.reaction_to_eba(reaction, user, False)
+            if kind == 'raw_reaction_add':
+                return DiscordEventConverter.raw_reaction_to_eba(payload, True)
+            if kind == 'raw_reaction_remove':
+                return DiscordEventConverter.raw_reaction_to_eba(payload, False)
+            if kind == 'member_join':
+                return DiscordEventConverter.member_join_to_eba(payload, bot_user_id)
+            if kind == 'member_remove':
+                return DiscordEventConverter.member_left_to_eba(payload, bot_user_id)
+            if kind == 'guild_join':
+                return DiscordEventConverter.guild_join_to_eba(payload)
+            if kind == 'guild_remove':
+                return DiscordEventConverter.guild_remove_to_eba(payload)
+        return None
+
+    @staticmethod
+    async def message_to_eba(message: discord.Message) -> platform_events.MessageReceivedEvent:
+        message_chain = await DiscordMessageConverter.target2yiri(message)
+        group = DiscordEventConverter.group_from_message(message)
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name='discord',
+            message_id=message.id,
+            message_chain=message_chain,
+            sender=DiscordEventConverter.user_from_author(message.author),
+            chat_type=platform_entities.ChatType.PRIVATE
+            if isinstance(message.channel, discord.DMChannel)
+            else platform_entities.ChatType.GROUP,
+            chat_id=message.channel.id,
+            group=group,
+            timestamp=message.created_at.timestamp(),
+            source_platform_object=message,
+        )
+
+    @staticmethod
+    async def message_edit_to_eba(
+        before: discord.Message, after: discord.Message
+    ) -> platform_events.MessageEditedEvent:
+        return platform_events.MessageEditedEvent(
+            type='message.edited',
+            adapter_name='discord',
+            message_id=after.id,
+            new_content=await DiscordMessageConverter.target2yiri(after),
+            editor=DiscordEventConverter.user_from_author(after.author),
+            chat_type=platform_entities.ChatType.PRIVATE
+            if isinstance(after.channel, discord.DMChannel)
+            else platform_entities.ChatType.GROUP,
+            chat_id=after.channel.id,
+            group=DiscordEventConverter.group_from_message(after),
+            timestamp=after.edited_at.timestamp() if after.edited_at else after.created_at.timestamp(),
+            source_platform_object=after,
+        )
+
+    @staticmethod
+    async def message_delete_to_eba(message: discord.Message) -> platform_events.MessageDeletedEvent:
+        return platform_events.MessageDeletedEvent(
+            type='message.deleted',
+            adapter_name='discord',
+            message_id=message.id,
+            operator=None,
+            chat_type=platform_entities.ChatType.PRIVATE
+            if isinstance(message.channel, discord.DMChannel)
+            else platform_entities.ChatType.GROUP,
+            chat_id=message.channel.id,
+            group=DiscordEventConverter.group_from_message(message),
+            timestamp=message.created_at.timestamp() if message.created_at else 0.0,
+            source_platform_object=message,
+        )
+
+    @staticmethod
+    def raw_message_delete_to_eba(payload: discord.RawMessageDeleteEvent) -> platform_events.MessageDeletedEvent:
+        return platform_events.MessageDeletedEvent(
+            type='message.deleted',
+            adapter_name='discord',
+            message_id=payload.message_id,
+            operator=None,
+            chat_type=platform_entities.ChatType.PRIVATE
+            if payload.guild_id is None
+            else platform_entities.ChatType.GROUP,
+            chat_id=payload.channel_id,
+            group=platform_entities.UserGroup(id=payload.guild_id) if payload.guild_id is not None else None,
+            source_platform_object=payload,
+        )
+
+    @staticmethod
+    def reaction_to_eba(
+        reaction: discord.Reaction,
+        user: discord.User | discord.Member,
+        is_add: bool,
+    ) -> platform_events.MessageReactionEvent:
+        message = reaction.message
+        return platform_events.MessageReactionEvent(
+            type='message.reaction',
+            adapter_name='discord',
+            message_id=message.id,
+            user=DiscordEventConverter.user_from_author(user),
+            reaction=str(reaction.emoji),
+            is_add=is_add,
+            chat_type=platform_entities.ChatType.PRIVATE
+            if isinstance(message.channel, discord.DMChannel)
+            else platform_entities.ChatType.GROUP,
+            chat_id=message.channel.id,
+            group=DiscordEventConverter.group_from_message(message),
+            source_platform_object=reaction,
+        )
+
+    @staticmethod
+    def raw_reaction_to_eba(
+        payload: discord.RawReactionActionEvent,
+        is_add: bool,
+    ) -> platform_events.MessageReactionEvent:
+        member = getattr(payload, 'member', None)
+        user = member or getattr(payload, 'user', None)
+        if user is None:
+            user = platform_entities.User(id=payload.user_id)
+        else:
+            user = DiscordEventConverter.user_from_author(user)
+        return platform_events.MessageReactionEvent(
+            type='message.reaction',
+            adapter_name='discord',
+            message_id=payload.message_id,
+            user=user,
+            reaction=str(payload.emoji),
+            is_add=is_add,
+            chat_type=platform_entities.ChatType.PRIVATE
+            if payload.guild_id is None
+            else platform_entities.ChatType.GROUP,
+            chat_id=payload.channel_id,
+            group=platform_entities.UserGroup(id=payload.guild_id) if payload.guild_id is not None else None,
+            source_platform_object=payload,
+        )
+
+    @staticmethod
+    def member_join_to_eba(
+        member: discord.Member,
+        bot_user_id: int | None,
+    ) -> platform_events.BotInvitedToGroupEvent | platform_events.MemberJoinedEvent:
+        group = DiscordEventConverter.group_from_guild(member.guild)
+        user = DiscordEventConverter.user_from_author(member)
+        if bot_user_id is not None and member.id == bot_user_id:
+            return platform_events.BotInvitedToGroupEvent(
+                type='bot.invited_to_group',
+                adapter_name='discord',
+                group=group,
+                inviter=None,
+                timestamp=member.joined_at.timestamp() if member.joined_at else 0.0,
+                source_platform_object=member,
+            )
+        return platform_events.MemberJoinedEvent(
+            type='group.member_joined',
+            adapter_name='discord',
+            group=group,
+            member=user,
+            inviter=None,
+            join_type='direct',
+            timestamp=member.joined_at.timestamp() if member.joined_at else 0.0,
+            source_platform_object=member,
+        )
+
+    @staticmethod
+    def member_left_to_eba(
+        member: discord.Member,
+        bot_user_id: int | None,
+    ) -> platform_events.BotRemovedFromGroupEvent | platform_events.MemberLeftEvent:
+        group = DiscordEventConverter.group_from_guild(member.guild)
+        user = DiscordEventConverter.user_from_author(member)
+        if bot_user_id is not None and member.id == bot_user_id:
+            return platform_events.BotRemovedFromGroupEvent(
+                type='bot.removed_from_group',
+                adapter_name='discord',
+                group=group,
+                operator=None,
+                source_platform_object=member,
+            )
+        return platform_events.MemberLeftEvent(
+            type='group.member_left',
+            adapter_name='discord',
+            group=group,
+            member=user,
+            is_kicked=False,
+            operator=None,
+            source_platform_object=member,
+        )
+
+    @staticmethod
+    def guild_join_to_eba(guild: discord.Guild) -> platform_events.BotInvitedToGroupEvent:
+        return platform_events.BotInvitedToGroupEvent(
+            type='bot.invited_to_group',
+            adapter_name='discord',
+            group=DiscordEventConverter.group_from_guild(guild),
+            inviter=None,
+            source_platform_object=guild,
+        )
+
+    @staticmethod
+    def guild_remove_to_eba(guild: discord.Guild) -> platform_events.BotRemovedFromGroupEvent:
+        return platform_events.BotRemovedFromGroupEvent(
+            type='bot.removed_from_group',
+            adapter_name='discord',
+            group=DiscordEventConverter.group_from_guild(guild),
+            operator=None,
+            source_platform_object=guild,
+        )
+
+    @staticmethod
+    async def target2legacy(message: discord.Message) -> platform_events.FriendMessage | platform_events.GroupMessage:
+        message_chain = await DiscordMessageConverter.target2yiri(message)
+        if isinstance(message.channel, discord.DMChannel):
+            return platform_events.FriendMessage(
+                sender=platform_entities.Friend(
+                    id=message.author.id,
+                    nickname=message.author.name,
+                    remark=str(message.channel.id),
+                ),
+                message_chain=message_chain,
+                time=message.created_at.timestamp(),
+                source_platform_object=message,
+            )
+        return platform_events.GroupMessage(
+            sender=platform_entities.GroupMember(
+                id=message.author.id,
+                member_name=message.author.display_name,
+                permission=platform_entities.Permission.Member,
+                group=platform_entities.Group(
+                    id=message.channel.id,
+                    name=message.channel.name,
+                    permission=platform_entities.Permission.Member,
+                ),
+                special_title='',
+            ),
+            message_chain=message_chain,
+            time=message.created_at.timestamp(),
+            source_platform_object=message,
+        )
+
+    @staticmethod
+    def user_from_author(author: discord.User | discord.Member) -> platform_entities.User:
+        return platform_entities.User(
+            id=author.id,
+            nickname=getattr(author, 'display_name', None) or author.name,
+            avatar_url=str(author.display_avatar.url) if getattr(author, 'display_avatar', None) else None,
+            is_bot=author.bot,
+            username=author.name,
+        )
+
+    @staticmethod
+    def group_from_message(message: discord.Message) -> platform_entities.UserGroup | None:
+        guild = getattr(message, 'guild', None)
+        if guild is None:
+            return None
+        return DiscordEventConverter.group_from_guild(guild)
+
+    @staticmethod
+    def group_from_guild(guild: discord.Guild) -> platform_entities.UserGroup:
+        return platform_entities.UserGroup(
+            id=guild.id,
+            name=guild.name,
+            member_count=guild.member_count,
+            avatar_url=str(guild.icon.url) if guild.icon else None,
+            owner_id=guild.owner_id,
+        )

src/langbot/pkg/platform/adapters/discord/manifest.yaml

@@ -0,0 +1,89 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: discord-eba
+  label:
+    en_US: Discord (EBA)
+    zh_Hans: Discord (EBA)
+  description:
+    en_US: Discord adapter (EBA architecture)
+    zh_Hans: Discord 适配器（EBA 架构版本）
+  icon: discord.svg
+
+spec:
+  categories:
+    - popular
+    - global
+  config:
+    - name: client_id
+      label:
+        en_US: Client ID
+        zh_Hans: 客户端 ID
+      type: string
+      required: true
+      default: ""
+    - name: token
+      label:
+        en_US: Token
+        zh_Hans: 令牌
+      type: string
+      required: true
+      default: ""
+
+  supported_events:
+    - message.received
+    - message.edited
+    - message.deleted
+    - message.reaction
+    - group.member_joined
+    - group.member_left
+    - bot.invited_to_group
+    - bot.removed_from_group
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - edit_message
+      - delete_message
+      - forward_message
+      - get_group_info
+      - get_group_member_list
+      - get_group_member_info
+      - get_user_info
+      - get_file_url
+      - mute_member
+      - unmute_member
+      - kick_member
+      - leave_group
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: get_channel
+      description: { en_US: "Get channel information", zh_Hans: "获取频道信息" }
+    - action: get_guild
+      description: { en_US: "Get guild information", zh_Hans: "获取服务器信息" }
+    - action: get_guild_channels
+      description: { en_US: "Get guild channels", zh_Hans: "获取服务器频道列表" }
+    - action: get_guild_roles
+      description: { en_US: "Get guild roles", zh_Hans: "获取服务器角色列表" }
+    - action: create_invite
+      description: { en_US: "Create channel invite", zh_Hans: "创建频道邀请链接" }
+    - action: pin_message
+      description: { en_US: "Pin a message", zh_Hans: "置顶消息" }
+    - action: unpin_message
+      description: { en_US: "Unpin a message", zh_Hans: "取消置顶消息" }
+    - action: add_reaction
+      description: { en_US: "Add a reaction", zh_Hans: "添加表情回应" }
+    - action: remove_reaction
+      description: { en_US: "Remove a reaction", zh_Hans: "移除表情回应" }
+    - action: typing
+      description: { en_US: "Send typing indicator", zh_Hans: "发送正在输入状态" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: DiscordAdapter

src/langbot/pkg/platform/adapters/discord/message_converter.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import base64
+import datetime
+import io
+import os
+import re
+import uuid
+
+import discord
+
+from langbot.pkg.utils import httpclient
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class DiscordMessageConverter:
+    @staticmethod
+    async def yiri2target(
+        message_chain: platform_message.MessageChain,
+    ) -> tuple[str, list[discord.File]]:
+        text_parts: list[str] = []
+        files: list[discord.File] = []
+
+        for element in list(message_chain):
+            if isinstance(element, platform_message.At):
+                text_parts.append(f'<@{element.target}>')
+            elif isinstance(element, platform_message.AtAll):
+                text_parts.append('@everyone')
+            elif isinstance(element, platform_message.Plain):
+                text_parts.append(element.text)
+            elif isinstance(element, platform_message.Image):
+                file_bytes, filename = await DiscordMessageConverter._load_image(element)
+                if file_bytes:
+                    files.append(discord.File(fp=io.BytesIO(file_bytes), filename=filename))
+            elif isinstance(element, platform_message.Voice):
+                file_bytes, filename = await DiscordMessageConverter._load_voice(element)
+                if file_bytes:
+                    files.append(discord.File(fp=io.BytesIO(file_bytes), filename=filename))
+            elif isinstance(element, platform_message.File):
+                file_bytes = await DiscordMessageConverter._load_file(element)
+                if file_bytes:
+                    filename = element.name or f'{uuid.uuid4()}.bin'
+                    files.append(discord.File(fp=io.BytesIO(file_bytes), filename=filename))
+            elif isinstance(element, platform_message.Forward):
+                for node in element.node_list:
+                    node_text, node_files = await DiscordMessageConverter.yiri2target(node.message_chain)
+                    text_parts.append(node_text)
+                    files.extend(node_files)
+
+        return ''.join(text_parts), files
+
+    @staticmethod
+    async def target2yiri(message: discord.Message) -> platform_message.MessageChain:
+        message_time = datetime.datetime.fromtimestamp(int(message.created_at.timestamp()))
+        elements: list[platform_message.MessageComponent] = [platform_message.Source(id=message.id, time=message_time)]
+        elements.extend(DiscordMessageConverter._text_components(message.content))
+
+        for attachment in message.attachments:
+            if DiscordMessageConverter._is_image_attachment(attachment):
+                elements.append(platform_message.Image(url=attachment.url))
+            else:
+                elements.append(
+                    platform_message.File(
+                        name=attachment.filename,
+                        size=attachment.size or 0,
+                        url=attachment.url,
+                    )
+                )
+
+        return platform_message.MessageChain(elements)
+
+    @staticmethod
+    def _text_components(text: str) -> list[platform_message.MessageComponent]:
+        if not text:
+            return []
+
+        pattern = re.compile(r'(@everyone|@here|<@!?(\d+)>)')
+        components: list[platform_message.MessageComponent] = []
+        last = 0
+        for match in pattern.finditer(text):
+            if match.start() > last:
+                components.append(platform_message.Plain(text=text[last : match.start()]))
+            if match.group(1) in ('@everyone', '@here'):
+                components.append(platform_message.AtAll())
+            else:
+                components.append(platform_message.At(target=match.group(2)))
+            last = match.end()
+        if last < len(text):
+            components.append(platform_message.Plain(text=text[last:]))
+        return components
+
+    @staticmethod
+    async def _load_image(element: platform_message.Image) -> tuple[bytes | None, str]:
+        filename = f'{uuid.uuid4()}.png'
+        if element.base64:
+            header, _, payload = element.base64.partition(',')
+            data = payload or header
+            if 'jpeg' in header or 'jpg' in header:
+                filename = f'{uuid.uuid4()}.jpg'
+            elif 'gif' in header:
+                filename = f'{uuid.uuid4()}.gif'
+            elif 'webp' in header:
+                filename = f'{uuid.uuid4()}.webp'
+            return base64.b64decode(data), filename
+        if element.url:
+            data, content_type = await DiscordMessageConverter._download(element.url)
+            if 'jpeg' in content_type or 'jpg' in content_type:
+                filename = f'{uuid.uuid4()}.jpg'
+            elif 'gif' in content_type:
+                filename = f'{uuid.uuid4()}.gif'
+            elif 'webp' in content_type:
+                filename = f'{uuid.uuid4()}.webp'
+            return data, filename
+        if element.path:
+            path = os.path.abspath(element.path.replace('\x00', ''))
+            if not os.path.exists(path):
+                return None, filename
+            with open(path, 'rb') as fp:
+                data = fp.read()
+            ext = os.path.splitext(path)[1]
+            if ext:
+                filename = f'{uuid.uuid4()}{ext}'
+            return data, filename
+        return None, filename
+
+    @staticmethod
+    async def _load_voice(element: platform_message.Voice) -> tuple[bytes | None, str]:
+        filename = f'{uuid.uuid4()}.mp3'
+        if element.base64:
+            header, _, payload = element.base64.partition(',')
+            data = payload or header
+            for ext in ('wav', 'mp3', 'ogg', 'm4a', 'aac', 'flac', 'opus', 'webm'):
+                if ext in header:
+                    filename = f'{uuid.uuid4()}.{ext}'
+                    break
+            return base64.b64decode(data), filename
+        if element.url:
+            data, _ = await DiscordMessageConverter._download(element.url)
+            return data, filename
+        return None, filename
+
+    @staticmethod
+    async def _load_file(element: platform_message.File) -> bytes | None:
+        if element.base64:
+            return base64.b64decode(element.base64.split(',')[-1])
+        if element.url:
+            data, _ = await DiscordMessageConverter._download(element.url)
+            return data
+        return None
+
+    @staticmethod
+    async def _download(url: str) -> tuple[bytes, str]:
+        session = httpclient.get_session(trust_env=True)
+        async with session.get(url) as response:
+            return await response.read(), response.headers.get('Content-Type', '')
+
+    @staticmethod
+    def _is_image_attachment(attachment: discord.Attachment) -> bool:
+        content_type = attachment.content_type or ''
+        return content_type.startswith('image/') or attachment.filename.lower().endswith(
+            ('.png', '.jpg', '.jpeg', '.gif', '.webp')
+        )

src/langbot/pkg/platform/adapters/discord/platform_api.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import typing
+
+import discord
+
+
+async def get_channel(bot: discord.Client, params: dict) -> dict:
+    channel = bot.get_channel(int(params['channel_id'])) or await bot.fetch_channel(int(params['channel_id']))
+    return {
+        'id': channel.id,
+        'name': getattr(channel, 'name', ''),
+        'type': str(channel.type),
+        'guild_id': getattr(getattr(channel, 'guild', None), 'id', None),
+    }
+
+
+async def get_guild(bot: discord.Client, params: dict) -> dict:
+    guild = bot.get_guild(int(params['guild_id'])) or await bot.fetch_guild(int(params['guild_id']))
+    return {'id': guild.id, 'name': guild.name, 'member_count': guild.member_count, 'owner_id': guild.owner_id}
+
+
+async def get_guild_channels(bot: discord.Client, params: dict) -> dict:
+    guild = bot.get_guild(int(params['guild_id'])) or await bot.fetch_guild(int(params['guild_id']))
+    channels = guild.channels or await guild.fetch_channels()
+    return {'channels': [{'id': channel.id, 'name': channel.name, 'type': str(channel.type)} for channel in channels]}
+
+
+async def get_guild_roles(bot: discord.Client, params: dict) -> dict:
+    guild = bot.get_guild(int(params['guild_id'])) or await bot.fetch_guild(int(params['guild_id']))
+    return {'roles': [{'id': role.id, 'name': role.name, 'position': role.position} for role in guild.roles]}
+
+
+async def create_invite(bot: discord.Client, params: dict) -> dict:
+    channel = bot.get_channel(int(params['channel_id'])) or await bot.fetch_channel(int(params['channel_id']))
+    invite = await channel.create_invite(
+        max_age=params.get('max_age', 0),
+        max_uses=params.get('max_uses', 0),
+        unique=params.get('unique', True),
+        reason=params.get('reason', 'LangBot EBA create_invite'),
+    )
+    return {'url': invite.url, 'code': invite.code}
+
+
+async def pin_message(bot: discord.Client, params: dict) -> dict:
+    channel = bot.get_channel(int(params['channel_id'])) or await bot.fetch_channel(int(params['channel_id']))
+    message = await channel.fetch_message(int(params['message_id']))
+    await message.pin(reason=params.get('reason', 'LangBot EBA pin_message'))
+    return {'ok': True}
+
+
+async def unpin_message(bot: discord.Client, params: dict) -> dict:
+    channel = bot.get_channel(int(params['channel_id'])) or await bot.fetch_channel(int(params['channel_id']))
+    message = await channel.fetch_message(int(params['message_id']))
+    await message.unpin(reason=params.get('reason', 'LangBot EBA unpin_message'))
+    return {'ok': True}
+
+
+async def add_reaction(bot: discord.Client, params: dict) -> dict:
+    channel = bot.get_channel(int(params['channel_id'])) or await bot.fetch_channel(int(params['channel_id']))
+    message = await channel.fetch_message(int(params['message_id']))
+    await message.add_reaction(params['emoji'])
+    return {'ok': True}
+
+
+async def remove_reaction(bot: discord.Client, params: dict) -> dict:
+    channel = bot.get_channel(int(params['channel_id'])) or await bot.fetch_channel(int(params['channel_id']))
+    message = await channel.fetch_message(int(params['message_id']))
+    user = (
+        bot.user
+        if 'user_id' not in params
+        else bot.get_user(int(params['user_id'])) or await bot.fetch_user(int(params['user_id']))
+    )
+    await message.remove_reaction(params['emoji'], user)
+    return {'ok': True}
+
+
+async def send_typing(bot: discord.Client, params: dict) -> dict:
+    channel = bot.get_channel(int(params['channel_id'])) or await bot.fetch_channel(int(params['channel_id']))
+    async with channel.typing():
+        return {'ok': True}
+
+
+PLATFORM_API_MAP: dict[str, typing.Callable[[discord.Client, dict], typing.Awaitable[dict]]] = {
+    'get_channel': get_channel,
+    'get_guild': get_guild,
+    'get_guild_channels': get_guild_channels,
+    'get_guild_roles': get_guild_roles,
+    'create_invite': create_invite,
+    'pin_message': pin_message,
+    'unpin_message': unpin_message,
+    'add_reaction': add_reaction,
+    'remove_reaction': remove_reaction,
+    'typing': send_typing,
+}

src/langbot/pkg/platform/adapters/discord/types.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import typing
+
+import pydantic
+
+
+class DiscordAdapterConfig(pydantic.BaseModel):
+    client_id: str
+    token: str
+    guild_id: typing.Optional[str] = None
+    debug_channel_id: typing.Optional[str] = None

src/langbot/pkg/platform/adapters/discord/voice.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+# Voice support is still implemented by the legacy Discord source adapter. The
+# EBA adapter exposes text, guild, member, moderation, and platform-specific APIs
+# first; voice-specific EBA actions will move here when that surface is migrated.

src/langbot/pkg/platform/adapters/lark/__init__.py

@@ -0,0 +1 @@
+"""Lark/Feishu EBA platform adapter."""

src/langbot/pkg/platform/adapters/lark/adapter.py

@@ -0,0 +1,680 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import json
+import time
+import traceback
+import typing
+import uuid
+
+from Crypto.Cipher import AES
+import lark_oapi
+from lark_oapi.api.auth.v3 import (
+    CreateAppAccessTokenRequest,
+    CreateAppAccessTokenRequestBody,
+    CreateAppAccessTokenResponse,
+    CreateTenantAccessTokenRequest,
+    CreateTenantAccessTokenRequestBody,
+    CreateTenantAccessTokenResponse,
+    ResendAppTicketRequest,
+    ResendAppTicketRequestBody,
+    ResendAppTicketResponse,
+)
+from lark_oapi.api.cardkit.v1 import (
+    ContentCardElementRequest,
+    ContentCardElementRequestBody,
+    ContentCardElementResponse,
+    CreateCardRequest,
+    CreateCardRequestBody,
+    CreateCardResponse,
+)
+from lark_oapi.api.im.v1 import (
+    CreateMessageRequest,
+    CreateMessageRequestBody,
+    CreateMessageResponse,
+    EventMessage,
+    EventSender,
+    P2ImMessageReceiveV1,
+    P2ImMessageReceiveV1Data,
+    ReplyMessageRequest,
+    ReplyMessageRequestBody,
+    ReplyMessageResponse,
+)
+import lark_oapi.ws.exception
+import pydantic
+import quart
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot.pkg.platform.adapters.lark.api_impl import LarkAPIMixin
+from langbot.pkg.platform.adapters.lark.event_converter import LarkEventConverter
+from langbot.pkg.platform.adapters.lark.message_converter import LarkMessageConverter
+from langbot.pkg.platform.adapters.lark.platform_api import PLATFORM_API_MAP
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class AESCipher:
+    def __init__(self, key: str):
+        self.key = hashlib.sha256(self.str_to_bytes(key)).digest()
+
+    @staticmethod
+    def str_to_bytes(data):
+        if isinstance(data, str):
+            return data.encode('utf8')
+        return data
+
+    @staticmethod
+    def _unpad(value: bytes) -> bytes:
+        return value[: -value[len(value) - 1]]
+
+    def decrypt_string(self, encrypted: str) -> str:
+        encrypted_bytes = base64.b64decode(encrypted)
+        iv = encrypted_bytes[: AES.block_size]
+        cipher = AES.new(self.key, AES.MODE_CBC, iv)
+        return self._unpad(cipher.decrypt(encrypted_bytes[AES.block_size :])).decode('utf8')
+
+
+class LarkAdapter(LarkAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    bot: lark_oapi.ws.Client = pydantic.Field(exclude=True)
+    api_client: lark_oapi.Client = pydantic.Field(exclude=True)
+    quart_app: quart.Quart = pydantic.Field(exclude=True)
+    cipher: AESCipher = pydantic.Field(exclude=True)
+
+    config: dict
+    lark_tenant_key: str = pydantic.Field(exclude=True, default='')
+    app_ticket: str | None = None
+    app_access_token: str | None = None
+    app_access_token_expire_at: int | None = None
+    tenant_access_tokens: dict[str, dict[str, typing.Any]] = pydantic.Field(default_factory=dict)
+    bot_uuid: str | None = None
+    event_loop: asyncio.AbstractEventLoop | None = pydantic.Field(exclude=True, default=None)
+
+    message_converter: LarkMessageConverter = LarkMessageConverter()
+    event_converter: LarkEventConverter = LarkEventConverter()
+    listeners: dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = pydantic.Field(default_factory=dict)
+    card_id_dict: dict[str, str] = pydantic.Field(default_factory=dict)
+    pending_monitoring_msg: dict[str, str] = pydantic.Field(default_factory=dict)
+    reply_to_monitoring_msg: dict[str, tuple[str, float]] = pydantic.Field(default_factory=dict)
+    _message_cache: dict[str, platform_events.MessageReceivedEvent] = pydantic.PrivateAttr(default_factory=dict)
+    _user_cache: dict[str, platform_entities.User] = pydantic.PrivateAttr(default_factory=dict)
+    _group_cache: dict[str, platform_entities.UserGroup] = pydantic.PrivateAttr(default_factory=dict)
+    _monitoring_mapping_ttl: int = 600
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger, **kwargs):
+        required_keys = ['app_id', 'app_secret', 'bot_name']
+        missing_keys = [key for key in required_keys if not config.get(key)]
+        if missing_keys:
+            raise ValueError(f'Lark missing required config: {", ".join(missing_keys)}')
+
+        api_client = self.build_api_client(config)
+        event_handler = self._build_event_handler()
+        bot = lark_oapi.ws.Client(config['app_id'], config['app_secret'], event_handler=event_handler)
+        cipher = AESCipher(config.get('encrypt-key', ''))
+
+        super().__init__(
+            config=config,
+            logger=logger,
+            lark_tenant_key=config.get('lark_tenant_key', ''),
+            bot_account_id=config['bot_name'],
+            bot=bot,
+            api_client=api_client,
+            quart_app=quart.Quart(__name__),
+            cipher=cipher,
+            listeners={},
+            card_id_dict={},
+            pending_monitoring_msg={},
+            reply_to_monitoring_msg={},
+            event_loop=None,
+            **kwargs,
+        )
+        self._message_cache = {}
+        self._user_cache = {}
+        self._group_cache = {}
+        self.request_app_ticket()
+
+    def _build_event_handler(self):
+        async def on_message(event: lark_oapi.im.v1.P2ImMessageReceiveV1):
+            await self._handle_message_event(event)
+
+        def sync_on_message(event: lark_oapi.im.v1.P2ImMessageReceiveV1):
+            self._submit_coro(on_message(event))
+
+        def sync_on_card_action(event):
+            return self._handle_card_action_sync(event)
+
+        return (
+            lark_oapi.EventDispatcherHandler.builder('', '')
+            .register_p2_im_message_receive_v1(sync_on_message)
+            .register_p2_card_action_trigger(sync_on_card_action)
+            .build()
+        )
+
+    def get_supported_events(self) -> list[str]:
+        return ['message.received', 'bot.invited_to_group', 'platform.specific']
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'send_message',
+            'reply_message',
+            'get_message',
+            'get_group_info',
+            'get_group_member_info',
+            'get_user_info',
+            'get_file_url',
+            'call_platform_api',
+        ]
+
+    def build_api_client(self, config: dict) -> lark_oapi.Client:
+        builder = lark_oapi.Client.builder().app_id(config['app_id']).app_secret(config['app_secret'])
+        if config.get('app_type', 'self') == 'isv':
+            builder = builder.app_type(lark_oapi.AppType.ISV)
+        return builder.build()
+
+    def request_app_ticket(self):
+        if self.config.get('app_type', 'self') != 'isv':
+            return
+        request = (
+            ResendAppTicketRequest.builder()
+            .request_body(
+                ResendAppTicketRequestBody.builder()
+                .app_id(self.config['app_id'])
+                .app_secret(self.config['app_secret'])
+                .build()
+            )
+            .build()
+        )
+        response: ResendAppTicketResponse = self.api_client.auth.v3.app_ticket.resend(request)
+        if not response.success():
+            raise RuntimeError(f'Lark app_ticket resend failed: {response.code} {response.msg}')
+
+    def request_app_access_token(self):
+        if self.config.get('app_type', 'self') != 'isv':
+            return
+        request = (
+            CreateAppAccessTokenRequest.builder()
+            .request_body(
+                CreateAppAccessTokenRequestBody.builder()
+                .app_id(self.config['app_id'])
+                .app_secret(self.config['app_secret'])
+                .app_ticket(self.app_ticket)
+                .build()
+            )
+            .build()
+        )
+        response: CreateAppAccessTokenResponse = self.api_client.auth.v3.app_access_token.create(request)
+        if not response.success():
+            raise RuntimeError(f'Lark app_access_token failed: {response.code} {response.msg}')
+        content = json.loads(response.raw.content)
+        self.app_access_token = content['app_access_token']
+        self.app_access_token_expire_at = int(time.time()) + content['expire'] - 300
+
+    def get_app_access_token(self):
+        if self.config.get('app_type', 'self') != 'isv':
+            return None
+        if (
+            self.app_access_token is None
+            or self.app_access_token_expire_at is None
+            or int(time.time()) >= self.app_access_token_expire_at
+        ):
+            self.request_app_access_token()
+        return self.app_access_token
+
+    def request_tenant_access_token(self, tenant_key: str):
+        if self.config.get('app_type', 'self') != 'isv':
+            return
+        request = (
+            CreateTenantAccessTokenRequest.builder()
+            .request_body(
+                CreateTenantAccessTokenRequestBody.builder()
+                .app_access_token(self.get_app_access_token())
+                .tenant_key(tenant_key)
+                .build()
+            )
+            .build()
+        )
+        response: CreateTenantAccessTokenResponse = self.api_client.auth.v3.tenant_access_token.create(request)
+        if not response.success():
+            raise RuntimeError(f'Lark tenant_access_token failed: {response.code} {response.msg}')
+        content = json.loads(response.raw.content)
+        self.tenant_access_tokens[tenant_key] = {
+            'token': content['tenant_access_token'],
+            'expire_at': int(time.time()) + content['expire'] - 300,
+        }
+
+    def get_tenant_access_token(self, tenant_key: str | None):
+        if self.config.get('app_type', 'self') != 'isv' or not tenant_key:
+            return None
+        cached = self.tenant_access_tokens.get(tenant_key)
+        if cached is None or int(time.time()) >= cached['expire_at']:
+            self.request_tenant_access_token(tenant_key)
+        return self.tenant_access_tokens.get(tenant_key, {}).get('token')
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ) -> platform_events.MessageResult:
+        text_elements, media_items = await self.message_converter.yiri2target(message, self.api_client)
+        receive_id_type = 'chat_id' if target_type == 'group' else 'open_id'
+        message_ids: list[str] = []
+
+        for msg_type, content in self._outbound_payloads(text_elements, media_items):
+            request = (
+                CreateMessageRequest.builder()
+                .receive_id_type(receive_id_type)
+                .request_body(
+                    CreateMessageRequestBody.builder()
+                    .receive_id(str(target_id))
+                    .content(json.dumps(content, ensure_ascii=False))
+                    .msg_type(msg_type)
+                    .uuid(str(uuid.uuid4()))
+                    .build()
+                )
+                .build()
+            )
+            response: CreateMessageResponse = await self.api_client.im.v1.message.acreate(request)
+            if not response.success():
+                raise RuntimeError(f'Lark send_message failed: {response.code} {response.msg}')
+            message_ids.append(getattr(response.data, 'message_id', ''))
+
+        return platform_events.MessageResult(
+            message_id=message_ids[-1] if message_ids else '', raw={'message_ids': message_ids}
+        )
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ) -> platform_events.MessageResult:
+        text_elements, media_items = await self.message_converter.yiri2target(message, self.api_client)
+        tenant_key = self._tenant_key_from_source(message_source)
+        message_ids: list[str] = []
+
+        for msg_type, content in self._outbound_payloads(text_elements, media_items):
+            request = (
+                ReplyMessageRequest.builder()
+                .message_id(self._message_id_from_source(message_source))
+                .request_body(
+                    ReplyMessageRequestBody.builder()
+                    .content(json.dumps(content, ensure_ascii=False))
+                    .msg_type(msg_type)
+                    .reply_in_thread(False)
+                    .uuid(str(uuid.uuid4()))
+                    .build()
+                )
+                .build()
+            )
+            response: ReplyMessageResponse = await self.api_client.im.v1.message.areply(
+                request, self.request_option(tenant_key)
+            )
+            if not response.success():
+                raise RuntimeError(f'Lark reply_message failed: {response.code} {response.msg}')
+            message_ids.append(getattr(response.data, 'message_id', ''))
+
+        return platform_events.MessageResult(
+            message_id=message_ids[-1] if message_ids else '', raw={'message_ids': message_ids}
+        )
+
+    def _outbound_payloads(self, text_elements: list[list[dict]], media_items: list[dict]) -> list[tuple[str, dict]]:
+        payloads: list[tuple[str, dict]] = []
+        if text_elements:
+            needs_post = any(ele.get('tag') == 'at' for paragraph in text_elements for ele in paragraph)
+            if needs_post:
+                payloads.append(('post', {'zh_Hans': {'title': '', 'content': text_elements}}))
+            else:
+                parts = []
+                for paragraph in text_elements:
+                    text = ''.join(ele.get('text', '') for ele in paragraph)
+                    if text:
+                        parts.append(text)
+                payloads.append(('text', {'text': '\n\n'.join(parts)}))
+        for media in media_items:
+            payloads.append((media['msg_type'], media['content']))
+        return payloads
+
+    async def is_stream_output_supported(self) -> bool:
+        return bool(self.config.get('enable-stream-reply', False))
+
+    async def on_monitoring_message_created(self, query, monitoring_message_id: str):
+        user_msg_id = getattr(query.message_event, 'message_id', None)
+        if user_msg_id:
+            self.pending_monitoring_msg[str(user_msg_id)] = monitoring_message_id
+
+    async def create_message_card(self, message_id, event) -> bool:
+        card_id = await self.create_card_id(message_id)
+        content = {'type': 'card', 'data': {'card_id': card_id, 'template_variable': {'content': 'Thinking...'}}}
+        request = (
+            ReplyMessageRequest.builder()
+            .message_id(self._message_id_from_source(event))
+            .request_body(
+                ReplyMessageRequestBody.builder().content(json.dumps(content)).msg_type('interactive').build()
+            )
+            .build()
+        )
+        response: ReplyMessageResponse = await self.api_client.im.v1.message.areply(
+            request, self.request_option(self._tenant_key_from_source(event))
+        )
+        if not response.success():
+            raise RuntimeError(f'Lark create_message_card failed: {response.code} {response.msg}')
+        return True
+
+    async def create_card_id(self, message_id) -> str:
+        card_data = {
+            'schema': '2.0',
+            'config': {'update_multi': True, 'streaming_mode': True},
+            'body': {
+                'direction': 'vertical',
+                'elements': [{'tag': 'markdown', 'content': '', 'element_id': 'streaming_txt'}],
+            },
+        }
+        request = (
+            CreateCardRequest.builder()
+            .request_body(CreateCardRequestBody.builder().type('card_json').data(json.dumps(card_data)).build())
+            .build()
+        )
+        response: CreateCardResponse = self.api_client.cardkit.v1.card.create(request)
+        if not response.success():
+            raise RuntimeError(f'Lark create_card failed: {response.code} {response.msg}')
+        self.card_id_dict[str(message_id)] = response.data.card_id
+        return response.data.card_id
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        if bot_message.msg_sequence % 8 != 0 and not is_final:
+            return
+        text_elements, _ = await self.message_converter.yiri2target(message, self.api_client)
+        content = '\n\n'.join(
+            ''.join(ele.get('text', '') for ele in paragraph if ele.get('tag') in {'text', 'md'})
+            for paragraph in text_elements
+        )
+        request = (
+            ContentCardElementRequest.builder()
+            .card_id(self.card_id_dict[bot_message.resp_message_id])
+            .element_id('streaming_txt')
+            .request_body(
+                ContentCardElementRequestBody.builder().content(content).sequence(bot_message.msg_sequence).build()
+            )
+            .build()
+        )
+        response: ContentCardElementResponse = self.api_client.cardkit.v1.card_element.content(
+            request, self.request_option(self._tenant_key_from_source(message_source))
+        )
+        if not response.success():
+            raise RuntimeError(f'Lark card_element update failed: {response.code} {response.msg}')
+        if is_final and bot_message.tool_calls is None:
+            self.card_id_dict.pop(bot_message.resp_message_id, None)
+
+    async def call_platform_api(self, action: str, params: dict = {}) -> dict:
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            raise NotSupportedError(f'call_platform_api:{action}')
+        return await handler(self, params)
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        if self.listeners.get(event_type) is callback:
+            self.listeners.pop(event_type, None)
+
+    def set_bot_uuid(self, bot_uuid: str):
+        self.bot_uuid = bot_uuid
+
+    def get_launcher_id(self, event: platform_events.MessageEvent) -> str | None:
+        source_event = getattr(event.source_platform_object, 'event', None)
+        message = getattr(source_event, 'message', None) if source_event else None
+        thread_id = getattr(message, 'thread_id', None)
+        if thread_id and isinstance(event, platform_events.MessageReceivedEvent) and event.group:
+            return f'{event.group.id}_{thread_id}'
+        return None
+
+    async def handle_unified_webhook(self, bot_uuid: str, path: str, request):
+        try:
+            data = await request.json
+            if 'encrypt' in data:
+                data = json.loads(self.cipher.decrypt_string(data['encrypt']))
+            event_type = self.get_event_type(data)
+            if event_type == 'url_verification':
+                return {'challenge': data.get('challenge')}
+            if event_type == 'app_ticket':
+                self.app_ticket = self._webhook_event(data).get('app_ticket')
+                return {'code': 200, 'message': 'ok'}
+            if event_type == 'im.message.receive_v1':
+                p2v1 = P2ImMessageReceiveV1()
+                p2v1.header = self._webhook_header(data)
+                event_data = P2ImMessageReceiveV1Data()
+                raw_event = self._webhook_event(data)
+                event_data.message = EventMessage(raw_event['message'])
+                event_data.sender = EventSender(raw_event['sender'])
+                p2v1.event = event_data
+                p2v1.schema = data.get('schema', '2.0')
+                await self._handle_message_event(p2v1)
+                return {'code': 200, 'message': 'ok'}
+            if event_type == 'im.chat.member.bot.added_v1':
+                raw_event = self._webhook_event(data)
+                header = self._webhook_header(data)
+                chat_id = raw_event.get('chat_id', '')
+                await self._send_bot_added_welcome(chat_id, getattr(header, 'tenant_key', None))
+                await self._dispatch_eba_event(LarkEventConverter.bot_invited_to_group(data, chat_id))
+                return {'code': 200, 'message': 'ok'}
+            if event_type == 'card.action.trigger':
+                feedback_event = self._feedback_event_from_webhook(data)
+                if feedback_event and platform_events.FeedbackEvent in self.listeners:
+                    await self.listeners[platform_events.FeedbackEvent](feedback_event, self)
+                return {'toast': {'type': 'success', 'content': '感谢您的反馈'}}
+            await self._dispatch_eba_event(LarkEventConverter.platform_specific(data, event_type, data))
+            return {'code': 200, 'message': 'ok'}
+        except Exception:
+            await self.logger.error(f'Error in lark webhook: {traceback.format_exc()}')
+            return {'code': 500, 'message': 'error'}
+
+    def get_event_type(self, data: dict) -> str:
+        schema = data.get('schema', '1.0')
+        if schema == '2.0':
+            return data.get('header', {}).get('event_type', '')
+        if 'event' in data:
+            return data['event'].get('type', '')
+        return data.get('type', '')
+
+    def _webhook_event(self, data: dict) -> dict:
+        return data.get('event', {})
+
+    def _webhook_header(self, data: dict):
+        return type('LarkWebhookHeader', (), data.get('header', {}))()
+
+    async def run_async(self):
+        self.event_loop = asyncio.get_running_loop()
+        if not self.config.get('enable-webhook', False):
+            try:
+                await self.bot._connect()
+            except lark_oapi.ws.exception.ClientException:
+                raise
+            except Exception:
+                await self.bot._disconnect()
+                if self.bot._auto_reconnect:
+                    await self.bot._reconnect()
+                else:
+                    raise
+        else:
+            while True:
+                await asyncio.sleep(1)
+
+    async def kill(self) -> bool:
+        self.bot._auto_reconnect = False
+        await self.bot._disconnect()
+        return True
+
+    async def is_muted(self, group_id: int | None = None) -> bool:
+        return False
+
+    async def _handle_message_event(self, event: lark_oapi.im.v1.P2ImMessageReceiveV1):
+        try:
+            if platform_events.FriendMessage in self.listeners or platform_events.GroupMessage in self.listeners:
+                legacy_event = await self.event_converter.target2legacy(event, self.api_client)
+                if legacy_event and type(legacy_event) in self.listeners:
+                    await self.listeners[type(legacy_event)](legacy_event, self)
+            eba_event = await self.event_converter.target2yiri(event, self.api_client)
+            if eba_event:
+                self._cache_event(eba_event)
+                await self._dispatch_eba_event(eba_event)
+        except Exception:
+            await self.logger.error(f'Error in lark message event: {traceback.format_exc()}')
+
+    async def _dispatch_eba_event(self, event: platform_events.Event):
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return
+
+    def _cache_event(self, event: platform_events.Event):
+        if not isinstance(event, platform_events.MessageReceivedEvent):
+            return
+        self._message_cache[str(event.message_id)] = event
+        self._user_cache[str(event.sender.id)] = event.sender
+        if event.group:
+            self._group_cache[str(event.group.id)] = event.group
+
+    def _handle_card_action_sync(self, event):
+        feedback_event = self._feedback_event_from_callback(event)
+        if feedback_event and platform_events.FeedbackEvent in self.listeners:
+            self._submit_coro(self.listeners[platform_events.FeedbackEvent](feedback_event, self))
+        from lark_oapi.event.callback.model.p2_card_action_trigger import P2CardActionTriggerResponse
+
+        return P2CardActionTriggerResponse({'toast': {'type': 'success', 'content': '感谢您的反馈'}})
+
+    def _submit_coro(self, coro):
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = self.event_loop
+            if loop and loop.is_running():
+                asyncio.run_coroutine_threadsafe(coro, loop)
+                return
+            coro.close()
+            raise
+        else:
+            loop.create_task(coro)
+
+    def _feedback_event_from_callback(self, event) -> platform_events.FeedbackEvent | None:
+        value = getattr(getattr(event.event, 'action', None), 'value', {}) or {}
+        return self._feedback_event(
+            raw=event,
+            feedback_id=getattr(event.header, 'event_id', str(uuid.uuid4())),
+            feedback_value=value.get('feedback', ''),
+            user_id=getattr(getattr(event.event, 'operator', None), 'open_id', None),
+            chat_id=getattr(getattr(event.event, 'context', None), 'open_chat_id', None),
+            message_id=getattr(getattr(event.event, 'context', None), 'open_message_id', None),
+        )
+
+    def _feedback_event_from_webhook(self, data: dict) -> platform_events.FeedbackEvent | None:
+        event = data.get('event', {})
+        value = event.get('action', {}).get('value', {}) or {}
+        operator = event.get('operator', {})
+        context = event.get('context', {})
+        return self._feedback_event(
+            raw=data,
+            feedback_id=data.get('header', {}).get('event_id', str(uuid.uuid4())),
+            feedback_value=value.get('feedback', ''),
+            user_id=operator.get('open_id') or operator.get('user_id'),
+            chat_id=context.get('open_chat_id'),
+            message_id=context.get('open_message_id'),
+        )
+
+    def _feedback_event(
+        self,
+        raw,
+        feedback_id: str,
+        feedback_value: str,
+        user_id: str | None,
+        chat_id: str | None,
+        message_id: str | None,
+    ) -> platform_events.FeedbackEvent | None:
+        if feedback_value == '有帮助':
+            feedback_type = 1
+        elif feedback_value == '无帮助':
+            feedback_type = 2
+        else:
+            return None
+        return platform_events.FeedbackEvent(
+            feedback_id=feedback_id,
+            feedback_type=feedback_type,
+            feedback_content=feedback_value,
+            user_id=user_id,
+            session_id=f'group_{chat_id}' if chat_id else (f'person_{user_id}' if user_id else None),
+            message_id=message_id,
+            stream_id=self.reply_to_monitoring_msg.get(message_id, (None, 0))[0] if message_id else None,
+            source_platform_object=raw,
+        )
+
+    async def _send_bot_added_welcome(self, chat_id: str, tenant_key: str | None):
+        welcome = self.config.get('bot_added_welcome', '')
+        if not welcome or not chat_id:
+            return
+        content = {'zh_Hans': {'title': '', 'content': [[{'tag': 'md', 'text': welcome}]]}}
+        request = (
+            CreateMessageRequest.builder()
+            .receive_id_type('chat_id')
+            .request_body(
+                CreateMessageRequestBody.builder()
+                .receive_id(chat_id)
+                .content(json.dumps(content, ensure_ascii=False))
+                .msg_type('post')
+                .uuid(str(uuid.uuid4()))
+                .build()
+            )
+            .build()
+        )
+        response: CreateMessageResponse = await self.api_client.im.v1.message.acreate(
+            request, self.request_option(tenant_key)
+        )
+        if not response.success():
+            await self.logger.warning(f'Lark bot_added_welcome failed: {response.code} {response.msg}')
+
+    def _tenant_key_from_source(self, event: platform_events.Event) -> str | None:
+        source = getattr(event, 'source_platform_object', None)
+        header = getattr(source, 'header', None)
+        return getattr(header, 'tenant_key', None)
+
+    def _message_id_from_source(self, event: platform_events.Event) -> str:
+        message_id = getattr(event, 'message_id', None)
+        if message_id:
+            return str(message_id)
+        source = getattr(event, 'source_platform_object', None)
+        source_event = getattr(source, 'event', None)
+        message = getattr(source_event, 'message', None) if source_event else None
+        message_id = getattr(message, 'message_id', None)
+        if message_id:
+            return str(message_id)
+        raise RuntimeError('Lark message source does not contain message_id')

src/langbot/pkg/platform/adapters/lark/api_impl.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import typing
+
+from lark_oapi.api.im.v1 import GetChatRequest, GetMessageRequest
+from lark_oapi.core.model import RequestOption
+
+from langbot.pkg.platform.adapters.lark.event_converter import LarkEventConverter
+from langbot.pkg.platform.adapters.lark.message_converter import LarkMessageConverter
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class LarkAPIMixin:
+    _message_cache: dict[str, platform_events.MessageReceivedEvent]
+    _user_cache: dict[str, platform_entities.User]
+    _group_cache: dict[str, platform_entities.UserGroup]
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> platform_events.MessageReceivedEvent:
+        cached = self._message_cache.get(str(message_id))
+        if cached:
+            return cached
+        request = GetMessageRequest.builder().message_id(str(message_id)).build()
+        response = await self.api_client.im.v1.message.aget(request, self.request_option(None))
+        if not response.success():
+            raise NotSupportedError(f'get_message:{message_id}')
+        items = getattr(response.data, 'items', None) or []
+        if not items:
+            raise NotSupportedError(f'get_message:{message_id}')
+        event_message = LarkEventConverter._build_event_message_from_message_item(items[0])
+        if event_message is None:
+            raise NotSupportedError(f'get_message:{message_id}')
+        message_chain = await LarkMessageConverter.target2yiri(event_message, self.api_client)
+        event = platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name='lark-eba',
+            message_id=str(message_id),
+            message_chain=message_chain,
+            sender=platform_entities.User(id=''),
+            chat_type=platform_entities.ChatType.GROUP if chat_type == 'group' else platform_entities.ChatType.PRIVATE,
+            chat_id=chat_id,
+            group=platform_entities.UserGroup(id=chat_id, name='') if chat_type == 'group' else None,
+            timestamp=0,
+            source_platform_object=items[0],
+        )
+        self._message_cache[str(message_id)] = event
+        return event
+
+    async def get_group_info(self, group_id: typing.Union[int, str]) -> platform_entities.UserGroup:
+        cached = self._group_cache.get(str(group_id))
+        if cached:
+            return cached
+        request = GetChatRequest.builder().chat_id(str(group_id)).build()
+        response = await self.api_client.im.v1.chat.aget(request, self.request_option(None))
+        if not response.success():
+            raise NotSupportedError(f'get_group_info:{group_id}')
+        data = response.data
+        group = platform_entities.UserGroup(
+            id=getattr(data, 'chat_id', group_id),
+            name=getattr(data, 'name', '') or '',
+            description=getattr(data, 'description', None),
+            avatar_url=getattr(data, 'avatar', None),
+            owner_id=getattr(data, 'owner_id', None),
+        )
+        self._group_cache[str(group.id)] = group
+        return group
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        user = self._user_cache.get(str(user_id)) or platform_entities.User(id=user_id)
+        return platform_entities.UserGroupMember(user=user, group_id=group_id, role=platform_entities.MemberRole.MEMBER)
+
+    async def get_user_info(self, user_id: typing.Union[int, str]) -> platform_entities.User:
+        cached = self._user_cache.get(str(user_id))
+        if cached:
+            return cached
+        return platform_entities.User(id=user_id)
+
+    async def get_file_url(self, file_id: str) -> str:
+        if str(file_id).startswith('file://'):
+            return str(file_id)
+        raise NotSupportedError('get_file_url requires a file:// path or platform-specific resource download params')
+
+    def request_option(self, tenant_key: str | None) -> RequestOption:
+        app_access_token = self.get_app_access_token()
+        tenant_access_token = self.get_tenant_access_token(tenant_key)
+        return (
+            RequestOption.builder()
+            .app_ticket(self.app_ticket)
+            .tenant_key(tenant_key)
+            .app_access_token(app_access_token)
+            .tenant_access_token(tenant_access_token)
+            .build()
+        )

src/langbot/pkg/platform/adapters/lark/event_converter.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import time
+import typing
+
+import lark_oapi
+from lark_oapi.api.im.v1 import EventMessage, GetMessageRequest, Message
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot.pkg.platform.adapters.lark.message_converter import LarkMessageConverter
+from langbot.pkg.platform.adapters.lark.types import ADAPTER_NAME
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class LarkEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    _processed_thread_quote_cache: typing.ClassVar[dict[str, float]] = {}
+    _processed_thread_quote_cache_max_size: typing.ClassVar[int] = 4096
+    _processed_thread_quote_cache_ttl_seconds: typing.ClassVar[int] = 86400
+
+    @staticmethod
+    async def yiri2target(event: platform_events.Event):
+        return getattr(event, 'source_platform_object', None)
+
+    @staticmethod
+    async def target2yiri(
+        event: lark_oapi.im.v1.P2ImMessageReceiveV1,
+        api_client: lark_oapi.Client,
+    ) -> platform_events.Event | None:
+        return await LarkEventConverter.message_to_eba(event, api_client)
+
+    @staticmethod
+    async def target2legacy(
+        event: lark_oapi.im.v1.P2ImMessageReceiveV1,
+        api_client: lark_oapi.Client,
+    ) -> platform_events.FriendMessage | platform_events.GroupMessage | None:
+        eba_event = await LarkEventConverter.message_to_eba(event, api_client)
+        if eba_event:
+            return eba_event.to_legacy_event()
+        return None
+
+    @staticmethod
+    async def message_to_eba(
+        event: lark_oapi.im.v1.P2ImMessageReceiveV1,
+        api_client: lark_oapi.Client,
+    ) -> platform_events.MessageReceivedEvent:
+        message = event.event.message
+        message_chain = await LarkMessageConverter.target2yiri(message, api_client)
+        await LarkEventConverter._append_quote_content(message, message_chain, api_client)
+
+        sender = LarkEventConverter.user_from_event(event)
+        chat_type = platform_entities.ChatType.PRIVATE
+        chat_id = LarkEventConverter.sender_id(event)
+        group = None
+        if getattr(message, 'chat_type', '') == 'group':
+            chat_type = platform_entities.ChatType.GROUP
+            chat_id = getattr(message, 'chat_id', '') or chat_id
+            group = platform_entities.UserGroup(id=chat_id, name='')
+
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name=ADAPTER_NAME,
+            message_id=getattr(message, 'message_id', ''),
+            message_chain=message_chain,
+            sender=sender,
+            chat_type=chat_type,
+            chat_id=chat_id,
+            group=group,
+            timestamp=LarkEventConverter._timestamp(getattr(message, 'create_time', None)),
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    def user_from_event(event: lark_oapi.im.v1.P2ImMessageReceiveV1) -> platform_entities.User:
+        sender_id = getattr(getattr(event.event.sender, 'sender_id', None), 'open_id', '') or ''
+        union_id = getattr(getattr(event.event.sender, 'sender_id', None), 'union_id', '') or ''
+        return platform_entities.User(id=sender_id, nickname=union_id)
+
+    @staticmethod
+    def sender_id(event: lark_oapi.im.v1.P2ImMessageReceiveV1) -> str:
+        return getattr(getattr(event.event.sender, 'sender_id', None), 'open_id', '') or ''
+
+    @staticmethod
+    def bot_invited_to_group(
+        raw_event: typing.Any,
+        chat_id: str,
+        operator_id: str | None = None,
+    ) -> platform_events.BotInvitedToGroupEvent:
+        return platform_events.BotInvitedToGroupEvent(
+            type='bot.invited_to_group',
+            adapter_name=ADAPTER_NAME,
+            group=platform_entities.UserGroup(id=chat_id, name=''),
+            inviter=platform_entities.User(id=operator_id) if operator_id else None,
+            timestamp=time.time(),
+            source_platform_object=raw_event,
+        )
+
+    @staticmethod
+    def platform_specific(
+        raw_event: typing.Any, action: str, data: dict | None = None
+    ) -> platform_events.PlatformSpecificEvent:
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            adapter_name=ADAPTER_NAME,
+            action=action,
+            data=data or {},
+            timestamp=time.time(),
+            source_platform_object=raw_event,
+        )
+
+    @classmethod
+    def _prune_processed_thread_quote_cache(cls, now: float | None = None) -> None:
+        if now is None:
+            now = time.time()
+        expire_before = now - cls._processed_thread_quote_cache_ttl_seconds
+        while cls._processed_thread_quote_cache:
+            oldest_key, oldest_ts = next(iter(cls._processed_thread_quote_cache.items()))
+            if oldest_ts >= expire_before:
+                break
+            cls._processed_thread_quote_cache.pop(oldest_key, None)
+        while len(cls._processed_thread_quote_cache) > cls._processed_thread_quote_cache_max_size:
+            cls._processed_thread_quote_cache.pop(next(iter(cls._processed_thread_quote_cache)), None)
+
+    @classmethod
+    def _extract_quote_message_id(cls, message: EventMessage) -> str | None:
+        parent_id = getattr(message, 'parent_id', None)
+        if not parent_id or parent_id == getattr(message, 'message_id', None):
+            return None
+        thread_id = getattr(message, 'thread_id', None)
+        if thread_id:
+            cls._prune_processed_thread_quote_cache()
+            if thread_id in cls._processed_thread_quote_cache:
+                return None
+            cls._processed_thread_quote_cache[thread_id] = time.time()
+        return parent_id
+
+    @staticmethod
+    async def _append_quote_content(
+        message: EventMessage,
+        message_chain: platform_message.MessageChain,
+        api_client: lark_oapi.Client,
+    ) -> None:
+        quote_message_id = LarkEventConverter._extract_quote_message_id(message)
+        if not quote_message_id:
+            return
+        quote_chain = await LarkEventConverter._fetch_quoted_message(quote_message_id, api_client)
+        if not quote_chain:
+            return
+        origin = platform_message.MessageChain(
+            [comp for comp in quote_chain if not isinstance(comp, platform_message.Source)]
+        )
+        message_chain.append(
+            platform_message.Quote(
+                id=quote_message_id,
+                group_id=getattr(message, 'chat_id', None),
+                target_id=getattr(message, 'chat_id', None),
+                origin=origin,
+            )
+        )
+
+    @staticmethod
+    async def _fetch_quoted_message(
+        quote_message_id: str,
+        api_client: lark_oapi.Client,
+    ) -> platform_message.MessageChain | None:
+        request = GetMessageRequest.builder().message_id(quote_message_id).build()
+        response = await api_client.im.v1.message.aget(request)
+        if not response.success() or not getattr(response.data, 'items', None):
+            return None
+        event_message = LarkEventConverter._build_event_message_from_message_item(response.data.items[0])
+        if event_message is None:
+            return None
+        return await LarkMessageConverter.target2yiri(event_message, api_client)
+
+    @staticmethod
+    def _build_event_message_from_message_item(message_item: Message) -> EventMessage | None:
+        body = getattr(message_item, 'body', None)
+        content = getattr(body, 'content', None) if body else None
+        if not content:
+            return None
+        event_data = {
+            'message_id': message_item.message_id,
+            'message_type': message_item.msg_type,
+            'content': content,
+            'create_time': message_item.create_time,
+            'mentions': getattr(message_item, 'mentions', []) or [],
+        }
+        for key in ('parent_id', 'root_id', 'thread_id', 'chat_id'):
+            value = getattr(message_item, key, None)
+            if value:
+                event_data[key] = value
+        return EventMessage(event_data)
+
+    @staticmethod
+    def _timestamp(value: typing.Any) -> float:
+        if isinstance(value, (int, float, str)):
+            try:
+                timestamp = float(value)
+                return timestamp / 1000 if timestamp > 10_000_000_000 else timestamp
+            except ValueError:
+                pass
+        if hasattr(value, 'timestamp'):
+            return float(value.timestamp())
+        return 0.0

src/langbot/pkg/platform/adapters/lark/lark.svg

@@ -0,0 +1 @@
+<?xml version="1.0" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg t="1711946937387" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="5208" xmlns:xlink="http://www.w3.org/1999/xlink" width="200" height="200"><path d="M262.339048 243.809524h326.070857s91.672381 84.504381 91.672381 200.655238l-152.81981 105.569524S445.781333 359.960381 262.339048 243.809524z" fill="#00DAB8" p-id="5209"></path><path d="M853.333333 423.350857s-112.103619-42.276571-183.393523-10.581333c-71.338667 31.695238-101.912381 73.923048-132.486096 105.618286-40.71619 42.22781-112.054857 116.150857-173.202285 73.923047-61.147429-42.276571 244.540952 147.846095 244.540952 147.846095s127.463619-71.631238 173.202286-190.122666C822.759619 444.464762 853.333333 423.350857 853.333333 423.350857z" fill="#0C3AA0" p-id="5210"></path><path d="M170.666667 402.236952v316.757334s112.298667 138.142476 376.978285 63.390476c112.103619-31.695238 203.824762-179.541333 203.824762-179.541333S618.934857 824.612571 170.666667 402.285714z" fill="#296DFF" p-id="5211"></path></svg>

src/langbot/pkg/platform/adapters/lark/manifest.yaml

@@ -0,0 +1,185 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: lark-eba
+  label:
+    en_US: Lark / Feishu (EBA)
+    zh_Hans: 飞书 (EBA)
+    zh_Hant: 飛書 (EBA)
+    ja_JP: Lark (EBA)
+  description:
+    en_US: Lark/Feishu adapter (EBA architecture), supporting self-built/store apps and WebSocket/Webhook modes.
+    zh_Hans: 飞书适配器（EBA 架构版本），支持自建/商店应用和长连接/Webhook 两种通信模式。
+    zh_Hant: 飛書適配器（EBA 架構版本），支援自建/商店應用和長連線/Webhook 兩種通訊模式。
+    ja_JP: Lark アダプター（EBA アーキテクチャ）、カスタム/ストアアプリと WebSocket/Webhook モードをサポートします。
+  icon: lark.svg
+
+spec:
+  categories:
+    - popular
+    - china
+    - global
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/lark
+    en: https://link.langbot.app/en/platforms/lark
+    ja: https://link.langbot.app/ja/platforms/lark
+  config:
+    - name: app_id
+      label:
+        en_US: App ID
+        zh_Hans: 应用ID
+        zh_Hant: 應用ID
+        ja_JP: アプリ ID
+      type: string
+      required: true
+      default: ""
+    - name: app_secret
+      label:
+        en_US: App Secret
+        zh_Hans: 应用密钥
+        zh_Hant: 應用密鑰
+        ja_JP: アプリシークレット
+      type: string
+      required: true
+      default: ""
+    - name: bot_name
+      label:
+        en_US: Bot Name
+        zh_Hans: 机器人名称
+        zh_Hant: 機器人名稱
+        ja_JP: ボット名
+      description:
+        en_US: Must match the Lark bot name so group mentions can be recognized.
+        zh_Hans: 必须与飞书机器人名称一致，否则机器人将无法在群内正常识别 @。
+        zh_Hant: 必須與飛書機器人名稱一致，否則機器人將無法在群組內正常識別 @。
+        ja_JP: グループメンションを認識するには Lark のボット名と一致する必要があります。
+      type: string
+      required: true
+      default: ""
+    - name: enable-webhook
+      label:
+        en_US: Enable Webhook Mode
+        zh_Hans: 启用 Webhook 模式
+        zh_Hant: 啟用 Webhook 模式
+        ja_JP: Webhook モードを有効化
+      description:
+        en_US: Enable request URL callback mode. Disable it to use WebSocket long connection mode.
+        zh_Hans: 启用 Request URL 回调模式。关闭时使用 WebSocket 长连接模式。
+        zh_Hant: 啟用 Request URL 回調模式。關閉時使用 WebSocket 長連線模式。
+        ja_JP: Request URL コールバックモードを有効化します。無効時は WebSocket 長期接続を使用します。
+      type: boolean
+      required: true
+      default: false
+    - name: webhook_url
+      label:
+        en_US: Webhook Callback URL
+        zh_Hans: Webhook 回调地址
+        zh_Hant: Webhook 回調地址
+        ja_JP: Webhook コールバック URL
+      description:
+        en_US: Copy this URL to the Lark app event subscription request URL.
+        zh_Hans: 复制此地址并粘贴到飞书应用事件订阅的 Request URL 中。
+        zh_Hant: 複製此地址並貼到飛書應用事件訂閱的 Request URL 中。
+        ja_JP: この URL を Lark アプリのイベント購読 Request URL に貼り付けてください。
+      type: webhook-url
+      required: false
+      default: ""
+      show_if:
+        field: enable-webhook
+        operator: eq
+        value: true
+    - name: encrypt-key
+      label:
+        en_US: Encrypt Key
+        zh_Hans: 加密密钥
+        zh_Hant: 加密密鑰
+        ja_JP: 暗号化キー
+      type: string
+      required: false
+      default: ""
+      show_if:
+        field: enable-webhook
+        operator: eq
+        value: true
+    - name: enable-stream-reply
+      label:
+        en_US: Enable Stream Reply Mode
+        zh_Hans: 启用飞书流式回复模式
+        zh_Hant: 啟用飛書串流回覆模式
+        ja_JP: ストリーミング返信モードを有効化
+      description:
+        en_US: If enabled, replies are rendered through an updating Lark card.
+        zh_Hans: 如果启用，将使用可更新的飞书卡片进行流式回复。
+        zh_Hant: 如果啟用，將使用可更新的飛書卡片進行串流回覆。
+        ja_JP: 有効にすると、更新可能な Lark カードでストリーミング返信します。
+      type: boolean
+      required: true
+      default: false
+    - name: app_type
+      label:
+        en_US: App Type
+        zh_Hans: 应用类型
+        zh_Hant: 應用類型
+        ja_JP: アプリタイプ
+      type: select
+      options:
+        - name: self
+          label:
+            en_US: Self-built Application
+            zh_Hans: 自建应用
+            zh_Hant: 自建應用
+            ja_JP: カスタムアプリ
+        - name: isv
+          label:
+            en_US: Store Application
+            zh_Hans: 商店应用
+            zh_Hant: 商店應用
+            ja_JP: ストアアプリ
+      required: false
+      default: self
+    - name: bot_added_welcome
+      label:
+        en_US: Bot Welcome Message
+        zh_Hans: 机器人进群欢迎语
+        zh_Hant: 機器人進群歡迎語
+        ja_JP: ボット参加時のウェルカムメッセージ
+      type: text
+      required: false
+      default: ""
+
+  supported_events:
+    - message.received
+    - bot.invited_to_group
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - get_message
+      - get_group_info
+      - get_group_member_info
+      - get_user_info
+      - get_file_url
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: check_tenant_access_token
+      description: { en_US: "Check whether the tenant access token can be obtained", zh_Hans: "检查 tenant access token 是否可获取" }
+    - action: refresh_app_access_token
+      description: { en_US: "Refresh store-app app access token", zh_Hans: "刷新商店应用 app access token" }
+    - action: refresh_tenant_access_token
+      description: { en_US: "Refresh store-app tenant access token", zh_Hans: "刷新商店应用 tenant access token" }
+    - action: get_chat
+      description: { en_US: "Get Lark chat metadata", zh_Hans: "获取飞书会话信息" }
+    - action: get_message
+      description: { en_US: "Get a Lark message", zh_Hans: "获取飞书消息" }
+    - action: get_message_resource
+      description: { en_US: "Download message image/file resource", zh_Hans: "下载消息图片/文件资源" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: LarkAdapter

src/langbot/pkg/platform/adapters/lark/message_converter.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+
+import base64
+import datetime
+import json
+import mimetypes
+import os
+import re
+import tempfile
+import traceback
+
+import lark_oapi
+from lark_oapi.api.im.v1 import (
+    CreateFileRequest,
+    CreateFileRequestBody,
+    CreateImageRequest,
+    CreateImageRequestBody,
+    EventMessage,
+    GetMessageResourceRequest,
+    GetMessageResourceResponse,
+)
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot.pkg.utils import httpclient
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class LarkMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    async def upload_image_to_lark(msg: platform_message.Image, api_client: lark_oapi.Client) -> str | None:
+        image_bytes = await LarkMessageConverter._get_component_bytes(msg)
+        if image_bytes is None:
+            return None
+
+        temp_file_path = ''
+        try:
+            with tempfile.NamedTemporaryFile(delete=False) as temp_file:
+                temp_file.write(image_bytes)
+                temp_file.flush()
+                temp_file_path = temp_file.name
+
+            request = (
+                CreateImageRequest.builder()
+                .request_body(
+                    CreateImageRequestBody.builder().image_type('message').image(open(temp_file_path, 'rb')).build()
+                )
+                .build()
+            )
+            response = await api_client.im.v1.image.acreate(request)
+            if not response.success():
+                return None
+            return response.data.image_key
+        except Exception:
+            traceback.print_exc()
+            return None
+        finally:
+            if temp_file_path:
+                try:
+                    os.unlink(temp_file_path)
+                except FileNotFoundError:
+                    pass
+
+    @staticmethod
+    async def upload_file_to_lark(
+        file_bytes: bytes,
+        api_client: lark_oapi.Client,
+        file_type: str,
+        file_name: str = 'file',
+        duration: int | None = None,
+    ) -> str | None:
+        temp_file_path = ''
+        try:
+            with tempfile.NamedTemporaryFile(delete=False) as temp_file:
+                temp_file.write(file_bytes)
+                temp_file.flush()
+                temp_file_path = temp_file.name
+
+            body_builder = (
+                CreateFileRequestBody.builder()
+                .file_type(file_type)
+                .file_name(file_name)
+                .file(open(temp_file_path, 'rb'))
+            )
+            if duration is not None:
+                body_builder = body_builder.duration(duration)
+
+            request = CreateFileRequest.builder().request_body(body_builder.build()).build()
+            response = await api_client.im.v1.file.acreate(request)
+            if not response.success():
+                return None
+            return response.data.file_key
+        except Exception:
+            traceback.print_exc()
+            return None
+        finally:
+            if temp_file_path:
+                try:
+                    os.unlink(temp_file_path)
+                except FileNotFoundError:
+                    pass
+
+    @staticmethod
+    async def _get_component_bytes(
+        msg: platform_message.Image | platform_message.Voice | platform_message.File,
+    ) -> bytes | None:
+        if getattr(msg, 'base64', None):
+            try:
+                base64_data = msg.base64
+                if ',' in base64_data:
+                    base64_data = base64_data.split(',', 1)[1]
+                return base64.b64decode(base64_data)
+            except Exception:
+                return None
+        if getattr(msg, 'url', None):
+            try:
+                if str(msg.url).startswith('file://'):
+                    with open(str(msg.url)[7:], 'rb') as f:
+                        return f.read()
+                session = httpclient.get_session()
+                async with session.get(msg.url) as response:
+                    if response.status == 200:
+                        return await response.read()
+            except Exception:
+                return None
+        if getattr(msg, 'path', None):
+            try:
+                with open(msg.path, 'rb') as f:
+                    return f.read()
+            except Exception:
+                return None
+        return None
+
+    @staticmethod
+    def _lark_file_type(file_name: str) -> str:
+        ext = os.path.splitext(file_name)[1].lstrip('.').lower()
+        return {
+            'opus': 'opus',
+            'mp4': 'mp4',
+            'pdf': 'pdf',
+            'doc': 'doc',
+            'docx': 'doc',
+            'xls': 'xls',
+            'xlsx': 'xls',
+            'ppt': 'ppt',
+            'pptx': 'ppt',
+        }.get(ext, 'stream')
+
+    @staticmethod
+    async def yiri2target(
+        message_chain: platform_message.MessageChain,
+        api_client: lark_oapi.Client,
+    ) -> tuple[list[list[dict]], list[dict]]:
+        message_elements: list[list[dict]] = []
+        media_items: list[dict] = []
+        pending_paragraph: list[dict] = []
+        markdown_image_pattern = re.compile(r'!\[([^\]]*)\]\(([^)]+)\)')
+
+        async def process_text_with_images(text: str) -> tuple[str, list[str]]:
+            matches = list(markdown_image_pattern.finditer(text))
+            if not matches:
+                return text, []
+            cleaned_text = text
+            extracted_urls: list[str] = []
+            for match in reversed(matches):
+                extracted_urls.insert(0, match.group(2))
+                cleaned_text = cleaned_text[: match.start()] + cleaned_text[match.end() :]
+            cleaned_text = re.sub(r'\n{3,}', '\n\n', cleaned_text).strip()
+            return cleaned_text, extracted_urls
+
+        for msg in message_chain:
+            if isinstance(msg, platform_message.Source):
+                continue
+            if isinstance(msg, platform_message.Plain):
+                cleaned_text, extracted_urls = await process_text_with_images(msg.text)
+                if cleaned_text:
+                    segments = re.split(r'\n\s*\n', cleaned_text)
+                    for i, segment in enumerate(segments):
+                        segment = segment.strip()
+                        if not segment:
+                            continue
+                        if i > 0 and pending_paragraph:
+                            message_elements.append(pending_paragraph)
+                            pending_paragraph = []
+                        pending_paragraph.append({'tag': 'md', 'text': segment})
+                for url in extracted_urls:
+                    image_key = await LarkMessageConverter.upload_image_to_lark(
+                        platform_message.Image(url=url), api_client
+                    )
+                    if image_key:
+                        media_items.append({'msg_type': 'image', 'content': {'image_key': image_key}})
+            elif isinstance(msg, platform_message.At):
+                pending_paragraph.append({'tag': 'at', 'user_id': str(msg.target), 'style': []})
+            elif isinstance(msg, platform_message.AtAll):
+                pending_paragraph.append({'tag': 'at', 'user_id': 'all', 'style': []})
+            elif isinstance(msg, platform_message.Image):
+                image_key = await LarkMessageConverter.upload_image_to_lark(msg, api_client)
+                if image_key:
+                    media_items.append({'msg_type': 'image', 'content': {'image_key': image_key}})
+            elif isinstance(msg, platform_message.Voice):
+                data = await LarkMessageConverter._get_component_bytes(msg)
+                if data:
+                    duration = int(msg.length * 1000) if msg.length else None
+                    file_key = await LarkMessageConverter.upload_file_to_lark(
+                        data, api_client, file_type='opus', file_name='voice.opus', duration=duration
+                    )
+                    if file_key:
+                        media_items.append({'msg_type': 'audio', 'content': {'file_key': file_key}})
+            elif isinstance(msg, platform_message.File):
+                data = await LarkMessageConverter._get_component_bytes(msg)
+                if data:
+                    file_name = msg.name or 'file'
+                    file_key = await LarkMessageConverter.upload_file_to_lark(
+                        data,
+                        api_client,
+                        file_type=LarkMessageConverter._lark_file_type(file_name),
+                        file_name=file_name,
+                    )
+                    if file_key:
+                        media_items.append({'msg_type': 'file', 'content': {'file_key': file_key}})
+            elif isinstance(msg, platform_message.Quote):
+                if msg.id:
+                    pending_paragraph.append({'tag': 'md', 'text': f'[引用消息 {msg.id}] '})
+                if msg.origin:
+                    sub_elements, sub_media = await LarkMessageConverter.yiri2target(msg.origin, api_client)
+                    message_elements.extend(sub_elements)
+                    media_items.extend(sub_media)
+            elif isinstance(msg, platform_message.Forward):
+                for node in msg.node_list:
+                    if node.sender_name or node.sender_id:
+                        pending_paragraph.append({'tag': 'md', 'text': f'\n[{node.sender_name or node.sender_id}] '})
+                    sub_elements, sub_media = await LarkMessageConverter.yiri2target(node.message_chain, api_client)
+                    message_elements.extend(sub_elements)
+                    media_items.extend(sub_media)
+
+        if pending_paragraph:
+            message_elements.append(pending_paragraph)
+
+        return message_elements, media_items
+
+    @staticmethod
+    async def target2yiri(
+        message: EventMessage,
+        api_client: lark_oapi.Client,
+    ) -> platform_message.MessageChain:
+        message_content = json.loads(message.content or '{}')
+        create_time = LarkMessageConverter._message_time(message)
+        components: list[platform_message.MessageComponent] = [
+            platform_message.Source(id=message.message_id, time=create_time)
+        ]
+
+        normalized = LarkMessageConverter._normalize_inbound_content(message, message_content)
+        for ele in normalized:
+            tag = ele.get('tag')
+            if tag in {'text', 'md'}:
+                text = ele.get('text') or ''
+                if text:
+                    components.append(platform_message.Plain(text=text))
+            elif tag == 'at':
+                user_id = ele.get('user_id') or ele.get('user_name') or ''
+                display = ele.get('user_name') or user_id
+                if user_id == 'all':
+                    components.append(platform_message.AtAll())
+                else:
+                    components.append(platform_message.At(target=user_id, display=display))
+            elif tag == 'img':
+                image_key = ele.get('image_key') or ''
+                image = await LarkMessageConverter._download_resource(
+                    api_client, message.message_id, image_key, 'image'
+                )
+                components.append(platform_message.Image(image_id=image_key, **image))
+            elif tag == 'audio':
+                file_key = ele.get('file_key') or ''
+                audio = await LarkMessageConverter._download_resource(api_client, message.message_id, file_key, 'file')
+                components.append(
+                    platform_message.Voice(
+                        voice_id=file_key,
+                        length=(ele.get('duration', 0) // 1000) if ele.get('duration') else None,
+                        **audio,
+                    )
+                )
+            elif tag == 'file':
+                file_key = ele.get('file_key') or ''
+                file_name = ele.get('file_name') or 'file'
+                file_data = await LarkMessageConverter._download_resource(
+                    api_client, message.message_id, file_key, 'file'
+                )
+                components.append(
+                    platform_message.File(
+                        id=file_key,
+                        name=file_name,
+                        size=file_data.pop('size', 0),
+                        **file_data,
+                    )
+                )
+
+        return platform_message.MessageChain(components)
+
+    @staticmethod
+    def _normalize_inbound_content(message: EventMessage, content: dict) -> list[dict]:
+        if message.message_type == 'text':
+            text = content.get('text', '')
+            return LarkMessageConverter._split_text_mentions(text, getattr(message, 'mentions', []) or [])
+        if message.message_type == 'post':
+            post_content = content.get('content', [])
+            flattened: list[dict] = []
+            for ele in post_content:
+                if isinstance(ele, dict):
+                    flattened.append(ele)
+                elif isinstance(ele, list):
+                    flattened.extend(item for item in ele if isinstance(item, dict))
+            return flattened
+        if message.message_type == 'image':
+            return [{'tag': 'img', 'image_key': content.get('image_key', ''), 'style': []}]
+        if message.message_type == 'file':
+            return [
+                {
+                    'tag': 'file',
+                    'file_key': content.get('file_key', ''),
+                    'file_name': content.get('file_name', 'file'),
+                }
+            ]
+        if message.message_type == 'audio':
+            return [
+                {
+                    'tag': 'audio',
+                    'file_key': content.get('file_key', ''),
+                    'duration': content.get('duration', 0),
+                }
+            ]
+        return [{'tag': 'text', 'text': json.dumps(content, ensure_ascii=False), 'style': []}]
+
+    @staticmethod
+    def _split_text_mentions(text: str, mentions: list) -> list[dict]:
+        if not text:
+            return []
+        mention_by_key = {getattr(m, 'key', ''): m for m in mentions}
+        pattern = re.compile(r'@_user_\d+')
+        result: list[dict] = []
+        pos = 0
+        for match in pattern.finditer(text):
+            if match.start() > pos:
+                result.append({'tag': 'text', 'text': text[pos : match.start()], 'style': []})
+            mention = mention_by_key.get(match.group(0))
+            if mention:
+                result.append(
+                    {
+                        'tag': 'at',
+                        'user_id': getattr(mention, 'id', None)
+                        or getattr(mention, 'open_id', None)
+                        or getattr(mention, 'user_id', None)
+                        or getattr(mention, 'key', match.group(0)),
+                        'user_name': getattr(mention, 'name', ''),
+                        'style': [],
+                    }
+                )
+            else:
+                result.append({'tag': 'text', 'text': match.group(0), 'style': []})
+            pos = match.end()
+        if pos < len(text):
+            result.append({'tag': 'text', 'text': text[pos:], 'style': []})
+        return result
+
+    @staticmethod
+    async def _download_resource(
+        api_client: lark_oapi.Client,
+        message_id: str,
+        file_key: str,
+        resource_type: str,
+    ) -> dict:
+        if not file_key:
+            return {}
+        request = (
+            GetMessageResourceRequest.builder().message_id(message_id).file_key(file_key).type(resource_type).build()
+        )
+        response: GetMessageResourceResponse = await api_client.im.v1.message_resource.aget(request)
+        if not response.success():
+            return {}
+        data = response.file.read()
+        content_type = response.raw.headers.get('content-type', 'application/octet-stream')
+        base64_data = base64.b64encode(data).decode()
+        ext = mimetypes.guess_extension(content_type.split(';')[0].strip()) or '.bin'
+        temp_path = os.path.join(tempfile.gettempdir(), f'lark_{file_key}{ext}')
+        with open(temp_path, 'wb') as f:
+            f.write(data)
+        return {
+            'url': f'file://{temp_path}',
+            'path': temp_path,
+            'base64': f'data:{content_type};base64,{base64_data}',
+            'size': len(data),
+        }
+
+    @staticmethod
+    def _message_time(message: EventMessage) -> datetime.datetime:
+        value = getattr(message, 'create_time', None)
+        if isinstance(value, datetime.datetime):
+            return value
+        if isinstance(value, (int, float, str)):
+            try:
+                timestamp = float(value)
+                if timestamp > 10_000_000_000:
+                    timestamp = timestamp / 1000
+                return datetime.datetime.fromtimestamp(timestamp)
+            except ValueError:
+                pass
+        return datetime.datetime.now()

src/langbot/pkg/platform/adapters/lark/platform_api.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+
+from lark_oapi.api.im.v1 import GetChatRequest, GetMessageRequest, GetMessageResourceRequest
+
+
+async def check_tenant_access_token(adapter, params: dict) -> dict:
+    tenant_key = params.get('tenant_key') or getattr(adapter, 'lark_tenant_key', None)
+    token = adapter.get_tenant_access_token(tenant_key)
+    return {'ok': bool(token) or adapter.config.get('app_type', 'self') != 'isv'}
+
+
+async def refresh_app_access_token(adapter, params: dict) -> dict:
+    adapter.app_access_token = None
+    adapter.app_access_token_expire_at = None
+    token = adapter.get_app_access_token()
+    return {'ok': bool(token) or adapter.config.get('app_type', 'self') != 'isv'}
+
+
+async def refresh_tenant_access_token(adapter, params: dict) -> dict:
+    tenant_key = params.get('tenant_key') or getattr(adapter, 'lark_tenant_key', None)
+    if tenant_key:
+        adapter.tenant_access_tokens.pop(tenant_key, None)
+    token = adapter.get_tenant_access_token(tenant_key)
+    return {'ok': bool(token) or adapter.config.get('app_type', 'self') != 'isv'}
+
+
+async def get_chat(adapter, params: dict) -> dict:
+    request = GetChatRequest.builder().chat_id(params['chat_id']).build()
+    response = await adapter.api_client.im.v1.chat.aget(request, adapter.request_option(params.get('tenant_key')))
+    return _response_to_dict(response)
+
+
+async def get_message(adapter, params: dict) -> dict:
+    request = GetMessageRequest.builder().message_id(params['message_id']).build()
+    response = await adapter.api_client.im.v1.message.aget(request, adapter.request_option(params.get('tenant_key')))
+    return _response_to_dict(response)
+
+
+async def get_message_resource(adapter, params: dict) -> dict:
+    request = (
+        GetMessageResourceRequest.builder()
+        .message_id(params['message_id'])
+        .file_key(params['file_key'])
+        .type(params.get('type', 'file'))
+        .build()
+    )
+    response = await adapter.api_client.im.v1.message_resource.aget(
+        request, adapter.request_option(params.get('tenant_key'))
+    )
+    if not response.success():
+        return _response_to_dict(response)
+    content_type = response.raw.headers.get('content-type', 'application/octet-stream')
+    data = response.file.read()
+    return {'ok': True, 'content_type': content_type, 'size': len(data)}
+
+
+def _response_to_dict(response) -> dict:
+    if not response.success():
+        return {'ok': False, 'code': response.code, 'msg': response.msg, 'log_id': response.get_log_id()}
+    data = getattr(response, 'data', None)
+    if hasattr(data, 'to_json'):
+        data = data.to_json()
+    return {'ok': True, 'data': _jsonable(data)}
+
+
+def _jsonable(value):
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, bytes):
+        return {'bytes': len(value)}
+    if isinstance(value, (list, tuple, set)):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, str):
+        return value
+    try:
+        return json.loads(value)
+    except Exception:
+        pass
+    raw = getattr(value, '__dict__', None)
+    if raw:
+        return {key: _jsonable(item) for key, item in raw.items() if not key.startswith('_')}
+    return str(value)
+
+
+PLATFORM_API_MAP = {
+    'check_tenant_access_token': check_tenant_access_token,
+    'refresh_app_access_token': refresh_app_access_token,
+    'refresh_tenant_access_token': refresh_tenant_access_token,
+    'get_chat': get_chat,
+    'get_message': get_message,
+    'get_message_resource': get_message_resource,
+}

src/langbot/pkg/platform/adapters/lark/types.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+ADAPTER_NAME = 'lark-eba'

src/langbot/pkg/platform/adapters/officialaccount/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from langbot.pkg.platform.adapters.officialaccount.adapter import OfficialAccountAdapter
+
+__all__ = ['OfficialAccountAdapter']

src/langbot/pkg/platform/adapters/officialaccount/adapter.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import asyncio
+import traceback
+import typing
+
+import pydantic
+
+from langbot.libs.official_account_api.api import OAClient, OAClientForLongerResponse
+from langbot.libs.official_account_api.oaevent import OAEvent
+from langbot.pkg.platform.adapters.officialaccount.api_impl import OfficialAccountAPIMixin
+from langbot.pkg.platform.adapters.officialaccount.event_converter import OfficialAccountEventConverter
+from langbot.pkg.platform.adapters.officialaccount.errors import NotSupportedError
+from langbot.pkg.platform.adapters.officialaccount.message_converter import OfficialAccountMessageConverter
+from langbot.pkg.platform.adapters.officialaccount.platform_api import PLATFORM_API_MAP
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class OfficialAccountAdapter(OfficialAccountAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    bot: typing.Any = pydantic.Field(exclude=True)
+
+    message_converter: OfficialAccountMessageConverter = OfficialAccountMessageConverter()
+    event_converter: OfficialAccountEventConverter = OfficialAccountEventConverter()
+
+    config: dict
+    bot_uuid: str | None = None
+    listeners: dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = {}
+    _message_cache: dict[str, platform_events.MessageReceivedEvent] = {}
+    _user_cache: dict[str, platform_entities.User] = {}
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        required_keys = ['token', 'EncodingAESKey', 'AppSecret', 'AppID', 'Mode']
+        missing_keys = [key for key in required_keys if not config.get(key)]
+        if missing_keys:
+            raise Exception(f'OfficialAccount EBA adapter missing config: {missing_keys}')
+
+        mode = config['Mode']
+        common_kwargs = {
+            'token': config['token'],
+            'EncodingAESKey': config['EncodingAESKey'],
+            'Appsecret': config['AppSecret'],
+            'AppID': config['AppID'],
+            'logger': logger,
+            'unified_mode': True,
+            'api_base_url': config.get('api_base_url', 'https://api.weixin.qq.com'),
+        }
+        if mode == 'drop':
+            bot = OAClient(**common_kwargs)
+        elif mode == 'passive':
+            bot = OAClientForLongerResponse(
+                **common_kwargs,
+                LoadingMessage=config.get('LoadingMessage', ''),
+            )
+        else:
+            raise KeyError('OfficialAccount Mode must be "drop" or "passive"')
+
+        super().__init__(
+            config=config,
+            logger=logger,
+            bot=bot,
+            bot_account_id=config.get('AppID', ''),
+            bot_uuid=None,
+            listeners={},
+            _message_cache={},
+            _user_cache={},
+        )
+        self._register_native_handlers()
+
+    def set_bot_uuid(self, bot_uuid: str):
+        self.bot_uuid = bot_uuid
+
+    def get_supported_events(self) -> list[str]:
+        return [
+            'message.received',
+            'platform.specific',
+        ]
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'reply_message',
+            'get_message',
+            'get_user_info',
+            'get_friend_list',
+            'call_platform_api',
+        ]
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ) -> platform_events.MessageResult:
+        raise NotSupportedError('send_message:official_account_requires_inbound_webhook_reply')
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ) -> platform_events.MessageResult:
+        source = await OfficialAccountEventConverter.yiri2target(message_source)
+        if not isinstance(source, OAEvent):
+            raise ValueError('OfficialAccount reply_message requires an OAEvent source object')
+        content = await OfficialAccountMessageConverter.yiri2target(message)
+        if self.config.get('Mode') == 'passive':
+            await self.bot.set_message(source.user_id, source.message_id, content)
+        else:
+            await self.bot.set_message(source.message_id, content)
+        return platform_events.MessageResult(message_id=source.message_id, raw={'queued': True})
+
+    async def call_platform_api(self, action: str, params: dict = {}) -> dict:
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            raise NotSupportedError(f'call_platform_api:{action}')
+        params = dict(params or {})
+        params.setdefault('mode', self.config.get('Mode'))
+        return await handler(self.bot, params)
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        registered = self.listeners.get(event_type)
+        if registered is callback:
+            self.listeners.pop(event_type, None)
+
+    async def handle_unified_webhook(self, bot_uuid: str, path: str, request):
+        return await self.bot.handle_unified_webhook(request)
+
+    async def run_async(self):
+        async def keep_alive():
+            while True:
+                await asyncio.sleep(1)
+
+        await self.logger.info('OfficialAccount EBA adapter running in unified webhook mode')
+        await keep_alive()
+
+    async def kill(self) -> bool:
+        return True
+
+    async def is_muted(self, group_id: int | None = None) -> bool:
+        return False
+
+    def _register_native_handlers(self):
+        for msg_type in ('text', 'image', 'voice', 'event'):
+            self.bot.on_message(msg_type)(self._handle_native_event)
+
+    async def _handle_native_event(self, event: OAEvent):
+        self.bot_account_id = event.receiver_id or self.bot_account_id
+        try:
+            if platform_events.FriendMessage in self.listeners:
+                legacy_event = await self.event_converter.target2legacy(event)
+                if legacy_event and platform_events.FriendMessage in self.listeners:
+                    await self.listeners[platform_events.FriendMessage](legacy_event, self)
+
+            eba_event = await self.event_converter.target2yiri(event)
+            if eba_event:
+                self._cache_event(eba_event)
+                await self._dispatch_eba_event(eba_event)
+        except Exception:
+            await self.logger.error(f'Error in officialaccount native event: {traceback.format_exc()}')
+
+    async def _dispatch_eba_event(self, event: platform_events.EBAEvent):
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return
+
+    def _cache_event(self, event: platform_events.Event):
+        if isinstance(event, platform_events.MessageReceivedEvent):
+            self._message_cache[str(event.message_id)] = event
+            self._user_cache[str(event.sender.id)] = event.sender

src/langbot/pkg/platform/adapters/officialaccount/api_impl.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import typing
+
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot.pkg.platform.adapters.officialaccount.errors import NotSupportedError
+
+
+class OfficialAccountAPIMixin:
+    _message_cache: dict[str, platform_events.MessageReceivedEvent]
+    _user_cache: dict[str, platform_entities.User]
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> platform_events.MessageReceivedEvent:
+        event = self._message_cache.get(str(message_id))
+        if event is None:
+            raise NotSupportedError('get_message:message_not_cached')
+        return event
+
+    async def get_user_info(self, user_id: typing.Union[int, str]) -> platform_entities.User:
+        user = self._user_cache.get(str(user_id))
+        if user is None:
+            raise NotSupportedError('get_user_info:not_cached')
+        return user
+
+    async def get_friend_list(self) -> list[platform_entities.User]:
+        return list(self._user_cache.values())
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: platform_message.MessageChain,
+    ) -> None:
+        raise NotSupportedError('edit_message')
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        raise NotSupportedError('delete_message')
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> platform_events.MessageResult:
+        raise NotSupportedError('forward_message')
+
+    async def upload_file(self, file_data: bytes, filename: str) -> str:
+        raise NotSupportedError('upload_file')
+
+    async def get_file_url(self, file_id: str) -> str:
+        raise NotSupportedError('get_file_url')
+
+    async def get_group_info(self, group_id: typing.Union[int, str]) -> platform_entities.UserGroup:
+        raise NotSupportedError('get_group_info')
+
+    async def get_group_list(self) -> list[platform_entities.UserGroup]:
+        raise NotSupportedError('get_group_list')
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        raise NotSupportedError('get_group_member_list')
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        raise NotSupportedError('get_group_member_info')

src/langbot/pkg/platform/adapters/officialaccount/errors.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+try:
+    from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+except ModuleNotFoundError:
+
+    class NotSupportedError(Exception):
+        def __init__(self, api_name: str, *args):
+            super().__init__(f"API '{api_name}' is not supported by this adapter", *args)
+            self.api_name = api_name

src/langbot/pkg/platform/adapters/officialaccount/event_converter.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import time
+import typing
+
+from langbot.libs.official_account_api.oaevent import OAEvent
+from langbot.pkg.platform.adapters.officialaccount.message_converter import OfficialAccountMessageConverter
+from langbot.pkg.platform.adapters.officialaccount.types import ADAPTER_NAME
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+
+
+class OfficialAccountEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    @staticmethod
+    async def yiri2target(event: platform_events.Event) -> typing.Any:
+        return getattr(event, 'source_platform_object', None)
+
+    async def target2legacy(self, event: OAEvent) -> platform_events.FriendMessage | None:
+        eba_event = await self.target2yiri(event)
+        if not isinstance(eba_event, platform_events.MessageReceivedEvent):
+            return None
+        return platform_events.FriendMessage(
+            sender=platform_entities.Friend(
+                id=eba_event.sender.id,
+                nickname=eba_event.sender.nickname,
+                remark='',
+            ),
+            message_chain=eba_event.message_chain,
+            time=eba_event.timestamp,
+            source_platform_object=event,
+        )
+
+    async def target2yiri(self, event: OAEvent) -> platform_events.Event | None:
+        if event.type in {'text', 'image', 'voice'}:
+            return await self.message_to_eba(event)
+        return self.platform_specific(event, f'officialaccount.{event.detail_type or event.type or "unknown"}')
+
+    async def message_to_eba(self, event: OAEvent) -> platform_events.MessageReceivedEvent:
+        sender_id = event.user_id or ''
+        timestamp = float(event.timestamp or time.time())
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name=ADAPTER_NAME,
+            message_id=event.message_id or f'{sender_id}:{int(timestamp)}',
+            message_chain=await OfficialAccountMessageConverter.target2yiri(event),
+            sender=platform_entities.User(
+                id=sender_id,
+                nickname=sender_id,
+            ),
+            chat_type=platform_entities.ChatType.PRIVATE,
+            chat_id=sender_id,
+            timestamp=timestamp,
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    def platform_specific(event: OAEvent, action: str) -> platform_events.PlatformSpecificEvent:
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            adapter_name=ADAPTER_NAME,
+            action=action,
+            data=dict(event),
+            timestamp=float(event.timestamp or time.time()),
+            source_platform_object=event,
+        )

src/langbot/pkg/platform/adapters/officialaccount/manifest.yaml

@@ -0,0 +1,123 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: officialaccount-eba
+  label:
+    en_US: Official Account (EBA)
+    zh_Hans: 微信公众号 (EBA)
+    zh_Hant: 微信公眾號 (EBA)
+  description:
+    en_US: WeChat Official Account adapter with Event-Based Agents support
+    zh_Hans: 微信公众号适配器（EBA 架构版本），通过统一 Webhook 接收公众号消息
+    zh_Hant: 微信公眾號適配器（EBA 架構版本），透過統一 Webhook 接收公眾號訊息
+  icon: officialaccount.png
+
+spec:
+  categories:
+    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/officialaccount
+    en: https://link.langbot.app/en/platforms/officialaccount
+    ja: https://link.langbot.app/ja/platforms/officialaccount
+  config:
+    - name: webhook_url
+      label:
+        en_US: Webhook Callback URL
+        zh_Hans: Webhook 回调地址
+        zh_Hant: Webhook 回調地址
+      description:
+        en_US: Copy this URL and paste it into your Official Account webhook configuration.
+        zh_Hans: 复制此地址并粘贴到微信公众号的 Webhook 配置中。
+        zh_Hant: 複製此地址並貼到微信公眾號的 Webhook 設定中。
+      type: webhook-url
+      required: false
+      default: ""
+    - name: token
+      label:
+        en_US: Token
+        zh_Hans: 令牌
+        zh_Hant: 令牌
+      type: string
+      required: true
+      default: ""
+    - name: EncodingAESKey
+      label:
+        en_US: EncodingAESKey
+        zh_Hans: 消息加解密密钥
+        zh_Hant: 訊息加解密密鑰
+      type: string
+      required: true
+      default: ""
+    - name: AppID
+      label:
+        en_US: App ID
+        zh_Hans: 应用 ID
+        zh_Hant: 應用 ID
+      type: string
+      required: true
+      default: ""
+    - name: AppSecret
+      label:
+        en_US: App Secret
+        zh_Hans: 应用密钥
+        zh_Hant: 應用密鑰
+      type: string
+      required: true
+      default: ""
+    - name: Mode
+      label:
+        en_US: Mode
+        zh_Hans: 接入模式
+        zh_Hant: 接入模式
+      description:
+        en_US: "drop replies within the current callback; passive returns a loading message first and queues the real reply for the user's next message."
+        zh_Hans: "drop 会在当前回调内等待回复；passive 会先返回加载提示，并将真实回复排队到用户下一条消息。"
+        zh_Hant: "drop 會在目前回調內等待回覆；passive 會先回傳載入提示，並將真實回覆排隊到使用者下一則訊息。"
+      type: string
+      required: true
+      default: "drop"
+    - name: LoadingMessage
+      label:
+        en_US: Loading Message
+        zh_Hans: 加载消息
+        zh_Hant: 載入訊息
+      type: string
+      required: false
+      default: "AI正在思考中，请发送任意内容获取回复。"
+    - name: api_base_url
+      label:
+        en_US: API Base URL
+        zh_Hans: API 基础 URL
+        zh_Hant: API 基礎 URL
+      description:
+        en_US: Optional Official Account API base URL, useful when routing through a reverse proxy.
+        zh_Hans: 可选，若通过反向代理访问微信公众号 API，可修改此项。
+        zh_Hant: 可選，若透過反向代理存取微信公眾號 API，可修改此項。
+      type: string
+      required: false
+      default: "https://api.weixin.qq.com"
+
+  supported_events:
+    - message.received
+    - platform.specific
+
+  supported_apis:
+    required:
+      - reply_message
+    optional:
+      - get_message
+      - get_user_info
+      - get_friend_list
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: get_mode
+      description: { en_US: "Return the configured Official Account reply mode", zh_Hans: "返回当前微信公众号回复模式" }
+    - action: get_cached_response_status
+      description: { en_US: "Inspect cached passive/drop reply state for diagnostics", zh_Hans: "查看被动回复缓存状态，用于诊断" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: OfficialAccountAdapter

src/langbot/pkg/platform/adapters/officialaccount/message_converter.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import datetime
+
+from langbot.libs.official_account_api.oaevent import OAEvent
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class OfficialAccountMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    async def yiri2target(message_chain: platform_message.MessageChain) -> str:
+        content_parts: list[str] = []
+        for component in message_chain:
+            if isinstance(component, platform_message.Source):
+                continue
+            if isinstance(component, platform_message.Plain):
+                content_parts.append(component.text)
+            elif isinstance(component, platform_message.At):
+                content_parts.append(f'@{component.display or component.target}')
+            elif isinstance(component, platform_message.AtAll):
+                content_parts.append('@all')
+            elif isinstance(component, platform_message.Image):
+                content_parts.append('[Image]')
+            elif isinstance(component, platform_message.Voice):
+                content_parts.append('[Voice]')
+            elif isinstance(component, platform_message.File):
+                content_parts.append(f'[File: {component.name or component.id or component.url or "file"}]')
+            elif isinstance(component, platform_message.Quote):
+                if component.id is not None:
+                    content_parts.append(f'[Quote {component.id}]')
+                if component.origin:
+                    content_parts.append(await OfficialAccountMessageConverter.yiri2target(component.origin))
+            elif isinstance(component, platform_message.Forward):
+                for node in component.node_list:
+                    if node.message_chain:
+                        content_parts.append(await OfficialAccountMessageConverter.yiri2target(node.message_chain))
+            else:
+                content_parts.append(str(component))
+        return '\n'.join(part for part in content_parts if part)
+
+    @staticmethod
+    async def target2yiri(event: OAEvent) -> platform_message.MessageChain:
+        timestamp = event.timestamp or int(datetime.datetime.now().timestamp())
+        components: list[platform_message.MessageComponent] = [
+            platform_message.Source(
+                id=event.message_id or f'{event.user_id}:{timestamp}',
+                time=datetime.datetime.fromtimestamp(timestamp),
+            )
+        ]
+
+        if event.type == 'text' and event.message:
+            components.append(platform_message.Plain(text=event.message))
+        elif event.type == 'image':
+            image_kwargs = {}
+            if event.picurl:
+                image_kwargs['url'] = event.picurl
+            if event.media_id:
+                image_kwargs['image_id'] = event.media_id
+            if image_kwargs:
+                components.append(platform_message.Image(**image_kwargs))
+        elif event.type == 'voice':
+            if event.media_id:
+                components.append(platform_message.Voice(voice_id=event.media_id))
+            else:
+                components.append(platform_message.Unknown(text='[officialaccount voice message without media id]'))
+        elif event.type == 'event':
+            components.append(platform_message.Unknown(text=f'[officialaccount event: {event.detail_type or "unknown"}]'))
+        else:
+            components.append(platform_message.Unknown(text=f'[unsupported officialaccount msgtype: {event.type or "unknown"}]'))
+
+        return platform_message.MessageChain(components)

src/langbot/pkg/platform/adapters/officialaccount/platform_api.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import typing
+
+
+async def get_mode(bot, params: dict) -> dict:
+    return {
+        'mode': params.get('mode') or ('passive' if hasattr(bot, 'msg_queue') else 'drop'),
+        'longer_response': hasattr(bot, 'msg_queue'),
+    }
+
+
+async def get_cached_response_status(bot, params: dict) -> dict:
+    message_id = params.get('message_id') or params.get('msg_id')
+    user_id = params.get('user_id') or params.get('from_user')
+    if hasattr(bot, 'generated_content'):
+        return {'pending': str(message_id) in {str(key) for key in bot.generated_content}}
+    if hasattr(bot, 'msg_queue'):
+        queue = bot.msg_queue.get(str(user_id), []) if user_id is not None else []
+        return {'queued': len(queue)}
+    return {'pending': False}
+
+
+PLATFORM_API_MAP: dict[str, typing.Callable[[typing.Any, dict], typing.Awaitable[dict]]] = {
+    'get_mode': get_mode,
+    'get_cached_response_status': get_cached_response_status,
+}

src/langbot/pkg/platform/adapters/officialaccount/types.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+ADAPTER_NAME = 'officialaccount-eba'

src/langbot/pkg/platform/adapters/telegram/__init__.py

@@ -0,0 +1,3 @@
+from langbot.pkg.platform.adapters.telegram.adapter import TelegramAdapter
+
+__all__ = ["TelegramAdapter"]

src/langbot/pkg/platform/adapters/telegram/adapter.py

@@ -0,0 +1,435 @@
+"""Telegram adapter main class (EBA version).
+
+Inherits AbstractPlatformAdapter, integrating all modules.
+Preserves all existing functionality (messaging, streaming output, markdown card, forum topics, etc.).
+"""
+
+from __future__ import annotations
+
+import time
+import typing
+import traceback
+
+import telegram
+import telegram.ext
+from telegram import Update
+from telegram.ext import (
+    ApplicationBuilder,
+    CallbackQueryHandler,
+    ChatMemberHandler,
+    ContextTypes,
+    MessageHandler,
+    MessageReactionHandler,
+    filters,
+)
+import telegramify_markdown
+import pydantic
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+
+from langbot.pkg.platform.adapters.telegram.message_converter import TelegramMessageConverter
+from langbot.pkg.platform.adapters.telegram.event_converter import TelegramEventConverter, LegacyEventConverter
+from langbot.pkg.platform.adapters.telegram.api_impl import TelegramAPIMixin
+from langbot.pkg.platform.adapters.telegram.platform_api import PLATFORM_API_MAP
+
+
+class TelegramAdapter(TelegramAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    """Telegram adapter (EBA version)."""
+
+    bot: telegram.Bot = pydantic.Field(exclude=True)
+    application: telegram.ext.Application = pydantic.Field(exclude=True)
+
+    message_converter: TelegramMessageConverter = TelegramMessageConverter()
+    event_converter: TelegramEventConverter = TelegramEventConverter()
+    legacy_event_converter: LegacyEventConverter = LegacyEventConverter()
+
+    config: dict
+
+    msg_stream_id: dict
+    """Stream message ID map. Key: stream message ID, value: first message source ID."""
+
+    seq: int
+    """Sequence number for message ordering."""
+
+    listeners: typing.Dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = {}
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        async def telegram_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
+            if (
+                not update.message
+                and not update.edited_message
+                and not update.chat_member
+                and not update.my_chat_member
+                and not update.callback_query
+                and not update.message_reaction
+            ):
+                return
+
+            # Skip messages from the bot itself
+            if update.message and update.message.from_user and update.message.from_user.is_bot:
+                return
+
+            try:
+                # Legacy event type callbacks (compat with existing botmgr FriendMessage / GroupMessage listeners)
+                if update.message and (
+                    platform_events.FriendMessage in self.listeners or platform_events.GroupMessage in self.listeners
+                ):
+                    legacy_event = await self.legacy_event_converter.target2yiri(update, self.bot, self.bot_account_id)
+                    if legacy_event and type(legacy_event) in self.listeners:
+                        await self.listeners[type(legacy_event)](legacy_event, self)
+
+                eba_event = await self.event_converter.target2yiri(update, self.bot, self.bot_account_id)
+                if eba_event:
+                    await self._dispatch_eba_event(eba_event)
+
+            except Exception:
+                await self.logger.error(f'Error in telegram callback: {traceback.format_exc()}')
+
+        application = ApplicationBuilder().token(config['token']).build()
+        bot = application.bot
+
+        # Register handler for all common update types
+        application.add_handler(
+            MessageHandler(
+                filters.TEXT | (filters.COMMAND) | filters.PHOTO | filters.VOICE | filters.Document.ALL,
+                telegram_callback,
+            )
+        )
+        # Register edited message handler
+        application.add_handler(
+            MessageHandler(
+                filters.UpdateType.EDITED_MESSAGE,
+                telegram_callback,
+            )
+        )
+        application.add_handler(
+            ChatMemberHandler(
+                telegram_callback,
+                ChatMemberHandler.CHAT_MEMBER,
+            )
+        )
+        application.add_handler(
+            ChatMemberHandler(
+                telegram_callback,
+                ChatMemberHandler.MY_CHAT_MEMBER,
+            )
+        )
+        application.add_handler(CallbackQueryHandler(telegram_callback))
+        application.add_handler(
+            MessageReactionHandler(
+                telegram_callback,
+                MessageReactionHandler.MESSAGE_REACTION,
+            )
+        )
+
+        super().__init__(
+            config=config,
+            logger=logger,
+            msg_stream_id={},
+            seq=1,
+            bot=bot,
+            application=application,
+            bot_account_id='',
+            listeners={},
+        )
+
+    # ---- Capability Declaration ----
+
+    def get_supported_events(self) -> list[str]:
+        return [
+            'message.received',
+            'message.edited',
+            'message.reaction',
+            'group.member_joined',
+            'group.member_left',
+            'group.member_banned',
+            'bot.invited_to_group',
+            'bot.removed_from_group',
+            'bot.muted',
+            'bot.unmuted',
+            'platform.specific',
+        ]
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'send_message',
+            'reply_message',
+            'edit_message',
+            'delete_message',
+            'forward_message',
+            'get_group_info',
+            'get_group_member_list',
+            'get_group_member_info',
+            'get_user_info',
+            'get_file_url',
+            'mute_member',
+            'unmute_member',
+            'kick_member',
+            'leave_group',
+            'call_platform_api',
+        ]
+
+    # ---- Message Send / Reply (preserving original logic) ----
+
+    async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain):
+        components = await TelegramMessageConverter.yiri2target(message, self.bot)
+
+        chat_id_str, _, thread_id_str = str(target_id).partition('#')
+        chat_id: int | str = int(chat_id_str) if chat_id_str.lstrip('-').isdigit() else chat_id_str
+        message_thread_id = int(thread_id_str) if thread_id_str and thread_id_str.isdigit() else None
+
+        for component in components:
+            component_type = component.get('type')
+            args = {'chat_id': chat_id}
+            if message_thread_id is not None:
+                args['message_thread_id'] = message_thread_id
+
+            if component_type == 'text':
+                text = component.get('text', '')
+                if self.config['markdown_card'] is True:
+                    text = telegramify_markdown.markdownify(content=text)
+                    args['parse_mode'] = 'MarkdownV2'
+                args['text'] = text
+                await self.bot.send_message(**args)
+            elif component_type == 'photo':
+                photo = component.get('photo')
+                if photo is None:
+                    continue
+                args['photo'] = telegram.InputFile(photo)
+                await self.bot.send_photo(**args)
+            elif component_type == 'document':
+                doc = component.get('document')
+                if doc is None:
+                    continue
+                filename = component.get('filename', 'file')
+                args['document'] = telegram.InputFile(doc, filename=filename)
+                await self.bot.send_document(**args)
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ):
+        assert isinstance(message_source.source_platform_object, Update)
+        components = await TelegramMessageConverter.yiri2target(message, self.bot)
+
+        for component in components:
+            component_type = component.get('type')
+            args = {
+                'chat_id': message_source.source_platform_object.effective_chat.id,
+            }
+
+            if message_source.source_platform_object.message.message_thread_id:
+                args['message_thread_id'] = message_source.source_platform_object.message.message_thread_id
+
+            if quote_origin:
+                args['reply_to_message_id'] = message_source.source_platform_object.message.id
+
+            if component_type == 'text':
+                if self.config['markdown_card'] is True:
+                    content = telegramify_markdown.markdownify(
+                        content=component['text'],
+                    )
+                else:
+                    content = component['text']
+                if self.config['markdown_card'] is True:
+                    args['parse_mode'] = 'MarkdownV2'
+                args['text'] = content
+                await self.bot.send_message(**args)
+            elif component_type == 'photo':
+                photo = component.get('photo')
+                if photo is None:
+                    continue
+                args['photo'] = telegram.InputFile(photo)
+                await self.bot.send_photo(**args)
+            elif component_type == 'document':
+                doc = component.get('document')
+                if doc is None:
+                    continue
+                filename = component.get('filename', 'file')
+                args['document'] = telegram.InputFile(doc, filename=filename)
+                await self.bot.send_document(**args)
+
+    # ---- Streaming Output (preserving original logic) ----
+
+    def _process_markdown(self, text: str) -> str:
+        if self.config.get('markdown_card', False):
+            return telegramify_markdown.markdownify(content=text)
+        return text
+
+    def _build_message_args(self, chat_id: int, text: str, message_thread_id: int = None, **extra_args) -> dict:
+        args = {'chat_id': chat_id, 'text': self._process_markdown(text), **extra_args}
+        if message_thread_id:
+            args['message_thread_id'] = message_thread_id
+        if self.config.get('markdown_card', False):
+            args['parse_mode'] = 'MarkdownV2'
+        return args
+
+    async def create_message_card(self, message_id, event):
+        assert isinstance(event.source_platform_object, Update)
+        update = event.source_platform_object
+        chat_id = update.effective_chat.id
+        chat_type = update.effective_chat.type
+        message_thread_id = update.message.message_thread_id
+
+        if chat_type == 'private':
+            draft_id = int(time.time() * 1000)
+            self.msg_stream_id[message_id] = ('private', draft_id)
+
+            args = self._build_message_args(chat_id, 'Thinking...', message_thread_id, draft_id=draft_id)
+            await self.bot.send_message_draft(**args)
+        else:
+            args = self._build_message_args(chat_id, 'Thinking...', message_thread_id)
+            send_msg = await self.bot.send_message(**args)
+            self.msg_stream_id[message_id] = ('group', send_msg.message_id)
+
+        return True
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        message_id = bot_message.resp_message_id
+        msg_seq = bot_message.msg_sequence
+        assert isinstance(message_source.source_platform_object, Update)
+        update = message_source.source_platform_object
+        chat_id = update.effective_chat.id
+        message_thread_id = update.message.message_thread_id
+
+        if message_id not in self.msg_stream_id:
+            return
+
+        chat_mode, draft_id = self.msg_stream_id[message_id]
+        components = await TelegramMessageConverter.yiri2target(message, self.bot)
+
+        if not components or components[0]['type'] != 'text':
+            if is_final and bot_message.tool_calls is None:
+                self.msg_stream_id.pop(message_id)
+            return
+
+        content = components[0]['text']
+
+        if chat_mode == 'private':
+            args = self._build_message_args(chat_id, content, message_thread_id, draft_id=draft_id)
+            await self.bot.send_message_draft(**args)
+            if is_final and bot_message.tool_calls is None:
+                del args['draft_id']
+                await self.bot.send_message(**args)
+                self.msg_stream_id.pop(message_id)
+        else:
+            stream_id = draft_id
+            if (msg_seq - 1) % 8 == 0 or is_final:
+                args = {
+                    'message_id': stream_id,
+                    'chat_id': chat_id,
+                    'text': self._process_markdown(content),
+                }
+                if self.config.get('markdown_card', False):
+                    args['parse_mode'] = 'MarkdownV2'
+                await self.bot.edit_message_text(**args)
+
+            if is_final and bot_message.tool_calls is None:
+                self.msg_stream_id.pop(message_id)
+
+    # ---- Forum Topic / Custom launcher_id (preserving original logic) ----
+
+    def get_launcher_id(self, event: platform_events.MessageEvent) -> str | None:
+        if not isinstance(event.source_platform_object, Update):
+            return None
+
+        message = event.source_platform_object.message
+        if not message:
+            return None
+
+        if message.message_thread_id:
+            if isinstance(event, platform_events.GroupMessage):
+                return f'{event.group.id}#{message.message_thread_id}'
+            elif isinstance(event, platform_events.FriendMessage):
+                return f'{event.sender.id}#{message.message_thread_id}'
+
+        return None
+
+    # ---- Stream Output Support Check ----
+
+    async def is_stream_output_supported(self) -> bool:
+        is_stream = False
+        if self.config.get('enable-stream-reply', None):
+            is_stream = True
+        return is_stream
+
+    async def is_muted(self, group_id: int) -> bool:
+        return False
+
+    # ---- Event Listeners ----
+
+    async def _dispatch_eba_event(self, event: platform_events.EBAEvent):
+        """Dispatch once, preferring the most specific registered listener."""
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners.pop(event_type, None)
+
+    # ---- Pass-through API ----
+
+    async def call_platform_api(
+        self,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """Call a Telegram-specific platform API."""
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+            raise NotSupportedError(f'call_platform_api:{action}')
+        return await handler(self.bot, params)
+
+    # ---- Lifecycle ----
+
+    async def run_async(self):
+        await self.application.initialize()
+        self.bot_account_id = (await self.bot.get_me()).username
+        await self.application.updater.start_polling(allowed_updates=Update.ALL_TYPES)
+        await self.application.start()
+        await self.logger.info('Telegram adapter running')
+
+    async def kill(self) -> bool:
+        if self.application.running:
+            await self.application.stop()
+            if self.application.updater:
+                await self.application.updater.stop()
+            await self.logger.info('Telegram adapter stopped')
+        return True

src/langbot/pkg/platform/adapters/telegram/api_impl.py

@@ -0,0 +1,252 @@
+"""Telegram universal API implementation (EBA version).
+
+Implements optional API methods defined in AbstractPlatformAdapter.
+"""
+
+from __future__ import annotations
+
+import typing
+
+import telegram
+
+import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+
+from langbot.pkg.platform.adapters.telegram.message_converter import TelegramMessageConverter
+
+
+class TelegramAPIMixin:
+    """Telegram universal API implementation mixin.
+
+    Used via multiple inheritance in TelegramAdapter.
+    Requires self.bot: telegram.Bot and self.config: dict attributes.
+    """
+
+    bot: telegram.Bot
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: platform_message.MessageChain,
+    ) -> None:
+        """Edit a previously sent message."""
+        components = await TelegramMessageConverter.yiri2target(new_content, self.bot)
+
+        for component in components:
+            if component['type'] == 'text':
+                text = component['text']
+                if self.config.get('markdown_card', False):
+                    import telegramify_markdown
+
+                    text = telegramify_markdown.markdownify(content=text)
+                args = {
+                    'chat_id': chat_id,
+                    'message_id': message_id,
+                    'text': text,
+                }
+                if self.config.get('markdown_card', False):
+                    args['parse_mode'] = 'MarkdownV2'
+                await self.bot.edit_message_text(**args)
+                return
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """Delete / recall a message."""
+        await self.bot.delete_message(chat_id=chat_id, message_id=message_id)
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> platform_events.MessageResult:
+        """Forward a message to another chat."""
+        result = await self.bot.forward_message(
+            chat_id=to_chat_id,
+            from_chat_id=from_chat_id,
+            message_id=message_id,
+        )
+        return platform_events.MessageResult(
+            message_id=result.message_id,
+            raw={'message_id': result.message_id},
+        )
+
+    async def get_group_info(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroup:
+        """Get group information."""
+        chat = await self.bot.get_chat(chat_id=group_id)
+        return platform_entities.UserGroup(
+            id=chat.id,
+            name=chat.title or '',
+            description=chat.description or None,
+            member_count=await self._get_member_count(group_id),
+        )
+
+    async def _get_member_count(self, group_id: typing.Union[int, str]) -> typing.Optional[int]:
+        """Get group member count."""
+        try:
+            return await self.bot.get_chat_member_count(chat_id=group_id)
+        except Exception:
+            return None
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        """Get group member list.
+
+        Note: Telegram Bot API only supports fetching the admin list
+        (get_chat_administrators), not the full member list.
+        This method returns the admin list.
+        """
+        admins = await self.bot.get_chat_administrators(chat_id=group_id)
+        members = []
+        for admin in admins:
+            role = platform_entities.MemberRole.MEMBER
+            if admin.status == 'creator':
+                role = platform_entities.MemberRole.OWNER
+            elif admin.status == 'administrator':
+                role = platform_entities.MemberRole.ADMIN
+
+            members.append(
+                platform_entities.UserGroupMember(
+                    user=platform_entities.User(
+                        id=admin.user.id,
+                        nickname=admin.user.first_name or '',
+                        username=admin.user.username,
+                        is_bot=admin.user.is_bot,
+                    ),
+                    group_id=group_id,
+                    role=role,
+                    display_name=admin.custom_title if hasattr(admin, 'custom_title') else None,
+                )
+            )
+        return members
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        """Get information about a specific group member."""
+        member = await self.bot.get_chat_member(chat_id=group_id, user_id=user_id)
+
+        role = platform_entities.MemberRole.MEMBER
+        if member.status == 'creator':
+            role = platform_entities.MemberRole.OWNER
+        elif member.status == 'administrator':
+            role = platform_entities.MemberRole.ADMIN
+
+        return platform_entities.UserGroupMember(
+            user=platform_entities.User(
+                id=member.user.id,
+                nickname=member.user.first_name or '',
+                username=member.user.username,
+                is_bot=member.user.is_bot,
+            ),
+            group_id=group_id,
+            role=role,
+            display_name=member.custom_title if hasattr(member, 'custom_title') else None,
+        )
+
+    async def get_user_info(
+        self,
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.User:
+        """Get user information."""
+        chat = await self.bot.get_chat(chat_id=user_id)
+        return platform_entities.User(
+            id=chat.id,
+            nickname=chat.first_name or '',
+            username=chat.username,
+        )
+
+    async def upload_file(
+        self,
+        file_data: bytes,
+        filename: str,
+    ) -> str:
+        """Upload a file.
+
+        Telegram does not support standalone file uploads; files are sent as
+        part of messages. This method raises NotSupportedError.
+        """
+        from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+        raise NotSupportedError('upload_file')
+
+    async def get_file_url(
+        self,
+        file_id: str,
+    ) -> str:
+        """Get file download URL."""
+        file = await self.bot.get_file(file_id)
+        return file.file_path
+
+    async def mute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        """Mute a group member."""
+        import datetime
+
+        permissions = telegram.ChatPermissions(can_send_messages=False)
+        kwargs = {
+            'chat_id': group_id,
+            'user_id': user_id,
+            'permissions': permissions,
+        }
+        if duration > 0:
+            kwargs['until_date'] = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(seconds=duration)
+        await self.bot.restrict_chat_member(**kwargs)
+
+    async def unmute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """Unmute a group member."""
+        permissions = telegram.ChatPermissions(
+            can_send_messages=True,
+            can_send_other_messages=True,
+            can_add_web_page_previews=True,
+            can_send_audios=True,
+            can_send_documents=True,
+            can_send_photos=True,
+            can_send_videos=True,
+            can_send_video_notes=True,
+            can_send_voice_notes=True,
+        )
+        await self.bot.restrict_chat_member(
+            chat_id=group_id,
+            user_id=user_id,
+            permissions=permissions,
+        )
+
+    async def kick_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """Kick a member from the group."""
+        await self.bot.ban_chat_member(chat_id=group_id, user_id=user_id)
+
+    async def leave_group(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> None:
+        """Make the bot leave a group."""
+        await self.bot.leave_chat(chat_id=group_id)

src/langbot/pkg/platform/adapters/telegram/event_converter.py

@@ -0,0 +1,424 @@
+"""Telegram event converter (EBA version).
+
+Converts all Telegram Update types to unified EBA events, not just messages.
+"""
+
+from __future__ import annotations
+
+import typing
+
+import telegram
+from telegram import Update
+
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+
+from langbot.pkg.platform.adapters.telegram.message_converter import TelegramMessageConverter
+
+
+def _make_user(tg_user: telegram.User) -> platform_entities.User:
+    """Convert a Telegram User to a unified User entity."""
+    return platform_entities.User(
+        id=tg_user.id,
+        nickname=tg_user.first_name or '',
+        username=tg_user.username,
+        is_bot=tg_user.is_bot,
+    )
+
+
+def _make_user_group(tg_chat: telegram.Chat) -> platform_entities.UserGroup:
+    """Convert a Telegram Chat to a unified UserGroup entity."""
+    return platform_entities.UserGroup(
+        id=tg_chat.id,
+        name=tg_chat.title or tg_chat.first_name or '',
+        description=tg_chat.description if hasattr(tg_chat, 'description') else None,
+    )
+
+
+def _chat_type(tg_chat: telegram.Chat) -> platform_entities.ChatType:
+    """Map Telegram Chat type to unified ChatType."""
+    if tg_chat.type == 'private':
+        return platform_entities.ChatType.PRIVATE
+    return platform_entities.ChatType.GROUP
+
+
+class TelegramEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    """Telegram event converter (EBA version)."""
+
+    @staticmethod
+    async def yiri2target(event: platform_events.Event, bot: telegram.Bot):
+        """Convert a unified event to a raw Telegram event (generally not needed)."""
+        if hasattr(event, 'source_platform_object'):
+            return event.source_platform_object
+        return None
+
+    @staticmethod
+    async def target2yiri(
+        update: Update,
+        bot: telegram.Bot,
+        bot_account_id: str,
+    ) -> typing.Optional[platform_events.EBAEvent]:
+        """Convert a Telegram Update to a unified EBA event.
+
+        Supports: message, edited_message, chat_member, my_chat_member,
+        callback_query, message_reaction, etc.
+        Unmappable events are wrapped as PlatformSpecificEvent.
+        """
+        import time
+
+        # ---- Message event ----
+        if (
+            update.message
+            and update.message.text is not None
+            or (update.message and (update.message.photo or update.message.voice or update.message.document))
+        ):
+            return await TelegramEventConverter._convert_message(update, bot, bot_account_id)
+
+        # ---- Edited message event ----
+        if update.edited_message:
+            return await TelegramEventConverter._convert_edited_message(update, bot, bot_account_id)
+
+        # ---- Member change event (chat_member) ----
+        if update.chat_member:
+            return TelegramEventConverter._convert_chat_member(update)
+
+        # ---- Bot's own member status change (my_chat_member) ----
+        if update.my_chat_member:
+            return TelegramEventConverter._convert_my_chat_member(update)
+
+        # ---- Callback query (button clicks, etc.) ----
+        if update.callback_query:
+            return platform_events.PlatformSpecificEvent(
+                type='platform.specific',
+                timestamp=time.time(),
+                adapter_name='telegram',
+                action='callback_query',
+                data={
+                    'callback_query_id': update.callback_query.id,
+                    'data': update.callback_query.data,
+                    'from_user_id': update.callback_query.from_user.id if update.callback_query.from_user else None,
+                    'message_id': update.callback_query.message.message_id if update.callback_query.message else None,
+                },
+                source_platform_object=update,
+            )
+
+        # ---- Message reaction ----
+        if update.message_reaction:
+            return TelegramEventConverter._convert_reaction(update)
+
+        # ---- Fallback: wrap as PlatformSpecificEvent ----
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            timestamp=time.time(),
+            adapter_name='telegram',
+            action='unknown_update',
+            data={'update_id': update.update_id},
+            source_platform_object=update,
+        )
+
+    @staticmethod
+    async def _convert_message(
+        update: Update,
+        bot: telegram.Bot,
+        bot_account_id: str,
+    ) -> platform_events.MessageReceivedEvent:
+        """Convert a Telegram message to MessageReceivedEvent."""
+        message = update.message
+        lb_message = await TelegramMessageConverter.target2yiri(message, bot, bot_account_id)
+
+        sender = _make_user(message.from_user) if message.from_user else platform_entities.User(id='')
+        chat = message.chat
+        ct = _chat_type(chat)
+
+        group = None
+        if ct == platform_entities.ChatType.GROUP:
+            group = _make_user_group(chat)
+
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            timestamp=message.date.timestamp() if message.date else 0.0,
+            adapter_name='telegram',
+            message_id=message.message_id,
+            message_chain=lb_message,
+            sender=sender,
+            chat_type=ct,
+            chat_id=chat.id,
+            group=group,
+            source_platform_object=update,
+        )
+
+    @staticmethod
+    async def _convert_edited_message(
+        update: Update,
+        bot: telegram.Bot,
+        bot_account_id: str,
+    ) -> platform_events.MessageEditedEvent:
+        """Convert a Telegram edited message to MessageEditedEvent."""
+        message = update.edited_message
+        lb_message = await TelegramMessageConverter.target2yiri(message, bot, bot_account_id)
+
+        editor = _make_user(message.from_user) if message.from_user else platform_entities.User(id='')
+        chat = message.chat
+        ct = _chat_type(chat)
+
+        group = None
+        if ct == platform_entities.ChatType.GROUP:
+            group = _make_user_group(chat)
+
+        return platform_events.MessageEditedEvent(
+            type='message.edited',
+            timestamp=message.edit_date.timestamp() if message.edit_date else 0.0,
+            adapter_name='telegram',
+            message_id=message.message_id,
+            new_content=lb_message,
+            editor=editor,
+            chat_type=ct,
+            chat_id=chat.id,
+            group=group,
+            source_platform_object=update,
+        )
+
+    @staticmethod
+    def _convert_chat_member(update: Update) -> typing.Optional[platform_events.EBAEvent]:
+        """Convert a chat_member update to MemberJoinedEvent / MemberLeftEvent / etc."""
+        import time
+
+        cm = update.chat_member
+        chat = cm.chat
+        group = _make_user_group(chat)
+        member = _make_user(cm.new_chat_member.user) if cm.new_chat_member else platform_entities.User(id='')
+        inviter = _make_user(cm.from_user) if cm.from_user else None
+
+        old_status = cm.old_chat_member.status if cm.old_chat_member else None
+        new_status = cm.new_chat_member.status if cm.new_chat_member else None
+
+        # Member joined
+        if old_status in (None, 'left', 'kicked') and new_status in (
+            'member',
+            'administrator',
+            'creator',
+            'restricted',
+        ):
+            return platform_events.MemberJoinedEvent(
+                type='group.member_joined',
+                timestamp=cm.date.timestamp() if cm.date else time.time(),
+                adapter_name='telegram',
+                group=group,
+                member=member,
+                inviter=inviter,
+                join_type='invite' if inviter and inviter.id != member.id else 'direct',
+                source_platform_object=update,
+            )
+
+        # Member left / kicked
+        if old_status in ('member', 'administrator', 'creator', 'restricted') and new_status in ('left', 'kicked'):
+            is_kicked = new_status == 'kicked'
+            return platform_events.MemberLeftEvent(
+                type='group.member_left',
+                timestamp=cm.date.timestamp() if cm.date else time.time(),
+                adapter_name='telegram',
+                group=group,
+                member=member,
+                is_kicked=is_kicked,
+                operator=inviter if is_kicked else None,
+                source_platform_object=update,
+            )
+
+        # Member muted (restricted with can_send_messages == False)
+        if new_status == 'restricted' and cm.new_chat_member:
+            restricted = cm.new_chat_member
+            if hasattr(restricted, 'can_send_messages') and not restricted.can_send_messages:
+                duration = None
+                if hasattr(restricted, 'until_date') and restricted.until_date:
+                    duration = int(restricted.until_date.timestamp() - time.time())
+                return platform_events.MemberBannedEvent(
+                    type='group.member_banned',
+                    timestamp=cm.date.timestamp() if cm.date else time.time(),
+                    adapter_name='telegram',
+                    group=group,
+                    member=member,
+                    operator=inviter,
+                    duration=duration,
+                    source_platform_object=update,
+                )
+
+        # Other chat_member changes -> PlatformSpecificEvent
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            timestamp=cm.date.timestamp() if cm.date else time.time(),
+            adapter_name='telegram',
+            action='chat_member_updated',
+            data={
+                'old_status': old_status,
+                'new_status': new_status,
+                'chat_id': chat.id,
+                'user_id': member.id,
+            },
+            source_platform_object=update,
+        )
+
+    @staticmethod
+    def _convert_my_chat_member(update: Update) -> typing.Optional[platform_events.EBAEvent]:
+        """Convert a my_chat_member update to bot status events."""
+        import time
+
+        mcm = update.my_chat_member
+        chat = mcm.chat
+        group = _make_user_group(chat)
+        inviter = _make_user(mcm.from_user) if mcm.from_user else None
+
+        old_status = mcm.old_chat_member.status if mcm.old_chat_member else None
+        new_status = mcm.new_chat_member.status if mcm.new_chat_member else None
+
+        # Bot invited to group
+        if old_status in (None, 'left', 'kicked') and new_status in ('member', 'administrator'):
+            return platform_events.BotInvitedToGroupEvent(
+                type='bot.invited_to_group',
+                timestamp=mcm.date.timestamp() if mcm.date else time.time(),
+                adapter_name='telegram',
+                group=group,
+                inviter=inviter,
+                source_platform_object=update,
+            )
+
+        # Bot removed from group
+        if old_status in ('member', 'administrator', 'creator') and new_status in ('left', 'kicked'):
+            return platform_events.BotRemovedFromGroupEvent(
+                type='bot.removed_from_group',
+                timestamp=mcm.date.timestamp() if mcm.date else time.time(),
+                adapter_name='telegram',
+                group=group,
+                operator=inviter,
+                source_platform_object=update,
+            )
+
+        # Bot muted
+        if new_status == 'restricted' and mcm.new_chat_member:
+            restricted = mcm.new_chat_member
+            if hasattr(restricted, 'can_send_messages') and not restricted.can_send_messages:
+                duration = None
+                if hasattr(restricted, 'until_date') and restricted.until_date:
+                    duration = int(restricted.until_date.timestamp() - time.time())
+                return platform_events.BotMutedEvent(
+                    type='bot.muted',
+                    timestamp=mcm.date.timestamp() if mcm.date else time.time(),
+                    adapter_name='telegram',
+                    group=group,
+                    operator=inviter,
+                    duration=duration,
+                    source_platform_object=update,
+                )
+
+        if old_status == 'restricted' and new_status in ('member', 'administrator') and mcm.new_chat_member:
+            return platform_events.BotUnmutedEvent(
+                type='bot.unmuted',
+                timestamp=mcm.date.timestamp() if mcm.date else time.time(),
+                adapter_name='telegram',
+                group=group,
+                operator=inviter,
+                source_platform_object=update,
+            )
+
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            timestamp=mcm.date.timestamp() if mcm.date else time.time(),
+            adapter_name='telegram',
+            action='my_chat_member_updated',
+            data={
+                'old_status': old_status,
+                'new_status': new_status,
+                'chat_id': chat.id,
+            },
+            source_platform_object=update,
+        )
+
+    @staticmethod
+    def _convert_reaction(update: Update) -> platform_events.MessageReactionEvent:
+        """Convert a Telegram message_reaction to MessageReactionEvent."""
+        import time
+
+        reaction = update.message_reaction
+        chat = reaction.chat
+
+        # Extract newly added emojis
+        new_emojis = []
+        if reaction.new_reaction:
+            for r in reaction.new_reaction:
+                if hasattr(r, 'emoji'):
+                    new_emojis.append(r.emoji)
+                elif hasattr(r, 'custom_emoji_id'):
+                    new_emojis.append(str(r.custom_emoji_id))
+
+        user = platform_entities.User(id='')
+        if reaction.user:
+            user = _make_user(reaction.user)
+
+        ct = _chat_type(chat)
+        group = _make_user_group(chat) if ct == platform_entities.ChatType.GROUP else None
+
+        return platform_events.MessageReactionEvent(
+            type='message.reaction',
+            timestamp=reaction.date.timestamp() if reaction.date else time.time(),
+            adapter_name='telegram',
+            message_id=reaction.message_id,
+            user=user,
+            reaction=new_emojis[0] if new_emojis else '',
+            is_add=len(new_emojis) > 0,
+            chat_type=ct,
+            chat_id=chat.id,
+            group=group,
+            source_platform_object=update,
+        )
+
+
+class LegacyEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    """Legacy event converter (compatibility layer).
+
+    Converts Telegram Updates to the old FriendMessage / GroupMessage format.
+    Used during the transition period to maintain backward compatibility.
+    """
+
+    @staticmethod
+    async def yiri2target(event: platform_events.MessageEvent, bot: telegram.Bot):
+        return event.source_platform_object
+
+    @staticmethod
+    async def target2yiri(event: Update, bot: telegram.Bot, bot_account_id: str):
+        """Convert to legacy format (FriendMessage / GroupMessage)."""
+        import langbot_plugin.api.entities.builtin.platform.events as legacy_events
+        import langbot_plugin.api.entities.builtin.platform.entities as legacy_entities
+
+        if not event.message:
+            return None
+
+        lb_message = await TelegramMessageConverter.target2yiri(event.message, bot, bot_account_id)
+
+        if event.effective_chat.type == 'private':
+            return legacy_events.FriendMessage(
+                sender=legacy_entities.Friend(
+                    id=event.effective_chat.id,
+                    nickname=event.effective_chat.first_name,
+                    remark=str(event.effective_chat.id),
+                ),
+                message_chain=lb_message,
+                time=event.message.date.timestamp(),
+                source_platform_object=event,
+            )
+        else:
+            return legacy_events.GroupMessage(
+                sender=legacy_entities.GroupMember(
+                    id=event.effective_chat.id,
+                    member_name=event.effective_chat.title,
+                    permission=legacy_entities.Permission.Member,
+                    group=legacy_entities.Group(
+                        id=event.effective_chat.id,
+                        name=event.effective_chat.title,
+                        permission=legacy_entities.Permission.Member,
+                    ),
+                    special_title='',
+                ),
+                message_chain=lb_message,
+                time=event.message.date.timestamp(),
+                source_platform_object=event,
+            )

src/langbot/pkg/platform/adapters/telegram/manifest.yaml

@@ -0,0 +1,98 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: telegram-eba
+  label:
+    en_US: Telegram (EBA)
+    zh_Hans: 电报 (EBA)
+  description:
+    en_US: Telegram Bot adapter (EBA architecture)
+    zh_Hans: 电报 Bot 适配器（EBA 架构版本）
+  icon: telegram.svg
+
+spec:
+  config:
+    - name: token
+      label:
+        en_US: Token
+        zh_Hans: 令牌
+      type: string
+      required: true
+      default: ""
+    - name: markdown_card
+      label:
+        en_US: Markdown Card
+        zh_Hans: 是否使用 Markdown 卡片
+      type: boolean
+      required: false
+      default: true
+    - name: enable-stream-reply
+      label:
+        en_US: Enable Stream Reply Mode
+        zh_Hans: 启用电报流式回复模式
+      description:
+        en_US: If enabled, the bot will use the stream of telegram reply mode
+        zh_Hans: 如果启用，将使用电报流式方式来回复内容
+      type: boolean
+      required: true
+      default: false
+
+  supported_events:
+    - message.received
+    - message.edited
+    - message.reaction
+    - group.member_joined
+    - group.member_left
+    - group.member_banned
+    - bot.invited_to_group
+    - bot.removed_from_group
+    - bot.muted
+    - bot.unmuted
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - edit_message
+      - delete_message
+      - forward_message
+      - get_group_info
+      - get_group_member_list
+      - get_group_member_info
+      - get_user_info
+      - get_file_url
+      - mute_member
+      - unmute_member
+      - kick_member
+      - leave_group
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: pin_message
+      description: { en_US: "Pin a message", zh_Hans: "置顶消息" }
+    - action: unpin_message
+      description: { en_US: "Unpin a message", zh_Hans: "取消置顶" }
+    - action: unpin_all_messages
+      description: { en_US: "Unpin all messages", zh_Hans: "取消所有置顶" }
+    - action: get_chat_administrators
+      description: { en_US: "Get chat admins", zh_Hans: "获取群管理员列表" }
+    - action: set_chat_title
+      description: { en_US: "Set chat title", zh_Hans: "修改群名称" }
+    - action: set_chat_description
+      description: { en_US: "Set chat description", zh_Hans: "修改群描述" }
+    - action: get_chat_member_count
+      description: { en_US: "Get member count", zh_Hans: "获取群成员数量" }
+    - action: send_chat_action
+      description: { en_US: "Send chat action (typing, etc.)", zh_Hans: "发送聊天动作" }
+    - action: create_chat_invite_link
+      description: { en_US: "Create invite link", zh_Hans: "创建邀请链接" }
+    - action: answer_callback_query
+      description: { en_US: "Answer callback query", zh_Hans: "应答回调查询" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: TelegramAdapter

src/langbot/pkg/platform/adapters/telegram/message_converter.py

@@ -0,0 +1,145 @@
+"""Telegram message chain converter.
+
+Migrated from the original sources/telegram.py TelegramMessageConverter. Logic unchanged.
+"""
+
+from __future__ import annotations
+
+import base64
+
+import telegram
+
+from langbot.pkg.utils import httpclient
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+
+
+class TelegramMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    async def yiri2target(message_chain: platform_message.MessageChain, bot: telegram.Bot) -> list[dict]:
+        """Convert a LangBot MessageChain to a list of Telegram-sendable components."""
+        components = []
+
+        for component in message_chain:
+            if isinstance(component, platform_message.Plain):
+                components.append({'type': 'text', 'text': component.text})
+            elif isinstance(component, platform_message.Image):
+                photo_bytes = None
+
+                if component.base64:
+                    b64_data = component.base64
+                    if ';base64,' in b64_data:
+                        b64_data = b64_data.split(';base64,', 1)[1]
+                    photo_bytes = base64.b64decode(b64_data)
+                elif component.url:
+                    session = httpclient.get_session()
+                    async with session.get(component.url) as response:
+                        photo_bytes = await response.read()
+                elif component.path:
+                    with open(component.path, 'rb') as f:
+                        photo_bytes = f.read()
+
+                components.append({'type': 'photo', 'photo': photo_bytes})
+            elif isinstance(component, platform_message.File):
+                file_bytes = None
+
+                if component.base64:
+                    b64_data = component.base64
+                    if ';base64,' in b64_data:
+                        b64_data = b64_data.split(';base64,', 1)[1]
+                    file_bytes = base64.b64decode(b64_data)
+                elif component.url:
+                    session = httpclient.get_session()
+                    async with session.get(component.url) as response:
+                        file_bytes = await response.read()
+                elif component.path:
+                    with open(component.path, 'rb') as f:
+                        file_bytes = f.read()
+
+                file_name = getattr(component, 'name', None) or 'file'
+                components.append({'type': 'document', 'document': file_bytes, 'filename': file_name})
+            elif isinstance(component, platform_message.Forward):
+                for node in component.node_list:
+                    components.extend(await TelegramMessageConverter.yiri2target(node.message_chain, bot))
+
+        return components
+
+    @staticmethod
+    async def target2yiri(message: telegram.Message, bot: telegram.Bot, bot_account_id: str):
+        """Convert a Telegram Message to a LangBot MessageChain."""
+        message_components = []
+
+        def parse_message_text(text: str) -> list[platform_message.MessageComponent]:
+            msg_components = []
+
+            if f'@{bot_account_id}' in text:
+                msg_components.append(platform_message.At(target=bot_account_id))
+                text = text.replace(f'@{bot_account_id}', '')
+            msg_components.append(platform_message.Plain(text=text))
+
+            return msg_components
+
+        if message.text:
+            message_text = message.text
+            message_components.extend(parse_message_text(message_text))
+
+        if message.photo:
+            if message.caption:
+                message_components.extend(parse_message_text(message.caption))
+
+            file = await message.photo[-1].get_file()
+
+            file_bytes = None
+            file_format = ''
+
+            async with httpclient.get_session(trust_env=True).get(file.file_path) as response:
+                file_bytes = await response.read()
+                file_format = 'image/jpeg'
+
+            message_components.append(
+                platform_message.Image(
+                    base64=f'data:{file_format};base64,{base64.b64encode(file_bytes).decode("utf-8")}'
+                )
+            )
+
+        if message.voice:
+            if message.caption:
+                message_components.extend(parse_message_text(message.caption))
+
+            file = await message.voice.get_file()
+
+            file_bytes = None
+            file_format = message.voice.mime_type or 'audio/ogg'
+
+            async with httpclient.get_session(trust_env=True).get(file.file_path) as response:
+                file_bytes = await response.read()
+
+            message_components.append(
+                platform_message.Voice(
+                    base64=f'data:{file_format};base64,{base64.b64encode(file_bytes).decode("utf-8")}',
+                    length=message.voice.duration,
+                )
+            )
+
+        if message.document:
+            if message.caption:
+                message_components.extend(parse_message_text(message.caption))
+
+            file = await message.document.get_file()
+            file_name = message.document.file_name or 'document'
+            file_size = message.document.file_size or 0
+            file_format = message.document.mime_type or 'application/octet-stream'
+
+            file_bytes = None
+            async with httpclient.get_session(trust_env=True).get(file.file_path) as response:
+                file_bytes = await response.read()
+
+            message_components.append(
+                platform_message.File(
+                    name=file_name,
+                    size=file_size,
+                    base64=f'data:{file_format};base64,{base64.b64encode(file_bytes).decode("utf-8")}',
+                )
+            )
+
+        return platform_message.MessageChain(message_components)

src/langbot/pkg/platform/adapters/telegram/platform_api.py

@@ -0,0 +1,125 @@
+"""Telegram platform-specific API dispatch table for call_platform_api."""
+
+from __future__ import annotations
+
+import typing
+
+import telegram
+
+
+async def pin_message(bot: telegram.Bot, params: dict) -> dict:
+    """Pin a message in a chat."""
+    await bot.pin_chat_message(
+        chat_id=params['chat_id'],
+        message_id=params['message_id'],
+        disable_notification=params.get('disable_notification', False),
+    )
+    return {"ok": True}
+
+
+async def unpin_message(bot: telegram.Bot, params: dict) -> dict:
+    """Unpin a message in a chat."""
+    await bot.unpin_chat_message(
+        chat_id=params['chat_id'],
+        message_id=params.get('message_id'),
+    )
+    return {"ok": True}
+
+
+async def unpin_all_messages(bot: telegram.Bot, params: dict) -> dict:
+    """Unpin all messages in a chat."""
+    await bot.unpin_all_chat_messages(chat_id=params['chat_id'])
+    return {"ok": True}
+
+
+async def get_chat_administrators(bot: telegram.Bot, params: dict) -> dict:
+    """Get chat administrator list."""
+    admins = await bot.get_chat_administrators(chat_id=params['chat_id'])
+    return {
+        "administrators": [
+            {
+                "user_id": a.user.id,
+                "username": a.user.username,
+                "first_name": a.user.first_name,
+                "status": a.status,
+                "custom_title": getattr(a, 'custom_title', None),
+            }
+            for a in admins
+        ]
+    }
+
+
+async def set_chat_title(bot: telegram.Bot, params: dict) -> dict:
+    """Set chat title."""
+    await bot.set_chat_title(
+        chat_id=params['chat_id'],
+        title=params['title'],
+    )
+    return {"ok": True}
+
+
+async def set_chat_description(bot: telegram.Bot, params: dict) -> dict:
+    """Set chat description."""
+    await bot.set_chat_description(
+        chat_id=params['chat_id'],
+        description=params.get('description', ''),
+    )
+    return {"ok": True}
+
+
+async def get_chat_member_count(bot: telegram.Bot, params: dict) -> dict:
+    """Get chat member count."""
+    count = await bot.get_chat_member_count(chat_id=params['chat_id'])
+    return {"count": count}
+
+
+async def send_chat_action(bot: telegram.Bot, params: dict) -> dict:
+    """Send a chat action (e.g. typing)."""
+    await bot.send_chat_action(
+        chat_id=params['chat_id'],
+        action=params.get('action', 'typing'),
+    )
+    return {"ok": True}
+
+
+async def create_chat_invite_link(bot: telegram.Bot, params: dict) -> dict:
+    """Create a chat invite link."""
+    link = await bot.create_chat_invite_link(
+        chat_id=params['chat_id'],
+        name=params.get('name'),
+        expire_date=params.get('expire_date'),
+        member_limit=params.get('member_limit'),
+    )
+    return {
+        "invite_link": link.invite_link,
+        "name": link.name,
+        "is_primary": link.is_primary,
+        "is_revoked": link.is_revoked,
+    }
+
+
+async def answer_callback_query(bot: telegram.Bot, params: dict) -> dict:
+    """Answer a callback query."""
+    await bot.answer_callback_query(
+        callback_query_id=params['callback_query_id'],
+        text=params.get('text'),
+        show_alert=params.get('show_alert', False),
+        url=params.get('url'),
+    )
+    return {"ok": True}
+
+
+# ---- Action dispatch table ----
+
+PLATFORM_API_MAP: dict[str, typing.Callable[[telegram.Bot, dict], typing.Awaitable[dict]]] = {
+    "pin_message": pin_message,
+    "unpin_message": unpin_message,
+    "unpin_all_messages": unpin_all_messages,
+    "get_chat_administrators": get_chat_administrators,
+    "set_chat_title": set_chat_title,
+    "set_chat_description": set_chat_description,
+    "get_chat_member_count": get_chat_member_count,
+    "send_chat_action": send_chat_action,
+    "create_chat_invite_link": create_chat_invite_link,
+    "answer_callback_query": answer_callback_query,
+}

src/langbot/pkg/platform/adapters/telegram/telegram.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"  viewBox="0 0 48 48" width="96px" height="96px"><path fill="#29b6f6" d="M24,4C13,4,4,13,4,24s9,20,20,20s20-9,20-20S35,4,24,4z"/><path fill="#fff" d="M34,15l-3.7,19.1c0,0-0.2,0.9-1.2,0.9c-0.6,0-0.9-0.3-0.9-0.3L20,28l-4-2l-5.1-1.4c0,0-0.9-0.3-0.9-1	c0-0.6,0.9-0.9,0.9-0.9l21.3-8.5c0,0,0.7-0.2,1.1-0.2c0.3,0,0.6,0.1,0.6,0.5C34,14.8,34,15,34,15z"/><path fill="#b0bec5" d="M23,30.5l-3.4,3.4c0,0-0.1,0.1-0.3,0.1c-0.1,0-0.1,0-0.2,0l1-6L23,30.5z"/><path fill="#cfd8dc" d="M29.9,18.2c-0.2-0.2-0.5-0.3-0.7-0.1L16,26c0,0,2.1,5.9,2.4,6.9c0.3,1,0.6,1,0.6,1l1-6l9.8-9.1	C30,18.7,30.1,18.4,29.9,18.2z"/></svg>

src/langbot/pkg/platform/adapters/telegram/types.py

@@ -0,0 +1,13 @@
+"""Telegram platform-specific type definitions."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class TelegramChatType(str, Enum):
+    """Telegram chat type."""
+    PRIVATE = "private"
+    GROUP = "group"
+    SUPERGROUP = "supergroup"
+    CHANNEL = "channel"

src/langbot/pkg/platform/adapters/wecom/__init__.py

@@ -0,0 +1 @@
+

src/langbot/pkg/platform/adapters/wecom/adapter.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import asyncio
+import traceback
+import typing
+
+import pydantic
+
+from langbot.libs.wecom_api.api import WecomClient
+from langbot.libs.wecom_api.wecomevent import WecomEvent
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot.pkg.platform.adapters.wecom.api_impl import WecomAPIMixin
+from langbot.pkg.platform.adapters.wecom.event_converter import WecomEventConverter
+from langbot.pkg.platform.adapters.wecom.message_converter import WecomMessageConverter
+from langbot.pkg.platform.adapters.wecom.platform_api import PLATFORM_API_MAP
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class WecomAdapter(WecomAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    bot: WecomClient = pydantic.Field(exclude=True)
+
+    message_converter: WecomMessageConverter = WecomMessageConverter()
+    event_converter: WecomEventConverter = WecomEventConverter()
+
+    config: dict
+    bot_uuid: str | None = None
+    listeners: dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = {}
+    _message_cache: dict[str, platform_events.MessageReceivedEvent] = {}
+    _user_cache: dict[str, typing.Any] = {}
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        required_keys = [
+            'corpid',
+            'secret',
+            'token',
+            'EncodingAESKey',
+        ]
+        missing_keys = [key for key in required_keys if key not in config]
+        if missing_keys:
+            raise Exception(f'WeCom missing required config fields: {missing_keys}')
+
+        bot = WecomClient(
+            corpid=config['corpid'],
+            secret=config['secret'],
+            token=config['token'],
+            EncodingAESKey=config['EncodingAESKey'],
+            contacts_secret=config.get('contacts_secret', ''),
+            logger=logger,
+            unified_mode=True,
+            api_base_url=config.get('api_base_url', 'https://qyapi.weixin.qq.com/cgi-bin'),
+        )
+
+        super().__init__(
+            config=config,
+            logger=logger,
+            bot=bot,
+            bot_account_id='',
+            bot_uuid=None,
+            listeners={},
+            _message_cache={},
+            _user_cache={},
+        )
+        self._register_native_handlers()
+
+    def set_bot_uuid(self, bot_uuid: str):
+        self.bot_uuid = bot_uuid
+
+    def get_supported_events(self) -> list[str]:
+        return [
+            'message.received',
+            'platform.specific',
+        ]
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'send_message',
+            'reply_message',
+            'get_message',
+            'get_user_info',
+            'get_friend_list',
+            'call_platform_api',
+        ]
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ) -> platform_events.MessageResult:
+        if target_type not in ('person', 'private'):
+            raise NotSupportedError(f'send_message:{target_type}')
+
+        user_id, agent_id = self._parse_target_id(target_id)
+        content_list = await WecomMessageConverter.yiri2target(message, self.bot)
+        raw_results = []
+        for content in content_list:
+            raw_results.append(await self._send_content(user_id, agent_id, content))
+        return platform_events.MessageResult(raw={'results': raw_results})
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ) -> platform_events.MessageResult:
+        wecom_event = await WecomEventConverter.yiri2target(message_source)
+        if not isinstance(wecom_event, WecomEvent):
+            raise ValueError('WeCom reply_message requires a WecomEvent source object')
+        content_list = await WecomMessageConverter.yiri2target(message, self.bot)
+        raw_results = []
+        for content in content_list:
+            raw_results.append(await self._send_content(wecom_event.user_id, int(wecom_event.agent_id), content))
+        return platform_events.MessageResult(message_id=wecom_event.message_id, raw={'results': raw_results})
+
+    async def call_platform_api(self, action: str, params: dict = {}) -> dict:
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            raise NotSupportedError(f'call_platform_api:{action}')
+        return await handler(self.bot, params)
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        registered = self.listeners.get(event_type)
+        if registered is callback:
+            self.listeners.pop(event_type, None)
+
+    async def handle_unified_webhook(self, bot_uuid: str, path: str, request):
+        return await self.bot.handle_unified_webhook(request)
+
+    async def run_async(self):
+        async def keep_alive():
+            while True:
+                await asyncio.sleep(1)
+
+        await self.logger.info('WeCom EBA adapter running in unified webhook mode')
+        await keep_alive()
+
+    async def kill(self) -> bool:
+        return True
+
+    async def is_muted(self, group_id: int | None = None) -> bool:
+        return False
+
+    def _register_native_handlers(self):
+        async def on_message(event: WecomEvent):
+            await self._handle_native_event(event)
+
+        self.bot.on_message('text')(on_message)
+        self.bot.on_message('image')(on_message)
+
+    async def _handle_native_event(self, event: WecomEvent):
+        self.bot_account_id = event.receiver_id or self.bot_account_id
+        try:
+            if platform_events.FriendMessage in self.listeners:
+                legacy_event = await self.event_converter.target2legacy(event, self.bot)
+                if legacy_event:
+                    callback = self.listeners.get(type(legacy_event))
+                    if callback:
+                        await callback(legacy_event, self)
+
+            eba_event = await self.event_converter.target2yiri(event, self.bot)
+            if eba_event:
+                self._cache_event(eba_event)
+                await self._dispatch_eba_event(eba_event)
+        except Exception:
+            await self.logger.error(f'Error in wecom native event: {traceback.format_exc()}')
+
+    async def _dispatch_eba_event(self, event: platform_events.EBAEvent):
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return
+
+    def _cache_event(self, event: platform_events.Event):
+        if not isinstance(event, platform_events.MessageReceivedEvent):
+            return
+        self._message_cache[str(event.message_id)] = event
+        self._user_cache[str(event.sender.id)] = event.sender
+
+    async def _send_content(self, user_id: str, agent_id: int, content: dict):
+        content_type = content.get('type')
+        if content_type == 'text':
+            return await self.bot.send_private_msg(user_id, agent_id, content.get('content', ''))
+        if content_type == 'image':
+            return await self.bot.send_image(user_id, agent_id, content['media_id'])
+        if content_type == 'voice':
+            return await self.bot.send_voice(user_id, agent_id, content['media_id'])
+        if content_type == 'file':
+            return await self.bot.send_file(user_id, agent_id, content['media_id'])
+        raise NotSupportedError(f'send_content:{content_type}')
+
+    @staticmethod
+    def _parse_target_id(target_id: str) -> tuple[str, int]:
+        user_id, sep, agent_id = str(target_id).partition('|')
+        if not user_id or not sep or not agent_id:
+            raise ValueError('WeCom target_id must be formatted as "user_id|agent_id"')
+        return user_id, int(agent_id)

src/langbot/pkg/platform/adapters/wecom/api_impl.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import typing
+
+from langbot.libs.wecom_api.api import WecomClient
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class WecomAPIMixin:
+    bot: WecomClient
+    _message_cache: dict[str, platform_events.MessageReceivedEvent]
+    _user_cache: dict[str, platform_entities.User]
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> platform_events.MessageReceivedEvent:
+        event = self._message_cache.get(str(message_id))
+        if event is None:
+            raise NotSupportedError('get_message:message_not_cached')
+        return event
+
+    async def get_user_info(self, user_id: typing.Union[int, str]) -> platform_entities.User:
+        cached = self._user_cache.get(str(user_id))
+        if cached is not None:
+            return cached
+        info = await self.bot.get_user_info(str(user_id))
+        return platform_entities.User(
+            id=info.get('userid') or user_id,
+            nickname=info.get('name') or str(user_id),
+            username=info.get('alias') or info.get('userid') or None,
+        )
+
+    async def get_friend_list(self) -> list[platform_entities.User]:
+        return list(self._user_cache.values())
+
+    async def upload_file(self, file_data: bytes, filename: str) -> str:
+        raise NotSupportedError('upload_file')
+
+    async def get_file_url(self, file_id: str) -> str:
+        raise NotSupportedError('get_file_url')
+
+    async def get_group_info(self, group_id: typing.Union[int, str]) -> platform_entities.UserGroup:
+        raise NotSupportedError('get_group_info')
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        raise NotSupportedError('get_group_member_list')
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        raise NotSupportedError('get_group_member_info')
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: platform_message.MessageChain,
+    ) -> None:
+        raise NotSupportedError('edit_message')
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        raise NotSupportedError('delete_message')

src/langbot/pkg/platform/adapters/wecom/event_converter.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import typing
+
+from langbot.libs.wecom_api.api import WecomClient
+from langbot.libs.wecom_api.wecomevent import WecomEvent
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot.pkg.platform.adapters.wecom.message_converter import WecomMessageConverter
+from langbot.pkg.platform.adapters.wecom.types import ADAPTER_NAME, make_private_chat_id
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+
+
+class WecomEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    @staticmethod
+    async def yiri2target(event: platform_events.Event) -> WecomEvent | None:
+        return getattr(event, 'source_platform_object', None)
+
+    @staticmethod
+    async def target2legacy(event: WecomEvent, bot: WecomClient | None = None) -> platform_events.FriendMessage | None:
+        eba_event = await WecomEventConverter.target2yiri(event, bot)
+        if hasattr(eba_event, 'to_legacy_event'):
+            return eba_event.to_legacy_event()
+        if event.type in {'text', 'image'} and eba_event is not None:
+            friend = platform_entities.Friend(
+                id=f'u{event.user_id}',
+                nickname=getattr(getattr(eba_event, 'sender', None), 'nickname', str(event.user_id or '')),
+                remark='',
+            )
+            return platform_events.FriendMessage(
+                sender=friend,
+                message_chain=eba_event.message_chain,
+                time=getattr(eba_event, 'timestamp', None),
+                source_platform_object=event,
+            )
+        return None
+
+    @staticmethod
+    async def target2yiri(event: WecomEvent, bot: WecomClient | None = None) -> platform_events.Event | None:
+        if event.type in {'text', 'image'}:
+            return await WecomEventConverter.message_to_eba(event, bot)
+        return WecomEventConverter.platform_specific(event, f'message.{event.detail_type or event.type or "unknown"}')
+
+    @staticmethod
+    async def message_to_eba(event: WecomEvent, bot: WecomClient | None = None) -> platform_events.MessageReceivedEvent:
+        if event.type == 'image':
+            message_chain = await WecomMessageConverter.target2yiri_image(event.picurl, event.message_id)
+        else:
+            message_chain = await WecomMessageConverter.target2yiri_text(event.message, event.message_id)
+
+        sender = await WecomEventConverter.user_from_event(event, bot)
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name=ADAPTER_NAME,
+            message_id=event.message_id or '',
+            message_chain=message_chain,
+            sender=sender,
+            chat_type=platform_entities.ChatType.PRIVATE,
+            chat_id=make_private_chat_id(event.user_id, event.agent_id),
+            group=None,
+            timestamp=float(event.timestamp or 0),
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    async def user_from_event(event: WecomEvent, bot: WecomClient | None = None) -> platform_entities.User:
+        nickname = str(event.user_id or '')
+        raw: dict[str, typing.Any] = {}
+        if bot and event.user_id:
+            try:
+                raw = await bot.get_user_info(event.user_id)
+                nickname = raw.get('name') or nickname
+            except Exception:
+                raw = {}
+
+        return platform_entities.User(
+            id=event.user_id or '',
+            nickname=nickname,
+            username=raw.get('alias') or raw.get('userid') or None,
+        )
+
+    @staticmethod
+    def platform_specific(event: WecomEvent, action: str) -> platform_events.PlatformSpecificEvent:
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            adapter_name=ADAPTER_NAME,
+            action=action,
+            data=dict(event),
+            timestamp=float(event.timestamp or 0),
+            source_platform_object=event,
+        )

src/langbot/pkg/platform/adapters/wecom/manifest.yaml

@@ -0,0 +1,117 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: wecom-eba
+  label:
+    en_US: WeCom (EBA)
+    zh_Hans: 企业微信 (EBA)
+    zh_Hant: 企業微信 (EBA)
+  description:
+    en_US: WeCom application message adapter (EBA architecture)
+    zh_Hans: 企业微信内部应用消息适配器（EBA 架构版本）
+    zh_Hant: 企業微信內部應用訊息適配器（EBA 架構版本）
+  icon: wecom.png
+
+spec:
+  categories:
+    - popular
+    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/wecom
+    en: https://link.langbot.app/en/platforms/wecom
+    ja: https://link.langbot.app/ja/platforms/wecom
+  config:
+    - name: webhook_url
+      label:
+        en_US: Webhook Callback URL
+        zh_Hans: Webhook 回调地址
+        zh_Hant: Webhook 回調地址
+      description:
+        en_US: Copy this URL and paste it into your WeCom app's webhook configuration
+        zh_Hans: 复制此地址并粘贴到企业微信应用的 Webhook 配置中
+        zh_Hant: 複製此地址並貼到企業微信應用的 Webhook 設定中
+      type: webhook-url
+      required: false
+      default: ""
+    - name: corpid
+      label:
+        en_US: Corpid
+        zh_Hans: 企业ID
+        zh_Hant: 企業ID
+      type: string
+      required: true
+      default: ""
+    - name: secret
+      label:
+        en_US: Secret
+        zh_Hans: 密钥 (Secret)
+        zh_Hant: 密鑰 (Secret)
+      type: string
+      required: true
+      default: ""
+    - name: token
+      label:
+        en_US: Token
+        zh_Hans: 令牌 (Token)
+        zh_Hant: 令牌 (Token)
+      type: string
+      required: true
+      default: ""
+    - name: EncodingAESKey
+      label:
+        en_US: EncodingAESKey
+        zh_Hans: 消息加解密密钥 (EncodingAESKey)
+        zh_Hant: 訊息加解密密鑰 (EncodingAESKey)
+      type: string
+      required: true
+      default: ""
+    - name: contacts_secret
+      label:
+        en_US: Contacts Secret
+        zh_Hans: 通讯录密钥
+        zh_Hant: 通訊錄密鑰
+      type: string
+      required: false
+      default: ""
+    - name: api_base_url
+      label:
+        en_US: API Base URL
+        zh_Hans: API 基础 URL
+        zh_Hant: API 基礎 URL
+      description:
+        en_US: Optional WeCom API base URL for private network or reverse proxy deployments.
+        zh_Hans: 可选，若部署在内网环境并通过反向代理访问企业微信 API，可根据文档填写此项
+        zh_Hant: 可選，若部署在內網環境並透過反向代理存取企業微信 API，可根據文件填寫此項
+      type: string
+      required: false
+      default: "https://qyapi.weixin.qq.com/cgi-bin"
+
+  supported_events:
+    - message.received
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - get_message
+      - get_user_info
+      - get_friend_list
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: check_access_token
+      description: { en_US: "Check whether the current WeCom access token is usable", zh_Hans: "检查当前企业微信 access token 是否可用" }
+    - action: refresh_access_token
+      description: { en_US: "Refresh the WeCom access token", zh_Hans: "刷新企业微信 access token" }
+    - action: get_user_info
+      description: { en_US: "Get WeCom user information by user ID", zh_Hans: "按用户 ID 获取企业微信用户信息" }
+    - action: send_to_all
+      description: { en_US: "Send an application text message to all contacts available to the configured contacts secret", zh_Hans: "使用配置的通讯录密钥向可见成员群发应用文本消息" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: WecomAdapter

src/langbot/pkg/platform/adapters/wecom/message_converter.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import datetime
+
+from langbot.libs.wecom_api.api import WecomClient
+from langbot.pkg.utils import image
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+def split_string_by_bytes(text: str, limit: int = 2048, encoding: str = 'utf-8') -> list[str]:
+    """Split text without cutting a multi-byte character in half."""
+    bytes_data = text.encode(encoding)
+    total_len = len(bytes_data)
+    parts: list[str] = []
+    start = 0
+
+    while start < total_len:
+        end = min(start + limit, total_len)
+        chunk = bytes_data[start:end]
+        part = chunk.decode(encoding, errors='ignore')
+        part_len = len(part.encode(encoding))
+        if part_len == 0 and end < total_len:
+            start += 1
+            continue
+        parts.append(part)
+        start += part_len
+
+    return parts
+
+
+class WecomMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    async def yiri2target(message_chain: platform_message.MessageChain, bot: WecomClient) -> list[dict]:
+        content_list: list[dict] = []
+
+        for msg in message_chain:
+            if isinstance(msg, platform_message.Source):
+                continue
+            if isinstance(msg, platform_message.Plain):
+                content_list.extend({'type': 'text', 'content': chunk} for chunk in split_string_by_bytes(msg.text))
+            elif isinstance(msg, platform_message.Image):
+                content_list.append({'type': 'image', 'media_id': await bot.get_media_id(msg)})
+            elif isinstance(msg, platform_message.Voice):
+                content_list.append({'type': 'voice', 'media_id': await bot.get_media_id(msg)})
+            elif isinstance(msg, platform_message.File):
+                content_list.append({'type': 'file', 'media_id': await bot.get_media_id(msg)})
+            elif isinstance(msg, platform_message.Forward):
+                for node in msg.node_list:
+                    content_list.extend(await WecomMessageConverter.yiri2target(node.message_chain, bot))
+            elif isinstance(msg, platform_message.Quote):
+                if msg.id is not None:
+                    content_list.append({'type': 'text', 'content': f'[Quote {msg.id}] '})
+                if msg.origin:
+                    content_list.extend(await WecomMessageConverter.yiri2target(msg.origin, bot))
+            elif isinstance(msg, platform_message.At):
+                content_list.append({'type': 'text', 'content': f'@{msg.display or msg.target}'})
+            elif isinstance(msg, platform_message.AtAll):
+                content_list.append({'type': 'text', 'content': '@all'})
+            else:
+                content_list.append({'type': 'text', 'content': str(msg)})
+
+        return content_list
+
+    @staticmethod
+    async def target2yiri_text(message: str | None, message_id: int | str | None = -1) -> platform_message.MessageChain:
+        return platform_message.MessageChain(
+            [
+                platform_message.Source(id=message_id, time=datetime.datetime.now()),
+                platform_message.Plain(text=message or ''),
+            ]
+        )
+
+    @staticmethod
+    async def target2yiri_image(picurl: str, message_id: int | str | None = -1) -> platform_message.MessageChain:
+        image_base64, image_format = await image.get_wecom_image_base64(pic_url=picurl)
+        return platform_message.MessageChain(
+            [
+                platform_message.Source(id=message_id, time=datetime.datetime.now()),
+                platform_message.Image(base64=f'data:image/{image_format};base64,{image_base64}'),
+            ]
+        )

src/langbot/pkg/platform/adapters/wecom/platform_api.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import typing
+
+from langbot.libs.wecom_api.api import WecomClient
+
+
+async def check_access_token(bot: WecomClient, params: dict) -> dict:
+    return {'valid': await bot.check_access_token()}
+
+
+async def refresh_access_token(bot: WecomClient, params: dict) -> dict:
+    bot.access_token = await bot.get_access_token(bot.secret)
+    return {'ok': bool(bot.access_token)}
+
+
+async def get_user_info(bot: WecomClient, params: dict) -> dict:
+    user_id = params.get('user_id') or params.get('userid')
+    if not user_id:
+        raise ValueError('user_id is required')
+    return await bot.get_user_info(str(user_id))
+
+
+async def send_to_all(bot: WecomClient, params: dict) -> dict:
+    content = params.get('content')
+    agent_id = params.get('agent_id') or params.get('agentid')
+    if not content:
+        raise ValueError('content is required')
+    if agent_id is None:
+        raise ValueError('agent_id is required')
+    await bot.send_to_all(str(content), int(agent_id))
+    return {'ok': True}
+
+
+PLATFORM_API_MAP: dict[str, typing.Callable[[WecomClient, dict], typing.Awaitable[dict]]] = {
+    'check_access_token': check_access_token,
+    'refresh_access_token': refresh_access_token,
+    'get_user_info': get_user_info,
+    'send_to_all': send_to_all,
+}

src/langbot/pkg/platform/adapters/wecom/types.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+ADAPTER_NAME = 'wecom-eba'
+
+
+def make_private_chat_id(user_id: str | int | None, agent_id: str | int | None) -> str:
+    """Build the routable private chat id used by the WeCom EBA adapter."""
+    user = str(user_id or '')
+    agent = str(agent_id or '')
+    if not user or not agent:
+        return user
+    return f'{user}|{agent}'

src/langbot/pkg/platform/adapters/wecombot/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

src/langbot/pkg/platform/adapters/wecombot/adapter.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import traceback
+import typing
+
+import pydantic
+
+from langbot.libs.wecom_ai_bot_api.api import WecomBotClient
+from langbot.libs.wecom_ai_bot_api.wecombotevent import WecomBotEvent
+from langbot.libs.wecom_ai_bot_api.ws_client import WecomBotWsClient
+from langbot.pkg.platform.adapters.wecombot.api_impl import WecomBotAPIMixin
+from langbot.pkg.platform.adapters.wecombot.event_converter import WecomBotEventConverter
+from langbot.pkg.platform.adapters.wecombot.message_converter import WecomBotMessageConverter
+from langbot.pkg.platform.adapters.wecombot.platform_api import PLATFORM_API_MAP
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class WecomBotAdapter(WecomBotAPIMixin, abstract_platform_adapter.AbstractPlatformAdapter):
+    bot: typing.Any = pydantic.Field(exclude=True)
+
+    message_converter: WecomBotMessageConverter = WecomBotMessageConverter()
+    event_converter: WecomBotEventConverter
+
+    config: dict
+    bot_uuid: str | None = None
+    bot_name: str = ''
+    listeners: dict[
+        typing.Type[platform_events.Event],
+        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
+    ] = {}
+    _message_cache: dict[str, platform_events.MessageReceivedEvent] = {}
+    _user_cache: dict[str, platform_entities.User] = {}
+    _group_cache: dict[str, platform_entities.UserGroup] = {}
+    _member_cache: dict[tuple[str, str], platform_entities.UserGroupMember] = {}
+    _stream_to_monitoring_msg: dict[str, tuple[str, float]] = {}
+    _STREAM_MAPPING_TTL: int = 600
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        enable_webhook = config.get('enable-webhook', False)
+        bot_name = config.get('robot_name', '')
+        if not enable_webhook:
+            required_keys = ['BotId', 'Secret']
+            missing_keys = [key for key in required_keys if not config.get(key)]
+            if missing_keys:
+                raise Exception(f'WeComBot WebSocket mode missing config: {missing_keys}')
+            bot = WecomBotWsClient(
+                bot_id=config['BotId'],
+                secret=config['Secret'],
+                logger=logger,
+                encoding_aes_key=config.get('EncodingAESKey', ''),
+            )
+        else:
+            required_keys = ['Token', 'EncodingAESKey', 'Corpid']
+            missing_keys = [key for key in required_keys if not config.get(key)]
+            if missing_keys:
+                raise Exception(f'WeComBot webhook mode missing config: {missing_keys}')
+            bot = WecomBotClient(
+                Token=config['Token'],
+                EnCodingAESKey=config['EncodingAESKey'],
+                Corpid=config['Corpid'],
+                logger=logger,
+                unified_mode=True,
+            )
+
+        super().__init__(
+            config=config,
+            logger=logger,
+            bot=bot,
+            bot_account_id=config.get('BotId', ''),
+            bot_uuid=None,
+            bot_name=bot_name,
+            event_converter=WecomBotEventConverter(bot_name=bot_name),
+            listeners={},
+            _message_cache={},
+            _user_cache={},
+            _group_cache={},
+            _member_cache={},
+            _stream_to_monitoring_msg={},
+        )
+        self._register_native_handlers()
+
+    def set_bot_uuid(self, bot_uuid: str):
+        self.bot_uuid = bot_uuid
+
+    def get_supported_events(self) -> list[str]:
+        return [
+            'message.received',
+            'feedback.received',
+            'platform.specific',
+        ]
+
+    def get_supported_apis(self) -> list[str]:
+        return [
+            'send_message',
+            'reply_message',
+            'get_message',
+            'get_user_info',
+            'get_friend_list',
+            'get_group_info',
+            'get_group_member_info',
+            'get_group_member_list',
+            'call_platform_api',
+        ]
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ) -> platform_events.MessageResult:
+        if self.config.get('enable-webhook', False):
+            raise NotSupportedError('send_message:webhook_mode')
+        if target_type not in ('person', 'private', 'group'):
+            raise NotSupportedError(f'send_message:{target_type}')
+        content = await WecomBotMessageConverter.yiri2target(message)
+        raw = await self.bot.send_message(str(target_id), content)
+        return platform_events.MessageResult(raw={'result': raw})
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ) -> platform_events.MessageResult:
+        event = await WecomBotEventConverter.yiri2target(message_source)
+        if not isinstance(event, WecomBotEvent):
+            raise ValueError('WeComBot reply_message requires a WecomBotEvent source object')
+        content = await WecomBotMessageConverter.yiri2target(message)
+        if not self.config.get('enable-webhook', False) and event.get('req_id'):
+            raw = await self.bot.reply_text(event.get('req_id'), content)
+        else:
+            raw = await self.bot.set_message(event.message_id, content)
+        return platform_events.MessageResult(message_id=event.message_id, raw={'result': raw})
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ) -> dict:
+        event = await WecomBotEventConverter.yiri2target(message_source)
+        if not isinstance(event, WecomBotEvent):
+            raise ValueError('WeComBot reply_message_chunk requires a WecomBotEvent source object')
+        content = await WecomBotMessageConverter.yiri2target(message)
+        success = await self.bot.push_stream_chunk(event.message_id, content, is_final=is_final)
+        if not success and is_final and not self.config.get('enable-webhook', False) and event.get('req_id'):
+            await self.bot.reply_text(event.get('req_id'), content)
+        return {'stream': success}
+
+    async def is_stream_output_supported(self) -> bool:
+        return self.config.get('enable-stream-reply', True)
+
+    async def call_platform_api(self, action: str, params: dict = {}) -> dict:
+        handler = PLATFORM_API_MAP.get(action)
+        if handler is None:
+            raise NotSupportedError(f'call_platform_api:{action}')
+        return await handler(self.bot, params)
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        registered = self.listeners.get(event_type)
+        if registered is callback:
+            self.listeners.pop(event_type, None)
+
+    async def handle_unified_webhook(self, bot_uuid: str, path: str, request):
+        if not self.config.get('enable-webhook', False):
+            return None
+        return await self.bot.handle_unified_webhook(request)
+
+    async def run_async(self):
+        if not self.config.get('enable-webhook', False):
+            await self.bot.connect()
+            return
+
+        async def keep_alive():
+            while True:
+                await asyncio.sleep(1)
+
+        await self.logger.info('WeComBot EBA adapter running in unified webhook mode')
+        await keep_alive()
+
+    async def kill(self) -> bool:
+        if not self.config.get('enable-webhook', False):
+            await self.bot.disconnect()
+        return True
+
+    async def is_muted(self, group_id: int | None = None) -> bool:
+        return False
+
+    async def on_monitoring_message_created(self, query, monitoring_message_id: str):
+        try:
+            stream_id = query.message_event.source_platform_object.stream_id
+            if stream_id:
+                self._stream_to_monitoring_msg[stream_id] = (monitoring_message_id, time.time())
+                self._cleanup_stream_mapping()
+        except Exception as e:
+            await self.logger.debug(f'Failed to map stream_id to monitoring message: {e}')
+
+    def _register_native_handlers(self):
+        self.bot.on_message('single')(self._handle_native_event)
+        self.bot.on_message('group')(self._handle_native_event)
+        if hasattr(self.bot, 'on_feedback'):
+            self.bot.on_feedback()(self._handle_feedback)
+        if hasattr(self.bot, 'on_message'):
+            self.bot.on_message('event')(self._handle_native_event)
+
+    async def _handle_native_event(self, event: WecomBotEvent):
+        try:
+            if platform_events.FriendMessage in self.listeners or platform_events.GroupMessage in self.listeners:
+                legacy_event = await self.event_converter.target2legacy(event)
+                if legacy_event and type(legacy_event) in self.listeners:
+                    await self.listeners[type(legacy_event)](legacy_event, self)
+
+            eba_event = await self.event_converter.target2yiri(event)
+            if eba_event:
+                self._cache_event(eba_event)
+                await self._dispatch_eba_event(eba_event)
+        except Exception:
+            await self.logger.error(f'Error in wecombot native event: {traceback.format_exc()}')
+
+    async def _handle_feedback(self, **kwargs):
+        try:
+            event = WecomBotEventConverter.feedback_to_eba(**kwargs)
+            if event.stream_id and event.stream_id in self._stream_to_monitoring_msg:
+                monitoring_msg_id, _ = self._stream_to_monitoring_msg[event.stream_id]
+                event.stream_id = monitoring_msg_id
+            await self._dispatch_eba_event(event)
+        except Exception:
+            await self.logger.error(f'Error in wecombot feedback event: {traceback.format_exc()}')
+
+    async def _dispatch_eba_event(self, event: platform_events.EBAEvent):
+        for event_type in (type(event), platform_events.EBAEvent, platform_events.Event):
+            callback = self.listeners.get(event_type)
+            if callback:
+                await callback(event, self)
+                return
+
+    def _cache_event(self, event: platform_events.Event):
+        if not isinstance(event, platform_events.MessageReceivedEvent):
+            return
+        self._message_cache[str(event.message_id)] = event
+        self._user_cache[str(event.sender.id)] = event.sender
+        if event.group:
+            self._group_cache[str(event.group.id)] = event.group
+            self._member_cache[(str(event.group.id), str(event.sender.id))] = platform_entities.UserGroupMember(
+                user=event.sender,
+                group_id=event.group.id,
+                role=platform_entities.MemberRole.MEMBER,
+                display_name=event.sender.nickname,
+            )
+
+    def _cleanup_stream_mapping(self):
+        now = time.time()
+        expired = [key for key, (_, ts) in self._stream_to_monitoring_msg.items() if now - ts > self._STREAM_MAPPING_TTL]
+        for key in expired:
+            del self._stream_to_monitoring_msg[key]

src/langbot/pkg/platform/adapters/wecombot/api_impl.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import typing
+
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.platform.errors import NotSupportedError
+
+
+class WecomBotAPIMixin:
+    _message_cache: dict[str, platform_events.MessageReceivedEvent]
+    _user_cache: dict[str, platform_entities.User]
+    _group_cache: dict[str, platform_entities.UserGroup]
+    _member_cache: dict[tuple[str, str], platform_entities.UserGroupMember]
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> platform_events.MessageReceivedEvent:
+        event = self._message_cache.get(str(message_id))
+        if event is None:
+            raise NotSupportedError('get_message:message_not_cached')
+        return event
+
+    async def get_user_info(self, user_id: typing.Union[int, str]) -> platform_entities.User:
+        cached = self._user_cache.get(str(user_id))
+        if cached is None:
+            raise NotSupportedError('get_user_info:not_cached')
+        return cached
+
+    async def get_friend_list(self) -> list[platform_entities.User]:
+        return list(self._user_cache.values())
+
+    async def get_group_info(self, group_id: typing.Union[int, str]) -> platform_entities.UserGroup:
+        cached = self._group_cache.get(str(group_id))
+        if cached is None:
+            raise NotSupportedError('get_group_info:not_cached')
+        return cached
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> platform_entities.UserGroupMember:
+        cached = self._member_cache.get((str(group_id), str(user_id)))
+        if cached is None:
+            raise NotSupportedError('get_group_member_info:not_cached')
+        return cached
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[platform_entities.UserGroupMember]:
+        return [member for (cached_group_id, _), member in self._member_cache.items() if cached_group_id == str(group_id)]
+
+    async def upload_file(self, file_data: bytes, filename: str) -> str:
+        raise NotSupportedError('upload_file')
+
+    async def get_file_url(self, file_id: str) -> str:
+        raise NotSupportedError('get_file_url')
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: platform_message.MessageChain,
+    ) -> None:
+        raise NotSupportedError('edit_message')
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        raise NotSupportedError('delete_message')
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> platform_events.MessageResult:
+        raise NotSupportedError('forward_message')
+
+    async def mute_member(self, group_id: typing.Union[int, str], user_id: typing.Union[int, str], duration: int = 0):
+        raise NotSupportedError('mute_member')
+
+    async def unmute_member(self, group_id: typing.Union[int, str], user_id: typing.Union[int, str]):
+        raise NotSupportedError('unmute_member')
+
+    async def kick_member(self, group_id: typing.Union[int, str], user_id: typing.Union[int, str]):
+        raise NotSupportedError('kick_member')
+
+    async def leave_group(self, group_id: typing.Union[int, str]):
+        raise NotSupportedError('leave_group')

src/langbot/pkg/platform/adapters/wecombot/event_converter.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import time
+import typing
+
+from langbot.libs.wecom_ai_bot_api.wecombotevent import WecomBotEvent
+from langbot.pkg.platform.adapters.wecombot.message_converter import WecomBotMessageConverter
+from langbot.pkg.platform.adapters.wecombot.types import ADAPTER_NAME
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot_plugin.api.entities.builtin.platform import entities as platform_entities
+from langbot_plugin.api.entities.builtin.platform import events as platform_events
+
+
+class WecomBotEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    def __init__(self, bot_name: str = ''):
+        self.bot_name = bot_name
+
+    @staticmethod
+    async def yiri2target(event: platform_events.Event) -> typing.Any:
+        return getattr(event, 'source_platform_object', None)
+
+    async def target2legacy(self, event: WecomBotEvent) -> platform_events.FriendMessage | platform_events.GroupMessage | None:
+        eba_event = await self.target2yiri(event)
+        if not isinstance(eba_event, platform_events.MessageReceivedEvent):
+            return None
+        if eba_event.chat_type == platform_entities.ChatType.PRIVATE:
+            return platform_events.FriendMessage(
+                sender=platform_entities.Friend(id=eba_event.sender.id, nickname=eba_event.sender.nickname, remark=''),
+                message_chain=eba_event.message_chain,
+                time=eba_event.timestamp,
+                source_platform_object=event,
+            )
+        return platform_events.GroupMessage(
+            sender=platform_entities.GroupMember(
+                id=eba_event.sender.id,
+                permission='MEMBER',
+                member_name=eba_event.sender.nickname,
+                group=platform_entities.Group(
+                    id=eba_event.group.id if eba_event.group else eba_event.chat_id,
+                    name=eba_event.group.name if eba_event.group else '',
+                    permission=platform_entities.Permission.Member,
+                ),
+                special_title='',
+            ),
+            message_chain=eba_event.message_chain,
+            time=eba_event.timestamp,
+            source_platform_object=event,
+        )
+
+    async def target2yiri(self, event: WecomBotEvent) -> platform_events.Event:
+        if event.type in {'single', 'group'} and event.msgtype != 'event':
+            return await self.message_to_eba(event)
+        return self.platform_specific(event, f'wecombot.{event.get("eventtype") or event.msgtype or event.type or "unknown"}')
+
+    async def message_to_eba(self, event: WecomBotEvent) -> platform_events.MessageReceivedEvent:
+        sender = platform_entities.User(id=event.userid, nickname=event.username or event.userid)
+        group = None
+        chat_type = platform_entities.ChatType.PRIVATE
+        chat_id = event.userid
+        if event.type == 'group':
+            chat_type = platform_entities.ChatType.GROUP
+            chat_id = str(event.chatid)
+            group = platform_entities.UserGroup(id=str(event.chatid), name=event.chatname or str(event.chatid))
+
+        return platform_events.MessageReceivedEvent(
+            type='message.received',
+            adapter_name=ADAPTER_NAME,
+            message_id=event.message_id or '',
+            message_chain=await WecomBotMessageConverter.target2yiri(event, self.bot_name),
+            sender=sender,
+            chat_type=chat_type,
+            chat_id=chat_id or '',
+            group=group,
+            timestamp=time.time(),
+            source_platform_object=event,
+        )
+
+    @staticmethod
+    def feedback_to_eba(
+        *,
+        feedback_id: str,
+        feedback_type: int,
+        feedback_content: str | None = None,
+        inaccurate_reasons: list | None = None,
+        session=None,
+    ) -> platform_events.FeedbackReceivedEvent:
+        session_id = None
+        user_id = None
+        message_id = None
+        stream_id = None
+        if session:
+            if getattr(session, 'chat_id', None):
+                session_id = f'group_{session.chat_id}'
+            elif getattr(session, 'user_id', None):
+                session_id = f'person_{session.user_id}'
+            user_id = getattr(session, 'user_id', None)
+            message_id = getattr(session, 'msg_id', None)
+            stream_id = getattr(session, 'stream_id', None)
+
+        return platform_events.FeedbackReceivedEvent(
+            type='feedback.received',
+            adapter_name=ADAPTER_NAME,
+            feedback_id=feedback_id,
+            feedback_type=feedback_type,
+            feedback_content=feedback_content,
+            inaccurate_reasons=[str(reason) for reason in (inaccurate_reasons or [])] or None,
+            user_id=user_id,
+            session_id=session_id,
+            message_id=message_id,
+            stream_id=stream_id,
+            timestamp=time.time(),
+            source_platform_object=session,
+        )
+
+    @staticmethod
+    def platform_specific(event: WecomBotEvent, action: str) -> platform_events.PlatformSpecificEvent:
+        return platform_events.PlatformSpecificEvent(
+            type='platform.specific',
+            adapter_name=ADAPTER_NAME,
+            action=action,
+            data=dict(event),
+            timestamp=time.time(),
+            source_platform_object=event,
+        )

src/langbot/pkg/platform/adapters/wecombot/manifest.yaml

@@ -0,0 +1,158 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: wecombot-eba
+  label:
+    en_US: WeComBot (EBA)
+    zh_Hans: 企业微信智能机器人 (EBA)
+    zh_Hant: 企業微信智慧機器人 (EBA)
+  description:
+    en_US: WeCom AI Bot adapter with Event-Based Agents support
+    zh_Hans: 企业微信智能机器人适配器（EBA 架构版本），支持长连接和 Webhook 两种接入方式
+    zh_Hant: 企業微信智慧機器人適配器（EBA 架構版本），支援長連線和 Webhook 兩種接入方式
+  icon: wecombot.png
+
+spec:
+  categories:
+    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/wecombot
+    en: https://link.langbot.app/en/platforms/wecombot
+    ja: https://link.langbot.app/ja/platforms/wecombot
+  config:
+    - name: BotId
+      label:
+        en_US: BotId
+        zh_Hans: 机器人ID (BotId)
+        zh_Hant: 機器人ID (BotId)
+      type: string
+      required: true
+      default: ""
+    - name: robot_name
+      label:
+        en_US: Robot Name
+        zh_Hans: 机器人名称
+        zh_Hant: 機器人名稱
+      type: string
+      required: true
+      default: ""
+    - name: enable-webhook
+      label:
+        en_US: Enable Webhook Mode
+        zh_Hans: 启用 Webhook 模式
+        zh_Hant: 啟用 Webhook 模式
+      description:
+        en_US: If enabled, the bot will use webhook mode. Otherwise it uses WebSocket long connection mode and does not need a webhook URL.
+        zh_Hans: 如果启用，机器人将使用 Webhook 模式；否则使用 WebSocket 长连接模式，不需要配置 webhook URL。
+        zh_Hant: 如果啟用，機器人將使用 Webhook 模式；否則使用 WebSocket 長連線模式，不需要設定 webhook URL。
+      type: boolean
+      required: true
+      default: false
+    - name: webhook_url
+      label:
+        en_US: Webhook Callback URL
+        zh_Hans: Webhook 回调地址
+        zh_Hant: Webhook 回調地址
+      description:
+        en_US: Copy this URL into WeComBot callback settings only when webhook mode is enabled.
+        zh_Hans: 仅在启用 Webhook 模式时复制此地址到企业微信智能机器人回调配置中。
+        zh_Hant: 僅在啟用 Webhook 模式時複製此地址到企業微信智慧機器人回調設定中。
+      type: webhook-url
+      required: false
+      default: ""
+      show_if:
+        field: enable-webhook
+        operator: eq
+        value: true
+    - name: Secret
+      label:
+        en_US: Secret
+        zh_Hans: 机器人密钥 (Secret)
+        zh_Hant: 機器人密鑰 (Secret)
+      description:
+        en_US: Required for WebSocket long connection mode.
+        zh_Hans: 使用 WebSocket 长连接模式时必填。
+        zh_Hant: 使用 WebSocket 長連線模式時必填。
+      type: string
+      required: false
+      default: ""
+    - name: Corpid
+      label:
+        en_US: Corpid
+        zh_Hans: 企业ID
+        zh_Hant: 企業ID
+      description:
+        en_US: Required for webhook mode.
+        zh_Hans: 使用 Webhook 模式时必填。
+        zh_Hant: 使用 Webhook 模式時必填。
+      type: string
+      required: false
+      default: ""
+    - name: Token
+      label:
+        en_US: Token
+        zh_Hans: 令牌 (Token)
+        zh_Hant: 令牌 (Token)
+      description:
+        en_US: Required for webhook mode.
+        zh_Hans: 使用 Webhook 模式时必填。
+        zh_Hant: 使用 Webhook 模式時必填。
+      type: string
+      required: false
+      default: ""
+    - name: EncodingAESKey
+      label:
+        en_US: EncodingAESKey
+        zh_Hans: 消息加解密密钥 (EncodingAESKey)
+        zh_Hant: 訊息加解密密鑰 (EncodingAESKey)
+      description:
+        en_US: Required for webhook mode. Optional for WebSocket mode when encrypted files need to be decrypted.
+        zh_Hans: Webhook 模式必填。WebSocket 模式下如需解密文件则填写。
+        zh_Hant: Webhook 模式必填。WebSocket 模式下如需解密檔案則填寫。
+      type: string
+      required: false
+      default: ""
+    - name: enable-stream-reply
+      label:
+        en_US: Enable Stream Reply
+        zh_Hans: 启用流式回复
+        zh_Hant: 啟用串流回覆
+      description:
+        en_US: If enabled, the bot will use WeComBot streaming replies.
+        zh_Hans: 如果启用，机器人将使用企业微信智能机器人流式回复。
+        zh_Hant: 如果啟用，機器人將使用企業微信智慧機器人串流回覆。
+      type: boolean
+      required: false
+      default: true
+
+  supported_events:
+    - message.received
+    - feedback.received
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - get_message
+      - get_user_info
+      - get_friend_list
+      - get_group_info
+      - get_group_member_info
+      - get_group_member_list
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: is_websocket_mode
+      description: { en_US: "Return whether the adapter is using WebSocket long connection mode", zh_Hans: "返回当前适配器是否使用 WebSocket 长连接模式" }
+    - action: get_stream_session_status
+      description: { en_US: "Inspect stream session state for a received message ID", zh_Hans: "按接收消息 ID 查看流式会话状态" }
+    - action: send_markdown
+      description: { en_US: "Send markdown text proactively in WebSocket mode", zh_Hans: "在 WebSocket 模式下主动发送 Markdown 文本" }
+
+execution:
+  python:
+    path: ./adapter.py
+    attr: WecomBotAdapter

src/langbot/pkg/platform/adapters/wecombot/message_converter.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import datetime
+
+from langbot.libs.wecom_ai_bot_api.wecombotevent import WecomBotEvent
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+
+
+class WecomBotMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    async def yiri2target(message_chain: platform_message.MessageChain) -> str:
+        content_parts: list[str] = []
+        for msg in message_chain:
+            if isinstance(msg, platform_message.Source):
+                continue
+            if isinstance(msg, platform_message.Plain):
+                content_parts.append(msg.text)
+            elif isinstance(msg, platform_message.At):
+                content_parts.append(f'@{msg.display or msg.target}')
+            elif isinstance(msg, platform_message.AtAll):
+                content_parts.append('@all')
+            elif isinstance(msg, platform_message.Image):
+                content_parts.append('[Image]')
+            elif isinstance(msg, platform_message.Voice):
+                content_parts.append('[Voice]')
+            elif isinstance(msg, platform_message.File):
+                content_parts.append(f'[File: {msg.name or msg.file_id or msg.url or "file"}]')
+            elif isinstance(msg, platform_message.Quote):
+                if msg.id is not None:
+                    content_parts.append(f'[Quote {msg.id}]')
+                if msg.origin:
+                    content_parts.append(await WecomBotMessageConverter.yiri2target(msg.origin))
+            elif isinstance(msg, platform_message.Forward):
+                for node in msg.node_list:
+                    if node.message_chain:
+                        content_parts.append(await WecomBotMessageConverter.yiri2target(node.message_chain))
+            else:
+                content_parts.append(str(msg))
+        return '\n'.join(part for part in content_parts if part)
+
+    @staticmethod
+    async def target2yiri(event: WecomBotEvent, bot_name: str = '') -> platform_message.MessageChain:
+        components: list[platform_message.MessageComponent] = [
+            platform_message.Source(id=event.message_id, time=datetime.datetime.now()),
+        ]
+        if event.type == 'group' and event.ai_bot_id:
+            components.append(platform_message.At(target=event.ai_bot_id))
+
+        if event.content:
+            content = event.content
+            if bot_name:
+                content = content.replace(f'@{bot_name}', '').strip()
+            if content:
+                components.append(platform_message.Plain(text=content))
+
+        WecomBotMessageConverter._append_images(components, event.images or ([event.picurl] if event.picurl else []))
+        WecomBotMessageConverter._append_file(components, event.file)
+        WecomBotMessageConverter._append_voice(components, event.voice)
+        WecomBotMessageConverter._append_video(components, event.video)
+        WecomBotMessageConverter._append_link(components, event.link)
+        WecomBotMessageConverter._append_quote(components, event.quote)
+
+        if not any(not isinstance(component, (platform_message.Source, platform_message.At)) for component in components):
+            components.append(platform_message.Unknown(text=f'[unsupported wecombot msgtype: {event.msgtype or "unknown"}]'))
+
+        return platform_message.MessageChain(components)
+
+    @staticmethod
+    def _append_images(components: list[platform_message.MessageComponent], images: list[str]):
+        for image_data in images:
+            if image_data:
+                components.append(platform_message.Image(base64=image_data))
+
+    @staticmethod
+    def _append_file(components: list[platform_message.MessageComponent], file_info: dict | None):
+        if not file_info:
+            return
+        file_url = file_info.get('download_url') or file_info.get('url') or file_info.get('fileurl') or file_info.get('path')
+        file_base64 = file_info.get('base64')
+        file_name = file_info.get('filename') or file_info.get('name')
+        file_size = file_info.get('filesize') or file_info.get('size')
+        try:
+            kwargs = {}
+            if file_url:
+                kwargs['url'] = file_url
+            if file_base64:
+                kwargs['base64'] = file_base64
+            if file_name:
+                kwargs['name'] = file_name
+            if file_size is not None:
+                kwargs['size'] = file_size
+            if kwargs:
+                components.append(platform_message.File(**kwargs))
+        except Exception:
+            components.append(platform_message.Unknown(text='[file message unsupported]'))
+
+    @staticmethod
+    def _append_voice(components: list[platform_message.MessageComponent], voice_info: dict | None):
+        if not voice_info:
+            return
+        voice_payload = voice_info.get('base64') or voice_info.get('url')
+        if not voice_payload:
+            return
+        if voice_info.get('base64') and not voice_payload.startswith('data:'):
+            voice_payload = f'data:audio/mpeg;base64,{voice_info.get("base64")}'
+        try:
+            if voice_payload.startswith('data:'):
+                components.append(platform_message.Voice(base64=voice_payload))
+            else:
+                components.append(platform_message.Voice(url=voice_payload))
+        except Exception:
+            components.append(platform_message.Unknown(text='[voice message unsupported]'))
+
+    @staticmethod
+    def _append_video(components: list[platform_message.MessageComponent], video_info: dict | None):
+        if not video_info:
+            return
+        video_payload = (
+            video_info.get('base64')
+            or video_info.get('url')
+            or video_info.get('download_url')
+            or video_info.get('fileurl')
+        )
+        if not video_payload:
+            return
+        try:
+            components.append(
+                platform_message.File(
+                    url=video_payload,
+                    name=video_info.get('filename') or video_info.get('name') or 'video',
+                    size=video_info.get('filesize') or video_info.get('size'),
+                )
+            )
+        except Exception:
+            components.append(platform_message.Unknown(text='[video message unsupported]'))
+
+    @staticmethod
+    def _append_link(components: list[platform_message.MessageComponent], link: dict | None, prefix: str = ''):
+        if not link:
+            return
+        summary = '\n'.join(
+            filter(None, [link.get('title', ''), link.get('description') or link.get('digest', ''), link.get('url', '')])
+        )
+        if summary:
+            components.append(platform_message.Plain(text=f'{prefix}{summary}'))
+
+    @staticmethod
+    def _append_quote(components: list[platform_message.MessageComponent], quote_info: dict | None):
+        if not quote_info:
+            return
+        origin: list[platform_message.MessageComponent] = []
+        if quote_info.get('content'):
+            origin.append(platform_message.Plain(text=quote_info.get('content')))
+        WecomBotMessageConverter._append_images(origin, quote_info.get('images') or ([quote_info.get('picurl')] if quote_info.get('picurl') else []))
+        WecomBotMessageConverter._append_file(origin, quote_info.get('file'))
+        WecomBotMessageConverter._append_voice(origin, quote_info.get('voice'))
+        WecomBotMessageConverter._append_video(origin, quote_info.get('video'))
+        WecomBotMessageConverter._append_link(origin, quote_info.get('link'))
+        if origin:
+            components.append(platform_message.Quote(origin=platform_message.MessageChain(origin)))