ErisPulse.Core.Bases.adapter 模块
模块概述
ErisPulse 适配器基础模块
提供适配器和消息发送DSL的基类实现
提示
- 用于实现与不同平台的交互接口
- 提供统一的消息发送DSL风格接口
函数列表
_action_denied_response(adapter: 'BaseAdapter', action: str)
内部方法 构造"出站动作被控制面禁用"的标准失败响应(已完成的 task)
被禁用的出站调用不发起任何网络请求,直接返回该响应。 SendDSL / ApiDSL / RequestDSL 在授权闸口处调用。
- adapter: 适配器实例(用于 make_error 构造标准响应)
- action: 被禁用的动作类型(send / api / request)
返回值: asyncio.Task(已完成,值为标准错误响应)
async _noop_async(value)
内部方法 立即返回值的协程(用于构造已完成 task)
_has_rules(send_dsl: 'SendDSL') -> bool
判断 SendDSL 实例是否附加了发送规则
- send_dsl (
SendDSL): 实例
返回值: 是否存在任意已设置的规则
_copy_rules(rules: dict) -> dict
复制规则字典(深拷贝可变值,如 hooks 列表)
用于 To/Using/Account 创建新实例时避免共享可变状态。 标量值(retry/timeout/defer 等)浅拷贝即可, 仅 hooks 列表需要创建新列表。
- rules: 原始规则字典
返回值: 独立的规则字典副本
_wrap_to_task(result: Any)
将任意返回值包装为 Task(用于重试路径的兼容处理)
- result: 原始方法返回值
返回值: asyncio.Task
_append_send_receipt(ledger: list, response: Any, ctx: dict) -> None
内部方法 从发送响应提取回执并记入消息事务账本
仅当响应为 dict 且含非空 message_id 时记录(标准 API 响应格式);
消息事务撤回时按账本逆序调用适配器 delete_message。
- ledger: 当前事务的账本列表(send_receipts ContextVar 值)
- response: 发送方法返回的响应(标准格式为 dict)
- ctx: 发送上下文(platform / bot_id / trace_id 等)
_wrap_send_method(method_name: str, original_method: Callable, send_dsl: 'SendDSL')
为发送方法注入生命周期钩子
仅对返回 Task/Awaitable 的发送方法生效,链式修饰方法(返回 SendDSL)不受影响。 不改变原方法的返回值类型或执行行为,仅在 Task 上添加回调来触发钩子。
类列表
class SendDSL
消息发送DSL基类
用于实现 Send.To(...).Func(...) 风格的链式调用接口
内置支持 At/AtAll/Reply 修饰器,适配器子类无需重复实现。 内置标准发送方法(Text/Image/Voice/Video/File/Location),默认委托给 Raw_ob12, 适配器只需实现 Raw_ob12 即可获得全部标准发送能力,也可覆盖单个方法以提供平台特定逻辑。 通过 send_context 属性可显式获取发送上下文(目标类型、目标ID、发送账号)。 通过 _apply_modifiers() 方法可自动将修饰器状态合并到消息段。
提示
- 适配器必须实现 Raw_ob12(OneBot12 消息段 → 平台 API 的统一入口)
- 标准发送方法(Text/Image/Voice/Video/File/Location)已内置并委托给 Raw_ob12,无需子类重复实现
- 子类可覆盖标准方法以提供平台特定逻辑,也可添加平台特有方法(如 Sticker)
- At/AtAll/Reply 已内置实现,无需子类覆盖
- 使用 self.send_context 获取发送上下文
- 使用 self._apply_modifiers(message) 合并修饰器到消息段
- 链式修饰方法(To/Using/At/Hook/Retry 等)返回 Self,使 IDE 能在链式调用中补全子类方法
方法列表
__init__(adapter: 'BaseAdapter', target_type: str | None = None, target_id: str | None = None, account_id: str | None = None, rules: dict | None = None)
初始化DSL发送器
- adapter: 所属适配器实例
- target_type: 目标类型(可选)
- target_id: 目标ID(可选)
- account_id: 发送账号(可选)
- rules: 已附加的发送规则字典(可选,用于 To/Using/Account 传播)
_wrapped_send_method(name: str, attr: Callable) -> Callable
获取(或构建并缓存)发送方法的 hooked 包装
缓存键为方法名,值记录 (原方法, 包装方法) 二元组。原方法比对用
底层函数对象(__func__——bound method 每次访问都是新对象,直接
is 比较恒不相等);不一致时(实例覆盖 / 热重载后类方法变化)
自动重建,保持归因语义。
内部方法
- name: 发送方法名
- attr: 本次属性访问解析到的原方法
返回值: 包装后的发送方法(同一实例同一方法恒返回同一 callable)
_clear_send_wrap_cache() -> None
清空发送方法包装缓存
发送规则装饰器(Hook/Retry/Timeout 等)变更 _rules 后调用,
确保后续访问基于最新规则状态重新构建(包装闭包虽在调用期动态读
_rules,清缓存维持"注册变化即重建"的显式不变量)。
内部方法
__getattr__(name: str)
动态属性访问处理,实现大小写不敏感调用
- 如果找到匹配的方法(忽略大小写),返回该方法
- 如果没找到,打印警告并抛出 AttributeError
- name: 属性名
返回值: 匹配的方法或属性
异常: AttributeError - 当属性不存在时抛出
list_sends() -> list[str]
列出本平台可用的发送方法名(排查「方法不存在」的指路牌)
返回值: 可用发送方法名列表(排除链式修饰方法)
At(user_id: str) -> 'Self'
@指定用户(可链式多次调用)
- user_id: 要@的用户ID
返回值 (SendDSL): 实例自身,支持链式调用
示例:
await adapter.Send.To("group", "123").At("456").Text("Hello")
await adapter.Send.To("group", "123").At("456").At("789").Text("@多人")
AtAll() -> 'Self'
@全体成员
返回值 (SendDSL): 实例自身,支持链式调用
示例:
await adapter.Send.To("group", "123").AtAll().Text("公告")
Reply(message_id: str) -> 'Self'
回复指定消息
- message_id: 要回复的消息ID
返回值 (SendDSL): 实例自身,支持链式调用
示例:
await adapter.Send.To("group", "123").Reply("msg_456").Text("回复内容")
_apply_modifiers(message) -> list[dict]
将 At/AtAll/Reply 修饰器应用到消息段
修饰器按以下顺序添加到消息段前:
- mention_all (@全体)
- mention (@用户,按调用顺序)
- reply (回复)
- message (
OneBot12): 消息段(dict 或 list[dict])
返回值: 合并后的消息段列表
示例:
segments = self._apply_modifiers([
{"type": "text", "data": {"text": "Hello"}}
])
send_context -> dict(property)
获取当前发送上下文(目标信息 + 发送账号)
返回值: 包含 target_type, target_id, account_id 的字典
示例:
ctx = self.send_context
# {"target_type": "group", "target_id": "123", "account_id": "bot1"}
await self._api_call(
endpoint="/send_message",
message=segments,
**self.send_context,
**kwargs
)
Raw_ob12(message: 'dict | list[dict]', **kwargs) -> Awaitable[Any]
发送 OneBot12 格式消息段(必须由适配器子类重写)
- message (
OneBot12): 消息段列表或单个消息段 - kwargs: 其他参数
返回值: asyncio.Task
Text(text: str) -> Awaitable[Any]
发送文本消息
默认实现委托给 :meth:Raw_ob12,适配器可覆盖以提供平台特定逻辑。
- text: 文本内容
返回值: asyncio.Task,await 后返回标准响应格式
示例:
await adapter.Send.To("user", "123").Text("Hello")
Image(file: str | bytes) -> Awaitable[Any]
发送图片消息
默认实现委托给 :meth:Raw_ob12,适配器可覆盖以提供平台特定逻辑。
- file: 图片文件(URL、路径或二进制数据)
返回值: asyncio.Task,await 后返回标准响应格式
示例:
await adapter.Send.To("user", "123").Image("https://example.com/img.png")
Voice(file: str | bytes) -> Awaitable[Any]
发送语音消息
默认实现委托给 :meth:Raw_ob12(OneBot12 audio 段),
适配器可覆盖以提供平台特定逻辑。
- file: 语音文件(URL、路径或二进制数据)
返回值: asyncio.Task,await 后返回标准响应格式
示例:
await adapter.Send.To("user", "123").Voice("https://example.com/voice.mp3")
Video(file: str | bytes) -> Awaitable[Any]
发送视频消息
默认实现委托给 :meth:Raw_ob12,适配器可覆盖以提供平台特定逻辑。
- file: 视频文件(URL、路径或二进制数据)
返回值: asyncio.Task,await 后返回标准响应格式
示例:
await adapter.Send.To("user", "123").Video("https://example.com/video.mp4")
File(file: str | bytes, filename: str | None = None) -> Awaitable[Any]
发送文件
默认实现委托给 :meth:Raw_ob12,适配器可覆盖以提供平台特定逻辑。
- file: 文件(URL、路径或二进制数据)
- filename: 文件名(可选,部分平台需要)
返回值: asyncio.Task,await 后返回标准响应格式
示例:
await adapter.Send.To("user", "123").File("https://example.com/doc.pdf")
Location(latitude: float, longitude: float, title: str = '', content: str = '') -> Awaitable[Any]
发送位置消息
默认实现委托给 :meth:Raw_ob12,适配器可覆盖以提供平台特定逻辑。
- latitude: 纬度
- longitude: 经度
- title: 位置标题(可选)
- content: 位置地址内容(可选)
返回值: asyncio.Task,await 后返回标准响应格式
示例:
await adapter.Send.To("group", "123").Location(39.9, 116.4, "北京")
To(target_type: str | None = None, target_id: str | int | None = None) -> 'Self'
设置消息目标
支持自动类型转换(遵循 :ref:session-type 规范):
如果
target_type是接收类型(如"private"),自动转换为对应的发送类型("user")如果只提供
target_id(字符串或数字)但未指定类型,默认推断为"user"发送类型(
"user"/"group"/"channel"/"guild"/"thread")保持原样target_type: 目标类型(接收类型或发送类型均可,None 时自动推断)
target_id: 目标ID(可选)
返回值 (SendDSL): 实例
示例:
# 标准用法(直接指定发送类型)
adapter.Send.To("user", "123").Text("Hello")
# 自动转换 private → user
adapter.Send.To("private", "123").Text("Hello")
# 简化形式(默认推断为 user)
adapter.Send.To("123").Text("Hello")
Using(account_id: str | int) -> 'Self'
设置发送账号
- _account_id: 发送账号
返回值 (SendDSL): 实例
示例:
adapter.Send.Using("bot1").To("123").Text("Hello")
adapter.Send.To("123").Using("bot1").Text("Hello") # 支持乱序
Account(account_id: str | int) -> 'Self'
设置发送账号
- _account_id: 发送账号
返回值 (SendDSL): 实例
示例:
adapter.Send.Account("bot1").To("123").Text("Hello")
adapter.Send.To("123").Account("bot1").Text("Hello") # 支持乱序
Hook(callback: Callable) -> 'Self'
附加发送成功后的回调钩子
仅当发送最终成功(包括重试成功)时执行,失败/超时/取消不触发。 可链式多次调用以添加多个 Hook,按添加顺序依次执行。
- callback: 回调函数,签名为
callback(result),可为同步或协程函数
返回值 (SendDSL): 实例自身,支持链式调用
示例:
await adapter.Send.To("user", "123").Hook(lambda r: print("发送成功!")).Text("你好")
async def on_success(result):
print(f"消息ID: {result.get('message_id')}")
await adapter.Send.To("user", "123").Hook(on_success).Text("异步回调")
Retry(times: int = 1) -> 'Self'
设置失败自动重试次数
含首次发送共尝试 times + 1 次。重试触发条件:
发送抛出异常
发送超时(配合 :meth:
Timeout使用)发送返回
status == "failed"的响应times: 重试次数(不含首次发送),默认 1
返回值 (SendDSL): 实例自身,支持链式调用
示例:
# 首次失败后重试2次,共3次尝试
await adapter.Send.To("user", "123").Retry(2).Text("带重试")
Timeout(seconds: float) -> 'Self'
设置单次发送超时时间
超时后取消当前尝试。若同时设置了 :meth:Retry,超时也会触发重试。
- seconds: 超时秒数
返回值 (SendDSL): 实例自身,支持链式调用
示例:
await adapter.Send.To("user", "123").Timeout(10).Text("带超时")
Defer(seconds: float = 1.0) -> 'Self'
延迟发送
在实际发起发送前等待 seconds 秒。用于延迟提醒、定时消息等场景。
注意:此延迟为进程内定时,重启进程会丢失,不提供持久化。
- seconds: 延迟秒数,默认 1.0
返回值 (SendDSL): 实例自身,支持链式调用
示例:
# 5秒后发送
await adapter.Send.To("user", "123").Defer(5).Text("迟到消息")
Priority(level: int = 0, *, drop_if_busy: bool = False) -> 'Self'
设置消息优先级
优先级会被记录到 :class:SendContext 的 extra["priority"],
供业务层监控或自定义调度使用。
当 drop_if_busy=True 时,启用积压丢弃:若当前在途发送任务数
超过阈值(默认 64,可通过 :meth:PriorityThreshold 调整),
直接放弃本次发送(返回 stage="dropped"),避免队列堆积。
- level: 优先级数值,越大越优先(默认 0)
- drop_if_busy: 是否在队列积压时丢弃本消息(默认 False)
返回值 (SendDSL): 实例自身,支持链式调用
示例:
# 低优先级消息,积压时自动丢弃
await adapter.Send.To("user", "123").Priority(-1, drop_if_busy=True).Text("可放弃的通知")
PriorityThreshold(threshold: int) -> 'Self'
设置优先级丢弃的积压阈值(全局生效)
配合 :meth:Priority 的 drop_if_busy=True 使用。
- threshold: 在途发送任务数阈值,超过则丢弃新消息
返回值 (SendDSL): 实例自身,支持链式调用
OnProgress(callback: Callable) -> 'Self'
设置进度回调
在发送的各个阶段(pending/sending/retrying/success/failed/timeout/cancelled/dropped)
调用,传入实时更新的 :class:SendContext。可据此实现监控、日志、介入决策。
callback: 回调函数,签名为
callback(ctx: SendContext),可为同步或协程函数
返回值 (SendDSL): 实例自身,支持链式调用
示例:
def on_progress(ctx):
print(f"阶段: {ctx.stage}, 尝试: {ctx.attempt + 1}/{ctx.max_attempts}")
if ctx.stage == "failed":
print(f"错误: {ctx.error!r}")
task = adapter.Send.To("user", "123").Retry(3).Timeout(10).OnProgress(on_progress).Text("监控")
OnError(callback: Callable) -> 'Self'
设置错误回调
当发送最终失败(重试耗尽仍失败、超时、取消)时调用一次,
传入最终的 :class:SendContext(ctx.error 为异常对象,超时时为
:class:asyncio.TimeoutError)。
与 :meth:OnProgress 的区别:OnProgress 在每个阶段都触发,
OnError 仅在最终失败时触发一次。
callback: 回调函数,签名为
callback(ctx: SendContext),可为同步或协程函数
返回值 (SendDSL): 实例自身,支持链式调用
示例:
async def on_error(ctx):
await admin_notify(f"发送失败: {ctx.target_id} {ctx.error!r}")
await adapter.Send.To("user", "123").Retry(2).OnError(on_error).Text("带错误处理")
Build() -> 'SendBuilder'
进入批量构建模式,返回 :class:SendBuilder
在构建模式下,发送方法(Text/Image 等)不再立即执行,而是累积为发送意图,
最后通过 send_all() 统一执行。规则统一作用于整批。
进入 Build 之前的 At/AtAll/Reply 修饰器和已设置的规则会继承到整批。
返回值: :class:SendBuilder 实例
示例:
# 构建多条消息,统一发送
results = await (
adapter.Send.To("user", "123").Build().Text("第一句").Image("pic.jpg").Text("第二句").send_all()
)
# results = [Text结果, Image结果, Text结果]
# 串行执行 + 重试失败的
await (
adapter.Send.To("group", "456")
.Build()
.Sequential()
.Retry(2)
.Text("保证顺序1")
.Text("保证顺序2")
.send_all()
)
class RequestDSL
请求操作 DSL 基类
用于对请求事件(好友请求、群邀请等)执行同意/拒绝操作。
采用与 Send 一致的工厂实例模式:adapter.Request("req_id").accept()
适配器只需在内部类中重写 accept / reject 即可。
提示
- 使用
adapter.Request(request_id).accept()同意请求- 使用
adapter.Request(request_id).reject()拒绝请求- 适配器重写
accept/reject实现平台逻辑- 基类默认返回
retcode=10002(不支持的操作)
方法列表
__init__(adapter: 'BaseAdapter', request_id: str | None = None, account_id: str | None = None)
初始化请求操作 DSL
- adapter: 所属适配器实例
- request_id: 请求ID
- account_id: 执行操作的 Bot 账号
__call__(request_id: str) -> 'Self'
设置请求ID,返回新的 RequestDSL 实例
使得 adapter.Request("req_id") 可以直接调用
- request_id: 请求ID
返回值: 新的 RequestDSL 实例
Using(account_id: str | int) -> 'Self'
指定执行操作的 Bot 账号
- account_id: 账号标识
返回值: 新的 RequestDSL 实例
示例:
adapter.Request("req_123").Using("bot1").accept()
_guard_request()
内部方法
请求操作授权闸口(scope.actions.
返回值: None 表示放行;否则为已完成的标准拒绝响应 task
accept(**kwargs) -> Awaitable[Any]
同意请求
- kwargs: 平台扩展参数(如 comment 备注)
返回值: asyncio.Task,await 后返回标准响应格式
示例:
result = await adapter.Request("req_123").accept()
result = await adapter.Request("req_123").accept(comment="欢迎")
reject(**kwargs) -> Awaitable[Any]
拒绝请求
- kwargs: 平台扩展参数(如 comment 拒绝理由)
返回值: asyncio.Task,await 后返回标准响应格式
示例:
result = await adapter.Request("req_123").reject()
result = await adapter.Request("req_123").reject(comment="暂不添加")
async _do_accept(**kwargs) -> dict[str, Any]
同意请求的具体实现(适配器子类重写)
- kwargs: 平台扩展参数
返回值: 标准响应格式
async _do_reject(**kwargs) -> dict[str, Any]
拒绝请求的具体实现(适配器子类重写)
- kwargs: 平台扩展参数
返回值: 标准响应格式
_not_implemented_response(action: str) -> dict[str, Any]
生成「未实现」的标准错误响应
- action: 操作名称(accept/reject)
返回值: 标准错误响应字典
_create_task(coro) -> Awaitable[Any]
创建 asyncio.Task
request_context -> dict(property)
获取当前请求操作上下文
account_id 优先取显式 Using() 指定值;未指定时兜底当前事件分发
链路的触发账户(无事件上下文时为 None)。
返回值: 包含 request_id, account_id 的字典
class BaseAdapter(ABC)
适配器基类
提供与外部平台交互的标准接口,子类必须实现必要方法
提示
- 必须实现call_api, start和shutdown方法
- Send 子类只需实现 Raw_ob12,即可获得全部标准发送方法(Text/Image/Voice/Video/File/Location)
- 可以自定义Request类实现平台特定的请求操作逻辑
- 通过on装饰器注册事件处理器
- 支持OneBot12协议的事件处理
- 通过 ConfigClass / AccountConfigClass 声明配置类,框架自动管理配置
- 通过 self.cfg / self.accounts 访问类型安全的配置对象(实时读取)
- 通过 self.emit_meta() 发送 meta 事件
- 通过 self.make_response() / self.make_error() 构造标准化响应
- 通过 I18nClass 声明翻译键集合,框架自动注册到 i18n 系统
嵌套类
class Request(RequestDSL)
请求操作 DSL 实现
适配器子类重写 accept / reject 以实现平台特定逻辑。
提示
- 默认实现返回
retcode=10002(不支持的操作)- 适配器应重写
accept/reject方法- 通过
self._api_call()调用平台 API- 通过
self._request_id获取请求标识- 通过
self._account_id获取 Bot 账号
class Api(ApiDSL)
标准 API 动作 DSL 实现
提供跨平台的 OneBot12 标准动作接口(信息查询、群管理、消息撤回、文件操作等)。
提示
- 默认实现委托给
adapter.call_api(action_name, ...),零配置可用- 适配器可覆盖单个标准方法以映射到平台原生 API
- 平台扩展动作通过
call("prefix.action", **params)调用- 使用
adapter.Api.Using("bot1")指定 Bot 账号
class Send(SendDSL)
消息发送DSL实现
提示
- 必须重写 Raw_ob12 方法(OneBot12 消息段 → 平台 API)
- 标准方法(Text/Image/Voice/Video/File/Location)已从 SendDSL 基类继承,默认委托 Raw_ob12
- 如需平台特定逻辑,可覆盖单个标准方法(如 Text)
- 可添加平台特有的发送方法(如 Sticker)
方法列表
####### Example(text: str) -> Awaitable[Any]
示例消息发送方法
- text: 文本内容
返回值: 异步任务
示例:
await adapter.Send.To("123").Example("Hello")
####### Raw_ob12(message: 'dict | list[dict]', **kwargs: Any) -> Awaitable[Any]
发送 OneBot12 格式消息段(必须由适配器子类重写)
此方法是反向转换(OneBot12 → 平台)的统一入口,适配器必须重写此方法。 未重写时,基类默认实现会记录错误日志并返回标准错误响应。
推荐使用框架提供的辅助方法:
self._apply_modifiers(message) - 合并 At/AtAll/Reply 修饰器到消息段
self.send_context - 获取发送上下文 (target_type, target_id, account_id)
message (
OneBot12): 格式的消息段数组或单个消息段[ {"type": "text", "data": {"text": "Hello"}}, {"type": "image", "data": {"file": "https://..."}}, ]
kwargs: 其他参数
返回值: asyncio.Task,await 后返回标准响应格式
示例:
# 用户调用
await adapter.Send.To("user", "123").Raw_ob12([
{"type": "text", "data": {"text": "Hello"}},
{"type": "image", "data": {"file": "https://..."}}
])
# 适配器子类重写示例(推荐:使用框架辅助方法)
def Raw_ob12(self, message: dict, **kwargs):
async def _do_send():
segments = self._apply_modifiers(message)
return await self._api_call(
endpoint="/send_message",
message=segments,
**self.send_context,
**kwargs
)
return asyncio.create_task(_do_send())
方法列表
_load_accounts() -> dict | None
内部方法 加载账户配置(可被子类覆写)
子类可覆写此方法实现自定义账户加载逻辑(如全局配置合并、旧格式迁移等)。 返回 None 时使用默认配置存储读取逻辑。
返回值: 账户配置字典,或 None 表示使用默认逻辑
_load_config()
内部方法 加载适配器配置(可被子类覆写)
子类可覆写此方法实现自定义配置加载逻辑(如旧格式迁移等)。 返回 None 时使用默认配置存储读取逻辑。
返回值: 配置实例,或 None 表示使用默认逻辑
async call_api(endpoint: str, **params: Any) -> Any
调用平台API的抽象方法
- endpoint (
API): 端点 - params (
API): 参数
返回值 (API): 调用结果
异常: NotImplementedError - 必须由子类实现
async start() -> None
启动适配器的抽象方法
异常: NotImplementedError - 必须由子类实现
async shutdown() -> None
关闭适配器的抽象方法
异常: NotImplementedError - 必须由子类实现
cfg -> Any(property)
类型安全的配置对象(实时读取)
每次访问都从配置存储读取最新值,确保用户修改配置后立即生效。 返回的 dataclass 实例是只读快照,修改它不会回写存储。
返回值: AdapterConfig / BaseConfig 实例
异常: AttributeError - 未声明 ConfigClass 时抛出
提示 推荐使用
self.cfg而非self.config, 后者已弃用且可能被子类属性覆盖产生冲突。
cfg(value: Any) -> None
设置配置实例,同时同步写入配置存储(保证实时性)
config -> Any(property)
self.cfg 的兼容别名
功能与 self.cfg 完全一致,推荐新代码使用 self.cfg。
accounts -> dict(property)
类型安全的账户配置字典(实时读取)
每次访问都从配置存储读取最新值,确保用户修改账户配置后立即生效。
返回值: 账户配置字典 {name: config_instance}
异常: AttributeError - 未声明 AccountConfigClass 时抛出
accounts(value: Any) -> None
设置账户配置字典,同时同步写入配置存储
enabled_accounts -> dict(property)
仅返回 enabled=True 的账户
返回值: 启用的账户配置字典
platform -> str(property)
获取平台名称
返回值: 平台名称字符串
_get_config_key() -> str
配置键名(默认用类名,可被子类覆写)
返回值: 配置键名字符串
_get_logger()
内部方法 获取 logger,兼容 sdk 未注入的场景
此处刻意使用函数内导入:模块顶层已有 logger,但函数内动态导入可让测试
通过 patch("ErisPulse.Core.logger.logger") 拦截日志输出。
_ensure_config_exists()
确保全局配置模板存在,不存在则生成默认配置
内部方法 会先行调用 _ensure_i18n_registered() 注册声明的翻译键, 确保配置描述引用的 i18n 键在生成模板时已可用。
_ensure_i18n_registered()
注册 I18nClass 中声明的翻译键到 i18n 系统
使用适配器配置键名(默认为类名)作为键名前缀和 domain,便于统一卸载。 方法是幂等的,多次调用不会产生副作用(重复注册会覆盖旧值)。
内部方法 由 init() 在生成配置之前隐式调用。
_ensure_event_mixin_registered()
注册 EventMixin 中声明的事件扩展方法
适配器声明 EventMixin 时,框架自动将其注册到适配器的平台
(即 self._platform),而不是通配符。
内部方法 由 init() 隐式调用。
update_bot_id(account_name: str, bot_id: str) -> None
运行期识别 bot_id 并持久化到账户配置
适配器在连接建立 / 事件到达时调用(协议事件的 self.user_id 即 bot_id)。
框架维护 bot_id → 账户名注册表(本进程解析链第一优先级),并在配置值
变化时把 accounts.<账户名>.bot_id 写入配置存储(无损路径)——
重启后账户实例重建即自带 bot_id,解析不再依赖账户活动回填。
- account_name: 账户名(accounts 配置键)
- bot_id: 协议侧机器人标识
_resolve_account(account_id: str | None = None) -> tuple
解析目标账户
- account_id 为 None → 返回第一个启用的账户
- account_id 匹配账户名 → 返回该账户
- account_id 匹配 bot_id 等字段 → 返回该账户
- account_id 非 None 但无法匹配 → 记录 WARNING 并返回第一个启用的账户
- 没有任何启用账户 → 抛出 ValueError
匹配字段优先级:账户名 > dataclass 中名为 bot_id 的字段 > 任意 str 类型字段
- account_id: 账户标识(账户名、bot_id 等)
返回值: (账户名, 账户配置实例) 元组
异常: ValueError - 未找到可用账户时抛出
spawn_client_loop(coro: Any, *, name: str = 'client_loop') -> Any
拉起客户端连接循环(归属本平台的后台任务)
客户端模式适配器(WebSocket 客户端 / HTTP 长轮询等)的常驻连接
循环经本方法调度:任务归属 self._platform——适配器 shutdown
时框架按归属自动取消,无需自己管理任务句柄;循环异常自动留痕
(连接断开重连等预期异常请在循环内自行捕获)。
与 start() 的两种正确写法配合:
start()内self.spawn_client_loop(self._connect_loop())后 立即返回(spawn-返回式:启动即成功,连接失败由循环内重试)start()内await self._connect_loop()常驻不返回 (常驻式:连接断开抛异常触发框架的退避重试链)
提示 两种写法都正确;混用(spawn 后又 await 同一循环)才是错误。 spawn-返回式适合需要快速返回启动确认的场景,常驻式适合 「连接即启动语义」的简单实现。
- coro: 连接循环协程(如
self._connect_loop()) - name: 任务名(日志留痕用)
返回值: 创建的 asyncio.Task(通常可忽略;临时事件循环场景为 None)
async emit_event(event: dict[str, Any]) -> None
上报接收事件的便捷方法(与 :meth:emit_meta 对称)
适配器收到平台原生事件并经 :meth:convert 转为 OneBot12 格式后,
经本方法提交给框架分发(含幂等去重、trace-id 串联、处理器并发
调度)。事件须携带 platform 字段(服务端模式通常为
self._platform 或按连接归属填写)。
- event: 符合 OneBot12 标准的事件数据
async emit_meta(detail_type: str, bot_id: str, **extra_info) -> None
发送 meta 事件的便捷方法
- detail_type: "connect" | "disconnect" | "heartbeat"
- bot_id (
Bot): 用户 ID - extra_info: 扩展字段(user_name, nickname, avatar 等)
make_response(*, status: str = STATUS_OK, retcode: int = RETCODE_OK, data: Any = None, message_id: str = '', message: str = '', raw: Any = None) -> dict
构造标准化响应
- status: 状态码("ok" | "failed")
- retcode: 返回码
- data: 响应数据
- message_id: 消息 ID
- message: 响应消息
- raw: 原始平台响应
返回值: 标准响应字典
make_error(retcode: int = RETCODE_SDK_FAILURE, message: str = '', raw: Any = None) -> dict
构造错误响应
- retcode: 错误码
- message: 错误消息
- raw: 原始平台响应
返回值: 标准错误响应字典
on_config_update(old_config: Any, new_config: Any) -> None
配置变更回调(可选实现)
子类可覆写此方法以响应配置热更新。默认实现为空操作。
- old_config: 变更前的配置实例
- new_config: 变更后的配置实例
async on_dependency_ready(module_name: str) -> None
软依赖模块就绪回调(可选实现)
当 optional_modules 中声明的模块被加载(含启动晚于适配器、
热重载后再加载)时调用。子类可覆写以启用对应可选功能。
- module_name: 就绪的模块名
示例:
optional_modules = ["TranslateEngine"]
async def on_dependency_ready(self, module_name):
if module_name == "TranslateEngine":
self._translate = self.sdk.TranslateEngine
async on_dependency_lost(module_name: str) -> None
软依赖模块丢失回调(可选实现)
当 optional_modules(或模块硬依赖)中声明的模块被卸载/禁用时
调用。子类可覆写以降级对应功能(如关闭翻译、清理缓存引用)。
- module_name: 丢失的模块名
send(target_type: str, target_id: str, message: Any, **kwargs: Any) -> asyncio.Task
发送消息的便捷方法,返回一个 asyncio Task
target_type: 目标类型
target_id: 目标ID
message: 消息内容
kwargs: 其他参数
- method: 发送方法名(默认为"Text")
返回值 (asyncio.Task): 对象,用户可以自主决定是否等待
异常: AttributeError - 当发送方法不存在时抛出
示例:
task = adapter.send("user", "123", "Hello")
# 用户可以选择等待: result = await task
# 或者不等待让其在后台执行
await adapter.send("group", "456", "Hello", method="Markdown") # 直接等待