# 函数节点嵌套系统 - 实现完整指南
## 📋 概述
已完成函数节点嵌套系统的**完整端到端实现**，包括后端核心逻辑、API 接口、前端状态管理、UI 组件和交互功能。
---
## 🏗️ 架构设计
### 后端架构 (Python/FastAPI)
```
server/app/core/
├── function_nodes.py .................... 函数节点基类系统
│ ├── InputNode ....................... 函数入口节点
│ ├── OutputNode ...................... 函数出口节点
│ ├── FunctionNode .................... 函数封装容器
│ └── create_function_node_class() ... 动态节点工厂
├── node_loader.py ...................... 节点加载器（已扩展）
│ ├── load_function_nodes() ........... 扫描&加载函数节点
│ └── reload_custom_nodes() ........... 增强版本（包含函数加载）
└── ...
server/app/api/
└── endpoints_graph.py .................. 图执行 API（已扩展）
├── POST /api/functions/save ....... 保存工作流为函数
├── GET /api/functions/list ........ 列出可用函数
└── GET /api/functions/{name} ..... 获取函数详细信息
```
### 前端架构 (React/TypeScript)
```
web/src/
├── stores/
│ └── useStore.ts ..................... 全局状态管理（已扩展）
│ ├── functionStack: [] ........... 函数层级栈
│ ├── rootNodes/rootEdges ........ 根层级状态保存
│ ├── enterFunction() ............ 进入函数
│ ├── exitFunction() ............. 返回上层
│ └── navigateToLevel() .......... 层级跳转
├── components/
│ ├── Workspace.tsx .................. 主画布（已扩展）
│ │ ├── onNodeDoubleClick() ........ 双击进入函数
│ │ ├── handleMenuAction('saveAsFunction') 右键保存
│ │ └── ......... 面包屑导航
│ ├── BreadcrumbNav.tsx .............. 新组件：层级导航
│ └── ...
└── ...
```
---
## 📁 数据存储结构
### 函数定义格式 (JSON)
位置: `cloud/custom_nodes/functions/{function_name}.json`
```json
{
"function_name": "extract_columns",
"display_name": "提取列",
"description": "从数据中提取指定列",
"inputs": [
{
"name": "data",
"type": "DataFrame",
"description": "输入数据"
},
{
"name": "columns",
"type": "StringArray",
"description": "要提取的列名"
}
],
"outputs": [
{
"name": "result",
"type": "DataFrame",
"description": "提取后的数据"
}
],
"nodes": [
{
"id": "input_data",
"type": "FunctionInput",
"position": {"x": 100, "y": 100},
"data": {
"param_name": "data",
"param_type": "DataFrame"
}
},
{
"id": "input_columns",
"type": "FunctionInput",
"position": {"x": 100, "y": 200},
"data": {
"param_name": "columns",
"param_type": "StringArray"
}
},
{
"id": "transform",
"type": "BuiltinTransform", // 实际的转换节点
"position": {"x": 300, "y": 150},
"data": { /* ... */ }
},
{
"id": "output_result",
"type": "FunctionOutput",
"position": {"x": 500, "y": 150},
"data": {
"output_name": "result",
"output_type": "DataFrame"
}
}
],
"edges": [
{
"id": "e1",
"source": "input_data",
"target": "transform",
"sourceHandle": "output-value",
"targetHandle": "input-data"
},
{
"id": "e2",
"source": "input_columns",
"target": "transform",
"sourceHandle": "output-value",
"targetHandle": "input-columns"
},
{
"id": "e3",
"source": "transform",
"target": "output_result",
"sourceHandle": "output-result",
"targetHandle": "input-value"
}
]
}
```
### 函数执行数据流
```
外部调用 (Context)
↓
FunctionNode.execute()
├─ 注入输入: context["__function_input_{param_name}"] = value
├─ 执行内部工作流: 运行 nodes & edges（TODO: 接入 WorkflowExecutor）
├─ 提取输出: context["__function_output_{output_name}"] → 返回
↓
返回结果
```
---
## 🚀 使用流程
### 1️⃣ 创建函数工作流
1. 在画布中设计工作流（包含 InputNode、OutputNode）
2. 右键点击画布空白处
3. 选择 **"保存为函数"**
4. 输入函数名称（英文，如 `extract_data`）
5. 输入显示名称（中文，如 `提取数据`）
6. 输入可选描述
**API 调用**:
```
POST /api/functions/save
{
"function_name": "extract_data",
"display_name": "提取数据",
"description": "从源数据中提取需要的信息",
"nodes": [...],
"edges": [...],
"inputs": [],
"outputs": []
}
```
**结果**:
- 函数定义保存到 `cloud/custom_nodes/functions/extract_data.json`
- 后端自动加载函数节点
- 前端 NodePalette 会出现新节点
### 2️⃣ 使用函数节点
1. 从左侧 NodePalette 找到函数节点（如 `extract_data`）
2. 拖拽到画布
3. 连接输入/输出
4. **双击函数节点**进入编辑
### 3️⃣ 进入函数编辑
**双击处理**:
```typescript
onNodeDoubleClick
├─ 检测节点类型 (node_type_name 包含 "Function")
├─ 提取函数名 (Function_xxx -> xxx)
├─ API 调用: GET /api/functions/{functionName}
├─ 调用 enterFunction(nodeId, nodeName, functionData)
└─ 画布切换到函数内部工作流
```
**状态转换**:
```
画布状态
├─ nodes: [...主工作流...]
├─ edges: [...连接...]
├─ functionStack: []
│ ↓ 双击进入
├─ functionStack: [
│ {functionId: "node_1", functionName: "extract_data", nodes: [...], edges: [...]}
│ ]
├─ nodes: [...函数内部nodes...]
├─ edges: [...函数内部edges...]
└─ 面包屑导航显示: 主工作流 / extract_data (层级1)
```
### 4️⃣ 在函数内编辑
- 画布显示函数内部的 nodes 和 edges
- 可以编辑、删除、添加节点
- 面包屑导航显示当前所在层级
- 支持**嵌套**: 在函数内再双击另一函数节点进入下一层
### 5️⃣ 返回上一层
**方式 1**: 点击面包屑的"返回"按钮
- 调用 `exitFunction()`
- 恢复上一层级的 nodes/edges
**方式 2**: 点击面包屑的"主工作流"
- 调用 `navigateToLevel(0)`
- 直接跳转到根层级
**方式 3**: 点击面包屑中间的函数名
- 调用 `navigateToLevel(levelIndex)`
- 跳转到指定层级
**状态恢复**:
```
执行 exitFunction() 或 navigateToLevel()
↓
从 functionStack pop 目标数据
↓
恢复 nodes/edges 到上一层级
↓
清空 functionStack（如果返回根层级）
↓
面包屑导航更新显示
```
---
## 🔧 核心实现细节
### 后端: 函数节点类 (function_nodes.py)
#### InputNode
```python
class InputNode(NodeBase):
"""函数入口节点 - 从上下文读取外部输入"""
def execute(self, context: dict) -> dict:
param_name = self.data.get("param_name")
# 从特殊键读取外部输入: __function_input_{param_name}
value = context.get(f"__function_input_{param_name}")
context[f"{self.id}.output_value"] = value
return context
```
#### OutputNode
```python
class OutputNode(NodeBase):
"""函数出口节点 - 写入上下文供外部读取"""
def execute(self, context: dict) -> dict:
output_name = self.data.get("output_name")
input_value = context.get(f"{self.input_node_id}.output_value")
# 写入特殊键供外部读取: __function_output_{output_name}
context[f"__function_output_{output_name}"] = input_value
return context
```
#### FunctionNode
```python
class FunctionNode(NodeBase):
"""函数封装容器 - 执行内部工作流"""
def execute(self, context: dict) -> dict:
# 1. 注入输入
for input_name, input_value in self.inputs.items():
context[f"__function_input_{input_name}"] = input_value
# 2. 执行内部工作流
executor = WorkflowExecutor(self.internal_nodes, self.internal_edges)
context = executor.execute(context)
# 3. 提取输出
outputs = {}
for output_name in self.output_names:
outputs[output_name] = context.get(f"__function_output_{output_name}")
context[f"{self.id}.outputs"] = outputs
return context
```
#### 动态节点工厂
```python
def create_function_node_class(name: str, workflow_data: dict) -> type:
"""运行时创建函数节点子类"""
class DynamicFunctionNode(FunctionNode):
def __init__(self):
super().__init__()
self.internal_nodes = workflow_data.get("nodes", [])
self.internal_edges = workflow_data.get("edges", [])
self.input_names = [i["name"] for i in workflow_data.get("inputs", [])]
self.output_names = [o["name"] for o in workflow_data.get("outputs", [])]
return DynamicFunctionNode
```
### 前端: 状态管理 (useStore.ts)
#### 状态定义
```typescript
interface AppState {
functionStack: FunctionStackItem[] // 函数层级栈
rootNodes: NodeSchema[] // 根层级节点备份
rootEdges: Edge[] // 根层级连线备份
enterFunction: (functionId, functionName, functionData) => void
exitFunction: () => void
navigateToLevel: (level: number) => void
}
```
#### enterFunction 实现
```typescript
enterFunction: (functionId: string, functionName: string, functionData: any) => {
const currentNodes = get().nodes
const currentEdges = get().edges
const stack = get().functionStack
// 首次进入：保存根层级
if (stack.length === 0) {
set({ rootNodes: currentNodes, rootEdges: currentEdges })
}
// 压入栈
set({
functionStack: [...stack, { functionId, functionName, nodes: currentNodes, edges: currentEdges }],
nodes: functionData.nodes || [],
edges: functionData.edges || [],
activeNodeId: null
})
}
```
#### exitFunction 实现
```typescript
exitFunction: () => {
const stack = get().functionStack
if (stack.length === 0) return
const newStack = stack.slice(0, -1)
if (newStack.length === 0) {
// 返回根层级
set({
functionStack: [],
nodes: get().rootNodes,
edges: get().rootEdges,
activeNodeId: null
})
} else {
// 返回上一函数层级
const prevLevel = newStack[newStack.length - 1]
set({
functionStack: newStack,
nodes: prevLevel.nodes,
edges: prevLevel.edges,
activeNodeId: null
})
}
}
```
#### navigateToLevel 实现
```typescript
navigateToLevel: (level: number) => {
const stack = get().functionStack
if (level === 0) {
// 跳转根层级
set({
functionStack: [],
nodes: get().rootNodes,
edges: get().rootEdges,
activeNodeId: null
})
} else if (level > 0 && level <= stack.length) {
// 跳转指定层级
const targetLevel = stack[level - 1]
set({
functionStack: stack.slice(0, level),
nodes: targetLevel.nodes,
edges: targetLevel.edges,
activeNodeId: null
})
}
}
```
### 前端: 双击进入 (Workspace.tsx)
```typescript
const onNodeDoubleClick = useCallback(async (_event, node) => {
const nodeType = node.data?.meta?.node_type_name || ''
// 检测函数节点（排除 Input/Output）
const isFunctionNode = nodeType.includes('Function')
&& !nodeType.includes('Input')
&& !nodeType.includes('Output')
if (!isFunctionNode) return
// 提取函数名 (Function_xxx -> xxx)
const functionName = nodeType.replace(/^Function_/, '')
try {
// API 加载函数数据
const response = await fetch(`http://127.0.0.1:8000/api/functions/${functionName}`)
const { data } = await response.json()
// 触发状态转换
const { enterFunction } = useStore.getState()
enterFunction(node.id, node.data?.label, data)
} catch (error) {
alert(`❌ 加载函数失败: ${error.message}`)
}
}, [])
```
### 前端: 右键保存函数 (Workspace.tsx)
```typescript
case 'saveAsFunction': {
const functionName = prompt('输入函数名称（英文字母和下划线）')
if (!functionName?.match(/^[a-zA-Z_][a-zA-Z0-9_]*$/)) {
alert('❌ 函数名称无效')
return
}
const displayName = prompt('输入显示名称') || functionName
const description = prompt('输入描述') || ''
// API 保存函数
const response = await fetch('http://127.0.0.1:8000/api/functions/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
function_name: functionName,
display_name: displayName,
description: description,
nodes: nodes,
edges: edges,
inputs: [], // 用户在函数内部添加 InputNode
outputs: [] // 用户在函数内部添加 OutputNode
})
})
const result = await response.json()
alert(`✅ 函数已保存: ${result.data.function_name}`)
}
```
### 前端: 面包屑导航 (BreadcrumbNav.tsx)
```typescript
export default function BreadcrumbNav() {
const functionStack = useStore((s) => s.functionStack)
const exitFunction = useStore((s) => s.exitFunction)
const navigateToLevel = useStore((s) => s.navigateToLevel)
if (functionStack.length === 0) return null // 根层级隐藏
// 构建面包屑路径
const breadcrumbs = [
{ id: 'root', name: '主工作流', level: 0 },
...functionStack.map((item, i) => ({
id: item.functionId,
name: item.functionName,
level: i + 1
}))
]
return (
{/* 返回按钮 */}
{/* 面包屑链接 */}
{breadcrumbs.map((bc, i) => (
))}
{/* 层级指示器 */}
L{functionStack.length}