前言¶
在 DSH 里跑一个 QQ 机器人，常见做法是自己拼协议端：要么维护一个 NapCat 的裸配置，要么在群里的消息里手动筛人、手动存上下文。dsh-qq-bot 把这条路补齐了：协议端交给 NapCat，插件自己在 DSH 里做人设、记忆、存档、白名单和暖场，手机上一键装完就能连。
下面介绍 Tongyu3 维护的 dsh-qq-bot，它是 DSH 的 QQ 机器人插件，分类为客户端，基于 NapCat + OneBot v11，支持人设 / 记忆 / 存档 / 白名单 / 暖场 / 表情包 / 扩展，可以在 Android 手机上本地一键部署。
这是什么¶
dsh-qq-bot 由 Tongyu3 维护，仓库地址 https://github.com/Tongyu3/dsh-qq-bot，目录页在 https://www.skillhub.cn/plugins/Tongyu3/dsh-qq-bot。它的思路是：NapCat 当协议端，走 OneBot v11（WebSocket），DSH 插件负责人设、记忆、聊天流程和设置页。
注意仓库名是 dsh-qq-bot，但插件内部包名与 bundle id 是 dsh-napcat——安装脚本、插件数据路径 ~/.dsh/dsh-napcat、路由 /dsh-napcat/api/* 都按 dsh-napcat 走，查资料和排错时别找错名字。
实测环境：Android 手机上的 DSH（Ubuntu 24.04 proot）+ NapCat 4.18.42 + Linux QQ 3.2.34 arm64，全程只走 127.0.0.1，不需要把机器人挂到公网。
核心功能¶
下面列出的都是 README 中写明的能力。
- 协议：默认 NapCat → OneBot v11 正向 WS（
ws://127.0.0.1:3001/），也支持 HTTP 模式与远程 NapCat。 - 连接：设置页提供「一键启动 NapCat」「打开 WebUI」「扫描本机」「连接这个账号」，不用手工改 JSON。
- 人设与记忆：分人设配置、长期记忆、对话存档，存档可回滚。
- 白名单：只回指定 QQ 或群，其余消息直接丢弃。
- 主动暖场：长时间没人说话时自动抛话题。
- 表情包：本地表情包目录 + 自动挑选发送。
- 扩展：
examples/extensions/*.mjs热插拔自定义命令。 - 日志：每轮请求、回复、错误都落盘，可在设置页查看。
安装与启用¶
环境要求：Linux（arm64 或 amd64），Android 的 proot 容器同样可用；Node.js ≥ 20；DSH 0.2.x，profile 目录可用（默认 ~/.dsh/profiles/web）。一键安装会额外装 Xvfb、x11vnc、noVNC、Electron 运行库、中文字体、NapCat.Shell 和 Linux QQ。建议能访问 GitHub 镜像（gh-proxy.com）与腾讯 CDN（qqdl.gtimg.cn）。
仓库 dist/ 放的是直接可用的压缩包，不用展开源码。安装命令来自 README：
tar xzf dist/dsh-napcat-0.1.0.tgz
cd package
bash install.sh
安装器会做六件事：
- 把插件复制到
$DSH_HOME/plugin-src/dsh-napcat，并以link:装进$DSH_HOME/profiles/web - 把
dsh-napcat写进 profile 的dsh.profile.bundles - 装 Xvfb / x11vnc / noVNC / Electron 运行库 / 中文字体
- 下载并解包 NapCat.Shell
- 下载并安装 Linux QQ 3.2.34（arm64 / amd64）
- 编译
libnapcat_launcher.so（启动时注入loadNapCat.js，不依赖 ptrace），并安装登录后自动配置 OneBot 的钩子
环境依赖由安装脚本自己备齐，不需要预先手工装。装完重启一次 DSH。
dist/ 里还有两个附件：dsh-napcat-0.1.0.tgz 是插件本体；dsh-napcat-handover2.zip 是交接整包（插件 tgz + 交接文档 + 一键入口），适合直接丢给智能体或另一台设备。
连接 QQ¶
插件版本 0.1.0，许可证 MIT。连接流程按 README 分六步：
- 进入设置 → QQ 机器人
- 点「一键启动 NapCat」
- 点「打开 WebUI」，用目标 QQ 扫码或密码登录
- 登录后
autoconfig-onebot.sh自动给onebot11_<QQ号>.json加上127.0.0.1:3001的 WS 服务（含 token），并带-q <QQ号>快速重启 NapCat - 回插件点「扫描本机」→「连接这个账号」
- 用另一个 QQ 发条消息验证
也可以用命令行手动确认：
/opt/napcat/start.sh # 起 Xvfb/VNC/QQ/NapCat
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/ # 426 = WS 在听
tail -f /root/.dsh/dsh-napcat/boot.log # 插件日志
远程 NapCat¶
不想在手机上跑 QQ 的话，可以在设置页「NapCat 主机」填那台机器（电脑 / 服务器）的局域网 IP，WebUI 端口 6099、OneBot 端口 3001，点「扫描本机」或直接填 ws://<IP>:3001/ + token。
源码结构¶
README 给了目录地图，排错时按这个找：
lib/index.js 宿主半端：路由、工具、懒人连接、配置
lib/napcat.js NapCat 探测 / onebot11 解析 / 启停
lib/onebot.js OneBot v11 客户端（重连、心跳、API 超时）
lib/pipeline.js 人设、记忆、聊天、暖场、表情包
lib/store.js 存档 / 记忆 / 表情包 / 扩展的数据层
lib/client.js 设置页（React）
install.sh 一键安装器
scripts/setup-napcat.sh 环境安装（NapCat + QQ + Xvfb/noVNC）
scripts/autoconfig-onebot.sh 登录后自动配 3001
docs/HANDOVER.md 完整交接：目录地图、九个坑、从零重装、排错、恢复
docs/SETTINGS.md 全部设置项速查
docs/EXTENSIONS.md 写扩展
常见问题与注意事项¶
README 列了这几个坑，值得先看：
- 装了插件 DSH 起不来：插件顶层
inject: ['webServer']会卡在「等待服务」，必须用ctx.inject([...], scope => ...)。恢复步骤见docs/HANDOVER.md第 5 节。 - WebUI 打不开：确认 6099 在听，
http://127.0.0.1:6099/webui/；token 在/opt/napcat/napcat/config/webui.json。 - 连上了但提示离线：NapCat 没登录（缺
-q <QQ号>会停在扫码页），此时 3001 在听也拿不到get_login_info。 - 登录服务 timeout：NapCat 的 msf 登录服务掉线，重试或换网络。
- 数据目录：插件数据放
~/.dsh/dsh-napcat/data，不要放/sdcard（FUSE 权限会炸）。
插件以当前 DSH 进程的权限运行，安装来自第三方仓库的内容在启用前应检查源码与许可证。插件本体 MIT；NapCat 与 Linux QQ 由各自上游提供，安装器只从官方 / 镜像下载，不随包分发。更多排错命令、恢复步骤和升级注意事项在 docs/HANDOVER.md。
结尾¶
dsh-qq-bot 的价值在于把「协议端 + 机器人行为 + 设置界面」这三件事合成一个可一键安装的块，手机本地跑，不用公网暴露。目录页 https://www.skillhub.cn/plugins/Tongyu3/dsh-qq-bot，源码 https://github.com/Tongyu3/dsh-qq-bot。
