前言¶
在 DeepSeek Harness（DSH）里做智能体，常见需求之一是把对话接到即时通讯：群里 @ 一下、私聊一句，就能走同一套 Harness 能力。自建桥接往往要单独起服务、自己管协议和发信路径，和 DSH 的「一切皆插件」、in-process 挂载方式也不一致。
下面介绍社区插件 dsh-onebot-qq（维护者 YUsaltyfish，分类：客户端）。它通过 NapCat 的 OneBot v11 协议收发 QQ 消息，以 DSH 原生插件形式挂在当前进程里，Linux / Windows 通用；装好 NapCat 与插件后，在控制台填连接项即可开始聊。
这是什么¶
dsh-onebot-qq 是面向 DSH 的 QQ 机器人插件：微内核 + 可插拔子插件，纯 in-process，无独立进程或 systemd。包内通过 dsh.bundle.patch 声明、一行挂载进 Cordis。
运行依赖 Node.js >= 22、DSH >= 0.2.1-rc.2 且 < 0.3.0（见 package.json 的 engines.dsh）。QQ 侧需要 NapCat（QQNT + OneBot v11），并开启正向 WebSocket 与 HTTP API；用 QQ 号在 NapCat 登录（文档建议小号），由该账号代为收发消息。
当前 npm 包版本为 0.1.1，许可证 MIT。GitHub 仓库见 YUsaltyfish/dsh-onebot-qq；社区目录页：skillhub.cn 插件页。
核心功能¶
README 将能力归纳为以下几类（以下均来自仓库说明，未单独验证每条在群/私聊下的边界）。
DSH 集成
- 原生插件：
cordis.patch.yml随包声明，进程内挂载。 - 出站统一：文本走
deliver()，媒体走sendMedia()；自动处理[AT:]、六项脱敏、插件装饰后再发送并留档。
微内核与子插件
- 自带 13 个子插件：门禁唤醒、命令、文件、人设句池、入群欢迎、生图、链接解析、表情包、简易群记忆，以及 4 个可选项（防刷屏、私聊好友门禁、看视频、看视频链接）；目录自动发现，单个子插件异常不影响其余。
- QQ 控制台：16 个页签，配置热改（原子写、备份、回滚）；子插件与页面大致 1:1 对应。
QQ 侧与人设
- 收发图片；生图 / 图生图（
openai-images/openai-chat）；群头像、表情包自动收集、入群欢迎、群记忆注入、可选链接解析。 - 开箱人设：内置「蓝色大肥鱼」与
_模板.md，首次启动自动投递；唤醒词与人设词在控制台可增删。
跨平台
- 路径、临时目录、CQ 文件引用、原子写、人设软链降级等集中在
platform/收口，面向 Linux / Windows（package.json描述亦提到 macOS）。
可选配套：若希望 QQ 会话对全局工具（ops_*、agent-team、MCP 资源等）也做门禁，可在本插件之后安装独立插件 dsh-onebot-qq-opsgate。不装也可正常聊天，文档说明 QQ 侧工具面更大、token 消耗可能略增。看视频相关能力需另跑本地解析侧车（ffmpeg 抽帧）；不装时视频/链接按普通消息处理。
安装与启用¶
前置准备¶
| 组件 | 要求 |
|---|---|
| Node.js | >= 22 |
| DSH | >= 0.2.1-rc.2 < 0.3.0 |
| NapCat | QQNT + OneBot v11；开启正向 WebSocket 与 HTTP API |
| QQ 号 | NapCat 登录用 |
安装插件（三选一）¶
官方 README 给出的命令如下（注意 --profile web）：
# GitHub（推荐）
dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq
# 本地 tgz（npm pack 产物）
dsh plugin --profile web add /abs/path/dsh-onebot-qq-0.1.1.tgz
# 本地目录（改代码立刻生效）
dsh plugin --profile web add link:/abs/path/dsh-onebot-qq
也可在 DSH 桌面端「设置 → 插件」中填写 GitHub 仓库地址安装。
可选 ops 门禁（须在本插件之后安装）：
dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq-opsgate
连接 NapCat 并验收¶
- 在 NapCat 登录 QQ，开启 WebSocket（默认
ws://127.0.0.1:3001）与 HTTP（默认http://127.0.0.1:3000），记下 token（可为空）。 - 打开 DSH 设置 →「QQ 控制台」→「NapCat 连接」，填写地址与 token，点击「测试 NapCat 连接」。
- 在「群聊」页顶部填写主人 QQ（必填），保存后自动连接。
- 在 QQ 中 @ 机器人或私聊，有回复即表示链路可用。
首次启动若缺少 adminQq，会进入「待配置模式」：控制台与工具可用、不连 NapCat；填完主人 QQ 后自动连接。
更细的安装、升级、卸载与键位说明见仓库内 docs/使用说明书.md、docs/安装与卸载.md、docs/配置参考.md 等。
典型用法¶
控制台与人设
控制台集成在 DSH 内置设置页，多页签热改。人设可参考随包的 personas/_模板.md 让模型协助撰写；文档建议多写示范对话。
文档入口（仓库内）
| 文档 | 内容 |
|---|---|
docs/使用说明书.md |
安装 → 连接 → 功能 → 人设 |
docs/安装前准备.md |
安装前准备与验收 |
docs/排错.md |
NapCat 连不上、工具不出现、图片发不出等 |
docs/Windows安装.md |
Windows 从零到跑通 |
适用场景与注意¶
适合谁
- 已在用 DSH，希望用 NapCat + OneBot v11 把 QQ 群聊/私聊接到 Harness，且不想单独维护一套出站服务。
- 需要收消息、发图、生图、表情、入群欢迎、简易群记忆等，并希望通过控制台热改配置。
安全与权限
插件以当前 DSH 进程的权限运行，能访问该进程可访问的资源与工具。安装前请自行审阅 源码与许可证，并评估是否安装 dsh-onebot-qq-opsgate 以收窄 QQ 会话可调用的全局工具面。
隐私
README 说明：包内不含真实 QQ 号、群号、token、API Key 或服务器路径；运行数据（配置、人设、表情库、群记忆、日志）在用户本地数据目录，不进仓库与 npm 包。
说明
仓库 README 注明文档与插件内容由 AI 生成，仅供参考，使用前请自行甄别。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-onebot-qq 把 OneBot QQ 能力收进 DSH 插件形态：NapCat 连上、控制台配好主人 QQ，即可在 QQ 里与 Harness 对话；微内核与子插件负责唤醒、媒体、人设与群场景能力。若要安装或查版本细节，可看 GitHub 仓库 与 SkillHub 目录页。
