前言¶
在 DeepSeek Harness（DSH）裏做 QQ 機器人，常見做法是單獨寫橋接腳本，把羣消息整段丟給模型再原樣發回。這類方案往往缺少「該不該接話」的判斷、按羣的策略，以及和 DSH 設置頁、用量統計的一體化體驗。下面介紹社區維護者 SenuMirai 發佈的 dsh-whale-qq（npm 包名 dsh-qq-group，當前版本 1.52.0，MIT）。它是 DSH Whale 系中的 QQ 模塊，通過 OneBot 11 連接 NapCatQQ，在桌面 DSH 裏提供羣聊/私聊、人設、記憶、價值評分接話、主動搭話，以及語音、唱歌、表情包、日記和可選看圖能力；數據與桌寵工程拆分後彼此獨立。
這是什麼¶
dsh-whale-qq 歸類爲 客戶端 插件：在 DSH 設置頁注入「QQ 羣聊」配置界面，並在本機與 NapCat 建立 WebSocket。項目從更早的 whale-girl QQ 模塊拆分而來，人設、模型與記憶不與其他 Whale 倉庫強行綁定；若與 dsh-whale-world 等同系列插件一起安裝，記憶等能力可按該系設計聯動。目錄頁：SkillHub 插件頁；源碼：GitHub SenuMirai/dsh-whale-qq。
核心功能¶
連接與協議¶
- 支持 OneBot 11 / NapCat：WebSocket 連接 NapCatQQ，含自動重連、啓動檢查、可選自動拉起 NapCat。
- 部署側需要 DeepSeek Harness 桌面版（或可加載插件的主機）、Node.js 22.12+、pnpm 9+、NapCatQQ 與 QQ NT（Windows 較常見；Linux 可用 NapCat Docker，登錄與風控以 QQ 側爲準），以及一個已入羣的機器人 QQ 號。
人設、模型與羣策略¶
- 多張人設卡；可按羣綁定，一張卡可綁多羣，未綁定則跟隨全局。
- 模型 provider/model、推理檔位、備用模型可按羣單獨選擇。
- 設置頁頂部支持逐羣開關：關閉後不接該羣消息、不主動開口、不寫互動。
接話與主動搭話¶
- 價值評分 v3：@、叫名字、引用直接回復；普通消息經關鍵詞、成員、上下文、熟識度、好感度、夜間等計算 0～100 分，再結合閾值與概率決定是否調用模型。
- 冷場邏輯：任意人類消息會重置去抖與主動開口倒計時；羣內持續有人說話時默認不插話。
- 直接對話隊列：生成過程中收到的 @/引用會排隊；主動開口會給 @ 讓位。
- 獨立主動搭話頁：冷場閾值、概率、冷卻、每日上限、安靜時段、試運行、主動語音概率等。
- 羣友畫像：每羣每人獨立熟識度/好感度；主人數值全局統一且可在設置中編輯。
多媒體與日記¶
- 語音 / 唱歌：Edge、CosyVoice2、Kokoro、GPT-SoVITS 等多後端；GPT-SoVITS 支持 v2ProPlus 與七種情緒參考音；可按羣設置語音概率。
- 表情包：自動收藏、AI 打標籤、按語境選圖；自拍圖併入常用庫，可用「尾巴/自拍」等標籤。
- 視覺看圖：當前/引用圖片、轉發聊天記錄中的圖片（嵌套轉發最多展開兩層）；策略可在設置中關閉或按 @、上下文等條件觸發以控制 token。
- 日記：記錄上下文、評分理由、內心吐槽；支持篩選、導出與刪除。
省 token 與穩定性¶
- 自適應上下文長度、記憶注入條數、夜間免打擾（跨午夜；夜間不再主動開口，普通接話可扣分）。
- 按羣統計 token 用量；模型僅返回 reasoning 時可提取、重試或走備用模型。
安裝與啓用¶
README 中的安裝流程分三塊：準備 NapCat、構建插件目錄、把包鏈入 DSH profile。正文不寫 git clone；請自行將倉庫放到本機目錄後，在該目錄執行構建，再用絕對路徑註冊。
1. NapCat 與 OneBot¶
- 安裝 QQ NT 與 NapCatQQ，用機器人 QQ 登錄。
- 在 NapCat 中啓用 OneBot 11，添加 WebSocket 服務器，例如地址
ws://127.0.0.1:3001，並自行生成 access token。 - 確認控制台顯示 OneBot WebSocket 已啓動。
2. 構建插件¶
在插件源碼根目錄執行：
pnpm install
pnpm run build
3. 鏈入 DSH 並重啓¶
方式一，使用 DSH CLI（路徑替換爲本機絕對路徑）：
dsh plugin --profile desktop add <絕對路徑>
方式二，編輯 profile 的 package.json，例如：
// <DSH_HOME>/profiles/desktop/package.json
{
"dependencies": {
"dsh-qq-group": "link:/absolute/path/to/dsh-qq-group"
},
"dsh": {
"profile": {
"bundles": [
"dsh-qq-group"
]
}
}
}
重啓 DSH。設置頁出現「QQ 羣聊」即表示 bundle 已加載。
4. 連接與首次自檢¶
DSH 設置 →「QQ 羣聊」→「連接」中填寫與 NapCat 一致的項，例如：
| 項 | 示例 | 說明 |
|---|---|---|
| WebSocket 地址 | ws://127.0.0.1:3001 |
NapCat 的 OneBot WS |
| Access Token | <YOUR_TOKEN> |
與 NapCat 一致，勿提交倉庫 |
| 機器人自稱 | 助手 |
羣內被呼叫的名字，可逗號分隔 |
| 主人 QQ | <YOUR_QQ> |
主人識別與好感初值，可留空 |
| 自動連接 | 開 | DSH 啓動後自動連接 |
設置頁點「啓動」，或在羣裏 @ 機器人；首次建議運行「體檢」與「模型檢查」。
典型用法與起步參數¶
README 給出的起步值可按羣氛圍調整，不必一次調滿：
| 參數 | 推薦 | 說明 |
|---|---|---|
| 搭話模式 | 主動 | 被動僅響應 @/叫名字；主動才插話與冷場開口 |
| 評分閾值 | 55～65 | 越高越挑 |
| 接話概率 | 0.15～0.35 | 分數達標後的二次隨機 |
| 冷卻 | 20～45 秒 | 兩句最小間隔；直接對話可跳過 |
| 夜間免打擾 | 23:00–08:00，扣 20 | 更大扣分則更安靜 |
| 看圖策略 | 自定義：@ + 問看法 | 需看更多圖時再選 all |
| 語音概率 | 0.1～0.3 | 過高易刷屏並增加 TTS 延遲 |
模型方面，日常文字可選用額度充足的 Flash 類模型；需要識圖時選擇支持 text + image 的型號；羣聊推理檔位建議 low，以控制延遲與 token。換模型後用量按 provider/model 分開統計。
設置頁大致分爲：人設/模型、連接、聊天頻率（按羣）、白名單/黑名單、夜間、語音、表情包、日記。
數據存放與隱私¶
運行時數據位於 $DSH_HOME/dsh-qq-group/，例如 qq.json（連接與羣策略）、settings.json（人設與模型）、qq-memory.json（每羣記憶，上限 200 條/羣）、profiles.json（羣友畫像）、diary.json（上限 1000 條）、stickers/（本地表情包）。倉庫本身不含聊天記憶、token 或 Cookie；羣聊內容會發往你所選模型 provider，需自行評估隱私與羣規。
適用場景與注意¶
適合：已在用 DSH 桌面版、希望 QQ 羣裏有「像人」的接話節奏（評分 + 主動 + 冷卻）、並要在同一宿主裏管理人設、日記與用量的開發者或羣管理員。
注意：
- 插件以當前 DSH 進程權限運行，安裝前請閱讀源碼與 MIT 許可證，並覈對 GitHub 倉庫 與 NapCat/QQ 使用條款。
- NapCat 登錄與風控由 QQ 側決定，插件不繞過。
- 語音依賴 edge-tts 網絡與本地 ffmpeg 等可選組件；視覺能力受所選模型限制。
- SkillHub 等爲社區目錄，與 DeepSeek / 幻方無官方從屬關係；星標等元數據以目錄與倉庫當時頁面爲準。
同系可選插件包括 dsh-whale-world（跨會話記憶與世界控制台）等；社區還列出 dsh-see-now、dsh-loadout、dsh-persona-distill 等搭配項，按需加裝。
結尾¶
dsh-whale-qq 把 QQ 羣聊收成 DSH 內可配置的客戶端插件：NapCat 進、設置頁管、評分與主動邏輯出。部署路徑是構建插件 → dsh plugin --profile desktop add 或 profile link → 配好 WebSocket 與 token → 按羣調閾值與多媒體概率。進一步說明與更新日誌見 GitHub，分類與簡介見 SkillHub 目錄頁。
