通信协议

警告

当前内容为旧版协议，新版协议正在补充完善中！

本文档面向希望在自己的应用中集成 MaaPipelineEditor (MPE) 本地通信功能的开发者。

如果您只是想使用 MPE 的本地服务功能，请查看 本地服务。

术语说明

在本文档中：

• MPE: MaaPipelineEditor 编辑器（浏览器端）
• 本地服务 / 服务端 / 客户端 / 伺服端: 指您实现的 WebSocket 服务器程序，三个术语含义相同

概述

MPE 的本地通信基于 WebSocket 协议实现，采用 JSON 格式进行消息传递。MPE 与本地服务之间通过路由化的 API 进行双向通信。

技术规格

• 协议: WebSocket (RFC 6455)
• 传输格式: JSON
• 默认端口: 9066
• 服务地址: ws://localhost:{port}
• 连接超时: 3 秒

消息格式

所有消息采用统一的 JSON 格式：

{
  "path": "/api/route_name",
  "data": {
    // 路由特定的数据
  }
}

• path: 路由路径，用于标识消息类型
• data: 消息携带的数据载荷，根据不同路由而变化

提示

大多数 WebSocket 库已将其封装并使用参数分开，具体请参考对应文档。

快速开始

最小化服务端示例

以下是一个使用 Python 实现的最小化 WebSocket 服务端示例：

import asyncio
import json
import websockets

async def handle_client(websocket):
    async for message in websocket:
        # 解析消息
        msg = json.loads(message)
        path = msg.get("path")
        data = msg.get("data")

        # 路由处理
        if path == "/etc/send_pipeline":
            file_path = data.get("file_path")
            pipeline = data.get("pipeline")

            # 处理接收到的 Pipeline
            print(f"收到 Pipeline: {file_path}")
            # 您的处理逻辑...

            # 发送确认
            await websocket.send(json.dumps({
                "path": "/etc/send_pipeline/ack",
                "data": {"status": "ok"}
            }))

async def main():
    async with websockets.serve(handle_client, "localhost", 9066):
        print("服务器已启动: ws://localhost:9066")
        await asyncio.Future()  # 永久运行

if __name__ == "__main__":
    asyncio.run(main())

MPE 连接流程

MPE 的连接流程如下：

1. 发起连接: 使用配置的端口连接到 ws://localhost:{port}
2. 等待握手: 等待 WebSocket 握手完成（最多 3 秒）
3. 连接成功: 触发 onopen 事件，用户可开始使用
4. 保持连接: 连接保持打开状态，直到主动断开或异常中断

API 路由

目前 MPE 通信协议定义了以下 API 路由：

提示

etc: editor to client，编辑器 → 服务端

cte: client to editor，服务端 → 编辑器

1. 接收 Pipeline(本地服务 → MPE)

路由: /cte/send_pipeline

方向: 本地服务 → MPE

用途: 服务端主动向 MPE 发送 Pipeline，用于从外部应用打开或同步 Pipeline 到编辑器。

请求数据:

{
  "path": "/cte/send_pipeline",
  "data": {
    "file_path": "D:/project/pipeline/task.json",
    "pipeline": {
      "节点1": {
        "recognition": {
          "type": "OCR",
          "param": {
            "expected": ["开始"]
          }
        }
        // ...
      }
    }
  }
}

字段说明:

字段	类型	说明
file_path	string	Pipeline 文件的路径标识
pipeline	object/string	Pipeline JSON 对象或 JSON 字符串

MPE 处理逻辑:

1. 文件已存在: 切换到对应文件并更新内容
2. 当前文件路径匹配: 直接更新当前文件
3. 新文件: 创建新文件标签页并导入 Pipeline

使用场景:

• 从您的应用中打开 Pipeline 文件到 MPE 进行可视化编辑
• 实时同步应用配置到 MPE
• 调试时将当前 Pipeline 状态发送到编辑器查看

参考代码

如果您在实现过程中遇到问题，可以参考 MPE 示例 Server 的 源代码