mirror of
https://gitee.com/dlmu-cone/Arborflow
synced 2026-10-24 02:02:19 +08:00
270 lines
7.2 KiB
Markdown
270 lines
7.2 KiB
Markdown
# ArborFlow
|
||
|
||
ArborFlow 是一个面向 [BehaviorTree.CPP](https://github.com/BehaviorTree/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
|
||
|
||
## 快速开始
|
||
|
||
进入项目目录并安装依赖：
|
||
|
||
```powershell
|
||
cd "D:\Elec Control\ArborFlow"
|
||
npm install
|
||
```
|
||
|
||
启动 Electron 开发模式：
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
执行类型检查并构建前端资源：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建完成后，可单独启动浏览器预览：
|
||
|
||
```bash
|
||
npm run preview
|
||
```
|
||
|
||
## 基本操作
|
||
|
||
1. 从左侧节点库单击节点，或将节点拖入画布。
|
||
2. 从父节点底部连接点拖到子节点顶部连接点。
|
||
3. 选中节点后，在右侧检查器修改名称、端口、黑板参数或断点。
|
||
4. 使用工具栏的自动布局按钮整理整棵树。
|
||
5. 将工程保存为 `.arborflow`，或导出为 BehaviorTree.CPP XML。
|
||
6. 打开 Monitor，填写机器人地址后连接实时状态流。
|
||
|
||
工程文件保存编辑器坐标、节点 ID、端口、备注等完整信息。XML 只保存 BehaviorTree.CPP 可执行数据，不包含编辑器坐标或实时运行状态。
|
||
|
||
## BehaviorTree.CPP XML
|
||
|
||
ArborFlow 导出 BehaviorTree.CPP v4 格式：
|
||
|
||
```xml
|
||
<?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
|
||
|
||
节点引用按以下顺序匹配：
|
||
|
||
1. 检查器中显示的 ArborFlow 节点 ID
|
||
2. 节点显示名称或 BehaviorTree.CPP 注册名称
|
||
3. 路径最后一段，例如 `/MainTree/NavigateToPose` 会匹配 `NavigateToPose`
|
||
|
||
名称重复时，同名节点会同时更新。需要精确定位时，应发送 ArborFlow 节点 ID。
|
||
|
||
### 直接 WebSocket 协议
|
||
|
||
每个 WebSocket 消息必须是一个 JSON 对象。单节点事件示例：
|
||
|
||
```json
|
||
{
|
||
"type": "status",
|
||
"nodeId": "navigate_action",
|
||
"status": "RUNNING",
|
||
"timestamp": 1784635200000
|
||
}
|
||
```
|
||
|
||
节点字段可以使用 `nodeId`、`uid`、`node`、`name` 或 `path`。`status` 可以是状态字符串，也可以是 BehaviorTree.CPP 对应的 `0` 至 `4` 数值。
|
||
|
||
一次更新多个节点：
|
||
|
||
```json
|
||
{
|
||
"type": "snapshot",
|
||
"timestamp": 1784635200000,
|
||
"nodes": {
|
||
"BatteryOK": "SUCCESS",
|
||
"NavigateToPose": "RUNNING",
|
||
"ReportResult": "IDLE"
|
||
}
|
||
}
|
||
```
|
||
|
||
连接成功后，ArborFlow 会发送订阅消息：
|
||
|
||
```json
|
||
{"type":"subscribe","client":"ArborFlow","protocol":1}
|
||
```
|
||
|
||
客户端每五秒发送一次 ping。服务端原样返回时间戳即可显示往返延迟：
|
||
|
||
```json
|
||
{"type":"pong","timestamp":1784635200000}
|
||
```
|
||
|
||
### 使用 rosbridge_server
|
||
|
||
启动 ROS 2 rosbridge：
|
||
|
||
```bash
|
||
ros2 launch rosbridge_server rosbridge_websocket_launch.xml
|
||
```
|
||
|
||
在 Monitor 中填写：
|
||
|
||
- WebSocket 地址：`ws://ROBOT_IP:9090`
|
||
- Topic：`/arborflow/status`
|
||
|
||
ArborFlow 会自动发送以下 rosbridge 订阅请求：
|
||
|
||
```json
|
||
{
|
||
"op": "subscribe",
|
||
"topic": "/arborflow/status",
|
||
"type": "std_msgs/msg/String"
|
||
}
|
||
```
|
||
|
||
ROS topic 使用 `std_msgs/msg/String`，将直接 WebSocket 协议中的 JSON 放入 `data` 字段：
|
||
|
||
```bash
|
||
ros2 topic pub --once /arborflow/status std_msgs/msg/String \
|
||
"{data: '{\"node\":\"NavigateToPose\",\"status\":\"RUNNING\"}'}"
|
||
```
|
||
|
||
### 本地模拟服务
|
||
|
||
项目包含一个用于联调的 WebSocket 状态模拟器：
|
||
|
||
```bash
|
||
npm run mock:monitor
|
||
```
|
||
|
||
随后在 Monitor 中连接：
|
||
|
||
```text
|
||
ws://127.0.0.1:1667
|
||
```
|
||
|
||
模拟器会让示例树中的 `BatteryOK`、`NavigateToPose` 和 `ReportResult` 循环切换状态。可通过环境变量修改端口：
|
||
|
||
```powershell
|
||
$env:ARBORFLOW_MOCK_PORT=1767
|
||
npm run mock:monitor
|
||
```
|
||
|
||
## 打包桌面应用
|
||
|
||
在当前操作系统上构建对应安装包：
|
||
|
||
```bash
|
||
npm run dist
|
||
```
|
||
|
||
也可以使用平台命令：
|
||
|
||
```bash
|
||
npm run dist:win
|
||
npm run dist:linux
|
||
npm run dist:mac
|
||
```
|
||
|
||
输出目录为 `release/`。建议在目标操作系统上执行对应打包命令，特别是 macOS 签名、公证以及不同 CPU 架构的构建。
|
||
|
||
可用的默认目标：
|
||
|
||
| 平台 | 输出格式 |
|
||
| --- | --- |
|
||
| Windows | NSIS 安装包、Portable |
|
||
| Linux | AppImage、deb |
|
||
| macOS | dmg、zip |
|
||
|
||
重新生成应用图标：
|
||
|
||
```bash
|
||
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 包 |
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
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`。
|