通信协议

框架提供外部 HTTP、正向 WebSocket 与反向 WebSocket 服务。每个服务使用独立令牌，按权限操作当前框架内的账号。

正向 WebSocket 认证

连接服务配置中的地址，在连接后 10 秒内发送：

{
  "type": "auth",
  "token": "YOUR_SERVICE_TOKEN",
  "name": "示例插件",
  "version": "1.0.0",
  "author": "开发者",
  "permissions": {
    "group_message": true,
    "friend_message": true,
    "group_event": true,
    "friend_event": true,
    "bot_offline": true,
    "bot_online": true
  }
}

name、version、author 与正确令牌均为必填。成功收到 {"type":"auth_ok"} 后发送接口请求；失败为 {"type":"auth_failed","message":"…"}。permissions 控制事件接收，不授予额外的账号或业务权限。临时私聊事件使用 friend_message 权限。

接口请求与响应

{
  "type": "action",
  "id": "request-1",
  "action": "get_group_list",
  "params": { "self_id": 123456789, "protocol_id": 0 }
}

账号通过 self_id + protocol_id 唯一选择。protocol_id 来自 get_protocol_list 的配置 ID，不是数组下标；0 是有效 ID，不能省略。大多数业务操作要求在线，登录及管理接口按各自说明执行。无参数接口传 {}。

成功响应：

{ "type": "action_result", "id": "request-1", "ok": true, "data": {} }

失败响应：

{ "type": "action_result", "id": "request-1", "ok": false, "error": "账号未在线" }

各 API 页描述的返回值是 data，可为对象、数组、字符串或 null。有上游业务结果码的接口还需判断业务状态，不能把外层 ok 当作付款、领取或加入成功。无 id 的请求仍可能执行，但不会收到 action_result。

同一连接可并发请求，返回顺序不保证与发送顺序一致，必须用 id 配对。连接需正确处理 WebSocket Ping/Pong 控制帧。文件传输通过 file_transfer 的 operation 显式操作。

HTTP

向 HTTP 服务地址发送 POST /api/{action}，请求体直接是 params，不包裹 action 帧。

curl -X POST "http://127.0.0.1:YOUR_PORT/api/get_group_list" \
  -H "Authorization: Bearer YOUR_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"self_id":123456789,"protocol_id":0}'

成功返回 {"ok":true,"data":…}，失败返回 {"ok":false,"error":"…"}。也可使用 X-Meng-Ka-Token 请求头；提供 Authorization 时以它为准，不接受 URL 查询令牌。请求体上限 4 MiB。认证失败为 401，未知接口为 404，参数或业务错误通常为 400，权益或 QQ 等级限制为 403，已移除接口为 410，插件服务暂不可用为 503。

权益与已移除接口错误

HTTP、WebSocket 与 IPC 使用相同业务错误字段；WebSocket 还包含对应请求的 type 和 id。例如 Plus 所选 QQ 未达到 32 级时：

{"type":"action_result","id":"request-1","ok":false,"status":"restricted","code":"QQ_LEVEL_TOO_LOW","requiredLevel":32,"currentLevel":20,"error":"当前 QQ 等级为 20 级，此 API 至少需要 32 级"}

code	含义	处理方式
TIER_CAPABILITY_FORBIDDEN	当前 Free 权益不支持此功能	使用支持该功能的权益后重试
QQ_LEVEL_TOO_LOW	所选 QQ 等级低于门槛	查看 requiredLevel 与 currentLevel；切换到符合条件的账号
QQ_LEVEL_UNKNOWN	无法核验所选 QQ 最新等级	确认账号在线，稍后重试
ACCOUNT_OFFLINE	所选 QQ 未在线	在账号页完成登录后重试
AUTHORIZATION_UNAVAILABLE	当前框架授权暂不可用	检查框架授权状态与网络连接
API_REMOVED	接口已移除	停止调用；升级权益也不会恢复该接口

前五种错误为 status: "restricted"，附带 requiredLevel、currentLevel；不适用等级比较时可为 0，不代表授权通过。已移除接口返回 status: "removed"。其他上游功能限制可能只有 errCode 与 error，不能假设所有失败都有 code。客户端不能通过传入权益、等级或自行等待来改变校验结果。

反向 WebSocket

框架主动连接服务配置中的 WebSocket 地址。握手头包含 Authorization: Bearer、X-Meng-Ka-Token、X-Meng-Ka-Service。接收端先校验令牌，再按同一 action/action_result 格式调用。

连接建立后框架发送 ready，其中 requires_plugin_info: false、supports_plugin_info: true。初始开启 group_message、friend_message、group_event、friend_event、bot_offline、bot_online 六项事件权限。插件可发送以下帧调整订阅：

{
  "type": "plugin_info",
  "name": "示例插件",
  "version": "1.0.0",
  "author": "开发者",
  "permissions": { "group_message": true, "bot_offline": true }
}

name、version、author 均需非空；成功返回 {"type":"plugin_info_ok"}。提供 permissions 时替换整组权限，未列出的项为 false；省略 permissions 则保留原权限。订阅调整不授予额外的账号或业务权限。

原生客户端示例

const socket = new WebSocket('ws://127.0.0.1:YOUR_PORT/')
socket.addEventListener('open', () => {
  socket.send(JSON.stringify({
    type: 'auth', token: 'YOUR_SERVICE_TOKEN',
    name: '示例插件', version: '1.0.0', author: '开发者',
    permissions: { group_message: true, friend_message: true },
  }))
})
socket.addEventListener('message', ({ data }) => {
  const frame = JSON.parse(data)
  if (frame.type === 'auth_ok') {
    socket.send(JSON.stringify({
      type: 'action', id: 'groups-1', action: 'get_group_list',
      params: { self_id: 123456789, protocol_id: 0 },
    }))
  }
  if (frame.type === 'action_result' && frame.id === 'groups-1') {
    if (frame.ok) console.log(frame.data)
    else console.error(frame.error)
  }
})

令牌只交给可信插件，不要放在公开网页中。旧版 forProtocol/client_type SDK、托管插件控制帧与 action_stream 不直接适用于 3.0，请使用本页协议。

调用限制

自定义发包、等级加速、扫码授权登录、红包领取及领取材料接口：Free 不可调用；Plus 每次调用核对当前 QQ 的最新等级，至少需要 32 级；Pro 不设这项 QQ 等级门槛。校验失败或无法获取最新等级时不会继续业务操作。账号在线、接口权限、当前框架授权及协议本身的安全确认仍须满足。

自框架 3.0.7 起，其他 API（包括 QQ 宠物和独立农场）不额外限制 QQ 等级，仍需满足账号在线、当前授权及接口业务条件。已移除的接口不会因权益满足而恢复。

含 red_packet 消息段的事件采用相同的新权益条件。Free 不接收该消息；Plus 按对应 QQ 的最新等级校验后推送。若红包位于混合消息、引用或撤回原消息中，条件未满足时整条事件不推送。普通文字提到“红包”不受影响。HTTP 客户端本身不接收事件。

等级不足时返回 ok: false、status: "restricted"、code、requiredLevel、currentLevel 和 error。code 可能为 QQ_LEVEL_TOO_LOW、QQ_LEVEL_UNKNOWN、ACCOUNT_OFFLINE 或 AUTHORIZATION_UNAVAILABLE。HTTP 同时返回 403。

实际等级由账号在线资料确定，请求参数不能指定权益或绕过检查。

IPC 插件

从框架的插件导入页安装插件。IPC 使用标准输入输出上的逐行 JSON，调用同一套 action / action_result，按权限访问当前框架内的账号。只允许调用清单 runtime.actions 声明的接口。安装包与权限说明见插件导入。