qq-official-bot

基于 Node.js 的 QQ 官方机器人开发 SDK，采用现代化的模块化架构设计，提供完整的类型支持和丰富的功能。

✨ 特性

• 🏗️ 模块化架构 - 采用服务化设计，职责分离，易于维护和扩展
• 🔌 多种连接方式 - 支持 WebSocket、Webhook 和中间件模式
• 📝 完整类型支持 - 使用 TypeScript 开发，提供完整的类型定义
• 🚀 简单易用 - 提供直观的 API 接口和丰富的示例
• 🛠️ 功能全面 - 覆盖 QQ 官方 API 的所有功能
• 🔒 安全可靠 - 内置请求验证和错误处理机制

📦 安装

npm install qq-official-bot
# 或者
yarn add qq-official-bot
# 或者
pnpm add qq-official-bot

🎯 核心架构

项目采用分层架构设计：

• Bot 层 - 对外提供统一的 API 接口
• Service 层 - 业务逻辑服务，负责具体功能实现
• Client 层 - 底层客户端，处理认证和连接管理
• Message 层 - 消息处理和构建
• Events 层 - 事件系统和调度器

🚀 快速开始

1. WebSocket 连接模式

import { Bot, ReceiverMode } from 'qq-official-bot'

const bot = new Bot({
    appid: 'your_app_id',           // QQ 机器人的 App ID
    secret: 'your_app_secret',      // QQ 机器人的 App Secret
    sandbox: false,                 // 是否为沙箱环境
    removeAt: true,                 // 自动移除消息中的 @机器人
    logLevel: 'info',               // 日志级别
    maxRetry: 10,                   // 最大重连次数
    intents: [
        'GROUP_AT_MESSAGE_CREATE',     // 群聊@消息事件
        'C2C_MESSAGE_CREATE',          // 私聊消息事件
        'GUILD_MESSAGES',              // 频道消息事件
        'DIRECT_MESSAGE',              // 频道私信事件
        'GUILD_MESSAGE_REACTIONS',     // 频道消息表态事件
        'GUILDS',                      // 频道变更事件
        'GUILD_MEMBERS',               // 频道成员变更事件
    ],
    mode: ReceiverMode.WEBSOCKET,   // 连接模式
})

// 启动机器人
await bot.start()

2. Webhook 连接模式

import { Bot, ReceiverMode } from 'qq-official-bot'

const bot = new Bot({
    appid: 'your_app_id',
    secret: 'your_app_secret',
    // ...其他配置
    mode: ReceiverMode.WEBHOOK,
    port: 3000,                     // Webhook 监听端口
    path: '/webhook',               // Webhook 路径
})

await bot.start()

3. 中间件模式 (Express/Koa)

import { Bot, ReceiverMode } from 'qq-official-bot'
import express from 'express'

const bot = new Bot({
    appid: 'your_app_id',
    secret: 'your_app_secret',
    // ...其他配置
    mode: ReceiverMode.MIDDLEWARE,
    application: 'express',         // 或 'koa'
})

const app = express()
app.use(bot.middleware)
app.listen(3000)

await bot.start()

📝 基本用法

发送消息

// 监听消息事件
bot.on('message.guild', async (event) => {
    // 频道消息回复
    await event.reply('Hello, World!')
})

bot.on('message.group', async (event) => {
    // 群消息回复
    await event.reply('Hello, Group!')
})

bot.on('message.private', async (event) => {
    // 私聊消息回复
    await event.reply('Hello, Private!')
})

// 主动发送消息
await bot.sendMessage(channel_id, 'Hello from bot!')
await bot.sendGroupMessage(group_id, 'Hello, Group!')
await bot.sendPrivateMessage(user_id, 'Hello, User!')

使用服务模块

// 使用频道服务
const guilds = await bot.guildService.getGuilds()
const guildInfo = await bot.guildService.getGuild(guild_id)

// 使用消息服务
await bot.messageService.sendMessage(channel_id, 'Hello!')
await bot.messageService.recallMessage(channel_id, message_id)

// 使用成员管理服务
await bot.memberService.muteGuildMember(guild_id, user_id, '600', '0')
await bot.memberService.kickGuildMember(guild_id, user_id)

// 使用权限管理服务
const permissions = await bot.permissionService.getChannelUserPermissions(channel_id, user_id)
await bot.permissionService.updateChannelUserPermissions(channel_id, user_id, 'add_permission', 'remove_permission')

## 🔧 服务模块架构

项目采用服务模块化设计，每个服务负责特定的功能领域：

核心服务

服务模块	功能描述	主要方法
GuildService	频道管理	getGuilds(), getGuild(), getGuildMembers()
ChannelService	子频道管理	getChannel(), createChannel(), updateChannel()
MessageService	消息处理	sendMessage(), recallMessage(), sendPrivateMessage()
MemberService	成员管理	muteGuildMember(), kickGuildMember(), muteGuildMembers()
PermissionService	权限管理	getChannelUserPermissions(), updateChannelUserPermissions()
ReactionService	表态管理	addGuildMessageReaction(), removeGuildMessageReaction()
ScheduleService	日程管理	getChannelSchedules(), createSchedule(), updateSchedule()
ThreadService	帖子管理	getThreads(), createThread(), deleteThread()
AudioService	音频控制	controlMemberMic(), kickChannelMember()
BotService	机器人信息	getSelfInfo(), getSelfGuilds(), postActionMessage()

服务特性

• ✅ 统一响应格式 - 所有服务方法返回 ApiResponse<T> 格式
• ✅ 错误处理 - 内置错误捕获和处理机制
• ✅ 类型安全 - 完整的 TypeScript 类型定义
• ✅ 向后兼容 - Bot 类保持原有 API 接口不变

🎯 API 参考

基础 API

功能	方法	参数	返回值
获取机器人信息	getSelfInfo()	-	User
获取频道列表	getGuilds()	-	Guild[]
获取频道信息	getGuild(guild_id)	guild_id: string	Guild
获取子频道列表	getGuildChannels(guild_id)	guild_id: string	Channel[]
获取子频道信息	getChannel(channel_id)	channel_id: string	Channel

消息 API

功能	方法	参数	返回值
发送频道消息	sendMessage(channel_id, content)	channel_id: string, content: Sendable	any
发送私聊消息	sendPrivateMessage(user_id, content)	user_id: string, content: Sendable	any
发送群消息	sendGroupMessage(group_id, content)	group_id: string, content: Sendable	any
撤回消息	recallMessage(channel_id, message_id)	channel_id: string, message_id: string	any

成员管理 API

功能	方法	参数	返回值
获取频道成员	getGuildMembers(guild_id)	guild_id: string	GuildMember[]
禁言成员	muteGuildMember(guild_id, user_id, seconds)	guild_id: string, user_id: string, seconds: string	any
踢出成员	kickGuildMember(guild_id, user_id)	guild_id: string, user_id: string	any

权限管理 API

功能	方法	参数	返回值
获取用户权限	getChannelUserPermissions(channel_id, user_id)	channel_id: string, user_id: string	ChannelMemberPermissions
更新用户权限	updateChannelUserPermissions(channel_id, user_id, add?, remove?)	channel_id: string, user_id: string, add?: string, remove?: string	any

🔧 配置选项

Bot 配置

interface BotConfig {
    appid: string              // 机器人 App ID
    secret: string             // 机器人 App Secret
    sandbox?: boolean          // 是否为沙箱环境，默认 false
    removeAt?: boolean         // 是否移除消息中的 @，默认 false
    logLevel?: string          // 日志级别，默认 'info'
    maxRetry?: number          // 最大重连次数，默认 10
    intents: Intent[]          // 订阅的事件类型
    mode: ReceiverMode         // 连接模式
    
    // WebSocket 模式特有配置
    // (无额外配置)
    
    // Webhook 模式特有配置
    port?: number              // 监听端口
    path?: string              // Webhook 路径
    
    // 中间件模式特有配置
    application?: 'express' | 'koa'  // 使用的框架
}

事件类型 (Intents)

type Intent = 
    | 'GUILDS'                    // 频道变更事件
    | 'GUILD_MEMBERS'             // 频道成员变更事件
    | 'GUILD_MESSAGES'            // 频道消息事件（私域）
    | 'PUBLIC_GUILD_MESSAGES'     // 频道消息事件（公域）
    | 'GUILD_MESSAGE_REACTIONS'   // 频道消息表态事件
    | 'DIRECT_MESSAGE'            // 频道私信事件
    | 'GROUP_AT_MESSAGE_CREATE'   // 群聊@消息事件
    | 'C2C_MESSAGE_CREATE'        // 私聊消息事件
    | 'MESSAGE_AUDIT'             // 消息审核事件

🎨 消息构建

基础消息

// 文本消息
await bot.sendMessage(channel_id, 'Hello, World!')

// 富文本消息
await bot.sendMessage(channel_id, [
    '这是一条包含 ',
    { type: 'mention', user_id: 'user123' },
    ' 的消息'
])

高级消息

import { MessageBuilder } from 'qq-official-bot'

// 使用消息构建器
const message = bot.messageBuilder
    .text('Hello ')
    .mention(user_id)
    .text('!')
    .build()

await bot.sendMessage(channel_id, message)