前言¶

在 DSH 里做群聊或私聊机器人，常见做法是另起服务、记端口，再和 Harness 的 LLM 配置对在一起。维护凭证、预算和会话数据时，往往还要自己拆目录、写脚本。easy-qqbot 由维护者 lixian292 发布，归类为模型推理相关插件，目标是把 QQ 接入、控制台和用量管理收进一个 DSH 插件包：装好后左侧栏有入口，配置与数据落在插件目录的 data/ 下。

下面按定位、能力、安装与典型用法说明；事实依据为项目 README 与 package.json（版本 0.1.0，MIT 许可证）。

这是什么¶

easy-qqbot 是「简洁易用的 DeepSeek Harness QQ 机器人插件」。它通过 QQ 机器人开放平台的 AppID / AppSecret 建立 WebSocket 长连接，在 DSH 进程内完成消息收发、模型调用与后台管理；不依赖改 DSH profile 文件即可完成基础安装。

• 目录页：SkillHub 插件页
• 源码与文档：GitHub lixian292/easy-qqbot

核心功能¶

README 中列出的能力如下（均已写在项目文档中，此处做归纳）：

1. 预算控制：记录每次模型调用的 token 与费用；支持日 / 月 / 单会话 token 限额、每日调用次数与超限冷却；控制台可看用量与会话明细。
2. QQ 官方机器人：文本与富媒体收发，鉴权、心跳、断线重连与 Resume；被动回复窗口超时后可转主动消息。
3. 长期记忆与上下文压缩：会话历史（JSONL）、滚动摘要、定期抽取的长期事实与用户画像；上下文超过阈值时压缩旧消息以控制长度与成本。
4. 个性化：全局人设及按会话、按用户覆盖模型、温度、记忆与压缩开关。
5. 图片理解（可选）：配置 OpenAI 兼容视觉接口后，入站图片先转中文描述再进入对话；未配置时仅为尺寸与类型占位。
6. 表情包系统：目录批量导入、页面上传或聊天自动抓取；打标签与描述后进入正式库，聊天中可按标签回复或由模型按 [[sticker: 标签]] 挑图。
7. 管理后台：概览、配置、表情包、预算、会话、人员、日志共七个页面；可从 DSH 侧栏打开，也可浏览器访问 /qqbot/。

运行时第三方依赖为零，使用 Node 内置模块与 DSH 提供的 ctx.llm、webServer 等服务。

环境与安装¶

前置要求¶

• DeepSeek Harness 已安装并运行，版本要求 >= 0.2.1-rc.2。
• Node.js：^22.19.0 || >= 24.0.0。
• QQ 机器人开放平台 应用（AppID、AppSecret），机器人已加入目标群或允许私聊。

安装命令¶

在 DSH 对话中让 Agent 执行，或调用插件管理工具（README 推荐方式）：

plugin_manager install_bundle https://github.com/lixian292/easy-qqbot

安装成功应看到 application: applied 或 restart-required。安装或更新后请完整重启 DSH 一次，以避免客户端 bundle 与引导缓存不一致导致的 web boot 报错。

插件以当前 DSH 进程权限运行。安装前请自行查阅仓库源码与 MIT 许可证，并确认你愿意把 QQ 凭证与配置保存在本机插件目录中。

配置 QQ 与连通性测试¶

1. 打开 DSH 左侧 QQ 机器人 →「打开完整控制台」。
2. 在「配置 → QQ 接入」填写 AppID、AppSecret 并保存（会自动重连）。
3. 在「概览」执行「测试 QQ 凭证」与「测试 LLM」，两项通过后再用于群聊或私聊。

可选：在「配置 → 视觉模型（可选）」启用图片理解，填写 OpenAI 兼容的 API Base URL、API Key 与模型名；视觉调用费用不计入插件预算统计。

典型用法¶

开始对话¶

私聊机器人，或在群里 @机器人 发消息。首次使用前可在「配置 → 人设」调整名字与说话风格。

批量导入表情包¶

把图片放入插件目录下的 import/（支持子目录），在控制台「表情包 → 扫描 import 目录 → 导入」。也可用命令行（README 示例）：

node tools/sticker-import.mjs --tags "无语,敷衍"

在「表情包」页为卡片填写标签与描述，将条目转为正式库后，模型回复与 #表情 命令才会使用这些图。聊天中可发送：

#表情 无语

QQ 内常用命令¶

管理员相关命令（如 #状态）通过「配置 → 命令与管理员」的 adminOpenids 或群主识别配置。

仅用浏览器访问控制台¶

若不开 DSH 前端，可在本机浏览器打开：

http://127.0.0.1:<DSH Web 端口>/qqbot/

功能与内嵌控制台一致。

数据位置与注意点¶

配置与运行数据均在插件目录 data/，含 config.json（含 AppSecret 与可选视觉 API Key）、budget/、chats/、stickers/、logs/ 等。.gitignore 已忽略 data/，请勿将密钥提交到版本库。管理接口绑定本机 DSH Web 服务，除同源请求外拒绝访问。

群聊被动回复窗口为 5 分钟、私聊 60 分钟，过期会转主动消息（受每日上限约束）。若侧栏没有「QQ 机器人」，多半需完整重启 DSH 而非仅刷新页面。

结尾¶

easy-qqbot 把 QQ 接入、LLM 对话、预算、记忆、表情包与管理台收进单一插件目录，适合已在 DSH 上跑模型、又需要 QQ 官方机器人通道的开发者。进一步细节见仓库 README 与 docs/ 下的架构与开发文档。

• 社区目录：https://www.skillhub.cn/plugins/lixian292/easy-qqbot
• GitHub：https://github.com/lixian292/easy-qqbot