列表操作节点
列表操作节点
【列表操作】节点用于对数组类型变量（Array）进行过滤、排序或提取。
在工作流或对话流智能体中，若用户上传多个文件（如图片、文档、音频、视频等），这些文件会被存储为一个数组变量。
列表操作节点可以帮助开发者在数组中筛选目标元素，并将结果传递给下游节点。
应用场景
- 文件分流处理：根据文件类型（图片、文档、音频、视频）将不同文件分配到不同的处理节点。
- 数据过滤：从数组变量中过滤出满足特定条件的项（如文件大小、扩展名、上传方式等）。
- 数据排序：根据属性（如文件名、大小、时间等）进行升序或降序排列。
- 数据截取：仅保留数组的前 N 项或最后一项，用于快速提取最新或最旧元素。
典型场景：
在一个文件问答应用中，用户可能同时上传 PDF 和 PNG 文件。
列表操作节点可以将 PDF 文件 提取出来送入 文档提取器节点，将 图片文件 送入 LLM 节点，实现混合文件的自动分流。
节点功能结构
列表操作节点由以下部分组成：
- 输入变量
- 过滤条件
- 排序（可选）
- 取前 N 项（可选）
- 输出变量
1. 输入变量
支持的数据结构：
| 类型 | 说明 |
|---|---|
| Array[string] | 字符串数组 |
| Array[number] | 数值数组 |
| Array[file] | 文件数组 |
建议
通常用于处理用户上传的 Array[File] 类型变量，例如 [1.mp3, 2.png, 3.docx]。
2. 过滤条件
过滤条件用于从数组中筛选符合要求的元素，可基于文件属性或数组元素值进行过滤。
文件类变量支持以下过滤字段：
| 字段 | 含义 |
|---|---|
type | 文件类别（图片、文档、音频、视频） |
size | 文件大小（单位：字节） |
name | 文件名 |
url | 文件上传 URL |
extension | 文件扩展名（如 .pdf、.jpg） |
mime_type | 文件 MIME 类型（如 text/html、application/pdf） |
transfer_method | 上传方式（本地上传 / URL 上传） |
过滤逻辑
支持的判断类型包括：
- 等于 / 不等于
- 包含 / 不包含
- 开始是 / 结束是
- 为空 / 不为空
- 大于 / 小于（适用于数值）
示例：
- 筛选文件类型为 文档（Document）；
- 过滤掉扩展名不为
.pdf的文件； - 仅保留文件大小小于 10MB 的项。
3. 排序（可选）
可根据文件属性进行排序：
| 排序方向 | 说明 |
|---|---|
| 升序 | 从小到大排序（A → Z / 小 → 大） |
| 降序 | 从大到小排序（Z → A / 大 → 小） |
适用于文件名、大小、时间戳等属性。
例如：按文件名 A-Z 排序，或按文件大小从大到小排序。
4. 取前 N 项（可选）
可以指定提取数组前 N 个元素（N 范围：1–20）。
常用于：
- 获取最新上传的文件；
- 限定下游节点处理数量；
- 测试或样本预览。
5. 输出变量
| 变量名称 | 类型 | 说明 |
|---|---|---|
result | Array | 过滤与排序后的结果集合 |
first_record | 单值 | 筛选结果中的第一个元素（result[0]） |
last_record | 单值 | 筛选结果中的最后一个元素（result[-1]） |
当
result仅包含一个文件时，first_record与last_record的值相同。
配置示例
文件类型分流处理
目标：当用户同时上传图片与文档时，让不同文件进入不同处理路径。
实现步骤
- 在开始节点中启用文件上传功能，允许同时上传「图片」与「文档文件」。
- 添加两个列表操作节点：
- 节点 A：过滤条件为
type = document； - 节点 B：过滤条件为
type = image。
- 节点 A：过滤条件为
- 节点 A 的输出变量（文档文件） → 连接至 文档提取器节点；
- 节点 B 的输出变量（图片文件） → 连接至 LLM 节点；
- 最后由 结束节点 汇总 LLM 的结果输出。
这样即可在一个应用中同时支持文本与图像类文件的智能处理。
最佳实践
- 确保输入变量类型正确：必须是数组类型（如 Array[File]），否则无法解析。
- 多条件组合：可同时设置多个过滤条件，如「文件类型为图片 AND 文件大小 < 5MB」。
- 命名清晰：为输出变量使用有意义的命名（如
doc_files、img_files）。 - 与文档提取器搭配使用：提取文档类文件后传递给文档解析流程。
- 与条件分支节点组合：根据筛选结果数量或类型执行不同分支逻辑。
- 控制性能：若文件数量较多，可使用「取前 N 项」避免处理过多文件。
常见问题
Q1：为什么输出为空？
A1：请检查过滤条件是否过于严格；若所有文件均不符合条件，输出结果将为空数组。
Q2：能否筛选特定扩展名？
A2：可以，在条件中选择 extension 并填入 .pdf、.docx 等值。
Q3：支持自定义排序字段吗？
A3：目前仅支持基于文件属性的排序；如需自定义复杂逻辑，可结合 代码执行节点 实现。
Q4：result 与 first_record 有什么区别？
A4：result 是完整的过滤结果（数组），first_record 是其中的第一个元素，常用于直接下游节点处理单文件场景。
小结
列表操作节点是数组数据处理的关键节点。
通过过滤、排序与提取机制，你可以轻松实现：
- 多文件类型的分流处理；
- 按条件筛选的文件或数据；
- 控制输出数量与顺序。
它常与 文档提取器节点、LLM 节点 搭配使用，是构建复杂文件交互工作流的基础组件。