Foreword

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin,” enabling various messaging platforms to be integrated into the Agent ecosystem through protocol-driven adapters. dsh-qqbot is an enhanced fork of the QQ Bot IM plugin based on deepseek-harness (dsh). It uses the QQ messaging platform as a front-end protocol driver for dsh agents and provides an integration solution based on the official Bot API. This eliminates potential account ban risks and stability issues associated with third-party protocol endpoints, while also adding rich media interaction, group management, and extension development capabilities.

Feature Overview

The plugin provides the following core capabilities:

  • Protocol-driven: An enhanced fork of the QQ Bot IM plugin based on deepseek-harness (dsh), using the QQ messaging platform as a front-end protocol driver for dsh agents.
  • Official Bot API: Uses the official Bot API (non-simulated protocols) with no account ban risk.
  • Sticker image library: Supports automatic deduplication, categorization, search, and selection.
  • Rich media sending and receiving: Supports sending and receiving images, voice messages, videos, files, and other media types.
  • Scheduled tasks: Supports preset scheduled tasks that let the AI speak in groups at scheduled times.
  • Multi-instance personalities: Supports independent operation of multiple accounts, with each instance having its own AppID, personality settings, and image library.
  • Affinity system: Features dual-dimensional calculation of familiarity and affinity, influencing the AI’s willingness to speak proactively.
  • Visual settings panel: Provides a floating dock for configuration, supports chat history playback and rich media viewing.
  • Group management: Supports join approval, muting, and member lookup.
  • Extension system: Provides five extension points, supporting custom tools, commands, interaction logic, and message processing.
  • Kick user function: Implemented using an owned QQ account together with the official QQ group web interface (functionality is limited and requires an owned account).

Installation and Enablement

Before installing, ensure that DeepSeek Harness is installed and that you are in the web profile environment, because the visual settings panel (floating dock) is only effective under the web profile.

  1. Run the following command to install the plugin:
    npx @deepseek-ai/dsh plugin --profile web add @zaofan/dsh-qqbot
  1. After installation, a “QQ Bot” panel will appear in the settings of dsh web; click it to configure the plugin.
  2. If installing directly from the GitHub source, ensure that the compiled artifact dist/ exists at the repository root (using the published npm release is recommended).

Core Capabilities

Protocol Integration and Security

The plugin does not use simulated protocol endpoints (such as NapCat); instead, it directly uses the official Tencent QQ Bot Open Platform API. This approach does not rely on logging in with your personal QQ account, has an extremely low account security risk, and consumes minimal resources (requires only HTTP + WebSocket). Because functionality is limited by the official API, some advanced features (such as kicking users) require special methods provided by the plugin.

Visual Configuration and Group Management

After installing it into the web profile, a floating dock appears in the lower-right corner of the interface. The following operations can be performed from this panel:
* Group management: Handle join approval, muting, and view the member list. The kick-user feature must be implemented using your own QQ account through the official QQ group web interface; after scanning the QR code once, you can avoid scanning for a long time.
* Chat playback: View group and private chat records like regular QQ, with support for zooming into images, playing local videos, and converting SILK voice messages to MP3.
* Send messages: Directly send text, images, or files in the panel’s chat box.

Extension System

The plugin includes an extension system that allows adding custom functionality without modifying the plugin source code. It provides five extension points:
1. tools: Tools that the AI can invoke proactively during reasoning.
2. commands: Logic executed when users trigger specific commands.
3. botplay: Handles card interaction button click events.
4. hooks: Tasks or listeners executed when the plugin starts.
5. inbound: Takes control of each message’s lifecycle (for example, filtering, rewriting, or silent handling).

Stickers and Intelligent Interaction

  • Image library management: The bot automatically stores images received in groups into the image library, with deduplication and categorization support.
  • Automatic replies: When users send commands such as “Send a happier image,” the AI automatically searches the library and selects an appropriate sticker.
  • Affinity mechanism: The system uses a small model to analyze the AI’s internal thoughts and actual statements to calculate familiarity and affinity. Affinity only affects the frequency of proactive statements; negative affinity does not cause the bot to ignore or attack group members.

Deployment Notes

  • Profile restriction: It must be installed into the web profile to use the visual settings panel. If installed into other profiles, the floating dock and settings page will not be visible.
  • Kick-user feature: The official QQ API does not expose a user-kicking interface; the plugin implements this feature using an “owned QQ account + official QQ group” approach. This means you need to manage the group with your own account and ensure that the account has administrator permissions.
  • Android deployment: In Android Termux or similar environments, if the system does not support the ONNX runtime, it is recommended to select “Program fallback (no small model dependency)” in the settings.
  • Privacy and security: The plugin does not contain any bot credentials (AppID/Secret) or private data; all sensitive information is managed by the user.

Summary

dsh-qqbot provides a secure, low-cost QQ bot integration solution for DeepSeek Harness. It ensures stability through the official API, provides flexible development capabilities through the extension system, and lowers the usage barrier through the visual settings panel. It is suitable for developers who need to deploy AI assistants in QQ groups, manage groups, or develop custom interaction features.