萌卡

外观

Node.js SDK ​

用同一套对象参数调用 API，通过正向 WebSocket、反向 WebSocket、HTTP 或本地 IPC 接入萌卡 NT。

下载 最新 Node.js SDK ZIP，或查看 SDK 源码。下载校验：SHA256。

准备环境 ​

使用 Node.js 22 或更高版本。下载 SDK 后，将其放入插件项目的 sdk 目录，在该目录安装依赖：

bash
cd sdk
npm ci --omit=dev

以下示例使用 ESM。插件项目的 package.json 需设置 "type": "module"，或将入口命名为 .mjs。

正向 WebSocket ​

在框架中创建正向 WebSocket 服务，将连接地址与令牌保存到插件运行环境。

js
import { createAPI } from './sdk/index.js'

const api = createAPI({
  url: process.env.MENGKA_WS_URL,
  token: process.env.MENGKA_PLUGIN_TOKEN,
  name: '示例插件',
  version: '1.0.0',
  author: '开发者',
  permissions: { group_message: true, bot_offline: true },
})

api.on('group_message', event => {
  console.log(event.self_id, event.protocol_id, event.group_id)
})
await api.connect()
const context = await api.get_plugin_context({})
console.log(context.available_actions)
const accounts = await api.get_bot_list({})
console.log(accounts)

connect() 在认证完成后才返回。事件监听可在连接前注册，避免漏接连接建立后的推送。

调用 API ​

方法名与 API 目录中的 action 一致，每次传入一个参数对象。也可使用 call 调用并设置本次等待时间：

js
const groups = await api.get_group_list({
  self_id: 123456789,
  protocol_id: 0,
})

const state = await api.call('level_task_management', {
  self_id: 123456789,
  protocol_id: 0,
  operation: 'status',
}, { timeoutMs: 30_000 })

SDK 默认等待 30 秒。等级任务执行可能需要更长时间，operation: 'run' 可显式等待 15 分钟，与后端任务上下文的时长对应：

js
const result = await api.call('level_task_management', {
  self_id: 123456789,
  protocol_id: 0,
  operation: 'run',
}, { timeoutMs: 900_000 })

停止等待不等于取消任务。超时后先查询实际结果，不要自动重发执行请求。

  • 账号由 self_id + protocol_id 共同选择，0 是有效协议 ID。
  • protocol_id 取自框架返回的账号或协议配置，不使用数组下标。
  • 仅能按插件权限访问当前框架内的账号，不能通过参数扩大权限。
  • 调用成功时返回 action_result 的 data；业务对象中的状态码仍需按该 API 文档判断。
  • 超时、断线或取消等待不代表操作没有执行。SDK 不自动重放请求；发送消息、领取奖励等操作应先查询结果再决定是否重试。
  • 新版不使用旧位置参数、client_type 或 forProtocol。迁移时按各 API 的参数表更新。
  • 一个框架只有一个节点，不再传入 node_id、nodeId 或 node 选择节点，也不提供节点新增、删除或代理设置接口。

自定义发包、等级加速、第三方扫码授权和红包领取及领取材料接口：Free 不可调用；Plus 每次调用核对对应 QQ 最新等级，至少需要 32 级；Pro 不设这项等级门槛。含红包消息段的事件也遵守此权益条件。自框架 3.0.7 起，其他 API（包括 QQ 宠物和独立农场）不额外限制 QQ 等级，仍需满足账号在线、当前授权及接口业务条件。SDK 本地角色和缓存等级不能授予权限，最终以框架校验为准；仅更新 SDK 不会改变旧框架的权益规则。

自身扫码登录与第三方扫码授权分别校验：支持此规则的框架中，get_login_qr、query_login_qr、登录安全验证二维码及 login_account 的 Linux 无密码扫码分支，Free 禁止调用，Plus / Pro 不设 QQ 等级前置条件；仍须通过 VM 实时权益检查。scan_qr / auth_qr 等第三方扫码授权继续要求 Plus 每次通过 VM 核验所选在线 QQ 的最新等级至少 32 级；Free 仍禁用，Pro 无此等级门槛。仅更新 SDK 不会改变旧框架权益，账号页正常登录及其他安全校验保持。

login_account 在 Linux 账号未保存密码时会获取登录二维码，这个扫码分支同样受上述权益条件限制；普通密码登录及框架管理员账号页的正常扫码流程保持原有规则。

以 get_plugin_context 返回的 available_actions 判断当前连接的能力。账号委托相关接口仅供受框架托管的 IPC 插件使用；SDK 包含方法不代表外部 HTTP 或 WebSocket 服务获准调用。

目录中标记“已移除”的 API 保留方法和参数类型，但具名方法与 call() 都会在发送请求前返回 API_REMOVED，错误中的 action 标识接口。QQ 宠物使用 qqpet_operation 的 30 项业务操作及只读 catalog；不支持其他底层操作。

接收事件 ​

js
api.on('event', event => {
  if (event.post_type === 'group_notice') {
    console.log(event.sub_type, event.self_id, event.protocol_id)
  }
})

SDK 将事件帧的 data 交给回调，保留原有字段；按 post_type 订阅的回调接收相同对象。可以选择统一监听或按类别监听，避免同时处理同一业务两次。事件不保证含有 event_id；system_event 是连接级事件，没有账号 self_id；群临时消息的 group_id 也可能缺失，不能据此自动推断回复目标。

群临时消息使用 friend_message 权限；好友通知使用 friend_event，群通知使用 group_event。连接状态事件需显式授权 system_event。字段见事件参考。断线期间不保证补发事件。

HTTP ​

js
import { createHTTPAPI } from './sdk/index.js'

const api = createHTTPAPI({
  url: process.env.MENGKA_HTTP_URL,
  token: process.env.MENGKA_PLUGIN_TOKEN,
})
const accounts = await api.get_bot_list({})

HTTP 使用插件 HTTP 服务的地址，不是管理后台的地址。HTTP 只调用接口，不接收事件。

反向 WebSocket ​

js
import { createReverseAPI } from './sdk/index.js'

const api = createReverseAPI({
  host: '127.0.0.1',
  port: 3001,
  path: '/mengka',
  token: process.env.MENGKA_PLUGIN_TOKEN,
  name: '示例插件',
  version: '1.0.0',
  author: '开发者',
  permissions: { group_message: true },
})

api.on('ready', () => {
  api.get_bot_list({}).then(accounts => console.log(accounts)).catch(console.error)
})
await api.listen()

在框架中填写与此监听地址、路径、令牌对应的反向 WebSocket 地址。listen() 表示服务开始监听；收到 ready 后才可调用 API。一个 SDK 实例接收一个框架连接。跨机器连接时调整监听地址并通过受保护的网络连接，不能把服务令牌写入 URL。

本地 IPC ​

js
import { createNativePlugin } from './sdk/index.js'

const plugin = createNativePlugin({
  pluginId: 'example-plugin',
  version: '1.0.0',
  actions: ['get_plugin_context', 'get_bot_list'],
})

plugin.on('bot_offline', event => {
  console.error('账号离线', event.self_id, event.protocol_id)
})
await plugin.start()
const accounts = await plugin.api.get_bot_list({})
console.error(accounts)

pluginId、version 必须与包内清单一致，调用的接口和订阅事件都要在清单声明。start() 会核对 ready 的插件、协议与受控连接文件中的 instance_id，握手完成后才返回。hello 的 framework_api: "3.0.0" 和 api_version: "1" 保持不变。标准输出专用于协议消息，日志使用 console.error。

SDK 不是可直接导入的插件安装包。Linux 框架的 IPC 插件仍需准备 Docker，并按 Docker Engine 目标架构携带 linux/amd64 或 linux/arm64 可执行入口与运行依赖。自 3.0.7 起，Windows 框架使用 Windows amd64 PE 可执行入口（通常是 .exe），不需要 Docker。不能把 .js 文件直接作为框架的可执行入口，也不能依赖宿主机已安装 Node.js。准备环境和打包要求见插件导入。外部 HTTP / WebSocket 接入不需要 Docker。

IPC 插件运行信息由框架提供的 MENGKA_PLUGIN_CONNECTION_FILE 读取，业务数据写入 plugin.dataPath。Linux 容器使用持久化 /data 和只读 /plugin 程序目录；Windows 原生插件使用框架分配的实际目录，并以框架运行账号的权限运行，不具备同等容器隔离，只导入可信插件。不要覆盖程序或读取框架账号缓存、数据库和授权文件。当前 IPC 不提供旧版 config / lifecycle 控制帧或配置热更新接口；system_event 中的连接生命周期通知是另一类事件。插件自己的设置应按现有管理页面或业务存储实现。

安全与排错 ​

令牌只保存在受保护的服务端配置中，不输出到日志，不放进网页代码。请求失败时保留可用的结构化错误字段，给用户展示操作所需的原因；不要将密码、授权令牌或完整登录材料回显。

连接与消息格式见通信协议，参数与适用协议见 API 目录。

萌卡 · 自托管 QQ 机器人框架

Copyright © 2026 Carlor-Official