概览与核心约定
萌喵 64 位 Windows DLL 插件开发包的整体架构、命名约定、内存生命周期与并发规则。
萌喵插件是一个 64 位 Windows DLL,安装后放置在 <程序目录>/plugins/<插件ID>.dll,由主程序直接加载运行。插件只需引入单头文件 plugin.h 即可调用所有公开接口。
插件 ID 命名规则
插件 ID 采用域名风格(例如 mmiao.app、weather.example.com):
- 至少包含两段,使用
.分隔 - 每段由小写字母、数字、下划线组成,且必须以小写字母开头
- 总长度不超过 128 字节
发布后请勿更改插件 ID
插件 ID 是插件的唯一身份标识。修改 ID 后会被识别为全新插件,原有的数据目录与启用状态将无法延续。
基础类型与命名约定
| 概念 | 统一名称 | 类型 | 说明 |
|---|---|---|---|
| Bot 自身账号(QQ 号) | self_id | uint64_t | 接收事件或发起操作的 Bot 账号 |
| 对方账号(好友 / 群成员等) | user_id | uint64_t | 好友、发送人或目标成员的 QQ 号 |
| 群号 | group_id | uint64_t | 用户可见的群号 |
| 账号平台 | platform | const char * | PLATFORM_ANDROID("android")或 PLATFORM_PC("pc") |
| 账号协议 | protocol | const char * | PROTOCOL_* 标识,如 "qq_phone"、"tim_pad";协议决定所属平台 |
- 字符串编码:所有字符串一律为以
\0结尾的 UTF-8const char *。 - 结果判定:
- 返回
bool的接口:true表示成功,false表示失败。 - 返回带
code结构体指针的接口:code == 0表示成功(登录结果还需同时满足attempt_id为空);本地失败时code == RESULT_LOCAL_ERROR(-1),服务端拒绝时保留服务端返回的code与error/msg。 - 返回指针的接口:
NULL表示客户端未提供该接口或未取得结果,不得将非NULL指针直接当作业务成功。
- 返回
内存与资源生命周期
- 回调参数:
on_group_message、on_friend_message、on_group_event、on_friend_event传入的结构体及所有字符串仅在当前回调期间有效。异步处理或长期保存时必须自行复制。 - API 返回值:由主程序分配的结果结构体或字符串,无论成功还是失败,用完后都必须调用对应的
free_*函数交还(传NULL安全,不做处理)。- 交还后,结构体及其内部所有数组、字符串立即失效。
- 禁止逐项释放内部指针,也禁止使用插件自己的
free()释放。 - 借用字符串(如
data_dir()的返回值)在整个载入期间有效,不可修改或传给free_string()。
- 列表遍历:访问
AccountList、DeviceList、FriendList、GroupList、StringList时只按count遍历;count == 0时不要读取items。 - 插件元信息:
plugin_info()返回的PluginInfo结构体及其字符串由插件自身持有,在本次载入期间必须持续有效(推荐使用静态变量)。
线程模型与并发要求
- 多线程并发回调:不同账号的消息和事件可能由多个线程同时投递;同一账号的消息和事件按到达顺序依次调用。
- 不要阻塞回调:所有回调应尽快返回。涉及网络等待的接口(登录、发消息、媒体上传、查列表、处理申请等)必须在插件自己的工作线程中调用(所需参数先从回调中复制)。
- 安全退出线程:DLL 释放后插件代码即从进程卸载,所有自建线程必须在
plugin_switch(false)或plugin_uninstall()返回前全部结束并回收句柄。 - 避免在
DllMain执行业务逻辑:安装或更新插件时,主程序会临时载入 DLL 读取plugin_info()。
权限、存储与容错
- 权限控制:标注为受权限控制的接口,其权限名与函数名一致。新导入插件默认全部开启,用户可在客户端插件页逐项关闭;权限被关闭时调用失败。
- 数据目录:插件配置、数据库等本地文件应存放在
data_dir()返回的目录中(<程序目录>/plugins/data/<插件ID>/),不要依赖 DLL 所在路径。目录不可写时应报告保存失败。 - 网络失败不盲目重试:网络超时或断连不代表服务端未执行该操作。发送消息、处理好友/群申请、领取红包等具有副作用的操作,失败后应先核实状态,不要盲目重试。
- 向前兼容:遇到不认识的事件类型、消息段或 JSON 字段时按未知内容处理,不要猜测其业务含义;读取 64 位整数(如
request_seq)时不要使用浮点数存储以免丢失精度。