SendDSL详解
Tip
什么时候需要读这篇:适配器开发路径内必读(发送 DSL)。不需要则跳过,不影响其它功能的使用。
SendDSL 让消息发送串成一条链完成:指定目标、@ / 回复、重试 / 超时 / 延迟、批量发送,一行链式调用搞定。本篇覆盖发送方法、修饰方法、发送规则与发送链路的内部机制。
基本调用方式
1. 指定类型和ID
await adapter.Send.To("group", "123").Text("Hello")
2. 仅指定ID
await adapter.Send.To("123").Text("Hello")
3. 指定发送账号
await adapter.Send.Using("bot1").Text("Hello")
4. 组合使用
await adapter.Send.Using("bot1").To("group", "123").Text("Hello")
方法链
flowchart LR
A["Using / Account<br/>(选发送账号,可选)"] --> B["To<br/>(选目标类型与 ID)"]
B --> C["修饰方法<br/>At / Reply / Expire / ForMember 等"]
C --> D["发送方法<br/>Text / Image / Voice / Video / File / Location / Raw_ob12"]
D --> E["返回 asyncio.Task"]
发送方法
所有发送方法返回 asyncio.Task 对象。
基本方法(基类内置)
以下标准方法已由 SendDSL 基类内置实现,**默认委托给 Raw_ob12**,适配器子类无需重复实现即可直接使用,且 IDE 能补全:
| 方法名 | 说明 | 返回值 |
|---|---|---|
Text(text: str) |
发送文本消息 | asyncio.Task |
Image(file: bytes | str) |
发送图片 | asyncio.Task |
Voice(file: bytes | str) |
发送语音(OneBot12 audio 段) |
asyncio.Task |
Video(file: bytes | str) |
发送视频 | asyncio.Task |
File(file: bytes | str, filename: str = None) |
发送文件 | asyncio.Task |
Location(latitude: float, longitude: float, title: str = "", content: str = "") |
发送位置消息(OneBot12 location 段) |
asyncio.Task |
适配器可覆盖单个标准方法以提供平台特定逻辑:
class Send(SendDSL):
def Raw_ob12(self, message, **kwargs):
# 必须实现
...
# 可选:覆盖 Text 以提供平台特定逻辑
# def Text(self, text: str):
# return self.Raw_ob12([{"type": "text", "data": {"text": text}}])
协议方法
| 方法名 | 说明 | 返回值 | 是否必须 |
|---|---|---|---|
Raw_ob12(message) |
发送 OneBot12 格式消息 | asyncio.Task |
必须实现 |
重要:
Raw_ob12是适配器的核心方法,必须实现。它是反向转换(OneBot12 → 平台)的统一入口。未实现时基类会记录 error 日志并返回标准错误响应(status: "failed",retcode: 10002)。标准方法(Text、Image等)默认委托给Raw_ob12。
平台特有方法
适配器可在 Send 子类中添加平台特有的发送方法(会被 event.supports() / event.available_methods() 识别):
class Send(SendDSL):
def Raw_ob12(self, message, **kwargs): ...
# 平台特有方法
def Sticker(self, sticker_id: str):
return self.Raw_ob12([{"type": "sticker", "data": {"id": sticker_id}}])
修饰方法
修饰方法返回 self 以支持链式调用。
At 方法
# @单个用户
await adapter.Send.To("group", "123").At("456").Text("你好")
# @多个用户
await adapter.Send.To("group", "123").At("456").At("789").Text("你们好")
AtAll 方法
# @全体成员
await adapter.Send.To("group", "123").AtAll().Text("大家好")
Reply 方法
# 回复消息
await adapter.Send.To("group", "123").Reply("msg_id").Text("回复内容")
组合修饰
await adapter.Send.To("group", "123").At("456").Reply("msg_id").Text("回复@的消息")
平台专有修饰方法
除了内置的 At/AtAll/Reply,适配器可以定义平台专有的修饰方法。这类方法**只需返回 self**,无需任何装饰器——框架会自动识别:
- 返回
self(SendDSL 实例)→ 修饰方法,不触发发送包装/生命周期事件,链式继续 - 返回
Task/Awaitable→ 发送方法
class Send(SendDSL):
def Raw_ob12(self, message, **kwargs): ...
# 修饰方法:返回 self,不发送
def Expire(self, seconds: int):
self._expire = seconds
return self
def ForMember(self, user_id: str):
self._member = user_id
return self
# 发送方法:返回 Task,依赖修饰方法设置的状态
def Board(self, content: str, **kwargs):
return self.Raw_ob12([{"type": "board", "data": {"text": content}}])
使用:
# 修饰方法可连续链式叠加
await adapter.Send.To("group", "big").Expire(3600).ForMember("114").Board("看板内容")
在 Event 包装类中使用修饰方法
Note
reply(via=) 与 event.send_chain() 本特性需要 ErisPulse **2.7.0+**。
event.reply() 默认只暴露 at_sender/at_users/at_all/quote 等内置修饰参数。要使用平台专有修饰方法,有两种方式:
方式一:reply() 的 via 参数
适合少量、已知的修饰方法:
await event.reply("看板内容", method="Board",
via=[("Expire", 3600), ("ForMember", "114514")])
via 是一个列表,每个元素可为:
| 形式 | 等价链式调用 |
|---|---|
"Name" |
.Name() |
("Name", arg1, arg2) |
.Name(arg1, arg2) |
("Name", (arg1,), {kw: val}) |
.Name(arg1, kw=val) |
方式二:event.send_chain()
适合连续多个修饰方法或无内容参数的动作型方法(如撤回、删除)。send_chain() 返回已配置好 To/Using 的发送链,可自由追加任意修饰方法和发送方法:
# 平台专有修饰方法 + 看板发送
await event.send_chain().Expire(3600).Board("一小时后过期")
# 连续多个修饰方法
await (event.send_chain()
.Expire(3600)
.ForMember("114514")
.Board("看板内容", content_type="markdown"))
# 内置修饰方法同样可用
await event.send_chain().At("123").Reply("msg_id").Text("hi")
# 无内容参数的动作型方法
await event.send_chain().DismissBoard()
send_chain()返回的是完整的 SendDSL 实例,因此所有链式特性都可用——不仅是修饰方法,还包括发送规则和批量构建:
# 发送规则:重试 + 超时 + 成功回调
await (event.send_chain()
.Retry(3).Timeout(10)
.Hook(lambda r: print("发送成功"))
.Text("可靠发送"))
# 延迟发送 + 平台修饰 + 看板
await event.send_chain().Defer(5).Expire(3600).Board("延迟看板")
# 批量构建模式
results = await (event.send_chain()
.Build()
.Text("第一句").Image("pic.jpg").Text("第二句")
.send_all())
账户管理
Using 方法
Using() 用于指定发送消息的账户。传入的标识符按以下优先级匹配到具体账户(解析由框架自动完成):
- 账户名 — 配置中的键名(如
"default"、"bot1") bot_id字段 — 账户配置中的bot_id字段(运行期由适配器回填,通常即机器人的self.user_id)- 任意 str 字段 — 配置中其他字符串字段
- 兜底 — 第一个启用的账户
# 使用账户名
await adapter.Send.Using("account1").To("user", "123").Text("Hello")
# 使用 bot_id(通常即事件中的 self.user_id)
await adapter.Send.Using("bot_123").To("user", "123").Text("Hello")
处理事件的链路内未显式
Using()时,框架自动绑定触发事件的账户(见无感语法糖);定时器 / 启动任务等无事件上下文场景走默认账户。
Account 方法
Account 方法与 Using 等价:
await adapter.Send.Account("account1").To("user", "123").Text("Hello")
异步处理
不等待结果
# 消息在后台发送
task = adapter.Send.To("user", "123").Text("Hello")
# 继续执行其他操作
# ...
等待结果
# 直接 await 获取结果
result = await adapter.Send.To("user", "123").Text("Hello")
print(f"发送结果: {result}")
# 先保存 Task,稍后等待
task = adapter.Send.To("user", "123").Text("Hello")
# ... 其他操作 ...
result = await task
发送规则系统
SendDSL 内置了一套发送规则装饰器,通过链式方法附加规则,在最终发送时统一应用。规则覆盖常见的生产场景:超时控制、失败重试、成功回调、延迟发送、优先级丢弃、进度监控。
规则方法返回 self(与 At/AtAll/Reply 一样),必须放在发送方法(Text/Image 等)之前调用。规则会随 To/Using/Account 创建的新实例传播。
规则方法一览
| 方法 | 说明 |
|---|---|
.Hook(callback) |
发送成功后执行的回调(可多次调用,按顺序执行) |
.Retry(times=1) |
失败自动重试 N 次(含首次共 N+1 次) |
.Timeout(seconds) |
单次发送超时,超时取消当前尝试(可与 Retry 叠加) |
.Defer(seconds=1.0) |
延迟发送(进程内定时,不持久化) |
.Priority(level, drop_if_busy=False) |
设置优先级;积压时可丢弃 |
.OnProgress(callback) |
各阶段进度回调(传入 SendContext) |
.OnError(callback) |
最终失败时的错误回调(仅触发一次) |
发送成功后执行逻辑(Hook)
# 同步回调
await (adapter.Send.To("user", "123")
.Hook(lambda r: print(f"发送成功,消息ID: {r['message_id']}"))
.Text("你好"))
# 异步回调
async def deduct_points(result):
await db.update(user_id="123", points=-1)
await adapter.Send.To("user", "123").Hook(deduct_points).Text("扣积分")
Hook 仅在发送最终成功(含重试成功)时执行;失败、超时、取消不触发。
失败自动重试(Retry)
# 首次失败后重试 2 次,共 3 次尝试
result = await adapter.Send.To("user", "123").Retry(2).Text("带重试")
重试触发条件:发送抛出异常、发送超时、发送返回 status == "failed" 的响应。
超时自动取消(Timeout)
# 单次发送超过 10 秒则取消
await adapter.Send.To("user", "123").Timeout(10).Text("带超时")
# 超时 + 重试:每次尝试 10 秒,最多 3 次
await adapter.Send.To("user", "123").Timeout(10).Retry(2).Text("超时重试")
进度监控(OnProgress / OnError)
def on_progress(ctx):
print(f"阶段: {ctx.stage}, 尝试: {ctx.attempt + 1}/{ctx.max_attempts}, 耗时: {ctx.elapsed:.2f}s")
if ctx.stage == "failed":
print(f" 错误: {ctx.error!r}")
async def on_error(ctx):
await notify_admin(f"发送给 {ctx.target_id} 失败: {ctx.error!r}")
await (adapter.Send.To("user", "123")
.Retry(3).Timeout(10)
.OnProgress(on_progress)
.OnError(on_error)
.Text("监控"))
SendContext 包含的字段:task_id、platform、method、target_type、target_id、bot_id、stage、attempt、max_attempts、started_at、finished_at、elapsed、error、result、extra。
stage 可能的值:pending、sending、retrying、success、failed、timeout、cancelled、dropped。
延迟发送(Defer)
# 5 秒后发送
await adapter.Send.To("user", "123").Defer(5).Text("迟到消息")
注意:延迟为进程内定时,进程重启会丢失,不提供持久化。
优先级与积压丢弃(Priority)
# 低优先级消息,队列积压时自动丢弃
result = await (adapter.Send.To("user", "123")
.Priority(-1, drop_if_busy=True)
.Text("可放弃的通知"))
# 若被丢弃,result["status"] == "failed"
drop_if_busy 启用后,当在途发送任务数超过阈值(默认 64)时直接放弃本次发送。可通过 .PriorityThreshold(n) 调整全局阈值。
规则组合与后台执行
# 不阻塞主流程,规则照样生效
task = (adapter.Send.To("user", "123")
.Hook(lambda r: print("发送成功!"))
.Retry(3)
.Timeout(10)
.OnProgress(on_progress)
.Text("你好"))
# 继续执行其他操作
await handle_next_action()
规则传播
规则随 To/Using/Account 创建的新实例传播,避免链式调用中规则丢失:
# 规则在 To 之前设置,也会传播到 To 创建的实例
builder = adapter.Send.Retry(3).Timeout(10)
send = builder.To("user", "123") # send 仍携带 Retry(3) 和 Timeout(10)
await send.Text("hi")
多个实例的规则相互独立(hooks 列表深拷贝)。
批量构建模式(Build)
除单发模式外,SendDSL 还支持批量构建模式:一条链路中写多个发送方法,最后统一执行。适用于“一口气发多条消息”的场景。
进入构建模式
在发送方法之前调用 .Build(),返回 SendBuilder。此后发送方法(Text/Image 等)不再立即执行,而是累积为发送意图:
results = await (adapter.Send.To("user", "123")
.Build() # 进入构建模式
.Text("第一句")
.Image("pic.jpg")
.Text("第二句")
.send_all()) # 统一执行
# results = [Text结果, Image结果, Text结果]
.send_all() 返回 asyncio.Task,await 后得到结果列表(按意图顺序)。
并行与串行
默认并行执行(并发发送,总耗时约等于最慢的一条)。需要保证消息到达顺序时调用 .Sequential():
# 串行:按顺序依次发送
await (adapter.Send.To("group", "456")
.Build()
.Sequential()
.Text("先发这个").Text("再发这个")
.send_all())
# 并行(默认,可显式调用)
await (adapter.Send.To("group", "456")
.Build()
.Parallel()
.Text("并发1").Text("并发2")
.send_all())
失败继续与重试
批量执行采用失败继续策略:某条失败不会中断其他条的发送。配合 .Retry() 时,失败的条目会自动重试(重试作用于单条,不是重试整批):
await (adapter.Send.To("user", "123")
.Build()
.Retry(2) # 每条各自重试 2 次
.Text("可能失败的").Image("也可能失败的")
.send_all())
整批规则与回调
规则统一作用于整批:
| 方法 | 说明 |
|---|---|
.Timeout(seconds) |
每条发送的单次超时 |
.Retry(times) |
每条发送各自重试(失败继续) |
.Defer(seconds) |
延迟整批发送 |
.Hook(callback) |
整批全部成功后触发,接收 results 列表 |
.OnError(callback) |
批次存在失败时触发,接收 BatchContext |
.OnProgress(callback) |
每条完成时触发,接收 BatchContext |
def on_progress(ctx):
print(f"进度: {ctx.completed}/{ctx.total}, 成功 {ctx.succeeded}, 失败 {ctx.failed}")
async def on_error(ctx):
print(f"批次有 {ctx.failed} 条失败")
results = await (adapter.Send.To("user", "123")
.Build()
.Retry(2).Timeout(10)
.OnProgress(on_progress)
.OnError(on_error)
.Hook(lambda rs: print("整批完成"))
.Text("a").Text("b").Text("c")
.send_all())
BatchContext 包含:task_id、total、completed、succeeded、failed、stage、results、errors、elapsed、extra。
stage 可能的值:pending、sending、success(全部成功)、partial(部分成功)、failed(全部失败)。
修饰器与规则的继承
.Build() 之前的 At/AtAll/Reply 修饰器和规则会继承到整批,作用于每条消息:
await (adapter.Send.To("group", "456")
.At("789") # 继承:每条消息都 @789
.Build()
.Retry(2) # 继承 + 追加:每条各自重试
.Text("@你的通知")
.Image("公告图")
.send_all())
进入 Build 后仍可追加修饰器(作用于整批):
await (adapter.Send.To("group", "456")
.Build()
.At("111").At("222") # 追加 @,作用于整批
.Text("@多人")
.send_all())
后台执行
与单发一样,.send_all() 返回 Task,可不 await 让其在后台执行:
task = (adapter.Send.To("user", "123")
.Build()
.Hook(lambda rs: print("批量发送完成"))
.Text("a").Text("b")
.send_all())
# 不阻塞主流程
await do_something_else()
命名规范
PascalCase 命名
所有发送方法使用大驼峰命名法:
# ✅ 正确
def Text(self, text: str):
pass
def Image(self, file: bytes):
pass
# ❌ 错误
def text(self, text: str):
pass
def send_image(self, file: bytes):
pass
平台特有方法
不推荐添加平台前缀方法:
# ✅ 推荐
def Sticker(self, sticker_id: str):
pass
# ❌ 不推荐
def TelegramSticker(self, sticker_id: str):
pass
使用 Raw 方法替代:
# ✅ 推荐
await adapter.Send.Raw_ob12([{"type": "sticker", ...}])
# ❌ 不推荐
def TelegramSticker(self, ...):
pass
Внутренняя структура отправки сообщения
За кулисами выполнения await adapter.Send.To("group", "123").Text("x") фреймворк делает следующие вещи:
flowchart TD
A["adapter.Send.To(...).Text(...)"] --> B["Цепочка методов To/Using<br/>Возвращает неизменяемый новый экземпляр (порядок не имеет значения)"]
B --> C["Перехват метода __getattribute__<br/>Оборачивает метод отправки"]
C --> D["Вызов оригинального метода (например, Text)<br/>Внутренне делегирует Raw_ob12"]
D --> E["Raw_ob12 возвращает asyncio.create_task(...)"]
E --> F["Запись лога [Send]"]
F --> G["emit message.sending (fire-and-forget)"]
G --> H{"Определены правила отправки?"}
H -->|"Нет"| I["done_callback задачи → emit message.sent"]
H -->|"Да"| J["apply_send_rules оборачивает внешней задачей<br/>Повтор, таймаут, задержка, приоритет"]
J --> I
I --> K["await возвращает стандартный словарь ответа"]
Что делает фреймворк на каждом этапе:
| Этап | Что делает фреймворк |
|---|---|
| Цепочка объединения | Каждый вызов To/Using/Account создает неизменяемый новый экземпляр и наследует уже установленные поля, поэтому To(...).Using(...) и Using(...).To(...) эквивалентны, порядок не имеет значения |
| Оборачивание метода | Методы отправки (Text и др.) перехватываются __getattribute__ и оборачиваются; методы-декораторы (To/Using/At/Retry и др.) не оборачиваются. Вложенные вызовы Raw_ob12 предотвращают дублирование обёрток с помощью маркировки _in_rule_wrap |
| Создание задачи | Raw_ob12 внутри использует asyncio.create_task() для создания задачи; Text() просто синхронно возвращает эту задачу, не блокируя |
| Лог отправки | Записывается событие лога [Send] platform/method -> target (можно отключить с помощью exclude_levels=["EVENT"]) |
message.sending |
Метод отправки вызывается немедленно в режиме fire-and-forget (только при наличии слушателей, сначала short-circuit с has_handlers) |
message.sent |
Привязывается к done_callback задачи — результат завершения всего процесса повторов при наличии правил, в противном случае — просто завершение исходной задачи |
Цепочка разрешения аккаунта
Идентификатор аккаунта, заданный явно через Using() (включая автоматически вставленный event.reply()), или аккаунт, привязанный автоматически в цепочке событий, разрешается в конкретный аккаунт в следующем порядке:
- Одиночный аккаунт адаптера (без
AccountConfigClass) → возвращается напрямую - Точное совпадение по
account_id - Совпадение по полю
bot_idкаждого аккаунта - Совпадение по любому строковому значению поля аккаунта (исключая
enabled/name) - Резервный аккаунт: первый включенный аккаунт (если
account_idне передан, используется по умолчанию; если переданныйaccount_idне может быть разрешен, записывается WARNING и используется по умолчанию (WARNING содержитplatform/account_id/accountдля определения источника событий, не привязанных к аккаунту)) - Нет включенных аккаунтов (все аккаунты отключены) → выбрасывается
ValueError: нет аккаунта для отправки
account_id, который вы передаете, берется из: явного указания вUsing()(включая автоматически вставленныйself.user_id/self.account_idвevent.reply()) > резервной привязки в цепочке событий (для отправки без явного указания аккаунта, привязывается аккаунт, вызвавший событие) > не указывается (используется аккаунт по умолчанию, для сценариев без контекста события, таких как таймеры / задачи запуска).
Незаметные синтаксические улучшения
«Автоматическое использование
Using()в цепочке событий» и «маршрутизация по имени аккаунта» требуют ErisPulse 2.12+.
| Синтаксический сахар | Условия | Эффект |
|---|---|---|
Автоматическое использование Using() в цепочке событий |
Вызов Send / Api / Request в цепочке обработки события |
Автоматически привязывается аккаунт, вызвавший событие (контекст ввода, send_context / api_context / request_context) |
Автоматическая ссылка в reply() |
quote=True |
Автоматически берется message_id события для создания Reply |
Автоматическая привязка аккаунта в reply() |
В цепочке reply |
Автоматически Using(self.account_id or self.user_id) — имя аккаунта может быть напрямую разрешено |
| Маршрутизация по имени аккаунта | Динамический аккаунт не получил user_id |
self.account_id события = имя аккаунта → имя аккаунта разрешается в правильный аккаунт |
| Резервный аккаунт по умолчанию | Без контекста события (таймеры / задачи запуска) | Первый включенный аккаунт (семантика по умолчанию не меняется) |
Двигатель правил отправки (повтор/таймаут/задержка)
Правила оборачиваются в новую внешнюю задачу после возврата задачи из Raw_ob12, не влияя на основной процесс. Ключевые факты:
| Правило | Описание |
|---|---|
Retry(n) |
Общее количество попыток n+1; повтор сразу после неудачи, без экспоненциальной задержки |
Timeout(s) |
Один отправка с таймаутом (используется asyncio.wait_for), если не исчерпаны попытки, повторяется |
Defer(s) |
Задержка перед отправкой |
Priority(level, drop_if_busy) |
Если накоплено больше порога, возвращает {status:"failed", retcode:10002, message:"dropped_low_priority"} |
Hook(fn) |
Выполняется только при успешном завершении |
on_progress / on_error |
Коллбэки на разных этапах / при неудаче |
Внимание: Повторы — это «немедленная повторная отправка», без задержек; если платформа требует задержки из-за лимитов, нужно вручную добавить
sleepвon_errorи повторно отправить. Успех правила определяется по значениюstatus == "ok"в возвращаемом словаре (такжеretcode == 0).
Полный формат стандартного ответа и семантика
retcodeсм. в спецификации API-ответа.
返回值
Task 对象
所有发送方法返回 asyncio.Task。适配器只需实现 Raw_ob12,标准方法(Text/Image 等)默认委托给它:
import asyncio
def Raw_ob12(self, message, **kwargs):
async def _do_send():
segments = self._apply_modifiers(message)
return await self._adapter.call_api(
endpoint="/send_message",
message=segments,
**self.send_context,
**kwargs,
)
return asyncio.create_task(_do_send())
# Text/Image/Voice/Video/File/Location 已从基类继承,自动委托给 Raw_ob12
# 如需覆盖标准方法,返回 asyncio.Task 即可:
# def Text(self, text: str):
# return self.Raw_ob12([{"type": "text", "data": {"text": text}}])
标准化响应
call_api 应返回标准化响应。推荐使用 make_response() / make_error() 方法:
async def call_api(self, endpoint: str, **params):
try:
# _do_api_call 为适配器自行实现的平台请求(示例占位)
result = await self._do_api_call(endpoint, **params)
return self.make_response(
data=result.get("data"),
message_id=result.get("message_id", ""),
raw=result,
)
except Exception as e:
return self.make_error(message=str(e))
也支持手动构造(旧版方式仍然兼容):
async def call_api(self, endpoint: str, **params):
return {
"status": "ok" or "failed",
"retcode": 0 or error_code,
"data": {...},
"message_id": "msg_id" or "",
"message": "",
"{platform}_raw": raw_response
}
完整示例
基本使用
from ErisPulse.Core import adapter
my_adapter = adapter.get("myplatform")
# 发送文本
await my_adapter.Send.To("user", "123").Text("Hello World!")
# 发送图片
await my_adapter.Send.To("group", "456").Image("https://example.com/image.jpg")
# 发送文件
with open("document.pdf", "rb") as f:
await my_adapter.Send.To("user", "123").File(f.read())
链式调用
# @用户 + 回复
await my_adapter.Send.To("group", "456").At("789").Reply("msg123").Text("回复@的消息")
# @全体 + 多个修饰
await my_adapter.Send.Using("bot1").To("group", "456").AtAll().Text("公告消息")
原始消息与消息构建
Raw_ob12 是反向转换的核心入口(接收 OB12 消息段 → 平台 API 调用),MessageBuilder 是配合其使用的链式消息段构建工具。
完整的
Raw_ob12实现规范、MessageBuilder用法及代码示例请参阅:
相关文档
继续适配器开发路径
遵循正式规范
- 发送方法规范 - 发送方法完整规范(
Raw_ob12实现与MessageBuilder)