正向 WebSocket

正向模式下，萌卡NT监听一个 WebSocket 端口，插件作为客户端连接该端口。

后台配置

在插件服务中选择“正向 WS”，填写服务名称、监听端口、服务令牌和绑定节点。监听地址由萌卡NT管理，插件通常连接：

ws://HOST:PORT/

同一端口只能由一个插件服务使用。

SDK 配置

const api = createAPI({
  host: '127.0.0.1',
  port: 3001,
  token: 'TOKEN',
  name: 'plugin-name',
  version: '1.0.0',
  author: 'developer',
})

连接生命周期

api.on('friend_message', handleFriendMessage)

await api.connect()

// 退出时
api.disconnect()

正向 SDK 不主动重连。需要持续运行的插件应在连接断开后按自身策略重新调用 connect()。

事件权限

SDK 在认证时根据已注册的监听器声明权限：

在 connect() 之后新增监听器不会更新本次连接的权限声明。需要新增事件类型时，断开并重新连接。

原始认证帧

使用其他语言实现客户端时，连接建立后 10 秒内发送：

{
  "type": "auth",
  "token": "TOKEN",
  "name": "plugin-name",
  "version": "1.0.0",
  "author": "developer",
  "permissions": {
    "group_message": true,
    "friend_message": true,
    "group_event": true,
    "friend_event": true,
    "bot_offline": true
  }
}

认证成功：

{ "type": "auth_ok" }

认证失败：

{ "type": "auth_failed", "message": "令牌错误" }

后续帧格式见通信协议。

插件市场托管运行

通过插件市场快捷安装并“添加服务”时，框架会创建监听服务、下发连接配置并托管插件进程。插件压缩包根目录（允许再嵌套一层发布目录）应包含 mengka-plugin.json：

{
  "schema_version": 1,
  "entrypoint": "bin/my-plugin",
  "arguments": ["--connection", "{{connection_file}}"],
  "working_directory": "."
}

框架启动进程时会提供以下环境变量：

参数和清单中的环境变量值支持 {{package_root}}、{{runtime_dir}}、{{connection_file}}、{{token_file}}、{{connection_url}} 占位符。市场托管服务优先级高于普通 SDK 服务；托管进程停止或连接断开时，框架会自动回退到仍在线的普通 SDK 连接。

将插件网页后台嵌入框架

插件可以在同一份 mengka-plugin.json 中声明网页后台：

{
  "schema_version": 1,
  "entrypoint": "bin/my-plugin",
  "arguments": [
    "--connection", "{{connection_file}}",
    "--admin-host", "{{admin_host}}",
    "--admin-port", "{{admin_port}}"
  ],
  "working_directory": ".",
  "web_admin": {
    "enabled": true,
    "title": "我的插件后台",
    "health_path": "/api/status",
    "auth_type": "header",
    "auth_header": "X-Mengka-Admin-Token"
  }
}

框架为后台分配仅监听 127.0.0.1 的随机端口，并通过已登录管理员才能访问的同源代理嵌入管理端。插件的管理令牌由框架保存在运行目录并在代理端注入，不会发送给浏览器。

新增环境变量如下：

对应清单占位符为 {{admin_host}}、{{admin_port}}、{{admin_base_path}}、{{admin_token_file}}。网页前端应使用 sdk/plugin-web 解析 API 路径，并将 Vite 等构建工具的资源基础路径设置为相对路径 ./。