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)