前言¶
在 DSH 裏做智能體，常見做法是接 Webhook、企業 IM 或自建 Bot 賬號。QQ 側若要用「真人號」說話、又要私聊可控、羣裏少刷屏，往往得自己搭 NapCat、寫 OneBot 消費邏輯，再把模型調用和風控拆成好幾塊。dsh-qq-bridge 是社區維護者 zxz-feng 提交的 DSH 客戶端類插件（當前 GitHub 星標爲 0），把 NapCat 提供的 OneBot v11 WebSocket 接到 DSH 工具鏈上：私聊按白名單回、羣聊用零 token 規則決策器決定是否開口，需要說話時才調模型，並帶點歌、表情包、資源檢索縮略圖等能力；自檢與週期自愈同樣不消耗 token。
下面按「是什麼 → 能做什麼 → 怎麼裝配 → 怎麼用 → 注意點」說明，事實以倉庫 README 與 package.json（版本 0.9.0，MIT，要求 dsh >= 0.2.0、node >= 22）爲準。
這是什麼¶
插件全名 dsh-qq-bridge，一句話定位：接管一個真實 QQ 號（NapCat 掃碼登錄後走 OneBot v11），不是單獨再註冊一個「機器人小號協議」。NapCat 不在插件內，插件只連 OneBot WS（默認 ws://127.0.0.1:3001，可改），因此換機器只要 NapCat 和配置還在即可。
三條設計取向（README 原文歸納）：
- 說話的是登錄的那個 QQ 號本身。
- 羣聊重點在「什麼時候閉嘴」：決策器用規則打分加概率，零 token、微秒級；確定要回才調 LLM。
- 裝完默認
enabled: true，但白名單爲空時不回覆任何人，避免誤觸羣聊。
核心功能¶
私聊與羣聊¶
- 私聊：通過
qq_allowlist配置self與friends白名單；未列入的好友不會觸發回覆。 - 羣聊：在
qq_allowlist的group.groups裏按羣號啓用；未配置的羣默認忽略。dryRun: true時只生成不發送，README 建議先演練一天。
羣決策與風格¶
羣策略字段寫在 group-allowlist.json 思路下（經 qq_allowlist / Web 設置頁修改），包括 replyProb、coldProb、每日上限、冷卻、quietHours、點歌與語音上限等；風格檔在 persona/styles/*.md，自帶 normal / sunbar / tsundere / cold / genki，切檔會同時改決策偏置（bias:）。主人可在羣裏用 #風格 指令或 qq_style 工具切換。
點歌、表情包與找資源¶
- 點歌 / B 站相關依賴可選 Python（含
yt-dlp登錄態）、系統ffmpeg；缺依賴時對應功能自行關閉，其餘照常。 - 表情包需自行導入（
node scripts/import-stickers.mjs --from <目錄>）；庫空則不發圖。 - 羣內「幫我找個 X（含黃油/galgame/壁紙等關鍵詞）」可走 DLsite 搜索 → 封面縮略圖 → 標題與鏈接回覆；只發店鋪公開封面，不搬運本體；直連失敗可走
GOODS_PROXY（默認http://127.0.0.1:17890）。
聯網搜索（四源併發）¶
羣裏問「XX 是什麼意思」類問題時，橋子進程併發：宿主 DSH 搜索（需搜索插件與 key，經 127.0.0.1 小門 HOST_API_URL / HOST_API_TOKEN）、DDG lite、B 站（tools/bili.py）、維基。無搜索插件時宿主源靜默跳過，其餘源仍可用。
DSH 工具與 Web 設置頁¶
宿主側註冊多組工具，例如 qq_status、qq_verify（自檢 6/6）、qq_config、qq_allowlist、qq_send_private / qq_send_group、qq_groups、qq_qr、qq_style、qq_stickers、qq_restart / qq_log 等。Web GUI：設置 → QQ 小鯨魚（與「刷 B 站」並列），可改連接、羣策略、風格、白名單並保存即時生效（下一條羣消息起生效，無需重啓 DSH）。
自檢自愈（零 token）¶
node scripts/verify.mjs [--fix] 檢查進程、OneBot、端口、白名單、家目錄；插件默認每 5 分鐘跑一遍（selfHeal.everyMin，0 爲關閉），僅修復時寫日誌。
安裝與啓用¶
前置：NapCat¶
先在 NapCat（Docker 如 mlikiowa/napcat-docker 映射 3001/6099，或 Windows 桌面版）掃碼登錄，並開啓 OneBot v11 WebSocket 服務器（端口 3001）。可用 HTTP 探測或裝插件後看 qq_verify 的依賴項：
curl -s -X POST http://127.0.0.1:3001/get_login_info
安裝插件¶
安裝命令須來自倉庫 README，不要用未在文檔出現的拼接形式：
dsh plugin --profile web add link:/絕對/路徑/dsh-qq-bridge
# 或：dsh plugin --profile web add github:<你的用戶名>/dsh-qq-bridge
裝完重啓一次 dsh。若遇 ERR_PNPM_IGNORED_BUILDS（pnpm 12），可加：
dsh plugin --profile web add <本倉庫地址> --config.strict-dep-builds=false
配置三步¶
- 私聊白名單（
qq_allowlist，示例字段見 README）：
qq_allowlist { "allow": { "self": "10001000",
"friends": { "20002000": { "label": "主人", "enabled": true } } } }
- 羣（不加則全忽略；建議先
dryRun: true）：
qq_allowlist { "group": { "groups": { "123456789": { "label": "主羣", "dryRun": false } } } }
- 自檢：
qq_verify → 6/6
OneBot 與模型鏈示例：
qq_config { "onebot": { "url": "ws://127.0.0.1:3001", "token": "" } }
qq_config { "llm": { "models": ["deepseek-v4.1-flash", "hy3"] } }
典型用法¶
| 場景 | 做法 |
|---|---|
| 看連接與白名單狀態 | 調用 qq_status 或 Web「現在什麼狀態」面板 |
| 演練羣發言 | 羣卡設 dryRun: true，觀察生成內容再改 false |
| 手動發一條 | qq_send_private / qq_send_group（羣可配合 dryRun） |
| 切羣性格 | 羣裏 #風格 傲嬌 或 qq_style { gid, style: "tsundere", intensity: "mid" } |
| 離線自檢 | node scripts/verify.mjs 或 Web「運維 → 跑自檢」 |
README 還說明：設置頁 HTTP 只綁 127.0.0.1 且做同源檢查；token 展示打碼，存回不會把打碼串寫入文件。
適用場景與注意¶
適合誰：已在用 DSH（--profile web）、願意自建 NapCat、需要真人 QQ 號在可控白名單與羣策略下接 LLM 的開發者或小範圍社羣；希望羣聊「少說話、說對話」而不是每條消息都進模型的人。
務必知曉：
- 插件以當前 dsh 進程權限運行；安裝前請自行閱讀 GitHub 源碼 與 MIT 許可證，確認配置與網絡行爲可接受。
- NapCat 掉線需人工掃碼，插件只能報告 OneBot 不通。
- 社區目錄 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係；DSH 生態是「一切皆插件」，本文介紹的是第三方插件，不是官方應用商店條目。
- 已知限制還包括：踢人未實現；語料與風格文件有政治內容過濾底線（見 README「語料」一節）。
結尾¶
dsh-qq-bridge 把 OneBot 橋、羣聊零 token 決策、LLM 回覆與 DSH 工具/Web 設置頁收在一個插件裏，默認空白名單避免誤發。若要進一步瞭解參數與目錄結構，直接讀倉庫 README；安裝與更新以 SkillHub 目錄頁與 GitHub 發佈爲準。
- 目錄頁：https://www.skillhub.cn/plugins/zxz-feng/dsh-qq-bridge
- 源碼：https://github.com/zxz-feng/dsh-qq-bridge
