open-source/qinglong
1
0
Fork 0
mirror of https://github.com/whyour/qinglong.git synced 2025-12-13 07:25:05 +08:00
Code Issues Packages Projects Releases Wiki Activity
95780bd3ad
qinglong/FLOWGRAM_INTEGRATION.md
copilot-swe-agent[bot] 95780bd3ad Add Flowgram integration documentation 
Co-authored-by: whyour <22700758+whyour@users.noreply.github.com>
2025-11-23 06:06:17 +00:00

4.5 KiB
Raw Blame History

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

{
  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

{
  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

<WorkflowEditorModal
  visible={isVisible}
  workflowGraph={existingGraph}
  onOk={(graph) => saveWorkflow(graph)}
  onCancel={() => setIsVisible(false)}
/>

Editor Props

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