插件导入

上传与框架运行环境匹配的 IPC 插件包，在框架中管理运行状态、配置和日志。Linux 框架使用 Docker 容器；自 3.0.7 起，Windows 框架直接运行 Windows amd64 插件，不需要 Docker。外部 HTTP / WebSocket 插件不需要 Docker。

Node.js 插件可使用 SDK 的 IPC 接入。SDK 只负责通信，插件仍需携带与目标系统和架构匹配的可执行入口和依赖，不能直接以 JavaScript 源文件作为入口，也不能依赖宿主机安装的 Node.js。

选择运行环境

Linux：打开“插件服务”的 IPC 导入分类，先检测 Docker 环境。检测只读取状态，不会安装或修改 Docker；需要准备环境时，确认页面说明后再执行准备。环境就绪后才能导入和启动插件。按 Docker Engine 的目标架构选择 linux/amd64 或 linux/arm64 插件包。

Windows：使用 Windows amd64 的 PE 可执行文件（通常是 .exe），无需检测或安装 Docker。Windows 原生插件会使用框架运行账号的权限；它不提供与 Linux 容器相同的文件系统隔离，只导入可信来源的插件。

安装包

支持 ZIP、TAR.GZ、TGZ，压缩包最大 512 MiB。根目录包含 mengka-plugin.json，程序入口必须是包内与目标系统和架构匹配的可执行文件。下面是 Linux 包示例；Windows 包应将 runtime.entry 改为包内的 .exe 入口，min_framework 至少设为 3.0.7。

{
  "schema": 3,
  "framework_api": "3.0.0",
  "plugin_id": "example-plugin",
  "name": "示例插件",
  "version": "1.0.0",
  "min_framework": "3.0.6",
  "author": "开发者",
  "notes": "首次发布",
  "runtime": {
    "entry": "plugin",
    "transport": "native-ipc-v1",
    "api_version": "1",
    "admin": false,
    "actions": ["get_bot_list"],
    "events": []
  }
}

entry 指向包内的可执行文件。仅声明插件实际需要的 Action 和事件，框架会检查权限；插件按权限访问当前框架内的账号。两种运行环境都保留安装包、清单、文件完整性及 IPC 授权校验。

IPC 握手

插件启动后通过标准输出发送一行 JSON，并以换行结束：

{"type":"hello","api_version":"1","framework_api":"3.0.0","plugin_id":"example-plugin","version":"1.0.0"}

plugin_id 与 version 必须匹配安装包清单。hello 中的 framework_api: "3.0.0" 与 api_version: "1" 是协议标识，不随框架补丁版本变化。

框架通过标准输入返回 type: "ready"。插件须核对 transport、api_version、framework_api、plugin_id，并确认 ready.instance_id 与框架通过 MENGKA_PLUGIN_CONNECTION_FILE 提供的受控连接文件一致，之后才可发送 action 请求。不要从网页或 API 参数接受替代的实例标识。接口响应为 action_result，推送为 event。完整请求格式见通信协议。

标准输出只写逐行 JSON 协议消息，日志写入标准错误；不要把调试输出混入 IPC 通道。

导入与运行

1. 在插件导入页上传压缩包。
2. 核对名称、作者、说明和权限。
3. 安装后启动插件，查看连接状态和运行日志。

插件可通过同一页面停止、更新和卸载。卸载时可保留数据，需要清除时使用彻底删除。外部 HTTP / WebSocket 插件在插件服务中配置，无需打成 IPC 包。

插件应将业务配置和数据写入 SDK 的 plugin.dataPath，路径由框架的受控连接文件提供。Linux 容器中的 /plugin 程序目录只读，业务数据保存在持久化的 /data；Windows 原生插件使用框架分配的数据目录，不使用容器路径。插件更新或重启会保留这些数据。stdout 只用于 IPC 协议，运行日志写入 stderr。