> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# filterRun()

根据声明式选项创建 `prepareRun` 函数。将结果传给 `createScorer()`，即可筛选消息并限制上下文大小。它还会在 Scorer pipeline 运行前移除不必要的字段。

如需声明式筛选，请使用 [`filterRun()`](#usage-example)。当你需要 `filterRun()` 未涵盖的命令式逻辑时，可直接编写自定义 `prepareRun` 函数。详情请参阅[自定义 Scorer：输入筛选](https://mastra.zisheng.pro/docs/evals/custom-scorers)。

## 使用示例

以下示例创建了一个 Scorer，它只能看到 Tool 调用和文本消息，并将上下文限制为最近 20 条消息：

```typescript
import { createScorer, filterRun } from '@mastra/core/evals'

const toolScorer = createScorer({
  id: 'tool-usage',
  description: 'Evaluates tool usage patterns',
  type: 'agent',
  prepareRun: filterRun({
    partTypes: ['tool-invocation', 'text'],
    maxRememberedMessages: 20,
  }),
}).generateScore(({ run }) => {
  // run.input.rememberedMessages contains only tool and text messages
  // run.output contains only tool and text messages
  return 1
})
```

### 按 Tool 名称筛选

仅保留涉及特定 Tool 的消息：

```typescript
import { createScorer, filterRun } from '@mastra/core/evals'

const fileEditScorer = createScorer({
  id: 'file-edit-quality',
  description: 'Evaluates file editing patterns',
  type: 'agent',
  prepareRun: filterRun({
    toolNames: ['write_file', 'string_replace_lsp', 'view'],
  }),
}).generateScore(({ run }) => {
  // Only messages with these tool calls remain
  return 1
})
```

### 移除字段

移除 Scorer 不需要的字段：

```typescript
import { createScorer, filterRun } from '@mastra/core/evals'

const simpleScorer = createScorer({
  id: 'response-length',
  description: 'Checks response length',
  type: 'agent',
  prepareRun: filterRun({
    dropRequestContext: true,
    dropExpectedTrajectory: true,
    dropGroundTruth: true,
    maxOutputMessages: 5,
  }),
}).generateScore(({ run }) => {
  return run.output.length > 0 ? 1 : 0
})
```

## 参数

**options** (`FilterRunOptions`): 用于控制 Scorer 接收哪些数据的配置对象。

**options.partTypes** (`MastraPartType[]`): 仅保留 part 与这些类型匹配的消息。每一项都与消息 part 的 type 进行前缀匹配。除非明确排除，否则始终保留纯文本消息（不含 Tool 调用）。System 消息和带标签的 System 消息永远不会被筛除。

**options.toolNames** (`string[]`): 仅保留针对这些特定 Tool 的 Tool 调用消息。每一项都与 Tool 名称进行前缀匹配。非 Tool 消息（文本、数据）不受影响。

**options.maxRememberedMessages** (`number`): remembered messages（上下文）中最多保留的消息数量。从末尾（最新消息）开始取。在类型和 Tool 筛选后应用。

**options.maxOutputMessages** (`number`): 输出中最多保留的消息数量。从末尾开始取。在类型和 Tool 筛选后应用。

**options.dropRequestContext** (`boolean`): 从 run 中完全移除 request context。

**options.dropExpectedTrajectory** (`boolean`): 从 run 中移除 expected trajectory。

**options.dropGroundTruth** (`boolean`): 从 run 中移除 ground truth。

**返回值：** `(run: ScorerRun) => ScorerRun`。该函数可用于 [`createScorer()`](https://mastra.zisheng.pro/reference/evals/create-scorer) 的 `prepareRun` 选项。

## Part 类型

`partTypes` 选项接受 `MastraPartType` 值。每个值都按前缀匹配，因此 `'data-'` 会匹配所有 data part 类型。

| 类型                  | 描述                             |
| ------------------- | ------------------------------ |
| `'text'`            | 文本内容 part                      |
| `'tool-invocation'` | Tool 调用和结果 part                |
| `'reasoning'`       | 思维链 reasoning part             |
| `'step-start'`      | 步骤标记 part                      |
| `'image'`           | 图像 part                        |
| `'file'`            | 文件 part                        |
| `'source'`          | 来源引用 part                      |
| `'source-document'` | 来源文档 part                      |
| `'data-'`           | 所有 data part（匹配任意 `data-*` 前缀） |
| `'data-om-'`        | Observational Memory 数据 part   |
| `'data-workspace-'` | Workspace 数据 part              |
| `'data-sandbox-'`   | Sandbox 数据 part                |
| `'data-tool-'`      | Tool 相关 data part              |

## 筛选行为

- 当 `input.rememberedMessages` 和 `output` 包含 Agent 消息数组时，**Part 类型筛选**会同时应用于二者。
- **Tool 名称筛选**仅影响包含 Tool 调用的消息。纯文本消息会直接保留。
- 无论 `partTypes` 或 `toolNames` 如何设置，**System 消息**（`systemMessages`、`taggedSystemMessages`）都不会被筛选。
- **消息数量限制**（`maxRememberedMessages`、`maxOutputMessages`）会在类型和 Tool 筛选后应用，并保留最新的消息。
- 同时设置 `partTypes` 和 `toolNames` 时，消息必须满足两个筛选条件才会被保留。