Introduction

DeepSeek Harness (DSH) is built on the core design philosophy of “everything is a plugin,” using plugin-based extensions to construct a local agent environment. Connecting an official QQ bot usually requires complex WebSocket connection maintenance and callback configuration, making it difficult for typical developers to maintain directly. The dsh-QQbot plugin encapsulates the official SDK’s connection logic and integrates it with the local DSH, enabling an AI assistant to work directly in QQ group chats or direct messages.

What Is It

dsh-QQbot is a client-side plugin maintained by master1Sun. It uses the official QQ bot’s WebSocket persistent connection mode to forward message streams into local DSH conversations. After being processed by DSH’s AI capabilities, the replies are distributed back to QQ by the plugin. The plugin supports independently operating multiple bots, running without a public endpoint, and provides rich message-processing functionality.

Core Features

  • Multiple Bots: Uses bots.json as the single source of truth for managing bots. Each bot has independent credentials and configuration, can stay online at the same time, and all replies are sent by the originating bot.
  • No Public Endpoint Required: Leverages the official SDK’s outbound connections to the QQ gateway, so the plugin can run without a public IP, domain name, or callback configuration.
  • Message Responses:
    • Group Chats: Replies directly when @mentioned (with the latest 10 messages included as context); unmentioned messages are filtered by value scoring before the bot interjects.
    • Direct Messages: Establishes a conversation directly.
  • Conversations and Memory: Reuses the same conversation for the same group chat or direct message. Supports /new to start a new conversation, as well as /记忆 and /清空记忆 for long-term memory management.
  • Multimodal and Voice: Supports images, files, and voice content in the context; voice transcription supports five levels; supports TTS voice replies and the “typing” status.
  • Scheduled Messages: Supports the /定时 command, with scheduling precision of approximately 30 seconds. Supports daily scheduling, interval repetition, and a mode=ai mode where the AI generates content in real time.
  • Group Management: Built-in sensitive-word recall, /广播, group join greetings, sticker recall, and sensitive operation approval.
  • AI Tools: Provides tool functions such as qqbot_schedule_*, qqbot_send_message, and qqbot_memory_*, allowing these capabilities to be invoked directly in a conversation.
  • Security and Reliability: Includes reply sanitization, media SSRF protection, a local path allowlist, daily quota control for proactive messages, and local message archiving.
  • Settings Interface: Integrated into DSH’s settings page; supports adding bots by QR scan or manual entry, and behavior configuration takes effect immediately.

Installation and Activation

The plugin must be installed into a specific DSH configuration profile (profile). Make sure to run the installation command from the correct profile directory.

dsh plugin --profile web add <本目录或 git 地址>

After installation, the plugin depends on ctx.webhookRuntime provided by @deepseek-ai/dsh-webhook. If that dependency is unavailable, the plugin falls back to degraded operation (does not create sessions); you can then check the status on the settings page and via /status.

Typical Usage

  1. Prepare the Environment: Create a bot on the QQ Open Platform and obtain the appId and appSecret. Configure the outbound IP allowlist, and set the “available group chat message scope” in the group settings to all.
  2. Add the Bot: Open DSH settings and go to the “QQ Bot” page. Add the bot by scanning a QR code or entering the information manually; it takes effect immediately after saving.
  3. Start Interacting: Invite the bot to a group chat or add it as a friend. Directly @mention it to start talking, or converse with it in a direct message.

Known Boundaries

  • Scheduled Message Precision: Scheduling precision is 30 seconds, and triggers only occur while the process is running; they do not occur when the process is stopped.
  • Group Chat Reply Limits: The passive reply window is limited to 5 minutes / 5 times. For very long tasks, sending may fail (you can enable proactiveFallback to consume the proactive quota).
  • Context Limits: Group chat historical context replays text content only and does not include images or files from historical attachments.
  • Process Reliability: webhookRuntime uses an in-process fire-and-forget mode. If the DSH process crashes, messages that have not been added to the conversation will be lost.

Conclusion

This plugin is suitable for developers who need to run DSH locally and want to use it directly within the QQ ecosystem. Before installation, it is recommended to review the source code and license (MIT). For more configuration details, refer to the GitHub repository.