前言¶
在 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 目录页。
