mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-11-02 05:45:20 +08:00
chore(merge): sync master into interactive cards
This commit is contained in:
fdc310
@@ -0,0 +1,200 @@
|
||||
# Event Based Agents 架构设计总览
|
||||
|
||||
> Product revision (2026-09-07): [Event processors and Pipeline plugin compatibility](./09-event-processors.md) defines an explicitly bound Runner alongside Pipeline and Agent. It supersedes the automatic EBA observer product model below; the new component and UI are planned, not yet implemented.
|
||||
|
||||
> 当前状态（2026-09-05）：平台事件、Bot `event_bindings`、独立 Agent、Pipeline / Agent 平级路由及 WebUI 已集成到 `dev/4.11.x`。实现入口为 `pkg/platform/botmgr.py::RuntimeBot` 与 `pkg/agent/runner/`。下文“当前架构的局限性”“现有架构”描述改造前背景；EventBus / EventRouter 图表示职责划分，不表示存在同名独立服务。当前实现和验收以 [STATUS.md](../agent-runner-pluginization/STATUS.md) 为准，平台动作使用[授权工具](../agent-runner-pluginization/PLATFORM_ACTION_TOOLS.md)。
|
||||
|
||||
## 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 (固定阶段链)
|
||||
│ │
|
||||
│ ▼
|
||||
│ Runner Host orchestrator
|
||||
│ ▼
|
||||
│ plugin Runner
|
||||
│
|
||||
▼
|
||||
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 (统一事件总线)
|
||||
│
|
||||
├─→ Plugin EventListener observers（始终广播，不参与响应仲裁）
|
||||
│
|
||||
▼
|
||||
EventRouter (读取 Bot 的 event_bindings)
|
||||
│
|
||||
├─→ Pipeline target — 完整 Stage 链，仅消息事件
|
||||
├─→ Agent target — 独立 Agent，经插件 Runner 执行
|
||||
└─→ discard — 明确丢弃
|
||||
│
|
||||
▼
|
||||
统一平台 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 事件响应目标与观察者
|
||||
|
||||
Pipeline 与 Agent 是长期并存、场景不同的同级处理器。Pipeline 保留完整 Stage 链，面向消息处理；Agent 是独立配置对象，选择一个已安装的插件 Runner，并可声明消息或非消息事件能力。Bot 的 `event_bindings` 只负责把事件绑定到既有 Pipeline、独立 Agent 或 `discard`。
|
||||
|
||||
插件 EventListener 是观察者：事件先广播给有权限的监听器，随后路由器再选择一个响应目标。Webhook、Dify、n8n 等外部执行方式若需要作为响应者，应由对应 Runner 插件表达，而不是增加另一套 Host Handler 主链。
|
||||
|
||||
现有 Pipeline 不会被转换为 Agent，Pipeline 内的 runner 配置也不会复制到独立 Agent。用户需要 Agent 时自行创建并绑定。
|
||||
|
||||
详见 [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_bindings`，目标引用原始 Pipeline 或独立 Agent UUID | 路由关系不复制处理器配置，Pipeline/Agent 各自保持事实源 |
|
||||
| 5 | Agent 处理器定位 | 独立 Agent + 插件 Runner | Host 不再内置具体 runner；不同 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) | 分阶段迁移计划 |
|
||||
| [07-agent-orchestration.md](./07-agent-orchestration.md) | **产品最终形态（2026-06 修订）**：Pipeline / Agent 同级处理器编排、SDK Agent 组件契约、发布火车 |
|
||||
|
||||
## 6. 涉及的代码仓库
|
||||
|
||||
| 仓库 | 改动范围 |
|
||||
|------|----------|
|
||||
| **langbot-plugin-sdk** | 事件定义、实体模型、API 接口、适配器基类、通信协议扩展 |
|
||||
| **LangBot**（后端） | 适配器实现、事件路由引擎、Bot/Agent 实体、Runner Host 编排 |
|
||||
| **LangBot**（前端） | Bot 事件处理器编排面板 |
|
||||
| **langbot-wiki** | 新架构文档、插件开发指南更新、适配器开发指南 |
|
||||
| **LangBot/plugins** | 示例更新（使用新事件和 API，插件保持独立发布） |
|
||||
@@ -0,0 +1,562 @@
|
||||
# 统一事件体系
|
||||
|
||||
## 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. EventBus 向有权限的 Plugin EventListener 广播观察者事件
|
||||
│ observer 不占用响应目标，也不参与 priority 仲裁
|
||||
│
|
||||
7. EventRouter 查询 Bot 的 event_bindings
|
||||
│ 精确/通配匹配 event_pattern，应用 filters 与 priority
|
||||
│ 选择一个 Pipeline、Agent 或 discard 目标
|
||||
│
|
||||
8. 目标处理事件
|
||||
│ Pipeline → 进入完整 Pipeline 流水线（仅消息事件）
|
||||
│ Agent → Host 编排已安装的插件 Runner
|
||||
│ discard → 不产生响应
|
||||
│
|
||||
9. 处理器执行完毕，可能通过 Host 授权 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. 文档自动生成
|
||||
@@ -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` 承载。
|
||||
@@ -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/ # 新路径（已迁移的适配器）
|
||||
```
|
||||
@@ -0,0 +1,175 @@
|
||||
# 事件路由与编排
|
||||
|
||||
> Implementation update (2026-09-08): the EventListener observer-broadcast proposal below is superseded by [Event processors](09-event-processors.md). Legacy EventListener hooks run only inside Pipeline. New EBA handlers use explicitly created and bound Runner instances, a third peer processor type alongside Agent and Pipeline.
|
||||
|
||||
> 状态：当前实施模型（2026-07-12）。本文以 Pipeline / Agent 平级并存为准，不再保留早期 `pipeline / agent / webhook / plugin` 四种 Handler 草案。
|
||||
|
||||
## 1. 路由边界
|
||||
|
||||
EBA 将事件处理拆成两个互不替代的阶段：
|
||||
|
||||
1. **观察者广播**：EventBus 把事件广播给有权限的插件 EventListener。观察者可记录、同步或执行受控副作用，但不占用响应目标。
|
||||
2. **响应者仲裁**：EventRouter 按 Bot 的 `event_bindings` 选择一个 Pipeline、独立 Agent 或 `discard`。
|
||||
|
||||
Pipeline 与 Agent 是平级处理器：
|
||||
|
||||
| 处理器 | 配置事实源 | 执行路径 | 事件范围 |
|
||||
| --- | --- | --- | --- |
|
||||
| Pipeline | Pipeline 表与完整 Stage 配置 | MessageAggregator -> QueryPool -> RuntimePipeline | 消息事件，首版为 `message.received` |
|
||||
| Agent | Agent 表中的 runner 与 runner config | Runner Host orchestrator -> plugin Runner | Agent/Runner 声明支持的消息或非消息事件 |
|
||||
| discard | 无处理器配置 | 明确结束路由 | 任意事件 |
|
||||
|
||||
插件 EventListener 不是第三种响应目标。Webhook、Dify、n8n、Coze 等外部系统需要响应事件时，由对应 Runner 插件承接。
|
||||
|
||||
## 2. 数据模型
|
||||
|
||||
### 2.1 独立 Agent
|
||||
|
||||
Agent 保存自己的 Runner 选择与配置，不嵌入 Pipeline，也不复制 Pipeline 的 AI stage：
|
||||
|
||||
```python
|
||||
class Agent(Base):
|
||||
uuid: str
|
||||
name: str
|
||||
description: str
|
||||
emoji: str
|
||||
kind: str # 固定为 "agent"
|
||||
component_ref: str # Runner id
|
||||
config: dict # runner + runner_config
|
||||
supported_event_patterns: list[str]
|
||||
```
|
||||
|
||||
当前配置形状：
|
||||
|
||||
```json
|
||||
{
|
||||
"runner": {
|
||||
"id": "plugin:langbot-team/LocalAgent/default"
|
||||
},
|
||||
"runner_config": {
|
||||
"plugin:langbot-team/LocalAgent/default": {
|
||||
"model": {
|
||||
"primary": "model-uuid",
|
||||
"fallbacks": []
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Runner id 来自已安装插件的 Runner manifest。Host 不维护 LocalAgent、Dify 或其他具体实现的内置分支。
|
||||
|
||||
### 2.2 EventBinding
|
||||
|
||||
Bot 维护事件到处理器的引用：
|
||||
|
||||
```python
|
||||
class EventBinding(BaseModel):
|
||||
id: str
|
||||
event_pattern: str # 精确、namespace.* 或 *
|
||||
target_type: str # agent | pipeline | discard
|
||||
target_uuid: str | None # Agent/Pipeline 原始 UUID
|
||||
filters: list[dict]
|
||||
priority: int
|
||||
enabled: bool
|
||||
description: str
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "binding-message",
|
||||
"event_pattern": "message.received",
|
||||
"target_type": "pipeline",
|
||||
"target_uuid": "pipeline-uuid",
|
||||
"filters": [],
|
||||
"priority": 100,
|
||||
"enabled": true
|
||||
},
|
||||
{
|
||||
"id": "binding-member-joined",
|
||||
"event_pattern": "group.member_joined",
|
||||
"target_type": "agent",
|
||||
"target_uuid": "agent-uuid",
|
||||
"filters": [],
|
||||
"priority": 50,
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Binding 只保存引用与路由条件。它不复制 Pipeline 或 Agent 配置。
|
||||
|
||||
## 3. 匹配与仲裁
|
||||
|
||||
事件模式支持：
|
||||
|
||||
- 精确匹配：`group.member_joined`
|
||||
- 命名空间通配：`group.*`
|
||||
- 全局通配：`*`
|
||||
|
||||
路由按以下顺序处理：
|
||||
|
||||
1. 忽略 `enabled = false` 的 binding。
|
||||
2. 检查 `event_pattern` 与结构化 filters。
|
||||
3. 校验目标存在且声明支持该事件。
|
||||
4. 按 `priority` 从高到低选择；同优先级按稳定列表顺序。
|
||||
5. 只执行一个响应目标。
|
||||
|
||||
Pipeline 目标只能匹配消息事件。非消息事件不得伪装成用户文本塞进 Pipeline。
|
||||
|
||||
## 4. 执行流程
|
||||
|
||||
```text
|
||||
Platform adapter
|
||||
-> normalized event
|
||||
-> EventBus
|
||||
-> authorized Plugin EventListener observers
|
||||
-> EventRouter
|
||||
-> Pipeline target -> full Pipeline stage chain
|
||||
-> Agent target -> Runner Host orchestrator
|
||||
-> discard -> stop
|
||||
-> Host delivery/platform API
|
||||
```
|
||||
|
||||
### 4.1 Pipeline target
|
||||
|
||||
消息事件按原有方式构造 Query，经 MessageAggregator、QueryPool 和完整 Pipeline Stage 链执行。Pipeline 可以继续使用 Runner 作为 AI stage 的实现，但 Pipeline 本身不会因此变成 Agent。
|
||||
|
||||
### 4.2 Agent target
|
||||
|
||||
Host 读取独立 Agent 的 Runner id/config，构造 event-first context、run-scoped resources 与 delivery policy，再调用插件 Runner。Runner 输出由 Host 统一归一化、记录和投递。
|
||||
|
||||
Runner 可通过 SDK/Python `RunnerAPIProxy.call_tool` 或 SDK-owned scoped MCP bridge 回调 Host 能力。两条路径都映射到 `PluginToRuntimeAction.CALL_TOOL`，使用相同的 run authorization、Host execution Query、ToolManager 和 Box session 规则。Box session 是 Host canonical scope 的固定长度安全哈希；同一平台会话稳定、不同 scope 隔离、缺少 identity 时 fail closed，Runner 不配置 sandbox scope。
|
||||
|
||||
### 4.3 Observer side effects
|
||||
|
||||
观察者与响应者可以同时工作。为避免编辑、reaction 等合成事件重复触发不可逆操作，Host 应按事件能力和授权过滤观察者可用 API，并记录副作用结果。Observer 广播不作为 fallback 响应。
|
||||
|
||||
## 5. Pipeline 与 Agent 的并存规则
|
||||
|
||||
1. Pipeline 与 Agent 保留各自的持久化、编辑和执行语义。
|
||||
2. 处理器聚合页面可以统一展示二者，但不会创建第三份处理器记录。
|
||||
3. 旧 Pipeline 仍是 Pipeline；其 runner config 不迁移、不复制为独立 Agent。
|
||||
4. 需要 Agent 的用户新建 Agent、选择已安装 Runner，再建立 event binding。
|
||||
5. 一个 Bot 可按不同事件同时绑定 Pipeline 与 Agent。
|
||||
|
||||
## 6. WebUI 约束
|
||||
|
||||
处理器入口展示带类型标识的 Agent 与 Pipeline。Bot 事件编排器应：
|
||||
|
||||
- 按 adapter manifest 展示可用事件；
|
||||
- 非消息事件不提供 Pipeline 目标；
|
||||
- Agent 目标按 `supported_event_patterns` 过滤；
|
||||
- 展示 priority、filters、enabled 与 discard；
|
||||
- 保存前校验目标 UUID 与 `target_type` 一致。
|
||||
|
||||
Pipeline 的配置、Debug Chat 和 Monitoring 继续使用 Pipeline 页面；Agent 使用独立表单配置 Runner 与事件能力。
|
||||
|
||||
## 7. 版本与迁移边界
|
||||
|
||||
此功能按当前 4.x schema 直接实现，不提供 LangBot 3.x 数据库或配置升级路径，也不读取旧 Runner 字段作为 fallback。旧 Pipeline 中的 runner 配置不会生成独立 Agent；用户按新产品模型添加 Agent 即可。
|
||||
|
||||
详见 [07-agent-orchestration.md](./07-agent-orchestration.md) 与 [08-agent-page-and-event-orchestration.md](./08-agent-page-and-event-orchestration.md)。
|
||||
@@ -0,0 +1,740 @@
|
||||
# 插件 SDK 改造
|
||||
|
||||
> Implementation update (2026-09-08): the EventListener observer-broadcast proposal below is superseded by [Event processors](09-event-processors.md). Legacy EventListener hooks run only inside Pipeline. New EBA handlers use explicitly created and bound Runner instances, a third peer processor type alongside Agent and Pipeline.
|
||||
|
||||
## 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。
|
||||
@@ -0,0 +1,147 @@
|
||||
# EBA 分阶段实施计划
|
||||
|
||||
> Implementation update (2026-09-08): the EventListener observer-broadcast proposal below is superseded by [Event processors](09-event-processors.md). Legacy EventListener hooks run only inside Pipeline. New EBA handlers use explicitly created and bound Runner instances, a third peer processor type alongside Agent and Pipeline.
|
||||
|
||||
> 更新：2026-09-05。P0–P4 的主要实现已落入 `dev/4.11.x`，P5 仍需按当前版本验收；下文工作项用于维护实现边界，不表示全部待开发。文件名沿用早期设计，但这里的“迁移”仅指代码架构逐步接入 EBA，不代表 LangBot 3.x 数据库或配置升级。当前提交、定向测试及发布缺口见 [STATUS.md](../agent-runner-pluginization/STATUS.md)。
|
||||
|
||||
## 1. 发布边界
|
||||
|
||||
EBA 跨越 SDK、平台适配器、LangBot Host、WebUI 与插件生态，按可验证阶段落地。当前发布遵守以下硬边界：
|
||||
|
||||
- LangBot 4.x 不支持从 3.x 数据库或配置升级；不保留 legacy migration chain、旧 JSON 模板或旧 Runner 字段读取。
|
||||
- Pipeline 与 Agent 平级且长期并存，分别保留持久化模型与执行链。
|
||||
- 现有 Pipeline 不迁移为 Agent，Pipeline 内的 runner config 不复制到 Agent。
|
||||
- 用户需要 Agent 时新建独立 Agent并选择已安装的 Runner。
|
||||
- Host 不按 LocalAgent id 做运行时、Box 或 WebUI 特判。
|
||||
- Runner 的 SDK/Python 与 scoped MCP bridge 回调共享 Host 授权与事件 session 规则。
|
||||
|
||||
## 2. 阶段总览
|
||||
|
||||
| 阶段 | 目标 | 主要仓库 | 完成条件 |
|
||||
| --- | --- | --- | --- |
|
||||
| P0 | SDK 事件、能力与 Runner 协议 | `langbot-plugin-sdk` | typed entities、manifest、proxy、runtime action 通过测试 |
|
||||
| P1 | 平台适配器 EBA 化 | LangBot + SDK | 事件转换、能力声明、通用/透传 API 通过 adapter checklist |
|
||||
| P2 | Host 观察者与响应者路由 | LangBot backend | observer 广播 + Pipeline/Agent/discard 单目标仲裁可运行 |
|
||||
| P3 | 独立 Agent 与 Runner 注册 | LangBot backend + plugins | Agent CRUD、registry、run authorization、delivery 可运行 |
|
||||
| P4 | WebUI 处理器与事件编排 | LangBot web | Agent/Pipeline 聚合入口和 Bot binding 编辑器可用 |
|
||||
| P5 | 发布门禁与文档 | LangBot skills/docs + runner plugins | 单测、UI E2E、真实 adapter smoke 和插件预检通过 |
|
||||
|
||||
## 3. P0：SDK 契约
|
||||
|
||||
### 工作项
|
||||
|
||||
- 定义规范化平台事件、actor/subject/conversation/delivery context。
|
||||
- 定义 adapter `supported_events`、`supported_apis` 与平台透传 API。
|
||||
- 定义 Runner manifest、run context/result、resource handles 和 pull/callback API。
|
||||
- 提供 `RunnerAPIProxy` 与 SDK-owned scoped MCP bridge。
|
||||
- 保持协议传输与权限校验可测试，不把 Host 私有 Query 对象暴露给插件。
|
||||
|
||||
### 验收
|
||||
|
||||
- stdio/WebSocket runtime 对 typed action 的序列化一致。
|
||||
- 无 `run_id` 或越权资源调用被拒绝。
|
||||
- Python proxy 与 MCP bridge 对同一 Host tool 呈现一致结果/错误形状。
|
||||
|
||||
## 4. P1：平台适配器
|
||||
|
||||
每个适配器按自己的能力增量接入，而不是要求所有平台一次性支持全部事件。
|
||||
|
||||
### 单适配器步骤
|
||||
|
||||
1. 将原生 SDK callback 转换为规范化事件。
|
||||
2. 声明实际支持的事件与 API，不把缺失能力伪装为成功。
|
||||
3. 实现 send/reply/edit/delete/group/user 等适用 API 与平台透传。
|
||||
4. 对消息链、媒体、reply target 和错误语义写单元测试。
|
||||
5. 按 `adapters/acceptance-checklist.md` 记录真实平台 probe。
|
||||
|
||||
### 验收
|
||||
|
||||
- `message.received` 保持正常收发。
|
||||
- 新事件不会重复转换或产生循环合成事件。
|
||||
- `supported_apis` 与实际调用能力一致。
|
||||
|
||||
## 5. P2：Host 路由
|
||||
|
||||
### 执行顺序
|
||||
|
||||
```text
|
||||
adapter event
|
||||
-> EventBus observer broadcast
|
||||
-> EventRouter match event_bindings
|
||||
-> one target: Pipeline | Agent | discard
|
||||
-> Host delivery
|
||||
```
|
||||
|
||||
### 约束
|
||||
|
||||
- Plugin EventListener 是 observer，不作为 priority fallback。
|
||||
- Pipeline 只处理消息事件并复用完整 Stage 链。
|
||||
- Agent 使用独立 Agent 配置和 Runner Host orchestrator。
|
||||
- edit/reaction 等事件的 observer 副作用能力按事件和 adapter 能力过滤。
|
||||
- dry-run 与合成派发必须使用同一匹配器，避免 UI 预览与真实路由漂移。
|
||||
|
||||
### 验收
|
||||
|
||||
- 精确、namespace wildcard、全局 wildcard、filters 与 priority 有单元覆盖。
|
||||
- 同一事件最多一个响应目标，但 observer 仍能收到事件。
|
||||
- Pipeline 与 Agent 可以在同一个 Bot 的不同 binding 中同时生效。
|
||||
|
||||
## 6. P3：独立 Agent 与 Runner
|
||||
|
||||
### 工作项
|
||||
|
||||
- `agents` 只保存 Agent；Pipeline 继续使用自己的表和 API。
|
||||
- Agent config 使用 `runner.id` 与 `runner_config[runner_id]`。
|
||||
- registry 只展示已安装、有效的插件 Runner。
|
||||
- Host 构造 run-scoped resources、state、delivery 与 event log/transcript。
|
||||
- SDK/Python `call_tool` 和 scoped MCP bridge 都回到同一个 Host ToolManager。
|
||||
- Box session 由 Host 将 instance/workspace/bot/adapter/target/thread scope 规范化并哈希为固定长度 `lb-box-<sha256>`；同 scope 稳定、不同 scope 隔离、缺少 identity 时 fail closed。
|
||||
|
||||
### 验收
|
||||
|
||||
- 安装/卸载 Runner 后 metadata 与表单选项同步。
|
||||
- Runner 无法调用未授权 model/tool/knowledge/state。
|
||||
- 两种 Host callback transport 不能覆盖 sandbox session id。
|
||||
- LocalAgent、ACP/ClaudeCode/Codex 与外部服务 Runner 不需要 Host id 特判。
|
||||
|
||||
## 7. P4：WebUI
|
||||
|
||||
### 工作项
|
||||
|
||||
- `/home/agents` 聚合显示 Agent 与 Pipeline，并明确类型。
|
||||
- 创建时选择 Agent 或 Pipeline，编辑时进入各自表单。
|
||||
- Agent 表单读取动态 Runner metadata，保存当前 `runner` / `runner_config` 形状。
|
||||
- Bot 事件编排器编辑 `event_pattern`、target、filters、priority 与 enabled。
|
||||
- 非消息事件过滤 Pipeline；Agent 按声明事件能力过滤。
|
||||
|
||||
### 验收
|
||||
|
||||
- 页面不出现 LocalAgent 专属 banner、变量隐藏或 Box/Pipeline 注入逻辑。
|
||||
- 空 Runner 市场状态给出可安装 Runner 的正常路径。
|
||||
- Pipeline Debug Chat/Monitoring 与 Agent 运行日志分别可用。
|
||||
|
||||
## 8. P5：发布门禁
|
||||
|
||||
### 自动化
|
||||
|
||||
- LangBot backend unit/integration tests 与 Ruff。
|
||||
- SDK Runner/proxy/MCP bridge tests。
|
||||
- Web lint/build 与关键 Playwright cases。
|
||||
- `skills/bin/lbs validate`、`skills/bin/lbs index --check`。
|
||||
- LocalAgent 与其他官方 Runner plugin package/test gate。
|
||||
|
||||
### 真实环境
|
||||
|
||||
- 至少一个消息事件走 Pipeline。
|
||||
- 至少一个非消息事件走独立 Agent 并执行平台动作。
|
||||
- SDK/Python 和 MCP bridge 各完成一次受权工具调用，并证明二者都进入同一个 `PluginToRuntimeAction.CALL_TOOL` Host handler。
|
||||
- Box 可用/不可用的降级路径可观察且无 Runner 特判。
|
||||
|
||||
## 9. 非目标
|
||||
|
||||
- 不把 Pipeline 改名或包装成 Agent。
|
||||
- 不自动把 Pipeline 内 runner 配置迁移成 Agent。
|
||||
- 不为 3.x 保留数据库迁移、旧模板或配置 fallback。
|
||||
- 不要求所有 Runner 经 MCP；本地 Python Runner 可以直接使用 SDK。
|
||||
- 不允许 Runner 自定义 Box session scope。
|
||||
- 不在首版实现多 Agent 串并联；多步骤编排留给后续 workflow。
|
||||
@@ -0,0 +1,187 @@
|
||||
# Agent 与 Pipeline 统一编排（产品最终形态）
|
||||
|
||||
> Implementation update (2026-09-08): the EventListener observer-broadcast proposal below is superseded by [Event processors](09-event-processors.md). Legacy EventListener hooks run only inside Pipeline. New EBA handlers use explicitly created and bound Runner instances, a third peer processor type alongside Agent and Pipeline.
|
||||
|
||||
> **状态**：历史方向稿（2026-06-12）；2026-09-05 标记归档用途。本文的示意 schema、5.0 发布火车、SDK 0.5.0aX 配套与多租户“预留”描述不再作为实施合同。当前 4.11 产品形态见 [08-agent-page-and-event-orchestration.md](./08-agent-page-and-event-orchestration.md)，协议见 [PROTOCOL_V1.md](../agent-runner-pluginization/PROTOCOL_V1.md)，已完成与剩余事项见 [STATUS.md](../agent-runner-pluginization/STATUS.md)。保留正文仅用于解释早期设计取舍。
|
||||
>
|
||||
> 本文档修订 [00-overview.md](./00-overview.md) §3.4 与 [04-event-routing.md](./04-event-routing.md) 中"四种 Handler"的编排模型：**所有编排目标统一进入处理器选择与事件绑定界面，但独立 Agent 与现有 Pipeline 保持不同类型**。事件路由的匹配机制、数据迁移策略、WebUI 交互骨架等内容仍以 04 为准，仅 handler 分类法被本文档取代。
|
||||
|
||||
## 1. 产品最终形态
|
||||
|
||||
**适配器接收各种事件 → 用户编排处理逻辑 → 处理器统一选择表面**，实现从 0 代码到低代码再到全代码的全层面支持：
|
||||
|
||||
```
|
||||
消息平台 (Telegram / Discord / 企微 / ...)
|
||||
│ 各类平台事件
|
||||
▼
|
||||
平台适配器（EBA 新结构，已迁移 12 个）
|
||||
│ EBAEvent (message.* / group.* / friend.* / bot.* / feedback.* / platform.*)
|
||||
▼
|
||||
EventRouter（事件 → 处理器绑定）
|
||||
├─→ 选中的处理器（响应者，单一仲裁）
|
||||
│ ├─ Pipeline：保留现有实体和执行链，仅处理消息事件
|
||||
│ └─ Agent：用户新建并选择 Runner 插件，可接本地、低代码或外部 runtime
|
||||
│
|
||||
└─→ 插件 EventListener（观察者，N 个广播，可 prevent_default）
|
||||
```
|
||||
|
||||
| 编写方式 | 处理器形态 | 代码化程度 |
|
||||
|----------|-----------|-----------|
|
||||
| WebUI 配置模型 + 提示词 + 工具 | 独立 Agent + LocalAgent 插件 | 0 代码 |
|
||||
| 可视化消息编排 | Pipeline（`kind=pipeline`，完整多 Stage 链） | 0 代码 |
|
||||
| 市场安装 | Agent 插件（市场分发） | 0 代码（使用者视角） |
|
||||
| 可视化工作流 | 工作流引擎定义的 Agent | 低代码 |
|
||||
| 对接外部平台 | dify / n8n / coze / webhook 外部 Agent | 集成 |
|
||||
| SDK 编写 | Agent 插件组件 | 全代码 |
|
||||
|
||||
### 1.1 三条并行工作线与汇合点
|
||||
|
||||
| 工作线 | 范围 | 在本架构中的位置 |
|
||||
|--------|------|------------------|
|
||||
| 适配器改造（refactor/eba，本分支） | 事件体系、适配器结构、平台 API、EventRouter | 事件的**生产侧** + 路由层 |
|
||||
| Agent 插件化 | Agent 抽象、Agent 组件类型、市场分发 | 事件的**消费侧**统一抽象 |
|
||||
| 工作流引擎 | 内部低代码工作流 | Agent 的一种**编写方式** |
|
||||
|
||||
**汇合点是 SDK 的 Agent 组件契约（§4）与 event→处理器绑定模型（§3）**。这两个接口冻结后，三条线可彼此 mock 独立推进。契约由本分支（EBA）牵头起草，三线评审后在 langbot-plugin-sdk 落地（发布通道：0.5.0aX pre-release 已打通）。
|
||||
|
||||
## 2. 从四种 Handler 到统一处理器表面
|
||||
|
||||
### 2.1 演进理由
|
||||
|
||||
04 文档中的 pipeline / agent / webhook / plugin 四种 handler_type，本质上都是"对事件作出响应的逻辑"，差别只在编写和部署方式。产品层统一展示和绑定这些处理器，但不会把既有 Pipeline 持久化为 Agent：
|
||||
|
||||
- **产品**：用户只需理解"给 Bot 的事件绑定处理器"，处理器可以是 Pipeline 或 Agent；
|
||||
- **工程**：路由层按 `target_type` 分发到 Pipeline 或 Agent，Agent 的扩展集中到 Runner 抽象；
|
||||
- **生态**：Agent 成为市场上可分发、可复用的一等公民。
|
||||
|
||||
### 2.2 收编映射
|
||||
|
||||
| 原 handler_type（04 文档） | 收编后 |
|
||||
|---------------------------|--------|
|
||||
| `pipeline` | 保留 Pipeline 实体；binding 使用 `target_type=pipeline` 和原 `pipeline_uuid`，进程内直接复用 MessageAggregator → QueryPool → Pipeline 机制 |
|
||||
| `agent`（RequestRunner） | 用户新建独立 Agent，并选择对应 Runner 插件；不读取或复制旧 Pipeline 内嵌 runner 配置 |
|
||||
| `webhook` | 外部 Agent 的一种：事件 POST 出去、响应解析为动作（保留 04 §5.4 的请求/响应格式） |
|
||||
| `plugin`（EventListener 分发） | **不收编**——角色不同，见 §2.3 |
|
||||
|
||||
### 2.3 响应者与观察者的角色切分
|
||||
|
||||
事件的消费方有两种角色，不应混为一谈：
|
||||
|
||||
- **响应者（Pipeline 或 Agent）**：路由选中**一个**，负责对事件作出回应（回复消息、执行动作）。多条绑定匹配同一事件时按 priority 仲裁，只取最高者。
|
||||
- **观察者（插件 EventListener）**：**广播**给所有注册插件，做旁路逻辑（日志、审计、风控、统计）。沿用现有机制不变，包括 `prevent_default()`——观察者可拦截本次事件，使处理器不被调用（与现有"插件拦截流水线"行为完全兼容）。
|
||||
|
||||
执行顺序：事件到达 → 先广播观察者（按插件优先级）→ 若未被 prevent_default → 分发给选中的处理器。
|
||||
|
||||
## 3. 数据模型：event → 处理器绑定
|
||||
|
||||
### 3.1 独立 Agent 与现有 Pipeline
|
||||
|
||||
Agent 与 Pipeline 都是一等处理器。用户创建 Agent、选择已安装的 Runner，再把适合的事件绑定到 Agent；Pipeline 继续保存在 Pipeline 表中，以完整 Stage 链处理消息事件。两者可在同一处理器列表中以不同 `kind` 展示和选择；这种聚合展示不会创建额外记录，也不会在两种模型之间复制配置。
|
||||
|
||||
```python
|
||||
class Agent(Base):
|
||||
"""Agent 实例：一个具体配置过的、可被事件绑定的响应者"""
|
||||
uuid: str # 主键
|
||||
name: str
|
||||
kind: str # 固定为 "agent"；Pipeline 使用自己的持久模型
|
||||
component_ref: str # Runner id，例如 plugin:<author>/<plugin>/<runner>
|
||||
config: dict # JSON — runner id、runner config 与资源/状态/投递策略
|
||||
# 多租户预留：归属主体字段（tenant/workspace），首版可空
|
||||
```
|
||||
|
||||
Bot 上的绑定配置（替代 04 §2.2 的 EventHandlerConfig，沿用其匹配语义）：
|
||||
|
||||
```python
|
||||
class EventBinding(pydantic.BaseModel):
|
||||
event_pattern: str # 精确 / "message.*" / "*"，匹配规则同 04 §4
|
||||
target_type: str # "agent" | "pipeline" | "discard"
|
||||
target_uuid: str # Agent 或 Pipeline 的原始 UUID；discard 时为空
|
||||
enabled: bool = True
|
||||
priority: int = 0 # 多条匹配时取最高者（单一仲裁）
|
||||
description: str = ''
|
||||
```
|
||||
|
||||
`use_pipeline_uuid` 只迁移 Bot 的路由结构：写入 `{"event_pattern": "message.received", "target_type": "pipeline", "target_uuid": <原 pipeline uuid>}`，继续引用原 Pipeline。迁移不会创建独立 Agent，也不会复制 Pipeline 内嵌的 runner 配置；需要 Agent 的用户自行新增 Agent 并修改 binding。观察者广播不需要配置（始终发生），04 中"兜底 plugin 规则"不再需要。
|
||||
|
||||
## 4. SDK Agent 组件契约（草案）
|
||||
|
||||
Agent 成为插件系统的第七种组件（现有：Command / Tool / EventListener / KnowledgeEngine / Parser / Page）。
|
||||
|
||||
### 4.1 Manifest
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Agent
|
||||
metadata:
|
||||
name: group-assistant
|
||||
label: { en_US: Group Assistant, zh_Hans: 群助理 }
|
||||
spec:
|
||||
handled_events: # 声明可处理的事件类型；绑定 UI 据此过滤
|
||||
- message.received
|
||||
- group.member_joined
|
||||
config: # 实例化配置 schema，复用现有组件配置体系
|
||||
- name: model
|
||||
type: llm-model-selector
|
||||
- name: persona
|
||||
type: prompt-editor
|
||||
execution:
|
||||
python: { path: agent.py, attr: GroupAssistant }
|
||||
```
|
||||
|
||||
### 4.2 运行时接口
|
||||
|
||||
```python
|
||||
class Agent(BaseComponent):
|
||||
async def handle(self, ctx: AgentContext) -> typing.AsyncGenerator[AgentChunk, None]:
|
||||
"""处理一次事件，流式产出回复与动作。每次事件调用一次。"""
|
||||
...
|
||||
|
||||
class AgentContext:
|
||||
event: EBAEvent # 触发事件（统一事件体系）
|
||||
bot: BotHandle # 来源 Bot 信息
|
||||
session: SessionHandle # 会话句柄：历史消息、会话变量（LangBot 侧管理，Agent 保持无状态）
|
||||
config: dict # 该 Agent 实例的配置
|
||||
|
||||
# 能力面（经 runtime RPC 回 LangBot 执行）：
|
||||
async def reply(self, chain: MessageChain, quote: bool = False): ...
|
||||
async def send_message(self, target_type: str, target_id: str, chain: MessageChain): ...
|
||||
async def call_platform_api(self, action: str, params: dict) -> dict: ...
|
||||
async def invoke_llm(self, model_uuid: str, messages: list, funcs: list = None) -> dict: ...
|
||||
# + 工具调用 / KB 检索 / 插件存储（沿用 LangBotAPIProxy 既有方法）
|
||||
|
||||
class AgentChunk:
|
||||
delta_message: MessageChain | None = None # 增量回复（流式）
|
||||
actions: list[dict] | None = None # 平台动作（同 webhook response_actions 格式）
|
||||
final: bool = False
|
||||
```
|
||||
|
||||
**流式**：复用 SDK 通信协议既有的 `chunk_status: continue/end` 机制，`handle()` 的每次 yield 对应一个 chunk。
|
||||
**Pipeline 与 Agent 分流**：Pipeline target 继续走 LangBot 进程内的 Pipeline 执行链；独立 Agent 经 Runner 插件 runtime 分发。路由层通过 binding 的 `target_type` 明确区分二者。
|
||||
|
||||
### 4.3 执行语义与可靠性
|
||||
|
||||
| 关注点 | 约定 |
|
||||
|--------|------|
|
||||
| 仲裁 | 单响应者：priority 最高的匹配绑定生效，其余忽略 |
|
||||
| 性能 | Pipeline 继续走进程内链路；插件 Agent 每事件过一次 RPC 边界，消息场景需设延迟预算（评审项：目标 P95 附加延迟） |
|
||||
| 会话状态 | 归 LangBot 侧（SessionHandle），插件 Agent 原则上无状态，崩溃重启不丢会话 |
|
||||
| 降级 | Agent 调用失败/超时：可配置 fallback（回错误提示，或指定备用处理器）；不会隐式回退到旧 Pipeline 配置 |
|
||||
| 多租户预留 | AgentContext / SessionHandle / 存储接口显式携带归属主体标识，禁止新增全局单例状态——为后续轻量 SaaS 多租户铺路 |
|
||||
|
||||
## 5. 发布火车
|
||||
|
||||
| 版本 | 内容 | 备注 |
|
||||
|------|------|------|
|
||||
| 4.11（可选） | 现状成果：12 个 EBA 适配器、插件全事件订阅、`call_platform_api` | 对用户不可见的管道工程 + 插件新能力，不动产品概念 |
|
||||
| **5.0** | 产品形态首发：EventRouter + event→处理器绑定 + WebUI 编排 + 旧 Bot 路由迁移 + 独立 Agent / Runner 插件 + SDK Agent 组件契约（可标 experimental） | `use_pipeline_uuid` 仅改写为指向原 Pipeline 的 binding，不生成 Agent；配 SDK 0.5.0 正式版；走 beta 周期 |
|
||||
| 5.x | 工作流 Agent（工作流引擎线挂入）、Agent 市场生态、剩余适配器（satori 等）、Agent 插件化收尾 | 验证开放注册机制 |
|
||||
| 多租户 | 独立评估：仅数据隔离 → 5.x 部署选项；伴随权限/计费/产品定位变化 → 6.0 | 前置条件是 §4.3 的归属主体预留已落实 |
|
||||
|
||||
## 6. 开放问题（评审清单）
|
||||
|
||||
1. **webhook 的最终定位**：作为外部 Agent（响应者，现方案）之外，是否还需要"纯通知观察者"形态（现 WebhookPusher 的角色）？
|
||||
2. **多 Agent 协作**：单一仲裁之外，是否需要"串联/并联多个 Agent"的场景？（建议 5.0 不做，留给工作流引擎表达）
|
||||
3. **工作流引擎的宿主**：核心内置，还是自身也作为一个插件交付（解释工作流定义的 Agent 插件）？
|
||||
4. **插件 Agent 的延迟预算**：消息主链路过 RPC 的 P95 目标值与压测方案。
|
||||
5. **Workflow 的处理器边界**：未来 Workflow 应作为与 Pipeline、Agent 平级的处理器，还是作为其中一种处理器的内部编排实现。
|
||||
6. **SDK 1.0 时机**：Agent 契约稳定后是否随 LangBot 5.x 给插件生态一个 API 稳定承诺。
|
||||
@@ -0,0 +1,185 @@
|
||||
# 处理器页面与事件编排产品设计
|
||||
|
||||
> Implementation update (2026-09-08): the EventListener observer-broadcast proposal below is superseded by [Event processors](09-event-processors.md). Legacy EventListener hooks run only inside Pipeline. New EBA handlers use explicitly created and bound Runner instances, a third peer processor type alongside Agent and Pipeline.
|
||||
|
||||
> 状态：当前实现说明（2026-09-05），对应 `dev/4.11.x`。P0–P3 已集成；发布验收见 [STATUS.md](../agent-runner-pluginization/STATUS.md)。
|
||||
>
|
||||
> 本文档修订 [07-agent-orchestration.md](./07-agent-orchestration.md) 中“Agent 替代 Pipeline”的表述。当前产品形态保留两种长期并存的同级处理器：**Agent** 与 **Pipeline**。处理器页面只是共享入口，不改变二者各自的持久化模型和执行语义。
|
||||
|
||||
## 1. 产品边界
|
||||
|
||||
LangBot 的处理逻辑分成两种同级形态：
|
||||
|
||||
| 形态 | 定位 | 可处理事件 | 典型用户 |
|
||||
| --- | --- | --- | --- |
|
||||
| Agent | runner 驱动的事件优先处理器，承载 Runner / 外部 runner | `message.*`、`group.*`、`friend.*`、`bot.*`、`feedback.*`、`platform.*` 等声明范围 | 需要直接处理多类平台事件或接入外部 agent runtime 的用户 |
|
||||
| Pipeline | 可视化、可控、可组合的消息处理流水线，执行完整 Stage 链 | 仅 `message.*`，首版等价于 `message.received` | 需要预处理、AI、后处理、扩展和输出控制的消息场景 |
|
||||
|
||||
处理器页面负责统一管理这两种处理单元：
|
||||
|
||||
- 创建时选择 **Agent** 或 **Pipeline**；
|
||||
- 列表中清晰标注类型与事件能力；
|
||||
- Pipeline 的编辑、调试、监控继续复用现有能力；
|
||||
- Agent 保存 runner 配置与事件能力，并通过 Bot 事件绑定进入运行时执行。
|
||||
|
||||
## 2. 信息架构
|
||||
|
||||
### 2.1 处理器页面
|
||||
|
||||
路径：`/home/agents`
|
||||
|
||||
职责：
|
||||
|
||||
1. 展示所有可被事件绑定的处理单元，包括 Agent 与 Pipeline。
|
||||
2. 创建时先选择类型：
|
||||
- Agent：创建一条独立 Agent 配置对象，默认支持其 runner 声明的事件范围；
|
||||
- Pipeline：创建一条独立 Pipeline，执行完整消息 Stage 链。
|
||||
3. 编辑时按类型进入不同表单：
|
||||
- Pipeline：沿用原 Pipeline 配置页，包括 AI、触发、安全、输出、扩展、Debug、Monitoring；
|
||||
- Agent：基础信息由详情入口编辑，主配置分为运行器、运行器配置、事件与工具；事件范围、自动事件工具、平台级动作和普通工具白名单在同一配置流程内维护。
|
||||
|
||||
处理器详情复用 `ProcessorDetailWorkbench`；Agent 与 Pipeline 保留各自的配置、调试和日志语义。`RunnerSelect` 提供已安装 Runner 和市场安装入口，安装状态可恢复；Runner 配置来自动态 metadata，不按 LocalAgent id 定制 Host 表单。调试事件选择位于输入区域；Bot 的平台事件调试位于机器人配置中，路由 dry-run 只解释匹配结果。
|
||||
|
||||
`/home/pipelines` 继续提供 Pipeline 直接编辑路径；共享处理器入口当前使用 `/home/agents`。URL 是实现路径，不代表 Agent 包含 Pipeline。
|
||||
|
||||
### 2.2 Bot 的事件编排
|
||||
|
||||
Bot 上维护“事件 -> 处理单元”的绑定规则：
|
||||
|
||||
```text
|
||||
Bot
|
||||
└─ EventBinding[]
|
||||
├─ event_pattern: message.received / group.member_joined / group.* / *
|
||||
├─ target_type: agent / pipeline / discard
|
||||
├─ target_uuid: Agent UUID 或 Pipeline UUID
|
||||
├─ filters: 事件字段过滤条件
|
||||
├─ priority: 数字越大越优先
|
||||
└─ enabled
|
||||
```
|
||||
|
||||
Pipeline 只能被绑定到 `message.*`。如果用户选择非消息事件，目标选择器不展示 Pipeline。
|
||||
|
||||
## 3. 持久化模型
|
||||
|
||||
### 3.1 Agent 实例与 Pipeline 实例
|
||||
|
||||
`agents` 表只保存 Agent；Pipeline 继续保存在 Pipeline 表中。当前物理表名 `legacy_pipelines` 是既有存储名称，不代表 Pipeline 在产品架构中是遗留或过渡形态。
|
||||
|
||||
```python
|
||||
class Agent(Base):
|
||||
workspace_uuid: str # workspace-scoped persistence
|
||||
uuid: str
|
||||
name: str
|
||||
description: str
|
||||
emoji: str
|
||||
kind: str # 首版固定为 "agent"
|
||||
component_ref: str # runner reference; execution config uses runner.id
|
||||
config: dict # runner, runner_config, allowed_tools, allowed_platform_tools
|
||||
supported_event_patterns: list[str]
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
```
|
||||
|
||||
处理器聚合服务把 `agents` 与 Pipeline 表投影成同一个前端列表：
|
||||
|
||||
```json
|
||||
{
|
||||
"uuid": "...",
|
||||
"name": "...",
|
||||
"kind": "agent | pipeline",
|
||||
"capability": {
|
||||
"supported_event_patterns": ["*"],
|
||||
"message_only": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Pipeline 投影时固定：
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "pipeline",
|
||||
"capability": {
|
||||
"supported_event_patterns": ["message.*"],
|
||||
"message_only": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Bot 事件绑定
|
||||
|
||||
Bot 使用 `event_bindings` JSON 字段持久化路由。当前未引入独立路由表；是否拆表应由查询、审计和多作用域需求决定。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"event_pattern": "group.member_joined",
|
||||
"target_type": "agent",
|
||||
"target_uuid": "...",
|
||||
"filters": [],
|
||||
"priority": 100,
|
||||
"enabled": true,
|
||||
"description": "Welcome new group members"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 4. 匹配规则
|
||||
|
||||
事件模式支持三层：
|
||||
|
||||
1. 精确匹配：`group.member_joined`
|
||||
2. 命名空间通配：`group.*`
|
||||
3. 全局通配：`*`
|
||||
|
||||
优先级：
|
||||
|
||||
1. `enabled = true`
|
||||
2. event pattern 命中
|
||||
3. filters 全部命中
|
||||
4. `priority` 数值高者优先
|
||||
5. 同优先级按列表顺序
|
||||
|
||||
## 5. 并存策略
|
||||
|
||||
1. Pipeline 与 Agent 长期并存，各自保存配置并执行自己的运行链路。
|
||||
2. 数据库升级中的旧路由转换由 Alembic 负责；当前运行时只读取 `event_bindings`，不再读取 `use_pipeline_uuid`。
|
||||
3. 旧 `pipeline_routing_rules` 不再作为第二个运行时路由来源；LangBot 4.x 不支持 3.x 数据库或配置升级。
|
||||
4. `event_bindings` 允许 `target_type=pipeline|agent|discard`；Pipeline 目标只限 `message.*`。
|
||||
5. Pipeline 与 Agent 保留各自的持久化和编辑语义；处理器聚合入口只负责统一展示和选择。
|
||||
|
||||
## 6. 已集成阶段与维护范围
|
||||
|
||||
### P0：处理器入口统一
|
||||
|
||||
- 新增 `/home/agents`。
|
||||
- 侧边栏显示“处理器”，列表包含平级的 Agent 与 Pipeline。
|
||||
- 创建时选择 Agent 或 Pipeline。
|
||||
- `/home/pipelines` 继续作为 Pipeline 直接编辑路径。
|
||||
|
||||
### P1：配置模型落地
|
||||
|
||||
- 新增 `agents` 表与 `/api/v1/agents`。
|
||||
- Agent 可保存 runner 与 runner_config。
|
||||
- Pipeline 继续使用原 Pipeline 表单与 API。
|
||||
|
||||
### P2：事件编排配置面
|
||||
|
||||
- Bot 表单新增事件编排编辑器。
|
||||
- 读取 adapter manifest 的 `supported_events` 生成事件选项。
|
||||
- 根据事件类型过滤可选目标：Pipeline 仅在 `message.*` 可选。
|
||||
|
||||
### P3：EventRouter 执行接入
|
||||
|
||||
- EBA 事件先广播插件 observer。
|
||||
- 然后按 `event_bindings` 的事件模式、filters、priority 和顺序选择一个处理器。
|
||||
- Pipeline 目标通过 MessageAggregator 进入完整 Pipeline Stage 链；Agent 目标直接进入 Runner 链路。
|
||||
- 非消息事件只选择声明支持该事件的 Agent，不调用 Pipeline；Runner 输出有平台 reply target 时会投递回平台。
|
||||
|
||||
## 7. 不做的事
|
||||
|
||||
- 不把 Pipeline 改名成 Agent，也不删除 Pipeline 的配置模型。
|
||||
- 不把 Pipeline 降级为兼容层、Agent 子类型或临时运行入口。
|
||||
- 不把非消息事件伪装成用户文本塞入 Pipeline。
|
||||
- 不在首版做多 Agent 串并联；需要多步骤处理时留给后续 workflow。
|
||||
@@ -0,0 +1,92 @@
|
||||
# Runner components and Pipeline plugin compatibility
|
||||
|
||||
## Product boundary
|
||||
|
||||
| Product | Implementation | Event entry |
|
||||
| --- | --- | --- |
|
||||
| Pipeline | Pipeline stages and an agent-capable Runner | Received messages |
|
||||
| Agent | A Runner with `spec.usages: [agent]` | Configured events |
|
||||
| Plugin processor | A Runner with `spec.usages: [event]` | Events declared in `spec.events` |
|
||||
|
||||
Runner is the only component for these execution styles. `spec.usages` can contain
|
||||
both `agent` and `event`; these are selection capabilities, not mutually exclusive
|
||||
execution modes. An installed component is reusable code. Users create processor
|
||||
instances, select a Runner and configure it, then bind Bot events to the instance.
|
||||
Installation alone never subscribes a component to incoming events.
|
||||
|
||||
## Legacy EventListener contract
|
||||
|
||||
EventListener remains a Pipeline extension. Existing plugins retain their import
|
||||
paths, handler registration syntax, event classes, Query-based APIs, and Pipeline
|
||||
plugin selection behavior. No conversion of installed listeners into standalone
|
||||
processor instances takes place.
|
||||
|
||||
Compatibility must cover execution behavior, not just successful deserialization:
|
||||
|
||||
| Hook | Required behavior |
|
||||
| --- | --- |
|
||||
| PersonMessageReceived / GroupMessageReceived | Read the returned EventContext before later stages; retain message edits and default prevention |
|
||||
| PromptPreProcessing | Preserve timing and apply returned default_prompt and prompt |
|
||||
| PersonNormalMessageReceived / GroupNormalMessageReceived | Preserve user_message_alter, default prevention, and replacement replies |
|
||||
| PersonCommandSent / GroupCommandSent | Preserve command stage timing, default prevention, and replacement replies |
|
||||
| NormalMessageResponded | Preserve response-stage timing, default prevention, and replacement message chains, including streaming behavior |
|
||||
| All hooks | Preserve plugin ordering, prevent_postorder across installations, bound-plugin filtering, Query identity, and Workspace scope |
|
||||
|
||||
RPC responses are new Python objects. Host code must consume returned values
|
||||
rather than assume mutations reached the original Query by object identity.
|
||||
Host-only references, including the active Query and raw adapter message, must
|
||||
remain available for legacy reply APIs without being exposed in serialized
|
||||
plugin events.
|
||||
|
||||
Preserve source event fields across EBA-to-legacy conversion, including group
|
||||
member permissions, bot group permissions, and member titles. Missing platform
|
||||
information must be distinguished from fields that were dropped during conversion.
|
||||
|
||||
Direct Agent and Event processor execution must not synthesize Pipeline lifecycle
|
||||
hooks. Those hooks describe actual Pipeline stages.
|
||||
|
||||
## SDK and runtime
|
||||
|
||||
`lbp comp Runner` generates `components/runner`. Every component uses
|
||||
`plugin:author/plugin/name` as its identity. Names are unique within a plugin.
|
||||
The component can override `async run(ctx)` and yield RunnerResult objects, or
|
||||
register typed platform callbacks through `@self.handler(EventClass)` in
|
||||
`initialize()`. Default run dispatches an exact handler, falling back to EBAEvent.
|
||||
A custom run can delegate to this dispatch with `await super().run(ctx)`.
|
||||
|
||||
Both styles share RunnerContext, invocation-bound ctx.api, logs, replies, deadlines,
|
||||
cancellation, worker isolation and the run ledger. ctx.event is the envelope;
|
||||
ctx.platform_event is the typed platform payload. Each invocation owns its context;
|
||||
never put the current context or run ID on a shared component or plugin instance.
|
||||
|
||||
The runtime emits completion on normal return unless the Runner already emitted a
|
||||
terminal result. Exceptions fail the run and retain preceding results. Cancelling
|
||||
the result stream cancels execution. There is no implicit retry or hidden model
|
||||
loop. Returned text and logs do not send platform messages: replies are explicit
|
||||
ctx.reply / ctx.reply_stream actions. Pipeline retains its configured output stage.
|
||||
|
||||
`self.plugin` continues to expose ordinary plugin APIs. ctx.api carries run-scoped
|
||||
resource grants and records tool actions. Workspace and installation authorization
|
||||
remain Host-enforced. Run identity and API operation scope are separate concepts.
|
||||
|
||||
## Selection and observability
|
||||
|
||||
Both product selectors discover the same Runner catalog and filter by usage.
|
||||
Validate usage again before execution. Event-capable Runners must declare events;
|
||||
users can route a subset, but cannot expand the manifest capability. Unconfigured
|
||||
instances expose no event subscriptions. Workspace ownership, plugin scope and
|
||||
instance identity are checked for routing, execution, cancellation and run reads.
|
||||
|
||||
Plugin processor details keep event debugging on the left and configuration/logs
|
||||
on the right. Component settings use the existing schema form. Logs and action
|
||||
results remain distinct from actual platform delivery; debug delivery is Mock.
|
||||
Agent-native interactions stay on the Agent product path; typed handlers consume
|
||||
platform events. Legacy Pipeline lifecycle hooks remain on the Pipeline path.
|
||||
|
||||
## Validation
|
||||
|
||||
SDK tests cover both execution styles, event matrices, concurrent contexts,
|
||||
termination, cancellation and permissions. Packaged CLI tests generate, build and
|
||||
execute the published component. Core tests cover usage-filtered discovery, event
|
||||
routing, Workspace authorization and real plugin-runtime transport. RunnerDemo
|
||||
provides multi-step actions, configuration isolation and controlled failures.
|
||||
@@ -0,0 +1,41 @@
|
||||
# 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) |
|
||||
| QQ Official API | Migrated; WebSocket inbound reached LangBot, model config blocked reply | [QQ Official API](./qqofficial.md) |
|
||||
| Slack | Migrated; private text and outbound/API plugin E2E verified | [Slack](./slack.md) |
|
||||
| WeCom Customer Service | Migrated; customer-side UI text plugin E2E verified, inbound media and platform-API live coverage pending | [WeCom Customer Service](./wecomcs.md) |
|
||||
| Kook | Migrated; unit/mocked converter and API coverage only, live acceptance pending | [Kook](./kook.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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,171 @@
|
||||
# EBA Adapter Acceptance Report
|
||||
|
||||
Date: May 10, 2026
|
||||
|
||||
Scope:
|
||||
|
||||
- `telegram-omni`
|
||||
- `discord-omni`
|
||||
- `aiocqhttp-omni`
|
||||
- `dingtalk-omni`
|
||||
- `lark-omni`
|
||||
- `wecom-omni`
|
||||
- `wecombot-omni`
|
||||
- `wecomcs-omni`
|
||||
- `officialaccount-omni`
|
||||
- `qqofficial-omni`
|
||||
- `slack-omni`
|
||||
|
||||
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. |
|
||||
| QQ Official API | Partial EBA acceptance | QQ Official API is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, docs, and a direct live probe scaffold. A real WebSocket-mode QQ Official bot reached the LangBot pipeline on `dev.rockchin.top`; reply/outbound evidence is blocked by the test model provider returning `model_not_found` for `deepseek-v3`. |
|
||||
| Slack | Partial EBA acceptance | Slack is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, docs, and a direct live probe scaffold. Real Slack private text reached `EBAEventProbe`; safe common APIs, outbound component fallback sweep, and declared Slack platform APIs passed. Channel mention and real inbound media evidence remain 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` |
|
||||
| QQ Official API unit | local mocked QQ Official client paths | `tests/unit_tests/platform/test_qqofficial_eba_adapter.py` |
|
||||
| Slack unit | local mocked Slack client paths | `tests/unit_tests/platform/test_slack_eba_adapter.py` |
|
||||
| Slack private | Slack workspace private DM on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/slack_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-omni` 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.
|
||||
@@ -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.png
|
||||
```
|
||||
|
||||
The EBA adapter is registered as `aiocqhttp-omni`. 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.
|
||||
@@ -0,0 +1,115 @@
|
||||
# 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 and card callbacks 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. |
|
||||
| `feedback.received` | unit covered | DingTalk card callback actions with feedback-like values (`like`, `dislike`, `cancel`, or `1`/`2`/`3`) map to `FeedbackReceivedEvent`. Other card actions remain `platform.specific`. |
|
||||
| `platform.specific` | implemented | Non-feedback card callbacks and unmapped callback/message shapes are emitted as structured platform-specific events. |
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,146 @@
|
||||
# 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-omni`.
|
||||
|
||||
## 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`
|
||||
- `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.
|
||||
@@ -0,0 +1,108 @@
|
||||
# KOOK EBA Adapter
|
||||
|
||||
## Status
|
||||
|
||||
KOOK has been migrated to the EBA adapter directory:
|
||||
|
||||
```text
|
||||
src/langbot/pkg/platform/adapters/kook/
|
||||
├── adapter.py
|
||||
├── api_impl.py
|
||||
├── event_converter.py
|
||||
├── manifest.yaml
|
||||
├── message_converter.py
|
||||
├── platform_api.py
|
||||
└── types.py
|
||||
```
|
||||
|
||||
The adapter is registered as `kook-omni`.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Field | Required | Default | Description |
|
||||
|-------|----------|---------|-------------|
|
||||
| `token` | Yes | `""` | KOOK bot token. |
|
||||
| `enable-stream-reply` | Yes | `false` | Reserved for shared platform configuration compatibility. |
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Evidence | Notes |
|
||||
|-------|----------|-------|
|
||||
| `message.received` | `plugin-e2e-ui` | Real KOOK UI channel message reached `EBAEventProbe` as `MessageReceivedEvent`. |
|
||||
| `platform.specific` | `plugin-e2e-ui` | KOOK gateway event without a common EBA mapping reached `EBAEventProbe` as `PlatformSpecificEventReceived`. |
|
||||
|
||||
## Common APIs
|
||||
|
||||
| API | Evidence | Notes |
|
||||
|-----|----------|-------|
|
||||
| `send_message` | `plugin-e2e-outbound` | Probe plugin sent channel messages through SDK `send_message`; KOOK returned message IDs. |
|
||||
| `reply_message` | `unit` | Supports `reply_msg_id` and optional quoted replies when the source message ID is available. |
|
||||
| `get_message` | `plugin-e2e-outbound` | Probe plugin fetched the cached triggering message. |
|
||||
| `get_group_info` | `plugin-e2e-outbound` | Probe plugin received cached KOOK channel info. |
|
||||
| `get_group_list` | `plugin-e2e-outbound` | Probe plugin received cached channel/group entities observed by the adapter. |
|
||||
| `get_group_member_info` | `plugin-e2e-outbound` | Probe plugin received cached sender info as a group member. |
|
||||
| `get_user_info` | `plugin-e2e-outbound` | Probe plugin received cached sender user info. |
|
||||
| `get_friend_list` | `plugin-e2e-outbound` | Probe plugin received cached users. |
|
||||
| `upload_file` | `unit` | Uses KOOK `asset/create` and returns URL/ID. |
|
||||
| `get_file_url` | `unit` | KOOK media IDs are URL-like in the adapter path; returns the ID unchanged. |
|
||||
| `delete_message` | `unit` | Calls KOOK delete endpoints. Live permission verification is still required. |
|
||||
| `forward_message` | `plugin-e2e-outbound` | Probe plugin sent flattened forward content through SDK `send_message`. |
|
||||
| `call_platform_api` | `plugin-e2e-outbound` | Probe plugin called safe KOOK platform-specific APIs through SDK `call_platform_api`. |
|
||||
|
||||
## Platform-Specific APIs
|
||||
|
||||
| Action | Evidence | Notes |
|
||||
|--------|----------|-------|
|
||||
| `get_current_user` | `plugin-e2e-outbound` | Probe plugin called `user/me`. |
|
||||
| `get_user` | `plugin-e2e-outbound` | Probe plugin called `user/view` for the triggering sender. |
|
||||
| `get_channel` | `plugin-e2e-outbound` | Probe plugin called `channel/view` for the triggering channel. |
|
||||
| `get_guild` | `plugin-e2e-outbound` | Probe plugin called `guild/view`; gateway URLs redact token query values. |
|
||||
| `get_gateway` | `plugin-e2e-outbound` | Probe plugin called `gateway/index`; returned token query values are redacted. |
|
||||
| `send_direct_message` | `unit` | Calls `direct-message/create`. |
|
||||
|
||||
## Components
|
||||
|
||||
| Component | Receive Evidence | Send Evidence | Notes |
|
||||
|-----------|------------------|---------------|-------|
|
||||
| `Source` | `plugin-e2e-ui` | N/A | KOOK message ID and timestamp are preserved. |
|
||||
| `Plain` | `plugin-e2e-ui` | `plugin-e2e-outbound` | Text and KMarkdown are represented as plain common text. |
|
||||
| `At` | `plugin-e2e-ui` | `plugin-e2e-outbound` | KOOK `(met)<id>(met)` mentions map to common `At`. |
|
||||
| `AtAll` | `unit` | `plugin-e2e-outbound` | KOOK `(met)all(met)` maps to common `AtAll`; real inbound UI AtAll was not tested. |
|
||||
| `Image` | `unit` | `unit` | URL/image ID based path only; live rendering still needs verification. |
|
||||
| `Voice` | `unit` | `unit` | URL based path only; live rendering still needs verification. |
|
||||
| `File` | `unit` | `unit` | URL based path only; upload API is exposed separately. |
|
||||
| `Forward` | `unit` | `unit` | Outbound forwards are flattened; inbound structured forwards are not exposed by current legacy implementation. |
|
||||
| `Unknown` | `unit` | N/A | Unsupported KOOK message types become `Unknown` or `PlatformSpecificEvent`. |
|
||||
|
||||
## Acceptance Record
|
||||
|
||||
Test date: June 4, 2026.
|
||||
|
||||
Plugin E2E verified on June 4, 2026 with `EBAEventProbe`, SDK standalone runtime, KOOK WebSocket adapter, and a real KOOK channel UI message.
|
||||
|
||||
Evidence:
|
||||
|
||||
- JSONL: `data/temp/kook_eba_plugin_probe.jsonl`
|
||||
- Plugin log: `data/logs/eba-probe-kook.log`
|
||||
|
||||
Observed and verified:
|
||||
|
||||
- A real KOOK UI channel message reached the plugin as `MessageReceived` with `bot_uuid=7ab5b065-6e4e-4def-95f0-3c265366e26f`, `adapter_name=kook`, common sender/group/chat fields, and common `MessageChain` components.
|
||||
- KOOK gateway-specific event reached the plugin as `PlatformSpecificEventReceived`.
|
||||
- Probe plugin called SDK `send_message`; KOOK returned message IDs for text, At, AtAll, image URL/base64 fallback path, quote fallback, file fallback, and flattened forward cases.
|
||||
- Probe plugin called common API methods through the SDK path: `get_message`, `get_user_info`, `get_friend_list`, `get_group_info`, `get_group_list`, and `get_group_member_info`.
|
||||
- Probe plugin called safe KOOK platform-specific APIs through SDK `call_platform_api`: `get_current_user`, `get_user`, `get_channel`, `get_gateway`, and `get_guild`.
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run pytest tests/unit_tests/platform/test_kook_eba_adapter.py
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Blocked or partial items:
|
||||
|
||||
- `plugin-e2e-ui` inbound coverage for image, file, voice, AtAll, quote, and forward.
|
||||
- `plugin-e2e-outbound` visual verification in KOOK UI for image/file/voice rendering. KOOK returned message IDs, but UI inspection was not performed in this run.
|
||||
- `reply_message` and `delete_message` live permission verification.
|
||||
- Destructive or permission-sensitive APIs were not declared beyond delete; KOOK mute/kick/leave remain explicit `NotSupportedError` paths until a safe fixture is available.
|
||||
@@ -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-omni`.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,101 @@
|
||||
# OfficialAccount EBA Adapter
|
||||
|
||||
Adapter directory: `src/langbot/pkg/platform/adapters/officialaccount/`
|
||||
|
||||
Manifest name: `officialaccount-omni`
|
||||
|
||||
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/unsubscribe/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-omni`, `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.
|
||||
@@ -0,0 +1,146 @@
|
||||
# QQOfficial EBA Adapter
|
||||
|
||||
Adapter directory: `src/langbot/pkg/platform/adapters/qqofficial/`
|
||||
|
||||
Manifest name: `qqofficial-omni`
|
||||
|
||||
Status: partial migration. The EBA adapter structure, manifest, converters, cache-backed safe APIs, platform API map, unit tests, and direct live probe scaffold are in place. A real QQ Official WebSocket bot on `dev.rockchin.top` received an inbound user message and drove LangBot into the normal pipeline path; the response path was blocked by the test environment model service returning `model_not_found` for `deepseek-v3`.
|
||||
|
||||
## Config
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| `appid` | yes | QQ Official app ID. |
|
||||
| `secret` | yes | QQ Official app secret. |
|
||||
| `token` | yes | QQ Official callback token. |
|
||||
| `enable-webhook` | yes | Uses LangBot unified webhook when true; otherwise uses the QQ WebSocket gateway. |
|
||||
| `enable-stream-reply` | yes | Enables C2C streaming replies when supported by the QQ Official endpoint. |
|
||||
| `webhook_url` | no | Generated by LangBot and copied into the QQ Official callback settings in webhook mode. |
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Evidence | Notes |
|
||||
| --- | --- | --- |
|
||||
| `message.received` | adapter-live, unit | `C2C_MESSAGE_CREATE`, `DIRECT_MESSAGE_CREATE`, `GROUP_AT_MESSAGE_CREATE`, `GROUP_MESSAGE_CREATE`, and `AT_MESSAGE_CREATE` map to common `MessageReceivedEvent`. Full-group mode has protocol regression coverage; the earlier live probe below covered the original message path. |
|
||||
| `message.reaction` | unit | `MESSAGE_REACTION_ADD` and `MESSAGE_REACTION_REMOVE` map to common `MessageReactionEvent`. Live gateway evidence is pending. |
|
||||
| `group.member_joined` | unit | `GUILD_MEMBER_ADD` and `GROUP_MEMBER_ADD` map to common `MemberJoinedEvent` when the gateway payload carries a group/guild/channel ID and member openid. |
|
||||
| `group.member_left` | unit | `GUILD_MEMBER_REMOVE` and `GROUP_MEMBER_REMOVE` map to common `MemberLeftEvent`. Live gateway evidence is pending. |
|
||||
| `bot.invited_to_group` | unit | `GUILD_CREATE` and `GROUP_ADD_ROBOT` map to common `BotInvitedToGroupEvent`. |
|
||||
| `bot.removed_from_group` | unit | `GUILD_DELETE` and `GROUP_DEL_ROBOT` map to common `BotRemovedFromGroupEvent`. |
|
||||
| `platform.specific` | unit | Unmapped gateway events are emitted as structured `PlatformSpecificEvent`; live evidence is pending. |
|
||||
|
||||
## Full-group messages
|
||||
|
||||
After a group owner enables QQ's "receive all messages" permission, QQ delivers
|
||||
`GROUP_MESSAGE_CREATE`, including messages that mention the bot. Both the EBA
|
||||
and legacy adapters accept this event over WebSocket and unified Webhook, retain
|
||||
the sender's `member_openid` (with the older `openid` alias as fallback), and use
|
||||
the original message ID for passive group replies.
|
||||
|
||||
Ordinary messages and images do not receive a bot `At` component. A full-group
|
||||
message receives that component only when QQ supplies a boolean `mentions[].is_you`
|
||||
equal to `true` and a matching native `<@ID>` or `<@!ID>` token in its text. Only
|
||||
the bot's own token is removed; mentions of other members remain text. Nicknames,
|
||||
`bot: true` alone, and a text that looks like a mention do not authorize a reply.
|
||||
The EBA component targets the adapter's configured bot account so existing
|
||||
`is_at_bot` route filters continue to match.
|
||||
|
||||
Default EBA group routes requiring `is_at_bot` still exclude unmentioned group
|
||||
messages. Custom event routes or plugin subscriptions may opt into ordinary
|
||||
messages. This change does not alter QQ permissions, existing bot configuration,
|
||||
event bindings, or plugin subscriptions.
|
||||
|
||||
`tests/unit_tests/platform/test_qqofficial_full_group_messages.py` exercises the
|
||||
real adapters and shared QQ parser with external gateway/download/send transports
|
||||
substituted. It covers text, images, self/other/unverified mentions, sender aliases,
|
||||
legacy @-only mode, private messages, and passive reply targets. This is protocol
|
||||
regression coverage, not a claim of a fresh live QQ probe of the whole upstream build.
|
||||
|
||||
## Common APIs
|
||||
|
||||
| API | Evidence | Notes |
|
||||
| --- | --- | --- |
|
||||
| `send_message` | unit, blocked | Sends private C2C, group, and text-only channel messages through the existing QQ Official client. Live outbound UI verification is pending because the test pipeline failed before producing a bot response. |
|
||||
| `reply_message` | unit, blocked | Replies using the source `QQOfficialEvent` message ID when available. Live reply was blocked by the test environment model service returning `model_not_found`. |
|
||||
| `get_message` | unit | Returns cached inbound `MessageReceivedEvent`. |
|
||||
| `get_user_info` | unit | Returns cached inbound sender. |
|
||||
| `get_friend_list` | unit | Returns cached private senders. |
|
||||
| `get_group_info` | unit | Returns cached group/channel metadata from inbound events. |
|
||||
| `get_group_member_info` | unit | Returns cached group sender as a common member. |
|
||||
| `get_group_member_list` | unit | Returns cached group members observed by the adapter. |
|
||||
| `call_platform_api` | unit, blocked | Safe diagnostic actions are implemented; live calls are pending credentials. |
|
||||
|
||||
## Platform APIs
|
||||
|
||||
| Action | Evidence | Notes |
|
||||
| --- | --- | --- |
|
||||
| `check_access_token` | unit, blocked | Calls the existing client token check. |
|
||||
| `refresh_access_token` | unit, blocked | Forces token refresh. |
|
||||
| `get_gateway_url` | unit, blocked | Fetches the WebSocket gateway URL. |
|
||||
| `get_mode` | unit | Returns webhook and stream-reply mode. |
|
||||
|
||||
## Components
|
||||
|
||||
| Receive Component | Evidence | Notes |
|
||||
| --- | --- | --- |
|
||||
| `Source` | unit | Uses QQ message/event IDs and timestamp. |
|
||||
| `Plain` | unit | Preserves text content. |
|
||||
| `At` | unit | Group and channel mention events insert an adapter bot mention marker. |
|
||||
| `Image` | unit | QQ image attachment URL is converted to common `Image`; falls back to URL if download fails. |
|
||||
| `Unknown` | unit | Unsupported/empty native payloads become `Unknown`. |
|
||||
| `Voice`, `File`, `Quote`, `Face`, `Forward`, mixed chain | blocked | Current native parser only exposes text and image attachments; live endpoint behavior still needs verification. |
|
||||
|
||||
| Send Component | Evidence | Notes |
|
||||
| --- | --- | --- |
|
||||
| `Plain` | unit, blocked | Sends through private, group, or channel text APIs. |
|
||||
| `At`, `AtAll` | unit, blocked | Converted to readable mention text. |
|
||||
| `Image` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
|
||||
| `Voice` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
|
||||
| `File` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
|
||||
| `Quote`, `Forward`, mixed chain | unit, blocked | Flattened to ordered send payloads where possible. |
|
||||
| `Face` | not-supported | No common QQ Official face mapping is implemented. |
|
||||
|
||||
## Verification Record
|
||||
|
||||
Test date: 2026-06-02
|
||||
|
||||
Endpoint/simulator: `dev.rockchin.top` with a real QQ Official WebSocket bot (`qqofficial-omni`, bot UUID `80a5560b-52b1-40e7-b7d6-4a2341eb4780`) and LangBot running from `/home/wgc/LangBotxg/LangBotEbaTest`.
|
||||
|
||||
Observed evidence:
|
||||
|
||||
- The QQ Official WebSocket bot was enabled with `enable-webhook=false`.
|
||||
- A real user message reached LangBot and entered the standard pipeline path.
|
||||
- The response path stopped at the model layer with `model_not_found` for `deepseek-v3`; this is a model/provider configuration issue, not an adapter conversion failure.
|
||||
- `qq-webhook.langbot.dev` was temporarily routed through Caddy to `127.0.0.1:5301` for webhook checks, but the observed EBA bot used WebSocket mode.
|
||||
|
||||
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_qqofficial_eba_probe.py
|
||||
QQOFFICIAL_APPID=... QQOFFICIAL_SECRET=... QQOFFICIAL_TOKEN=... uv run python tests/e2e/live_qqofficial_eba_probe.py
|
||||
```
|
||||
|
||||
Webhook-mode probe:
|
||||
|
||||
```bash
|
||||
QQOFFICIAL_APPID=... QQOFFICIAL_SECRET=... QQOFFICIAL_TOKEN=... uv run python tests/e2e/live_qqofficial_eba_probe.py --webhook --host 0.0.0.0 --port 5312
|
||||
```
|
||||
|
||||
Evidence JSONL path: `data/temp/qqofficial_eba_probe.jsonl` for direct adapter live probe; plugin E2E evidence should use `data/temp/qqofficial_eba_plugin_probe.jsonl`.
|
||||
|
||||
Destructive operations: none implemented.
|
||||
|
||||
Blocked items:
|
||||
|
||||
- `plugin-e2e-ui`: standalone probe plugin JSONL evidence is still pending; the observed live run reached LangBot core/pipeline but was not recorded by the EBA probe plugin.
|
||||
- `plugin-e2e-outbound`: waiting for visible QQ client verification of plugin `send_message`/`reply_message` output after a working model/provider is configured.
|
||||
- Inbound non-text media and platform lifecycle events require endpoint evidence before they can be marked complete.
|
||||
@@ -0,0 +1,84 @@
|
||||
# Slack EBA Adapter
|
||||
|
||||
## Structure
|
||||
|
||||
Slack is migrated into `src/langbot/pkg/platform/adapters/slack/` with the standard EBA adapter layout:
|
||||
|
||||
- `adapter.py` owns lifecycle, listener dispatch, unified webhook handling, outbound send/reply, and event caches.
|
||||
- `event_converter.py` maps Slack `im` and `app_mention` channel events to `message.received`.
|
||||
- `message_converter.py` maps common `MessageChain` components to Slack text fallback and maps inbound Slack text/image payloads back to EBA components.
|
||||
- `api_impl.py` provides cache-backed common read APIs.
|
||||
- `platform_api.py` declares safe Slack-specific API actions.
|
||||
- `manifest.yaml` declares `slack-omni`.
|
||||
|
||||
The legacy `src/langbot/pkg/platform/sources/slack.py` adapter is kept unchanged.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Field | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| `webhook_url` | No | Generated by LangBot. Paste it into Slack Event Subscriptions. |
|
||||
| `bot_token` | Yes | Slack bot token, usually `xoxb-...`. |
|
||||
| `signing_secret` | Yes | Slack app signing secret. |
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Notes |
|
||||
|-------|-------|
|
||||
| `message.received` | Emitted for private `im` messages and channel `app_mention` events. Channel messages are mapped to group chats. |
|
||||
| `platform.specific` | Reserved for Slack event types that are not converted into common message events. |
|
||||
|
||||
## Common APIs
|
||||
|
||||
Required:
|
||||
|
||||
- `send_message`
|
||||
- `reply_message`
|
||||
|
||||
Optional:
|
||||
|
||||
- `get_message`
|
||||
- `get_user_info`
|
||||
- `get_friend_list`
|
||||
- `get_group_info`
|
||||
- `get_group_list`
|
||||
- `get_group_member_list`
|
||||
- `get_group_member_info`
|
||||
- `call_platform_api`
|
||||
|
||||
Cache-backed APIs are only available after the relevant inbound event has been observed.
|
||||
|
||||
## Platform APIs
|
||||
|
||||
| Action | Notes |
|
||||
|--------|-------|
|
||||
| `get_mode` | Returns webhook mode and configured bot account id. |
|
||||
| `auth_test` | Calls Slack `auth.test` with the configured bot token. |
|
||||
|
||||
## Known Limits
|
||||
|
||||
- Slack file/image outbound is currently represented as text fallback because the existing Slack SDK wrapper only exposes `chat_postMessage`.
|
||||
- Inbound channel coverage follows the legacy adapter behavior: only `app_mention` events are treated as group messages.
|
||||
- Real live testing requires a public callback URL configured in Slack Event Subscriptions.
|
||||
|
||||
## Verification
|
||||
|
||||
Local mocked unit coverage validates manifest parity, event conversion, legacy listener compatibility, cache-backed APIs, send/reply routing, and declared platform APIs.
|
||||
|
||||
Plugin E2E evidence was captured on June 2, 2026 against `dev.rockchin.top` with Slack private DM input and `EBAEventProbe` through the standalone runtime.
|
||||
|
||||
Evidence file: `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/slack_eba_plugin_probe.jsonl`.
|
||||
|
||||
Observed:
|
||||
|
||||
- Real Slack private text produced `MessageReceived` with `adapter_name=slack-omni`, `Source + Plain`, private chat type, and filled `bot_uuid`.
|
||||
- Safe common APIs passed: `get_message`, `get_user_info`, `get_friend_list`.
|
||||
- Outbound component fallback sweep passed through `send_message`: plain/at/face, image, quote, file, and forward.
|
||||
- Declared Slack platform APIs passed: `get_mode`, `auth_test`.
|
||||
|
||||
Still pending:
|
||||
|
||||
- Channel `app_mention` plugin E2E.
|
||||
- Real inbound Slack file/image UI evidence.
|
||||
|
||||
Live probe scaffold: `tests/e2e/live_slack_eba_probe.py`.
|
||||
@@ -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-omni`.
|
||||
|
||||
## 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.
|
||||
@@ -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-omni`.
|
||||
|
||||
This record covers the regular WeCom application-message adapter. WeCom AI Bot (`wecombot-omni`) 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-omni`
|
||||
- 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-omni`, 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.
|
||||
@@ -0,0 +1,158 @@
|
||||
# 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-omni`.
|
||||
|
||||
This is separate from regular WeCom internal applications (`wecom-omni`). WeComBot supports WebSocket long connection mode, which does not require a webhook URL. Webhook mode remains available when `enable-webhook=true`.
|
||||
|
||||
## AI Interactions
|
||||
|
||||
In WebSocket mode, `interaction.request` renders actions as a
|
||||
`button_interaction` template card. A single `select` field renders as a native
|
||||
`multiple_interaction` dropdown with a Submit button (up to 10 options). The
|
||||
callback's `selected_items.selected_item[].option_ids.option_id` carries the
|
||||
selected option ID, as documented in the WeCom AI Bot event protocol. The Host
|
||||
resolves the original option value from its persisted interaction request.
|
||||
Webhook mode does not offer this proactive card API.
|
||||
|
||||
## 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-omni`
|
||||
- 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-omni`, 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.
|
||||
@@ -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-omni`. It is separate from regular WeCom application messages (`wecom-omni`) and WeCom AI Bot (`wecombot-omni`).
|
||||
|
||||
## 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-omni`
|
||||
- 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.
|
||||
Reference in New Issue
Block a user