ErisPulse 请求操作规范
Tip
什么时候需要读这篇:当你的适配器需要处理好友请求/群邀请(转换请求事件、实现 accept/reject,含异构端点的请求类型上下文留存),或模块中要用 event.approve() / event.reject() 审批请求时对照本文。不需要则跳过。
本文档定义了 ErisPulse 适配器中请求事件操作的标准化规范,包括请求事件的字段要求、Request DSL 的使用方式和适配器实现要求。
1. 概述
请求事件(type: "request")是 OneBot12 标准中定义的特殊事件类型,代表需要 Bot 做出决策的请求(如好友请求、群邀请等)。
与消息事件不同,请求事件需要双向交互:
- 接收:适配器将平台原生请求转换为标准请求事件
- 响应:模块通过
RequestDSL 或Event.approve()/Event.reject()执行操作
平台原生请求事件
│
▼
Converter.convert() ← 适配器实现(正向转换)
│
▼
标准请求事件 (含 request_id)
│
├─→ 模块处理器 @request.on_friend_request()
│ │
│ ├─→ event.approve() ← 同意请求
│ └─→ event.reject() ← 拒绝请求
│ │
│ ▼
│ adapter.Request(request_id).accept()
│ │
│ ▼
│ BaseAdapter.Request.accept() ← 适配器重写
│ │
│ ▼
│ 平台 API 调用
│
└─→ 或直接通过适配器操作
await adapter.Request("req_id").accept()
2. 请求事件字段要求
2.1 标准字段
请求事件除必须包含 OneBot12 标准字段外,还需包含以下字段:
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
request_id |
string | 强烈推荐 | 请求标识符,用于同意/拒绝操作 |
user_id |
string | 是 | 请求发起者ID |
user_nickname |
string | 否 | 请求发起者昵称 |
comment |
string | 否 | 请求附言 |
2.2 request_id 字段
request_id 是请求操作的核心标识符:
- 用途:标识一个可操作的请求,供
RequestDSL 使用 - 生成规则:
- 优先使用平台原生的请求标识(如 OneBot11 的
flag字段、Telegram 的chat_invite_link等) - 如果平台没有原生请求ID,适配器应生成一个唯一标识(建议格式:
{platform}_{timestamp}_{user_id})
- 优先使用平台原生的请求标识(如 OneBot11 的
- 唯一性:在同一平台范围内应保持唯一
- 缺失行为:当
request_id缺失时,event.approve()/event.reject()将抛出ValueError
2.3 请求事件示例
{
"id": "evt_123456",
"time": 1752241225,
"type": "request",
"detail_type": "friend",
"platform": "onebot11",
"self": {
"platform": "onebot11",
"user_id": "bot_123"
},
"user_id": "user_456",
"user_nickname": "YingXinche",
"comment": "请加好友",
"request_id": "flag_abc123",
"onebot11_raw": {...},
"onebot11_raw_type": "request"
}
3. Request DSL
3.1 链式调用
Request 提供与 Send 风格一致的链式调用接口:
# 基本用法
await adapter.Request("req_id").accept()
await adapter.Request("req_id").reject()
# 指定 Bot 账号
await adapter.Request("req_id").Using("bot1").accept()
# 附带备注(通过 kwargs)
await adapter.Request("req_id").accept(comment="欢迎")
await adapter.Request("req_id").reject(comment="暂不添加")
# 组合使用
await adapter.Request("req_id").Using("bot1").accept(comment="欢迎")
3.2 方法列表
| 方法 | 说明 | 返回值 |
|---|---|---|
Using(account_id) |
指定执行操作的 Bot 账号 | RequestDSL(支持链式调用) |
accept(**kwargs) |
同意请求 | asyncio.Task(await 后返回标准响应) |
reject(**kwargs) |
拒绝请求 | asyncio.Task(await 后返回标准响应) |
3.3 返回值格式
操作返回标准 API 响应格式:
成功:
{
"status": "ok",
"retcode": 0,
"data": null,
"message_id": "",
"message": ""
}
失败:
{
"status": "failed",
"retcode": 34001,
"data": null,
"message_id": "",
"message": "请求已过期或不存在"
}
未实现(适配器未重写 _do_accept/_do_reject):
{
"status": "failed",
"retcode": 10002,
"data": null,
"message_id": "",
"message": "平台 MyAdapter 未实现请求操作 (accept)"
}
4. Event 便捷方法
Event 包装类提供了便捷方法,适合在请求事件处理器中使用:
from ErisPulse.Core.Event import request
@request.on_friend_request()
async def handle_friend_request(event):
# 检查请求ID
request_id = event.get_request_id()
if not request_id:
print("警告:请求事件缺少 request_id")
return
# 同意请求
result = await event.approve()
# 或拒绝请求
# result = await event.reject(comment="暂不添加好友")
# 检查结果
if result.get("status") == "ok":
print("操作成功")
else:
print(f"操作失败: {result.get('message')}")
4.1 Event 方法列表
| 方法 | 说明 | 返回值 |
|---|---|---|
get_request_id() |
获取请求ID | str |
approve(comment=None) |
同意当前请求事件 | 标准响应格式 |
reject(comment=None) |
拒绝当前请求事件 | 标准响应格式 |
5. 适配器实现要求
5.1 转换器要求
适配器的转换器在转换请求事件时,必须正确设置 request_id 字段:
def convert_request_event(self, raw_event: dict) -> dict:
"""转换平台原生请求事件"""
return {
"id": self._generate_event_id(raw_event),
"time": int(time.time()),
"type": "request",
"detail_type": self._map_request_type(raw_event), # "friend" 或 "group"
"platform": self._platform_name,
"self": {
"platform": self._platform_name,
"user_id": str(self._bot_id),
},
"user_id": str(raw_event.get("user_id", "")),
"user_nickname": raw_event.get("nickname", ""),
"comment": raw_event.get("message", ""),
"request_id": self._extract_request_id(raw_event), # ← 关键字段
f"{self._platform_name}_raw": raw_event,
f"{self._platform_name}_raw_type": raw_event.get("type", ""),
}
def _extract_request_id(self, raw_event: dict) -> str:
"""
从平台原生事件提取请求ID
优先使用平台原生的请求标识,若无则生成唯一ID
"""
# 优先使用平台原生ID
if flag := raw_event.get("flag"):
return str(flag)
if request_key := raw_event.get("request_key"):
return str(request_key)
# 兜底:生成唯一ID
import hashlib
raw = f"{self._platform_name}_{raw_event.get('user_id')}_{raw_event.get('timestamp')}"
return hashlib.md5(raw.encode()).hexdigest()
5.2 Request 内部类实现
基类的 accept() / reject() 是公开入口:内置 scope 授权闸口(scope.actions.<owner>.request,禁用时直接返回 34601 拒绝响应)与任务包装,适配器不要重写公开入口——重写会绕过授权闸口。适配器重写 _do_accept / _do_reject(异步方法,直接返回标准响应 dict)。
多账户提醒:
_do_accept/_do_reject内是适配器自己调call_api,账户不会自动注入——账户经self.request_context.get("account_id")获取(Using()显式指定 > 事件链自动绑定,与 Send 的send_context同口径),并作为account_id参数传给call_api,否则多账户部署下会落到默认账户。
from ErisPulse.Core import BaseAdapter, RequestDSL
class MyAdapter(BaseAdapter):
class Request(RequestDSL):
"""MyPlatform 请求操作实现"""
async def _do_accept(self, **kwargs) -> dict:
"""
同意请求
:param kwargs: 扩展参数,如 comment="备注"
:return: 标准响应格式 dict
"""
try:
result = await self._adapter.call_api(
endpoint="/set_request",
request_id=self._request_id,
account_id=self.request_context.get("account_id"),
approve=True,
**kwargs,
)
return {
"status": "ok" if result.get("code") == 0 else "failed",
"retcode": result.get("code", 0),
"data": None,
"message_id": "",
"message": result.get("message", ""),
}
except Exception as e:
return {
"status": "failed",
"retcode": 34001,
"data": None,
"message_id": "",
"message": f"请求操作失败: {e}",
}
async def _do_reject(self, **kwargs) -> dict:
"""拒绝请求(与 _do_accept 同构:approve=False)"""
5.3 请求类型上下文留存(异构端点适配器必须)
5.3.1 契约缺口
Request DSL 是无状态句柄:调用方只持 request_id(§3),请求类型不在调用参数里。而不少平台的同意/拒绝端点是异构的——以 OneBot11 系为例:
| 请求类型 | 端点 |
|---|---|
| 好友添加 | set_friend_add_request(flag, approve) |
| 群申请 / 群邀请 | set_group_add_request(flag, sub_type, approve),sub_type ∈ {"add", "invite"} |
调用方只知道 request_id,端点选择却需要类型。这段上下文只可能由适配器补齐:请求事件本就是适配器接收并转换的(类型信息在转换时就在手上),且一个 request_id 对应的请求类型不会变。适配器若不自行留存,只能猜测端点或依赖调用方传非标准参数——典型故障形态是群邀请被送进好友端点,flag 被协议端按 user_id 解析而报错。
5.3.2 规范要求
平台端点异构(同意/拒绝需要按请求类型路由)的适配器,accept / reject 实现必须满足:
- 事件侧留存:适配器收到请求事件的入口处,把
request_id → {请求类型, sub_type, group_id, 账户}写入实例内缓存(统一字段见 §5.3.3),并顺手清理过期条目 - 操作侧路由:
_do_accept/_do_reject内的端点选择顺序为 kwargs 显式传参 > 缓存 > 回退默认端点并记 WARNING——类型未知必须打日志(可观测),不得静默选端点 - kwargs 保留名:显式覆盖参数统一命名
request_type/sub_type/group_id(无下划线前缀、跨适配器同名同义);不使用_request_type一类私有约定名(标准调用方不会传) - 账户读取与归属校验:操作账户统一经基类属性
self.request_context.get("account_id")获取(Using()显式指定 > 事件链自动绑定,与 Send 的send_context同口径);留存条目的事件到达账户作为事件链缺失时的兜底(如轮询合成事件、跨重启重建)。账户无法解析到具体账户实例时必须快速失败(返回 34005),不得静默回退默认账户——回退会把操作打到错误连接(flag 在默认账户会话不存在,平台报 invalid,多账户下表现为「只有第一个账户能操作」) - 默认持久化:留存介质默认为框架统一存储(
self.sdk.storage)单键整快照——请求为低频批复类事件,事件到达时即写透(库内足迹恒为 1 个键);启动时一次加载回内存,运行时读路径零开销;存储不可用时降级仅内存(WARNING),不阻断事件流 - 处理后清理:操作提交成功后删除该
request_id条目并同步写透快照
单一请求端点的平台(如统一 /set_request)无需留存,透传即可。本节是适配器实现口径,Request DSL 契约不受影响。
5.3.3 统一条目字段(介质无关)
上下文条目按以下统一字段形状留存。字段形状是互操作契约:内存 dict、KV value、ORM 行均按同一形状落存,后续跨适配器聚合或迁移时形状一致;存储介质自选,不因介质改变字段语义。
| 字段 | 类型 | 必含 | 语义与来源 |
|---|---|---|---|
request_type |
str |
是 | 请求类型,取自事件 detail_type("friend" / "group") |
sub_type |
str | None |
群请求必含 | 群请求子类型 "add" / "invite",取自平台原生事件(OB11 系 sub_type) |
group_id |
str | None |
群请求必含 | 目标群 ID,取自平台原生事件 |
account |
str | None |
多账户必含 | 事件到达账户,取自事件 self.user_id |
ts |
float |
是 | 事件到达 Unix 时间戳(秒),TTL 判定基准 |
条目一致性规则:
- 一一对应:一个
request_id至多对应一个条目;同request_id的重复事件覆盖写入(幂等) - 处理后删除:操作提交成功即删除条目
- TTL:以
ts为基准,建议 1 小时级(覆盖平台侧请求有效期);过期视同未留存,走回退默认端点 + WARNING - 键名(KV 持久化时):
{适配器配置键}:request_ctx:{request_id},避免跨适配器冲突
5.3.4 参考实现(统一存储单键快照,默认)
留存介质默认为框架统一存储(self.sdk.storage):请求事件是批复类低频事件(好友/群请求,非消息流),事件到达时即写透不会造成写入压力。存储形式为单键整快照——整个上下文字典作为一个键一次写入(库内足迹恒为 1 个键,随处理自动收敛),不做逐 flag 分键。重启后启动时一次加载回内存,运行时读路径零开销。
import time
from ErisPulse.Core import BaseAdapter, RequestDSL
class MyAdapter(BaseAdapter):
"""请求端点异构平台(好友与群请求分端点)"""
_REQ_CTX_TTL = 86400 # 留存秒数(覆盖平台侧 flag 有效期,重启不丢)
_REQ_CTX_MAX = 512 # 条目容量上限
def __init__(self, sdk=None):
super().__init__(sdk)
self._request_ctx: dict[str, dict] = {} # request_id → 请求上下文(内存态)
self._ctx_key = f"{self._get_config_key()}:request_ctx" # 单键整快照
async def start(self):
# 启动加载(重启后仍可审批);存储不可用按冷启动处理
try:
loaded = self.sdk.storage.get(self._ctx_key, {}) or {}
now = time.time()
self._request_ctx = {k: v for k, v in loaded.items()
if now - v.get("ts", 0) <= self._REQ_CTX_TTL}
except Exception as e:
self.logger.warning(f"请求上下文加载失败(按冷启动处理): {e}")
self._request_ctx = {}
def _persist_ctx(self) -> None:
"""单键整快照写透(存储不可用时降级仅内存,不阻断事件流)"""
try:
self.sdk.storage.set(self._ctx_key, self._request_ctx)
except Exception as e:
self.logger.warning(f"请求上下文写透失败(降级仅内存): {e}")
def remember_request(self, request_id: str, *, request_type: str,
sub_type: str | None = None, group_id: str | None = None,
account: str | None = None) -> None:
"""事件侧留存请求上下文(适配器收到请求事件的入口处调用)"""
now = time.time()
expired = [k for k, c in self._request_ctx.items() if now - c["ts"] > self._REQ_CTX_TTL]
for k in expired:
self._request_ctx.pop(k)
while len(self._request_ctx) >= self._REQ_CTX_MAX:
self._request_ctx.pop(min(self._request_ctx, key=lambda k: self._request_ctx[k]["ts"]))
self._request_ctx[request_id] = {
"request_type": request_type, # "friend" / "group"
"sub_type": sub_type, # 群请求子类型:"add" / "invite"
"group_id": group_id,
"account": account, # 事件到达账户(事件的 self.user_id / 代位账户名)
"ts": now,
}
self._persist_ctx()
class Request(RequestDSL):
"""端点路由:kwargs 显式传参 > 缓存 > 回退默认端点 + WARNING"""
def _route(self, **kwargs) -> dict:
ctx = {k: kwargs[k] for k in ("request_type", "sub_type", "group_id") if kwargs.get(k)}
cached = self._adapter._request_ctx.get(self._request_id, {})
if not ctx.get("request_type"):
ctx.update({k: v for k, v in cached.items()
if k in ("request_type", "sub_type", "group_id") and v})
ctx.setdefault("account", cached.get("account"))
if not ctx.get("request_type"):
self._adapter.logger.warning(f"请求 {self._request_id} 类型未知,按好友端点回退")
ctx["request_type"] = "friend"
return ctx
def _resolve_or_fail(self, account):
"""
审批账户归属校验:解析失败快速失败(34005),不回退默认账户。
回退默认账户会把操作打到错误连接上(flag 在该账户会话不存在,
平台报 invalid,表现为「只有第一个账户能操作」的玄学故障)。
"""
if not account:
return None, None # 无任何账户信息时维持默认账户语义
name, inst = self._adapter._resolve_account(account)
hit = str(account) == str(name) or str(account) == str(getattr(inst, "bot_id", "") or "")
if not hit:
self._adapter.logger.warning(
f"请求 {self._request_id} 的账户 {account} 无法解析,拒绝回退默认账户")
return None, "34005"
return (name, inst), None
async def _do_accept(self, **kwargs) -> dict:
"""同意请求;kwargs 类型路由可用 request_type / sub_type / group_id 显式覆盖"""
return await self._do_action(approve=True, **kwargs)
async def _do_reject(self, **kwargs) -> dict:
"""拒绝请求(与 _do_accept 同构:approve=False)"""
return await self._do_action(approve=False, **kwargs)
async def _do_action(self, approve: bool, **kwargs) -> dict:
ctx = self._route(**kwargs)
account = self.request_context.get("account_id") or ctx.get("account")
resolved, fail = self._resolve_or_fail(account)
if fail:
return {
"status": "failed", "retcode": 34005, "data": None,
"message_id": "", "message": f"请求账户 {account} 无法解析到账户实例",
}
try:
if ctx["request_type"] == "group":
result = await self._adapter.call_api(
endpoint="/set_group_add_request",
flag=self._request_id,
sub_type=ctx.get("sub_type") or "add",
approve=approve,
account_id=account,
)
else:
result = await self._adapter.call_api(
endpoint="/set_friend_add_request",
flag=self._request_id,
approve=approve,
account_id=account,
)
response = {
"status": "ok" if result.get("code") == 0 else "failed",
"retcode": result.get("code", 0),
"data": None,
"message_id": "",
"message": result.get("message", ""),
}
except Exception as e:
response = {
"status": "failed", "retcode": 34001, "data": None,
"message_id": "", "message": f"请求操作失败: {e}",
}
if response["status"] == "ok":
self._adapter._request_ctx.pop(self._request_id, None) # 处理后清理
self._adapter._persist_ctx()
return response
5.3.5 边界与降级
降级语义:统一存储不可用(连接失败冷却期 fast-fail)时写透降级为仅内存(WARNING 可观测),事件照常分发;重启后条目丢失走「类型未知回退 + WARNING」路径。
等价介质:内置 ORM(request_id 主键建表,见 数据模型层)语义等价,适配器可按需选用;不引入额外文件或新依赖。
多实例边界:本规范不覆盖多进程实例协同——ErisPulse 为单进程多 bot 模型(多账户同进程,请求与其所属账户天然同侧),统一存储即满足重启语义;跨实例共享(多进程分摊账户)需要时再行立项。
5.4 平台不支持请求操作
如果平台本身不支持好友请求/群邀请操作(如某些平台自动处理请求),适配器可以:
- 不重写
Request内部类:使用基类默认实现,调用accept()/reject()时返回retcode=10002 - **在转换时跳过
request_id**:不生成request_id,让event.approve()抛出ValueError - 记录日志:在
_do_accept/_do_reject中记录警告并返回适当错误码
5.5 总结:Send 与 Request 并行
适配器有两个并行的 DSL 内部类,各司其职:
BaseAdapter
├── Send(SendDSL) ← 消息发送
│ ├── Raw_ob12() ← 必须实现
│ ├── Text() ← 推荐实现
│ └── Image() ← 按需实现
│
└── Request(RequestDSL) ← 请求操作
├── accept() ← 公开入口(scope 闸口 + 任务包装,勿重写)
├── reject() ← 公开入口(同上)
├── _do_accept() ← 按需重写
└── _do_reject() ← 按需重写
5.6 适配器 __init__ 注意事项
重写 Request 内部类的 __init__ 时,必须透传参数并调用 super().__init__(),详见 适配器开发入门 - __init__ 注意事项(Request 同理,参数为 adapter, request_id, account_id)。
6. 适配器实现检查清单
基础要求
- 若重写了
__init__,已调用super().__init__()(确保 Send / Request 工厂初始化)
请求事件转换
- 请求事件包含
request_id字段(强烈推荐) -
detail_type正确映射为"friend"或"group" - 保留平台原始数据在
{platform}_raw字段中 -
request_id生成规则有文档说明
请求操作
-
Request内部类已实现(如平台支持请求操作) -
_do_accept()/_do_reject()已重写(公开入口accept()/reject()勿重写——绕过 scope 授权闸口) - 操作返回标准 API 响应格式
- 不支持的操作返回
retcode=10002 - 网络错误返回
retcode=33xxx(遵循 API 响应标准)
请求类型上下文留存(异构端点平台,见 §5.3)
- 请求事件入口已留存
request_id → {请求类型, sub_type, group_id, 账户}上下文 - 条目字段与 §5.3.3 统一字段表一致(含
ts时间戳;request_id一一对应、处理后删除) -
accept/reject端点路由顺序为 kwargs 显式传参 > 缓存 > 回退默认端点 + WARNING - 类型覆盖参数使用保留名
request_type/sub_type/group_id(无_request_type一类私有约定名) - 缓存有 TTL 与容量上限,操作提交成功后清理对应条目
- 多账户:操作账户经
self.request_context.get("account_id")读取(Using()> 事件链兜底),留存账户作事件链缺失时兜底 - 审批账户解析失败快速失败(34005),不回退默认账户
- 默认统一存储单键快照:启动加载、事件到达/处理后写透、存储不可用降级仅内存
7. 错误码扩展
请求操作相关的适配器实现层推荐错误码(遵循 API 响应标准 §3.2,
落在 34xxx 平台错误段的低三位自定义):
| 错误码 | 错误名 | 说明 |
|---|---|---|
| 34001 | Request Not Found | 请求不存在或已过期 |
| 34002 | Request Already Handled | 请求已被处理 |
| 34003 | Request Not Supported | 平台不支持该类型的请求操作 |
| 34004 | Permission Denied | Bot 无权处理此请求(平台返回) |
| 34005 | Request Account Unresolved | 请求所属账户无法解析到账户实例(快速失败,不回退默认账户) |
与框架码的边界:以上
340xx是平台/适配器返回的请求处理失败; ErisPulse 框架在scope.actions禁用某模块的 request 动作时,在调用适配器之前 直接返回34601(Action Denied,见 API 响应标准 §5.3), 两者互不替代:先过34601框架闸口,再落到平台层340xx错误。
8. 相关文档
实现请求操作时配套对照:
- 事件转换标准 - 完整的事件转换规范(含
request_id字段要求) - API 响应标准 - 适配器 API 响应格式标准(操作返回值与错误码)
- 存储后端 - 需要跨重启留存请求上下文时的统一 KV 存储
同一适配器的其它 DSL: