概述

MPE Flow 是一款高性能跨协议工作流编排与执行引擎。通过单一可执行文件，即可无缝运行桌面端图形界面 (GUI) 或独立无头命令行工具 (CLI)。

安装指南

Windows

前往 更新日志 页面下载 Windows 平台安装包（.exe 安装程序或免安装版），双击即可完成安装。

macOS

前往 更新日志 页面下载 macOS 的 Universal DMG 镜像包（单个安装包已同时原生适配 Apple Silicon M 系列芯片与 Intel 芯片机型）。双击打开 DMG 文件后，将 MPE 图标拖入 Applications（应用程序） 文件夹即可。

xattr -cr /Applications/MPE.app

Linux

MPE Flow 为 Linux 平台同时提供了原生桌面端 GUI 安装包与轻量独立无头 CLI 二进制：

方式一：Debian / Ubuntu 安装包 (.deb)

前往 更新日志 页面下载 .deb 包并通过 dpkg 安装：

sudo dpkg -i mpe_*_amd64.deb || sudo apt-get install -f

方式二：免安装便携版 (.AppImage)

下载便携 .AppImage 包，赋予可执行权限后直接双击或终端运行：

chmod +x MPE_*.AppImage
./MPE_*.AppImage

方式三：轻量无头 CLI (tar.gz)

适用于 Docker 容器、无头服务器与 CI/CD 流水线环境：

# 下载并解压 CLI
curl -LO https://download.mpe.run/releases/latest/mpe-vX.Y.Z-linux-x86_64.tar.gz
tar xzf mpe-vX.Y.Z-linux-x86_64.tar.gz

# 赋予执行权限并移入 PATH
chmod +x mpe
sudo mv mpe /usr/local/bin/

# 验证安装
mpe --help

快速示例

创建一个工作流文件 hello.mpf（默认采用简洁直观的 YAML 格式）：

_version: 1
flow:
  uuid: example-flow
  name: Hello World
  nodes:
    - uuid: entry-1
      type: entry
      name: Start
      data:
        type: entry
    - uuid: http-1
      type: http:request
      name: Fetch Data
      data:
        type: http:request
        url: https://httpbin.org/get
        method: get
    - uuid: end-1
      type: end
      name: End
      data:
        type: end
  connections:
    - id: conn-1
      source_node_uuid: entry-1
      target_node_uuid: http-1
      source_port_id: out
      target_port_id: in
    - id: conn-2
      source_node_uuid: http-1
      target_node_uuid: end-1
      source_port_id: "true"
      target_port_id: in

运行工作流：

mpe run -f hello.mpf

全域 AI 助手与智能编排

MPE Flow 原生内置了深度集成的全域 AI 流程编排架构师（Agentic AI Copilot），具备自然语言工作流生成、自主推进「执行到底」、自适应折行排版优化与一键报错智能自愈等全套智能体能力。

配置 AI Provider

前往系统设置 全局设置 → AI 助手 即可添加与管理模型服务商：

• 常用服务预设： 提供 DeepSeek、OpenAI、Claude、Kimi、Ollama 等主流厂商的常用预设，一键填入 Base URL 与推荐模型。
• Base URL 与 API Key： 自由接入公有云 API 或本地自建大模型端点（例如本地 Ollama 服务 http://localhost:11434/v1）。
• 模型自省与选择： 支持一键拉取服务商模型列表，或手动指定任意模型标识（如 deepseek-chat、deepseek-reasoner、gpt-4o、claude-3-5-sonnet）。
• 自定义全局 System Prompt： 注入您团队的特定业务规范、接口命名偏好或统一脚本风格，每次对话时自动附加生效。

交互形态与全局快捷键

MPE Flow 提供了四种无缝衔接的 AI 助手交互入口：

画布操作与自然语言流程生成

AI Copilot 不仅能回答文本，更通过强类型 Tool Calling 直接操控图形化画布：

• 自然语言生成 DAG： 例如：“创建一个登录认证并提取 Token 传递给下游 WebSocket 长连接的完整工作流”。
• 批量编排流水线： 具备 batch_create_pipeline 能力，一条指令即可原子化创建多节点复合流转拓扑并自动建立端口连线。
• 自动排版与自适应折行： 支持传统水平/垂直 DAG 排版，并全新引入 自适应折行布局算法 (Adaptive Wrap)，自动根据视口与多分支层级优化排版，杜绝连线重叠与无限横向拉伸。
• 脚本生成与修复： 自动编写满足 QuickJS / Rhai 运行时规范的 JavaScript 脚本，完成复杂加解密、动态计算与数据清洗。
• 数据源检索与导入： 感知已接入的 OpenAPI / Swagger 规范，按需自动导入接口并转为工作流节点。

自主 ReAct 执行与最大轮次控制

面向复杂的多步验证与探索性编排场景：

• 默认强制运行验证： 批量创建流水线后（batch_create_pipeline 默认 auto_run: true），自动触发执行并采集报告，确保交付即验证通过。
• 可配置执行轮次上限 (aiMaxIterations)： 在 AI 设置中支持配置 ReAct 最大推理轮次（5~100 轮，默认 20，提供 10、20、40、60 快捷预设）。当复杂任务达到轮次上限时，AI 优雅暂停并给出友好的后续操作指引。
• 中途纠偏插话 (Midway Steering)： 当 AI 正在批量执行或持续推理时，无需中止任务，可直接在输入框发送补充指令（例如：“端口改用 8080”），AI 将实时吸收新指令动态微调后续步骤。
• 思考链透明化 (Thinking Chain)： 原生适配 DeepSeek-R1 等推理模型，流式解析 <think> 标签，提供可折叠展开的推理思考过程展示。
• 高风险操作安全确认： 清空画布、批量删除节点、安装外部插件等破坏性操作前，弹出用户确认卡片，需人工授权后方可执行。

节点报错一键 AI 深度诊断与自愈

当协议节点执行遇到异常（HTTP 500、WebSocket 握手超时、断言失败等）：

• 在错误提示条或执行历史面板中点击 AI 诊断与修复。
• Copilot 自动采集上游节点上下文、出入参快照与底层错误链进行归因分析。
• 清晰呈现根因（如认证头缺失、Token 失效、JSONPath 语法错误），并在画布中一键应用推荐修复方案。

本地工作区代码感知与多模态

点击 关联本地项目，将工作流与本地源码工程建立连接：

• 项目结构扫描： 自动感知工程技术栈、路由文件、OpenAPI 文档与配置文件。
• 切片阅读与代码检索： 检索后端 Controller、DTO 定义与环境变量规范，精准填充接口路径与请求体格式。
• 截图多模态输入： 支持直接粘贴或拖拽接口文档截图、错误弹窗截图，AI 自动结合图像信息完成配置。

快捷斜杠指令与人机交互工具

MPE Flow 为全域 AI 助手配备了高频键盘快捷指令与人机协同工具桥接：

• 斜杠快捷指令 (/)： 在聊天输入框中输入 / 即可呼出自动补全悬浮面板：
  • /fix — 一键深度诊断并修复当前选中节点或最近失败节点的配置报错。
  • /explain — 剖析当前激活工作流的拓扑结构、变量流转与业务链路。
  • /test — 根据上游协议返回的数据特征，智能生成断言节点与边界用例。
• 交互式问询卡片 (ask_user)： 当大模型需要用户决策（如选取鉴权范围、确认环境地址、选择替代分支方案）时，自动生成交互式单选/多选或表单卡片，支持可选空提交，并安全挂起工具执行循环，等待用户点击提交后继续推进。
• 快速切换 AI 模型供应商： 无需反复打开设置面板，可在聊天输入框、面板顶部导航栏及 Spotlight 浮层 (Ctrl+K / Cmd+K) 中直接即时切换当前模型。
• 变量提取节点跨层级回溯： 自动向上回溯跳过断言、分支等非数据生产节点，支持按节点 UUID、别名或自定义节点名称绑定最近的上游数据源。
• 安全白名单终端工具 (terminal_exec)： AI 可在关联的工作区中执行经白名单严格校验的系统命令（如 git status、npm test、cargo check），高危操作强制触发卡片二次确认。
• 全信任自主模式 (Full Trust Mode)： 资深开发者可在设置中启用全信任模式，自主推进执行时免除频繁手动卡片点击，实现全自动端到端探索。
• 思考水滴物理动效与 Token 统计： 深度思考模型推理时，实时显示字数统计与下落堆叠水滴加载动画，推理链路直观生动。

CLI 命令参考

# 查看所有命令
mpe --help

# 指定激活环境、输出 Markdown 摘要与导出独立离线 HTML 测试报告
mpe run -f flow.mpf -e staging --summary summary.md --export-html report.html

# 启动常驻 Ingress 模拟服务网关
mpe serve -f webhook_mock.mpf -p 9527

# 通过 stdio 发布原生 MCP 工具供 Claude Desktop 或 Cursor 调用
mpe mcp serve -f search_tool.mpf --transport stdio

# 在声明式精简 YAML 与标准 .mpf 文件之间双向互转
mpe flow convert flow.mpf declarative.yaml
mpe flow convert declarative.yaml flow.mpf

# 全局环境文件管理
mpe env list --format table
mpe env show staging --source merged
mpe env set staging API_BASE=https://api.staging.com --local
mpe env delete staging --local

# 格式化流程文件或在 YAML 与 JSON 之间转换
mpe flow fmt ./flows/hello.mpf --to yaml
mpe flow fmt --all --to yaml

# 查看特定命令帮助
mpe run --help
mpe serve --help
mpe mcp serve --help
mpe env --help

CI/CD 集成 (GitHub Actions)

mpe run 提供完善的 CI/CD 原生支持，具备规范化退出码、生命周期三阶段对齐的 JUnit XML 测试套件（{flow} :: Setup、{flow} :: Main、{flow} :: Teardown）、自动生成 GitHub Actions Step Summary Markdown 摘要，以及独立交互式 HTML 报告导出。

# 导出 JUnit XML 并自动写入 GitHub Actions Step Summary
mpe run -f flow.mpf -e staging \
  --report junit --report-file results.xml \
  --summary "$GITHUB_STEP_SUMMARY" \
  --export-html report.html

在仓库中添加工作流步骤，通过 dorny/test-reporter 在 Pull Request 中自动执行工作流并展示测试报告：

name: Flow Tests

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run MPE flows
        run: |
          mpe run -f tests/flows/api-smoke.mpf \
            --report junit --report-file results.xml \
            --summary "$GITHUB_STEP_SUMMARY" \
            --export-html report.html

      - name: Publish test report
        if: always()
        uses: dorny/test-reporter@v1
        with:
          name: MPE Flow Results
          path: results.xml
          reporter: java-junit
          fail-on-error: 'true'

标准输出格式 (Output Format)

CLI 命令执行时默认向标准输出 (stdout) 输出规范的 JSON 结构体：

{
  "success": true,
  "data": null,
  "error": null,
  "execution_time": 156,
  "node_reports": [
    {
      "node_uuid": "entry-001",
      "node_type": "entry",
      "node_name": "Start",
      "status": "success",
      "duration_ms": 1,
      "used_port_id": "out"
    },
    {
      "node_uuid": "http-001",
      "node_type": "http:request",
      "node_name": "Fetch Data",
      "status": "success",
      "duration_ms": 233,
      "output_data": {
        "success": true,
        "status": 200,
        "body": { ... },
        "headers": { ... }
      }
    }
  ],
  "flow_report": {
    "flow_name": "Hello World",
    "total_nodes": 3,
    "executed_count": 3,
    "status": "success",
    "duration_ms": 234
  }
}

退出状态码 (Exit Codes)

工作流文件格式规范 (.mpf)

MPE 流程文件采用 .mpf 扩展名，遵循 FlowFile 统一包装格式。流程文件默认采用 YAML 格式持久化（同时保持对历史 JSON 文件的无缝向下兼容）：

_version: 1
flow:
  uuid: my-flow
  name: My Flow
  initial_variables:
    api_base: https://api.example.com
    token: abc123
  nodes:
    # 节点列表数组 ...
  connections:
    # 连线列表数组 ...

Top-level Fields

Flow Fields

节点配置结构 (Node)

uuid: node-uuid
type: http:request
name: My HTTP Request
data:
  type: http:request
  url: https://api.example.com
  method: get

节点连线规范 (Connections)

连线定义了工作流节点之间的有向执行流向与数据传递拓扑。

id: conn-1
source_node_uuid: entry-1
target_node_uuid: http-1
source_port_id: out
target_port_id: in

端口对应速查表 (Port Reference)

变量系统

语法规范

向变量池注入变量

1. 初始化变量：在工作流全局设置 flow.initial_variables 中定义
2. 变量提取节点：使用 variable:extractor 配合 JSONPath 从 last_node_output 提取
3. 脚本注入：在 script 节点中使用 fn.variables.set(name, value)

// variable:extractor example
{
  "type": "variable:extractor",
  "data": {
    "type": "variable:extractor",
    "output_mappings": [
      { "source": "$.body.id", "target": "user_id" },
      { "source": "$.status", "target": "http_status" }
    ]
  }
}

// Later use: {{user_id}}, {{http_status}}

内置动态变量 (Dynamic Variables)

MPE Flow 深度内置了一系列免声明的动态变量，在每个步骤执行时实时计算取值：

Conditional / Assertion Paths

conditional and assertion nodes read directly from last_node_output:

全局环境与机密安全分层

MPE Flow 将环境配置从工作流文件中彻底解耦。环境定义作为独立的 YAML 文件存储在 <flows_dir>/environments/ 目录下（默认位于 ~/.app/flows/environments/，亦可通过 MPE_ENVIRONMENTS_DIR 环境变量覆盖），支持在所有工作流之间全局复用 dev、staging、prod 等多套环境变量集。

双文件机密隔离架构

每个环境均支持双文件设计，天然兼顾团队协同共享与个人本地敏感机密隔离：

• 共享基础文件（<name>.yaml）： 存储团队通用配置（如服务域名、公共端口、公共超时策略等），直接随工作流一同提交入库 Git。
• 机器私有覆盖层（<name>.local.yaml）： 在本地机器上无缝覆盖共享文件中的同名变量，专用于存放开发者个人 API Token、数据库密码与私钥。建议在 .gitignore 中添加 *.local.yaml，彻底杜绝机密误入代码仓库。

# <flows_dir>/environments/staging.yaml（团队共享，提交入库 Git）
name: staging
description: 测试环境配置
variables:
  API_URL: https://staging-api.example.com
  TIMEOUT_MS: 5000
  MOCK_MODE: false

# <flows_dir>/environments/staging.local.yaml（个人本地私有，加入 .gitignore）
name: staging
variables:
  AUTH_TOKEN: dev_secret_bearer_token_xyz987
  CLIENT_SECRET: sk_staging_99214a8f

四级变量解析级联优先级

在单次执行、单步调试或并发压测工作流时，变量将严格按照以下四级优先级进行级联解析与合并：

GUI 桌面端环境交互

• 左侧面板环境折叠区： 侧边栏支持按需展开/收起环境列表，支持显示各环境变量数量角标，并可一键完成环境激活、重命名、复制副本与删除。
• 画布顶部工具栏选择器： 在画布顶部快速切换当前激活环境，即时生效，无需退出画布。
• 环境管理器弹窗（双模式）：
  • 全局模式： 支持带语法高亮与校验的 YAML 直读直写编辑，独立切换查看与编辑共享层及本地私有覆盖层。
  • 画布模式： 并排展示当前流程的兜底变量，并通过级联对比矩阵 (Cascade Comparison Matrix) 直观对比各层取值与最终生效值。
• 全执行链路贯通： 交互式运行、单步断点调试（F10/F11）与高并发压测均会自动带入并合并当前激活环境。
• 流程导出环境烘焙与敏感凭证扫描： 导出工作流时可选择将当前激活环境的变量直接“烘焙”写入 flow.initial_variables，生成自包含的单文件。内置凭据安全扫描，自动检测 key、secret、token、password、auth、cred、cert、private 等敏感关键字并提示清除，避免密钥外泄。

环境存储目录配置

环境目录默认跟随流程目录派生（<flows_dir>/environments），支持通过以下方式灵活自定义：

• GUI 设置： 设置 (Settings) → 存储 (Storage) → 环境文件目录 (environmentsDir)。
• 环境变量： 设置 MPE_ENVIRONMENTS_DIR=/path/to/environments。
• 配置文件： 在 config.toml（位于 $MPE_CONFIG 或系统数据目录）中设置 storage.environments_dir。

CLI 环境管理 (mpe env)

在无头 CI/CD 服务器或脚本中，可直接通过 mpe env 子命令全功能管理环境文件：

# 列出所有环境（名称、变量数、是否存在本地私有覆盖、文件路径）
mpe env list --format table

# 查看指定环境变量（支持查看 merged 合并层、base 共享层或 local 本地层）
mpe env show staging --source merged
mpe env show staging --source base
mpe env show staging --source local

# 向团队共享环境写入变量
mpe env set staging API_URL=https://staging.example.com TIMEOUT_MS=6000

# 向本地私有覆盖层写入敏感机密（保存至 .local.yaml）
mpe env set staging AUTH_TOKEN=secret_token_12345 --local

# 删除指定环境的本地覆盖层或完整删除环境
mpe env delete staging --local
mpe env delete staging

指定环境执行工作流

在 mpe run、mpe debug 或 mpe stress run 中通过 -e, --env <NAME> 指定环境：

# 指定 staging 环境执行流程
mpe run -f flows/checkout.mpf -e staging

# 指定环境并附加运行时变量临时覆盖
mpe run -f flows/checkout.mpf -e staging --var TIMEOUT_MS=10000 --var NOTIFY=true

# 指定 staging 环境进行压力测试
mpe stress run -f flows/checkout.mpf -e staging -u 100 -r 15

流程生命周期阶段 (Setup / Main / Teardown)

MPE Flow 将工作流执行模型升级为原生的一等公民生命周期三阶段架构。告别了脆弱、难以排查的回调函数机制，每个阶段均是完整的可视化多协议画布子图，无缝兼容所有协议节点：

三大阶段职责分工

Teardown 阶段中的只读 $report 报告变量

Teardown 阶段在启动时会自动注入代表 Main 核心业务执行结果的保留变量 $report，可在节点配置或脚本中直接读取：

• {{$report.status}} — Main 阶段执行状态（"success"、"failed"、"cancelled"）。
• {{$report.duration_ms}} — 核心业务流程的实际执行耗时（毫秒）。
• {{$report.node_reports}} — 各节点执行明细、输出数据、状态码与断言判定结果列表。

# 示例：在 Teardown 的 HTTP 节点中向群机器人发送自动化测试汇总卡片
{
  "msg_type": "text",
  "content": {
    "text": "【API 自动化测试报告】状态: {{$report.status}}, 核心链路耗时: {{$report.duration_ms}}ms"
  }
}

阶段失败与容错传播规则

• Setup 阶段失败： 若 Setup 中任一节点遇到未捕获异常或路由至 false 端口，系统将跳过 Main 阶段（标记为 stages.main.status == "skipped"），但依然会执行 Teardown 阶段清理已申请的前置资源。
• Teardown 阶段失败： 若 Main 业务已顺利通过但 Teardown 阶段清理失败，整体流程标记为失败，但报告中 stages.main.status 保持 "success" — 严格区分业务功能正确性与基础设施清理偶发故障。
• 无依赖根节点确定性执行： 在 Setup 和 Teardown 子图中，若存在多个无前驱连线的根节点（入度为 0），执行引擎将严格依据画布上的 (y, x) 坐标自上而下、从左向右确定性执行，彻底杜绝 JSON 数组乱序执行隐患。

画布阶段切换胶囊栏 (StageTabBar)

画布左上方常驻紧凑的阶段切换胶囊栏（Setup | Main | Teardown），悬停即可查看各阶段说明。添加、连线、删除节点以及撤销/重做操作均严格隔离在当前活跃阶段内。

开始与结束节点 (Entry / End)

Entry 开始节点

工作流各阶段的起始触发点，单图画布中必须且只能存在一个有效 Entry 节点（支持画布调色板便捷添加，具备防重复唯一性保护）。

{
  "uuid": "entry-1",
  "type": "entry",
  "name": "开始",
  "data": { "type": "entry" }
}

End 结束节点

工作流终端节点。当执行流推进至 end 节点时，当前阶段正常终止。

{
  "uuid": "end-1",
  "type": "end",
  "name": "结束",
  "data": { "type": "end" }
}

子流程节点 (Subflow)

子流程节点支持将其他独立工作流（.mpf 文件或工作区已存流程）作为模块化子节点嵌入到当前流程中，实现高内聚、可复用的复杂业务流编排。

画布拖拽生成与标签联动

支持直接从左侧侧边栏流程列表拖拽任意流程文件到画布中央，系统将自动创建并绑定该流程的子流程节点。双击子流程节点或在配置面板中点击“打开流程”，将在顶部多标签栏 (FlowTabBar) 中以独立标签打开目标子流程，便于即时查看与编辑，同时保留当前父流程的草稿与调试状态。

{
  "uuid": "subflow-1",
  "type": "flow:sub",
  "name": "用户登录与鉴权子流程",
  "data": {
    "type": "flow:sub",
    "target_flow_id": "7b6c3d9a-1234-5678-abcd-ef0123456789",
    "target_flow_path": "./subflows/auth.mpf",
    "inherit_all_variables": true,
    "variable_mappings": [
      { "source": "parent_username", "target": "login_user" },
      { "source": "parent_password", "target": "login_pass" }
    ],
    "export_all_variables": true,
    "output_mappings": [
      { "source": "access_token", "target": "auth_token" }
    ]
  }
}

配置参数详解

导出变量静态推断与预期预览

MPE Flow 内置静态代码与变量流转推断分析引擎。配置面板能够深度解析目标子流程结构，预先推断出其内部提取并导出的变量清单（如 variable:extractor 或 script 导出的变量），在子流程面板中直接呈现「预期导出变量预览」，支持一键复制变量名，并在下游节点引用时智能弱化未声明告警提示。

环路依赖检测与防死锁

MPE Flow 的 DAG 编译器在预检阶段即对子流程依赖图执行拓扑排序与环路检测。若存在直接自引用（A → A）或相互间接循环调用（A → B → A），校验器将立即拦截并给出明确的环路路径报错，彻底防止无限递归死锁。

HTTP 请求节点 (http:request)

发送高吞吐 HTTP/HTTPS 网络请求，支持 GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 等全套标准方法。

{
  "uuid": "http-1",
  "type": "http:request",
  "name": "用户登录接口",
  "data": {
    "type": "http:request",
    "url": "{{api_base}}/api/v1/auth/login",
    "method": "post",
    "headers": {
      "Authorization": "Bearer {{token}}"
    },
    "body_type": "body",
    "content_type": "json",
    "body": "{\"username\": \"admin\", \"password\": \"{{password}}\"}",
    "timeout_ms": 30000
  }
}

核心配置参数 (Core Fields)

HTTP 节点输出数据结构

{
  "success": true,
  "status": 200,
  "body": { "id": 1, "token": "eyJhbGciOi..." },
  "headers": { "content-type": "application/json" },
  "timing": { "connect_ms": 45, "total_ms": 150 }
}

HTTP Ingress 与 Webhook 模拟服务

MPE Flow 支持在工作流内直接启动轻量级内嵌 HTTP 服务端监听，无需启动独立的 Express/Nginx 即可完成 Webhook 触发、异步回调与接口 Mock 仿真验证。

http:ingress — HTTP 服务端监听节点

http:ingress 节点在指定端口上启动监听，负责捕获外部推送的 Webhook 请求或客户端调用。执行器与调试引擎会自动将其作为起始根节点优先触发。

uuid: ingress-1
type: http:ingress
name: 订单 Webhook 接收器
data:
  type: http:ingress
  port: 8080
  path: /api/v1/webhook/order
  method: post
  timeout_ms: 30000

Ingress 节点输出数据 (下游可直接引用)

• {{request_body}} — 外部客户端发来的 JSON 或原始请求体文本。
• {{headers}} — 请求头映射（如 x-hub-signature-256、authorization）。
• {{query}} — URL Query 查询参数键值对。
• {{connection_id}} — 本次 HTTP 连接上下文 ID（供下游 http:respond 关联回包）。

http:respond — HTTP 模拟响应节点

http:respond 节点与 http:ingress 节点配合使用，通过 connection_id 将自定义的状态码、响应头与响应体回写给外部客户端。

uuid: respond-1
type: http:respond
name: 确认回调成功
data:
  type: http:respond
  connection_id: "{{connection_id}}"
  status_code: 200
  headers:
    Content-Type: application/json
  body: '{"code": 0, "msg": "Webhook received successfully", "order_id": "{{order_id}}"}'

条件分支节点 (Conditional)

根据预设规则或动态表达式判定执行分支，将流程路由至 true 或 false 输出端口。

简单条件 (Simple Condition)

{
  "uuid": "cond-1",
  "type": "conditional",
  "name": "校验 HTTP 状态码",
  "data": {
    "type": "conditional",
    "condition_type": "simple",
    "field_path": "status",
    "operator": "equal",
    "expected_value": 200
  }
}

高级表达式 (Advanced Expression)

{
  "data": {
    "type": "conditional",
    "condition_type": "advanced",
    "advanced_expression": "status >= 200 && status < 300"
  }
}

比较操作符 (Operators)

JavaScript 脚本节点 (Script)

在高性能轻量级 QuickJS 安全沙箱运行时中执行 JavaScript 代码（支持完整 ES2020 语法标准）。

{
  "uuid": "script-1",
  "type": "script",
  "name": "处理业务数据",
  "data": {
    "type": "script",
    "script": "const data = JSON.parse(fn.response.raw); fn.variables.set('user_id', data.body.id);",
    "timeout_ms": 5000
  }
}

脚本内置沙箱 API (Script API)

断言验证节点 (Assertion)

校验上游数据是否符合业务预期，生成包含实际值、期望值与判定耗时的结构化测试报告。

{
  "uuid": "assert-1",
  "type": "assertion",
  "name": "校验接口返回",
  "data": {
    "type": "assertion",
    "mode": "all",
    "assertions": [
      { "id": "a1", "description": "状态码为 200", "target": "$.status", "operator": "eq", "expected": 200 },
      { "id": "a2", "description": "包含业务数据", "target": "$.body.data", "operator": "exists" }
    ]
  }
}

断言操作符分类 (Assertion Operators)

WebSocket 长连接节点组

提供针对 WebSocket 双向长连接全生命周期管控的三个专用节点：连接、收发/消息收集与关闭。

// 建立 WebSocket 连接 (ws:connect)
{ "type": "ws:connect", "data": { "type": "ws:connect", "url": "wss://echo.example.com/ws" } }

// 发送消息并收集对端回包 (ws:send_collect)
{ "type": "ws:send_collect", "data": {
    "type": "ws:send_collect",
    "connection_id": "ws-connect-uuid",
    "message": "{\"type\":\"ping\"}",
    "collect_timeout_ms": 10000
  }
}

// 主动断开连接 (ws:close)
{ "type": "ws:close", "data": { "type": "ws:close", "connection_id": "ws-connect-uuid" } }

其他核心协议节点 (TCP / UDP / SSE / GraphQL)

TCP 原始套接字

{ "type": "tcp:connect", "data": { "type": "tcp:connect", "host": "localhost", "port": 8080 } }
{ "type": "tcp:send", "data": { "type": "tcp:send", "connection_id": "uuid", "data": "Hello" } }
{ "type": "tcp:receive", "data": { "type": "tcp:receive", "connection_id": "uuid" } }
{ "type": "tcp:close", "data": { "type": "tcp:close", "connection_id": "uuid" } }

UDP 数据报文

{ "type": "udp:bind", "data": { "type": "udp:bind", "local_addr": "0.0.0.0", "local_port": 8888 } }
{ "type": "udp:send_to", "data": { "type": "udp:send_to", "connection_id": "uuid", "data": "Hello", "target_addr": "192.168.1.100", "target_port": 9999 } }
{ "type": "udp:recv_from", "data": { "type": "udp:recv_from", "connection_id": "uuid" } }
{ "type": "udp:close", "data": { "type": "udp:close", "connection_id": "uuid" } }

SSE (Server-Sent Events) 服务端流式推送

{ "type": "sse:connect", "data": { "type": "sse:connect", "url": "https://api.example.com/events" } }
{ "type": "sse:listen", "data": { "type": "sse:listen", "connection_id": "uuid", "max_events": 100 } }
{ "type": "sse:disconnect", "data": { "type": "sse:disconnect", "connection_id": "uuid" } }

GraphQL 查询与订阅

{ "type": "graphql:connect", "data": { "type": "graphql:connect", "endpoint": "https://api.example.com/graphql" } }
{ "type": "graphql:query", "data": { "type": "graphql:query", "connection_id": "uuid", "query": "query { users { id name } }" } }
{ "type": "graphql:subscribe", "data": { "type": "graphql:subscribe", "connection_id": "uuid", "query": "subscription { newUser { id } }" } }
{ "type": "graphql:introspect", "data": { "type": "graphql:introspect", "connection_id": "uuid" } }
{ "type": "graphql:disconnect", "data": { "type": "graphql:disconnect", "connection_id": "uuid" } }

可视化调试与断点控制

MPE Flow 内置全功能图形化交互调试器（同时支持 CLI 交互式单步调试）。可在任意节点挂起执行、实时查看/修改上下文变量、跳过不稳定节点或注入模拟产物。

断点标记

鼠标悬停在画布任意节点上，点击节点顶部的断点红点即可切换断点状态。开启调试运行后，执行器将在遇到断点节点前自动暂停并聚焦画布视口。

调试动作与全局快捷键

子流程步入步出与调用栈追踪

面对多层嵌套子流程的复杂业务场景，MPE Flow 调试引擎原生支持嵌套调用栈帧 (DebugCallFrame) 与分层级单步穿透。

子流程精细化单步控制

当执行推进至子流程节点时：

• 步入 (Step Into / F11)： 画布无缝下钻至子流程拓扑视图，顶部面包屑动态显示当前嵌套层级（如 主流程 > 鉴权子流程），并在子流程首个执行节点高亮闪烁暂停。
• 步过 (Step Over / F10)： 将子流程作为黑盒原子步骤执行，直接在父流程后续节点恢复暂停，适合快速跳过已验证成熟的公共模块。
• 步出 (Step Out / Shift+F11)： 当深入排查完子流程中的关键步骤后，一键执行完毕子流程剩余节点并返回父级上下文，无需逐节点敲击单步。

多层调试调用栈帧 (Call Stack)

右侧执行面板 - 堆栈中将动态呈现清晰的嵌套调用链路：

#0 根工作流 (订单主链路) → 子流程节点: 支付结算
  #1 支付结算 (Payment Pipeline) → 子流程节点: Token 刷新
    #2 Token 刷新 (OAuth2 Refresh) → HTTP 节点: /oauth/token [PAUSED 已暂停]

点击调用栈中的任意父级栈帧，画布视口与变量面板将即刻回溯切换至该层级的工作流视图与变量快照，支持在父子流程之间随时横向对照调试数据。

交互式流程切片执行与人机协同 (HITL)

MPE Flow 支持从庞大的工作流中框选局部子图或单节点按需独立触发执行，无需从 Entry 节点完整跑完全流程。

执行选中节点 (run_slice)

在画布上框选或多选目标节点，右键唤出上下文菜单并选择 执行选中节点：

• 零入度根节点自动推导： 编译器自动分析选中节点集合，将集合内部入度为 0 的节点识别为局部执行根节点，即使切片中没有 Entry 节点也能正常运行。
• 临时运行防污染： 切片执行产生的数据纯内存运转，不会持久化写入左侧历史执行记录列表，保持测试历史整洁干净。
• 敏捷调优验证： 适合在下游节点修改脚本算法、数据提取表达式或断言规则后，单步即时复测，免受上游耗时数据库或限流接口困扰。

人机协同 (HITL) 动态交互卡片

在自动化流转过程中，协议节点或 AI 智能体可通过 ask_human 协议发起人工确认或补充输入：

• 流程安全挂起： 遇到人机交互步骤时，执行流程自动挂起等待，并在右侧 执行面板 (ExecutionPanel) 中弹出结构化交互卡片。
• 表单数据提交： 用户可在卡片中输入文本、选择分支策略或授权操作。提交后，数据自动作为该节点的输出注入上下文变量池，驱动下游继续推进。
• 切片运行指示徽标： 执行中的切片具备醒目的状态徽章与一键中止控制。

生命周期全阶段调试与视图联动

MPE Flow 调试引擎支持贯穿 Setup → Main → Teardown 全生命周期的无缝断点调试。

画布阶段自动跟踪与视口聚焦

在单步步进 (F10/F11) 或恢复执行直至遇到 Setup/Teardown 中的断点节点时：

• 画布视口将自动切换展示当前暂停节点所在的阶段，免除用户手动点击阶段标签栏。
• 顶部多标签栏实时显示各阶段的单步调试状态（已完成、暂停中、等待执行）。
• 若用户在暂停状态下主动切换到其他阶段，顶部会常驻显示「一键跳转回暂停节点所在阶段」的快捷横幅。
• 在 Teardown 阶段调试时，右侧变量池可直接查看已注入的 Main 阶段完整报告变量快照 $report。

原生 MCP Server 引擎与共享网关

MPE Flow 宿主内核原生内置了高性能 Model Context Protocol (MCP) Server 服务引擎（flow-engine/src/mcp_server）。无需编写额外的 Python 或 TypeScript 胶水代码，也无需依赖外部插件二进制，即可直接将任意多协议工作流发布为供大模型（Cursor、Claude Desktop、本地智能体）调用的强类型 AI 工具。

9528 默认共享网关

默认情况下，发布的工作流会自动接入运行在端口 9528 上的集中式共享网关（紧邻 Ingress 监听器 9527，可在「设置 → 网络」中自定义）：

• 集中发现入口 (/mcp)： 在 AI 客户端中仅需配置一次该网关地址，即可自动发现宿主中已发布的所有工作流工具。后续新增、修改或卸载工作流，客户端无需更改任何配置。
• 路径隔离路由 (/{flow-slug}/mcp)： 支持通过 slug 路径前缀直接访问指定工作流，提供独立的上下文与参数隔离。
• 独立端口模式： 支持为重要流程分配独立自定义端口，作为单独的常驻进程提供服务。

自动化工具 Schema 推导

MPE Flow 自动根据工作流元数据编译生成标准 JSON Schema 工具定义：

• 工具名称 (Tool Name)： 自动取自 flow.name（转换为符合规范的 slug 标识，具备确定性重名消歧机制）。
• 工具描述 (Description)： 自动取自工作流描述 flow.description。
• 参数模式 (Input Schema)： 自动推导自工作流的 flow.initial_variables，每个初始变量自动映射为一个输入参数，包含类型、描述与默认值。
• 执行产物回传： 工作流末尾节点（如 variable:extractor、http:request 或 script 节点）的产物将直接格式化为 MCP 工具调用的返回结果，喂入大模型上下文。

画布一键发布与服务治理

画布一键发布

在桌面端应用中将流程发布为 MCP 工具极度便捷：

1. 在顶部流程标签页上右键点击当前工作流，或在流程下拉菜单中选择。
2. 点击 发布为 MCP 服务 (Publish as MCP Server)，唤起配置弹窗。
3. 在弹窗中核对工具名称、描述与通信协议（默认 9528 共享网关、独立端口或 stdio 进程模式）。
4. 点击 启动服务 立即生效，或直接一键复制客户端配置代码段。

设置中心服务治理面板

打开「设置 → MCP 服务治理」标签页，集中查看与管理所有已注册的 MCP 服务实例：

• 按端点清晰分组： 共享网关与独立端口服务层级化分组展示，运行状态（绿色运行中、灰色已停止）一目了然。
• 实例持久化保护： 注册的服务实例记录受持久化保护，应用退出重启后配置不丢失，支持启动时自动平滑恢复。
• 热重载 (Reload)： 当磁盘上的工作流文件发生修改后，点击 重载 即可就地刷新该工具执行逻辑，无需重启网关。
• 画布快速跳转： 点击治理表格中的任意流程名称，画布即可快速定位并打开对应工作流进行编辑。

Cursor 与 Claude Desktop 配置接入

MPE Flow 支持一键复制开箱即用的客户端配置文件片段：

方式一：Stdio 进程模式（推荐 Cursor 与 Claude Desktop 使用）

通过子进程标准输入输出直接通信，零网络端口监听，轻量且安全：

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
// 或 Cursor: .cursor/mcp.json
{
  "mcpServers": {
    "mpe-search-tool": {
      "command": "mpe",
      "args": [
        "mcp",
        "serve",
        "-f",
        "/path/to/search_tool.mpf",
        "--transport",
        "stdio"
      ]
    }
  }
}

方式二：Streamable HTTP 模式（9528 共享网关）

多个 AI 客户端统一连接至本机常驻共享网关：

{
  "mcpServers": {
    "mpe-gateway": {
      "url": "http://127.0.0.1:9528/mcp"
    }
  }
}

CLI 命令行服务生命周期 (mpe mcp)

在终端或无头服务器中通过命令行管理 MCP 服务生命周期：

# 启动单流程 stdio 服务（零端口占用）
mpe mcp serve -f ./flows/weather_api.mpf --transport stdio

# 后台守护启动 9528 共享网关
mpe mcp start --gateway --port 9528 --detach

# 将指定工作流发布并挂载到共享网关
mpe mcp start -f ./flows/database_query.mpf --shared

# 列出所有已注册与运行中的 MCP 服务实例
mpe mcp list --all

# 导出指定实例的 Cursor / Claude Desktop 配置代码段
mpe mcp config-snippet <实例ID或流程名称>

# 工作流修改后热重载实例
mpe mcp reload <实例ID或流程名称>

# 停止或移除已发布的服务实例
mpe mcp stop <实例ID或流程名称>
mpe mcp remove <实例ID或流程名称>

插件系统概述

插件用于扩展 MPE Flow 的协议节点生态。插件作为独立的侧边子进程（Sidecar Process）运行，通过标准输入输出 (stdio) 与宿主进行轻量级 JSON-RPC 2.0 通信（按行分隔，支持 LF 与 CRLF）。应用启动时宿主自动拉起插件完成 describe 握手，将其声明的节点动态注册到全局 NodeRegistry 中。插件节点在工作流编排、执行引擎与测试报告中与内置原生节点享有完全一致的一等公民体验。

插件安装目录

将包含 plugin.json 元数据清单的插件目录放入系统插件存放目录（默认位于 get_data_dir()/plugins；Windows 下位于 %APPDATA%/multi-protocol-flow-executor/plugins；可通过 MPE_PLUGIN_DIR 环境变量自定义覆盖）。宿主在启动时自动同步扫描：格式不合法的插件将被安全跳过，连续 3 次握手失败的插件将被临时隔离以保障宿主稳定性。

plugin.json 清单规范

协议插件生态与内置服务

协议插件作为独立开源仓库托管在 multi-protocol-flow GitHub 组织下（如 Kafka、Redis、MongoDB、gRPC、DB、SMTP 等）。同时，MPE Flow 宿主已原生内置 Model Context Protocol (MCP) Server 服务发布引擎（提供 9528 共享网关与按流路由），外部 MCP 客户端工具调用则可通过插件或标准连接器编排。可在 GUI 插件市场或 插件市场页面 一键安装扩展。

SDK 与自定义插件开发

插件 SDK 与底层 Wire 通信协议契约统一托管在独立的开源公共仓库中：multi-protocol-flow/mpe-plugin-sdk。Rust SDK 提供一等公民的强类型支持，同时提供轻量级 Python 和 Node.js 插件脚手架。Wire 类型直接共享自 mpe-plugin-sdk::protocol，确保宿主与插件之间永远不会产生协议漂移。

开发流程

1. 克隆或引用 SDK 仓库
2. 实现 Plugin Trait（实现 describe 声明节点元数据 + execute 执行协议调用；可选实现 flow_ended 释放每轮执行资源）
3. 编译为跨平台二进制或编写启动脚本
4. 将输出目录放置在 plugins/ 插件目录中进行联调

参考文档

• SDK 仓库开发指南：docs/plugin-guide.md (英文) / docs/plugin-guide.zh-CN.md (中文) 以及 docs/plugin-protocol.md
• 宿主架构文档：docs/plugin-architecture.md、docs/plugin-perf.md（可在 multi-protocol-flow GitHub 组织中查阅）

插件市场与分发

可在桌面端 GUI 设置面板的 插件市场 (Plugin Market) 标签页中一键浏览与安装插件，或直接通过 CLI 命令行进行管理：

mpe plugin dir
mpe plugin list
mpe plugin install <name> [--version <v>] [--registry <url>] [--dir <dir>] [--force]

注册中心契约规范

• GET {base}/plugins 返回可用插件列表，每项包含各操作系统平台的打包资产 (zip) url 与可选的 sha256 校验和（宿主将严格校验哈希，杜绝篡改）。
• 支持的操作系统平台键：windows-x64 | windows-arm64 | linux-x64 | linux-arm64 | macos-x64 | macos-arm64。
• Zip 包根目录必须包含以插件同名的唯一顶层文件夹，内部放置 plugin.json 与所有相关依赖产物。

公共插件注册中心默认通过 GitHub Pages 静态托管 (multi-protocol-flow.github.io/mpe-plugin-registry)。在网站的 插件市场页面 也可直接浏览最新插件生态。