跳转到正文

概览与核心约定

萌喵 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_iduint64_t接收事件或发起操作的 Bot 账号
对方账号(好友 / 群成员等)user_iduint64_t好友、发送人或目标成员的 QQ 号
群号group_iduint64_t用户可见的群号
账号平台platformconst char *PLATFORM_ANDROID("android")或 PLATFORM_PC("pc")
账号协议protocolconst char *PROTOCOL_* 标识,如 "qq_phone"、"tim_pad";协议决定所属平台
  • 字符串编码:所有字符串一律为以 \0 结尾的 UTF-8 const char *。
  • 结果判定:
    • 返回 bool 的接口:true 表示成功,false 表示失败。
    • 返回带 code 结构体指针的接口:code == 0 表示成功(登录结果还需同时满足 attempt_id 为空);本地失败时 code == RESULT_LOCAL_ERROR(-1),服务端拒绝时保留服务端返回的 code 与 error / msg。
    • 返回指针的接口:NULL 表示客户端未提供该接口或未取得结果,不得将非 NULL 指针直接当作业务成功。

内存与资源生命周期

  1. 回调参数:on_group_message、on_friend_message、on_group_event、on_friend_event 传入的结构体及所有字符串仅在当前回调期间有效。异步处理或长期保存时必须自行复制。
  2. API 返回值:由主程序分配的结果结构体或字符串,无论成功还是失败,用完后都必须调用对应的 free_* 函数交还(传 NULL 安全,不做处理)。
    • 交还后,结构体及其内部所有数组、字符串立即失效。
    • 禁止逐项释放内部指针,也禁止使用插件自己的 free() 释放。
    • 借用字符串(如 data_dir() 的返回值)在整个载入期间有效,不可修改或传给 free_string()。
  3. 列表遍历:访问 AccountList、DeviceList、FriendList、GroupList、StringList 时只按 count 遍历;count == 0 时不要读取 items。
  4. 插件元信息:plugin_info() 返回的 PluginInfo 结构体及其字符串由插件自身持有,在本次载入期间必须持续有效(推荐使用静态变量)。

线程模型与并发要求

  • 多线程并发回调:不同账号的消息和事件可能由多个线程同时投递;同一账号的消息和事件按到达顺序依次调用。
  • 不要阻塞回调:所有回调应尽快返回。涉及网络等待的接口(登录、发消息、媒体上传、查列表、处理申请等)必须在插件自己的工作线程中调用(所需参数先从回调中复制)。
  • 安全退出线程:DLL 释放后插件代码即从进程卸载,所有自建线程必须在 plugin_switch(false) 或 plugin_uninstall() 返回前全部结束并回收句柄。
  • 避免在 DllMain 执行业务逻辑:安装或更新插件时,主程序会临时载入 DLL 读取 plugin_info()。

权限、存储与容错

  • 权限控制:标注为受权限控制的接口,其权限名与函数名一致。新导入插件默认全部开启,用户可在客户端插件页逐项关闭;权限被关闭时调用失败。
  • 数据目录:插件配置、数据库等本地文件应存放在 data_dir() 返回的目录中(<程序目录>/plugins/data/<插件ID>/),不要依赖 DLL 所在路径。目录不可写时应报告保存失败。
  • 网络失败不盲目重试:网络超时或断连不代表服务端未执行该操作。发送消息、处理好友/群申请、领取红包等具有副作用的操作,失败后应先核实状态,不要盲目重试。
  • 向前兼容:遇到不认识的事件类型、消息段或 JSON 字段时按未知内容处理,不要猜测其业务含义;读取 64 位整数(如 request_seq)时不要使用浮点数存储以免丢失精度。

本页目录