TRSS-Yunzai QQBot Plugin

文件	最后提交记录	最后更新时间
Model	优化召回相关，和qbot设置账号	4 天前
YePanel	1 Signed-off-by: ikun250 <8911239+ikun25000@user.noreply.gitee.com>	2 个月前
resources	删除文件 resources/script/.keep	2 个月前
.eslintrc.cjs	1 1 Signed-off-by: ikun250 <8911239+ikun25000@user.noreply.gitee.com>	2 个月前
.gitignore	1 1 Signed-off-by: ikun250 <8911239+ikun25000@user.noreply.gitee.com>	2 个月前
LICENSE	add LICENSE. Signed-off-by: ikun250 <8911239+ikun25000@user.noreply.gitee.com>	2 个月前
README.md	更新README.md	5 天前
button.html	新增破冰/邀请功能，增强错误处理与事件补丁，优化存储配置	6 天前
index.js	优化部分代码，新增免费兜底COS	2 天前
package.json	。。 Signed-off-by: ikun250 <8911239+ikun25000@user.noreply.gitee.com>	2 个月前

TRSS-Yunzai QQBot Plugin

TRSS-Yunzai QQBot 嘿群主壳插件

Tip

建议使用TRSS原版,此版本为嘿壳版,会在任意时间直接进行罚壳,且不会与TRSS一致

自用人机群主版

新增QQ机器人认证错误处理，破冰，召回功能，发送语音适配官方文档
新增只读错误、取消错误、WebSocket错误检测
新增运行时定时器清理
优化了ws超时的报错重连
toCallback 默认改为 false
新增 forceSilk 配置
新增 icebreaker 和 recall 配置对象
fullMessageDB 改为 level 存储

上传图片用法(需要自己的上传插件加载成功)

// 网络图片
await Bot.uploadImage("https://example.com/a.png")

// 本地图片路径
await Bot.uploadImage("/root/qqbot/data/images/a.png")

// file 协议本地图片
await Bot.uploadImage("file:///root/qqbot/data/images/a.png")

// base64 图片
await Bot.uploadImage("base64://iVBORw0KGgoAAAANSUhEUgAA...")

// 图片 Buffer
const buffer = fs.readFileSync("/root/qqbot/data/images/a.png")
await Bot.uploadImage(buffer)

最简单写法：

const image = await Bot.uploadImage("https://example.com/a.png")

{
  url: "https://上传后的图片地址",
  width: 640,
  height: 360
}

如果要指定某个 QQBot 账号上传：

const image = await Bot[3889000008].uploadImage("https://example.com/a.png")

为了感谢龙虾，新增模拟龙虾在线。优化全量部分内容，优化多机器人配置，修复非本适配器可以触发命令的问题

修复了dau无法统计的bug 修复了原生MD加模板按钮，单发按钮和原生MD的问题修复了点击回调按钮msg_id越权的问题

新增发送嘿壳的文件

原生按钮开放，新增按钮生成器

由于龙虾占用腾讯服务器，增加了ws断线检测和通知，24小时内没有次数了，机器人会被罚壳。已经增加嘿壳的自动重连(应该不会掉线？)

新增掉线检测相关和全量消息相关命令，交互式按钮，请开启原生MD后使用 #qbot帮助查看

// 1. 网络文件，自动文件名
segment.file("https://example.com/file.pdf")

// 2. 网络文件，自定义文件名(利用机制发送嘿壳.jpg，嘿壳.mp3)
segment.file("https://bbs.hycdn.cn/image/2026/01/24/500031/b3fcde82eed9639923cf532d84d6412e.jpg?a=https://嘿壳.jpg","无效参数.jpg")
segment.file("http://game.gtimg.cn/images/up/act/a20170301pre/media/bg.mp3","嘿壳.mp3",1)

// 3. 本地文件，绝对路径
segment.file("/root/yunzai/data/file.pdf", "文件.pdf")

// 4. 本地文件，相对路径
segment.file("./data/file.pdf", "文件.pdf")

// 5. file:// 协议本地文件
segment.file("file:///root/yunzai/data/file.pdf", "文件.pdf")

// 6. 强制分片上传
segment.file({
  file: "https://example.com/large.zip",
  name: "大文件.zip",
  force_chunk: 1
})

// 7. 不强制分片上传
segment.file({
  file: "https://example.com/file.pdf",
  name: "文件.pdf"
})

// 8. Buffer 文件上传
segment.file(buffer, "文件.pdf")

文件撤回示例

基础用法

// 发送文件，20秒后自动撤回
segment.file("https://example.com/file.pdf", "文档.pdf", 0, 20)

// 参数说明：
// 参数1: 文件URL或路径
// 参数2: 文件名
// 参数3: force_chunk (0=自动判断, 1=强制分片上传)
// 参数4: recall_time (撤回时间，单位：秒，0=不撤回)

注意事项

recall_time 为 0 或不填时，不会自动撤回
撤回时间从文件发送成功开始计算
超过2分钟的消息无法撤回（QQ官方限制）
私聊文件会自动使用分片上传，force_chunk 参数无效

账号掉线检测与重连命令

总开关

# 开启掉线检测（总开关，必须先开启此项其他功能才生效）
#QQBot账号掉线检测 开启

# 关闭掉线检测
#QQBot账号掉线检测 关闭

掉线提醒

# 开启掉线提醒（会向所有管理员发送掉线通知）
#QQBot账号掉线提醒 开启

# 关闭掉线提醒
#QQBot账号掉线提醒 关闭

自动重连

# 开启自动重连（检测到掉线后自动尝试重连）
#QQBot账号掉线自动重连 开启

# 关闭自动重连
#QQBot账号掉线自动重连 关闭

检测时间间隔

# 设置检测间隔为1分钟（最小值）
#QQBot账号掉线检测时间设置 1分钟

# 设置检测间隔为5分钟（推荐值）
#QQBot账号掉线检测时间设置 5分钟

# 设置检测间隔为10分钟
#QQBot账号掉线检测时间设置 10分钟

# 设置检测间隔为30分钟（最大值）
#QQBot账号掉线检测时间设置 30分钟

# 支持范围：1-30 分钟
#QQBot账号掉线检测时间设置 15分钟

工作原理

检测机制：定时调用 /gateway/bot 接口查询 session_start_limit.remaining
掉线判断：remaining === 0 表示账号已掉线，无剩余连接次数
重连流程：
- 检测到 remaining === 0 时，记录 reset_after（重置等待时间）
- 发送掉线提醒（如已开启）
- 等待 reset_after 毫秒后，再次检查 remaining 是否恢复
- 若 remaining > 0，执行 logout() → login() 重连
- 重连成功后发送通知（如已开启）

配置示例

# config.yaml
offlineDetect:
  enabled: true           # 总开关
  notify: true            # 掉线提醒
  autoReconnect: true     # 自动重连
  interval: 5             # 检测间隔（分钟）

通知消息示例

掉线提醒：
[3889000008] 账号下线：[下线通知]你的帐号当前登录已失效，请5小时6分钟7秒后重新登录。
发送 /Bot上线3889000008 重新登录

重连成功：
[3889000008] 账号重连成功！

重连失败：
[3889000008] 自动重连失败：Connection timeout

转发消息改为渲染成图片,需要安装ws-plugin
#QQBot设置转换开启配合#ws绑定实现互通数据
#QQBotDAU and #QQBotDAUpro
Model/template/groupIncreaseMsg_default.js中自定义入群发送主动消息
config/QQBot.yaml中使用以下自定义模版,如果设置了全局md会优先使用自定义模版,配合e.toQQBotMD = true将特定消息转换成md,亦可在全局md模式下通过e.toQQBotMD = false将特定消息不转换成md
- 方法1: 直接修改config/QQBot.yaml (推荐)
```
customMD:
  BotQQ:
    custom_template_id: 模版id
    keys:
      - key1 # 对应的模版key名字
      - key2
      # ... 最多10个
```
- 方法2: 在Model/template目录下新建markdownTemplate.js文件,写入以下内容 (不推荐)
```
// params为数组,每一项为{key:string,values: ['\u200B']} // values固定为['\u200B']
export defalut {
  custom_template_id: '',
  params: []
}
```
#QQBot调用统计 根据e.reply()发送的消息进行统计,每条消息仅统计一次,未做持久化处理,默认关闭,#QQBot设置调用统计开启

config/QQBot.yaml中使用以下配置项,在全局MD时会以MD的模式自动加入params中

mdSuffix:
  BotQQ:
    - key: key1
      values:
        - value # 如果用到了key则不会添加
    - key: key2
      values:
        # \ 需转义 \\
        - "{{ e.msg.replace(/^#/g, '\\/') }}" # {{}}中为动态参数,会在发送时替换成对应值,目前仅有e可用,也可以传入js表达式等等, 后续可能会添加自定义方法
    # ...

config/QQBot.yaml中使用以下配置项,在全局MD时会以button的模式自动加入按钮指定行数并独占一行,当超过5排按钮时不会添加

btnSuffix:
  BotQQ:
    position: 1 # 位置:第几行 1 - 5
    values:
      - text: test
        callback: test
        show: # 达成什么条件才会显示
          type: random # 目前仅支持 random
          data: 50 # 0-100
      - text: test2
        input: test2
      # ... 最多10个

#QQBot用户统计: 对比昨日的用户数据,默认关闭,#QQBot设置用户统计开启
config/QQBot.yaml中使用前台日志消息过滤（~~自欺欺人大法~~），将会不在前台打印自定的消息内容，防log刷屏（~~比如修仙、宝可梦等~~），也可以使用#QQBot添加/删除过滤日志垃圾机器人
- 自定义消息采取完整消息匹配，非关键词匹配
- 非必要不建议开启此项
  
  注意：只会过滤部分QQBot的日志
```
filterLog:
  BotQQ:
    - 群主是机器人
    - 垃圾bot
    - 垃圾Bot
    # ...
```
config/QQBot.yaml中simplifiedSdkLog是否简化sdk日志,若设置为true则不会打印 recv from Group(xxx): xxx,并且会简化发送为send to Group(xxx): <markdown><button>
~~#QQBot一键群发: 需要先配置模版 template/oneKeySendGroupMsg_default.js~~
config/QQBot.yaml中markdownImgScale: 1是否对markdown中的图片进行等比例缩放,0.5为缩小50%,1.5为放大50%,以此类推
config/QQBot.yaml中sendButton: true未开启全局MD时是否单独发送按钮
config/QQBot.yaml中dauDB: level选择存储dau数据的数据库,可选: level, redis,以及false关闭dau统计(仅每日发言用户和群)
- level
  - 优点: 统计了大部分数据
  - 缺点: 缓存存一份,level存一份
- redis
  - 优点: 大部分使用redis存储,不会缓存
  - 缺点: 没有缓存所以有些没统计
已适配YePanel,提供dau统计和设置功能
config/QQBot.yaml中bus是否使用ws中转站

使用ws中转站可以降低成本,只需要一台低性能云服务器即可通过IP白名单验证,后端可使用本地服务器
填写格式:

  bus: {
    BotQQ: "example.com"
  }

后端搭建[QQBotWs]

安装教程

准备：TRSS-Yunzai
~~输入：#安装QQBot-Plugin~~
打开：QQ 收缩平台创建 Bot：
① 创建机器人
② 开发设置 → 得到 机器人QQ号:AppID:Token:AppSecret
输入：#QQBot设置机器人QQ号:AppID:Token:AppSecret:[01]:[01]

格式示例

机器人QQ号 114 AppID 514 Token 1919 AppSecret 810 群Bot 频道私域

#QBot设置114:514:1919:810:1:1

高阶能力

Markdown 消息

已经嘿壳，感谢龙虾🦞

使用教程

#QQBot账号
#QQBot设置 + 机器人QQ号:AppID:Token:AppSecret:是否群Bot:是否频道私域（是1 否0）
#QQBotMD + 机器人QQ号:模板ID
#QQBotMD + 机器人QQ号:raw 开启原生MD
#QQBotMD + 机器人QQ号: 关闭原生MD

项目介绍

TRSS-Yunzai QQBot Plugin

AFL-3.0 JavaScript 89提交数

定制我的领域

README

规则集

下载使用量

项目总下载次数（含Clone、Pull、 zip 包及 release 下载），每日凌晨更新

贡献者1

语言类型

JavaScript69.25%

Vue12.78%

HTML12.51%

CSS5.46%

QQBot-Plugin:基于TRSS-Yunzai的QQ机器人插件项目

TRSS-Yunzai QQBot Plugin

Tip

自用人机群主版

文件撤回示例

基础用法

更多示例

注意事项

账号掉线检测与重连命令

总开关

掉线提醒

自动重连

检测时间间隔

工作原理

配置示例

通知消息示例

安装教程

格式示例

高阶能力

使用教程

项目介绍

下载使用量

语言类型

目录