Amesu NPM | npm.io

本项目是一个在 Node.js 环境下运行的 QQ 机器人第三方 SDK。

Introduction

由于腾讯是近期上线的群聊 API，官方文档的内容与实际表现有部分差异，请勿将其用于生产环境。

项目的名字来源于 Cygames 开发和发行的游戏『公主连结 Re:Dive』中的登场角色「アメス」，其罗马音 「a me su」 用作了本项目的名字。

Install

npm i amesu

Usage

const { Client } = require('amesu');

const client = new Client({
  appid: '1145141919',
  token: '38bc73e16208135fb111c0c573a44eaa',
  secret: '6208135fb111c0c5',
  events: ['GROUP_MESSAGES', 'PUBLIC_GUILD_MESSAGES'],
});

// 监听频道消息
client.on('at.message.create', async event => {
  // 快捷回复
  await event.reply({
    content: 'hello world',
  });
});

// 监听群聊消息
client.on('group.at.message.create', async event => {
  // API 调用
  await client.api.sendGroupMessage(event.group_openid, {
    msg_id: event.id,
    msg_type: 0,
    content: 'hello world',
  });
});

// 机器人上线
client.online();

事件回调中的 reply() 函数是 client.api 的语法糖，会根据消息事件的类型指向对应消息发送的 api 函数，并自动传入 from_id 与 msg_id。

Event

目前 socket 返回的事件全部为大写，并用下划线做分割。但是在 Node.js 的 EventEmitter 中，事件名一般使用小写字母。

这是因为事件名通常表示一种行为或状态，而不是一个特定的类或构造函数。根据 JavaScript 的命名约定，使用小写字母来表示这些行为或状态更为常见和推荐。

所以 Amesu 针对事件名做了以下处理：

事件名全部转换为小写
使用小数点替换下划线
会话事件添加 session 前缀

例如 MESSAGE_CREATE -> message.create，READY -> session.ready。

你可以仅监听事件的部分前缀，例如：

const { Client } = require('amesu');

const client = new Client();

client
  .on('guild.member', event => {
    console.log(event);
  })
  .online();

这样 guild.member.add、guild.member.update、guild.member.remove，三个事件将会被全部监听，这使得消息订阅更具有灵活性。

Config

/** 客户端配置项 */
interface ClientConfig {
  /** 机器人 ID */
  appid: string;
  /** 机器人令牌 */
  token: string;
  /** 机器人密钥 */
  secret: string;
  /** 订阅事件 */
  events: IntentEvent[];
  /** 是否开启沙盒，默认 `false` */
  sandbox: boolean;
  /** 掉线重连数，默认 `3` */
  max_retry?: number;
  /** 日志等级，默认 `'INFO'`，仅输出收到的指令信息 */
  log_level?: LogLevel;
}

/** 日志等级，具体使用可查阅 log4js 文档 */
type LogLevel = 'OFF' | 'FATAL' | 'ERROR' | 'WARN' | 'INFO' | 'DEBUG' | 'TRACE' | 'ALL';

API

Client.api

封装了官方文档所提供的 api 接口，可直接调用。（并不是所有 api 都能返回期望的结果）

Client.request

基于 fetch 封装，可发送自定义网络请求。

Client.online()

机器人上线。

Client.offline()

机器人下线。

Client.useEventInterceptor(interceptor)

添加事件拦截器。

Request.useRequestInterceptor(interceptor)

添加请求拦截器。

Request.useResponseInterceptor(interceptor)

添加响应拦截器。

Request.basis(config)

发送网络请求。（基础封装）

Request.get(url, params)

发送 GET 请求。

Request.delete(url, params)

发送 DELETE 请求。

Request.post(url, params)

发送 POST 请求。

Request.put(url, params)

发送 PUT 请求。

Request.patch(url, params)

发送 PATCH 请求。

插件开发

Amesu 仅仅是一个用于帮助建立 socket 通信的 SDK，而不是一个机器人解决方案，这两者不应该耦合，所以并未原生提供插件支持。

如果你想要开发插件，建立属于自己的生态，可以直接将她作为依赖进行二次开发。她十分的轻便，没有复杂的依赖项。拥有完整类型提示的同时，仅有 120 kb 的大小，而官方 SDK 却占据了 430 kb+。

若不想手搓，可以使用 kokkoro 框架进行机器人开发。如果不想集成框架体系，那么你也可以直接安装 @kokkoro/core 依赖去自定义插件。

npm i @kokkoro/core

插件代码示例：

import { useCommand, useEvent } from '@kokkoro/core';

/**
 * @type {import('@kokkoro/core').Metadata}
 */
export const metadata = {
  name: 'example',
  description: '插件示例',
};

export default function Example() {
  useEvent(
    ctx => {
      ctx.logger.mark('link start');
    },
    ['session.ready'],
  );

  useCommand('/测试', () => 'hello world');
  useCommand('/复读 <message>', ctx => ctx.query.message);
}

更多示例可查看 core 的 README 自述。