前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”，通过协议驱动将各类消息平台接入 Agent 生态。dsh-qqbot 是基于 deepseek-harness (dsh) 的 QQ Bot IM 插件增强 fork。它将 QQ 消息平台作为 dsh agent 的前端协议驱动，并提供了一套基于官方 Bot API 的接入方案，解决了第三方协议端可能存在的封号风险与稳定性问题，同时补全了富媒体交互、群管理及扩展开发能力。
功能概览¶
该插件具备以下核心能力：
- 协议驱动：基于 deepseek-harness (dsh) 的 QQ Bot IM 插件增强 fork，将 QQ 消息平台作为 dsh agent 的前端协议驱动。
- 官方 Bot API：使用官方 Bot API（非模拟协议），无封号风险。
- 表情包图库：支持自动去重、分类、检索与挑图。
- 富媒体收发：支持图片、语音、视频、文件等多种媒体形式的收发。
- 定时任务：支持预设定时任务，让 AI 按时在群内发言。
- 多实例人格：支持多账号独立运行，每个实例拥有独立的 AppID、人格设定与图库。
- 好感度系统：具备熟识度与好感度双维度计算，影响 AI 的主动发言意愿。
- 可视化设置面板：提供悬浮球 dock 进行设置，支持聊天记录回放与富媒体查看。
- 群管理：支持入群审批、禁言、查成员。
- 扩展系统：提供 5 套扩展点，支持自定义工具、命令、交互逻辑与消息处理。
- 踢人功能：通过自有 QQ 号配合群官网接口实现（功能受限，需依赖自有号）。
安装与启用¶
安装前需确认已安装 DeepSeek Harness 并处于 web profile 环境中，因为可视化设置面板（悬浮球 dock）仅在 web profile 下生效。
- 执行以下命令安装插件：
npx @deepseek-ai/dsh plugin --profile web add @zaofan/dsh-qqbot
- 安装完成后，在
dsh web的设置中会出现「QQ 机器人」面板，点击即可进行配置。 - 若从 GitHub 源码直接安装，需确保仓库根目录存在编译产物
dist/（推荐直接使用 npm 发布版）。
核心能力¶
协议接入与安全性¶
插件不走模拟协议端（如 NapCat），而是直接使用腾讯官方 QQ 机器人开放平台接口。这种方式不依赖你的个人 QQ 号登录，账号安全风险极低，且资源占用极小（仅需 HTTP + WebSocket）。由于功能受限于官方接口，部分高级功能（如踢人）需通过插件提供的特殊方式补充。
可视化设置与群管理¶
安装到 web profile 后，界面右下角会出现悬浮球 dock。通过该面板可以进行以下操作：
* 群管理：处理入群审批、禁言、查看成员列表。踢人功能需使用你自己的 QQ 号通过群官网接口实现，扫码一次后可长期免扫。
* 聊天回放：像普通 QQ 一样查看群聊与私聊记录，支持放大图片、播放本地视频、将 SILK 语音转为 MP3。
* 发送消息：在面板聊天框中直接发送文字、插图或文件。
扩展系统¶
插件内置了扩展系统，允许在不修改插件源码的情况下添加自定义功能。系统提供 5 套扩展点：
1. tools：供 AI 在思考过程中主动调用的工具。
2. commands：用户触发特定命令时执行的逻辑。
3. botplay：处理卡片互动按钮点击事件。
4. hooks：插件启动时执行的任务或监听器。
5. inbound：接管每一条消息的命运（如过滤、改写、静默处理）。
表情包与智能互动¶
- 图库管理：机器人会自动将群内接收到的图片存入图库，支持去重与分类。
- 自动回复：用户发送“发个开心点的图”等指令，AI 会自动检索图库并挑选合适的表情包回复。
- 好感度机制：系统通过小模型分析 AI 的内心想法与实际发言，计算熟识度与好感度。好感度仅影响 AI 主动发言的频率，负好感也不会导致机器人冷落或攻击群成员。
部署注意¶
- Profile 限制：必须安装到
webprofile 才能使用可视化设置面板。若安装到其他 profile，将无法看到悬浮球和设置页。 - 踢人功能：QQ 官方未开放踢人接口，插件通过“自有 QQ 号 + 群官网”实现此功能。这意味着你需要用自己的号去管理群，且需确保该账号拥有管理权限。
- 安卓部署：在安卓 Termux 等环境中，若系统不支持 ONNX 运行时，建议在设置中勾选“程序兜底（不依赖小模型）”。
- 隐私安全：插件不包含任何机器人凭据（AppID/Secret）与隐私数据，所有敏感信息由用户自行管理。
总结¶
dsh-qqbot 为 DeepSeek Harness 提供了安全、低成本的 QQ 机器人接入方案。它通过官方 API 保证了稳定性，通过扩展系统提供了灵活的开发空间，通过可视化面板降低了使用门槛。适合需要在 QQ 群组中部署 AI 助手、进行群管理或开发自定义互动功能的开发者。
