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

# filterRun()

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

如需宣告式篩選，請使用 [`filterRun()`](#usage-example)。若需要命令式邏輯，請直接撰寫自訂 `prepareRun` 函式，以涵蓋 `filterRun()` 不支援的需求。如需更多資訊，請參閱[自訂評分器：輸入篩選](https://mastra.zisheng.pro/zh-TW/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`。此函式適合用作 `prepareRun` 選項，該選項位於 [`createScorer()`](https://mastra.zisheng.pro/zh-TW/reference/evals/create-scorer)。

## 部分類型

`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 呼叫的訊息。僅含文字的訊息會保留。
- **系統訊息**（`systemMessages`、`taggedSystemMessages`）絕不會遭到篩選，不受 `partTypes` 或 `toolNames` 影響。
- **訊息限制**（`maxRememberedMessages`、`maxOutputMessages`）會在類型與 Tool 篩選後套用，並取用最新訊息。
- 同時設定 `partTypes` 與 `toolNames` 時，訊息必須符合兩個篩選條件才會保留。