mirror of
https://github.com/whyour/qinglong.git
synced 2025-12-13 07:25:05 +08:00
Add Flowgram integration documentation
Co-authored-by: whyour <22700758+whyour@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
a0a70703bc
commit
95780bd3ad
196
FLOWGRAM_INTEGRATION.md
Normal file
196
FLOWGRAM_INTEGRATION.md
Normal file
|
|
@ -0,0 +1,196 @@
|
||||||
|
# Flowgram.ai Integration
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
The workflow editor now uses the official Flowgram.ai library (@flowgram.ai/free-layout-editor) instead of a custom implementation. This provides a professional, feature-rich workflow editing experience.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Components
|
||||||
|
```
|
||||||
|
FlowgramEditor (Main Component)
|
||||||
|
↓
|
||||||
|
FreeLayoutEditorProvider (Context)
|
||||||
|
↓
|
||||||
|
EditorRenderer (Canvas)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Node Registries
|
||||||
|
Following Flowgram's pattern, each node type is registered with:
|
||||||
|
- `type`: Node identifier
|
||||||
|
- `info`: Display information (icon, description)
|
||||||
|
- `meta`: Visual properties (size, etc.)
|
||||||
|
- `onAdd`: Factory function to create new node instances
|
||||||
|
|
||||||
|
### Plugins Enabled
|
||||||
|
1. **FreeSnapPlugin** - Snap-to-grid for precise placement
|
||||||
|
2. **FreeLinesPlugin** - Visual connection lines between nodes
|
||||||
|
3. **FreeNodePanelPlugin** - Node addition panel
|
||||||
|
4. **MinimapPlugin** - Overview map for large workflows
|
||||||
|
5. **PanelManagerPlugin** - Panel management
|
||||||
|
|
||||||
|
## Node Types
|
||||||
|
|
||||||
|
### 1. Start Node
|
||||||
|
- Type: `start`
|
||||||
|
- Size: 120x60
|
||||||
|
- Purpose: Workflow entry point
|
||||||
|
|
||||||
|
### 2. HTTP Request Node
|
||||||
|
- Type: `http`
|
||||||
|
- Size: 280x120
|
||||||
|
- Config: url, method, headers, body
|
||||||
|
|
||||||
|
### 3. Script Execution Node
|
||||||
|
- Type: `script`
|
||||||
|
- Size: 280x120
|
||||||
|
- Config: scriptPath, scriptContent
|
||||||
|
|
||||||
|
### 4. Condition Node
|
||||||
|
- Type: `condition`
|
||||||
|
- Size: 280x120
|
||||||
|
- Config: condition expression
|
||||||
|
|
||||||
|
### 5. Delay Node
|
||||||
|
- Type: `delay`
|
||||||
|
- Size: 280x100
|
||||||
|
- Config: delayMs (milliseconds)
|
||||||
|
|
||||||
|
### 6. Loop Node
|
||||||
|
- Type: `loop`
|
||||||
|
- Size: 280x100
|
||||||
|
- Config: iterations
|
||||||
|
|
||||||
|
### 7. End Node
|
||||||
|
- Type: `end`
|
||||||
|
- Size: 120x60
|
||||||
|
- Purpose: Workflow termination
|
||||||
|
|
||||||
|
## Data Format Conversion
|
||||||
|
|
||||||
|
### From WorkflowGraph to Flowgram
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
nodes: workflowGraph.nodes.map(node => ({
|
||||||
|
id: node.id,
|
||||||
|
type: node.type,
|
||||||
|
data: { title: node.label, ...node.config },
|
||||||
|
position: { x: node.x || 0, y: node.y || 0 }
|
||||||
|
})),
|
||||||
|
edges: [],
|
||||||
|
viewport: { x: 0, y: 0, zoom: 1 }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### From Flowgram to WorkflowGraph
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
nodes: flowgramData.nodes.map(node => ({
|
||||||
|
id: node.id,
|
||||||
|
type: node.type,
|
||||||
|
label: node.data.title,
|
||||||
|
x: node.position.x,
|
||||||
|
y: node.position.y,
|
||||||
|
config: { ...node.data }
|
||||||
|
})),
|
||||||
|
startNode: flowgramData.nodes[0]?.id
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
### Core
|
||||||
|
- `@flowgram.ai/free-layout-editor@1.0.2` - Main editor
|
||||||
|
- `@flowgram.ai/runtime-interface@1.0.2` - Runtime types
|
||||||
|
|
||||||
|
### Plugins
|
||||||
|
- `@flowgram.ai/free-snap-plugin@1.0.2`
|
||||||
|
- `@flowgram.ai/free-lines-plugin@1.0.2`
|
||||||
|
- `@flowgram.ai/free-node-panel-plugin@1.0.2`
|
||||||
|
- `@flowgram.ai/minimap-plugin@1.0.2`
|
||||||
|
- `@flowgram.ai/free-container-plugin@1.0.2`
|
||||||
|
- `@flowgram.ai/free-group-plugin@1.0.2`
|
||||||
|
- `@flowgram.ai/panel-manager-plugin@1.0.2`
|
||||||
|
- `@flowgram.ai/free-stack-plugin@1.0.2`
|
||||||
|
|
||||||
|
### Utilities
|
||||||
|
- `nanoid@^3.0.0` - Unique ID generation
|
||||||
|
- `lodash-es@^4.17.21` - Utility functions
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### In Modal
|
||||||
|
```tsx
|
||||||
|
<WorkflowEditorModal
|
||||||
|
visible={isVisible}
|
||||||
|
workflowGraph={existingGraph}
|
||||||
|
onOk={(graph) => saveWorkflow(graph)}
|
||||||
|
onCancel={() => setIsVisible(false)}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Editor Props
|
||||||
|
```tsx
|
||||||
|
const editorProps = useEditorProps(initialData, nodeRegistries);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Visual Editing
|
||||||
|
- Drag and drop nodes
|
||||||
|
- Visual connection lines
|
||||||
|
- Snap-to-grid alignment
|
||||||
|
- Pan and zoom canvas
|
||||||
|
- Minimap for navigation
|
||||||
|
|
||||||
|
### Node Management
|
||||||
|
- Add nodes via panel or toolbar
|
||||||
|
- Select and edit nodes
|
||||||
|
- Delete nodes
|
||||||
|
- Move and position freely
|
||||||
|
|
||||||
|
### Professional UX
|
||||||
|
- Smooth animations
|
||||||
|
- Responsive design
|
||||||
|
- Dark mode compatible
|
||||||
|
- Undo/redo support (via Flowgram)
|
||||||
|
- Keyboard shortcuts (via Flowgram)
|
||||||
|
|
||||||
|
## Future Enhancements
|
||||||
|
|
||||||
|
With Flowgram integration, we can easily add:
|
||||||
|
1. **Form Meta** - Detailed node configuration forms
|
||||||
|
2. **Runtime Plugin** - Execute workflows
|
||||||
|
3. **Variable Panel** - Manage workflow variables
|
||||||
|
4. **Context Menu** - Right-click actions
|
||||||
|
5. **Custom Services** - Validation, testing, etc.
|
||||||
|
6. **Shortcuts** - Custom keyboard shortcuts
|
||||||
|
7. **Container Nodes** - Group nodes together
|
||||||
|
8. **Group Nodes** - Visual grouping
|
||||||
|
|
||||||
|
## Benefits
|
||||||
|
|
||||||
|
### For Users
|
||||||
|
- Professional workflow editor
|
||||||
|
- Intuitive drag-and-drop interface
|
||||||
|
- Visual feedback
|
||||||
|
- Familiar editing patterns
|
||||||
|
|
||||||
|
### For Developers
|
||||||
|
- Maintained by Bytedance
|
||||||
|
- Active development
|
||||||
|
- Plugin ecosystem
|
||||||
|
- TypeScript support
|
||||||
|
- Comprehensive documentation
|
||||||
|
|
||||||
|
### For Product
|
||||||
|
- Future-proof architecture
|
||||||
|
- Extensible design
|
||||||
|
- Community support
|
||||||
|
- Regular updates
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Flowgram.ai Official Site](https://flowgram.ai/)
|
||||||
|
- [GitHub Repository](https://github.com/bytedance/flowgram.ai)
|
||||||
|
- [Free Layout Demo](https://flowgram.ai/examples/free-layout/free-feature-overview.html)
|
||||||
|
- [Best Practices](https://flowgram.ai/examples/free-layout/free-feature-overview.html#%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5)
|
||||||
Loading…
Reference in New Issue
Block a user