Introduction

DeepSeek Harness (DSH) is an agent runtime environment based on the Cordis framework. dsh-adapter-qq is its official QQ bot adapter plugin, designed to meet the need for developers to have in-depth interactions with a DSH Agent through mobile or desktop QQ (such as full coding, Shell execution, and sub-agent planning).

Unlike common reverse-engineered protocol implementations, this plugin is built on the official QQ OpenAPI v2. It connects DSH’s Web UI capabilities with the QQ one-on-one chat window, enabling real-time synchronization of conversations, execution, and approvals.

Core Features

This plugin primarily provides the following capabilities:

  1. C2C one-on-one chat adaptation based on QQ OpenAPI v2: Uses long-lived WebSocket Gateway connections to receive messages and HTTP APIs to send messages. No third-party reverse-engineered protocol is required, providing a stable and compliant connection.
  2. Real-time bidirectional synchronization: Ask a question in QQ and see it reflected in the Web UI in real time; perform operations in the Web UI and receive progress updates in QQ in real time.
  3. Bidirectional approval synchronization: When operations that exceed permissions (such as file modifications) are encountered, approval cards are pushed to both QQ and the Web UI. Supports one-click “Allow” or “Deny” in QQ, with immediate resolution on both sides.
  4. Interactive control board: Generates a button panel in chat, supporting one-click session switching, preset selection, and permission switching without complex input.
  5. Global custom quick menu: Automatically registers a bottom quick menu through the official API after startup, providing entries for the session list, status, and quick management.
  6. Dynamic presets and permission management: The preset list is dynamically retrieved from the DSH runtime, supporting instant switching of permission levels within a session (read-only, workspace write, full system).
  7. Native Web UI configuration: Configuration items are embedded in the native DSH Web UI settings page, with sensitive fields automatically masked.

Installation and Prerequisites

Before installing, ensure your environment meets the following requirements:

  • Node.js: version >= 18
  • Dependencies: @deepseek-ai/cordis (^4.0.0) and @deepseek-ai/schemastery (^3.18.0)
  • QQ credentials: You must have the AppID and AppSecret from the QQ Open Platform

The installation command is as follows:

dsh plugin --profile web add dsh-adapter-qq

Configuration

After installation, go to the Settings page in the DSH Web UI and expand the QQ Bot card to configure it. The main configuration options include:

  • appId: Enter the Bot AppID from the QQ Open Platform.
  • clientSecret: Enter the AppSecret (masked display).
  • sandbox: Whether to connect to the sandbox environment (recommended during testing).
  • userOpenid: The dedicated bound user OpenID (if left blank, it will be automatically bound when the first message is received).
  • defaultPreset: The default Agent preset for new sessions (e.g., standard).
  • defaultCwd: The default working directory for new sessions.
  • autoRegisterMenu: Automatically register the bottom quick menu after startup.
  • markdown: Prefer Markdown rendering for message replies.
  • syncToolCalls: Whether to synchronously push tool call execution progress.
  • toolCallAggregateWindowMs: Aggregation window duration for tool call pushes (milliseconds).

Interactive Commands

In the QQ one-on-one chat window, you can send the following commands directly or click buttons in the bottom menu / control board:

Command Description
/sessions View the workspace hierarchical session list; supports switching by key/button
/new Start the new session wizard; select a workspace or directory
/switch <index or ID> Switch the currently active session
/current View detailed information about the current session
/model View the model list; supports one-click switching
/effort View or switch the reasoning level (off/low/medium/high/xhigh/max)
/stats View session statistics (rounds, steps, LLM latency, cache hit rate, etc.)
/preset View or switch the Agent preset
/permission View or switch the permission mode (read-only, workspace write, full system)
/cancel / /stop Abort the current Agent run
/approve / /reject Approve or reject pending approval requests
/menu Manually synchronize the bottom quick menu
/help Show the help menu and control board

Notes

  • Runtime permissions: The plugin runs with the permissions of the current DSH process. Pay attention to permission configurations when performing system operations or file modifications.
  • License: The project follows the MIT License.
  • Network environment: If using proxy software (such as Clash), ensure that bots.qq.com and *.qq.com have direct connections to avoid DNS resolution failures.

Summary

dsh-adapter-qq is a key plugin that connects the DeepSeek Harness ecosystem with the QQ ecosystem. It provides a stable and compliant C2C interaction method through official APIs and implements deep bidirectional binding with the Web UI. It is suitable for developers who need to use DSH’s coding and execution capabilities on mobile devices or in instant messaging scenarios.

Documentation and Source Code:
* Skill directory: https://www.skillhub.cn/plugins/jixishi/dsh-adapter-qq
* GitHub repository: https://github.com/jixishi/dsh-adapter-qq