dsh-qq

让 DSH（DeepSeek Harness）里的 Agent 在 QQ 上发消息、在群里自动接话，并带一个网页管理面板。

通道是本机 NapCat（QQNT + OneBot 11 HTTP）：插件不加好友、不碰协议，只把 OneBot 的 HTTP 接口和事件推送接到 DSH 上。只依赖 Node 内置模块，没有第三方运行时依赖。

安装

dsh plugin add github:ReWebaiyu/dsh-qq

也可以在 dsh-m 市场里搜「QQ」（收录后）直接装。装完重启 DSH，工具列表里出现 qq_* 六个工具，左侧栏出现 QQ 图标。

前提：本机跑一个 NapCat

1. QQNT（QQ 官网版）+ NapCat.Shell（NapNeko/NapCatQQ）。
2. 以管理员身份运行 launcher.bat <你的QQ号>，首次扫码登录，之后可快速登录。
3. 在 NapCat 的 config/onebot11_<QQ号>.json 里打开：
   • httpServers：127.0.0.1:3000，带 token（也可以不带）；
   • httpClients：url: http://127.0.0.1:3012/event，reportSelfMessage: false。
4. 把 token、NapCat 安装路径、要接话的群号填进你的 profile patch（见下）。

配置

插件以 profile patch 的形式注入，默认值在 lib/config.js，仓库根目录的 cordis.patch.yml 是公开模板（token 留空、群号留空）。真实的 QQ 号 / 群号 / token 放进你自己的 profile cordis.patch.yml，按 id: qq 覆盖整行 config：

- id: qq
  config:
    accessToken: '你的 NapCat token'
    launcherPath: 'C:\NapCat\launcher.bat'
    loginAccount: '你的QQ号'
    groups: ['你的群号']

字段	缺省	说明
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	面板端口
napcatWebuiUrl / napcatWebuiConfig	127.0.0.1:6099 / C:\NapCat\config\webui.json	面板读 WebUI token（登录状态 / 二维码）
qrcodePath	C:\NapCat\cache\qrcode.png	扫码登录时面板直接回这张图
groups / watchUsers	[] / []	白名单；都空 = 不限制（面板里改更直观，存进 data/admin.json）
persona / aliases / chatChance / cooldownSec / …	见 lib/config.js	面板里都能改

三块东西

部分	地址	作用
工具	（Agent 直接调用）	发消息、读历史、自动接话开关
事件入口	http://127.0.0.1:3012/	收 NapCat 的 httpClients 推送
管理面板	http://127.0.0.1:3014/	人设、白名单、用量、扫码登录

工具

工具	作用
qq_status	体检：后端连通性、端口监听、登录 QQ 号与昵称、在线状态、后端版本、延迟
qq_send_private	按 QQ 号发私聊
qq_send_group	按群号发群聊，可选 atUserIds @ 人
qq_history	读好友/群最近消息、最近会话与未读数
qq_backend	查端口；提权启动 NapCat
qq_bot	自动接话：status / on / off / test

侧边框（DSH 界面内）

刷新一次页面后，左侧栏会出现 QQ 图标（sidebar.panellist + main 两个 Slot）：

• 点图标 → 中间区域就是完整面板（iframe 指向 /qq-panel/?embed=1，和网页版是同一份页面，只是去掉左侧竖栏、导航变顶部横排）。
• 面板顶部细工具栏有「刷新」和「在浏览器打开」。
• 万一同源路由被拦，5 秒没收到 ready 信号会自动退回直连 127.0.0.1:3014。

不想多挂一个侧边框：设置 →「QQ 消息」→ 关掉「在侧边栏显示 QQ 面板」。开关状态存在 data/admin.json 的 panelEnabled，刷新后仍生效。

网页面板

打开 http://127.0.0.1:3014/。

• 顶栏：QQ 头像 + 昵称 + QQ 号 + 状态点。已连接=绿点；后端在线但没登录=黄点（右侧出现「扫码登录」）；后端没起=红点（右侧出现「启动后端」）。
• 启动后端：提权拉起 NapCat，并等 OneBot 端口起来（最多 45 秒，接口返回真实结果）；起来后没登录会自动弹扫码框。
• 扫码登录：向 NapCat WebUI 要二维码（重试 4 次，NapCat 刚启动时 WebUI 可能还没就绪）；拿不到就提示去看 NapCat 控制台窗口里的二维码。
• 概览：今日回复 / 今日 Token / 监听群 / 最近决策流 / 运行状态（事件数、限流、模型、后端版本）。
• 人设：直接编辑 persona 提示词，保存即生效；「试说一句」用真实模型生成预览，不会发到群里。
• 白名单：监听群 + 监听账号两组名单（与关系：群和人都命中才处理；都空 = 全部）。
• 用量：今日调用次数、输入/输出 token、近 7 天柱状图、今日模型分布。
• 设置：闲聊接话概率、同群冷却、回复长度、每群/全局每小时上限、上下文条数、触发词。

面板只监听 127.0.0.1，配置和用量落在 data/admin.json（改完立即覆盖到运行时，不用重启）。

自动接话怎么工作

群消息 ──NapCat httpClients──▶ POST http://127.0.0.1:3012/event
                                     │
                              engine.handleEvent
                                     │  ① 白名单 + 触发判定
                     @我 / 叫到名字 / 闲聊概率 + 问题句
                                     │  ② 组 prompt（人设 + 最近 N 条上下文）
                       宿主 llm 服务（用 DSH 当前默认模型，无需额外 key）
                                     │  ③ 清洗 + 拟人延迟 + send_group_msg + 记用量
                                     ▼
                                  群里看到一句话

• 触发：被 @ 必回；文本含 aliases 或账号昵称必回；其余按概率只捡问句。
• 拟人：限长（默认 80 字）、按字数算 0.7–5 秒「打字时间」+ 抖动、同群串行。
• 限流：每群每小时 8 条、全局 30 条、同群冷却 25 秒（被点名 8 秒）。
• 额度：回复走你自己的 DSH 模型额度。

踩过的坑

• 改插件代码后要 remove_bundle + install_bundle（ESM 缓存；单纯 reinstall 会报 already-installed）。只改面板 HTML 不用重启，刷新页面即可。
• 事件监听器和面板服务都挂在 globalThis（Symbol.for('dsh-qq.host')）上整进程只建一次，面板每个请求现取 cfg/store/engine，所以热重载不会拿到旧对象、也不会占住端口。改端口要重启 DSH 才彻底生效。
• NapCat 的 httpClients 不发 Authorization，eventToken 必须留空（否则每个事件 401）。
• NapCat WebUI 认证是两步：POST /api/auth/login {hash: sha256(token+'.napcat')} → 拿 Credential，再 Authorization: Bearer <Credential>。token 在 config/webui.json。
• 关掉 NapCat 控制台窗口 = 机器人下线；面板顶栏会变红点。

License

MIT