Awesome Open Source
Awesome Open Source

stars download release license

QQLight机器人框架的WebSocket-RPC插件

插件通过WebSocket与JSON实现远程过程调用,让你能使用任何喜欢的语言编写QQ机器人程序

插件下载地址

使用方法

将插件复制到QQLight机器人框架的plugin目录中,运行QQLight机器人并在插件管理中启用插件

插件启动后默认监听49632端口,在本机可以使用WebSocket客户端通过URLws://localhost:49632/连接服务器

配置

第一次启动插件后会在插件数据目录plugin/websocket.protocol中生成config.json文件,里面提供了一些插件配置项

你可以修改这些插件配置项并保存文件,然后重新启动插件使新的配置生效

address

服务器监听地址,默认为127.0.0.1,即只允许本机连接服务器,如果你希望通过外网连接服务器,可以设置为0.0.0.0

port

服务器监听端口号,默认为49632

path

WebSocket握手时的URL路径,默认为根路径/,即通过ws://localhost:49632/连接服务器。如果将路径修改为/xxx/yyy,则需要通过ws://localhost:49632/xxx/yyy才能连接服务器

路径应该只包含字母数字/,当允许通过外网连接服务器时,请设置一个足够复杂的路径,防止被他人恶意连接

示例

浏览器示例

这是一个复读机(Echo)的Javascript示例,可以直接运行在浏览器上:

var ws = new WebSocket('ws://localhost:49632/');
ws.onmessage = function(ev) {
    var data   = JSON.parse(ev.data);
    var params = data.params;
    if(data.event === 'message') {
        var rpc = {
            id: Math.random().toString(),
            method: "sendMessage",
            params: {
                type    : params.type,
                group   : params.group,
                qq      : params.qq,
                content : params.content
            }
        };
        ws.send(JSON.stringify(rpc));
    }
}

Node.js示例

这是一个复读机(Echo)的Node.js示例,使用了ws模块:

const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:49632/');
ws.on('message', data => {
    data = JSON.parse(data);
    if(data.event === 'message') {
        ws.send(JSON.stringify({
            id: Math.random().toString(),
            method: 'sendMessage',
            params: {...data.params}
        }));
    }
});

API文档

服务端与客户端发送的消息都是顶层结构为对象的JSON格式文本,文本编码为UTF-8

事件

事件是服务器会主动发送给客户端的消息,如机器人收到好友请求时,服务器会向客户端发送如下格式的消息:

{
    "event": "friendRequest", 
    "params": {
        "qq"      : "123456",
        "message" : ""
    }
}

接口

接口是客户端可以发送给服务器的消息,服务器收到消息会调用机器人相应的方法处理,下面是删除好友的消息示例:

{
    "id"    : "1024"
    "method": "deleteFriend", 
    "params": {
        "qq": ""
    }
}

所有接口调用必须携带字符串类型的id字段,且每次请求都应该使用不同的id,服务器返回结果会包含与调用时相同的idid用于分辨返回的数据属于哪个调用

接口返回

无返回值的接口调用成功会返回仅包含id字段的对象:

{
    "id"    : "1024"
}

有返回值的接口调用成功会返回包含idresult字段的对象,其中result字段类型与值视具体接口而定:

{
    "id"    : "1024"
    "result": true
}

接口调用发生错误会返回包含iderror字段的对象,其中error字段为字符串类型的错误信息:

{
    "id"   : "1024"
    "error": "Unknown Method"
}

API列表

事件.收到消息

{
    "event": "message", 
    "params": {
        "type"    : 2,   // 1=好友消息、2=群消息、3=群临时消息、4=讨论组消息、5=讨论组临时消息、6=QQ临时消息
        "group"   : "",  // 类型为1或6的时候,此参数为空字符串,其余情况下为群号或讨论组号
        "qq"      : "",  // 消息来源QQ号,"10000"都是来自系统的消息(比如某人被禁言或某人撤回消息等)
        "content" : "",  // 消息内容
        "msgid"   : ""   // 消息id,撤回消息的时候会用到,群消息会存在,其余情况下为空  
    }
}

事件.收到好友请求

{
    "event": "friendRequest", 
    "params": {
        "qq"      : "",
        "message" : ""      // 验证消息
    }
}

收到该事件时可以通过调用接口.处理好友请求处理

事件.好友变动

{
    "event": "friendChange", 
    "params": {
        "type": 1,          // 1.成为好友(单向) 2.成为好友(双向) 3、被删除好友
        "qq": ""
    }
}

事件.群成员增加

{
    "event": "groupMemberIncrease", 
    "params": {
        "type"      : 1,        // 1=主动加群、2=被管理员邀请
        "group"     : "",       //
        "qq"        : "",       //
        "operator"  : ""        // 操作者QQ
    }
}

事件.群成员减少

{
    "event": "groupMemberDecrease", 
    "params": {
        "type"      : 1,        // 1=主动退群、2=被管理员踢出
        "group"     : "",       //
        "qq"        : "",       //
        "operator"  : ""        // 操作者QQ,仅在被管理员踢出时存在
    }
}

事件.群管理员变动

{
    "event": "adminChange", 
    "params": {
        "type"      : 1,        // 1=成为管理 2=被解除管理
        "group"     : "",       //
        "qq"        : ""        //
    }
}

事件.加群请求

{
    "event": "groupRequest", 
    "params": {
        "type"      : 1,        // 1=主动加群、2=被邀请进群、3=机器人被邀请进群
        "group"     : "",       //
        "qq"        : "",       //
        "operator"  : "",       // 邀请者QQ,主动加群时不存在
        "message"   : "",       // 加群附加消息,只有主动加群时存在
        "seq"       : ""        // 序列号,处理加群请求时需要用到
    }
}

type为1时,指有人主动申请进群,这时operator字段为空,如果你是管理员,可以调用接口.处理加群请求处理

type为2时,指群员邀请别人进群,这时message字段为空,如果你是管理员,可以调用接口.处理加群请求处理

type为3时,指机器人被邀请进群,这时message字段为空,可以调用接口.处理加群请求处理

事件.收款

{
    "event": "receiveMoney", 
    "params": {
        "type"      : 1,        // 1=好友转账、2=群临时会话转账、3=讨论组临时会话转账
        "group"     : "",       // type为1时此参数为空,type为2、3时分别为群号或讨论组号
        "qq"        : "",       // 转账者QQ
        "amount"    : "",       // 转账金额
        "message"   : "",       // 转账备注消息
        "id"        : ""        // 转账订单号
    }
}

接口.发送消息

{
    "method": "sendMessage", 
    "params": {
        "type"    : 2,      // 1=好友消息、2=群消息、3=群临时消息、4=讨论组消息、5=讨论组临时消息、6=QQ临时消息
        "group"   : "",     // 群号或讨论组号,发送消息给好友的情况下忽略
        "qq"      : "",     // QQ号,发送消息给群或讨论组的情况下忽略
        "content" : ""
    }
}

无返回值

接口.撤回消息

{
    "method": "withdrawMessage", 
    "params": {
        "group": "",
        "msgid": ""
    }
}

无返回值

接口.获取好友列表

{
    "method" : "getFriendList",
    "params": {
        "cache": true       // 是否缓存结果
    }
}

接口.添加好友

{
    "method": "addFriend", 
    "params": {
        "qq"        : "",
        "message"   : ""       // 验证消息,可选
    }
}

无返回值

接口.删除好友

{
    "method": "deleteFriend", 
    "params": {
        "qq": ""
    }
}

无返回值

接口.获取群列表

{
    "method": "getGroupList",
    "params": {
        "cache": true       // 是否缓存结果
    }
}

接口.获取群成员列表

{
    "method": "getGroupMemberList",
    "params": {
        "group": "",
        "cache": true       // 是否缓存结果
    }
}

接口.添加群

{
    "method": "addGroup", 
    "params": {
        "group"     : "",
        "message"   : ""    // 验证消息,可选
    }
}

无返回值

接口.退出群

{
    "method": "quitGroup", 
    "params": {
        "group": ""
    }
}

无返回值

接口.获取群名片

{
    "method": "getGroupCard", 
    "params": {
        "group" : "",
        "qq"    : ""
    }
}

接口.上传图片

{
    "method": "uploadImage",
    "params": {
        "type"  : 2,        // 1=私聊类型的图片、2=群组类型的图片
        "object": ""        // 图片准备发送到的QQ号或群组号
        "data"  : ""        // 图像数据转换的十六进制字符串
    }
}

该接口并不发送图片,而是将图片上传到QQ服务器,并返回GUIDGUID用法参见替换符.image/flash

所获得的GUID只能对typeobject指定的对象使用,否则图片可能无法显示

接口.获取QQ资料

{
    "method": "getQQInfo",
    "params": {
        "qq": ""
    }
}

接口.获取群资料

{
    "method": "getGroupInfo",
    "params": {
        "group": ""
    }
}

接口.邀请好友入群

{
    "method": "inviteIntoGroup",
    "params": {
        "qq"    : "",
        "group" : ""
    }
}

无返回值

接口.设置群名片

{
    "method": "setGroupCard", 
    "params": {
        "group" : "",
        "qq"    : "",
        "name"  : ""
    }
}

无返回值

接口.获取当前登录账号

{
    "method": "getLoginAccount"
}

接口.设置个性签名

{
    "method": "setSignature",
    "params": {
        "content": ""
    }
}

无返回值

接口.获取QQ昵称

{
    "method": "getNickname",
    "params": {
        "qq": ""
    }
}

接口.设置QQ昵称

{
    "method": "setNickname",
    "params": {
        "name": ""
    }
}

无返回值

接口.获取名片点赞数量

{
    "method": "getPraiseCount",
    "params": {
        "qq": ""
    }
}

接口.点赞名片

{
    "method": "givePraise",
    "params": {
        "qq": ""
    }
}

无返回值

接口.处理好友请求

{
    "method": "handleFriendRequest",
    "params": {
        "qq"       : "",
        "type"     : 1,      // 1=同意、2=拒绝、3=忽略
        "message"  : ""      // 拒绝理由,仅在拒绝请求时有效
    }
}

无返回值

接口.设置在线状态

{
    "method": "setState",
    "params": {
        "type": 1  // 1=我在线上、2=Q我吧、3=离开、4=忙碌、5=请勿打扰、6=隐身
    }
}

无返回值

接口.处理加群请求

{
    "method": "handleGroupRequest",
    "params": {
        "group"     : "",
        "qq"        : "",
        "seq"       : "",   // 加群请求事件提供的序列号
        "type"      : 1,    // 1=同意、2=拒绝、3=忽略
        "message"   : ""    // 拒绝时的拒绝理由,其它情况忽略
    }
}

无返回值

接口.移除群成员

{
    "method": "kickGroupMember",
    "params": {
        "group" : "",
        "qq"    : ""
    }
}

无返回值

接口.禁言

{
    "method": "silence",
    "params": {
        "group"     : "",
        "qq"        : "",
        "duration"  : 0     // 禁言时间,单位为秒,为0时解除禁言
    }
}

无返回值

接口.全体禁言

{
    "method": "globalSilence",
    "params": {
        "group"   : "",
        "enable"  : true     // true为全体禁言,false为取消全体禁言
    }
}

无返回值

接口.获取Cookies

{
    "method": "getCookies"
}

接口.获取Bkn

{
    "method": "getBkn",
    "cookies": ""
}

接口.获取长Bkn

{
    "method": "getBknLong",
    "cookies": ""
}

接口.发表空间说说

{
    "method": "sendQzone", 
    "params": {
        "content" : ""      // 内容,发送到空间说说的内容,目前仅支持文本内容
    }
}

替换符.at

在发送的群消息中使用[QQ:at=xxx]表示at某个群成员,其中xxx可以替换为任意群成员QQ

使用[QQ:at=all]表示at全体成员,但仅在发送者为群管理员时有效

替换符.face/emoji

在发送的消息中使用[QQ:face=212]代表一个QQ表情,其中212为表情代码,使用[QQ:emoji=39091]代表一个emoji表情

这里不提供QQ表情和emoji表情的表情代码,你需要自己想办法获取它们

替换符.image/flash

发送消息中使用[QQ:pic=xxx]代表一张图片,[QQ:flash,pic=xxx]代表一张闪照

其中xxx可以是图片GUID,也可以是图片URL,图片GUID可以通过调用接口.上传图片接口获得

语言绑定

插件提供了较为低级的接口,当使用其它语言调用时,通常需要根据语言特性进行封装以方便开发,下面是一些已有的语言绑定:

编译环境

MinGW 3.4.5

许可证

GLWT(祝你好运)公共许可证
版权所有(C)每个人,除了作者

任何人都被允许复制、分发、修改、合并、销售、出版、再授权或
任何其它操作,但风险自负。

作者对这个项目中的代码一无所知。
代码处于可用或不可用状态,没有第三种情况。


                祝你好运公共许可证
            复制、分发和修改的条款和条件

0:在不导致作者被指责或承担责任的情况下,你可以做任何你想
要做的事情。

无论是在合同行为、侵权行为或其它因使用本软件产生的情形,作
者不对任何索赔、损害承担责任。

祝你好运及一帆风顺

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
C (274,193
Json (10,998
Plugin (9,792
Websocket (5,268
Qq (331
Qqbot (239
Related Projects