前言¶
在 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
