{"id":19533226,"url":"https://github.com/xueelf/amesu","last_synced_at":"2025-04-26T13:33:33.879Z","repository":{"id":205075001,"uuid":"713203944","full_name":"xueelf/amesu","owner":"xueelf","description":"Node.js SDK for QQ Bot","archived":false,"fork":false,"pushed_at":"2024-10-28T08:42:50.000Z","size":163,"stargazers_count":21,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-28T13:34:05.801Z","etag":null,"topics":["bot","qq"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xueelf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-02T03:26:39.000Z","updated_at":"2024-10-27T12:56:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"d89ecd68-4458-49e2-9b9f-8b17f65c1d91","html_url":"https://github.com/xueelf/amesu","commit_stats":null,"previous_names":["xueelf/amesu"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xueelf%2Famesu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xueelf%2Famesu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xueelf%2Famesu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xueelf%2Famesu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xueelf","download_url":"https://codeload.github.com/xueelf/amesu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224036338,"owners_count":17245035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","qq"],"created_at":"2024-11-11T02:06:07.170Z","updated_at":"2024-11-11T02:06:08.168Z","avatar_url":"https://github.com/xueelf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://vip2.loli.io/2022/11/04/AWEchfODdwszL8N.png\" alt=\"Amesu\" width=\"200\" /\u003e\n    \u003ch3\u003eAmesu\u003c/h3\u003e\n\u003c/div\u003e\n\n---\n\n![package](https://img.shields.io/npm/v/amesu?label=amesu\u0026style=flat-square\u0026logo=npm\u0026labelColor=FAFAFA)\n![engine](https://img.shields.io/node/v/amesu?style=flat-square\u0026logo=Node.js\u0026labelColor=FAFAFA)\n![downloads](https://img.shields.io/npm/dt/amesu?style=flat-square\u0026logo=tinder\u0026logoColor=FF8C00\u0026labelColor=FAFAFA\u0026color=616DF8)\n\n本项目是一个在 Node.js 环境下运行的 QQ 机器人第三方 SDK。\n\n## Introduction\n\n\u003e 由于腾讯是近期上线的群聊 API，官方文档的内容与实际表现**有部分差异**，请勿将其用于生产环境。\n\n项目的名字来源于 Cygames 开发和发行的游戏『公主连结 Re:Dive』中的登场角色「アメス」，其罗马音 **「a me su」** 用作了本项目的名字。\n\n## Install\n\n```shell\nnpm i amesu\n```\n\n## Usage\n\n```javascript\nconst { Client } = require('amesu');\n\nconst client = new Client({\n  appid: '1145141919',\n  token: '38bc73e16208135fb111c0c573a44eaa',\n  secret: '6208135fb111c0c5',\n  events: ['GROUP_AND_C2C_EVENT', 'PUBLIC_GUILD_MESSAGES'],\n});\n\n// 监听频道消息\nclient.on('at.message.create', async event =\u003e {\n  // 快捷回复\n  await event.reply({\n    content: 'hello world',\n  });\n});\n\n// 监听群聊消息\nclient.on('group.at.message.create', async event =\u003e {\n  // API 调用\n  await client.api.sendGroupMessage(event.group_openid, {\n    msg_id: event.id,\n    msg_type: 0,\n    content: 'hello world',\n  });\n});\n\n// 机器人上线\nclient.online();\n```\n\n事件回调中的 `reply()` 函数是 `client.api` 的语法糖，会根据**消息事件**的类型指向对应消息发送的 api 函数，并自动传入 from_id 与 msg_id。\n\n## Event\n\n目前 socket 返回的事件全部为大写，并用下划线做分割。但是在 Node.js 的 `EventEmitter` 中，事件名一般使用小写字母。\n\n这是因为事件名通常表示一种行为或状态，而不是一个特定的类或构造函数。根据 JavaScript 的命名约定，使用小写字母来表示这些行为或状态更为常见和推荐。\n\n所以 Amesu 针对事件名做了以下处理：\n\n- 事件名全部转换为小写\n- 使用小数点替换下划线\n- 会话事件添加 `session` 前缀\n\n例如 `MESSAGE_CREATE` -\u003e `message.create`，`READY` -\u003e `session.ready`。\n\n你可以仅监听事件的部分前缀，例如：\n\n```javascript\nconst { Client } = require('amesu');\n\nconst client = new Client();\n\nclient\n  .on('guild.member', event =\u003e {\n    console.log(event);\n  })\n  .online();\n```\n\n这样 `guild.member.add`、`guild.member.update`、`guild.member.remove`，三个事件将会被全部监听，这使得消息订阅更具有灵活性。\n\n## Config\n\n```typescript\n/** 客户端配置项 */\ninterface ClientConfig {\n  /** 机器人 ID */\n  appid: string;\n  /** 机器人令牌 */\n  token: string;\n  /** 机器人密钥 */\n  secret: string;\n  /** 订阅事件 */\n  events: IntentEvent[];\n  /** 是否开启沙盒，默认 `false` */\n  sandbox: boolean;\n  /** 掉线重连数，默认 `3` */\n  max_retry?: number;\n  /** 日志等级，默认 `'INFO'`，仅输出收到的指令信息 */\n  log_level?: LogLevel;\n}\n\n/** 日志等级，具体使用可查阅 log4js 文档 */\ntype LogLevel = 'OFF' | 'FATAL' | 'ERROR' | 'WARN' | 'INFO' | 'DEBUG' | 'TRACE' | 'ALL';\n```\n\n## API\n\n### Client.api\n\n封装了官方文档所提供的 api 接口，可直接调用。（并不是所有 api 都能返回期望的结果）\n\n### Client.request\n\n基于 fetch 封装，可发送自定义网络请求。\n\n### Client.online()\n\n机器人上线。\n\n### Client.offline()\n\n机器人下线。\n\n### Client.useEventInterceptor(interceptor)\n\n添加事件拦截器。\n\n### Request.useRequestInterceptor(interceptor)\n\n添加请求拦截器。\n\n### Request.useResponseInterceptor(interceptor)\n\n添加响应拦截器。\n\n### Request.basis(config)\n\n发送网络请求。（基础封装）\n\n### Request.get(url[, params][, config])\n\n发送 GET 请求。\n\n### Request.delete(url[, params][, config])\n\n发送 DELETE 请求。\n\n### Request.post(url[, params][, config])\n\n发送 POST 请求。\n\n### Request.put(url[, params][, config])\n\n发送 PUT 请求。\n\n### Request.patch(url[, params][, config])\n\n发送 PATCH 请求。\n\n## 插件开发\n\nAmesu 仅仅是一个用于帮助建立 socket 通信的 SDK，而不是一个机器人解决方案，这两者不应该耦合，所以并未原生提供插件支持。\n\n如果你想要开发插件，建立属于自己的生态，可以直接将她作为依赖进行二次开发。她十分的轻便，没有复杂的依赖项。拥有完整类型提示的同时，仅有 120 kb 的大小，而官方 SDK 却占据了 430 kb+。\n\n若不想手搓，可以使用 [kokkoro](https://github.com/kokkorojs/kokkoro) 框架进行机器人开发。如果不想集成框架体系，那么你也可以直接安装 `@kokkoro/core` 依赖去自定义插件。\n\n```shell\nnpm i @kokkoro/core\n```\n\n插件代码示例：\n\n```javascript\nimport { useCommand, useEvent } from '@kokkoro/core';\n\n/**\n * @type {import('@kokkoro/core').Metadata}\n */\nexport const metadata = {\n  name: 'example',\n  description: '插件示例',\n};\n\nexport default function Example() {\n  useEvent(\n    ctx =\u003e {\n      ctx.logger.mark('link start');\n    },\n    ['session.ready'],\n  );\n\n  useCommand('/测试', () =\u003e 'hello world');\n  useCommand('/复读 \u003cmessage\u003e', ctx =\u003e ctx.query.message);\n}\n```\n\n更多示例可查看 core 的 [README](https://github.com/kokkorojs/kokkoro/blob/master/packages/core/README.md) 自述。\n\n## FAQ\n\n### 为什么要做这个项目？\n\n因为官方 [频道 SDK](https://github.com/tencent-connect/bot-node-sdk) 已经有 2 年没更新了，不支持群聊而且使用体验非常糟糕。\n\n### 为什么 config 一定要指定 events？\n\n如果你是公域机器人，那么在使用官方 SDK 不传入 events 情况下，就会不断重连并在控制台疯狂输出。\n\n原因是部分事件仅限私域机器人使用，如果公域机器人订阅了就会抛异常，私域机器人订阅了公域事件却不会有任何问题...\n\n官方 SDK 的逻辑是没有传 events 就默认监听全部事件（其实也并不是全部，文档里有遗漏），这是不合理的。现在也没有任何手段知道机器人是公域还是私域，以及是否拥有群聊权限等问题，因此只能手动在 config 传入。\n\n### 为什么部分 API 没有返回结果？\n\n腾讯是近期才开放群聊 API 内测的，提供的文档也很不完善，目前存在字段、返回结果不一致，v1、v2 接口混用（鉴权方式不一样）等问题，所以调用某些接口可能会无法达到预期。\n\n### 为什么 request 不使用 axios 封装？\n\naxios 太大了，基于 fetch 的封装 build 后大小仅 3 kb 不到，基本满足大部分的使用场景。如果你想要使用 axios 或者其它网络请求库，可以自行安装依赖。\n\n### 这个 SDK 能做什么？\n\n频道与群聊的消息收发已测试完毕，API 返回结果与 interface 不符的问题还待腾讯后续完善文档和接口统一。\n\n当前 Amesu 已经有了完整的鉴权流程（会话保活、掉线重连、凭证刷新），并做了日志和网络请求的封装，后面没什么问题就不会再有大改了。如果有 API 缺失，在 `api` 文件内参考格式直接添加 url 就可以正常使用，也欢迎来提 pr。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxueelf%2Famesu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxueelf%2Famesu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxueelf%2Famesu/lists"}