docs: add demo readme (#698)

* docs: add demo readme

* chore: demo add readme to package.json

apps/demo-fixed-layout/REAME.md

@@ -0,0 +1,372 @@
+# FlowGram.AI - Demo Fixed Layout
+
+Best practices demo for fixed layout
+
+## Installation
+
+```shell
+npx @flowgram.ai/create-app@latest fixed-layout
+```
+
+## Project Overview
+
+### Core Tech Stack
+- Frontend Framework: React 18 + TypeScript
+- Build Tool: Rsbuild (a modern build tool based on Rspack)
+- Styling: Less + Styled Components + CSS Variables
+- UI Component Library: Semi Design (@douyinfe/semi-ui)
+- State Management: Editor framework developed in-house by Flowgram
+- Dependency Injection: Inversify
+
+
+### Core Dependencies
+
+- @flowgram.ai/fixed-layout-editor: Core dependency for the fixed-layout editor
+- @flowgram.ai/fixed-semi-materials: Semi Design materials library
+- @flowgram.ai/form-materials: Form materials library
+- @flowgram.ai/group-plugin: Group plugin
+- @flowgram.ai/minimap-plugin: Minimap plugin
+
+## Code Overview
+
+```
+src/
+├── app.tsx                    # Application entry component
+├── editor.tsx                 # Main editor component
+├── index.ts                   # Module export entry
+├── initial-data.ts            # Initial data configuration
+├── type.d.ts                  # Global type declarations
+│
+├── assets/                    # Static assets
+│   ├── icon-mouse.tsx         # Mouse icon component
+│   └── icon-pad.tsx           # Trackpad icon component
+│
+├── components/                # Common components library
+│   ├── index.ts               # Components export entry
+│   ├── node-list.tsx          # Node list component
+│   │
+│   ├── agent-adder/           # Agent adder component
+│   │   └── index.tsx
+│   ├── agent-label/           # Agent label component
+│   │   └── index.tsx
+│   ├── base-node/             # Base node component
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── branch-adder/          # Branch adder component
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── drag-node/             # Draggable node component
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── node-adder/            # Node adder component
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   └── utils.ts
+│   ├── selector-box-popover/  # Selection box popover component
+│   │   └── index.tsx
+│   ├── sidebar/               # Sidebar components
+│   │   ├── index.tsx
+│   │   ├── sidebar-node-renderer.tsx
+│   │   ├── sidebar-provider.tsx
+│   │   └── sidebar-renderer.tsx
+│   └── tools/                 # Toolbar components
+│       ├── index.tsx
+│       ├── styles.tsx
+│       ├── fit-view.tsx       # Fit view tool
+│       ├── minimap-switch.tsx # Minimap toggle
+│       ├── minimap.tsx        # Minimap component
+│       ├── readonly.tsx       # Readonly mode toggle
+│       ├── run.tsx            # Run tool
+│       ├── save.tsx           # Save tool
+│       ├── switch-vertical.tsx # Vertical layout toggle
+│       └── zoom-select.tsx    # Zoom selector
+│
+├── context/                   # React Context state management
+│   ├── index.ts               # Context export entry
+│   ├── node-render-context.ts # Node render context
+│   └── sidebar-context.ts     # Sidebar context
+│
+├── form-components/           # Form components library
+│   ├── index.ts               # Export entry for form components
+│   ├── feedback.tsx           # Feedback component
+│   │
+│   ├── form-content/          # Form content components
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-header/           # Form header components
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   ├── title-input.tsx
+│   │   └── utils.tsx
+│   ├── form-inputs/           # Form input components
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-item/             # Form item component
+│   │   ├── index.css
+│   │   └── index.tsx
+│   ├── form-outputs/          # Form output components
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   └── properties-edit/       # Property editing components
+│       ├── index.tsx
+│       ├── property-edit.tsx
+│       └── styles.tsx
+│
+├── hooks/                     # Custom React hooks
+│   ├── index.ts               # Hooks export entry
+│   ├── use-editor-props.ts    # Hook for editor properties
+│   ├── use-is-sidebar.ts      # Hook for sidebar state
+│   └── use-node-render-context.ts # Hook for node render context
+│
+├── nodes/                     # Flow node definitions
+│   ├── index.ts               # Node registry
+│   ├── default-form-meta.tsx  # Default form metadata
+│   │
+│   ├── agent/                 # Agent node type
+│   │   ├── index.ts
+│   │   ├── agent.ts
+│   │   ├── agent-llm.ts
+│   │   ├── agent-memory.ts
+│   │   ├── agent-tools.ts
+│   │   ├── memory.ts
+│   │   └── tool.ts
+│   ├── break-loop/            # Break loop node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case/                  # Case branch node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case-default/          # Default case node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── catch-block/           # Exception catch block node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── end/                   # End node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── if/                    # Conditional node
+│   │   └── index.ts
+│   ├── if-block/              # Conditional block node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── llm/                   # LLM node
+│   │   └── index.ts
+│   ├── loop/                  # Loop node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── start/                 # Start node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── switch/                # Switch branch node
+│   │   └── index.ts
+│   └── trycatch/              # Try-Catch node
+│       ├── index.ts
+│       └── form-meta.tsx
+│
+├── plugins/                   # Plugin system
+│   ├── index.ts               # Plugins export entry
+│   │
+│   ├── clipboard-plugin/      # Clipboard plugin
+│   │   └── create-clipboard-plugin.ts
+│   ├── group-plugin/          # Group plugin
+│   │   ├── index.ts
+│   │   ├── group-box-header.tsx
+│   │   ├── group-node.tsx
+│   │   ├── group-note.tsx
+│   │   ├── group-tools.tsx
+│   │   ├── icons/
+│   │   │   └── index.tsx
+│   │   └── multilang-textarea-editor/ # Multi-language textarea editor
+│   │       ├── index.css
+│   │       ├── index.tsx
+│   │       └── base-textarea.tsx
+│   └── variable-panel-plugin/ # Variable panel plugin
+│       ├── index.ts
+│       ├── variable-panel-layer.tsx
+│       ├── variable-panel-plugin.ts
+│       └── components/
+│           ├── full-variable-list.tsx
+│           ├── global-variable-editor.tsx
+│           └── variable-panel.tsx
+│
+├── services/                  # Services layer
+│   ├── index.ts
+│   └── custom-service.ts      # Custom service
+│
+├── shortcuts/                 # Shortcuts system
+│   ├── index.ts
+│   ├── constants.ts           # Shortcut constants
+│   └── utils.ts               # Shortcut utilities
+│
+└── typings/                   # Type definitions
+    ├── index.ts               # Types export entry
+    ├── json-schema.ts         # JSON Schema types
+    └── node.ts                # Node type definitions
+```
+
+## Architecture Design Analysis
+
+### Overall Architecture Pattern
+
+This project adopts a layered architecture combined with modular design:
+
+1. Presentation Layer
+    - Component layer: responsible for UI rendering and user interactions
+    - Tools layer: provides editor tool features
+
+2. Business Logic Layer
+    - Node system: defines the behavior and properties of various flow nodes
+    - Plugin system: provides extensible functional modules
+    - Services layer: handles business logic and data operations
+
+3. Data Layer
+    - Context state management: manages global application state
+    - Type system: ensures consistency of data structures
+
+### Key Design Patterns
+
+#### 1. Provider Pattern
+```typescript
+// The main editor component uses multiple nested Providers
+<FixedLayoutEditorProvider {...editorProps}>
+  <SidebarProvider>
+    <EditorRenderer />
+    <DemoTools />
+    <SidebarRenderer />
+  </SidebarProvider>
+  </FixedLayoutEditorProvider>
+```
+
+Use cases:
+- `FixedLayoutEditorProvider`: provides core editor features and state
+- `SidebarProvider`: manages sidebar visibility and the selected node
+
+#### 2. Registry Pattern
+```typescript
+export const FlowNodeRegistries: FlowNodeRegistry[] = [
+  StartNodeRegistry,
+  EndNodeRegistry,
+  SwitchNodeRegistry,
+  LLMNodeRegistry,
+  // ... more node types
+];
+```
+
+Advantages:
+- Supports dynamic registration of node types
+- Easy to extend with new node types
+- Decouples node type definitions
+
+#### 3. Plugin Pattern
+```typescript
+plugins: () => [
+  createMinimapPlugin({...}),
+  createGroupPlugin({...}),
+  createClipboardPlugin(),
+  createVariablePanelPlugin({}),
+]
+```
+
+Plugin system highlights:
+- Minimap plugin: provides a canvas minimap
+- Group plugin: supports node grouping and management
+- Clipboard plugin: enables copy and paste
+- Variable panel plugin: provides a UI for variable management
+
+#### 4. Factory Pattern
+Widely used in node creation and configuration:
+```typescript
+getNodeDefaultRegistry(type) {
+  return {
+    type,
+    meta: {
+      defaultExpanded: true,
+    },
+  };
+}
+```
+
+#### 5. Observer Pattern
+Implemented via the history system:
+```typescript
+history: {
+  enable: true,
+  enableChangeNode: true,
+  onApply: debounce((ctx, opt) => {
+    console.log('auto save: ', ctx.document.toJSON());
+  }, 100),
+}
+```
+
+#### 6. Strategy Pattern
+Reflected in the materials system:
+```typescript
+materials: {
+  components: {
+    ...defaultFixedSemiMaterials,
+    [FlowRendererKey.ADDER]: NodeAdder,
+    [FlowRendererKey.BRANCH_ADDER]: BranchAdder,
+    // Different render strategies can be swapped by key
+  }
+}
+```
+
+### State Management Architecture
+
+#### Context System Design
+The project uses multiple dedicated Contexts to manage different domains of state:
+
+1. SidebarContext: manages sidebar state
+```typescript
+export const SidebarContext = React.createContext<{
+  visible: boolean;
+  nodeId?: string;
+  setNodeId: (node: string | undefined) => void;
+}>({ visible: false, setNodeId: () => {} });
+```
+
+2. NodeRenderContext: manages state related to node rendering
+3. IsSidebarContext: simple boolean state
+
+#### Custom Hooks
+- `useEditorProps`: centralizes all editor configuration props
+- `useIsSidebar`: determines whether the current environment is the sidebar
+- `useNodeRenderContext`: gets the node render context
+
+### Component Architecture
+
+#### Component Layering
+1. Base components
+    - `BaseNode`: base rendering component for all nodes
+    - `DragNode`: node component in drag state
+
+2. Functional components
+    - Adders: `NodeAdder`, `BranchAdder`, `AgentAdder`
+    - Tools: zoom, save, run, and other utilities
+
+3. Container components
+    - `Sidebar`: sidebar container and its subcomponents
+    - `Tools`: toolbar container
+
+### Data Flow Architecture
+
+#### Initial Data Structure
+The project defines a complete initial flow dataset, including examples of multiple node types:
+- Start node: entry point of the flow, defines output parameters
+- Agent node: contains LLM, Memory, and Tools subcomponents
+- LLM node: large language model processing node
+- Switch node: conditional branch node
+- Loop node: loop processing node
+- TryCatch node: exception handling node
+- End node: end of the flow
+
+#### Data Transformation Mechanism
+```typescript
+fromNodeJSON(node, json) {
+  return json; // Transform logic on data import
+},
+toNodeJSON(node, json) {
+  return json; // Transform logic on data export
+}
+```

apps/demo-fixed-layout/REAME.zh_CN.md

@@ -0,0 +1,372 @@
+# FlowGram.AI - Demo Fixed Layout
+
+固定布局最佳实践 demo
+
+## 安装
+
+```shell
+npx @flowgram.ai/create-app@latest fixed-layout
+```
+
+## 项目概览
+
+### 核心技术栈
+- **前端框架**: React 18 + TypeScript
+- **构建工具**: Rsbuild (基于 Rspack 的现代构建工具)
+- **样式方案**: Less + Styled Components + CSS Variables
+- **UI 组件库**: Semi Design (@douyinfe/semi-ui)
+- **状态管理**: 基于 Flowgram 自研的编辑器框架
+- **依赖注入**: Inversify
+
+
+### 核心依赖包
+
+- **@flowgram.ai/fixed-layout-editor**: 固定布局编辑器核心依赖
+- **@flowgram.ai/fixed-semi-materials**: Semi Design 物料库
+- **@flowgram.ai/form-materials**: 表单物料库
+- **@flowgram.ai/group-plugin**: 分组插件
+- **@flowgram.ai/minimap-plugin**: 缩略图插件
+
+## 代码说明
+
+```
+src/
+├── app.tsx                    # 应用入口组件
+├── editor.tsx                 # 主编辑器组件
+├── index.ts                   # 模块导出入口
+├── initial-data.ts            # 初始化数据配置
+├── type.d.ts                  # 全局类型声明
+│
+├── assets/                    # 静态资源
+│   ├── icon-mouse.tsx         # 鼠标图标组件
+│   └── icon-pad.tsx           # 触控板图标组件
+│
+├── components/                # 通用组件库
+│   ├── index.ts               # 组件导出入口
+│   ├── node-list.tsx          # 节点列表组件
+│   │
+│   ├── agent-adder/           # Agent 添加器组件
+│   │   └── index.tsx
+│   ├── agent-label/           # Agent 标签组件
+│   │   └── index.tsx
+│   ├── base-node/             # 基础节点组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── branch-adder/          # 分支添加器组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── drag-node/             # 拖拽节点组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── node-adder/            # 节点添加器组件
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   └── utils.ts
+│   ├── selector-box-popover/  # 选择框弹出层组件
+│   │   └── index.tsx
+│   ├── sidebar/               # 侧边栏组件
+│   │   ├── index.tsx
+│   │   ├── sidebar-node-renderer.tsx
+│   │   ├── sidebar-provider.tsx
+│   │   └── sidebar-renderer.tsx
+│   └── tools/                 # 工具栏组件群
+│       ├── index.tsx
+│       ├── styles.tsx
+│       ├── fit-view.tsx       # 适应视图工具
+│       ├── minimap-switch.tsx # 缩略图开关
+│       ├── minimap.tsx        # 缩略图组件
+│       ├── readonly.tsx       # 只读模式切换
+│       ├── run.tsx            # 运行工具
+│       ├── save.tsx           # 保存工具
+│       ├── switch-vertical.tsx # 垂直布局切换
+│       └── zoom-select.tsx    # 缩放选择器
+│
+├── context/                   # React Context 状态管理
+│   ├── index.ts               # Context 导出入口
+│   ├── node-render-context.ts # 节点渲染上下文
+│   └── sidebar-context.ts     # 侧边栏上下文
+│
+├── form-components/           # 表单组件库
+│   ├── index.ts               # 表单组件导出入口
+│   ├── feedback.tsx           # 反馈组件
+│   │
+│   ├── form-content/          # 表单内容组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-header/           # 表单头部组件
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   ├── title-input.tsx
+│   │   └── utils.tsx
+│   ├── form-inputs/           # 表单输入组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-item/             # 表单项组件
+│   │   ├── index.css
+│   │   └── index.tsx
+│   ├── form-outputs/          # 表单输出组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   └── properties-edit/       # 属性编辑组件
+│       ├── index.tsx
+│       ├── property-edit.tsx
+│       └── styles.tsx
+│
+├── hooks/                     # 自定义 React Hooks
+│   ├── index.ts               # Hooks 导出入口
+│   ├── use-editor-props.ts    # 编辑器属性 Hook
+│   ├── use-is-sidebar.ts      # 侧边栏状态 Hook
+│   └── use-node-render-context.ts # 节点渲染上下文 Hook
+│
+├── nodes/                     # 流程节点定义
+│   ├── index.ts               # 节点注册表
+│   ├── default-form-meta.tsx  # 默认表单元数据
+│   │
+│   ├── agent/                 # Agent 节点类型
+│   │   ├── index.ts
+│   │   ├── agent.ts
+│   │   ├── agent-llm.ts
+│   │   ├── agent-memory.ts
+│   │   ├── agent-tools.ts
+│   │   ├── memory.ts
+│   │   └── tool.ts
+│   ├── break-loop/            # 跳出循环节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case/                  # Case 分支节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case-default/          # 默认 Case 节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── catch-block/           # 异常捕获块节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── end/                   # 结束节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── if/                    # 条件判断节点
+│   │   └── index.ts
+│   ├── if-block/              # 条件块节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── llm/                   # LLM 节点
+│   │   └── index.ts
+│   ├── loop/                  # 循环节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── start/                 # 开始节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── switch/                # Switch 分支节点
+│   │   └── index.ts
+│   └── trycatch/              # Try-Catch 节点
+│       ├── index.ts
+│       └── form-meta.tsx
+│
+├── plugins/                   # 插件系统
+│   ├── index.ts               # 插件导出入口
+│   │
+│   ├── clipboard-plugin/      # 剪贴板插件
+│   │   └── create-clipboard-plugin.ts
+│   ├── group-plugin/          # 分组插件
+│   │   ├── index.ts
+│   │   ├── group-box-header.tsx
+│   │   ├── group-node.tsx
+│   │   ├── group-note.tsx
+│   │   ├── group-tools.tsx
+│   │   ├── icons/
+│   │   │   └── index.tsx
+│   │   └── multilang-textarea-editor/
+│   │       ├── index.css
+│   │       ├── index.tsx
+│   │       └── base-textarea.tsx
+│   └── variable-panel-plugin/ # 变量面板插件
+│       ├── index.ts
+│       ├── variable-panel-layer.tsx
+│       ├── variable-panel-plugin.ts
+│       └── components/
+│           ├── full-variable-list.tsx
+│           ├── global-variable-editor.tsx
+│           └── variable-panel.tsx
+│
+├── services/                  # 服务层
+│   ├── index.ts               
+│   └── custom-service.ts      # 自定义服务
+│
+├── shortcuts/                 # 快捷键系统
+│   ├── index.ts               
+│   ├── constants.ts           # 快捷键常量
+│   └── utils.ts               # 快捷键工具函数
+│
+└── typings/                   # 类型定义
+    ├── index.ts               # 类型导出入口
+    ├── json-schema.ts         # JSON Schema 类型
+    └── node.ts                # 节点类型定义
+```
+
+## 架构设计分析
+
+### 整体架构模式
+
+该项目采用了**分层架构**和**模块化设计**相结合的架构模式：
+
+1. **表现层 (Presentation Layer)**
+   - 组件层：负责 UI 渲染和用户交互
+   - 工具层：提供编辑器工具功能
+
+2. **业务逻辑层 (Business Logic Layer)**
+   - 节点系统：定义各种流程节点的行为和属性
+   - 插件系统：提供可扩展的功能模块
+   - 服务层：处理业务逻辑和数据操作
+
+3. **数据层 (Data Layer)**
+   - Context 状态管理：管理应用全局状态
+   - 类型系统：确保数据结构的一致性
+
+### 核心设计模式
+
+#### 1. 提供者模式 (Provider Pattern)
+```typescript
+// 主编辑器组件使用多层 Provider 嵌套
+<FixedLayoutEditorProvider {...editorProps}>
+  <SidebarProvider>
+    <EditorRenderer />
+    <DemoTools />
+    <SidebarRenderer />
+  </SidebarProvider>
+</FixedLayoutEditorProvider>
+```
+
+**应用场景**: 
+- `FixedLayoutEditorProvider`: 提供编辑器核心功能和状态
+- `SidebarProvider`: 管理侧边栏的显示状态和选中节点
+
+#### 2. 注册表模式 (Registry Pattern)
+```typescript
+export const FlowNodeRegistries: FlowNodeRegistry[] = [
+  StartNodeRegistry,
+  EndNodeRegistry,
+  SwitchNodeRegistry,
+  LLMNodeRegistry,
+  // ... 更多节点类型
+];
+```
+
+**设计优势**:
+- 支持动态节点类型注册
+- 易于扩展新的节点类型
+- 实现了节点类型的解耦
+
+#### 3. 插件模式 (Plugin Pattern)
+```typescript
+plugins: () => [
+  createMinimapPlugin({...}),
+  createGroupPlugin({...}),
+  createClipboardPlugin(),
+  createVariablePanelPlugin({}),
+]
+```
+
+**插件系统特点**:
+- **缩略图插件**: 提供画布缩略图功能
+- **分组插件**: 支持节点分组管理
+- **剪贴板插件**: 实现复制粘贴功能
+- **变量面板插件**: 提供变量管理界面
+
+#### 4. 工厂模式 (Factory Pattern)
+在节点创建和配置中广泛使用：
+```typescript
+getNodeDefaultRegistry(type) {
+  return {
+    type,
+    meta: {
+      defaultExpanded: true,
+    },
+  };
+}
+```
+
+#### 5. 观察者模式 (Observer Pattern)
+通过历史记录系统实现：
+```typescript
+history: {
+  enable: true,
+  enableChangeNode: true,
+  onApply: debounce((ctx, opt) => {
+    console.log('auto save: ', ctx.document.toJSON());
+  }, 100),
+}
+```
+
+#### 6. 策略模式 (Strategy Pattern)
+在材料系统中体现：
+```typescript
+materials: {
+  components: {
+    ...defaultFixedSemiMaterials,
+    [FlowRendererKey.ADDER]: NodeAdder,
+    [FlowRendererKey.BRANCH_ADDER]: BranchAdder,
+    // 可根据 key 替换不同的渲染策略
+  }
+}
+```
+
+### 状态管理架构
+
+#### Context 系统设计
+项目采用了多个专用的 Context 来管理不同领域的状态：
+
+1. **SidebarContext**: 管理侧边栏状态
+```typescript
+export const SidebarContext = React.createContext<{
+  visible: boolean;
+  nodeId?: string;
+  setNodeId: (node: string | undefined) => void;
+}>({ visible: false, setNodeId: () => {} });
+```
+
+2. **NodeRenderContext**: 管理节点渲染相关状态
+3. **IsSidebarContext**: 简单的布尔状态管理
+
+#### 自定义 Hooks 设计
+- `useEditorProps`: 集中管理编辑器的所有配置属性
+- `useIsSidebar`: 判断当前是否在侧边栏环境中
+- `useNodeRenderContext`: 获取节点渲染上下文
+
+### 组件架构设计
+
+#### 组件分层结构
+1. **基础组件层**
+   - `BaseNode`: 所有节点的基础渲染组件
+   - `DragNode`: 拖拽状态下的节点组件
+
+2. **功能组件层**
+   - 添加器组件: `NodeAdder`, `BranchAdder`, `AgentAdder`
+   - 工具组件: 缩放、保存、运行等功能组件
+
+3. **容器组件层**
+   - `Sidebar`: 侧边栏容器及其子组件
+   - `Tools`: 工具栏容器
+
+### 数据流架构
+
+#### 初始数据结构
+项目定义了完整的初始流程数据，包含多种节点类型的示例：
+- **Start 节点**: 流程起始点，定义输出参数
+- **Agent 节点**: 包含 LLM、Memory、Tools 子组件
+- **LLM 节点**: 大语言模型处理节点
+- **Switch 节点**: 条件分支节点
+- **Loop 节点**: 循环处理节点
+- **TryCatch 节点**: 异常处理节点
+- **End 节点**: 流程结束点
+
+#### 数据转换机制
+```typescript
+fromNodeJSON(node, json) {
+  return json; // 数据导入时的转换逻辑
+},
+toNodeJSON(node, json) {
+  return json; // 数据导出时的转换逻辑
+}
+```

apps/demo-fixed-layout/package.json

@@ -12,7 +12,9 @@
     "index.html",
     "package.json",
     "rsbuild.config.ts",
-    "tsconfig.json"
+    "tsconfig.json",
+    "REAME.md",
+    "REAME.zh_CN.md"
   ],
   "scripts": {
     "build": "exit 0",

apps/demo-free-layout/README.zh_CN.md

@@ -0,0 +1,386 @@
+# FlowGram.AI - Demo Free Layout
+
+自由布局最佳实践 demo
+
+## 安装 
+
+```shell
+npx @flowgram.ai/create-app@latest free-layout
+```
+
+## 项目概览
+
+### 核心技术栈
+- **前端框架**: React 18 + TypeScript
+- **构建工具**: Rsbuild (基于 Rspack 的现代构建工具)
+- **样式方案**: Less + Styled Components + CSS Variables
+- **UI 组件库**: Semi Design (@douyinfe/semi-ui)
+- **状态管理**: 基于 Flowgram 自研的编辑器框架
+- **依赖注入**: Inversify
+
+### 核心依赖包
+
+- **@flowgram.ai/free-layout-editor**: 自由布局编辑器核心依赖
+- **@flowgram.ai/free-snap-plugin**: 自动对齐及辅助线插件
+- **@flowgram.ai/free-lines-plugin**: 连线渲染插件
+- **@flowgram.ai/free-node-panel-plugin**: 节点添加面板渲染插件
+- **@flowgram.ai/minimap-plugin**: 缩略图插件
+- **@flowgram.ai/free-container-plugin**: 子画布插件
+- **@flowgram.ai/free-group-plugin**: 分组插件
+- **@flowgram.ai/form-materials**: 表单物料
+- **@flowgram.ai/runtime-interface**: 运行时接口
+- **@flowgram.ai/runtime-js**: js 运行时模块
+
+## 代码说明
+
+### 目录结构
+```
+src/
+├── app.tsx                  # 应用入口文件
+├── editor.tsx               # 编辑器主组件
+├── initial-data.ts          # 初始化数据配置
+├── assets/                  # 静态资源
+├── components/              # 组件库
+│   ├── index.ts
+│   ├── add-node/            # 添加节点组件
+│   ├── base-node/           # 基础节点组件
+│   ├── comment/             # 注释组件
+│   ├── group/               # 分组组件
+│   ├── line-add-button/     # 连线添加按钮
+│   ├── node-menu/           # 节点菜单
+│   ├── node-panel/          # 节点添加面板
+│   ├── selector-box-popover/ # 选择框弹窗
+│   ├── sidebar/             # 侧边栏
+│   ├── testrun/             # 测试运行组件
+│   │   ├── hooks/           # 测试运行钩子
+│   │   ├── node-status-bar/ # 节点状态栏
+│   │   ├── testrun-button/  # 测试运行按钮
+│   │   ├── testrun-form/    # 测试运行表单
+│   │   ├── testrun-json-input/ # JSON输入组件
+│   │   └── testrun-panel/   # 测试运行面板
+│   └── tools/               # 工具组件
+├── context/                 # React Context
+│   ├── node-render-context.ts # 当前渲染节点 Context
+│   ├── sidebar-context        # 侧边栏 Context
+├── form-components/         # 表单组件库
+│   ├── form-content/        # 表单内容
+│   ├── form-header/         # 表单头部
+│   ├── form-inputs/         # 表单输入
+│   └── form-item/           # 表单项
+│   └── feedback.tsx         # 表单校验错误渲染
+├── hooks/                   
+│   ├── index.ts
+│   ├── use-editor-props.tsx # 编辑器属性钩子
+│   ├── use-is-sidebar.ts    # 侧边栏状态钩子
+│   ├── use-node-render-context.ts # 节点渲染上下文钩子
+│   └── use-port-click.ts    # 端口点击钩子
+├── nodes/                    # 节点定义
+│   ├── index.ts
+│   ├── constants.ts         # 节点常量定义
+│   ├── default-form-meta.ts # 默认表单元数据
+│   ├── block-end/           # 块结束节点
+│   ├── block-start/         # 块开始节点
+│   ├── break/               # 中断节点
+│   ├── code/                # 代码节点
+│   ├── comment/             # 注释节点
+│   ├── condition/           # 条件节点
+│   ├── continue/            # 继续节点
+│   ├── end/                 # 结束节点
+│   ├── group/               # 分组节点
+│   ├── http/                # HTTP节点
+│   ├── llm/                 # LLM节点
+│   ├── loop/                # 循环节点
+│   ├── start/               # 开始节点
+│   └── variable/            # 变量节点
+├── plugins/                 # 插件系统
+│   ├── index.ts
+│   ├── context-menu-plugin/ # 右键菜单插件
+│   ├── runtime-plugin/      # 运行时插件
+│   │   ├── client/          # 客户端
+│   │   │   ├── browser-client/ # 浏览器客户端
+│   │   │   └── server-client/  # 服务器客户端
+│   │   └── runtime-service/ # 运行时服务
+│   └── variable-panel-plugin/ # 变量面板插件
+│       └── components/      # 变量面板组件
+├── services/                 # 服务层
+│   ├── index.ts
+│   └── custom-service.ts    # 自定义服务
+├── shortcuts/                # 快捷键系统
+│   ├── index.ts
+│   ├── constants.ts         # 快捷键常量
+│   ├── shortcuts.ts         # 快捷键定义
+│   ├── type.ts              # 类型定义
+│   ├── collapse/            # 折叠快捷键
+│   ├── copy/                # 复制快捷键
+│   ├── delete/              # 删除快捷键
+│   ├── expand/              # 展开快捷键
+│   ├── paste/               # 粘贴快捷键
+│   ├── select-all/          # 全选快捷键
+│   ├── zoom-in/             # 放大快捷键
+│   └── zoom-out/            # 缩小快捷键
+├── styles/                   # 样式文件
+├── typings/                  # 类型定义
+│   ├── index.ts
+│   ├── json-schema.ts       # JSON Schema类型
+│   └── node.ts              # 节点类型定义
+└── utils/                    # 工具函数
+    ├── index.ts
+    └── on-drag-line-end.ts  # 拖拽连线结束处理
+```
+
+### 关键目录功能说明
+
+#### 1. `/components` - 组件库
+- **base-node**: 所有节点的基础渲染组件
+- **testrun**: 完整的测试运行功能模块，包含状态栏、表单、面板等
+- **sidebar**: 侧边栏组件，提供工具和属性面板
+- **node-panel**: 节点添加面板，支持拖拽添加新节点
+
+#### 2. `/nodes` - 节点系统
+每个节点类型都有独立的目录，包含：
+- 节点注册信息 (`index.ts`)
+- 表单元数据定义 (`form-meta.ts`)
+- 节点特定的组件和逻辑
+
+#### 3. `/plugins` - 插件系统
+- **runtime-plugin**: 支持浏览器和服务器两种运行模式
+- **context-menu-plugin**: 右键菜单功能
+- **variable-panel-plugin**: 变量管理面板
+
+#### 4. `/shortcuts` - 快捷键系统
+完整的快捷键支持，包括：
+- 基础操作：复制、粘贴、删除、全选
+- 视图操作：放大、缩小、折叠、展开
+- 每个快捷键都有独立的实现模块
+
+## 应用架构设计
+
+### 核心设计模式
+
+#### 1. 插件化架构 (Plugin Architecture)
+应用采用高度模块化的插件系统，每个功能都作为独立插件存在：
+
+```typescript
+plugins: () => [
+  createFreeLinesPlugin({ renderInsideLine: LineAddButton }),
+  createMinimapPlugin({ /* 配置 */ }),
+  createFreeSnapPlugin({ /* 对齐配置 */ }),
+  createFreeNodePanelPlugin({ renderer: NodePanel }),
+  createContainerNodePlugin({}),
+  createFreeGroupPlugin({ groupNodeRender: GroupNodeRender }),
+  createContextMenuPlugin({}),
+  createRuntimePlugin({ mode: 'browser' }),
+  createVariablePanelPlugin({})
+]
+```
+
+#### 2. 节点注册系统 (Node Registry Pattern)
+通过注册表模式管理不同类型的工作流节点：
+
+```typescript
+export const nodeRegistries: FlowNodeRegistry[] = [
+  ConditionNodeRegistry,    // 条件节点
+  StartNodeRegistry,        // 开始节点
+  EndNodeRegistry,          // 结束节点
+  LLMNodeRegistry,          // LLM节点
+  LoopNodeRegistry,         // 循环节点
+  CommentNodeRegistry,      // 注释节点
+  HTTPNodeRegistry,         // HTTP节点
+  CodeNodeRegistry,         // 代码节点
+  // ... 更多节点类型
+];
+```
+
+#### 3. 依赖注入模式 (Dependency Injection)
+使用 Inversify 框架实现服务的依赖注入：
+
+```typescript
+onBind: ({ bind }) => {
+  bind(CustomService).toSelf().inSingletonScope();
+}
+```
+
+## 核心功能分析
+
+### 1. 编辑器配置系统
+
+`useEditorProps` 是整个编辑器的配置中心，包含：
+
+```typescript
+export function useEditorProps(
+  initialData: FlowDocumentJSON,
+  nodeRegistries: FlowNodeRegistry[]
+): FreeLayoutProps {
+  return useMemo<FreeLayoutProps>(() => ({
+    background: true,                    // 背景网格
+    readonly: false,                     // 是否只读
+    initialData,                         // 初始数据
+    nodeRegistries,                      // 节点注册表
+    
+    // 核心功能配置
+    playground: { preventGlobalGesture: true /* 阻止 mac 浏览器手势翻页 */ },
+    nodeEngine: { enable: true },
+    variableEngine: { enable: true },
+    history: { enable: true, enableChangeNode: true },
+    
+    // 业务逻辑配置
+    canAddLine: (ctx, fromPort, toPort) => { /* 连线规则 */ },
+    canDeleteLine: (ctx, line) => { /* 删除连线规则 */ },
+    canDeleteNode: (ctx, node) => { /* 删除节点规则 */ },
+    canDropToNode: (ctx, params) => { /* 拖拽规则 */ },
+    
+    // 插件配置
+    plugins: () => [/* 插件列表 */],
+    
+    // 事件处理
+    onContentChange: debounce((ctx, event) => { /* 自动保存 */ }, 1000),
+    onInit: (ctx) => { /* 初始化 */ },
+    onAllLayersRendered: (ctx) => { /* 渲染完成 */ }
+  }), []);
+}
+```
+
+### 2. 节点类型系统
+
+应用支持多种工作流节点类型：
+
+```typescript
+export enum WorkflowNodeType {
+  Start = 'start',           // 开始节点
+  End = 'end',               // 结束节点
+  LLM = 'llm',               // 大语言模型节点
+  HTTP = 'http',             // HTTP请求节点
+  Code = 'code',             // 代码执行节点
+  Variable = 'variable',     // 变量节点
+  Condition = 'condition',   // 条件判断节点
+  Loop = 'loop',             // 循环节点
+  BlockStart = 'block-start', // 子画布开始节点
+  BlockEnd = 'block-end',    // 子画布结束节点
+  Comment = 'comment',       // 注释节点
+  Continue = 'continue',     // 继续节点
+  Break = 'break',           // 中断节点
+}
+```
+
+每个节点都遵循统一的注册模式：
+
+```typescript
+export const StartNodeRegistry: FlowNodeRegistry = {
+  type: WorkflowNodeType.Start,
+  meta: {
+    isStart: true,
+    deleteDisable: true,        // 不可删除
+    copyDisable: true,          // 不可复制
+    nodePanelVisible: false,    // 不在节点面板显示
+    defaultPorts: [{ type: 'output' }],
+    size: { width: 360, height: 211 }
+  },
+  info: {
+    icon: iconStart,
+    description: '工作流的起始节点，用于设置启动工作流所需的信息。'
+  },
+  formMeta,                     // 表单配置
+  canAdd() { return false; }    // 不允许添加多个开始节点
+};
+```
+
+### 3. 插件化架构
+
+应用的功能通过插件系统实现模块化：
+
+#### 核心插件列表
+1. **FreeLinesPlugin** - 连线渲染和交互
+2. **MinimapPlugin** - 缩略图导航
+3. **FreeSnapPlugin** - 自动对齐和辅助线
+4. **FreeNodePanelPlugin** - 节点添加面板
+5. **ContainerNodePlugin** - 容器节点（如循环节点）
+6. **FreeGroupPlugin** - 节点分组功能
+7. **ContextMenuPlugin** - 右键菜单
+8. **RuntimePlugin** - 工作流运行时
+9. **VariablePanelPlugin** - 变量管理面板
+
+### 4. 运行时系统
+
+应用支持两种运行模式：
+
+```typescript
+createRuntimePlugin({
+  mode: 'browser',              // 浏览器模式
+  // mode: 'server',            // 服务器模式
+  // serverConfig: {
+  //   domain: 'localhost',
+  //   port: 4000,
+  //   protocol: 'http',
+  // },
+})
+```
+
+## 设计理念与架构优势
+
+### 1. 高度模块化
+- **插件化架构**: 每个功能都是独立插件，易于扩展和维护
+- **节点注册系统**: 新节点类型可以轻松添加，无需修改核心代码
+- **组件化设计**: UI组件高度复用，职责清晰
+
+### 2. 类型安全
+- **完整的TypeScript支持**: 从配置到运行时的全链路类型保护
+- **JSON Schema集成**: 节点数据结构通过Schema验证
+- **强类型的插件接口**: 插件开发有明确的类型约束
+
+### 3. 用户体验优化
+- **实时预览**: 支持工作流的实时运行和调试
+- **丰富的交互**: 拖拽、缩放、对齐、快捷键等完整的编辑体验
+- **可视化反馈**: 缩略图、状态指示、连线动画等视觉反馈
+
+### 4. 扩展性设计
+- **开放的插件系统**: 第三方可以轻松开发自定义插件
+- **灵活的节点系统**: 支持自定义节点类型和表单配置
+- **多运行时支持**: 浏览器和服务器双模式运行
+
+### 5. 性能优化
+- **按需加载**: 组件和插件支持按需加载
+- **防抖处理**: 自动保存等高频操作的性能优化
+
+## 技术亮点
+
+### 1. 自研编辑器框架
+基于 `@flowgram.ai/free-layout-editor` 自研框架，提供：
+- 自由布局的画布系统
+- 完整的撤销/重做功能
+- 节点和连线的生命周期管理
+- 变量引擎和表达式系统
+
+### 2. 先进的构建配置
+使用 Rsbuild 作为构建工具：
+
+```typescript
+export default defineConfig({
+  plugins: [pluginReact(), pluginLess()],
+  source: {
+    entry: { index: './src/app.tsx' },
+    decorators: { version: 'legacy' }  // 支持装饰器
+  },
+  tools: {
+    rspack: {
+      ignoreWarnings: [/Critical dependency/]  // 忽略特定警告
+    }
+  }
+});
+```
+
+### 3. 国际化支持
+内置多语言支持：
+
+```typescript
+i18n: {
+  locale: navigator.language,
+  languages: {
+    'zh-CN': {
+      'Never Remind': '不再提示',
+      'Hold {{key}} to drag node out': '按住 {{key}} 可以将节点拖出',
+    },
+    'en-US': {},
+  }
+}
+```
+

apps/demo-free-layout/REAME.md

@@ -0,0 +1,386 @@
+# FlowGram.AI - Demo Free Layout
+
+Best-practice demo for free layout
+
+## Installation
+
+```shell
+npx @flowgram.ai/create-app@latest free-layout
+```
+
+## Project Overview
+
+### Core Tech Stack
+- **Frontend framework**: React 18 + TypeScript
+- **Build tool**: Rsbuild (a modern build tool based on Rspack)
+- **Styling**: Less + Styled Components + CSS Variables
+- **UI library**: Semi Design (@douyinfe/semi-ui)
+- **State management**: Flowgram’s in-house editor framework
+- **Dependency injection**: Inversify
+
+### Core Dependencies
+
+- **@flowgram.ai/free-layout-editor**: Core dependency for the free layout editor
+- **@flowgram.ai/free-snap-plugin**: Auto-alignment and guide-lines plugin
+- **@flowgram.ai/free-lines-plugin**: Connection line rendering plugin
+- **@flowgram.ai/free-node-panel-plugin**: Node add-panel rendering plugin
+- **@flowgram.ai/minimap-plugin**: Minimap plugin
+- **@flowgram.ai/free-container-plugin**: Sub-canvas plugin
+- **@flowgram.ai/free-group-plugin**: Grouping plugin
+- **@flowgram.ai/form-materials**: Form materials
+- **@flowgram.ai/runtime-interface**: Runtime interfaces
+- **@flowgram.ai/runtime-js**: JS runtime module
+
+## Code Guide
+
+### Directory Structure
+```
+src/
+├── app.tsx                  # Application entry file
+├── editor.tsx               # Main editor component
+├── initial-data.ts          # Initial data configuration
+├── assets/                  # Static assets
+├── components/              # Component library
+│   ├── index.ts
+│   ├── add-node/            # Add-node component
+│   ├── base-node/           # Base node components
+│   ├── comment/             # Comment components
+│   ├── group/               # Group components
+│   ├── line-add-button/     # Connection add button
+│   ├── node-menu/           # Node menu
+│   ├── node-panel/          # Node add panel
+│   ├── selector-box-popover/ # Selection box popover
+│   ├── sidebar/             # Sidebar
+│   ├── testrun/             # Test-run module
+│   │   ├── hooks/           # Test-run hooks
+│   │   ├── node-status-bar/ # Node status bar
+│   │   ├── testrun-button/  # Test-run button
+│   │   ├── testrun-form/    # Test-run form
+│   │   ├── testrun-json-input/ # JSON input component
+│   │   └── testrun-panel/   # Test-run panel
+│   └── tools/               # Utility components
+├── context/                 # React Context
+│   ├── node-render-context.ts # Current rendering node context
+│   ├── sidebar-context        # Sidebar context
+├── form-components/         # Form component library
+│   ├── form-content/        # Form content
+│   ├── form-header/         # Form header
+│   ├── form-inputs/         # Form inputs
+│   └── form-item/           # Form item
+│   └── feedback.tsx         # Validation error rendering
+├── hooks/
+│   ├── index.ts
+│   ├── use-editor-props.tsx # Editor props hook
+│   ├── use-is-sidebar.ts    # Sidebar state hook
+│   ├── use-node-render-context.ts # Node render context hook
+│   └── use-port-click.ts    # Port click hook
+├── nodes/                    # Node definitions
+│   ├── index.ts
+│   ├── constants.ts         # Node constants
+│   ├── default-form-meta.ts # Default form metadata
+│   ├── block-end/           # Block end node
+│   ├── block-start/         # Block start node
+│   ├── break/               # Break node
+│   ├── code/                # Code node
+│   ├── comment/             # Comment node
+│   ├── condition/           # Condition node
+│   ├── continue/            # Continue node
+│   ├── end/                 # End node
+│   ├── group/               # Group node
+│   ├── http/                # HTTP node
+│   ├── llm/                 # LLM node
+│   ├── loop/                # Loop node
+│   ├── start/               # Start node
+│   └── variable/            # Variable node
+├── plugins/                 # Plugin system
+│   ├── index.ts
+│   ├── context-menu-plugin/ # Right-click context menu plugin
+│   ├── runtime-plugin/      # Runtime plugin
+│   │   ├── client/          # Client
+│   │   │   ├── browser-client/ # Browser client
+│   │   │   └── server-client/  # Server client
+│   │   └── runtime-service/ # Runtime service
+│   └── variable-panel-plugin/ # Variable panel plugin
+│       └── components/      # Variable panel components
+├── services/                 # Service layer
+│   ├── index.ts
+│   └── custom-service.ts    # Custom service
+├── shortcuts/                # Shortcuts system
+│   ├── index.ts
+│   ├── constants.ts         # Shortcut constants
+│   ├── shortcuts.ts         # Shortcut definitions
+│   ├── type.ts              # Type definitions
+│   ├── collapse/            # Collapse shortcut
+│   ├── copy/                # Copy shortcut
+│   ├── delete/              # Delete shortcut
+│   ├── expand/              # Expand shortcut
+│   ├── paste/               # Paste shortcut
+│   ├── select-all/          # Select-all shortcut
+│   ├── zoom-in/             # Zoom-in shortcut
+│   └── zoom-out/            # Zoom-out shortcut
+├── styles/                   # Styles
+├── typings/                  # Type definitions
+│   ├── index.ts
+│   ├── json-schema.ts       # JSON Schema types
+│   └── node.ts              # Node type definitions
+└── utils/                    # Utility functions
+    ├── index.ts
+    └── on-drag-line-end.ts  # Handle end of drag line
+```
+
+### Key Directory Functions
+
+#### 1. `/components` - Component Library
+- **base-node**: Base rendering components for all nodes
+- **testrun**: Complete test-run module, including status bar, form, and panel
+- **sidebar**: Sidebar components providing tools and property panels
+- **node-panel**: Node add panel with drag-to-add capability
+
+#### 2. `/nodes` - Node System
+Each node type has its own directory, including:
+- Node registration (`index.ts`)
+- Form metadata (`form-meta.ts`)
+- Node-specific components and logic
+
+#### 3. `/plugins` - Plugin System
+- **runtime-plugin**: Supports both browser and server modes
+- **context-menu-plugin**: Right-click context menu
+- **variable-panel-plugin**: Variable management panel
+
+#### 4. `/shortcuts` - Shortcuts System
+Complete keyboard shortcut support, including:
+- Basic actions: copy, paste, delete, select-all
+- View actions: zoom-in, zoom-out, collapse, expand
+- Each shortcut has its own implementation module
+
+## Application Architecture
+
+### Core Design Patterns
+
+#### 1. Plugin Architecture
+Highly modular plugin system; each feature is an independent plugin:
+
+```typescript
+plugins: () => [
+  createFreeLinesPlugin({ renderInsideLine: LineAddButton }),
+  createMinimapPlugin({ /* config */ }),
+  createFreeSnapPlugin({ /* alignment config */ }),
+  createFreeNodePanelPlugin({ renderer: NodePanel }),
+  createContainerNodePlugin({}),
+  createFreeGroupPlugin({ groupNodeRender: GroupNodeRender }),
+  createContextMenuPlugin({}),
+  createRuntimePlugin({ mode: 'browser' }),
+  createVariablePanelPlugin({})
+]
+```
+
+#### 2. Node Registry Pattern
+Manage different workflow node types via a registry:
+
+```typescript
+export const nodeRegistries: FlowNodeRegistry[] = [
+  ConditionNodeRegistry,    // Condition node
+  StartNodeRegistry,        // Start node
+  EndNodeRegistry,          // End node
+  LLMNodeRegistry,          // LLM node
+  LoopNodeRegistry,         // Loop node
+  CommentNodeRegistry,      // Comment node
+  HTTPNodeRegistry,         // HTTP node
+  CodeNodeRegistry,         // Code node
+  // ... more node types
+];
+```
+
+#### 3. Dependency Injection
+Use Inversify for service DI:
+
+```typescript
+onBind: ({ bind }) => {
+  bind(CustomService).toSelf().inSingletonScope();
+}
+```
+
+## Core Features
+
+### 1. Editor Configuration System
+
+`useEditorProps` is the configuration center of the editor:
+
+```typescript
+export function useEditorProps(
+  initialData: FlowDocumentJSON,
+  nodeRegistries: FlowNodeRegistry[]
+): FreeLayoutProps {
+  return useMemo<FreeLayoutProps>(() => ({
+    background: true,                    // Background grid
+    readonly: false,                     // Readonly mode
+    initialData,                         // Initial data
+    nodeRegistries,                      // Node registries
+
+    // Core feature configs
+    playground: { preventGlobalGesture: true /* Prevent Mac browser swipe gestures */ },
+    nodeEngine: { enable: true },
+    variableEngine: { enable: true },
+    history: { enable: true, enableChangeNode: true },
+
+    // Business rules
+    canAddLine: (ctx, fromPort, toPort) => { /* Connection rules */ },
+    canDeleteLine: (ctx, line) => { /* Line deletion rules */ },
+    canDeleteNode: (ctx, node) => { /* Node deletion rules */ },
+    canDropToNode: (ctx, params) => { /* Drag-and-drop rules */ },
+
+    // Plugins
+    plugins: () => [/* Plugin list */],
+
+    // Events
+    onContentChange: debounce((ctx, event) => { /* Auto save */ }, 1000),
+    onInit: (ctx) => { /* Initialization */ },
+    onAllLayersRendered: (ctx) => { /* After render */ }
+  }), []);
+}
+```
+
+### 2. Node Type System
+
+The app supports multiple workflow node types:
+
+```typescript
+export enum WorkflowNodeType {
+  Start = 'start',           // Start node
+  End = 'end',               // End node
+  LLM = 'llm',               // Large language model node
+  HTTP = 'http',             // HTTP request node
+  Code = 'code',             // Code execution node
+  Variable = 'variable',     // Variable node
+  Condition = 'condition',   // Conditional node
+  Loop = 'loop',             // Loop node
+  BlockStart = 'block-start', // Sub-canvas start node
+  BlockEnd = 'block-end',    // Sub-canvas end node
+  Comment = 'comment',       // Comment node
+  Continue = 'continue',     // Continue node
+  Break = 'break',           // Break node
+}
+```
+
+Each node follows a unified registration pattern:
+
+```typescript
+export const StartNodeRegistry: FlowNodeRegistry = {
+  type: WorkflowNodeType.Start,
+  meta: {
+    isStart: true,
+    deleteDisable: true,        // Not deletable
+    copyDisable: true,          // Not copyable
+    nodePanelVisible: false,    // Hidden in node panel
+    defaultPorts: [{ type: 'output' }],
+    size: { width: 360, height: 211 }
+  },
+  info: {
+    icon: iconStart,
+    description: 'The starting node of the workflow, used to set up information needed to launch the workflow.'
+  },
+  formMeta,                     // Form configuration
+  canAdd() { return false; }    // Disallow multiple start nodes
+};
+```
+
+### 3. Plugin Architecture
+
+App features are modularized via the plugin system:
+
+#### Core Plugin List
+1. **FreeLinesPlugin** - Connection rendering and interaction
+2. **MinimapPlugin** - Minimap navigation
+3. **FreeSnapPlugin** - Auto-alignment and guide-lines
+4. **FreeNodePanelPlugin** - Node add panel
+5. **ContainerNodePlugin** - Container nodes (e.g., loop nodes)
+6. **FreeGroupPlugin** - Node grouping
+7. **ContextMenuPlugin** - Right-click context menu
+8. **RuntimePlugin** - Workflow runtime
+9. **VariablePanelPlugin** - Variable management panel
+
+### 4. Runtime System
+
+Two run modes are supported:
+
+```typescript
+createRuntimePlugin({
+  mode: 'browser',              // Browser mode
+  // mode: 'server',            // Server mode
+  // serverConfig: {
+  //   domain: 'localhost',
+  //   port: 4000,
+  //   protocol: 'http',
+  // },
+})
+```
+
+## Design Philosophy and Advantages
+
+### 1. Highly Modular
+- **Plugin architecture**: Each feature is an independent plugin, easy to extend and maintain
+- **Node registry system**: Add new node types without changing core code
+- **Componentized UI**: Highly reusable components with clear responsibilities
+
+### 2. Type Safety
+- **Full TypeScript support**: End-to-end type safety from configuration to runtime
+- **JSON Schema integration**: Node data validated by schemas
+- **Strongly typed plugin interfaces**: Clear type constraints for plugin development
+
+### 3. User Experience
+- **Real-time preview**: Run and debug workflows live
+- **Rich interactions**: Dragging, zooming, snapping, shortcuts for a complete editing experience
+- **Visual feedback**: Minimap, status indicators, line animations
+
+### 4. Extensibility
+- **Open plugin system**: Third parties can easily develop custom plugins
+- **Flexible node system**: Custom node types and form configurations supported
+- **Multiple runtimes**: Both browser and server modes
+
+### 5. Performance
+- **On-demand loading**: Components and plugins support lazy loading
+- **Debounce**: Performance optimizations for high-frequency operations like auto-save
+
+## Technical Highlights
+
+### 1. In-house Editor Framework
+Based on `@flowgram.ai/free-layout-editor`, providing:
+- Free-layout canvas system
+- Full undo/redo functionality
+- Lifecycle management for nodes and connections
+- Variable engine and expression system
+
+### 2. Advanced Build Configuration
+Using Rsbuild as the build tool:
+
+```typescript
+export default defineConfig({
+  plugins: [pluginReact(), pluginLess()],
+  source: {
+    entry: { index: './src/app.tsx' },
+    decorators: { version: 'legacy' }  // Enable decorators
+  },
+  tools: {
+    rspack: {
+      ignoreWarnings: [/Critical dependency/]  // Ignore specific warnings
+    }
+  }
+});
+```
+
+### 3. Internationalization
+Built-in multilingual support:
+
+```typescript
+i18n: {
+  locale: navigator.language,
+  languages: {
+    'zh-CN': {
+      'Never Remind': '不再提示',
+      'Hold {{key}} to drag node out': '按住 {{key}} 可以将节点拖出',
+    },
+    'en-US': {},
+  }
+}
+```
+

apps/demo-free-layout/package.json

@@ -13,7 +13,8 @@
     "package.json",
     "rsbuild.config.ts",
     "tsconfig.json",
-    "README.md"
+    "REAME.md",
+    "REAME.zh_CN.md"
   ],
   "scripts": {
     "build": "exit 0",

apps/docs/src/en/examples/fixed-layout/fixed-feature-overview.mdx

@@ -19,75 +19,365 @@ npx @flowgram.ai/create-app@latest fixed-layout
 
 https://github.com/bytedance/flowgram.ai/tree/main/apps/demo-fixed-layout
 
-## Feature Introduction
-
-<table className="rs-table">
-  <tr>
-    <td>Minimap</td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/minimap.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>Undo/Redo</td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/redo-undo.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>Copy/Paste (Support Shortcut)</td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/copypaste.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>
-        <div>Box Selection + Drag</div>
-      </div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <div className="rs-center">
-          <img loading="lazy" src="/fixed-layout/dragdrop.gif"  />
-        </div>
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>Horizontal/Vertical Layout Switch</div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/layout-change.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>Branch Fold</div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/fold.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>Group</div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/group.gif"  />
-      </div>
-    </td>
-  </tr>
-</table>
+## Project Overview
+
+### Core Tech Stack
+- Frontend Framework: React 18 + TypeScript
+- Build Tool: Rsbuild (a modern build tool based on Rspack)
+- Styling: Less + Styled Components + CSS Variables
+- UI Component Library: Semi Design (@douyinfe/semi-ui)
+- State Management: Editor framework developed in-house by Flowgram
+- Dependency Injection: Inversify
+
+
+### Core Dependencies
+
+- @flowgram.ai/fixed-layout-editor: Core dependency for the fixed-layout editor
+- @flowgram.ai/fixed-semi-materials: Semi Design materials library
+- @flowgram.ai/form-materials: Form materials library
+- @flowgram.ai/group-plugin: Group plugin
+- @flowgram.ai/minimap-plugin: Minimap plugin
+
+## Code Overview
+
+```
+src/
+├── app.tsx                    # Application entry component
+├── editor.tsx                 # Main editor component
+├── index.ts                   # Module export entry
+├── initial-data.ts            # Initial data configuration
+├── type.d.ts                  # Global type declarations
+│
+├── assets/                    # Static assets
+│   ├── icon-mouse.tsx         # Mouse icon component
+│   └── icon-pad.tsx           # Trackpad icon component
+│
+├── components/                # Common components library
+│   ├── index.ts               # Components export entry
+│   ├── node-list.tsx          # Node list component
+│   │
+│   ├── agent-adder/           # Agent adder component
+│   │   └── index.tsx
+│   ├── agent-label/           # Agent label component
+│   │   └── index.tsx
+│   ├── base-node/             # Base node component
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── branch-adder/          # Branch adder component
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── drag-node/             # Draggable node component
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── node-adder/            # Node adder component
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   └── utils.ts
+│   ├── selector-box-popover/  # Selection box popover component
+│   │   └── index.tsx
+│   ├── sidebar/               # Sidebar components
+│   │   ├── index.tsx
+│   │   ├── sidebar-node-renderer.tsx
+│   │   ├── sidebar-provider.tsx
+│   │   └── sidebar-renderer.tsx
+│   └── tools/                 # Toolbar components
+│       ├── index.tsx
+│       ├── styles.tsx
+│       ├── fit-view.tsx       # Fit view tool
+│       ├── minimap-switch.tsx # Minimap toggle
+│       ├── minimap.tsx        # Minimap component
+│       ├── readonly.tsx       # Readonly mode toggle
+│       ├── run.tsx            # Run tool
+│       ├── save.tsx           # Save tool
+│       ├── switch-vertical.tsx # Vertical layout toggle
+│       └── zoom-select.tsx    # Zoom selector
+│
+├── context/                   # React Context state management
+│   ├── index.ts               # Context export entry
+│   ├── node-render-context.ts # Node render context
+│   └── sidebar-context.ts     # Sidebar context
+│
+├── form-components/           # Form components library
+│   ├── index.ts               # Export entry for form components
+│   ├── feedback.tsx           # Feedback component
+│   │
+│   ├── form-content/          # Form content components
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-header/           # Form header components
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   ├── title-input.tsx
+│   │   └── utils.tsx
+│   ├── form-inputs/           # Form input components
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-item/             # Form item component
+│   │   ├── index.css
+│   │   └── index.tsx
+│   ├── form-outputs/          # Form output components
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   └── properties-edit/       # Property editing components
+│       ├── index.tsx
+│       ├── property-edit.tsx
+│       └── styles.tsx
+│
+├── hooks/                     # Custom React hooks
+│   ├── index.ts               # Hooks export entry
+│   ├── use-editor-props.ts    # Hook for editor properties
+│   ├── use-is-sidebar.ts      # Hook for sidebar state
+│   └── use-node-render-context.ts # Hook for node render context
+│
+├── nodes/                     # Flow node definitions
+│   ├── index.ts               # Node registry
+│   ├── default-form-meta.tsx  # Default form metadata
+│   │
+│   ├── agent/                 # Agent node type
+│   │   ├── index.ts
+│   │   ├── agent.ts
+│   │   ├── agent-llm.ts
+│   │   ├── agent-memory.ts
+│   │   ├── agent-tools.ts
+│   │   ├── memory.ts
+│   │   └── tool.ts
+│   ├── break-loop/            # Break loop node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case/                  # Case branch node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case-default/          # Default case node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── catch-block/           # Exception catch block node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── end/                   # End node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── if/                    # Conditional node
+│   │   └── index.ts
+│   ├── if-block/              # Conditional block node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── llm/                   # LLM node
+│   │   └── index.ts
+│   ├── loop/                  # Loop node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── start/                 # Start node
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── switch/                # Switch branch node
+│   │   └── index.ts
+│   └── trycatch/              # Try-Catch node
+│       ├── index.ts
+│       └── form-meta.tsx
+│
+├── plugins/                   # Plugin system
+│   ├── index.ts               # Plugins export entry
+│   │
+│   ├── clipboard-plugin/      # Clipboard plugin
+│   │   └── create-clipboard-plugin.ts
+│   ├── group-plugin/          # Group plugin
+│   │   ├── index.ts
+│   │   ├── group-box-header.tsx
+│   │   ├── group-node.tsx
+│   │   ├── group-note.tsx
+│   │   ├── group-tools.tsx
+│   │   ├── icons/
+│   │   │   └── index.tsx
+│   │   └── multilang-textarea-editor/ # Multi-language textarea editor
+│   │       ├── index.css
+│   │       ├── index.tsx
+│   │       └── base-textarea.tsx
+│   └── variable-panel-plugin/ # Variable panel plugin
+│       ├── index.ts
+│       ├── variable-panel-layer.tsx
+│       ├── variable-panel-plugin.ts
+│       └── components/
+│           ├── full-variable-list.tsx
+│           ├── global-variable-editor.tsx
+│           └── variable-panel.tsx
+│
+├── services/                  # Services layer
+│   ├── index.ts
+│   └── custom-service.ts      # Custom service
+│
+├── shortcuts/                 # Shortcuts system
+│   ├── index.ts
+│   ├── constants.ts           # Shortcut constants
+│   └── utils.ts               # Shortcut utilities
+│
+└── typings/                   # Type definitions
+    ├── index.ts               # Types export entry
+    ├── json-schema.ts         # JSON Schema types
+    └── node.ts                # Node type definitions
+```
+
+## Architecture Design Analysis
+
+### Overall Architecture Pattern
+
+This project adopts a layered architecture combined with modular design:
+
+1. Presentation Layer
+ - Component layer: responsible for UI rendering and user interactions
+ - Tools layer: provides editor tool features
+
+2. Business Logic Layer
+ - Node system: defines the behavior and properties of various flow nodes
+ - Plugin system: provides extensible functional modules
+ - Services layer: handles business logic and data operations
+
+3. Data Layer
+ - Context state management: manages global application state
+ - Type system: ensures consistency of data structures
+
+### Key Design Patterns
+
+#### 1. Provider Pattern
+```typescript
+// The main editor component uses multiple nested Providers
+<FixedLayoutEditorProvider {...editorProps}>
+  <SidebarProvider>
+    <EditorRenderer />
+    <DemoTools />
+    <SidebarRenderer />
+  </SidebarProvider>
+  </FixedLayoutEditorProvider>
+```
+
+Use cases:
+- `FixedLayoutEditorProvider`: provides core editor features and state
+- `SidebarProvider`: manages sidebar visibility and the selected node
+
+#### 2. Registry Pattern
+```typescript
+export const FlowNodeRegistries: FlowNodeRegistry[] = [
+  StartNodeRegistry,
+  EndNodeRegistry,
+  SwitchNodeRegistry,
+  LLMNodeRegistry,
+  // ... more node types
+];
+```
+
+Advantages:
+- Supports dynamic registration of node types
+- Easy to extend with new node types
+- Decouples node type definitions
+
+#### 3. Plugin Pattern
+```typescript
+plugins: () => [
+  createMinimapPlugin({...}),
+  createGroupPlugin({...}),
+  createClipboardPlugin(),
+  createVariablePanelPlugin({}),
+]
+```
+
+Plugin system highlights:
+- Minimap plugin: provides a canvas minimap
+- Group plugin: supports node grouping and management
+- Clipboard plugin: enables copy and paste
+- Variable panel plugin: provides a UI for variable management
+
+#### 4. Factory Pattern
+Widely used in node creation and configuration:
+```typescript
+getNodeDefaultRegistry(type) {
+  return {
+    type,
+    meta: {
+      defaultExpanded: true,
+    },
+  };
+}
+```
+
+#### 5. Observer Pattern
+Implemented via the history system:
+```typescript
+history: {
+  enable: true,
+  enableChangeNode: true,
+  onApply: debounce((ctx, opt) => {
+    console.log('auto save: ', ctx.document.toJSON());
+  }, 100),
+}
+```
+
+#### 6. Strategy Pattern
+Reflected in the materials system:
+```typescript
+materials: {
+  components: {
+    ...defaultFixedSemiMaterials,
+    [FlowRendererKey.ADDER]: NodeAdder,
+    [FlowRendererKey.BRANCH_ADDER]: BranchAdder,
+    // Different render strategies can be swapped by key
+  }
+}
+```
+
+### State Management Architecture
+
+#### Context System Design
+The project uses multiple dedicated Contexts to manage different domains of state:
+
+1. SidebarContext: manages sidebar state
+```typescript
+export const SidebarContext = React.createContext<{
+  visible: boolean;
+  nodeId?: string;
+  setNodeId: (node: string | undefined) => void;
+}>({ visible: false, setNodeId: () => {} });
+```
+
+2. NodeRenderContext: manages state related to node rendering
+3. IsSidebarContext: simple boolean state
+
+#### Custom Hooks
+- `useEditorProps`: centralizes all editor configuration props
+- `useIsSidebar`: determines whether the current environment is the sidebar
+- `useNodeRenderContext`: gets the node render context
+
+### Component Architecture
+
+#### Component Layering
+1. Base components
+ - `BaseNode`: base rendering component for all nodes
+ - `DragNode`: node component in drag state
+
+2. Functional components
+ - Adders: `NodeAdder`, `BranchAdder`, `AgentAdder`
+ - Tools: zoom, save, run, and other utilities
+
+3. Container components
+ - `Sidebar`: sidebar container and its subcomponents
+ - `Tools`: toolbar container
+
+### Data Flow Architecture
+
+#### Initial Data Structure
+The project defines a complete initial flow dataset, including examples of multiple node types:
+- Start node: entry point of the flow, defines output parameters
+- Agent node: contains LLM, Memory, and Tools subcomponents
+- LLM node: large language model processing node
+- Switch node: conditional branch node
+- Loop node: loop processing node
+- TryCatch node: exception handling node
+- End node: end of the flow
+
+#### Data Transformation Mechanism
+```typescript
+fromNodeJSON(node, json) {
+  return json; // Transform logic on data import
+},
+toNodeJSON(node, json) {
+  return json; // Transform logic on data export
+}
+```

apps/docs/src/en/examples/free-layout/free-feature-overview.mdx

@@ -19,28 +19,379 @@ npx @flowgram.ai/create-app@latest free-layout
 
 https://github.com/bytedance/flowgram.ai/tree/main/apps/demo-free-layout
 
+## Project Overview
+
+### Core Tech Stack
+- **Frontend framework**: React 18 + TypeScript
+- **Build tool**: Rsbuild (a modern build tool based on Rspack)
+- **Styling**: Less + Styled Components + CSS Variables
+- **UI library**: Semi Design (@douyinfe/semi-ui)
+- **State management**: Flowgram’s in-house editor framework
+- **Dependency injection**: Inversify
+
+### Core Dependencies
+
+- **@flowgram.ai/free-layout-editor**: Core dependency for the free layout editor
+- **@flowgram.ai/free-snap-plugin**: Auto-alignment and guide-lines plugin
+- **@flowgram.ai/free-lines-plugin**: Connection line rendering plugin
+- **@flowgram.ai/free-node-panel-plugin**: Node add-panel rendering plugin
+- **@flowgram.ai/minimap-plugin**: Minimap plugin
+- **@flowgram.ai/free-container-plugin**: Sub-canvas plugin
+- **@flowgram.ai/free-group-plugin**: Grouping plugin
+- **@flowgram.ai/form-materials**: Form materials
+- **@flowgram.ai/runtime-interface**: Runtime interfaces
+- **@flowgram.ai/runtime-js**: JS runtime module
+
+## Code Guide
+
+### Directory Structure
+```
+src/
+├── app.tsx                  # Application entry file
+├── editor.tsx               # Main editor component
+├── initial-data.ts          # Initial data configuration
+├── assets/                  # Static assets
+├── components/              # Component library
+│   ├── index.ts
+│   ├── add-node/            # Add-node component
+│   ├── base-node/           # Base node components
+│   ├── comment/             # Comment components
+│   ├── group/               # Group components
+│   ├── line-add-button/     # Connection add button
+│   ├── node-menu/           # Node menu
+│   ├── node-panel/          # Node add panel
+│   ├── selector-box-popover/ # Selection box popover
+│   ├── sidebar/             # Sidebar
+│   ├── testrun/             # Test-run module
+│   │   ├── hooks/           # Test-run hooks
+│   │   ├── node-status-bar/ # Node status bar
+│   │   ├── testrun-button/  # Test-run button
+│   │   ├── testrun-form/    # Test-run form
+│   │   ├── testrun-json-input/ # JSON input component
+│   │   └── testrun-panel/   # Test-run panel
+│   └── tools/               # Utility components
+├── context/                 # React Context
+│   ├── node-render-context.ts # Current rendering node context
+│   ├── sidebar-context        # Sidebar context
+├── form-components/         # Form component library
+│   ├── form-content/        # Form content
+│   ├── form-header/         # Form header
+│   ├── form-inputs/         # Form inputs
+│   └── form-item/           # Form item
+│   └── feedback.tsx         # Validation error rendering
+├── hooks/
+│   ├── index.ts
+│   ├── use-editor-props.tsx # Editor props hook
+│   ├── use-is-sidebar.ts    # Sidebar state hook
+│   ├── use-node-render-context.ts # Node render context hook
+│   └── use-port-click.ts    # Port click hook
+├── nodes/                    # Node definitions
+│   ├── index.ts
+│   ├── constants.ts         # Node constants
+│   ├── default-form-meta.ts # Default form metadata
+│   ├── block-end/           # Block end node
+│   ├── block-start/         # Block start node
+│   ├── break/               # Break node
+│   ├── code/                # Code node
+│   ├── comment/             # Comment node
+│   ├── condition/           # Condition node
+│   ├── continue/            # Continue node
+│   ├── end/                 # End node
+│   ├── group/               # Group node
+│   ├── http/                # HTTP node
+│   ├── llm/                 # LLM node
+│   ├── loop/                # Loop node
+│   ├── start/               # Start node
+│   └── variable/            # Variable node
+├── plugins/                 # Plugin system
+│   ├── index.ts
+│   ├── context-menu-plugin/ # Right-click context menu plugin
+│   ├── runtime-plugin/      # Runtime plugin
+│   │   ├── client/          # Client
+│   │   │   ├── browser-client/ # Browser client
+│   │   │   └── server-client/  # Server client
+│   │   └── runtime-service/ # Runtime service
+│   └── variable-panel-plugin/ # Variable panel plugin
+│       └── components/      # Variable panel components
+├── services/                 # Service layer
+│   ├── index.ts
+│   └── custom-service.ts    # Custom service
+├── shortcuts/                # Shortcuts system
+│   ├── index.ts
+│   ├── constants.ts         # Shortcut constants
+│   ├── shortcuts.ts         # Shortcut definitions
+│   ├── type.ts              # Type definitions
+│   ├── collapse/            # Collapse shortcut
+│   ├── copy/                # Copy shortcut
+│   ├── delete/              # Delete shortcut
+│   ├── expand/              # Expand shortcut
+│   ├── paste/               # Paste shortcut
+│   ├── select-all/          # Select-all shortcut
+│   ├── zoom-in/             # Zoom-in shortcut
+│   └── zoom-out/            # Zoom-out shortcut
+├── styles/                   # Styles
+├── typings/                  # Type definitions
+│   ├── index.ts
+│   ├── json-schema.ts       # JSON Schema types
+│   └── node.ts              # Node type definitions
+└── utils/                    # Utility functions
+    ├── index.ts
+    └── on-drag-line-end.ts  # Handle end of drag line
+```
+
+### Key Directory Functions
+
+#### 1. `/components` - Component Library
+- **base-node**: Base rendering components for all nodes
+- **testrun**: Complete test-run module, including status bar, form, and panel
+- **sidebar**: Sidebar components providing tools and property panels
+- **node-panel**: Node add panel with drag-to-add capability
+
+#### 2. `/nodes` - Node System
+Each node type has its own directory, including:
+- Node registration (`index.ts`)
+- Form metadata (`form-meta.ts`)
+- Node-specific components and logic
+
+#### 3. `/plugins` - Plugin System
+- **runtime-plugin**: Supports both browser and server modes
+- **context-menu-plugin**: Right-click context menu
+- **variable-panel-plugin**: Variable management panel
+
+#### 4. `/shortcuts` - Shortcuts System
+Complete keyboard shortcut support, including:
+- Basic actions: copy, paste, delete, select-all
+- View actions: zoom-in, zoom-out, collapse, expand
+- Each shortcut has its own implementation module
+
+## Application Architecture
+
+### Core Design Patterns
+
+#### 1. Plugin Architecture
+Highly modular plugin system; each feature is an independent plugin:
+
+```typescript
+plugins: () => [
+  createFreeLinesPlugin({ renderInsideLine: LineAddButton }),
+  createMinimapPlugin({ /* config */ }),
+  createFreeSnapPlugin({ /* alignment config */ }),
+  createFreeNodePanelPlugin({ renderer: NodePanel }),
+  createContainerNodePlugin({}),
+  createFreeGroupPlugin({ groupNodeRender: GroupNodeRender }),
+  createContextMenuPlugin({}),
+  createRuntimePlugin({ mode: 'browser' }),
+  createVariablePanelPlugin({})
+]
+```
+
+#### 2. Node Registry Pattern
+Manage different workflow node types via a registry:
+
+```typescript
+export const nodeRegistries: FlowNodeRegistry[] = [
+  ConditionNodeRegistry,    // Condition node
+  StartNodeRegistry,        // Start node
+  EndNodeRegistry,          // End node
+  LLMNodeRegistry,          // LLM node
+  LoopNodeRegistry,         // Loop node
+  CommentNodeRegistry,      // Comment node
+  HTTPNodeRegistry,         // HTTP node
+  CodeNodeRegistry,         // Code node
+  // ... more node types
+];
+```
+
+#### 3. Dependency Injection
+Use Inversify for service DI:
+
+```typescript
+onBind: ({ bind }) => {
+  bind(CustomService).toSelf().inSingletonScope();
+}
+```
+
+## Core Features
+
+### 1. Editor Configuration System
+
+`useEditorProps` is the configuration center of the editor:
+
+```typescript
+export function useEditorProps(
+  initialData: FlowDocumentJSON,
+  nodeRegistries: FlowNodeRegistry[]
+): FreeLayoutProps {
+  return useMemo<FreeLayoutProps>(() => ({
+    background: true,                    // Background grid
+    readonly: false,                     // Readonly mode
+    initialData,                         // Initial data
+    nodeRegistries,                      // Node registries
+
+    // Core feature configs
+    playground: { preventGlobalGesture: true /* Prevent Mac browser swipe gestures */ },
+    nodeEngine: { enable: true },
+    variableEngine: { enable: true },
+    history: { enable: true, enableChangeNode: true },
+
+    // Business rules
+    canAddLine: (ctx, fromPort, toPort) => { /* Connection rules */ },
+    canDeleteLine: (ctx, line) => { /* Line deletion rules */ },
+    canDeleteNode: (ctx, node) => { /* Node deletion rules */ },
+    canDropToNode: (ctx, params) => { /* Drag-and-drop rules */ },
+
+    // Plugins
+    plugins: () => [/* Plugin list */],
+
+    // Events
+    onContentChange: debounce((ctx, event) => { /* Auto save */ }, 1000),
+    onInit: (ctx) => { /* Initialization */ },
+    onAllLayersRendered: (ctx) => { /* After render */ }
+  }), []);
+}
+```
+
+### 2. Node Type System
+
+The app supports multiple workflow node types:
+
+```typescript
+export enum WorkflowNodeType {
+  Start = 'start',           // Start node
+  End = 'end',               // End node
+  LLM = 'llm',               // Large language model node
+  HTTP = 'http',             // HTTP request node
+  Code = 'code',             // Code execution node
+  Variable = 'variable',     // Variable node
+  Condition = 'condition',   // Conditional node
+  Loop = 'loop',             // Loop node
+  BlockStart = 'block-start', // Sub-canvas start node
+  BlockEnd = 'block-end',    // Sub-canvas end node
+  Comment = 'comment',       // Comment node
+  Continue = 'continue',     // Continue node
+  Break = 'break',           // Break node
+}
+```
+
+Each node follows a unified registration pattern:
+
+```typescript
+export const StartNodeRegistry: FlowNodeRegistry = {
+  type: WorkflowNodeType.Start,
+  meta: {
+    isStart: true,
+    deleteDisable: true,        // Not deletable
+    copyDisable: true,          // Not copyable
+    nodePanelVisible: false,    // Hidden in node panel
+    defaultPorts: [{ type: 'output' }],
+    size: { width: 360, height: 211 }
+  },
+  info: {
+    icon: iconStart,
+    description: 'The starting node of the workflow, used to set up information needed to launch the workflow.'
+  },
+  formMeta,                     // Form configuration
+  canAdd() { return false; }    // Disallow multiple start nodes
+};
+```
+
+### 3. Plugin Architecture
+
+App features are modularized via the plugin system:
+
+#### Core Plugin List
+1. **FreeLinesPlugin** - Connection rendering and interaction
+2. **MinimapPlugin** - Minimap navigation
+3. **FreeSnapPlugin** - Auto-alignment and guide-lines
+4. **FreeNodePanelPlugin** - Node add panel
+5. **ContainerNodePlugin** - Container nodes (e.g., loop nodes)
+6. **FreeGroupPlugin** - Node grouping
+7. **ContextMenuPlugin** - Right-click context menu
+8. **RuntimePlugin** - Workflow runtime
+9. **VariablePanelPlugin** - Variable management panel
+
+### 4. Runtime System
+
+Two run modes are supported:
+
+```typescript
+createRuntimePlugin({
+  mode: 'browser',              // Browser mode
+  // mode: 'server',            // Server mode
+  // serverConfig: {
+  //   domain: 'localhost',
+  //   port: 4000,
+  //   protocol: 'http',
+  // },
+})
+```
+
+## Design Philosophy and Advantages
+
+### 1. Highly Modular
+- **Plugin architecture**: Each feature is an independent plugin, easy to extend and maintain
+- **Node registry system**: Add new node types without changing core code
+- **Componentized UI**: Highly reusable components with clear responsibilities
+
+### 2. Type Safety
+- **Full TypeScript support**: End-to-end type safety from configuration to runtime
+- **JSON Schema integration**: Node data validated by schemas
+- **Strongly typed plugin interfaces**: Clear type constraints for plugin development
+
+### 3. User Experience
+- **Real-time preview**: Run and debug workflows live
+- **Rich interactions**: Dragging, zooming, snapping, shortcuts for a complete editing experience
+- **Visual feedback**: Minimap, status indicators, line animations
+
+### 4. Extensibility
+- **Open plugin system**: Third parties can easily develop custom plugins
+- **Flexible node system**: Custom node types and form configurations supported
+- **Multiple runtimes**: Both browser and server modes
+
+### 5. Performance
+- **On-demand loading**: Components and plugins support lazy loading
+- **Debounce**: Performance optimizations for high-frequency operations like auto-save
+
+## Technical Highlights
+
+### 1. In-house Editor Framework
+Based on `@flowgram.ai/free-layout-editor`, providing:
+- Free-layout canvas system
+- Full undo/redo functionality
+- Lifecycle management for nodes and connections
+- Variable engine and expression system
+
+### 2. Advanced Build Configuration
+Using Rsbuild as the build tool:
+
+```typescript
+export default defineConfig({
+  plugins: [pluginReact(), pluginLess()],
+  source: {
+    entry: { index: './src/app.tsx' },
+    decorators: { version: 'legacy' }  // Enable decorators
+  },
+  tools: {
+    rspack: {
+      ignoreWarnings: [/Critical dependency/]  // Ignore specific warnings
+    }
+  }
+});
+```
+
+### 3. Internationalization
+Built-in multilingual support:
+
+```typescript
+i18n: {
+  locale: navigator.language,
+  languages: {
+    'zh-CN': {
+      'Never Remind': '不再提示',
+      'Hold {{key}} to drag node out': '按住 {{key}} 可以将节点拖出',
+    },
+    'en-US': {},
+  }
+}
+```
 
-## Feature Introduction
-
-<table className="rs-table">
-  <tr>
-    <td>
-      Auto Layout
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/free-layout/autolayout.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      Snap + Reference Line
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/free-layout/snap.gif"  />
-      </div>
-    </td>
-  </tr>
-</table>

apps/docs/src/zh/examples/fixed-layout/fixed-feature-overview.mdx

@@ -9,9 +9,10 @@ import { FixedFeatureOverview } from '../../../../components';
 
 <FixedFeatureOverview />
 
+
 ## 安装
 
-```bash
+```shell
 npx @flowgram.ai/create-app@latest fixed-layout
 ```
 
@@ -19,75 +20,366 @@ npx @flowgram.ai/create-app@latest fixed-layout
 
 https://github.com/bytedance/flowgram.ai/tree/main/apps/demo-fixed-layout
 
-## 功能介绍
-
-<table className="rs-table">
-  <tr>
-    <td>缩略图</td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/minimap.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>撤销/重做</td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/redo-undo.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>复制/粘贴(支持快捷键)</td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/copypaste.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>
-        <div>框选 + 拖拽</div>
-      </div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <div className="rs-center">
-          <img loading="lazy" src="/fixed-layout/dragdrop.gif"  />
-        </div>
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>水平/垂直布局切换</div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/layout-change.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>分支折叠</div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/fold.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <div>分组</div>
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/fixed-layout/group.gif"  />
-      </div>
-    </td>
-  </tr>
-</table>
+
+## 项目概览
+
+### 核心技术栈
+- **前端框架**: React 18 + TypeScript
+- **构建工具**: Rsbuild (基于 Rspack 的现代构建工具)
+- **样式方案**: Less + Styled Components + CSS Variables
+- **UI 组件库**: Semi Design (@douyinfe/semi-ui)
+- **状态管理**: 基于 Flowgram 自研的编辑器框架
+- **依赖注入**: Inversify
+
+
+### 核心依赖包
+
+- **@flowgram.ai/fixed-layout-editor**: 固定布局编辑器核心依赖
+- **@flowgram.ai/fixed-semi-materials**: Semi Design 物料库
+- **@flowgram.ai/form-materials**: 表单物料库
+- **@flowgram.ai/group-plugin**: 分组插件
+- **@flowgram.ai/minimap-plugin**: 缩略图插件
+
+## 代码说明
+
+```
+src/
+├── app.tsx                    # 应用入口组件
+├── editor.tsx                 # 主编辑器组件
+├── index.ts                   # 模块导出入口
+├── initial-data.ts            # 初始化数据配置
+├── type.d.ts                  # 全局类型声明
+│
+├── assets/                    # 静态资源
+│   ├── icon-mouse.tsx         # 鼠标图标组件
+│   └── icon-pad.tsx           # 触控板图标组件
+│
+├── components/                # 通用组件库
+│   ├── index.ts               # 组件导出入口
+│   ├── node-list.tsx          # 节点列表组件
+│   │
+│   ├── agent-adder/           # Agent 添加器组件
+│   │   └── index.tsx
+│   ├── agent-label/           # Agent 标签组件
+│   │   └── index.tsx
+│   ├── base-node/             # 基础节点组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── branch-adder/          # 分支添加器组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── drag-node/             # 拖拽节点组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── node-adder/            # 节点添加器组件
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   └── utils.ts
+│   ├── selector-box-popover/  # 选择框弹出层组件
+│   │   └── index.tsx
+│   ├── sidebar/               # 侧边栏组件
+│   │   ├── index.tsx
+│   │   ├── sidebar-node-renderer.tsx
+│   │   ├── sidebar-provider.tsx
+│   │   └── sidebar-renderer.tsx
+│   └── tools/                 # 工具栏组件群
+│       ├── index.tsx
+│       ├── styles.tsx
+│       ├── fit-view.tsx       # 适应视图工具
+│       ├── minimap-switch.tsx # 缩略图开关
+│       ├── minimap.tsx        # 缩略图组件
+│       ├── readonly.tsx       # 只读模式切换
+│       ├── run.tsx            # 运行工具
+│       ├── save.tsx           # 保存工具
+│       ├── switch-vertical.tsx # 垂直布局切换
+│       └── zoom-select.tsx    # 缩放选择器
+│
+├── context/                   # React Context 状态管理
+│   ├── index.ts               # Context 导出入口
+│   ├── node-render-context.ts # 节点渲染上下文
+│   └── sidebar-context.ts     # 侧边栏上下文
+│
+├── form-components/           # 表单组件库
+│   ├── index.ts               # 表单组件导出入口
+│   ├── feedback.tsx           # 反馈组件
+│   │
+│   ├── form-content/          # 表单内容组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-header/           # 表单头部组件
+│   │   ├── index.tsx
+│   │   ├── styles.tsx
+│   │   ├── title-input.tsx
+│   │   └── utils.tsx
+│   ├── form-inputs/           # 表单输入组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   ├── form-item/             # 表单项组件
+│   │   ├── index.css
+│   │   └── index.tsx
+│   ├── form-outputs/          # 表单输出组件
+│   │   ├── index.tsx
+│   │   └── styles.tsx
+│   └── properties-edit/       # 属性编辑组件
+│       ├── index.tsx
+│       ├── property-edit.tsx
+│       └── styles.tsx
+│
+├── hooks/                     # 自定义 React Hooks
+│   ├── index.ts               # Hooks 导出入口
+│   ├── use-editor-props.ts    # 编辑器属性 Hook
+│   ├── use-is-sidebar.ts      # 侧边栏状态 Hook
+│   └── use-node-render-context.ts # 节点渲染上下文 Hook
+│
+├── nodes/                     # 流程节点定义
+│   ├── index.ts               # 节点注册表
+│   ├── default-form-meta.tsx  # 默认表单元数据
+│   │
+│   ├── agent/                 # Agent 节点类型
+│   │   ├── index.ts
+│   │   ├── agent.ts
+│   │   ├── agent-llm.ts
+│   │   ├── agent-memory.ts
+│   │   ├── agent-tools.ts
+│   │   ├── memory.ts
+│   │   └── tool.ts
+│   ├── break-loop/            # 跳出循环节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case/                  # Case 分支节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── case-default/          # 默认 Case 节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── catch-block/           # 异常捕获块节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── end/                   # 结束节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── if/                    # 条件判断节点
+│   │   └── index.ts
+│   ├── if-block/              # 条件块节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── llm/                   # LLM 节点
+│   │   └── index.ts
+│   ├── loop/                  # 循环节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── start/                 # 开始节点
+│   │   ├── index.ts
+│   │   └── form-meta.tsx
+│   ├── switch/                # Switch 分支节点
+│   │   └── index.ts
+│   └── trycatch/              # Try-Catch 节点
+│       ├── index.ts
+│       └── form-meta.tsx
+│
+├── plugins/                   # 插件系统
+│   ├── index.ts               # 插件导出入口
+│   │
+│   ├── clipboard-plugin/      # 剪贴板插件
+│   │   └── create-clipboard-plugin.ts
+│   ├── group-plugin/          # 分组插件
+│   │   ├── index.ts
+│   │   ├── group-box-header.tsx
+│   │   ├── group-node.tsx
+│   │   ├── group-note.tsx
+│   │   ├── group-tools.tsx
+│   │   ├── icons/
+│   │   │   └── index.tsx
+│   │   └── multilang-textarea-editor/
+│   │       ├── index.css
+│   │       ├── index.tsx
+│   │       └── base-textarea.tsx
+│   └── variable-panel-plugin/ # 变量面板插件
+│       ├── index.ts
+│       ├── variable-panel-layer.tsx
+│       ├── variable-panel-plugin.ts
+│       └── components/
+│           ├── full-variable-list.tsx
+│           ├── global-variable-editor.tsx
+│           └── variable-panel.tsx
+│
+├── services/                  # 服务层
+│   ├── index.ts
+│   └── custom-service.ts      # 自定义服务
+│
+├── shortcuts/                 # 快捷键系统
+│   ├── index.ts
+│   ├── constants.ts           # 快捷键常量
+│   └── utils.ts               # 快捷键工具函数
+│
+└── typings/                   # 类型定义
+    ├── index.ts               # 类型导出入口
+    ├── json-schema.ts         # JSON Schema 类型
+    └── node.ts                # 节点类型定义
+```
+
+## 架构设计分析
+
+### 整体架构模式
+
+该项目采用了**分层架构**和**模块化设计**相结合的架构模式：
+
+1. **表现层 (Presentation Layer)**
+- 组件层：负责 UI 渲染和用户交互
+- 工具层：提供编辑器工具功能
+
+2. **业务逻辑层 (Business Logic Layer)**
+- 节点系统：定义各种流程节点的行为和属性
+- 插件系统：提供可扩展的功能模块
+- 服务层：处理业务逻辑和数据操作
+
+3. **数据层 (Data Layer)**
+- Context 状态管理：管理应用全局状态
+- 类型系统：确保数据结构的一致性
+
+### 核心设计模式
+
+#### 1. 提供者模式 (Provider Pattern)
+```typescript
+// 主编辑器组件使用多层 Provider 嵌套
+<FixedLayoutEditorProvider {...editorProps}>
+  <SidebarProvider>
+    <EditorRenderer />
+    <DemoTools />
+    <SidebarRenderer />
+  </SidebarProvider>
+</FixedLayoutEditorProvider>
+```
+
+**应用场景**:
+- `FixedLayoutEditorProvider`: 提供编辑器核心功能和状态
+- `SidebarProvider`: 管理侧边栏的显示状态和选中节点
+
+#### 2. 注册表模式 (Registry Pattern)
+```typescript
+export const FlowNodeRegistries: FlowNodeRegistry[] = [
+  StartNodeRegistry,
+  EndNodeRegistry,
+  SwitchNodeRegistry,
+  LLMNodeRegistry,
+  // ... 更多节点类型
+];
+```
+
+**设计优势**:
+- 支持动态节点类型注册
+- 易于扩展新的节点类型
+- 实现了节点类型的解耦
+
+#### 3. 插件模式 (Plugin Pattern)
+```typescript
+plugins: () => [
+  createMinimapPlugin({...}),
+  createGroupPlugin({...}),
+  createClipboardPlugin(),
+  createVariablePanelPlugin({}),
+]
+```
+
+**插件系统特点**:
+- **缩略图插件**: 提供画布缩略图功能
+- **分组插件**: 支持节点分组管理
+- **剪贴板插件**: 实现复制粘贴功能
+- **变量面板插件**: 提供变量管理界面
+
+#### 4. 工厂模式 (Factory Pattern)
+在节点创建和配置中广泛使用：
+```typescript
+getNodeDefaultRegistry(type) {
+  return {
+    type,
+    meta: {
+      defaultExpanded: true,
+    },
+  };
+}
+```
+
+#### 5. 观察者模式 (Observer Pattern)
+通过历史记录系统实现：
+```typescript
+history: {
+  enable: true,
+  enableChangeNode: true,
+  onApply: debounce((ctx, opt) => {
+    console.log('auto save: ', ctx.document.toJSON());
+  }, 100),
+}
+```
+
+#### 6. 策略模式 (Strategy Pattern)
+在材料系统中体现：
+```typescript
+materials: {
+  components: {
+    ...defaultFixedSemiMaterials,
+    [FlowRendererKey.ADDER]: NodeAdder,
+    [FlowRendererKey.BRANCH_ADDER]: BranchAdder,
+    // 可根据 key 替换不同的渲染策略
+  }
+}
+```
+
+### 状态管理架构
+
+#### Context 系统设计
+项目采用了多个专用的 Context 来管理不同领域的状态：
+
+1. **SidebarContext**: 管理侧边栏状态
+```typescript
+export const SidebarContext = React.createContext<{
+  visible: boolean;
+  nodeId?: string;
+  setNodeId: (node: string | undefined) => void;
+}>({ visible: false, setNodeId: () => {} });
+```
+
+2. **NodeRenderContext**: 管理节点渲染相关状态
+3. **IsSidebarContext**: 简单的布尔状态管理
+
+#### 自定义 Hooks 设计
+- `useEditorProps`: 集中管理编辑器的所有配置属性
+- `useIsSidebar`: 判断当前是否在侧边栏环境中
+- `useNodeRenderContext`: 获取节点渲染上下文
+
+### 组件架构设计
+
+#### 组件分层结构
+1. **基础组件层**
+- `BaseNode`: 所有节点的基础渲染组件
+- `DragNode`: 拖拽状态下的节点组件
+
+2. **功能组件层**
+- 添加器组件: `NodeAdder`, `BranchAdder`, `AgentAdder`
+- 工具组件: 缩放、保存、运行等功能组件
+
+3. **容器组件层**
+- `Sidebar`: 侧边栏容器及其子组件
+- `Tools`: 工具栏容器
+
+### 数据流架构
+
+#### 初始数据结构
+项目定义了完整的初始流程数据，包含多种节点类型的示例：
+- **Start 节点**: 流程起始点，定义输出参数
+- **Agent 节点**: 包含 LLM、Memory、Tools 子组件
+- **LLM 节点**: 大语言模型处理节点
+- **Switch 节点**: 条件分支节点
+- **Loop 节点**: 循环处理节点
+- **TryCatch 节点**: 异常处理节点
+- **End 节点**: 流程结束点
+
+#### 数据转换机制
+```typescript
+fromNodeJSON(node, json) {
+  return json; // 数据导入时的转换逻辑
+},
+toNodeJSON(node, json) {
+  return json; // 数据导出时的转换逻辑
+}
+```

apps/docs/src/zh/examples/free-layout/free-feature-overview.mdx

@@ -11,7 +11,7 @@ import { FreeFeatureOverview } from '../../../../components';
 
 ## 安装
 
-```bash
+```shell
 npx @flowgram.ai/create-app@latest free-layout
 ```
 
@@ -19,28 +19,379 @@ npx @flowgram.ai/create-app@latest free-layout
 
 https://github.com/bytedance/flowgram.ai/tree/main/apps/demo-free-layout
 
+## 项目概览
+
+### 核心技术栈
+- **前端框架**: React 18 + TypeScript
+- **构建工具**: Rsbuild (基于 Rspack 的现代构建工具)
+- **样式方案**: Less + Styled Components + CSS Variables
+- **UI 组件库**: Semi Design (@douyinfe/semi-ui)
+- **状态管理**: 基于 Flowgram 自研的编辑器框架
+- **依赖注入**: Inversify
+
+### 核心依赖包
+
+- **@flowgram.ai/free-layout-editor**: 自由布局编辑器核心依赖
+- **@flowgram.ai/free-snap-plugin**: 自动对齐及辅助线插件
+- **@flowgram.ai/free-lines-plugin**: 连线渲染插件
+- **@flowgram.ai/free-node-panel-plugin**: 节点添加面板渲染插件
+- **@flowgram.ai/minimap-plugin**: 缩略图插件
+- **@flowgram.ai/free-container-plugin**: 子画布插件
+- **@flowgram.ai/free-group-plugin**: 分组插件
+- **@flowgram.ai/form-materials**: 表单物料
+- **@flowgram.ai/runtime-interface**: 运行时接口
+- **@flowgram.ai/runtime-js**: js 运行时模块
+
+## 代码说明
+
+### 目录结构
+```
+src/
+├── app.tsx                  # 应用入口文件
+├── editor.tsx               # 编辑器主组件
+├── initial-data.ts          # 初始化数据配置
+├── assets/                  # 静态资源
+├── components/              # 组件库
+│   ├── index.ts
+│   ├── add-node/            # 添加节点组件
+│   ├── base-node/           # 基础节点组件
+│   ├── comment/             # 注释组件
+│   ├── group/               # 分组组件
+│   ├── line-add-button/     # 连线添加按钮
+│   ├── node-menu/           # 节点菜单
+│   ├── node-panel/          # 节点添加面板
+│   ├── selector-box-popover/ # 选择框弹窗
+│   ├── sidebar/             # 侧边栏
+│   ├── testrun/             # 测试运行组件
+│   │   ├── hooks/           # 测试运行钩子
+│   │   ├── node-status-bar/ # 节点状态栏
+│   │   ├── testrun-button/  # 测试运行按钮
+│   │   ├── testrun-form/    # 测试运行表单
+│   │   ├── testrun-json-input/ # JSON输入组件
+│   │   └── testrun-panel/   # 测试运行面板
+│   └── tools/               # 工具组件
+├── context/                 # React Context
+│   ├── node-render-context.ts # 当前渲染节点 Context
+│   ├── sidebar-context        # 侧边栏 Context
+├── form-components/         # 表单组件库
+│   ├── form-content/        # 表单内容
+│   ├── form-header/         # 表单头部
+│   ├── form-inputs/         # 表单输入
+│   └── form-item/           # 表单项
+│   └── feedback.tsx         # 表单校验错误渲染
+├── hooks/
+│   ├── index.ts
+│   ├── use-editor-props.tsx # 编辑器属性钩子
+│   ├── use-is-sidebar.ts    # 侧边栏状态钩子
+│   ├── use-node-render-context.ts # 节点渲染上下文钩子
+│   └── use-port-click.ts    # 端口点击钩子
+├── nodes/                    # 节点定义
+│   ├── index.ts
+│   ├── constants.ts         # 节点常量定义
+│   ├── default-form-meta.ts # 默认表单元数据
+│   ├── block-end/           # 块结束节点
+│   ├── block-start/         # 块开始节点
+│   ├── break/               # 中断节点
+│   ├── code/                # 代码节点
+│   ├── comment/             # 注释节点
+│   ├── condition/           # 条件节点
+│   ├── continue/            # 继续节点
+│   ├── end/                 # 结束节点
+│   ├── group/               # 分组节点
+│   ├── http/                # HTTP节点
+│   ├── llm/                 # LLM节点
+│   ├── loop/                # 循环节点
+│   ├── start/               # 开始节点
+│   └── variable/            # 变量节点
+├── plugins/                 # 插件系统
+│   ├── index.ts
+│   ├── context-menu-plugin/ # 右键菜单插件
+│   ├── runtime-plugin/      # 运行时插件
+│   │   ├── client/          # 客户端
+│   │   │   ├── browser-client/ # 浏览器客户端
+│   │   │   └── server-client/  # 服务器客户端
+│   │   └── runtime-service/ # 运行时服务
+│   └── variable-panel-plugin/ # 变量面板插件
+│       └── components/      # 变量面板组件
+├── services/                 # 服务层
+│   ├── index.ts
+│   └── custom-service.ts    # 自定义服务
+├── shortcuts/                # 快捷键系统
+│   ├── index.ts
+│   ├── constants.ts         # 快捷键常量
+│   ├── shortcuts.ts         # 快捷键定义
+│   ├── type.ts              # 类型定义
+│   ├── collapse/            # 折叠快捷键
+│   ├── copy/                # 复制快捷键
+│   ├── delete/              # 删除快捷键
+│   ├── expand/              # 展开快捷键
+│   ├── paste/               # 粘贴快捷键
+│   ├── select-all/          # 全选快捷键
+│   ├── zoom-in/             # 放大快捷键
+│   └── zoom-out/            # 缩小快捷键
+├── styles/                   # 样式文件
+├── typings/                  # 类型定义
+│   ├── index.ts
+│   ├── json-schema.ts       # JSON Schema类型
+│   └── node.ts              # 节点类型定义
+└── utils/                    # 工具函数
+    ├── index.ts
+    └── on-drag-line-end.ts  # 拖拽连线结束处理
+```
+
+### 关键目录功能说明
+
+#### 1. `/components` - 组件库
+- **base-node**: 所有节点的基础渲染组件
+- **testrun**: 完整的测试运行功能模块，包含状态栏、表单、面板等
+- **sidebar**: 侧边栏组件，提供工具和属性面板
+- **node-panel**: 节点添加面板，支持拖拽添加新节点
+
+#### 2. `/nodes` - 节点系统
+每个节点类型都有独立的目录，包含：
+- 节点注册信息 (`index.ts`)
+- 表单元数据定义 (`form-meta.ts`)
+- 节点特定的组件和逻辑
+
+#### 3. `/plugins` - 插件系统
+- **runtime-plugin**: 支持浏览器和服务器两种运行模式
+- **context-menu-plugin**: 右键菜单功能
+- **variable-panel-plugin**: 变量管理面板
+
+#### 4. `/shortcuts` - 快捷键系统
+完整的快捷键支持，包括：
+- 基础操作：复制、粘贴、删除、全选
+- 视图操作：放大、缩小、折叠、展开
+- 每个快捷键都有独立的实现模块
+
+## 应用架构设计
+
+### 核心设计模式
+
+#### 1. 插件化架构 (Plugin Architecture)
+应用采用高度模块化的插件系统，每个功能都作为独立插件存在：
+
+```typescript
+plugins: () => [
+  createFreeLinesPlugin({ renderInsideLine: LineAddButton }),
+  createMinimapPlugin({ /* 配置 */ }),
+  createFreeSnapPlugin({ /* 对齐配置 */ }),
+  createFreeNodePanelPlugin({ renderer: NodePanel }),
+  createContainerNodePlugin({}),
+  createFreeGroupPlugin({ groupNodeRender: GroupNodeRender }),
+  createContextMenuPlugin({}),
+  createRuntimePlugin({ mode: 'browser' }),
+  createVariablePanelPlugin({})
+]
+```
+
+#### 2. 节点注册系统 (Node Registry Pattern)
+通过注册表模式管理不同类型的工作流节点：
+
+```typescript
+export const nodeRegistries: FlowNodeRegistry[] = [
+  ConditionNodeRegistry,    // 条件节点
+  StartNodeRegistry,        // 开始节点
+  EndNodeRegistry,          // 结束节点
+  LLMNodeRegistry,          // LLM节点
+  LoopNodeRegistry,         // 循环节点
+  CommentNodeRegistry,      // 注释节点
+  HTTPNodeRegistry,         // HTTP节点
+  CodeNodeRegistry,         // 代码节点
+  // ... 更多节点类型
+];
+```
+
+#### 3. 依赖注入模式 (Dependency Injection)
+使用 Inversify 框架实现服务的依赖注入：
+
+```typescript
+onBind: ({ bind }) => {
+  bind(CustomService).toSelf().inSingletonScope();
+}
+```
+
+## 核心功能分析
+
+### 1. 编辑器配置系统
+
+`useEditorProps` 是整个编辑器的配置中心，包含：
+
+```typescript
+export function useEditorProps(
+  initialData: FlowDocumentJSON,
+  nodeRegistries: FlowNodeRegistry[]
+): FreeLayoutProps {
+  return useMemo<FreeLayoutProps>(() => ({
+    background: true,                    // 背景网格
+    readonly: false,                     // 是否只读
+    initialData,                         // 初始数据
+    nodeRegistries,                      // 节点注册表
+
+    // 核心功能配置
+    playground: { preventGlobalGesture: true /* 阻止 mac 浏览器手势翻页 */ },
+    nodeEngine: { enable: true },
+    variableEngine: { enable: true },
+    history: { enable: true, enableChangeNode: true },
+
+    // 业务逻辑配置
+    canAddLine: (ctx, fromPort, toPort) => { /* 连线规则 */ },
+    canDeleteLine: (ctx, line) => { /* 删除连线规则 */ },
+    canDeleteNode: (ctx, node) => { /* 删除节点规则 */ },
+    canDropToNode: (ctx, params) => { /* 拖拽规则 */ },
+
+    // 插件配置
+    plugins: () => [/* 插件列表 */],
+
+    // 事件处理
+    onContentChange: debounce((ctx, event) => { /* 自动保存 */ }, 1000),
+    onInit: (ctx) => { /* 初始化 */ },
+    onAllLayersRendered: (ctx) => { /* 渲染完成 */ }
+  }), []);
+}
+```
+
+### 2. 节点类型系统
+
+应用支持多种工作流节点类型：
+
+```typescript
+export enum WorkflowNodeType {
+  Start = 'start',           // 开始节点
+  End = 'end',               // 结束节点
+  LLM = 'llm',               // 大语言模型节点
+  HTTP = 'http',             // HTTP请求节点
+  Code = 'code',             // 代码执行节点
+  Variable = 'variable',     // 变量节点
+  Condition = 'condition',   // 条件判断节点
+  Loop = 'loop',             // 循环节点
+  BlockStart = 'block-start', // 子画布开始节点
+  BlockEnd = 'block-end',    // 子画布结束节点
+  Comment = 'comment',       // 注释节点
+  Continue = 'continue',     // 继续节点
+  Break = 'break',           // 中断节点
+}
+```
+
+每个节点都遵循统一的注册模式：
+
+```typescript
+export const StartNodeRegistry: FlowNodeRegistry = {
+  type: WorkflowNodeType.Start,
+  meta: {
+    isStart: true,
+    deleteDisable: true,        // 不可删除
+    copyDisable: true,          // 不可复制
+    nodePanelVisible: false,    // 不在节点面板显示
+    defaultPorts: [{ type: 'output' }],
+    size: { width: 360, height: 211 }
+  },
+  info: {
+    icon: iconStart,
+    description: '工作流的起始节点，用于设置启动工作流所需的信息。'
+  },
+  formMeta,                     // 表单配置
+  canAdd() { return false; }    // 不允许添加多个开始节点
+};
+```
+
+### 3. 插件化架构
+
+应用的功能通过插件系统实现模块化：
+
+#### 核心插件列表
+1. **FreeLinesPlugin** - 连线渲染和交互
+2. **MinimapPlugin** - 缩略图导航
+3. **FreeSnapPlugin** - 自动对齐和辅助线
+4. **FreeNodePanelPlugin** - 节点添加面板
+5. **ContainerNodePlugin** - 容器节点（如循环节点）
+6. **FreeGroupPlugin** - 节点分组功能
+7. **ContextMenuPlugin** - 右键菜单
+8. **RuntimePlugin** - 工作流运行时
+9. **VariablePanelPlugin** - 变量管理面板
+
+### 4. 运行时系统
+
+应用支持两种运行模式：
+
+```typescript
+createRuntimePlugin({
+  mode: 'browser',              // 浏览器模式
+  // mode: 'server',            // 服务器模式
+  // serverConfig: {
+  //   domain: 'localhost',
+  //   port: 4000,
+  //   protocol: 'http',
+  // },
+})
+```
+
+## 设计理念与架构优势
+
+### 1. 高度模块化
+- **插件化架构**: 每个功能都是独立插件，易于扩展和维护
+- **节点注册系统**: 新节点类型可以轻松添加，无需修改核心代码
+- **组件化设计**: UI组件高度复用，职责清晰
+
+### 2. 类型安全
+- **完整的TypeScript支持**: 从配置到运行时的全链路类型保护
+- **JSON Schema集成**: 节点数据结构通过Schema验证
+- **强类型的插件接口**: 插件开发有明确的类型约束
+
+### 3. 用户体验优化
+- **实时预览**: 支持工作流的实时运行和调试
+- **丰富的交互**: 拖拽、缩放、对齐、快捷键等完整的编辑体验
+- **可视化反馈**: 缩略图、状态指示、连线动画等视觉反馈
+
+### 4. 扩展性设计
+- **开放的插件系统**: 第三方可以轻松开发自定义插件
+- **灵活的节点系统**: 支持自定义节点类型和表单配置
+- **多运行时支持**: 浏览器和服务器双模式运行
+
+### 5. 性能优化
+- **按需加载**: 组件和插件支持按需加载
+- **防抖处理**: 自动保存等高频操作的性能优化
+
+## 技术亮点
+
+### 1. 自研编辑器框架
+基于 `@flowgram.ai/free-layout-editor` 自研框架，提供：
+- 自由布局的画布系统
+- 完整的撤销/重做功能
+- 节点和连线的生命周期管理
+- 变量引擎和表达式系统
+
+### 2. 先进的构建配置
+使用 Rsbuild 作为构建工具：
+
+```typescript
+export default defineConfig({
+  plugins: [pluginReact(), pluginLess()],
+  source: {
+    entry: { index: './src/app.tsx' },
+    decorators: { version: 'legacy' }  // 支持装饰器
+  },
+  tools: {
+    rspack: {
+      ignoreWarnings: [/Critical dependency/]  // 忽略特定警告
+    }
+  }
+});
+```
+
+### 3. 国际化支持
+内置多语言支持：
+
+```typescript
+i18n: {
+  locale: navigator.language,
+  languages: {
+    'zh-CN': {
+      'Never Remind': '不再提示',
+      'Hold {{key}} to drag node out': '按住 {{key}} 可以将节点拖出',
+    },
+    'en-US': {},
+  }
+}
+```
 
-## 功能介绍
-
-<table className="rs-table">
-  <tr>
-    <td>
-      自动整理
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/free-layout/autolayout.gif"  />
-      </div>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      吸附对齐 + 参考线
-    </td>
-    <td>
-      <div className="rs-center">
-        <img loading="lazy" src="/free-layout/snap.gif"  />
-      </div>
-    </td>
-  </tr>
-</table>