前言¶
在 DSH（DeepSeek Harness）裏跑 Agent，常見做法是瀏覽器對話或接 API。若希望 Agent 能往 QQ 私聊、羣裏發消息，並在羣裏按規則自動接話，通常要自己接 OneBot 協議、寫事件回調和限流邏輯。下面介紹社區插件 dsh-qq（倉庫 ReWebaiyu/dsh-qq）：它只對接本機 NapCat 的 OneBot 11 HTTP 與事件推送，把收發、歷史、後端啓動和自動接話封裝成 DSH 工具，並附帶網頁管理面板與 DSH 側邊框入口。
這是什麼¶
dsh-qq 由維護者 ReWebaiyu 發佈，分類爲客戶端插件，當前 package 版本 0.1.0，許可證 MIT，運行要求 Node.js >= 22。插件不實現 QQ 協議、不加好友，通道是本機 NapCat（QQNT + OneBot 11 HTTP）；實現上只依賴 Node 內置模塊，無第三方運行時依賴。
核心功能¶
Agent 工具（六個 qq_*）¶
| 工具 | 作用 |
|---|---|
qq_status |
體檢：後端連通、端口、登錄 QQ 與暱稱、在線狀態、後端版本、延遲 |
qq_send_private |
按 QQ 號發私聊 |
qq_send_group |
按羣號發羣聊，可選 atUserIds @ 人 |
qq_history |
讀好友/羣最近消息、最近會話與未讀數 |
qq_backend |
查端口；提權啓動 NapCat |
qq_bot |
自動接話：status / on / off / test |
事件與管理面板¶
| 部分 | 地址 | 作用 |
|---|---|---|
| 事件入口 | http://127.0.0.1:3012/ |
接收 NapCat httpClients 推送 |
| 管理面板 | http://127.0.0.1:3014/ |
人設、白名單、用量、掃碼登錄等 |
面板僅監聽 127.0.0.1；配置與用量寫入 data/admin.json，改完立即生效，無需重啓 DSH。
DSH 側邊框¶
安裝並重啓 DSH 後，刷新頁面，左側欄會出現 QQ 圖標。點圖標可在 DSH 中間區域嵌入完整面板（iframe 指向 /qq-panel/?embed=1）；工具欄可刷新或在瀏覽器打開。若 5 秒內未收到 ready 信號，會退回直連 127.0.0.1:3014。可在設置 →「QQ 消息」中關閉「在側邊欄顯示 QQ 面板」，狀態保存在 data/admin.json 的 panelEnabled。
自動接話（概要）¶
羣消息經 NapCat httpClients POST 到 http://127.0.0.1:3012/event，經白名單與觸發判定（@、別名/暱稱、閒聊概率與問句等）後，用人設與最近上下文調用 DSH 當前默認模型生成回覆，再經限長、擬人延遲與限流後 send_group_msg。默認限流包括：每羣每小時 8 條、全局 30 條、同羣冷卻 25 秒（被點名 8 秒）。回覆消耗的是你本機 DSH 的模型額度。
安裝與啓用¶
官方安裝命令如下。裝完後重啓 DSH，工具列表應出現上述六個工具，側欄出現 QQ 圖標。
dsh plugin add github:ReWebaiyu/dsh-qq
也可以在 dsh-m 市場裏搜「QQ」（收錄後）直接安裝。
前提：本機 NapCat¶
- 安裝 QQNT（QQ 官網版）與 NapCat.Shell（NapNeko/NapCatQQ）。
- 以管理員身份運行
launcher.bat <你的QQ號>，首次掃碼登錄。 - 在 NapCat 的
config/onebot11_<QQ號>.json中配置：
-httpServers：127.0.0.1:3000，可帶 token；
-httpClients：url: http://127.0.0.1:3012/event，reportSelfMessage: false。 - 將 token、NapCat 安裝路徑、要接話的羣號寫入 profile patch（見下）。
Profile 配置¶
插件通過 profile patch 注入；默認值在 lib/config.js，倉庫根目錄 cordis.patch.yml 爲公開模板。真實 QQ 號、羣號、token 應放在你自己的 profile cordis.patch.yml，按 id: qq 覆蓋整段 config：
- id: qq
config:
accessToken: '你的 NapCat token'
launcherPath: 'C:\NapCat\launcher.bat'
loginAccount: '你的QQ號'
groups: ['你的羣號']
常用字段說明（缺省與 README 一致）：
| 字段 | 缺省 | 說明 |
|---|---|---|
baseUrl |
http://127.0.0.1:3000 |
OneBot HTTP 根地址 |
accessToken |
空 | 與 NapCat onebot11_<uin>.json 的 token 一致 |
launcherPath / loginAccount |
C:\NapCat\launcher.bat / 空 |
qq_backend start 與面板「啓動後端」 |
eventPort |
3012 |
事件端口；改後需同步 NapCat httpClients 並重啓 NapCat |
eventToken |
空 | 必須空：NapCat 的 httpClients 不發 Authorization |
adminPort |
3014 |
面板端口 |
groups / watchUsers |
[] / [] |
白名單；都空表示不限制（面板可改，存 data/admin.json） |
persona、aliases、chatChance、cooldownSec 等詳見 lib/config.js，面板中均可調整。
典型用法¶
1. 安裝插件並配 NapCat¶
按上一節完成 dsh plugin add、NapCat OneBot 配置與 profile patch，重啓 DSH 與 NapCat（按需）。
2. 用 Agent 發消息與查狀態¶
在 DSH 對話中讓 Agent 調用工具，例如：
qq_status：確認 OneBot 端口與登錄狀態；qq_send_group：向指定羣發送內容；qq_history：拉取最近會話或羣消息供上下文使用。
3. 網頁或側欄管理自動接話¶
瀏覽器打開 http://127.0.0.1:3014/，或在 DSH 側欄 QQ 面板中操作：
- 頂欄紅/黃/綠點表示後端與登錄狀態；可「啓動後端」「掃碼登錄」；
- 「人設」編輯 persona；「白名單」配置監聽羣與賬號；「設置」調整接話概率、冷卻、觸發詞等；
- Agent 側用
qq_bot的 on / off / status / test 控制或探測自動接話。
4. 事件鏈路覈對¶
NapCat 應向 http://127.0.0.1:3012/event 推送羣消息；若事件 401，檢查 eventToken 必須留空（NapCat httpClients 不帶 Authorization）。
適用場景與注意¶
適合：已在本機使用 DSH、願意自建 NapCat 的開發者，希望 Agent 直接操作 QQ 收發與羣聊接話，並用人設與白名單在面板裏調參，而不從零寫 OneBot 橋接。
注意：
- 插件以當前 DSH 進程權限運行；安裝前請自行審閱 GitHub 源碼 與 MIT 許可證。
- 關閉 NapCat 控制台窗口會導致機器人下線，面板頂欄會顯示紅點。
- 改插件代碼後文檔建議
remove_bundle+install_bundle（ESM 緩存）；改監聽端口需重啓 DSH。 - DSH 生態是「一切皆插件」；社區目錄頁 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-qq 把 NapCat OneBot 11 的 HTTP 與事件接到 DSH：六個 qq_* 工具供 Agent 發消息、讀歷史、管後端與自動接話，127.0.0.1:3014 面板與 DSH 側欄負責運維與策略配置。若你已在用 DSH 並本機跑 NapCat，可按 README 完成安裝與 profile 配置後試用。
- 目錄頁：https://www.skillhub.cn/plugins/ReWebaiyu/dsh-qq
- 倉庫：https://github.com/ReWebaiyu/dsh-qq
