前言¶
DeepSeek Harness（DSH）的核心设计理念是「一切皆插件」，通过插件化扩展能力来构建本地智能体环境。接入 QQ 官方机器人通常涉及复杂的 WebSocket 连接维护和回调配置，普通开发者难以直接维护。dsh-QQbot 插件封装了官方 SDK 的连接逻辑，将其接入本机 DSH，从而让 AI 能够直接在 QQ 群聊或单聊中工作。
是什么¶
dsh-QQbot 是一个客户端插件，由 master1Sun 维护。它利用 QQ 官方机器人的 WebSocket 长连接模式，将消息流转发到本地 DSH 的会话中。通过 DSH 的 AI 能力处理后，回复再由插件分发回 QQ。该插件支持多机器人独立运行、免公网接入以及丰富的消息处理功能。
核心功能¶
- 多机器人：通过
bots.json作为唯一事实来源管理机器人。每个机器人拥有独立的凭据和配置，可同时在线，所有回复均由来源机器人发出。 - 免公网接入：利用官方 SDK 主动外连 QQ 网关的特性，插件本身无需公网 IP、域名或回调配置即可运行。
- 消息响应：
- 群聊：@ 机器人直接回复（附带最近 10 条上下文）；未 @ 消息经价值评分过滤后才插话。
- 单聊：直接建立会话。
- 会话与记忆：同一群聊或单聊复用会话，支持
/new重开会话、/记忆和/清空记忆进行长期记忆管理。 - 多模态与语音：支持图片、文件、语音入上下文；语音转写支持五档；支持 TTS 语音回复和「正在输入」状态。
- 定时消息：支持
/定时命令，调度精度约 30 秒。支持每天定时、间隔重复以及 AI 现场生成内容的mode=ai模式。 - 群管理：内置敏感词撤回、
/广播、入群欢迎语、表情撤回以及敏感操作审批功能。 - AI 工具：提供
qqbot_schedule_*、qqbot_send_message、qqbot_memory_*等工具函数，允许在对话中直接调用这些能力。 - 安全与可靠：包含回复净化、媒体 SSRF 防护、本地路径白名单、主动消息每日配额控制以及消息本地归档。
- 设置界面：集成在 DSH 的设置页面中，支持扫码或手动添加机器人，行为配置热生效。
安装与启用¶
插件需要安装在 DSH 的特定配置文件（profile）中。确保你在正确的 profile 目录下执行安装命令。
dsh plugin --profile web add <本目录或 git 地址>
安装完成后，插件依赖 @deepseek-ai/dsh-webhook 提供的 ctx.webhookRuntime。若该依赖不可用，插件会降级运行（不创建会话），此时可通过设置页与 /status 查看状态。
典型用法¶
- 准备环境：在 QQ 开放平台创建机器人，获取
appId和appSecret。配置出口 IP 白名单，并将群设置中的「可获取的群聊消息范围」设为全部。 - 添加机器人：打开 DSH 设置，进入「QQ 机器人」页面。通过扫码或手动填写信息添加机器人，保存后立即生效。
- 开始交互：将机器人拉入群聊或添加为好友。直接 @ 它说话，或在私聊中对话即可。
已知边界¶
- 定时消息精度：调度精度为 30 秒，且仅在进程运行时触发，进程停止时不会触发。
- 群聊回复限制：被动回复窗口限制为 5 分钟 / 5 次。对于超长任务，可能导致发送失败（可开启
proactiveFallback消耗主动配额）。 - 上下文限制：群聊历史上下文只回放文本内容，不包含历史附件中的图片或文件。
- 进程可靠性：
webhookRuntime采用进程内 fire-and-forget 模式。若 DSH 进程崩溃，未入会话的消息会丢失。
结语¶
该插件适合需要在本地运行 DSH 并希望直接在 QQ 生态中使用的开发者。安装前建议检查源码与许可证（MIT）。更多配置细节请参考 GitHub 仓库。
