Introduction

DeepSeek Harness（DSH）encapsulates the capabilities of large models into a locally runnable Agent. In common scenarios where an Agent is run locally, it is often necessary to interact with it through IM channels. Integrating with the official QQ bot (q.qq.com) typically involves handling persistent WebSocket connections, message routing, session isolation, and complex permission approval logic.

The dsh-im-qq plugin solves the above problems. It acts as an intermediate layer that converts QQ message streams into standard DSH events, and sends the Agent’s reasoning results back to QQ in reverse. With this plugin, users can invoke the full capabilities of Harness—tool calls, memory, subagents, etc.—directly in QQ direct messages, group chats, or channels.

Plugin Overview

  • Name: dsh-im-qq
  • Maintainer: 988hj7tczd-oss
  • Core value: Integrates the official QQ bot protocol with DSH, enabling full-featured Agent interaction over IM.
  • License: MIT

Core Features

The plugin implements the following core capabilities:

  1. Message intake: Supports direct messages (C2C), @bot in group chats, and @bot in channels.
  2. Session isolation: Automatically creates an independent session for each user/group, with the message prefix uniformly set to qq:.
  3. Agent capabilities: Full support for tool calls, memory management, subagents, and filesystem operations.
  4. Connection mechanism: Based on persistent WebSocket connections, with support for heartbeats, reconnection (RESUME), and automatic recognition.
  5. Message handling: Supports reply merging, splitting of overly long messages, removal of internal tags, and fallback for errors.
  6. Security and rate limiting: Whitelist mechanism (Fail-closed) and message frequency control.
  7. Approval bridge: Enables approval of high-privilege operations through inline QQ buttons (✅/⭐/❌), with support for revocation via /revoke.
  8. Slash commands: Supports commands such as /help, /ping, /me, /new, /approve, /always, and /revoke.

Installation and Configuration

Installation

Run the installation script in the plugin directory:

./install.sh

After installation is complete, restart harness-desktop.

Configuration

Option A (Recommended): Desktop settings
1. Open Settings → Plugins → Plugin Configuration.
2. Find the QQ Bot card.
3. Fill in AppID and AppSecret, then click Save and Start. The credentials will be written to $DSH_HOME/.credentials.yaml.

Option B (Manual): Edit the configuration file
Edit $DSH_HOME/cordis.patch.yml and add the following configuration block (id must be quoted to prevent YAML from parsing it as a number):

- insert:
    - id: dsh-im-qq
      name: dsh-im-qq
      config:
        id: '你的AppID'
        secret: '你的AppSecret'
        sandbox: true
        transport: 'websocket'
        provider: 'deepseek-official'
        model: 'deepseek-v4-flash'
        agentPreset: 'standard'
        cwd: '~/qq-workspace'
        workspaceIsolation: true
        allowFrom: ['*']
        groupAllowFrom: ['*']
        deliverWindowMs: 900
        textChunkLimit: 4000
        replyPassiveLimit: 4
        approval: true
        slashCommands: true
        debug: false

Usage

  • Direct message: Send a message directly to the bot.
  • Group chat/channel: @bot followed by the message content.
  • Slash commands:
    • /help: View help
    • /ping: Check connection status
    • /me: Send user information
    • /new: Create a new session
    • /approve / /always: Approval-related
    • /revoke: Revoke approval permissions
  • Approval flow: When the Agent needs to perform a high-privilege operation, inline buttons will appear in the QQ message.
    • ✅ Allow once: Temporary authorization.
    • ⭐ Always allow: Permanent authorization (can be revoked using /revoke).
    • ❌ Deny: Reject the request.

Notes and Troubleshooting

1. Bot Type and Test Users (Must Verify)

  • Public vs. private domain: When creating a bot on q.qq.com, you must select a public-domain bot. Private-domain bots cannot call group interfaces and will cause the persistent error 11255.
  • Test users: You must add your QQ number in Test User Management. Messages from users who are not test users will also cause the 11255 error.
  • Sandbox mode: It is recommended to enable sandbox: true first for validation, and switch it to false after the system is stable.

2. Common Error Handling

  • WS Close Code 4009: It is normal for this code to appear in the logs (the QQ server actively disconnects about every 30 minutes); the plugin automatically resumes/reconnects, so no intervention is required.
  • Slow replies / no reply:
    • Enable debug: true to view the logs.
    • Check whether the inbound pipeline was rejected by ACL.
    • Check whether the Agent reported an error (fallback prompt text will be provided).
  • Reply with URL failed to send: The QQ platform requires URLs in messages to be pre-added in the backend Message URL Configuration; otherwise the entire message fails to be sent.
  • Missing credentials: Check whether id was parsed as a number (it must be quoted) and whether the environment variable pointed to by secretEnv has been exported.
  • Approval buttons unresponsive: Confirm that the platform side has subscribed to button interaction events (intent 1<<26).

3. Proactive Message Quota

The official QQ limit is 4 proactive messages per user/per group per month. The plugin prioritizes passive replies (within the validity period of msg_id) by default, so normal conversations do not consume quota. Only when the reply length exceeds the passive limit (default 4 per message) does it switch to proactive messages that consume quota. If you encounter the 50015014 error, it means rate limiting has been triggered. The plugin implements exponential backoff retry, but high-frequency proactive pushes may still be limited.

4. Known Boundaries

  • Images/streaming/Typing: Configuration items are reserved by the interface, but the code is not yet implemented (P4/P5 level).
  • Webhook: The official long-term direction is Webhook (requires public HTTPS + IP whitelist). The current architecture has abstracted a dual mode; in the future, only platform/transport/webhook.js needs to be implemented to switch.