Preface¶

DeepSeek Harness (command: dsh) summarizes its architecture in one sentence: everything is a plugin. Models, tools, sessions, sandboxes, and even the Agent loop itself can be replaced. The official repository is still in developer preview at the time of writing, and breaking compatibility changes are expected. Common entry points after out-of-the-box use are the Web UI and headless one-off tasks; if you want the same set of Agents to appear in QQ — where you can continue conversations in private chats and only respond when mentioned in groups — you need an IM channel instead of modifying the Agent loop.

This is exactly what dsh-qqbot does. Maintained by tencent-connect, the repository positions itself as a frontend protocol driver that treats the QQ messaging platform as a dsh Agent: messages coming from QQ enter ctx.agents, and model replies are sent back to QQ in Markdown format. The community plugin directory lists it under “Tools and Capabilities”, with an inclusion date of 2026-08-15. Note that this directory is an independent site and has no official affiliation with DeepSeek / HuanFang, and should not be treated as an official app store. The “official plugin” mentioned in the repository refers to the plugin for connecting Tencent QQ Bot to dsh, not official endorsement from the directory site.

This article is collated after cross-checking with the plugin directory page, the GitHub repository README, package.json, and the official DeepSeek Harness repository: what it is, which profile to install it to, and how to chat after scanning the QR code.

What it is¶

The npm package name of dsh-qqbot is @tencent-connect/dsh-qqbot. The current package.json version is 0.4.0, the primary language is TypeScript, and the license is MIT (Copyright 2026 Tencent Connect). The GitHub repository tencent-connect/dsh-qqbot was created on 2026-08-14; as of writing (2026-08-17), the GitHub API shows 53 stars, while the community directory page displayed 26 stars at the time. Star counts should refer to the first-hand GitHub data.

Its solved problem is very specific: enabling an already initialized dsh environment to send and receive messages via QQ Bot. The data flow in the README can be visualized as:

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

In other words, instead of writing a whole new bot logic, this plugin adds an IM frontend to an existing dsh Agent. The plugin declares itself as a pure Cordis plugin, following dsh’s “Plugins, not loop changes” philosophy: it declares inject = ['agents'] as a dependency, and does not directly couple with other plugins.

Core Features¶

Separate sessions for private chats and group chats¶

Each QQ private chat user and each group corresponds to an independent Agent. The session key is qqbot:${appId}:${scope}:${peerId}, and the SessionId is deterministically derived via SHA-256. After the process restarts, it can be restored using the same rules. The parsing order is: reuse within the process → restore from persistence → create anew. The default idle timeout is 30 minutes (sessionIdleTimeout, 1800000 ms), after which the Agent will be automatically disposed to avoid occupying memory indefinitely.

Group chats require @ to reply by default¶

requireMention defaults to true: if the bot is not mentioned in a group, the plugin will not send ordinary group chat messages to the Agent. You can additionally add directPrompt and groupPrompt for private chats and group chats respectively, to append an extra system prompt. The configuration Schema in the source code also provides access control: private chats and group chats can be set to open, allowlist, or disabled, with support for openid whitelists. This item is not listed in the README configuration table; for fine-grained permission control, refer to the repository source code.

Replies use Markdown and are split according to QQ length limits¶

Outgoing messages are sent via sendMarkdown instead of plain text. The default maximum length for a single message is 4500 characters (textChunkLimit), and the source code comments note that QQ’s actual limit is approximately 5000 characters. The splitting logic will detect code blocks and tables to avoid truncating Markdown structures mid-element.

Manage sessions and models within chats¶

The slash commands listed in the README are as follows:

You can also find registered commands like /bot-new (new session), /bot-clear (similar to reset), /bot-ping, and /bot-version in the source code; the official external documentation takes the four commands listed in the README as the standard. The default LLM provider is deepseek-official, and the default model is deepseek-chat. You can also modify the provider and model parameters, or load presets from agent-presets (tool sets, prompts, etc.) via preset.

Installation and Activation¶

Before starting, complete dsh initialization and model configuration according to the official DeepSeek Harness guidelines. The current developer preview startup method for the official repository is:

npx @deepseek-ai/dsh web

The installation command given on the community directory page is:

dsh plugin add github:tencent-connect/dsh-qqbot

For reproducible installations, the directory page recommends pinning the commit hash:

dsh plugin add github:tencent-connect/dsh-qqbot#<commit>

Replace <commit> with the actual commit hash from the repository. The plugin runs with the permissions of the current dsh process, and may execute code during installation; you should inspect the source repository and license before installing.

The repository README recommends creating a separate qqbot profile and installing the npm package (current version 0.4.0). The README notes: it is recommended to upgrade to version 0.4.0 or higher before scanning the QR code, which supports clicking links to open in a browser and avoids misrendered QR codes in some terminals.

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

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

On first startup, if credentials have not been configured, the plugin will enter the QR code setup flow: a QR code will be printed in the terminal → scan it with mobile QQ to bind → credentials will be written to this profile. You will not need to repeat the scan on subsequent startups.

For local source code modifications, or for direct use via environment variables without scanning the QR code, the README provides a path-based installation method:

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

For development and debugging, you can also use --patch:

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

appId and appSecret are required parameters, which can also be provided via the environment variables QQBOT_APPID and QQBOT_SECRET. Never commit secrets to public repositories.

When installing from GitHub source code, the official dsh documentation also reminds you that git dependencies pull source code instead of built artifacts. pnpm ≥10 may require you to enable allowBuilds for this package in the profile’s pnpm-workspace.yaml before executing add again. If the first add fails, follow the terminal prompts and do not skip the authorization check.

Typical Usage¶

After binding is complete, you can send messages directly to the bot in QQ. The steps below can all be reproduced according to the repository documentation.

1. Complete a conversation in a private chat¶

After starting the qqbot profile and completing the QR code scan, send a regular question to the bot. The message will enter the plugin via WebSocket, then call agent.followup(). The reply will be sent back in Markdown format; if it exceeds textChunkLimit, it will be split automatically. The default model is deepseek-chat.

2. Only respond when mentioned in a group chat¶

After inviting the bot into a group, it will not reply to every group message by default. You need to @ the bot, or set requireMention to false (not recommended in noisy groups). You can also write a separate groupPrompt for group chats, for example to restrict tone or prohibit proxying sensitive operations.

3. Manage the current session with slash commands¶

Send the following messages in the corresponding private chat or group:

/bot-help
/bot-status
/bot-model
/bot-reset

/bot-help lists all available commands; /bot-status shows the current session status; /bot-model lets you view or switch the model; use /bot-reset to clear context if the conversation goes off track. These commands act on the session of the current peer, and will not clear the memory of other users or groups.

4. Modify common configurations per the README¶

The most relevant items in the README configuration table for daily use are:

cwd determines the working directory of the Agent on disk. dsh’s tools default to following the current process permissions. After connecting the bot to QQ, you are exposing this set of permissions to anyone who can send messages, so you should carefully consider whitelists and requireMention first.

Applicable Scenarios and Notes¶

This tool is suitable for users who are already using dsh and want to connect the same set of Agents to QQ: personal assistants in private chats, small teams using @bot in groups to query code or run tasks, and triggering your custom presets from QQ. It is not suitable to be understood as “install it and replace the official QQ customer service backend” — it is an IM channel plugin, and the models, tools, and sandboxes still come from your current dsh profile.

Keep these notes in mind before use:
1. Permissions and Source Code. The plugin runs with the permissions of the current dsh process, and may execute code during installation. Read the source code of tencent-connect/dsh-qqbot and the MIT license before installing; for production environments, use the pinned commit format github:owner/repo#commit as recommended on the directory page.
2. Credentials. AppID / AppSecret or credentials written via QR code scan are equivalent to the bot’s identity. Do not commit them to git, and do not use unrestricted open mode on shared machines without access control.
3. Preview Version Compatibility. The official DeepSeek Harness README clearly states that it is currently in developer preview, with breaking changes expected. The plugin’s peer dependencies point to @deepseek-ai/cordis >=4.0.1 and @deepseek-ai/dsh-agent / dsh-llm / dsh-session >=0.1.0-rc.6. If loading fails after upgrading dsh, first verify the versions of these dependencies.
4. Group Chat Disturbance. The default @ gatekeeping is designed to reduce unnecessary interruptions. Before turning off requireMention, confirm the group size and access control settings.
5. Directory and Repository Are Not the Same. Use the installation command from the directory page as the standard; the specific QR code process, configuration items, and commands should refer to the GitHub README. If there is a conflict between the two, the repository’s first-hand documentation is closer to the actual implementation.

Summary¶

dsh-qqbot turns QQ into a frontend for dsh Agents: private chats and group chats have isolated sessions, can be restored to the same sessionKey after a process restarts, default to responding only when mentioned in groups, and replies are split and sent according to Markdown rules. The installation command on the directory page is dsh plugin add github:tencent-connect/dsh-qqbot; to actually run it, the more complete process is to install it into the qqbot profile, then scan the QR code to bind after starting.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-qqbot/

GitHub: https://github.com/tencent-connect/dsh-qqbot