TuxMonkey/Arborflow

Fork 0

mirror of https://gitee.com/dlmu-cone/Arborflow synced 2026-10-23 17:52:20 +08:00

Files

TuxMonkey 5cc4c73e47 docs: add Chinese usage and monitor guide

2026-07-21 20:17:52 +08:00

7.2 KiB

Raw Blame History

ArborFlow

ArborFlow 是一个面向 BehaviorTree.CPP 的跨平台行为树生成、编辑与运行状态可视化工具。

项目使用 Electron、React、TypeScript 和 React Flow 构建，可在 Windows、Linux 与 macOS 上运行。当前版本以单个主行为树为编辑单位，可通过 SubTree 节点引用其他行为树。

主要功能

拖拽创建节点并通过端口连接父子关系
支持控制、装饰、动作、条件和子树节点
自动阻止环路、重复父节点以及非法子节点数量
编辑节点注册名称、端口、黑板表达式、备注和断点标记
自动布局、画布缩放、小地图、撤销与重做
保存和打开 .arborflow 工程文件
导入、导出和预览 BehaviorTree.CPP v4 XML
通过 WebSocket 或 rosbridge_server 实时显示节点状态
实时事件流、消息计数、节点匹配统计、延迟检测和自动重连

支持的运行状态：

状态	数值	含义
`IDLE`	`0`	节点空闲
`RUNNING`	`1`	节点正在执行
`SUCCESS`	`2`	节点执行成功
`FAILURE`	`3`	节点执行失败
`SKIPPED`	`4`	节点被跳过

环境要求

Node.js 20 或更高版本
npm 10 或更高版本
Windows 10/11、主流 Linux 发行版或 macOS

快速开始

进入项目目录并安装依赖：

cd "D:\Elec Control\ArborFlow"
npm install

启动 Electron 开发模式：

npm run dev

执行类型检查并构建前端资源：

npm run build

构建完成后，可单独启动浏览器预览：

npm run preview

基本操作

从左侧节点库单击节点，或将节点拖入画布。
从父节点底部连接点拖到子节点顶部连接点。
选中节点后，在右侧检查器修改名称、端口、黑板参数或断点。
使用工具栏的自动布局按钮整理整棵树。
将工程保存为 .arborflow，或导出为 BehaviorTree.CPP XML。
打开 Monitor，填写机器人地址后连接实时状态流。

工程文件保存编辑器坐标、节点 ID、端口、备注等完整信息。XML 只保存 BehaviorTree.CPP 可执行数据，不包含编辑器坐标或实时运行状态。

BehaviorTree.CPP XML

ArborFlow 导出 BehaviorTree.CPP v4 格式：

<?xml version="1.0" encoding="UTF-8"?>
<root BTCPP_format="4" main_tree_to_execute="MainTree">
    <BehaviorTree ID="MainTree">
        <Sequence name="Mission Sequence">
            <Condition ID="BatteryOK" min_level="{battery_threshold}"/>
            <Action ID="NavigateToPose" goal="{goal}"/>
        </Sequence>
    </BehaviorTree>
</root>

同一父节点下的执行顺序按照子节点在画布上的横向位置从左到右确定。导出前必须保证画布中只有一个根节点，并且所有节点组成一棵无环树。

Real-time Monitor

监视器支持两种接入方式：

ROS 或其他程序直接提供 WebSocket JSON 服务
使用 rosbridge_server 订阅 ROS 2 topic

节点引用按以下顺序匹配：

检查器中显示的 ArborFlow 节点 ID
节点显示名称或 BehaviorTree.CPP 注册名称
路径最后一段，例如 /MainTree/NavigateToPose 会匹配 NavigateToPose

名称重复时，同名节点会同时更新。需要精确定位时，应发送 ArborFlow 节点 ID。

直接 WebSocket 协议

每个 WebSocket 消息必须是一个 JSON 对象。单节点事件示例：

{
  "type": "status",
  "nodeId": "navigate_action",
  "status": "RUNNING",
  "timestamp": 1784635200000
}

节点字段可以使用 nodeId、uid、node、name 或 path。status 可以是状态字符串，也可以是 BehaviorTree.CPP 对应的 0 至 4 数值。

一次更新多个节点：

{
  "type": "snapshot",
  "timestamp": 1784635200000,
  "nodes": {
    "BatteryOK": "SUCCESS",
    "NavigateToPose": "RUNNING",
    "ReportResult": "IDLE"
  }
}

连接成功后，ArborFlow 会发送订阅消息：

{"type":"subscribe","client":"ArborFlow","protocol":1}

客户端每五秒发送一次 ping。服务端原样返回时间戳即可显示往返延迟：

{"type":"pong","timestamp":1784635200000}

使用 rosbridge_server

启动 ROS 2 rosbridge：

ros2 launch rosbridge_server rosbridge_websocket_launch.xml

在 Monitor 中填写：

WebSocket 地址：ws://ROBOT_IP:9090
Topic：/arborflow/status

ArborFlow 会自动发送以下 rosbridge 订阅请求：

{
  "op": "subscribe",
  "topic": "/arborflow/status",
  "type": "std_msgs/msg/String"
}

ROS topic 使用 std_msgs/msg/String，将直接 WebSocket 协议中的 JSON 放入 data 字段：

ros2 topic pub --once /arborflow/status std_msgs/msg/String \
  "{data: '{\"node\":\"NavigateToPose\",\"status\":\"RUNNING\"}'}"

本地模拟服务

项目包含一个用于联调的 WebSocket 状态模拟器：

npm run mock:monitor

随后在 Monitor 中连接：

ws://127.0.0.1:1667

模拟器会让示例树中的 BatteryOK、NavigateToPose 和 ReportResult 循环切换状态。可通过环境变量修改端口：

$env:ARBORFLOW_MOCK_PORT=1767
npm run mock:monitor

打包桌面应用

在当前操作系统上构建对应安装包：

npm run dist

也可以使用平台命令：

npm run dist:win
npm run dist:linux
npm run dist:mac

输出目录为 release/。建议在目标操作系统上执行对应打包命令，特别是 macOS 签名、公证以及不同 CPU 架构的构建。

可用的默认目标：

平台	输出格式
Windows	NSIS 安装包、Portable
Linux	AppImage、deb
macOS	dmg、zip

重新生成应用图标：

npm run icon:render

npm 命令

命令	用途
`npm run dev`	启动 Vite 和 Electron 开发环境
`npm run build`	TypeScript 检查并构建前端
`npm run preview`	预览生产前端资源
`npm run mock:monitor`	启动本地实时状态模拟器
`npm run icon:render`	使用 Electron 重新生成 PNG 图标
`npm run dist`	构建当前平台桌面安装包
`npm run dist:win`	构建 Windows 包
`npm run dist:linux`	构建 Linux 包
`npm run dist:mac`	构建 macOS 包

项目结构

ArborFlow/
├─ electron/          Electron 主进程与 preload
├─ public/            公共静态资源
├─ scripts/           Mock Monitor 与图标生成脚本
├─ src/
│  ├─ components/     节点、属性面板和监视器组件
│  ├─ lib/            XML、布局、校验和运行协议
│  ├─ App.tsx         编辑器主界面与状态管理
│  └─ styles.css      应用样式
├─ build/             应用图标
├─ package.json       npm 与 Electron Builder 配置
└─ README.md

安全说明

Electron 渲染进程启用了上下文隔离和沙箱，并关闭 Node.js 集成。文件打开与保存通过受限的 preload API 调用主进程完成。

实时监视器只处理节点状态，不会执行服务端发送的脚本。实际机器人网络中仍建议使用受信任的局域网、wss:// 或其他安全隧道。

License

本项目使用 MIT License，详见 LICENSE。

7.2 KiB Raw Blame History Unescape Escape