前言¶

在 DSH 裏接 QQ 羣機器人，常見做法是依賴 @tencent-connect/dsh-qqbot，並在 qqbot 側打開「羣聊僅回覆 @ 機器人的消息」（requireMention: true）。這樣羣噪音少，但羣友不 @ 就喚不醒，叫醒之後若每條都要 @，對話也不自然。若關掉該開關，羣裏幾乎每句話都會進 agent，成本和打擾都上去。

下面介紹社區插件 dsh-qqbot-guard（維護者 anwesc，分類：工作流）。它在進程內給 qqbot 打補丁，不改 qqbot 與 SDK 文件；配合 qqbot 的 @ 門控，實現關鍵詞當 @ 用、續聊窗口、批量合併回覆、刷屏保護與羣歷史附件摘要，並在 DSH 設置 → QQ 守護 裏可視化配置，保存即生效。

這是什麼¶

dsh-qqbot-guard 是 qqbot 的增強層，不是另一個機器人。README 明確：@tencent-connect/dsh-qqbot 仍需單獨安裝；本插件只在進程內補丁，不修改 qqbot 與 SDK 的任何文件。

當前 package 版本爲 1.3.1（MIT 許可證）。插件在 dsh-plugin.org 與 SkillHub 目錄頁 可查；源碼與說明見 GitHub：anwesc/dsh-qqbot-guard。

核心功能¶

README 用場景表概括了能力，要點如下。

關鍵詞喚醒：羣友不 @，正文包含配置的關鍵詞（默認「大肥魚」「肥魚」「魚魚」）時，插件給消息補上 mentions.is_you，qqbot 門控放行，效果與真 @ 相近，且不在正文裏殘留 <@機器人>。

續聊窗口：叫醒後，在窗口內（默認 10 分鐘無相關話題則休眠）不必每條 @；每條先走快通道（真實 @、引用機器人、關鍵詞），否則用小模型判斷「是否還在同一話題」。相關則放行並續期，無關則靜默，羣裏看不到拒答痕跡。

批量與回覆形態（1.2.0 起，1.3.0 起判定同時給出合併/逐條）：安靜約 1.2 秒結算一批（從第一條起最多等 4 秒）；能一條講完則合成一條回覆，講不完或拿不準則逐條回。合併回覆默認不帶引用框；逐條回覆可用 followUpQuoteReply 帶引用，平臺不接受時自動退回普通發送。

刷屏保護：默認 10 秒內超過 15 條進入冷卻，只回復判定挑中的相關消息編號，其餘安靜。

附和與表情：「哈哈哈」「收到」等默認走場景內處理——續期並只發一張內置表情（可關或改 followUpAckMode）；內置 9 張鯨魚娘圖，僅限個人非商業；也可指向自定義 png/jpg/gif/webp 目錄。

羣歷史：消息含圖片/語音/文件時，歷史可帶 [圖片「a.png」@路徑] 等摘要；可開表情轉文字、預下載附件，便於模型接着聊。

判定與糾錯（1.3.1）：窗口內被忽略的消息也進上下文並標 [已忽略]；開窗可生成「當前話題」錨點；設置頁「判定記錄」展示最近 10 次判定，可一鍵糾正，糾正樣本會帶入下次判定（最多 5 條 followUpJudgeExamples）。

判定模型默認跟隨該羣會話實際使用的模型（羣內 /model > settings.yaml 的 agent-default-model > 宿主默認 > 兜底 deepseek-official/deepseek-v4-flash）；設置頁可單獨填 followUpJudgeProvider / followUpJudgeModel，兩項都填才覆蓋。

安裝與啓用¶

安裝前請理解：插件以當前 DSH 進程權限運行，安裝前應自行查看源碼與 MIT 許可證，並確認 peer 依賴 @tencent-connect/dsh-qqbot（README 要求 >=0.5.3，optional peer）。

兩個前提，缺一不可（缺了關鍵詞或續聊會異常）：

1. QQ 羣機器人設置裏，「機器人可獲取的羣聊消息範圍」選 獲取羣內全部消息；否則不 @ 的消息不會推給機器人。
2. DSH 的 qqbot 插件設置裏打開 羣聊僅回覆 @ 機器人的消息（requireMention: true）。界面提示「開啓後，機器人僅可回覆 @ 機器人的羣聊消息」——正是本插件要在合規前提下繞過的門控；插件通過補 mention 與續聊判定配合該開關。

步驟：

1. 在插件市場安裝 qqbot：搜 @tencent-connect/dsh-qqbot。
2. 安裝本插件：市場搜 dsh-qqbot-guard，或執行：

dsh plugin --profile web add dsh-qqbot-guard

3. 打開 DSH 設置 → QQ 守護，確認狀態行：補丁是否掛上、活動窗口數、qqbot 路徑、配置文件路徑；有 reason 時按提示排查 SDK 白名單（默認 >=1.0.5 <2.0.0，strictVersion: false 時超範圍仍可能嘗試安裝）。
4. 保存配置寫入 $DSH_HOME/qqbot-guard.json（原子寫）；App 環境常見路徑爲 /root/.dsh/qqbot-guard.json，首次啓動會自動生成。也可設 $DSH_QQBOT_GUARD_CONFIG 或手改 JSON；profile 裏可用 cordis.patch.yml 的 qqbot-guard 段覆蓋（新增插件行需 - insert:）。

典型用法¶

30 秒上手（來自 README）：

1. 裝好 qqbot 與本插件。
2. 在羣裏發一句 大肥魚（或 肥魚 / 魚魚，可在設置頁改 triggers）。
3. 機器人回覆後，不用再 @，直接接着聊；默認 10 分鐘沒有相關話題會自動休眠。

排查「叫了醒但不 @ 不回」（順序參考 FAQ）：

• 是否超過 followUpWindowMinutes（默認 10 分鐘）。
• 是否被判爲無關（跑題、純表情、純附件等可能不回）。
• 讀接口狀態：GET /qqbot-guard/config 中的 status.followUpJudge（calls、errors、lastError）與 status.followUpSticker（表情跳過原因等）。
• 判定失敗默認 followUpOnJudgeError = skip 不回；若希望失敗也回，可在設置頁改爲 reply（模型異常時可能吸進無關話題）。

重啓 DSH：續聊窗口只在內存裏，重啓後需重新發關鍵詞或 @ 一次；qqbot 磁盤上的會話歷史仍在。

進階：想用社區「大肥魚」GIF 包可參照 README 指向 diwer/ai-biaoqingbao（CC BY-NC-SA 4.0、非商業），下載輕量包後將 followUpStickerDir 指到解壓目錄並保留 NOTICE.txt 署名；程序不區分來源，目錄內 png/jpg/gif/webp 均可隨機挑選。

設置頁與主要配置¶

設置頁爲 9 張可摺疊卡片（默認展開「喚醒與開關」「續聊窗口」），標題下有一行當前值摘要；粘底保存欄在有改動時纔可保存，保存後下一條消息即按新配置走。

常用字段默認值見 README「配置項」表，例如：enabled true、triggers 含「大肥魚」等、followUpWindowMinutes 10、followUpBurstMs 1200、followUpFloodWindowMs 10000、followUpFloodMax 15、followUpQuoteReply true。完整列表以倉庫 README 爲準。

適用場景與注意¶

適合誰：已在 DSH 跑 qqbot、希望羣聊「像正常羣聊一樣」——關鍵詞叫醒、短時續聊、刷屏時不逐條燒 token、歷史裏能看見附件摘要——又願意保留 qqbot「僅 @ 回覆」門控的運維者。

成本與噪音：README 說明，只有進入續聊窗口且未走快通道的消息才做一次判定（量級爲數十 token）；短附和默認不調模型；刷屏保護把大批量壓成一次挑編號。

安全與合規：插件補丁 qqbot 行爲，配置與日誌路徑在設置頁狀態行可見；不要使用未審閱的第三方插件處理敏感羣聊。表情資源注意許可證（內置鯨魚娘僅限個人非商業；外鏈表情包需自備合規拷貝）。

結尾¶

dsh-qqbot-guard 把 QQ 羣機器人從「要麼全 @、要麼全響」折成可配置的喚醒 + 續聊 + 批量與刷屏策略，並配上設置頁與判定糾錯，適合作爲 qqbot 之上的工作流增強層。

• 目錄頁：https://www.skillhub.cn/plugins/anwesc/dsh-qqbot-guard
• GitHub：https://github.com/anwesc/dsh-qqbot-guard