Introduction¶

Running a QQ bot in DSH usually involves building the protocol endpoint yourself: either maintaining a bare NapCat configuration, or manually filtering users from group messages and manually storing contexts. dsh-qq-bot completes this path: the protocol endpoint is handled by NapCat, while the plugin handles persona, memory, archives, whitelist, and warming up directly within DSH. One-click installation on a mobile phone is all that’s needed to connect.

Below is an introduction to dsh-qq-bot maintained by Tongyu3. It is a QQ bot plugin for DSH, categorized as a client, based on NapCat + OneBot v11. It supports persona / memory / archives / whitelist / warming up / emojis / extensions, and can be deployed locally with one click on an Android phone.

What is this¶

dsh-qq-bot is maintained by Tongyu3, repository address is https://github.com/Tongyu3/dsh-qq-bot, directory page is https://www.skillhub.cn/plugins/Tongyu3/dsh-qq-bot. Its approach is: NapCat acts as the protocol endpoint using OneBot v11 (WebSocket), and the DSH plugin handles persona, memory, chat flow, and settings page.

Note that the repository name is dsh-qq-bot, but the internal package name and bundle id is dsh-napcat — the installation script, plugin data path ~/.dsh/dsh-napcat, and route /dsh-napcat/api/* all follow dsh-napcat, so don’t look for the wrong name when researching and troubleshooting.

Tested environment: DSH on an Android phone (Ubuntu 24.04 proot) + NapCat 4.18.42 + Linux QQ 3.2.34 arm64. The entire process only uses 127.0.0.1, no need to expose the bot to the public internet.

Core Features¶

The capabilities listed below are those explicitly written in the README.

1. Protocol: Default NapCat → OneBot v11 Forward WS (ws://127.0.0.1:3001/), also supports HTTP mode and remote NapCat.
2. Connection: The settings page provides “One-click Start NapCat”, “Open WebUI”, “Scan Localhost”, “Connect this Account”, no need to manually edit JSON.
3. Persona and Memory: Divided into persona configuration, long-term memory, and conversation archives; archives can be rolled back.
4. Whitelist: Only reply to specified QQ or groups; all other messages are discarded directly.
5. Active Warming Up: Automatically initiates topics when no one speaks for a long time.
6. Emojis: Local emoji directory + automatic selection and sending.
7. Extensions: examples/extensions/*.mjs for hot-pluggable custom commands.
8. Logging: Every request, reply, and error is logged to disk; viewable in the settings page.

Installation and Enablement¶

Environment requirements: Linux (arm64 or amd64), Android proot containers are also available; Node.js ≥ 20; DSH 0.2.x, profile directory available (default ~/.dsh/profiles/web). One-click installation will additionally install Xvfb, x11vnc, noVNC, Electron runtime, Chinese fonts, NapCat.Shell, and Linux QQ. Access to GitHub mirrors (gh-proxy.com) and Tencent CDN (qqdl.gtimg.cn) is recommended.

The dist/ directory contains ready-to-use compressed packages; no need to expand the source code. Installation commands are from the README:

tar xzf dist/dsh-napcat-0.1.0.tgz
cd package
bash install.sh

The installer does six things:

1. Copies the plugin to $DSH_HOME/plugin-src/dsh-napcat and links it into $DSH_HOME/profiles/web using link:
2. Writes dsh-napcat into the profile’s dsh.profile.bundles
3. Installs Xvfb / x11vnc / noVNC / Electron runtime / Chinese fonts
4. Downloads and unpacks NapCat.Shell
5. Downloads and installs Linux QQ 3.2.34 (arm64 / amd64)
6. Compiles libnapcat_launcher.so (injects loadNapCat.js at startup, does not depend on ptrace), and installs the hook to auto-configure OneBot after login

Environment dependencies are provided by the installation script itself; no need to manually install beforehand. Restart DSH once installed.

There are also two attachments in dist/: dsh-napcat-0.1.0.tgz is the plugin itself; dsh-napcat-handover2.zip is the handover package (plugin tgz + handover docs + one-click entry), suitable for handing directly to an agent or another device.

Connecting to QQ¶

Plugin version 0.1.0, license MIT. The connection process follows six steps in the README:

1. Enter Settings → QQ Bot
2. Click “One-click Start NapCat”
3. Click “Open WebUI”, scan the target QQ code or login via password
4. After login, autoconfig-onebot.sh automatically adds the WS service at 127.0.0.1:3001 (including token) to onebot11_<QQ号>.json, and restarts NapCat quickly with -q <QQ号>
5. Go back to the plugin and click “Scan Localhost” → “Connect this Account”
6. Send a message from another QQ to verify

You can also manually confirm via the command line:

/opt/napcat/start.sh                     # Start Xvfb/VNC/QQ/NapCat
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/   # 426 = WS listening
tail -f /root/.dsh/dsh-napcat/boot.log   # Plugin logs

Remote NapCat¶

If you don’t want to run QQ on the phone, you can fill in the LAN IP of that machine (computer/server) in the settings page “NapCat Host”, WebUI port 6099, OneBot port 3001, and click “Scan Localhost” or directly fill ws://<IP>:3001/ + token.

Source Code Structure¶

The README provides a directory map; use this when troubleshooting:

lib/index.js        Host side: routes, utilities, lazy connection, config
lib/napcat.js       NapCat detection / onebot11 parsing / start/stop
lib/onebot.js       OneBot v11 client (reconnect, heartbeat, API timeout)
lib/pipeline.js     Persona, memory, chat, warming up, emojis
lib/store.js        Archive / memory / emoji / extension data layer
lib/client.js       Settings page (React)
install.sh          One-click installer
scripts/setup-napcat.sh       Environment setup (NapCat + QQ + Xvfb/noVNC)
scripts/autoconfig-onebot.sh  Auto-config 3001 after login
docs/HANDOVER.md    Complete handover: directory map, nine pitfalls, reinstall from scratch, troubleshooting, recovery
docs/SETTINGS.md    Quick reference for all settings
docs/EXTENSIONS.md  Writing extensions

Common Issues and Notes¶

The README lists these pitfalls, worth checking first:

• DSH won’t start after installing the plugin: The plugin’s top-level inject: ['webServer'] will hang on “Waiting for service”, you must use ctx.inject([...], scope => ...). See section 5 of docs/HANDOVER.md for recovery steps.
• WebUI won’t open: Confirm 6099 is listening, http://127.0.0.1:6099/webui/; token is in /opt/napcat/napcat/config/webui.json.
• Connected but shows offline: NapCat is not logged in (missing -q <QQ号> will stop at the scan page), at this point 3001 is listening but get_login_info cannot be obtained.
• Login service timeout: NapCat’s msf login service goes offline, retry or change network.
• Data directory: Plugin data goes in ~/.dsh/dsh-napcat/data, do not put it in /sdcard (FUSE permissions will crash).

The plugin runs with the permissions of the current DSH process. Content installed from third-party repositories should be checked for source code and license before enabling. The plugin itself is MIT; NapCat and Linux QQ are provided by their respective upstreams, and the installer downloads only from official/mirror sources, not distributed with the package. More troubleshooting commands, recovery steps, and upgrade notes are in docs/HANDOVER.md.

Conclusion¶

The value of dsh-qq-bot lies in synthesizing these three things—protocol endpoint + bot behavior + settings interface—into a one-click installable block that runs locally on a mobile phone without exposing it to the public internet. Directory page https://www.skillhub.cn/plugins/Tongyu3/dsh-qq-bot, source code https://github.com/Tongyu3/dsh-qq-bot.