CyberBot - 基于 node-napcat-ts 的 QQ 机器人框架

CyberBot 是一个使用 TypeScript 开发的 QQ 机器人框架，基于 node-napcat-ts 库，提供了丰富的插件系统和消息处理功能。

.oooooo.                .o8                          oooooooooo.                .   
d8P'  `Y8b              "888                          `888'   `Y8b             .o8   
888          oooo    ooo  888oooo.   .ooooo.  oooo d8b  888     888  .ooooo.  .o888oo 
888           `88.  .8'   d88' `88b d88' `88b `888""8P  888oooo888' d88' `88b   888   
888            `88..8'    888   888 888ooo888  888      888    `88b 888   888   888   
`88b    ooo     `888'     888   888 888    .o  888      888    .88P 888   888   888 . 
`Y8bood8P'      .8'      `Y8bod8P' `Y8bod8P' d888b    o888bood8P'  `Y8bod8P'   "888" 
            .o..P'                                                                   
            `Y8P'                                                                  

功能特点

• 基于 WebSocket 的高效通信
• 完善的插件系统，支持动态加载和卸载
• 自动重连和错误处理机制
• 丰富的消息处理接口
• 支持定时任务
• 日志系统
• 权限管理系统

系统要求

• Node.js 18.x 或更高版本
• npm 或 pnpm 包管理器

安装

# 使用 
npx cyberbot-next

然后根据人机交互命令创建配置文件，然后根据指示运行项目。

配置

项目使用 config.json 文件进行配置，主要配置项包括：

{
  "bot": 机器人QQ号,
  "master": 主人QQ号,
  "admins": [管理员QQ号],
  "baseUrl": "ws://127.0.0.1:3001",
  "accessToken": "napcatqq连接密钥",
  "throwPromise": true,
  "reconnection": {
    "enable": true,
    "attempts": 10,
    "delay": 5000
  },
  "debug": true,
  "plugins": {
    "system": ["系统插件名称"],
    "user": ["用户插件名称"]
  },
  "logger": {
    "level": "info",
    "maxSize": "10m",
    "maxDays": 7
  }
}

使用方法

启动机器人

# 开发环境启动
npm start

创建插件

插件是 CyberBot 的核心功能扩展方式。每个插件都需要实现 Plugin 接口，包括以下主要方法：

• initialize(client): 插件初始化方法
• cleanup(): 插件清理方法

可以通过继承 CybePlugin 基类来快速创建插件。示例：

import { CybePlugin, AllHandlers } from 'cyberbot-next';

export class UserPlugin extends CybePlugin<AllHandlers['message']> {
  name = '插件名称';
  version = '1.0.0';
  description = '插件描述';
  
  setup() {
    // 注册消息处理器
    this.registerMessageHandler('message', async(e) => {
      if (e.raw_message === '关键词') {
        await this.reply('回复内容');
      }
    });
    
    // 处理私聊消息
    this.registerMessageHandler('message.private', async (e) => {
      // 处理逻辑
    });
    
    // 处理群聊消息
    this.registerMessageHandler('message.group', async (e) => {
      // 处理逻辑
    });
  }
  
  // 定义定时任务
  cron = [
    [
      '*/5 * * * * *', // cron表达式
      () => {
        // 定时执行的代码
      },
    ],
  ];
}

插件目录结构

plugins/
  ├── cmds/         # 命令处理插件
  ├── demo/         # 示例插件
  ├── deepseek/     # DeepSeek API相关插件
  ├── fabing/       # 发病模拟插件
  ├── keyword/      # 关键词响应插件 
  ├── like/         # 点赞相关插件
  ├── manager/      # 管理员插件
  ├── scraper/      # 网页爬虫插件
  └── screenshoot/  # 截图功能插件

API 参考

客户端核心方法

• sendPrivateMessage(userId, content): 发送私聊消息
• sendGroupMessage(groupId, content): 发送群聊消息
• deleteMessage(messageId): 撤回消息
• kickMember(groupId, userId): 踢出群成员
• banMember(groupId, userId, duration): 禁言群成员
• isMaster(userId): 检查是否为主人
• isAdmin(userId): 检查是否为管理员
• getGroupAvatarLink(groupId): 获取群头像链接
• getQQAvatarLink(userId): 获取用户头像链接

参考与致谢

本项目参考了以下项目的设计：

• napcatqq 项目
• node-napcat-ts 项目

许可证

ISC License