Preface¶

DeepSeek Harness (dsh) encapsulates agent capabilities as pluggable Cordis plugins, but most examples still revolve around terminal or web interfaces. If you want colleagues or users to interact with an Agent directly within QQ, you need to handle the QQ Bot API, WebSocket long connections, inbound/outbound messages, and session isolation for each private chat/group chat yourself.

Below we introduce @tencent-connect/dsh-qqbot: a dsh client plugin maintained by tencent-connect that integrates QQ private and group chats into the dsh agent loop. Credentials can be bound via QR code scanning, and they also support passing via environment variables or configuration files.

What is This¶

@tencent-connect/dsh-qqbot is a QQ Bot IM channel plugin for deepseek-harness. The message flow is as follows:

QQ User → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
                                 ↑                           │
                                 └── session/event ──────────┘
                                       (assistant reply → QQ sendMarkdown)

The plugin adheres to dsh’s “Plugins, not loop changes” principle: it is a pure Cordis plugin, declares dependencies via inject = ['agents'], and does not directly modify the agent loop. Current version is 0.4.0, licensed under MIT, and requires Node.js >= 18. The GitHub repository has about 74 stars.

Core Features¶

Messages and Sessions¶

• Both private chats and group chats can trigger the Agent; group chats require @bot by default (requireMention, default true).
• Each QQ private user or group chat corresponds to a separate Agent, with the session key being qqbot:${appId}:${scope}:${peerId}, and a SessionId derived via SHA-256, which can be restored after process restart.
• Idle timeout (default 30 minutes) automatically disposes of the Agent to avoid memory leaks.
• Replies are sent in Markdown format, supporting text splitting aware of code blocks and tables (with a default limit of 4500 characters per message).

Model and Presets¶

• The default LLM provider is deepseek-official, model deepseek-chat; it can be switched via configuration or the /model command.
• Supports mounting agent-presets (tool sets, prompts, etc.), viewable or switchable via /preset, effective for new sessions.
• Private chats and group chats can have additional system prompts set separately (directPrompt, groupPrompt).

Built-in Slash Commands¶

Q&A Interaction¶

Supports dsh’s ask_user_question: for single-choice questions, it generates inline buttons (clicking one greys out the others), and for multiple-choice, reply with numbers; questions are presented sequentially. Single-question timeout defaults to 5 minutes (askTimeoutMs).

Installation and Enabling¶

Method 1: npm Installation (Recommended)¶

First install the plugin into a standalone profile, then start dsh:

# Install to profile
npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot

# Start
npx @deepseek-ai/dsh --profile qqbot

On first startup, if credentials are not configured, the plugin will enter QR code guidance: output a QR code in the terminal, scan it with the mobile QQ app to bind, and credentials are automatically saved to the profile. Subsequent startups do not require scanning again. It is recommended to use plugin version 0.4.0 or above, which supports clicking a link to open the QR code in a browser, avoiding misalignment issues in some terminals.

Method 2: Local Path Installation¶

Suitable for scenarios requiring source code modification:

cd /path/to/dsh-qqbot
pnpm install && pnpm build

npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot

export QQBOT_APPID="Your AppID" QQBOT_SECRET="Your AppSecret"
npx @deepseek-ai/dsh --profile qqbot

Method 3: –patch Development Mode¶

export QQBOT_APPID="Your AppID" QQBOT_SECRET="Your AppSecret"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

Configuration Options¶

AppID and AppSecret can be obtained after creating a Bot on the QQ Open Platform, and the plugin interfaces with QQ Bot API v2.

Typical Usage¶

1. Install and start according to Method 1, complete QR code scanning and binding.
2. In QQ private chats or groups, @bot and send questions; the Agent replies in Markdown.
3. For long conversations, use /compact to compress history; switch models with /model; reset context with /new.
4. For local development, pnpm dev watches for builds, and use --patch for debugging:

pnpm install
pnpm build
export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

Applicable Scenarios and Notes¶

Who is this for?

• Teams or individuals who already run Agents on dsh and want to expose the same capabilities to QQ.
• Deployments requiring IM-specific features like group chat @triggers, private chat direct connections, and per-peer model preferences.

Pre-use Notes

• The plugin runs with the permissions of the current dsh process. The Agent’s accessible working directory, tools, and network scope are the same as the dsh instance. Please read the source code and MIT license before installation to ensure it aligns with your security policies.
• Group chats require @bot by default to avoid triggering LLM calls for every message in the group.
• The community directory SkillHub is an independent site with no official affiliation with DeepSeek or High-Flyer; plugin information is based on the GitHub repository.

Conclusion¶

@tencent-connect/dsh-qqbot connects the QQ WebSocket message stream to the dsh agent loop. Credentials are configured via QR code or environment variables, and private chats and group chats maintain independent sessions. If you are looking for a QQ integration solution in the dsh ecosystem, you can start with the npm installation command and adjust the model, preset, and group chat prompts as needed.

• Directory page: https://www.skillhub.cn/plugins/tencent-connect/dsh-qqbot
• GitHub: https://github.com/tencent-connect/dsh-qqbot