前言¶
在 DSH 里做智能体时，常见做法是自己接 OneBot 协议、再写一堆工具让助手查群、发消息、读媒体。协议地址、Token、群白名单和视觉开关往往散落在配置文件或脚本里，运维和试聊也要换好几个界面。下面介绍社区插件 dsh-qq（维护者 oka-rin，分类为客户端）：它把 QQ 对话、媒体理解、DSH 内操作 QQ，以及在线状态与配置面板收进一个插件，并支持 NapCat、SnowLuma 与通用 OneBot 后端接入。
这是什么¶
dsh-qq 是面向 DeepSeek Harness 的 QQ 机器人集成插件。源码在 GitHub：oka-rin/dsh-qq，社区目录页为 skillhub.cn/plugins/oka-rin/dsh-qq。插件描述为： bundled bot、NapCat/SnowLuma/OneBot 连接、控制面板与 QQ 相关工具；网关后端由外部自行部署，插件不捆绑镜像、不隐式安装后端。
运行环境要求 DSH 与 Node.js 22.13 或更新版本（见 package.json 中 engines.node）。当前资料中的版本号为 0.8.0，许可证为 MIT。
核心功能¶
README 中的能力表与说明可核对如下要点。
QQ 对话：群内 @ 机器人、引用其消息，或私聊；新安装默认不开口，需在配置中开启聊天，并按需开启私聊与群范围（群白名单留空表示不限制群）。
图片、动图、视频：发给机器人让其理解内容；可展开合并转发里的聊天和媒体。图片需要支持视觉的模型；动图与视频还需要主机上的 ffmpeg / ffprobe；相关开关新安装默认关闭。
在 DSH 里操作 QQ：通过自然语言让助手发消息、查群成员、找历史聊天、查看人物档案等（README 称插件内提供多类工具，具体以安装后助手可用能力为准）。
统一面板：在 DSH 设置 → QQ 机器人 查看在线状态、会话和日志，修改配置，开关自动聊天；支持打开 QQ 登录页人工登录（SnowLuma Docker 的 noVNC、NapCat WebUI 等流程见官方文档）。
按需扩展：表情包、生图、学习、资讯分享、QQ 空间与群管理等；部分扩展取决于后端权限和外部服务。
后端与部署：可填写已有 OneBot HTTP / WebSocket 与 Token；无后端时可在 接入与部署 使用 一键部署 SnowLuma（Linux / Windows 宿主，依赖 Docker 等条件见 docker 文档）。NapCat 接入见 napcat.md。高级项见 advanced.md。
安装与启用¶
1、准备环境¶
- 已安装并运行 DSH，Node.js ≥ 22.13。
- 准备 NapCat / SnowLuma / OneBot 后端的 HTTP 地址、正向 WebSocket 地址和 Token（或安装后按向导一键部署 SnowLuma）。
- 准备 OpenAI 兼容 的模型接口地址、模型名与 API Key。
2、安装插件¶
安装来源为该 GitHub 仓库，不是 npm 上的同名包。在 DSH 对话里把下面这句话发给助手即可：
帮我从 https://github.com/oka-rin/dsh-qq 安装这个插件。
也可下载源码，在 DSH 插件管理器中用本地目录安装。
3、连接 QQ 与模型¶
打开 DSH 设置 → QQ 机器人 → 接入与部署。若使用一键部署，需按 SnowLuma 原版流程在网页登录 QQ、审阅条款并配置网关 hook，再检测连接；新建部署仅保存本机 OneBot 接入信息，不代表已在线。
已有后端可直接填写（端口以你的后端为准）：
| 填什么 | 示例 |
|---|---|
| OneBot HTTP 地址 | http://127.0.0.1:3000 |
| OneBot WebSocket 地址 | ws://127.0.0.1:3001/event |
| OneBot Token | 后端设置的令牌，不是 QQ 密码 |
| 模型接口 / 模型名 / API Key | 模型服务提供的内容 |
点击 检测 OneBot 连接，成功后保存，再到「运维」重启机器人。连接检查通过只代表 QQ 侧可达，模型是否可用需试聊确认。
NapCat 未登录时，可在插件配置选择 gatewayBackend: napcat，按 README 复制登录令牌并在官方 WebUI 扫码；不要将令牌或密码发到聊天。
4、开启聊天并试一条¶
在配置中开启聊天；群聊需填写允许的群后再启用。在 QQ 私聊或在允许群里 @ 机器人发「你好」。收到回复后，再按需打开视觉、动图、视频与转发展开开关并试发对应消息。
典型用法¶
装好后在 DSH 对话里直接用自然语言即可，无需记忆工具名。README 给出的示例包括：
- 「看看 QQ 机器人在线没有。」
- 「列出机器人加入的群。」
- 「看看这个群最近在聊什么。」
- 「查一下之前聊过的视频。」
- 「给这个群发一条消息：今晚八点开始。」（需指定目标群）
- 「为什么机器人刚才没回复？」
适用场景与注意¶
适合谁：已在用或计划用 DSH 做助手，并希望 QQ 作为客户端通道，同时在 DSH 内完成接入检测、运维与部分群管/档案操作的用户。
连接通过但不回复：检查聊天开关、私聊开关与群范围；连接成功不会自动开启发言。
已有 Docker 版 SnowLuma：可继续连接原实例；迁移到原生需按文档备份与人工扫码，安装脚本不会停止容器或复制登录态。
数据与更新：配置、聊天归档与学习数据在独立 dataDir，不在插件代码目录；更新前备份并沿用同一 dataDir，避免另开实例导致记录割裂。
安全与权限：插件以当前 DSH 进程权限运行；安装前应阅读源码与 MIT 许可证，并理解 OneBot Token、VNC 密码与 API Key 的保管方式。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；NapCat、SnowLuma、QQ 与模型服务各遵循其自身条款。
结尾¶
dsh-qq 把 QQ 聊天、媒体理解、助手侧 QQ 工具与设置面板集中在 DSH 插件内，并对接 NapCat、SnowLuma 与 OneBot。按 README 安装、接好后端、开启聊天即可在 QQ 与 DSH 两侧联调。
- 目录页：https://www.skillhub.cn/plugins/oka-rin/dsh-qq
- 源码与文档：https://github.com/oka-rin/dsh-qq
