Architecture

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

Installation

Option 1: Manual execution

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

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

On first launch, the plugin detects missing credentials and auto-enters the QR-code onboarding flow: terminal prints QR → scan with mobile QQ to bind → credentials are auto-saved to profile; no re-scan needed on later starts.

Tip: Upgrade to 0.4.0+ before scanning. Supports opening the link in a browser, avoiding QR code misalignment in some terminals.

Option 2: Local path installation

# 构建
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

Option 3: --patch development mode

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

Configuration

Config	Type	Default	Description
appId	string	Required	QQ Bot AppID (or via the QQBOT_APPID environment variable)
appSecret	string	Required	QQ Bot AppSecret (or via the QQBOT_SECRET environment variable)
provider	string	deepseek-official	LLM provider name
model	string	deepseek-chat	Model name
preset	string	-	Agent preset id
cwd	string	process.cwd()	Agent working directory
requireMention	boolean	true	Whether group chats require @bot to trigger
groupPrompt	string	-	Additional system prompt for group chats
directPrompt	string	-	Additional system prompt for direct chats
textChunkLimit	number	4500	Maximum character count per message
streaming	boolean	true	Whether to enable streaming output (never enabled in group chats)
sessionIdleTimeout	number	1800000	Session idle timeout (ms), default 30 minutes
processingTimeoutMs	number	1800000	Processing timeout (ms); aborts the current LLM call when exceeded
maxQueue	number	20	Maximum concurrency queue length
historyLimit	number	10	Number of group history buffer entries
askTimeoutMs	number	300000	Pending question timeout (ms), default 5 minutes (ask_user_question)
showToolResults	boolean	false	Whether to show successful tool call results (errors are always shown)
debug	boolean	false	Debug mode

Access Control (access)

Config	Type	Default	Description
access.c2cMode	open/allowlist/disabled	open	Direct chat access mode
access.c2cAllow	string[]	[]	Direct chat allowlist (user openid)
access.groupMode	open/allowlist/disabled	open	Group chat access mode
access.groupAllow	string[]	[]	Group chat allowlist (group openid)

Rich Media Understanding (media)

Config	Type	Default	Description
media.enabled	boolean	true	Whether to enable rich media understanding (image/video download + tool analysis)
media.maxMB	number	200	Maximum download size for rich media (MB)
media.ttlHours	number	24	Lifetime of rich media (hours); 0 = never expires

Vision Understanding (vision)

Config	Type	Default	Description
vision.enabled	boolean	false	Whether to enable vision understanding (qqbot_describe_image tool)
vision.provider	string	-	Vision model provider (e.g. pi-ai)
vision.model	string	-	Vision model id (e.g. qwen-vl-max)
vision.maxBytes	number	10MB	Maximum image size in bytes
vision.maxTokens	number	1024	Maximum output tokens
vision.timeoutMs	number	120000	Vision call timeout (ms)

Sending Attachments (sendFile)

Config	Type	Default	Description
sendFile.restrictPaths	boolean	true	Whether to enforce the path allowlist (media + cwd + extraRoots only)
sendFile.extraRoots	string[]	[]	Additional root directories allowed for access

Built-in Commands

Command	Description
/new (aliases /reset /clear)	Start a new session (clears context)
/compact	Compact session history (summary replaces older records, context is preserved)
/model	View or switch model
/preset	View or switch agent preset (takes effect in new sessions)
/stop	Abort the current generation
/bot-ping	Network latency check (returns transfer and processing time)
/bot-version	View version information
/bot-status	View the current session status
/bot-help	View all commands

Core Modules

src/
├── index.ts                    # Cordis 插件入口（async apply）
├── config.ts                   # 配置 Schema
├── types.ts                    # 全局类型定义
├── setup.ts                    # 凭据绑定（扫码）
├── gateway/                    # 网关装配
│   ├── bootstrap.ts            # 启动装配（监听 session/event 等）
│   └── middleware-setup.ts     # 中间件链配置
├── transport/                  # 传输层
│   ├── inbound.ts              # QQ 入站消息 → agent.followup()
│   ├── outbound.ts             # session/event → QQ sendMarkdown
│   ├── outbound-buffer.ts      # 流式缓冲
│   ├── streaming-writer.ts     # 流式写入
│   ├── reply-target.ts         # 回复目标解析
│   ├── msgid-cache.ts          # 被动回复 msgid 缓存
│   ├── reply-limiter.ts        # 被动回复限流
│   ├── tool-presenter.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 只读
├── features/                   # 交互特性
│   ├── question-channel.ts     # ask_user_question 问答通道
│   ├── approval-channel.ts     # approval 审批确认通道
│   └── answer-parser.ts        # 答案解析
├── media/                      # 多媒体
│   ├── vision-tool.ts          # 图片视觉理解
│   ├── send-file-tool.ts       # 发送本地文件
│   └── media-cleaner.ts        # 媒体 TTL 清理
├── middleware/                 # 中间件
│   ├── question-answer.ts      # 问答答案处理
│   └── attachment.ts           # 附件处理
├── shared/                     # 共享工具
│   ├── utils.ts                # 通用函数
│   ├── scope.ts                # scope/peer 提取
│   └── send-helper.ts          # 分块发送
└── commands/                   # 斜杠命令

Session Routing

sessionKey: qqbot:${appId}:${scope}:${peerId}, with the SessionId deterministically derived via SHA-256, so it can be restored after a restart.

Resolution: in-process reuse → persistent restore → create new.

Design Principles

• Pure Cordis plugin — follows the dsh "Plugins, not loop changes" principle
• Declarative dependencies — inject = ['agents'], no direct coupling with other plugins
• Session isolation — each QQ direct-chat user/group chat gets its own independent Agent
• Preset support — presets (toolsets, prompts, etc.) can be attached via the agent-presets service
• Idle reclamation — Agents are automatically disposed on timeout to prevent memory leaks
• Markdown output — replies are sent in Markdown format, with chunking aware of code blocks/tables
• Image understanding — supports qqbot_describe_image vision understanding to analyze images sent by users
• Attachment sending — supports qqbot_send_file to send local files to the user (path allowlist enabled by default)
• Q&A interaction — supports ask_user_question; single choice generates inline buttons (clicking one grays out the rest), multi-choice replies with numbers, advancing question by question with per-question timeouts
• Operation confirmation — supports approval/request; critical operations ask the user for confirmation via "allow/deny" buttons

Local Development

# 安装依赖
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