前言¶
在 DSH（DeepSeek Harness）里跑 Agent，常见做法是浏览器对话或接 API。若希望 Agent 能往 QQ 私聊、群里发消息，并在群里按规则自动接话，通常要自己接 OneBot 协议、写事件回调和限流逻辑。下面介绍社区插件 dsh-qq（仓库 ReWebaiyu/dsh-qq）：它只对接本机 NapCat 的 OneBot 11 HTTP 与事件推送，把收发、历史、后端启动和自动接话封装成 DSH 工具，并附带网页管理面板与 DSH 侧边框入口。
这是什么¶
dsh-qq 由维护者 ReWebaiyu 发布，分类为客户端插件，当前 package 版本 0.1.0，许可证 MIT，运行要求 Node.js >= 22。插件不实现 QQ 协议、不加好友，通道是本机 NapCat（QQNT + OneBot 11 HTTP）；实现上只依赖 Node 内置模块，无第三方运行时依赖。
核心功能¶
Agent 工具（六个 qq_*）¶
| 工具 | 作用 |
|---|---|
qq_status |
体检：后端连通、端口、登录 QQ 与昵称、在线状态、后端版本、延迟 |
qq_send_private |
按 QQ 号发私聊 |
qq_send_group |
按群号发群聊，可选 atUserIds @ 人 |
qq_history |
读好友/群最近消息、最近会话与未读数 |
qq_backend |
查端口；提权启动 NapCat |
qq_bot |
自动接话：status / on / off / test |
事件与管理面板¶
| 部分 | 地址 | 作用 |
|---|---|---|
| 事件入口 | http://127.0.0.1:3012/ |
接收 NapCat httpClients 推送 |
| 管理面板 | http://127.0.0.1:3014/ |
人设、白名单、用量、扫码登录等 |
面板仅监听 127.0.0.1；配置与用量写入 data/admin.json，改完立即生效，无需重启 DSH。
DSH 侧边框¶
安装并重启 DSH 后，刷新页面，左侧栏会出现 QQ 图标。点图标可在 DSH 中间区域嵌入完整面板（iframe 指向 /qq-panel/?embed=1）；工具栏可刷新或在浏览器打开。若 5 秒内未收到 ready 信号，会退回直连 127.0.0.1:3014。可在设置 →「QQ 消息」中关闭「在侧边栏显示 QQ 面板」，状态保存在 data/admin.json 的 panelEnabled。
自动接话（概要）¶
群消息经 NapCat httpClients POST 到 http://127.0.0.1:3012/event，经白名单与触发判定（@、别名/昵称、闲聊概率与问句等）后，用人设与最近上下文调用 DSH 当前默认模型生成回复，再经限长、拟人延迟与限流后 send_group_msg。默认限流包括：每群每小时 8 条、全局 30 条、同群冷却 25 秒（被点名 8 秒）。回复消耗的是你本机 DSH 的模型额度。
安装与启用¶
官方安装命令如下。装完后重启 DSH，工具列表应出现上述六个工具，侧栏出现 QQ 图标。
dsh plugin add github:ReWebaiyu/dsh-qq
也可以在 dsh-m 市场里搜「QQ」（收录后）直接安装。
前提：本机 NapCat¶
- 安装 QQNT（QQ 官网版）与 NapCat.Shell（NapNeko/NapCatQQ）。
- 以管理员身份运行
launcher.bat <你的QQ号>，首次扫码登录。 - 在 NapCat 的
config/onebot11_<QQ号>.json中配置：
-httpServers：127.0.0.1:3000，可带 token；
-httpClients：url: http://127.0.0.1:3012/event，reportSelfMessage: false。 - 将 token、NapCat 安装路径、要接话的群号写入 profile patch（见下）。
Profile 配置¶
插件通过 profile patch 注入；默认值在 lib/config.js，仓库根目录 cordis.patch.yml 为公开模板。真实 QQ 号、群号、token 应放在你自己的 profile cordis.patch.yml，按 id: qq 覆盖整段 config：
- id: qq
config:
accessToken: '你的 NapCat token'
launcherPath: 'C:\NapCat\launcher.bat'
loginAccount: '你的QQ号'
groups: ['你的群号']
常用字段说明（缺省与 README 一致）：
| 字段 | 缺省 | 说明 |
|---|---|---|
baseUrl |
http://127.0.0.1:3000 |
OneBot HTTP 根地址 |
accessToken |
空 | 与 NapCat onebot11_<uin>.json 的 token 一致 |
launcherPath / loginAccount |
C:\NapCat\launcher.bat / 空 |
qq_backend start 与面板「启动后端」 |
eventPort |
3012 |
事件端口；改后需同步 NapCat httpClients 并重启 NapCat |
eventToken |
空 | 必须空：NapCat 的 httpClients 不发 Authorization |
adminPort |
3014 |
面板端口 |
groups / watchUsers |
[] / [] |
白名单；都空表示不限制（面板可改，存 data/admin.json） |
persona、aliases、chatChance、cooldownSec 等详见 lib/config.js，面板中均可调整。
典型用法¶
1. 安装插件并配 NapCat¶
按上一节完成 dsh plugin add、NapCat OneBot 配置与 profile patch，重启 DSH 与 NapCat（按需）。
2. 用 Agent 发消息与查状态¶
在 DSH 对话中让 Agent 调用工具，例如：
qq_status：确认 OneBot 端口与登录状态；qq_send_group：向指定群发送内容；qq_history：拉取最近会话或群消息供上下文使用。
3. 网页或侧栏管理自动接话¶
浏览器打开 http://127.0.0.1:3014/，或在 DSH 侧栏 QQ 面板中操作：
- 顶栏红/黄/绿点表示后端与登录状态；可「启动后端」「扫码登录」；
- 「人设」编辑 persona；「白名单」配置监听群与账号；「设置」调整接话概率、冷却、触发词等；
- Agent 侧用
qq_bot的 on / off / status / test 控制或探测自动接话。
4. 事件链路核对¶
NapCat 应向 http://127.0.0.1:3012/event 推送群消息；若事件 401，检查 eventToken 必须留空（NapCat httpClients 不带 Authorization）。
适用场景与注意¶
适合：已在本机使用 DSH、愿意自建 NapCat 的开发者，希望 Agent 直接操作 QQ 收发与群聊接话，并用人设与白名单在面板里调参，而不从零写 OneBot 桥接。
注意：
- 插件以当前 DSH 进程权限运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证。
- 关闭 NapCat 控制台窗口会导致机器人下线，面板顶栏会显示红点。
- 改插件代码后文档建议
remove_bundle+install_bundle（ESM 缓存）；改监听端口需重启 DSH。 - DSH 生态是「一切皆插件」；社区目录页 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-qq 把 NapCat OneBot 11 的 HTTP 与事件接到 DSH：六个 qq_* 工具供 Agent 发消息、读历史、管后端与自动接话，127.0.0.1:3014 面板与 DSH 侧栏负责运维与策略配置。若你已在用 DSH 并本机跑 NapCat，可按 README 完成安装与 profile 配置后试用。
- 目录页：https://www.skillhub.cn/plugins/ReWebaiyu/dsh-qq
- 仓库：https://github.com/ReWebaiyu/dsh-qq
