安卓版QQ频道机器人APP客户端插件开发指南 0 次阅读

本文档将指导您如何为QQ频道机器人客户端开发插件。

插件结构

每个插件都是一个标准的 JavaScript 文件，需要导出一个包含以下字段的对象:

// 插件对象
const plugin = {
  // 基本信息(必需)
  id: 'plugin-id',          // 插件ID,只能包含小写字母、数字、下划线和横线
  name: '插件名称',         // 插件显示名称
  description: '插件描述',  // 插件功能描述
  command: '/命令',         // 触发命令,必须以/开头
  
  // 基本信息(可选)
  version: '1.0.0',        // 插件版本号
  author: '作者名称',      // 插件作者
  enabled: true,           // 插件是否启用
  
  // 配置项(可选)
  config: {
    // 插件的配置项
    minPoints: 10,         // 示例:最小积分
    maxPoints: 100,        // 示例:最大积分
  },
  
  // 数据存储(可选)
  storage: {
    // 插件的数据存储
    records: new Map()     // 示例:记录存储
  },
  
  // 消息处理函数(必需)
  handler: async (message, channel, context) => {
    // 返回值:
    // - 字符串: 要发送的回复消息
    // - null/undefined: 不发送回复
    // - Promise<string>: 异步返回回复消息
    return '回复消息'
  }
}

// 导出插件
module.exports = plugin

API 说明

1. 消息对象(message)

消息对象包含了消息的完整信息：

{
  id: "消息ID",
  channel_id: "频道ID", 
  guild_id: "服务器ID",
  content: "消息内容",
  cleanContent: "去除命令前缀的消息内容", // 新增:清理后的内容
  timestamp: "2023-01-01T00:00:00.000Z",
  status: "normal", // 消息状态: normal-正常, auditing-审核中, rejected-审核拒绝
  author: {
    id: "用户ID",
    username: "用户名",
    bot: false,
    avatar: "头像URL"
  },
  member: {
    roles: ["角色ID1", "角色ID2"],
    joined_at: "加入时间"
  },
  mentions: [
    {
      id: "被@用户ID",
      username: "被@用户名"
    }
  ],
  mention_everyone: false
}

2. 频道对象(channel)

频道对象包含了频道的基本信息：

{
  id: "频道ID",
  guild_id: "服务器ID",
  name: "频道名称",
  type: 0, // 频道类型
  position: 1, // 显示位置
  parent_id: "父频道ID",
  owner_id: "创建者ID",
  permissions: "权限值"
}

3. 上下文对象(context)

上下文对象提供了插件运行时的环境和工具：

{
  // 存储API - 持久化存储插件数据
  storage: {
    get: (key) => value, // 获取存储的值
    set: (key, value) => void, // 设置存储的值
    delete: (key) => void, // 删除存储的值
    clear: () => void, // 清空存储
    has: (key) => boolean // 检查键是否存在
  },
  
  // 配置API - 管理插件配置
  config: {
    get: (key) => value, // 获取配置项
    set: (key, value) => void, // 设置配置项
  },
  
  // 日志API - 记录插件运行日志
  log: {
    info: (message, details) => void, // 记录信息日志
    success: (message, details) => void, // 记录成功日志
    warning: (message, details) => void, // 记录警告日志
    error: (message, details) => void // 记录错误日志
  },
  
  // 工具API
  api: {
    // 发送消息
    sendMessage: async (channelId, content, options) => {
      // channelId: 频道ID
      // content: 消息内容
      // options: 可选参数
      //   - msg_id: 回复的消息ID
      //   - event_id: 事件ID
      // 返回:
      // - 成功: messageObject
      // - 审核: { code: 304023, data: { message_audit: { audit_id: "xxx" } } }
      return response
    },
    
    // 删除消息
    deleteMessage: async (channelId, messageId) => {
      // channelId: 频道ID
      // messageId: 消息ID
      return boolean
    },
    
    // 获取成员信息
    getMember: async (guildId, userId) => {
      // guildId: 服务器ID
      // userId: 用户ID
      return memberObject
    },
    
    // 获取服务器角色列表
    getGuildRoles: async (guildId) => {
      // guildId: 服务器ID
      return rolesArray
    },
    
    // 检查权限
    hasPermission: (permissions, permission) => {
      // permissions: 权限值
      // permission: 要检查的权限
      return boolean
    }
  }
}

插件功能界面预览

消息处理流程

1. 消息接收

   • 系统接收到新消息时，会检查消息内容是否以配置的命令前缀开始
   • 解析出命令和参数
   • 查找所有匹配的已启用插件

2. 插件执行

   • 对每个匹配的插件：
     • 创建独立的插件上下文对象
     • 调用插件的handler函数
     • 等待处理结果
   • 多个插件可以使用相同的命令
   • 插件按照加载顺序依次执行
   • 某个插件执行失败不会影响其他插件

3. 响应处理

   • 每个插件的handler如果返回字符串，系统会自动发送响应消息
   • 每个响应都是独立的，会分别发送到频道
   • 发送的消息可能进入审核状态(code: 304023)
   • 审核通过或拒绝会触发相应的事件

权限处理

系统会自动计算机器人的权限：

1. 管理员权限

   • 频道主
   • 管理员
   • 超级管理员
   • 子频道管理员
     拥有以上角色时自动获得所有权限(1099511627775)

2. 普通权限

   • 根据角色的permissions值按位计算
   • 多个角色的权限值进行按位或运算
   • 可以使用api.hasPermission检查特定权限

最佳实践

1. 错误处理

   handler: async (message, channel, context) => {
     try {
       // 处理逻辑
       context.log.info('处理成功', { messageId: message.id })
       return '成功消息'
     } catch (error) {
       context.log.error('处理失败', { error, messageId: message.id })
       return '处理失败，请稍后重试'
     }
   }

2. 数据持久化

   // 使用storage API保存数据
   const records = context.storage.get('records') || {}
   records[userId] = { /* 数据 */ }
   context.storage.set('records', records)

3. 消息审核处理

   const response = await context.api.sendMessage(channelId, content)
   if (response.code === 304023) {
     context.log.info('消息进入审核', {
       auditId: response.data.message_audit.audit_id
     })
   }

4. 权限检查

   if (!context.api.hasPermission(channel.permissions, 'MANAGE_MESSAGES')) {
     return '权限不足，需要管理消息的权限'
   }

么么扎~~