Preface

One of the core ideas of DeepSeek Harness (DSH) is “everything is a plugin.” When interacting with an Agent via an instant messaging client, a standardized driver layer is required. The dsh-qqbot plugin provides this capability, treating the QQ messaging platform as a front-end protocol driver for a dsh agent. Users can converse with the Agent in QQ direct messages or group chats, execute tools, switch models, manage sessions or workspaces, and complete approvals through QQ messages.

Plugin Positioning

dsh-qqbot is an open-source QQ Bot IM plugin for DeepSeek Harness (dsh). The project is maintained by cafeawa and is licensed under the MIT License.

The plugin was rewritten from scratch. It does not include Tencent’s internal plugin code and does not depend on the UNLICENSED @tencent-connect/qqbot-connector. Its underlying protocol uses the MIT-licensed @tencent-connect/qqbot-nodejs.

Core Features

The plugin has the following core capabilities:

  • Message intake and rendering: Supports QQ direct message (C2C) and group chat message intake. Supports streaming replies and Markdown chunked sending, ensuring that long text renders correctly on the QQ platform.
  • Session management: Supports session isolation, idle reclamation and restart recovery, as well as workspace isolation and cross-session switching.
  • Model routing: Supports per-peer (single-chat peer) preference configuration, configuration via settings.yaml, or inheritance of the host’s default settings.
  • Context processing: Supports group chat history context, quoted message handling, and file attachment downloads.
  • Built-in commands: Provides commands such as dsh, goal, /bot-model, /bot-reset, /bot-status, and /bot-workspace.
  • Approval bridging: Provides a dsh approval bridge, supporting approval via QQ buttons/text while the WebUI is also notified simultaneously.
  • Task notifications: Supports completion notifications for long-running goal tasks.

Installation and Configuration

Environment Requirements

Node.js >= 18, and the dsh environment must be available.

Build and Install

In the dsh-qqbot project directory, run the following commands to build and install the plugin into a dsh profile:

# 1. 安装依赖并构建
corepack pnpm install
corepack pnpm build

# 2. 安装插件（使用本地路径）
dsh plugin --profile qqbot add /path/to/dsh-qqbot

After installation, it can be loaded via the --patch mechanism using cordis.patch.yml.

Configuration File

In the profile’s cordis.patch.yml, configure the QQ Bot credentials and some runtime parameters:

- id: im-qqbot
  config:
    appId: __FROM_ENV__
    appSecret: __FROM_ENV__
    requireMention: true
    textChunkLimit: 4500
    sessionIdleTimeout: 1800000
    maxQueue: 20
    processingTimeoutMs: 120000
    historyLimit: 10
    access:
      c2cMode: open
      c2cAllow: []
      groupMode: open
      groupAllow: []
    debug: false

Main configuration options:
* appId / appSecret: QQ Bot credentials; supports reading from environment variables QQBOT_APPID / QQBOT_SECRET.
* requireMention: Whether the bot must be @-mentioned in group chat mode to trigger a conversation.
* sessionIdleTimeout: Session idle timeout (milliseconds).
* access: Access control mode (open means open).

Startup and Usage

After configuration, start dsh and load the plugin using the following method:

export QQBOT_APPID="你的AppID"
export QQBOT_SECRET="你的AppSecret"
dsh --profile qqbot

Architecture Overview

The plugin message processing flow is as follows:

QQ 用户 → QQ WebSocket → @tencent-connect/qqbot-nodejs → 中间件链
                                                              ↓
                                                     handleInbound
                                                              ↓
                                                     SessionManager → dsh agent
                                                              ↓
                                              session/event → outbound → QQ Markdown

Notes

  1. The plugin runs with the permissions of the current dsh process. Please ensure that you review the source code and license before installation.
  2. Ecosystem context: The DSH philosophy is “everything is a plugin.” The community directory is an independent site and has no official affiliation with DeepSeek / 幻方.

Summary

dsh-qqbot provides DSH Agents with a standardized QQ integration layer. Through features such as session management, model routing, and approval bridging, it makes it possible to build complex workflows on the QQ platform. Project address: https://github.com/cafeawa/dsh-qqbot