ErisPulse.Core.Bases.api_dsl 模块
模块概述
ErisPulse 标准 API 动作 DSL 模块
提供 ApiDSL——OneBot12 标准 API 动作的强类型 DSL 基类,由适配器基类的
Api 内嵌类继承使用;ErisPulse.Core.Bases.adapter 对其 re-export,
既有导入路径(ErisPulse.Core.Bases.adapter.ApiDSL / ErisPulse.Core.Bases.ApiDSL)不变。
提示
- 标准方法默认委托给
adapter.call_api(action_name, ...),适配器可按需覆盖- 使用
adapter.Api.Using("bot1").get_user_info("123")指定 Bot 账号- 平台扩展动作通过
call("prefix.action", **params)调用
函数列表
_code_string_constants(code) -> set
递归收集代码对象引用的字符串常量(探测 **params 内的字段消费)
_call_account_mode(adapter) -> str
探测适配器 call_api 消费账户字段的方式
返回 account_id(标准名)/ _account_id(旧名)/ none(不消费),
结果按适配器类缓存。签名只有 **params 的适配器继续扫描函数体常量,
覆盖在内部 params.pop("account_id") 的实现。
- adapter: 适配器实例
返回值: 账户字段名模式
_warn_account_unconsumed(adapter) -> None
适配器不消费账户字段时提示一次(每个适配器类仅一次)
_adapt_account_param(adapter, params: dict) -> dict
按适配器实现改写标准账户字段名(兼容旧适配器)
标准实现(消费
account_id):原样传递旧实现(只有
_account_id):改写为旧名,Using()继续生效完全不消费:剔除字段避免泄漏到平台参数,并提示一次 WARNING
adapter: 适配器实例
params: 已合并 api_context 的动作参数
返回值: 改写后的参数
类列表
class ApiDSL
标准 API 动作 DSL 基类
提供 OneBot12 标准动作的强类型方法,模块开发者只需面向标准接口编程, 由适配器负责映射到平台原生 API。
与 SendDSL(消息发送)、RequestDSL(请求操作)并行。覆盖 OneBot12 标准
动作中的用户 / 群组 / 频道(Guild)/ 消息管理 / 元(Meta)常规接口,以及
文件资源动作(upload_file / get_file / 分片,见方法 docstring 降级说明);
唯一例外是 send_message——由 SendDSL.Raw_ob12 承担,不在本类重复。
提示
- 标准方法默认委托给
adapter.call_api(action_name, ...),适配器可按需覆盖- 使用
adapter.Api.Using("bot1").get_user_info("123")指定 Bot 账号- 平台扩展动作通过
call("prefix.action", **params)调用- 所有方法返回标准 API 响应格式(status / retcode / data / message_id / message)
- 适配器可覆盖单个标准方法以映射到平台 API,无需全部实现
- 分片动作按阶段拆分为 prepare / transfer / finish 三个方法(见各自文档)
方法列表
__init__(adapter: 'BaseAdapter', account_id: str | None = None)
初始化标准 API 动作 DSL
- adapter: 所属适配器实例
- account_id: 执行操作的 Bot 账号(可选)
Using(account_id: str | int) -> 'Self'
指定执行操作的 Bot 账号
- account_id: 账号标识
返回值: 新的 ApiDSL 实例
示例:
info = await adapter.myplatform.Api.Using("bot1").get_user_info("123")
api_context -> dict(property)
获取当前 API 操作上下文
account_id 优先取显式 Using() 指定值;未指定时兜底当前事件分发
链路的触发账户(无事件上下文时为 None)。
返回值: 包含 account_id 的字典
_merge_context(params: dict) -> dict
将 api_context 合并到参数字典
优先级:业务参数显式传入的 account_id > Using() > 事件分发链路兜底。
- params: 业务参数
返回值: 合并后的参数字典
async _api_call(action: str, **params: Any) -> dict[str, Any]
内部方法 API 动作统一授权入口
先经作用域出站维度检查(scope.actions.call_api。
name 传标准动作名,支持动作级细粒度规则(如仅放行 get_* 查询类)。
- action (
OneBot12): 标准动作名或平台扩展动作名 - params: 动作参数(已合并 api_context)
返回值: 标准 API 响应
async get_self_info() -> dict[str, Any]
获取机器人自身信息
返回值: 标准响应,data 包含 user_id / user_name / user_displayname
示例:
result = await adapter.myplatform.Api.get_self_info()
my_name = result["data"]["user_name"]
async get_user_info(user_id: str) -> dict[str, Any]
获取用户信息
- user_id: 用户 ID(可以是好友,也可以是陌生人)
返回值: 标准响应,data 包含 user_id / user_name / user_displayname / user_remark
示例:
result = await adapter.myplatform.Api.get_user_info("123456")
user_name = result["data"]["user_name"]
async get_friend_list() -> dict[str, Any]
获取好友列表
返回值: 标准响应,data 为好友信息列表
示例:
result = await adapter.myplatform.Api.get_friend_list()
friends = result["data"]
async get_group_info(group_id: str) -> dict[str, Any]
获取群信息
- group_id: 群 ID
返回值: 标准响应,data 包含 group_id / group_name
示例:
result = await adapter.myplatform.Api.get_group_info("123456")
group_name = result["data"]["group_name"]
async get_group_list() -> dict[str, Any]
获取群列表
返回值: 标准响应,data 为群信息列表
示例:
result = await adapter.myplatform.Api.get_group_list()
groups = result["data"]
async get_group_member_info(group_id: str, user_id: str) -> dict[str, Any]
获取群成员信息
- group_id: 群 ID
- user_id: 用户 ID
返回值: 标准响应,data 包含 user_id / user_name / user_displayname
示例:
result = await adapter.myplatform.Api.get_group_member_info("123", "456")
member = result["data"]
async get_group_member_list(group_id: str) -> dict[str, Any]
获取群成员列表
- group_id: 群 ID
返回值: 标准响应,data 为群成员信息列表
示例:
result = await adapter.myplatform.Api.get_group_member_list("123456")
members = result["data"]
async set_group_name(group_id: str, group_name: str) -> dict[str, Any]
设置群名称
- group_id: 群 ID
- group_name: 新群名称
返回值: 标准响应
示例:
await adapter.myplatform.Api.set_group_name("123456", "新群名")
async leave_group(group_id: str) -> dict[str, Any]
退出群
- group_id: 群 ID
返回值: 标准响应
示例:
await adapter.myplatform.Api.leave_group("123456")
async get_guild_info(guild_id: str) -> dict[str, Any]
获取频道(服务器)信息
- guild_id: 频道 ID
返回值: 标准响应,data 包含 guild_id / guild_name
示例:
result = await adapter.myplatform.Api.get_guild_info("100001")
guild_name = result["data"]["guild_name"]
async get_guild_list() -> dict[str, Any]
获取频道(服务器)列表
返回值: 标准响应,data 为 list[get_guild_info 响应]
示例:
result = await adapter.myplatform.Api.get_guild_list()
guilds = result["data"]
async set_guild_name(guild_id: str, guild_name: str) -> dict[str, Any]
设置频道(服务器)名称
- guild_id: 频道 ID
- guild_name: 新的频道名称
返回值: 标准响应
示例:
await adapter.myplatform.Api.set_guild_name("100001", "新频道名")
async get_guild_member_info(guild_id: str, user_id: str) -> dict[str, Any]
获取频道(服务器)成员信息
- guild_id: 频道 ID
- user_id: 用户 ID
返回值: 标准响应,data 包含 user_id / user_name / user_displayname
示例:
result = await adapter.myplatform.Api.get_guild_member_info("100001", "123456")
display_name = result["data"]["user_displayname"]
async get_guild_member_list(guild_id: str) -> dict[str, Any]
获取频道(服务器)成员列表
- guild_id: 频道 ID
返回值: 标准响应,data 为 list[get_guild_member_info 响应]
示例:
result = await adapter.myplatform.Api.get_guild_member_list("100001")
members = result["data"]
async leave_guild(guild_id: str) -> dict[str, Any]
退出频道(服务器)
- guild_id: 频道 ID
返回值: 标准响应
示例:
await adapter.myplatform.Api.leave_guild("100001")
async get_channel_info(guild_id: str, channel_id: str) -> dict[str, Any]
获取频道下的子频道信息
- guild_id: 频道(服务器)ID
- channel_id: 子频道 ID
返回值: 标准响应,data 包含 channel_id / channel_name
示例:
result = await adapter.myplatform.Api.get_channel_info("100001", "200001")
channel_name = result["data"]["channel_name"]
async get_channel_list(guild_id: str, *, joined_only: bool = False) -> dict[str, Any]
获取频道下的子频道列表
- guild_id: 频道(服务器)ID
- joined_only: 仅返回已加入的子频道(默认 False)
返回值: 标准响应,data 为 list[get_channel_info 响应]
示例:
result = await adapter.myplatform.Api.get_channel_list("100001")
channels = result["data"]
async set_channel_name(guild_id: str, channel_id: str, channel_name: str) -> dict[str, Any]
设置子频道名称
- guild_id: 频道(服务器)ID
- channel_id: 子频道 ID
- channel_name: 新的子频道名称
返回值: 标准响应
示例:
await adapter.myplatform.Api.set_channel_name("100001", "200001", "新子频道名")
async get_channel_member_info(guild_id: str, channel_id: str, user_id: str) -> dict[str, Any]
获取子频道成员信息
- guild_id: 频道(服务器)ID
- channel_id: 子频道 ID
- user_id: 用户 ID
返回值: 标准响应,data 包含 user_id / user_name / user_displayname
示例:
result = await adapter.myplatform.Api.get_channel_member_info("100001", "200001", "123456")
async get_channel_member_list(guild_id: str, channel_id: str) -> dict[str, Any]
获取子频道成员列表
- guild_id: 频道(服务器)ID
- channel_id: 子频道 ID
返回值: 标准响应,data 为 list[get_channel_member_info 响应]
示例:
result = await adapter.myplatform.Api.get_channel_member_list("100001", "200001")
members = result["data"]
async leave_channel(guild_id: str, channel_id: str) -> dict[str, Any]
退出子频道
- guild_id: 频道(服务器)ID
- channel_id: 子频道 ID
返回值: 标准响应
示例:
await adapter.myplatform.Api.leave_channel("100001", "200001")
async delete_message(message_id: str) -> dict[str, Any]
撤回 / 删除消息
- message_id: 消息 ID
返回值: 标准响应
示例:
await adapter.myplatform.Api.delete_message("msg_123456")
async upload_file(*, type: str, name: str, url: str | None = None, path: str | None = None, data: bytes | None = None, headers: dict[str, str] | None = None, sha256: str | None = None) -> dict[str, Any]
上传文件到平台资源库(OB12 文件资源模型)
.. note:: 依赖平台特有的 file_id 文件资源能力,通用性不足,ErisPulse
常规路径不使用——模块发送文件请用 SendDSL.File(file)(发送时直传)。
本方法仅当适配器后端具备 file_id 资源能力时透传;多数平台适配器
不会实现它,调用方需自行处理 10002。
file_id 资源模型标准化到框架层是未来方向,当前版本不提供。
- type: 上传方式(
url/path/data) - name: 文件名(如
foo.jpg) - url: 文件 URL(
type="url"时必须传入) - path: 文件路径(
type="path"时必须传入) - data: 文件数据(
type="data"时必须传入) - headers: 下载 URL 时附加的 HTTP 请求头(可选)
- sha256: 文件数据的 SHA256 校验和(可选)
返回值: 标准响应,data 包含 file_id
示例:
result = await adapter.Api.upload_file(type="url", name="logo.jpg", url="https://example.com/logo.jpg")
file_id = result["data"]["file_id"]
async get_file(file_id: str, type: str = 'url') -> dict[str, Any]
从平台资源库获取文件(OB12 文件资源模型)
.. note:: 依赖平台特有的 file_id 文件资源能力,通用性不足,ErisPulse
常规路径不使用;仅当适配器后端具备该能力时透传,多数平台不会实现
(返回 10002)。file_id 资源模型标准化到框架层是未来方向,
当前版本不提供。
- file_id: 文件 ID
- type: 获取方式(
url/path/data),默认url
返回值: 标准响应,data 包含 name / url 或 path 或 data
示例:
result = await adapter.myplatform.Api.get_file("file_abc", "url")
download_url = result["data"]["url"]
async upload_file_fragmented_prepare(name: str, total_size: int) -> dict[str, Any]
分片上传 · 准备阶段(OB12 文件资源模型,见分组说明——框架内尚无实现方)
分片上传三步:prepare → transfer(循环,逐片调用)→ finish。
本方法为第一阶段,创建传输会话并返回 file_id(后续阶段使用)。
- name: 文件名(如
foo.jpg) - total_size: 完整文件大小(字节)
返回值: 标准响应,data 包含 file_id(仅供传输阶段使用)
示例:
r = await adapter.Api.upload_file_fragmented_prepare("foo.jpg", 1048576)
file_id = r["data"]["file_id"]
async upload_file_fragmented_transfer(file_id: str, offset: int, data: bytes) -> dict[str, Any]
分片上传 · 传输阶段(OB12 文件资源模型,见分组说明——框架内尚无实现方)
将文件按字节偏移逐片写入:offset 从 0 开始,每片长度为 len(data)。
- file_id (
prepare): 阶段返回的文件 ID - offset: 本次分片的字节偏移
- data: 本次分片数据
返回值: 标准响应
示例:
await adapter.Api.upload_file_fragmented_transfer(file_id, 0, chunk)
await adapter.Api.upload_file_fragmented_transfer(file_id, len(chunk), next_chunk)
async upload_file_fragmented_finish(file_id: str, sha256: str) -> dict[str, Any]
分片上传 · 完成阶段(OB12 文件资源模型,见分组说明——框架内尚无实现方)
- file_id (
prepare): 阶段返回的文件 ID - sha256: 整个文件的 SHA256(全小写十六进制)
返回值: 标准响应,data 包含 file_id(供以后使用)
示例:
await adapter.Api.upload_file_fragmented_finish(file_id, sha256_hex)
async get_file_fragmented_prepare(file_id: str) -> dict[str, Any]
分片下载 · 准备阶段(OB12 文件资源模型,见分组说明——框架内尚无实现方)
分片下载两步:prepare(获取文件元信息)→ transfer(循环取片)。
- file_id: 文件 ID
返回值: 标准响应,data 包含 name / total_size / sha256
示例:
r = await adapter.Api.get_file_fragmented_prepare("file_abc")
meta = r["data"]
async get_file_fragmented_transfer(file_id: str, offset: int, size: int) -> dict[str, Any]
分片下载 · 传输阶段(OB12 文件资源模型,见分组说明——框架内尚无实现方)
按 offset 取一片,size 为本次请求的字节数(最后一片可小于 size)。
- file_id: 文件 ID
- offset: 本次分片的字节偏移
- size: 本次请求大小(字节)
返回值: 标准响应,data 包含 data(本次分片字节)
示例:
while offset < total_size:
r = await adapter.Api.get_file_fragmented_transfer(file_id, offset, 65536)
offset += len(r["data"]["data"])
async get_latest_events(limit: int = 0, timeout: int = 0) -> dict[str, Any]
获取最新事件(仅 HTTP 通信方式必须支持)
- limit: 最多返回事件数量(0 = 不限制)
- timeout: 长轮询等待秒数(0 = 短轮询,不等待)
返回值: 标准响应,data 为事件对象数组(从旧到新,不含元事件)
async get_supported_actions() -> dict[str, Any]
获取实现支持的动作列表
返回值: 标准响应,data 为动作名字符串数组(可能不含 get_latest_events)
async get_status() -> dict[str, Any]
获取运行状态
返回值: 标准响应,data 包含 good / bots
- good: 各模块是否均正常(bool)
- bots: 机器人账号状态列表,每项含 self{platform, user_id} 与 online
async get_version() -> dict[str, Any]
获取实现版本信息
返回值: 标准响应,data 包含 impl / version / onebot_version
async call(action: str, **params: Any) -> dict[str, Any]
调用平台扩展动作(逃生舱)
用于调用 OneBot12 标准之外的平台扩展动作。
建议使用 {prefix}.{action} 命名(如 telegram.send_sticker),
遵循 OneBot12 扩展规则。
- action: 动作名称(标准动作名或
{prefix}.{action}扩展动作名) - params: 动作参数
返回值: 标准响应格式
示例:
# 调用平台扩展动作
result = await adapter.myplatform.Api.call("telegram.send_sticker", sticker_id="CAACAgIAAxkBAA...")
# 也可用于调用标准动作(等价于直接调用对应方法)
result = await adapter.myplatform.Api.call("get_user_info", user_id="123")