gp-floweditor 0.0.1
General Platform Flow - Visual workflow editor and executor
License: MIT
Requires Python: >=3.9
Keywords: flow, workflow, node, graph, visual-editor, executor, qt, pyside, general-platform, gp

# gp-flow: General Platform Flow Editor

**gp-flow** 是 General Platform 的可视化流程编辑器模块，提供完整的节点图编辑和执行功能。它支持创建、编辑和执行可视化工作流，适用于自动化测试、业务流程编排等场景。

## 许可证

本项目采用 MIT 许可证:

```
MIT License

Copyright (c) 2023 notmmao

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## 特性

- **可视化编辑**: 基于 Qt 的图形化节点编辑器，支持拖拽、连接、布局
- **节点系统**: 内置多种节点类型（start, action, if, loop, end, set）
- **流程执行**: 支持同步/异步执行，带断点调试和单步执行
- **执行追踪**: 记录完整的执行轨迹，便于调试和分析
- **参数编辑**: 集成 gp-aw 的参数编辑器，支持动态参数配置
- **Undo/Redo**: 完整的撤销/重做支持
- **可扩展**: 易于扩展的节点定义系统

## 安装

```bash
pip install gp-flow
```

## 快速开始

### 创建和执行流程

```python
from gp_flow.graph import FlowGraph, FlowNode
from gp_flow.executor import FlowExecutor, ExecutionContext

# 创建流程图
graph = FlowGraph()

# 添加节点
start = FlowNode(type="start", title="Start", pos=(100, 100))
action1 = FlowNode(type="action", title="Action 1", pos=(300, 100))
if_node = FlowNode(type="if", title="Check Value", pos=(500, 100))
end = FlowNode(type="end", title="End", pos=(700, 100))

# 配置节点参数
start.params["vars"] = {"x": 10}
if_node.params["condition"] = "x > 5"

# 添加节点到图
for node in [start, action1, if_node, end]:
    graph.add_node(node)

# 连接节点
graph.add_edge(start.id, "out", action1.id, "in")
graph.add_edge(action1.id, "out", if_node.id, "in")
graph.add_edge(if_node.id, "true", end.id, "in")

# 执行流程
executor = FlowExecutor(graph)
ctx = executor.run()

# 查看执行轨迹
print(ctx.trace)
```

### 使用编辑器 UI

```python
from PySide6.QtWidgets import QApplication
from gp_flow.scene import FlowScene
from gp_flow.view import FlowView

app = QApplication([])

# 创建场景和视图
scene = FlowScene()
view = FlowView(scene)

# 添加节点到场景
scene.create_node("start", pos=(100, 100))
scene.create_node("action", pos=(300, 100))
scene.create_node("end", pos=(500, 100))

view.show()
app.exec()
```

## 架构

### 核心组件

- **FlowGraph**: 流程图数据模型，管理节点和连接
- **FlowNode**: 节点模型，包含类型、参数、位置等信息
- **FlowEdge**: 连接边模型，表示节点间的数据/控制流
- **NodeDefinition**: 节点定义抽象基类，定义节点的端口、参数和行为
- **FlowExecutor**: 流程执行器，支持逐步执行和调试
- **ExecutionContext**: 执行上下文，维护执行状态和变量

### 节点类型

| 类型 | 说明 |
|------|------|
| `start` | 流程起点，支持初始化变量 |
| `action` | 动作节点，执行具体操作 |
| `if` | 条件分支，根据表达式选择路径 |
| `loop` | 循环节点，支持 while 循环和最大迭代限制 |
| `end` | 流程终点 |
| `set` | 变量设置节点 |

### 编辑器组件

- **FlowScene**: 流程图场景，管理可视化节点项
- **FlowView**: 流程图视图，处理交互和渲染
- **FlowNodeEditor**: 节点属性编辑器
- **NodePalette**: 节点调色板，用于拖拽创建节点
- **Overlay 系统**: 运行时覆盖层，显示执行状态和调试信息

## 项目结构

```
gp-flow/
├── gp_flow/                 # 核心模块
│   ├── __init__.py         # 模块入口
│   ├── graph.py            # FlowGraph, FlowNode, FlowEdge 数据模型
│   ├── node_def.py         # 节点定义（NodeDefinition 及内置实现）
│   ├── executor.py         # 流程执行器
│   ├── registry.py         # 节点注册表
│   ├── scene.py            # Qt 场景实现
│   ├── view.py             # Qt 视图实现
│   ├── item.py             # 可视化节点项
│   ├── layout.py           # 自动布局算法
│   ├── flow_editor.py      # 节点属性编辑器
│   ├── node_palette.py     # 节点调色板
│   ├── widgets.py          # 自定义控件
│   ├── undo.py             # 撤销/重做支持
│   ├── selection.py        # 选择管理
│   ├── rule.py             # 连接规则验证
│   ├── exec_ctrl.py        # 执行控制
│   └── overlay/            # 运行时覆盖层组件
│       ├── overlay.py
│       ├── runtime_card.py
│       ├── mini_console.py
│       └── zoom_indicator.py
└── README.md              # 项目说明
```

## 依赖

- **gp-ir**: General Platform 中间表示
- **gp-aw**: 自动小部件库（参数编辑）
- **PySide6>=6.4**: Qt 绑定

## 贡献

欢迎提交 Issue 和 Pull Request 来改进项目！

## 支持

如有问题，请在 GitHub 仓库中创建 Issue。