> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 列表操作器

**列表操作节点**是 XpertAI 数字专家工作流（Workflow）中用于批量数据处理的逻辑节点。它允许在工作流中对列表（数组）类型的数据进行筛选、排序、提取等操作，从而为后续节点提供更精准的数据输入。

***

## 一、节点功能概述

在数字专家的执行链路中，数据常以数组或集合的形式出现，例如：

* 知识检索返回的多条文档；
* 接口返回的记录列表；
* 上游节点的批量计算结果。

列表操作节点通过配置灵活的条件和规则，对输入列表进行结构化处理，使工作流能够自动完成数据筛选、提取、排序等逻辑，从而实现“数据驱动的智能分支决策”。

***

## 二、核心能力

### 1. 条件筛选（Filter By）

支持通过多条件筛选列表元素。
用户可配置多个筛选条件，并选择逻辑关系：

* **AND**：满足所有条件的元素才保留；
* **OR**：满足任一条件即可保留。

这使得节点能够在运行时根据变量或属性值动态过滤列表内容，实现自动化的数据过滤流程。

**典型应用：**

* 过滤出价格低于指定阈值的产品；
* 仅保留状态为“待处理”的任务；
* 从多条检索结果中选出置信度较高的内容。

***

### 2. 元素提取（Extract By）

提供按索引提取指定位置元素的能力。
支持：

* 正向索引（从第 1 个开始）；
* 反向索引（如 `-1` 表示最后一个元素）。

**应用示例：**

* 获取列表中的最新一条数据；
* 提取前 N 条或特定位置的记录用于后续计算。

***

### 3. 排序（Sort By）

支持根据指定变量对列表进行升序或降序排序。
当数据集中包含时间、数值或优先级等字段时，排序功能可以快速帮助工作流自动确定执行顺序。

**应用示例：**

* 按时间从近到远排列任务；
* 按权重从高到低选择最优结果；
* 对接口返回的结果进行排序后再提取第一项。

***

### 4. 截取前 N 条（Top N）

允许设置仅保留前 N 条结果。
可与排序功能结合使用，实现“选出前 N 个最优项”的场景。

**应用示例：**

* 选取置信度最高的前 5 条回答；
* 获取最新的 3 条记录；
* 从分析结果中保留关键样本。

***

## 三、输出结果

节点执行完成后，会自动生成多个输出变量，供后续节点引用：

| 输出变量           | 类型  | 说明                |
| -------------- | --- | ----------------- |
| `result`       | 数组  | 筛选、排序、截取后的完整结果集   |
| `first_record` | 单项  | 结果中的第一条记录         |
| `last_record`  | 单项  | 结果中的最后一条记录        |
| `error`        | 字符串 | 若执行出现错误，将在此返回错误信息 |

***

## 四、典型应用场景

### 🔹 场景一：检索结果过滤

在知识问答或文档召回流程中，使用列表操作节点过滤掉置信度较低的回答，仅保留高质量的候选结果。

### 🔹 场景二：智能排序与提取

在推荐系统、任务调度或财务分析等场景中，根据权重、时间、金额等字段对结果排序，并提取最符合条件的项。

### 🔹 场景三：多分支决策前置处理

通过列表筛选提前处理数据，确保后续条件判断、循环或聚合节点只处理目标子集，提高执行效率。

***

## 五、节点在工作流中的价值

列表操作节点是 **数字专家工作流的“数据处理器”**，让工作流具备基础的数据逻辑能力。
通过它，用户可以：

* 在无代码界面中完成复杂数据筛选与排序；
* 减少手写逻辑脚本的需求；
* 提升工作流在多样化数据场景下的适配能力；
* 构建更智能、更具决策能力的自动化流程。

***

**总结**：
列表操作节点以模块化方式集成了过滤、提取、排序等常见数据处理逻辑，是构建高可控、高自动化数字专家工作流的核心组件之一。通过与条件判断、循环、触发器等节点协同，它让 XpertAI 的智能体能够以数据驱动的方式，自主完成从信息筛选到决策执行的全过程。