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

# filterRun()

透過宣告式選項建立 `prepareRun` 函式。將結果傳遞至 `createScorer()`，即可篩選訊息及限制上下文大小。此函式亦會在評分器管線執行前移除不必要的欄位。

如需宣告式篩選，請使用 [`filterRun()`](#usage-example)。如需要 `filterRun()` 未涵蓋的命令式邏輯，請直接編寫自訂 `prepareRun` 函式。詳情請參閱[自訂評分器：輸入篩選](https://mastra.zisheng.pro/zh-HK/docs/evals/custom-scorers)。

## 使用範例

以下範例建立一個評分器，只會接收 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
})
```

### 移除欄位

移除評分器不需要的欄位：

```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`): 控制評分器接收哪些資料的設定物件。

**options.partTypes** (`MastraPartType[]`): 只保留組件符合這些類型的訊息。每個項目會以訊息組件的類型作前綴比對。除非明確排除，否則純文字訊息（不含 Tool 調用）一律保留。系統訊息及帶標籤的系統訊息絕不會被篩選。

**options.toolNames** (`string[]`): 只保留這些指定 Tool 的 Tool 調用訊息。每個項目會以 Tool 名稱作前綴比對。不含 Tool 的訊息（文字、資料）不受影響。

**options.maxRememberedMessages** (`number`): 在記憶訊息（上下文）中保留的訊息數目上限。從末端（最近的訊息）開始選取。在類型及 Tool 篩選後套用。

**options.maxOutputMessages** (`number`): 在輸出中保留的訊息數目上限。從末端開始選取。在類型及 Tool 篩選後套用。

**options.dropRequestContext** (`boolean`): 從執行中完全移除請求上下文。

**options.dropExpectedTrajectory** (`boolean`): 從執行中移除預期軌跡。

**options.dropGroundTruth** (`boolean`): 從執行中移除標準答案。

**傳回值：** `(run: ScorerRun) => ScorerRun`。適用於 [`createScorer()`](https://mastra.zisheng.pro/zh-HK/reference/evals/create-scorer) 的 `prepareRun` 選項的函式。

## 組件類型

`partTypes` 選項接受 `MastraPartType` 值。每個值都會作前綴比對，因此 `'data-'` 會符合所有資料組件類型。

| 類型                  | 說明                       |
| ------------------- | ------------------------ |
| `'text'`            | 文字內容組件                   |
| `'tool-invocation'` | Tool 調用及結果組件             |
| `'reasoning'`       | 思維鏈推理組件                  |
| `'step-start'`      | 步驟標記組件                   |
| `'image'`           | 圖像組件                     |
| `'file'`            | 檔案組件                     |
| `'source'`          | 來源參考組件                   |
| `'source-document'` | 來源文件組件                   |
| `'data-'`           | 所有資料組件（符合任何 `data-*` 前綴） |
| `'data-om-'`        | 觀察記憶資料組件                 |
| `'data-workspace-'` | Workspace 資料組件           |
| `'data-sandbox-'`   | Sandbox 資料組件             |
| `'data-tool-'`      | Tool 相關資料組件              |

## 篩選行為

- 當 `input.rememberedMessages` 及 `output` 包含 Agent 訊息陣列時，**組件類型篩選**會套用至兩者。
- **Tool 名稱篩選**只會影響包含 Tool 調用的訊息。純文字訊息會直接通過。
- 無論 `partTypes` 或 `toolNames` 為何，**系統訊息**（`systemMessages`、`taggedSystemMessages`）絕不會被篩選。
- **訊息限制**（`maxRememberedMessages`、`maxOutputMessages`）會在類型及 Tool 篩選後套用，並選取最近的訊息。
- 同時設定 `partTypes` 及 `toolNames` 時，訊息必須符合兩項篩選條件才會保留。