前言¶

在 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