前言¶

DeepSeek Harness（dsh）把智能体能力封装成可插拔的 Cordis 插件，但多数示例仍围绕终端或 Web 界面。如果你希望同事、用户直接在 QQ 里与 Agent 对话，需要自己处理 QQ Bot API、WebSocket 长连接、消息入站出站，以及每个私聊/群聊的会话隔离。

下面介绍 @tencent-connect/dsh-qqbot：由 tencent-connect 维护的 dsh 客户端插件，把 QQ 私聊与群聊接入 dsh 的 agent loop，凭据可通过扫码绑定，也支持环境变量或配置文件传入。

这是什么¶

@tencent-connect/dsh-qqbot 是面向 deepseek-harness 的 QQ Bot IM 通道插件。消息路径如下：

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

插件遵循 dsh「Plugins, not loop changes」原则：纯 Cordis 插件，通过 inject = ['agents'] 声明依赖，不直接改动 agent loop。当前版本 0.4.0，许可证 MIT，要求 Node.js >= 18。GitHub 仓库约 74 stars。

核心功能¶

消息与会话¶

• 私聊与群聊均可触发 Agent；群聊默认需 @bot（requireMention，默认 true）。
• 每个 QQ 私聊用户或群聊对应独立 Agent，会话 key 为 qqbot:${appId}:${scope}:${peerId}，经 SHA-256 派生 SessionId，进程重启后可恢复。
• 闲置超时（默认 30 分钟）自动 dispose Agent，避免内存泄漏。
• 回复以 Markdown 格式发送，支持代码块/表格感知的文本切分（单条上限默认 4500 字符）。

模型与预设¶

• 默认 LLM 提供商 deepseek-official，模型 deepseek-chat；可通过配置或 /model 命令切换。
• 支持挂载 agent-presets 预设（工具集、prompt 等），/preset 查看或切换，新会话生效。
• 私聊、群聊可分别设置额外 system prompt（directPrompt、groupPrompt）。

内置斜杠命令¶

问答互动¶

支持 dsh 的 ask_user_question：单选生成内联按钮（点一个其余变灰），多选回复编号，逐题推进；单题超时默认 5 分钟（askTimeoutMs）。

安装与启用¶

方式一：npm 安装（推荐）¶

先把插件装进独立 profile，再启动 dsh：

# 安装到 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

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

配置项¶

AppID 与 AppSecret 需在 QQ 开放平台 创建 Bot 后获取，插件对接 QQ Bot API v2。

典型用法¶

1. 按方式一安装并启动，完成扫码绑定。
2. 在 QQ 私聊或群里 @bot 发送问题，Agent 以 Markdown 回复。
3. 长对话用 /compact 压缩历史；切换模型用 /model；重置上下文用 /new。
4. 本地开发时，pnpm dev 监听构建，配合 --patch 调试：

pnpm install
pnpm build
export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

适用场景与注意¶

适合谁

• 已在 dsh 上跑 Agent，希望把同一套能力暴露到 QQ 的团队或个人。
• 需要群聊 @触发、私聊直连、per-peer 模型偏好等 IM 场景特化的部署。

使用前注意

• 插件以当前 dsh 进程的权限运行，Agent 能访问的工作目录、工具、网络范围与 dsh 实例一致。安装前请阅读 源码 与 MIT 许可证，确认符合你的安全策略。
• 群聊默认需 @bot，避免群内每条消息都触发 LLM 调用。
• 社区目录 SkillHub 是独立站点，与 DeepSeek / 幻方无官方从属关系；插件信息以 GitHub 仓库为准。

结尾¶

@tencent-connect/dsh-qqbot 把 QQ WebSocket 消息流接到 dsh 的 agent loop，扫码或环境变量完成凭据配置，私聊与群聊各自维护独立会话。若你正在 dsh 生态里找 QQ 接入方案，可以从 npm 安装命令起步，按需调整模型、preset 与群聊 prompt。

• 目录页：https://www.skillhub.cn/plugins/tencent-connect/dsh-qqbot
• GitHub：https://github.com/tencent-connect/dsh-qqbot