前言¶
在 DSH 裏跑一個 QQ 機器人，常見做法是自己拼協議端：要麼維護一個 NapCat 的裸配置，要麼在羣裏的消息裏手動篩人、手動存上下文。dsh-qq-bot 把這條路補齊了：協議端交給 NapCat，插件自己在 DSH 裏做人設、記憶、存檔、白名單和暖場，手機上一鍵裝完就能連。
下面介紹 Tongyu3 維護的 dsh-qq-bot，它是 DSH 的 QQ 機器人插件，分類爲客戶端，基於 NapCat + OneBot v11，支持人設 / 記憶 / 存檔 / 白名單 / 暖場 / 表情包 / 擴展，可以在 Android 手機上本地一鍵部署。
這是什麼¶
dsh-qq-bot 由 Tongyu3 維護，倉庫地址 https://github.com/Tongyu3/dsh-qq-bot，目錄頁在 https://www.skillhub.cn/plugins/Tongyu3/dsh-qq-bot。它的思路是：NapCat 當協議端，走 OneBot v11（WebSocket），DSH 插件負責人設、記憶、聊天流程和設置頁。
注意倉庫名是 dsh-qq-bot，但插件內部包名與 bundle id 是 dsh-napcat——安裝腳本、插件數據路徑 ~/.dsh/dsh-napcat、路由 /dsh-napcat/api/* 都按 dsh-napcat 走，查資料和排錯時別找錯名字。
實測環境：Android 手機上的 DSH（Ubuntu 24.04 proot）+ NapCat 4.18.42 + Linux QQ 3.2.34 arm64，全程只走 127.0.0.1，不需要把機器人掛到公網。
核心功能¶
下面列出的都是 README 中寫明的能力。
- 協議：默認 NapCat → OneBot v11 正向 WS（
ws://127.0.0.1:3001/），也支持 HTTP 模式與遠程 NapCat。 - 連接：設置頁提供「一鍵啓動 NapCat」「打開 WebUI」「掃描本機」「連接這個賬號」，不用手工改 JSON。
- 人設與記憶：分人設配置、長期記憶、對話存檔，存檔可回滾。
- 白名單：只回指定 QQ 或羣，其餘消息直接丟棄。
- 主動暖場：長時間沒人說話時自動拋話題。
- 表情包：本地表情包目錄 + 自動挑選發送。
- 擴展：
examples/extensions/*.mjs熱插拔自定義命令。 - 日誌：每輪請求、回覆、錯誤都落盤，可在設置頁查看。
安裝與啓用¶
環境要求：Linux（arm64 或 amd64），Android 的 proot 容器同樣可用；Node.js ≥ 20；DSH 0.2.x，profile 目錄可用（默認 ~/.dsh/profiles/web）。一鍵安裝會額外裝 Xvfb、x11vnc、noVNC、Electron 運行庫、中文字體、NapCat.Shell 和 Linux QQ。建議能訪問 GitHub 鏡像（gh-proxy.com）與騰訊 CDN（qqdl.gtimg.cn）。
倉庫 dist/ 放的是直接可用的壓縮包，不用展開源碼。安裝命令來自 README：
tar xzf dist/dsh-napcat-0.1.0.tgz
cd package
bash install.sh
安裝器會做六件事：
- 把插件複製到
$DSH_HOME/plugin-src/dsh-napcat，並以link:裝進$DSH_HOME/profiles/web - 把
dsh-napcat寫進 profile 的dsh.profile.bundles - 裝 Xvfb / x11vnc / noVNC / Electron 運行庫 / 中文字體
- 下載並解包 NapCat.Shell
- 下載並安裝 Linux QQ 3.2.34（arm64 / amd64）
- 編譯
libnapcat_launcher.so（啓動時注入loadNapCat.js，不依賴 ptrace），並安裝登錄後自動配置 OneBot 的鉤子
環境依賴由安裝腳本自己備齊，不需要預先手工裝。裝完重啓一次 DSH。
dist/ 裏還有兩個附件：dsh-napcat-0.1.0.tgz 是插件本體；dsh-napcat-handover2.zip 是交接整包（插件 tgz + 交接文檔 + 一鍵入口），適合直接丟給智能體或另一臺設備。
連接 QQ¶
插件版本 0.1.0，許可證 MIT。連接流程按 README 分六步：
- 進入設置 → QQ 機器人
- 點「一鍵啓動 NapCat」
- 點「打開 WebUI」，用目標 QQ 掃碼或密碼登錄
- 登錄後
autoconfig-onebot.sh自動給onebot11_<QQ號>.json加上127.0.0.1:3001的 WS 服務（含 token），並帶-q <QQ號>快速重啓 NapCat - 回插件點「掃描本機」→「連接這個賬號」
- 用另一個 QQ 發條消息驗證
也可以用命令行手動確認：
/opt/napcat/start.sh # 起 Xvfb/VNC/QQ/NapCat
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/ # 426 = WS 在聽
tail -f /root/.dsh/dsh-napcat/boot.log # 插件日誌
遠程 NapCat¶
不想在手機上跑 QQ 的話，可以在設置頁「NapCat 主機」填那臺機器（電腦 / 服務器）的局域網 IP，WebUI 端口 6099、OneBot 端口 3001，點「掃描本機」或直接填 ws://<IP>:3001/ + token。
源碼結構¶
README 給了目錄地圖，排錯時按這個找：
lib/index.js 宿主半端：路由、工具、懶人連接、配置
lib/napcat.js NapCat 探測 / onebot11 解析 / 啓停
lib/onebot.js OneBot v11 客戶端（重連、心跳、API 超時）
lib/pipeline.js 人設、記憶、聊天、暖場、表情包
lib/store.js 存檔 / 記憶 / 表情包 / 擴展的數據層
lib/client.js 設置頁（React）
install.sh 一鍵安裝器
scripts/setup-napcat.sh 環境安裝（NapCat + QQ + Xvfb/noVNC）
scripts/autoconfig-onebot.sh 登錄後自動配 3001
docs/HANDOVER.md 完整交接：目錄地圖、九個坑、從零重裝、排錯、恢復
docs/SETTINGS.md 全部設置項速查
docs/EXTENSIONS.md 寫擴展
常見問題與注意事項¶
README 列了這幾個坑，值得先看：
- 裝了插件 DSH 起不來：插件頂層
inject: ['webServer']會卡在「等待服務」，必須用ctx.inject([...], scope => ...)。恢復步驟見docs/HANDOVER.md第 5 節。 - WebUI 打不開：確認 6099 在聽，
http://127.0.0.1:6099/webui/；token 在/opt/napcat/napcat/config/webui.json。 - 連上了但提示離線：NapCat 沒登錄（缺
-q <QQ號>會停在掃碼頁），此時 3001 在聽也拿不到get_login_info。 - 登錄服務 timeout：NapCat 的 msf 登錄服務掉線，重試或換網絡。
- 數據目錄：插件數據放
~/.dsh/dsh-napcat/data，不要放/sdcard（FUSE 權限會炸）。
插件以當前 DSH 進程的權限運行，安裝來自第三方倉庫的內容在啓用前應檢查源碼與許可證。插件本體 MIT；NapCat 與 Linux QQ 由各自上游提供，安裝器只從官方 / 鏡像下載，不隨包分發。更多排錯命令、恢復步驟和升級注意事項在 docs/HANDOVER.md。
結尾¶
dsh-qq-bot 的價值在於把「協議端 + 機器人行爲 + 設置界面」這三件事合成一個可一鍵安裝的塊，手機本地跑，不用公網暴露。目錄頁 https://www.skillhub.cn/plugins/Tongyu3/dsh-qq-bot，源碼 https://github.com/Tongyu3/dsh-qq-bot。
