dsh-qqbot

A QQ Bot plugin for deepseek-harness (dsh), connecting DeepSeek AI assistants to QQ private and group chats.

简体中文 | English

Scan to join the QQ group / channel

Architecture

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

Installation

Method 1: Desktop install (recommended)

No command line needed — everything happens inside the app:

1. Install: click "Plugins" in the left sidebar → "Add plugin" → enter @tencent-connect/dsh-qqbot@latest → install and start now

1. Connect: avatar at the bottom-left → Settings → "QQ Bots" → scan the QR code with mobile QQ

Credentials are saved automatically after the scan; later launches need no re-scan.

Method 2: Manual

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

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

On first launch, the plugin detects missing credentials and automatically starts the QR flow: a QR code is printed in the terminal → scan it with the QQ mobile app → credentials are saved to the profile, so subsequent launches require no re-scan.

In environments without the in-app binding page (pure CLI), set QQBOT_BIND_OPEN_BROWSER=1 to additionally open a browser QR page as a fallback.

Note: Upgrade to 0.4.0 or later for browser-link scanning, which avoids QR code misalignment in some terminals.

Method 3: Local path

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

# Add to a profile (local path)
npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot

# Start
export QQBOT_APPID="yourAppID" QQBOT_SECRET="yourAppSecret"
npx @deepseek-ai/dsh --profile qqbot

Method 4: --patch dev mode

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

Configuration

Access control (access)

Rich media (media)

Vision (vision)

File sending (sendFile)

Built-in Commands

Core Modules

src/
├── index.ts                    # Cordis plugin entry (async apply)
├── config.ts                   # Config schema
├── types.ts                    # Global types
├── setup.ts                    # Credential binding (QR)
├── gateway/                    # Gateway assembly
│   ├── bootstrap.ts            # Startup wiring (session/event listeners, etc.)
│   └── middleware-setup.ts     # Middleware chain config
├── transport/                  # Transport layer
│   ├── inbound.ts              # QQ inbound message → agent.followup()
│   ├── outbound.ts             # session/event → QQ sendMarkdown
│   ├── outbound-buffer.ts      # Streaming buffer
│   ├── streaming-writer.ts     # Streaming writer
│   ├── reply-target.ts         # Reply target resolution
│   ├── msgid-cache.ts          # Passive reply msgid cache
│   ├── reply-limiter.ts        # Passive reply rate limiter
│   ├── tool-presenter.ts       # Tool-call presentation
│   └── chunker.ts              # Markdown chunking
├── session/                    # Session management
│   ├── session-manager.ts      # QQ peer → Agent mapping
│   └── idle-evictor.ts         # Idle eviction
├── model/                      # Model routing
│   ├── model-resolver.ts       # Route resolution
│   ├── prefs-store.ts          # Per-peer preference persistence
│   └── settings-reader.ts      # settings.yaml read-only
├── features/                   # Interaction features
│   ├── question-channel.ts     # ask_user_question Q&A channel
│   ├── approval-channel.ts     # approval confirmation channel
│   └── answer-parser.ts        # Answer parsing
├── media/                      # Media
│   ├── vision-tool.ts          # Image vision understanding
│   ├── send-file-tool.ts       # Send local files
│   └── media-cleaner.ts        # Media TTL cleanup
├── middleware/                 # Middleware
│   ├── question-answer.ts      # Q&A answer handling
│   └── attachment.ts           # Attachment handling
├── shared/                     # Shared utilities
│   ├── utils.ts                # Common helpers
│   ├── scope.ts                # scope/peer extraction
│   └── send-helper.ts          # Chunked send
└── commands/                   # Slash commands

Session Routing

sessionKey: qqbot:${appId}:${scope}:${peerId}; a UUID session id is minted for new sessions and persisted to model-prefs.json, resuming by the persisted id after restarts; pre-0.6 sessions keep their originally derived ids.

Resolution strategy: in-process reuse → persisted resume → fresh create.

Design Principles

• Pure Cordis plugin — follows the dsh "Plugins, not loop changes" principle
• Declarative dependencies — inject = ['agents'], no direct coupling to other plugins
• Session isolation — one independent Agent per QQ direct user / group
• Preset support — mount presets (toolkits, prompts, etc.) via the agent-presets service
• Idle eviction — auto-dispose Agents on timeout to prevent memory leaks
• Markdown output — replies sent as Markdown with code-block/table-aware chunking
• Image understanding — supports qqbot_describe_image vision to analyze images sent by users
• File sending — supports qqbot_send_file to send local files to users (path allowlist enabled by default)
• Question interaction — supports ask_user_question with inline keyboard buttons (mutually exclusive) or numbered replies, one question at a time with timeout
• Approval confirmation — supports approval/request to ask for user confirmation on critical actions via allow/deny buttons

Local Development

# Install dependencies
pnpm install

# Build
pnpm build

# Dev mode (watch)
pnpm dev

# Debug via --patch
export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

License

MIT