dsh-qqbot

One-Sentence Overview

dsh-qqbot connects a QQ bot to DeepSeek Harness: turning the QQ messaging platform into a frontend channel for dsh agents. Just @ the bot in private or group chats to converse, send files, and invoke agent tools. Scan a QR code on first launch to bind QQ credentials; each chat window holds its own independent session.

Core Capabilities

• Private & Group Chat: Private chats always respond; group chats trigger only when @bot by default, with an option to disable the gate and respond to all messages
• QR Code Credential Binding: On first launch, the terminal prints a QR code; scan it with QQ mobile to obtain AppID/AppSecret and automatically write to profile
• Attachment Handling: Images include size descriptions automatically; voice messages are transcribed to text; file attachments are downloaded locally and the model is prompted to read them via path
• Markdown Streaming Replies: Private chats push replies paragraph by paragraph (streaming) by default; group chats send entire paragraphs at once due to QQ protocol limitations; long replies are split by code block/table awareness
• Independent Sessions: Each QQ user/group maps to a dsh agent; sessions are persisted via SHA-256 derived sessionIds and can be restored after restart
• Built-in Slash Commands + Access Control: /new /compact /model /stop plus /bot-ping /bot-version /bot-status /bot-help, with openid/groupOpenid whitelist support to allow or disable private and group chats

Technical Implementation

• Language: TypeScript (ESM, tsconfig compiles to dist/, main points to dist/index.js)
• Key Dependencies: @tencent-connect/qqbot-nodejs (QQ OpenAPI + WebSocket client + middleware chain), @tencent-connect/qqbot-connector (QR code binding), js-yaml (cordis.patch.yml read/write)
• Architecture Pattern: Pure Cordis plugin, inject = ['agents']; entry apply() runs credential guidance then calls bootstrapGateway() to assemble SDK middleware chain (error handling → filtering → access control → group history buffer → @ gate → cleaning → rate limiting → slash commands → concurrent serialization → input state → quoting → attachments → envelope), and routes dsh outbound events back to QQ via ctx.on('session/event', ...)
• Entry File: src/index.ts (Cordis plugin entry, includes credential guidance); gateway assembly in src/gateway/bootstrap.ts

Use Cases

Ideal for users who want to interact with DeepSeek Harness via QQ: ask questions in QQ daily, let the agent read files, write code, or run commands—no need to open the web console. Can also serve as a team assistant in QQ groups, with each person's conversation context isolated from others. Resources are automatically released after 30 minutes of inactivity.

Prerequisites and Compatibility

Installation

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

Configuration Options

The plugin declares fields via Schemastery Schema (src/config.ts:56); the "Description" column in the table below is in plain language. Default values work for normal scenarios after installation; regular users don't need to adjust.

FAQ

Q: What do I need to do on first launch?

A: If AppID/AppSecret is not detected on startup, the plugin prints a QR code in the terminal; scan to complete binding. Credentials are automatically written to the current profile's cordis.patch.yml, no need to scan again next time. When QR code is misaligned, use the browser link output by version 0.4.0+ instead.

Q: Do I need to @bot in group chats for it to respond?

A: requireMention is enabled by default; group chats only trigger responses when @bot. Set to false to respond to any message. Private chats are unaffected by this switch and always respond.

Q: Will conversation context leak between different QQ groups?

A: No. Each QQ private chat user and each QQ group has an independent sessionKey. sessionId is deterministically derived via SHA-256 from qqbot:${appId}:${scope}:${peerId}, restorable after restart. Dialogues between different groups/people are isolated.

Q: Does it support images, voice, and files?

A: Images include size descriptions in context. Voice messages prefer ASR-transcribed text; if the model can't access audio, the original link is attached as fallback. File attachments are automatically downloaded to ${cwd}/.qqbot/${messageId}/ with path prompts, then the model reads them via tools. File downloads include HTTPS + SSRF protection and 20MB size limits.

Q: How to enable streaming replies?

A: Streaming is on by default for private chats (streaming: true), replies push paragraph by paragraph. Group chats never stream due to QQ group message API limitations, only sending entire Markdown blocks. If global streaming is disabled, private chats also switch to sending complete replies at once.

Q: How to switch models?

A: Send /model in chat to list available models (click to switch), or /model provider/model to specify a route. Preferences are persisted per sessionKey to ~/.dsh-qqbot/model-prefs.json, so the same person/group retains settings on next restart.

Q: How to completely reset the current conversation?

A: Send /new (alias /reset, /clear) to discard the current session and start a new one. To preserve context but compress history, send /compact (requires host with compaction service). Long idle sessions over 30 minutes are auto-disposed and restored on next message.

Q: "Credentials not configured" error—now what?

A: QR scanning automatically writes to profile. In dev mode (loading source via cordis.dev.yml), the profile directory can't be located, so the plugin prints export/set environment variable instructions to terminal. For manual configuration, write appId and appSecret to the corresponding plugin entry in the profile's cordis.patch.yml.

Learning Curve

Beginner — scan QR code to bind QQ credentials, start chatting in private messages immediately. Advanced users can adjust group gating, whitelists, Markdown split thresholds, and other parameters as needed.

Known Issues and Limitations

• Model preferences are persisted per sessionKey to ~/.dsh-qqbot/model-prefs.json; deleting this file resets all preferences. No UI-based batch cleanup currently available.
• Group chat streaming is always disabled: QQ group message API doesn't support incremental updates, so group chats only send entire Markdown blocks, with single-message limits controlled by textChunkLimit (default 4500).
• File attachment downloads have 20MB size limits and HTTPS + SSRF protection. When either rule is triggered, download is skipped and only path description is retained; oversized files need to be manually placed in the agent's working directory.
• Sessions idle for 30 minutes are automatically disposed; the next message triggers a "resume → create" flow. If the host lacks sessions service, resume fails and falls back to creating a brand new session (history lost).
• Model switching uses fork + rebuild strategy. If sessions.fork service doesn't exist at the lower level, it falls back to disposing old session and creating new one with new model (equivalent to /new, context lost).
• /compact command requires host to have agent-presets or compaction service loaded; returns "compression capability unavailable" when not loaded.
• In streaming replies, both assistant/chunk and assistant/message enter the buffer. If turn/end ends abnormally mid-stream,底层错误码 like STREAM_CLOSED are silently ignored (won't appear in user messages).

基于 deepseek-harness (dsh) 的 QQ Bot IM 插件，将 QQ 消息平台作为 dsh agent 的前端协议驱动。

中文 | English

架构

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

安装

方式一：手动执行

# 安装到 profile
npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot

# 启动
npx @deepseek-ai/dsh --profile qqbot

首次启动时，插件检测到凭据未配置会自动进入扫码引导：终端输出二维码 → 手机 QQ 扫码绑定 → 凭据自动保存到 profile，后续启动无需再次扫码。

提示：建议升级至 0.4.0 以上版本扫码，支持点击链接在浏览器打开，避免部分终端二维码渲染错位的问题。

方式二：本地路径安装

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

# 安装到 profile（本地路径）
npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot

# 启动
export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh --profile qqbot

方式三：--patch 开发模式

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

配置项

内置命令

核心模块

src/
├── index.ts                    # Cordis 插件入口（async apply）
├── config.ts                   # 配置 Schema
├── types.ts                    # 全局类型定义
├── setup.ts                    # 凭据绑定（扫码）
├── transport/                  # 传输层
│   ├── inbound.ts              # QQ 入站消息 → agent.followup()
│   ├── outbound.ts             # session/event → QQ sendMarkdown
│   ├── outbound-buffer.ts      # 流式缓冲
│   └── chunker.ts              # Markdown 文本切分
├── session/                    # 会话管理层
│   ├── session-manager.ts      # QQ peer → Agent 映射
│   └── idle-evictor.ts         # 闲置回收
├── model/                      # 模型路由层
│   ├── model-resolver.ts       # 路由解析
│   ├── prefs-store.ts          # per-peer 偏好持久化
│   └── settings-reader.ts      # settings.yaml 只读
├── shared/                     # 共享工具
│   ├── utils.ts                # 通用函数
│   ├── scope.ts                # scope/peer 提取
│   └── send-helper.ts          # 分块发送
├── commands/                   # 斜杠命令
└── typings/                    # 外部模块声明

会话路由

sessionKey: qqbot:${appId}:${scope}:${peerId}，由 SHA-256 确定性派生 SessionId，重启后可恢复。

解析策略：进程内复用 → 持久化恢复 → 全新创建。

设计原则

• 纯 Cordis 插件 — 遵循 dsh "Plugins, not loop changes" 原则
• 声明式依赖 — inject = ['agents']，不直接耦合其他插件
• 会话隔离 — 每个 QQ 私聊用户/群聊各一个独立 Agent
• Preset 支持 — 可通过 agent-presets 服务挂载预设（工具集、prompt 等）
• 闲置回收 — 超时自动 dispose Agent，防止内存泄漏
• Markdown 输出 — 回复以 Markdown 格式发送，支持代码块/表格感知切分

本地开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 开发模式（watch）
pnpm dev

# 用 --patch 方式调试
export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

License

MIT