PyQQbotPython 實現(xiàn)的 QQ 機器人

一、介紹
QQBot 是一個用 python 實現(xiàn)的、基于騰訊 SmartQQ 協(xié)議的簡單 QQ 機器人，可運行在 Linux 和 Windows 平臺下，所有代碼均集成在一個 [qqbot.py][code] 文件中，代碼量僅 400 多行（不包括注釋）。程序采用單線程的方式運行，且盡可能的減少了網(wǎng)絡(luò)和登錄錯誤（特別是所謂的 103 error ）發(fā)生的概率。
[code]: https://raw.githubusercontent.com/pandolia/qqbot/master/qqbot.py

本項目 github 地址： https://github.com/pandolia/qqbot/

你可以用 QQBot 來實現(xiàn)：
* 監(jiān)控、收集 QQ 消息
* 自動消息推送
* 聊天機器人
* 通過 QQ 遠程控制電腦、智能家電

二、安裝方法
在 Python 2.7 下使用，用 pip 安裝，安裝命令：

$ pip install qqbot

也可以直接下載 [qqbot.py][code] 運行，但需先安裝 [requests](https://pypi.python.org/pypi/requests) 庫。

三、使用方法
##### 1. 啟動 QQBot
在命令行輸入： **qqbot** ，或直接運行 [qqbot.py][code] ： **python qqbot.py** 。啟動過程中會自動彈出二維碼圖片（Linux下需安裝有 gvfs ，否則需要手動打開圖片），需要用手機 QQ 客戶端掃碼并授權(quán)登錄。啟動成功后，會將本次登錄信息保存到本地文件中，下次啟動時，可以輸入： **qqbot qq號碼**，或：**python qqbot.py qq號碼** ，先嘗試從本地文件中恢復登錄信息（不需要手動掃碼），只有恢復不成功或登錄信息已過期時才會需要手動掃碼登錄。
##### 2. 操作 QQBot
QQ 機器人啟動后，用另外一個 QQ 向本 QQ 發(fā)送消息即可操作 QQBot 。目前提供以下命令：
    1） 幫助：
        -help
    2） 列出 好友/群/討論組:
        -list buddy/group/discuss
    3） 向 好友/群/討論組 發(fā)送消息:
        -send buddy/group/discuss uin message
        其中 uin 是臨時 qq 號，利用 -list 命令查看好友等的臨時 qq 號。   
    4） 停止 QQBot ：
        -stop

四、實現(xiàn)你自己的 QQ 機器人
實現(xiàn)自己的 QQ 機器人非常簡單，只需要繼承 [qqbot.py][code] 中提供的 **QQBot** 類并重新實現(xiàn)此類中的消息響應(yīng)方法 **onPullComplete** 方法。示例代碼：

    from qqbot import QQBot    
    class MyQQBot(QQBot):
        def onPollComplete(self, msgType, from_uin, buddy_uin, message):
            if message == '-hello':
                self.send(msgType, from_uin, '你好，我是QQ機器人')
            elif message == '-stop':
                self.stopped = True
                self.send(msgType, from_uin, 'QQ機器人已關(guān)閉')
    
    myqqbot = MyQQBot()
    myqqbot.Login()
    myqqbot.PollForever()

以上代碼運行后，用另外一個 QQ 向本 QQ 發(fā)送消息 **“-hello”**，則會自動回復 **“你好，我是 QQ 機器人”**，發(fā)送消息 **“-stop”** 則會關(guān)閉 QQ 機器人。

五、 QQBot 類中的主要方法、屬性
#### 1. 構(gòu)造方法、登錄方法、主要屬性

    >>> bot = QQBot()
    >>> bot.Login()
    ...

構(gòu)造方法生成一個 QQBot 實例，其實沒做任何工作。全部的登錄、獲取 好友/群/討論組 列表的工作在 **Login** 方法中完成。Login 方法會檢查命令行參數(shù) sys.argv 中是否提供了 qq 號碼。若沒有提供 qq 號碼，則需要手動掃碼登錄。登錄后會將登錄信息保存在本地。若提供了 qq 號碼，則會先嘗試從本地恢復會話信息（不需要手動掃碼），只有恢復不成功或登錄信息已過期時才會需要手動掃碼登錄。

QQBot 登錄完成后，可以進行消息收發(fā)了，且 好友/群/討論組 的列表保存在 **buddy, buddyStr, group, groupStr, discuss, discussStr** 屬性當中。

    >>> bot.buddy
    ((1880557506, 'Jack'), (2776164208, 'Mike'), ..., (2536444957, 'Kebi'))
    >>> print bot.buddyStr

    好友列表：
        0, Jack (2348993434)
        1, Mike (348093248)
        ...
#### 2. 消息收發(fā)

    >>> bot.poll()
    ('buddy', 207353438, 207353438, 'hello')
    >>> bot.poll()
    ('', 0, 0, '')
    >>> bot.send('buddy', 45789321, 'hello')

向buddy45789321發(fā)送消息成功
**poll** 方法向 QQ 服務(wù)器查詢消息，如果有未讀消息則會立即返回，返回值為一個四元 tuple ：
    (msgType, from_uin, buddy_uin, message)
其中 **msgType** 可以為 **'buddy'** 、 **'group'** 或 **'discuss'**，分別表示這是一個 **好友消息** 、**群消息** 或 **討論組消息** ； **from_uin** 和 **buddy_uin** 代表消息發(fā)送者的 **uin** ，可以通過 uin 向發(fā)送者回復消息，如果這是一個好友消息，則 from_uin 和 buddy_uin 相同，均為好友的 uin ，如果是群消息或討論組消息，則 from_uin 為該群或討論組的 uin ， buddy_uin 為消息發(fā)送人的 uin ； **message** 為消息內(nèi)容，是一個 **utf8** 編碼的 string 。
如果沒有未讀消息，則 **poll** 方法會一直等待兩分鐘，若期間沒有其他人發(fā)消息過來，則返回一個只含空值的四元 tuple ：
    ('', 0, 0, '')
**send** 方法的三個參數(shù)為 **msgType** 、 **to_uin** 和 **message** ，分別代表 **消息類型** 、**接收者的 uin** 以及 **消息內(nèi)容** ，消息內(nèi)容必須是一個 **utf8** 編碼的 string 。
如果發(fā)送消息的頻率過快， qq 號碼可能會被鎖定甚至封號。因此每發(fā)送一條消息，會強制 sleep 3 秒鐘，每發(fā)送 10 條消息，會強制 sleep 30 秒鐘。同一條消息重復發(fā)送多次也可能被鎖號或封號，因此每條消息發(fā)送之前都會在開頭附加一個隨機數(shù)字。
這里需要注意的是，當 poll 方法因等待消息而阻塞時，不要試圖在另一個線程中調(diào)用 send 方法發(fā)送消息，也不要試圖用多線程的方式同時調(diào)用 send 方法，否則可能引起一些無法預料的錯誤。
#### 3. 無限消息輪詢

    >>> bot.PullForever()

**PullForever** 方法會不停的調(diào)用 poll 方法，并將 poll 方法的返回值傳遞給 **onPullComplete** 方法，直到 stopped 屬性變?yōu)?True 。如下：

    def PollForever(self):
        self.stopped = False
        while not self.stopped:
            pullResult = self.poll()
            self.onPollComplete(*pullResult)

onPollComplete 方法是 QQ 機器人的靈魂。你可以自由發(fā)揮，重寫此方法，實現(xiàn)更智能的機器人。

六、參考資料
QQBot 參考了以下開源項目：

- [ScienJus/qqbot](https://github.com/ScienJus/qqbothttps://github.com/pandolia/qqbot/) （ruby）
- [floatinghotpot/qqbot](https://github.com/floatinghotpot/qqbot) （node.js）

在此感謝以上兩位作者的無私分享，特別是感謝 ScienJus 對 SmartQQ 協(xié)議所做出的深入細致的分析。

### 七、反饋

有任何問題或建議可以發(fā)郵件給我，郵箱： <[email protected]> 。