前言¶
在 DeepSeek Harness（DSH）上做一個能收發 QQ 消息的機器人，繞不開三件事：裝 LinuxQQ、裝 NapCat 這類 OneBot 實現、再分別處理登錄態和啓動。這三件事分散在命令行與多個進程之間，換臺機器就要重做一遍，登錄態也容易丟。下面介紹的 dsh-qq-stack 就是把這一整套流程收進一個插件裏：下載、解包、配置、啓動交給插件，登錄態託管起來，對外只暴露標準的 OneBot 11 接口。
這是什麼¶
dsh-qq-stack 是 DSH 的 QQ 協議端插件，維護者爲 2008BingYu。它解決的是上面說的重複勞動：把 LinuxQQ 與 NapCat 的安裝、啓動、登錄交給插件管理，對上提供 OneBot 11 正向 WebSocket，供任意兼容客戶端接入。倉庫版本爲 1.1.0，許可證 MIT。
核心功能¶
插件的能力按職責拆開看主要有六項：
- 隨引擎啓動：引擎拉起後自動檢查運行環境，缺失時後臺安裝，就緒時直接啓動 QQ
- 標準協議端：OneBot 11 正向 WebSocket，默認監聽
127.0.0.1:3001 - 登錄態託管：掃碼一次後保存賬號，後續啓動使用快速登錄
- 安裝過程可見：分步顯示 LinuxQQ、NapCat 的下載與解壓狀態，以及鏡像測速進度
- 配置可在頁面修改：監聽地址與訪問令牌保存後自動生效
- 運行環境可清理：頁面內一鍵停止 QQ，並刪除已下載的客戶端與登錄數據
安裝啓用¶
安裝命令來自 README 原文：
dsh plugin --profile web add dsh-qq-stack
也可以在插件頁的「添加插件」中填入包名，或使用 Release 中提供的壓縮包。安裝完成後需要重啓一次引擎。
需要注意：插件不會自動安裝運行環境。引擎啓動後約 2 秒會檢查 ~/.dsh/qq-bot：已安裝則直接啓動 QQ；未安裝時只在設置頁提示，需要點擊「開始安裝」後纔會執行下面這幾步：
- 下載 LinuxQQ 客戶端（約 198MB）
- 檢查系統依賴，缺失時按當前發行版安裝對應軟件包
- 測試多個下載源，選擇可用且最快的一個下載 NapCat（約 34MB）
- 解包、寫入 OneBot 配置、生成啓動腳本
- 啓動 QQ
安裝過程與結果記錄在 ~/.dsh/qq-bot/logs/install.log，頁面會同步顯示當前步驟和進度。
典型用法¶
設置頁分「登錄」和「設置」兩個頁面。登錄頁在未登錄時顯示二維碼，用手機 QQ 掃碼並在手機上確認後，二維碼區域會顯示當前狀態；登錄成功後顯示頭像、暱稱與 QQ 號，可切換賬號。設置頁包含連接設置（監聽地址與訪問令牌，修改後自動保存並重啓 QQ 生效）和清理運行環境（停止 QQ 並刪除 ~/.dsh/qq-bot）。
配置文件爲 ~/.dsh/qq-bot/config.env，各鍵如下：
| 鍵 | 默認 | 說明 |
|---|---|---|
DSH_QQ_UIN |
登錄後自動寫入 | 用於快速登錄的 QQ 號 |
DSH_QQ_HOST |
127.0.0.1 |
OneBot 監聽地址 |
DSH_QQ_WS_PORT |
3001 |
OneBot 監聽端口 |
DSH_QQ_TOKEN |
空 | 訪問令牌；留空表示不校驗 |
安裝目錄默認是 ~/.dsh/qq-bot，可通過環境變量 DSH_QQ_ROOT 修改。
接入 OneBot 客戶端時，任意兼容 OneBot 11 的客戶端都可以連接：地址 ws://127.0.0.1:3001，令牌與 DSH_QQ_TOKEN 一致，該值爲空時無需填寫。
出問題時看日誌，路徑如下：
| 路徑 | 內容 |
|---|---|
~/.dsh/qq-bot/logs/plugin.log |
插件操作日誌：按鈕請求、狀態變化、保存/應用/登出等（令牌已脫敏，超過 2MB 輪轉） |
~/.dsh/qq-bot/logs/install.log |
安裝過程與各步驟進度 |
~/.dsh/qq-bot/logs/qq.log |
QQ 與 NapCat 運行日誌 |
頁面上的每個操作都會記進 plugin.log，也可以直接取尾部內容：
http://127.0.0.1:3080/api/plugins/qq-stack/log?n=200
日誌裏的令牌一律替換爲 ***。
適用場景與注意¶
環境要求是 Linux（aarch64 / amd64），可安裝 apt 軟件包；Android 上的 DSH 運行環境同樣適用；Node ≥ 22.5；首次安裝約需 250MB 磁盤空間與相應下載流量。插件啓動的 Linux 版 QQ 客戶端依賴 xvfb-run 與 dbus-run-session，因此不支持 Windows。
幾個容易踩的點：
- 掃碼後仍顯示未登錄，需要先在手機上確認登錄，僅掃碼不構成登錄
- 卸載或清理運行環境會刪除登錄數據，重裝後屬於全新安裝，需要重新掃碼
- 一段時間後掉線時，引擎啓動會重新拉起 QQ 並用已保存賬號快速登錄；登錄態失效則需重新掃碼
- 羣裏沒有回覆時，消息處理由接入的對話插件負責，本插件只維護 QQ 在線與協議接口
- 提示登錄失敗或賬號受限屬於 QQ 賬號側限制，需在 QQ 安全中心完成身份驗證後再嘗試登錄
另外要注意權限邊界：插件以當前 dsh 進程的權限運行，安裝前應先檢查源碼與許可證，再決定是否引入。
卸載插件不會自動刪除運行環境，刪除方式二選一：卸載前在設置頁點擊「清理運行環境」，或手動執行：
bash ~/.dsh/qq-bot/stop-qq.sh && rm -rf ~/.dsh/qq-bot
結尾¶
dsh-qq-stack 的價值在於把「裝環境、起 QQ、管登錄、暴露協議」做成一條可復現的鏈路，讓 QQ 機器人接入 DSH 時不必再手工維護 LinuxQQ 與 NapCat。目錄頁在 https://www.skillhub.cn/plugins/2008BingYu/dsh-qq-stack，源碼在 https://github.com/2008BingYu/dsh-qq-stack。該目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
