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

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

你可以用 QQBot 來實現：
* 監控、收集 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 客戶端掃碼并授權登錄。啟動成功后，會將本次登錄信息保存到本地文件中，下次啟動時，可以輸入： **qqbot qq號碼**，或：**python qqbot.py qq號碼** ，先嘗試從本地文件中恢復登錄信息（不需要手動掃碼），只有恢復不成功或登錄信息已過期時才會需要手動掃碼登錄。
##### 2. 操作 QQBot
QQ 機器人啟動后，用另外一個 QQ 向本 QQ 發送消息即可操作 QQBot 。目前提供以下命令：
? ? 1） 幫助：
? ? ? ? -help
? ? 2） 列出 好友/群/討論組:
? ? ? ? -list buddy/group/discuss
? ? 3） 向 好友/群/討論組 發送消息:
? ? ? ? -send buddy/group/discuss uin message
? ? ? ? 其中 uin 是臨時 qq 號，利用 -list 命令查看好友等的臨時 qq 號。? ?
? ? 4） 停止 QQBot ：
? ? ? ? -stop

四、實現你自己的 QQ 機器人
實現自己的 QQ 機器人非常簡單，只需要繼承 [qqbot.py][code] 中提供的 **QQBot** 類并重新實現此類中的消息響應方法 **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機器人已關閉')
????
????myqqbot?=?MyQQBot()
????myqqbot.Login()
????myqqbot.PollForever()

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

五、 QQBot 類中的主要方法、屬性
#### 1. 構造方法、登錄方法、主要屬性

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

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

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

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

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

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

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

????>>>?bot.PullForever()

**PullForever** 方法會不停的調用 poll 方法，并將 poll 方法的返回值傳遞給 **onPullComplete** 方法，直到 stopped 屬性變為 True 。如下：

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

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

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

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

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

### 七、反饋

有任何問題或建議可以發郵件給我，郵箱： 。