Introduction¶

Building a bot on DeepSeek Harness (DSH) that can send and receive QQ messages inevitably involves three things: installing LinuxQQ, installing OneBot implementations like NapCat, and then separately handling login state and startup. These three tasks are scattered across the command line and multiple processes; you have to redo them when changing machines, and the login state is easily lost. The dsh-qq-stack introduced below integrates this entire process into a single plugin: downloading, unpacking, configuring, and starting are handled by the plugin, login state is managed, and only a standard OneBot 11 interface is exposed externally.

What is it¶

dsh-qq-stack is a QQ protocol endpoint plugin for DSH, maintained by 2008BingYu. It solves the repetitive labor mentioned above: handing the installation, startup, and login of LinuxQQ and NapCat to the plugin for management, and providing an upstream OneBot 11 Forward WebSocket for any compatible client to connect to. The repository version is 1.1.0, licensed under MIT.

Core Features¶

The plugin’s capabilities are mainly divided into six items based on responsibilities:

• Start with engine: Automatically check the runtime environment after the engine starts; install in the background if missing, and start QQ directly when ready.
• Standard protocol endpoint: OneBot 11 Forward WebSocket, listening on 127.0.0.1:3001 by default.
• Login state management: Save the account after scanning the QR code once, and use quick login for subsequent startups.
• Visible installation process: Display the download and extraction status of LinuxQQ and NapCat step-by-step, as well as mirror speed test progress.
• Configuration modifiable on page: Changes to listen address and access token take effect automatically after saving.
• Runtime environment cleanup: Stop QQ with one click on the page and delete downloaded clients and login data.

Installation and Activation¶

The installation command comes from the original README:

dsh plugin --profile web add dsh-qq-stack

You can also enter the package name in the “Add Plugin” section of the plugin page, or use the archive provided in the Release. After installation, the engine needs to be restarted once.

Note: The plugin will not automatically install the runtime environment. About 2 seconds after the engine starts, it checks ~/.dsh/qq-bot: if installed, QQ starts directly; if not installed, it only prompts on the settings page, and the following steps will only be executed after clicking “Start Installation”:

1. Download LinuxQQ client (approx. 198MB)
2. Check system dependencies, install corresponding packages for the current distribution if missing
3. Test multiple download sources, select an available and fastest one to download NapCat (approx. 34MB)
4. Unpack, write OneBot config, and generate startup script
5. Start QQ

The installation process and results are recorded in ~/.dsh/qq-bot/logs/install.log, and the page displays the current step and progress synchronously.

Typical Usage¶

The settings page is divided into two tabs: “Login” and “Settings”. The login page shows a QR code when not logged in; after scanning with QQ Mobile and confirming on the phone, the QR code area shows the current status; after successful login, it displays the avatar, nickname, and QQ number, and allows account switching. The settings page includes connection settings (listen address and access token, which take effect automatically after modification and restarting QQ) and runtime environment cleanup (stop QQ and delete ~/.dsh/qq-bot).

The configuration file is ~/.dsh/qq-bot/config.env, with the following keys:

The default installation directory is ~/.dsh/qq-bot, which can be modified via the environment variable DSH_QQ_ROOT.

When connecting a OneBot client, any compatible OneBot 11 client can connect: address ws://127.0.0.1:3001, token consistent with DSH_QQ_TOKEN, and no need to fill it in when this value is empty.

Check logs when issues arise, the paths are as follows:

Every operation on the page is recorded in plugin.log, and you can also get the tail content directly:

http://127.0.0.1:3080/api/plugins/qq-stack/log?n=200

Tokens in the logs are replaced with ***.

Applicable Scenarios and Notes¶

The environment requirements are Linux (aarch64 / amd64), capable of installing apt packages; the DSH runtime environment on Android is also applicable; Node ≥ 22.5; first-time installation requires about 250MB of disk space and corresponding download traffic. The Linux QQ client started by the plugin relies on xvfb-run and dbus-run-session, so Windows is not supported.

A few common pitfalls:

• Still shows not logged in after scanning, need to confirm login on the phone first, scanning alone does not constitute login
• Uninstalling or cleaning the runtime environment deletes login data, so a reinstall is a fresh installation requiring rescan
• After disconnecting for a while, the engine will restart QQ and quick login with the saved account; if the login state expires, rescan is needed
• No reply in the group, message processing is handled by the connected dialogue plugin, this plugin only maintains QQ online status and protocol interface
• Prompts of login failure or account restrictions are QQ-side limitations, need to complete identity verification in QQ Security Center before trying to login

Also, pay attention to permission boundaries: the plugin runs with the permissions of the current dsh process; check the source code and license before installing, then decide whether to introduce it.

Uninstalling the plugin will not automatically delete the runtime environment; choose one of the two methods: click “Clean Runtime Environment” on the settings page before uninstalling, or manually execute:

bash ~/.dsh/qq-bot/stop-qq.sh && rm -rf ~/.dsh/qq-bot

Conclusion¶

The value of dsh-qq-stack lies in making the process of “installing environment, starting QQ, managing login, exposing protocol” a reproducible pipeline, so that when connecting a QQ bot to DSH, manual maintenance of LinuxQQ and NapCat is no longer needed. The directory page is at https://www.skillhub.cn/plugins/2008BingYu/dsh-qq-stack, and the source code is at https://github.com/2008BingYu/dsh-qq-stack. This directory is a community site and has no official affiliation with DeepSeek / Hypersphere.