Preface

When building a DeepSeek Harness (DSH) channel plugin, a common issue is that the web side is already functional, but the QQ side lacks a directly runnable channel plugin. Developing your own Gateway integration, message handling, file management, approval workflows, and session persistence involves significant effort.

This guide introduces sliverp/DeepSeek-harness-qqbot, an out-of-tree DeepSeek Harness channel plugin. It uses the official @tencent-connect/qqbot-nodejs Gateway client to integrate QQ Bots with persistent Harness agents, covering C2C and group chat text, images, files, approvals, and commands.

What This Is

  • Plugin Name: sliverp/DeepSeek-harness-qqbot
  • Maintainer: sliverp
  • License: MIT
  • Purpose: A DSH channel plugin that connects the QQ Bot Gateway to persistent Harness agents.

Core Features

Sessions & Messages

  • C2C and group chat text messages.
  • Each C2C or group chat session corresponds to a persistent Harness session.
  • /new and /reset preserve old history and switch to a new durable session.
  • Inbound PNG, JPEG, WebP, and GIF images are processed as durable Harness attachments.
  • If the selected model does not accept image input, it automatically degrades to text-only.
  • Inbound voice transcription and non-image attachment metadata include temporary QQ download URLs.
  • Outbound supports assistant text, images, and local workspace files.

File Sending

  • Provides a QQ-turn-scoped qq_send_file tool for sending files during the current QQ turn.
  • The tool is restricted to the workspace and performs file size checks.
  • Only accepts regular files within cwd, resolves symbolic links, and rejects files larger than 104,857,600 bytes (100 MiB).

QQ Capabilities

  • QQ Markdown replies are enabled by default; requires QQ Markdown permission, otherwise the QQ API will reject Markdown messages.
  • Supports typing indicators, long reply splitting, session-based ordering, deduplication, send retries, and bounded timeouts.

Approvals & Access Control

  • Operations requiring Harness approval send requester-bound QQ approval messages with one-shot Allow and Reject buttons.
  • Only the QQ user who initiated the current turn can approve or reject.
  • Approval timeout defaults to 120,000 milliseconds; unanswered requests are rejected.
  • Supports fallback to another composed approval channel.
  • C2C and group chat traffic can use open, allowlist, or disabled access policies.
  • Workspaces containing non-public data are recommended to use the allowlist policy; allowed QQ users also gain access to tools provided by the selected agent preset.

DSH Integration

  • Credentials are resolved via the Harness credential service rather than being hardcoded in the plugin configuration.
  • If AppID or AppSecret is not configured, the plugin starts in dormant mode and does not block DSH.
  • Invalid QQ credentials only take the QQ channel offline, not preventing DSH startup.
  • Supports Harness agent-preset composition for tools, prompts, and skills.
  • If the web side has already opened the same live session, the QQ side safely reuses it without creating a second session writer.

Requirements

  • Node.js 22.19 or higher
  • pnpm 10.33.4
  • DeepSeek Harness 0.1.0-rc.7 or higher
  • QQ Bot AppID and AppSecret, with C2C and/or group message events enabled
  • Inline Keyboard permission required for QQ approval buttons
  • package.json declares version 0.1.5

Installation & Activation

Install from GitHub:

pnpm dsh plugin --profile web add github:sliverp/DeepSeek-harness-qqbot

If you have a local checkout, you can install from the path directly:

pnpm dsh plugin --profile web add /absolute/path/to/DeepSeek-harness-qqbot

During development, you can set credentials in the startup environment:

export QQBOT_APP_ID='your-app-id'
export QQBOT_APP_SECRET='your-app-secret'
pnpm dsh --profile web

For long-term operation, place QQBOT_APP_ID in ~/.dsh/.env and save QQBOT_APP_SECRET via the Harness credential settings interface. Do not commit both values to the repository.

You can also adjust access policies or restrictions by overriding the plugin line in ~/.dsh/profiles/web/cordis.patch.yml.

Typical Usage

  1. Start DSH and wait for the log to show QQ Gateway connected.

  2. Send to the bot:

/bot-ping

  1. Send plain text or images. Messages are appended to the durable Harness session of the corresponding conversation, and model replies are sent back to QQ.

  2. Send /new and confirm the bot reports a new session.

  3. Send registered commands, for example:

/goal
/plan
/compact

Other available commands include:

/bot-ping
/bot-image-test
/bot-file-test
/bot-help
/bot-status
/bot-cancel

Use Cases & Notes

Suitable for scenarios where DSH agents need to be used in QQ C2C or group chats, especially for teams that want to reuse persistent sessions, agent presets, file sending, and approval workflows.

Notes:

  • The plugin runs with the current dsh process permissions; review the source code and license before installation.
  • Use the allowlist policy if the workspace contains non-public data.
  • Disable Markdown replies when QQ Markdown permission is not enabled to avoid QQ API message rejection.
  • qq_send_file only sends regular files within cwd and is subject to a 100 MiB limit.
  • Approval buttons depend on Inline Keyboard permission; timeout defaults to 120,000 milliseconds.

Conclusion

sliverp/DeepSeek-harness-qqbot connects QQ Bot’s messaging, sessions, files, and approvals to DSH’s persistent agent sessions, making it a suitable starting point for a QQ channel plugin.

GitHub: https://github.com/sliverp/DeepSeek-harness-qqbot