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

# RegexFilterProcessor

`RegexFilterProcessor` 透過零成本的正則表達式模式比對，篩選、遮蔽或封鎖 Agent 訊息中的內容。過程不會呼叫 LLM，所有偵測均以正則表達式為基礎。

它支援常見模式（PII、機密資料、URL）的內置預設，以及自訂正則表達式規則，並可套用於輸入、輸出或兩個階段。

## 使用範例

封鎖輸入訊息中的 PII：

```typescript
import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'block',
  phase: 'input',
})
```

遮蔽輸出中的機密資料：

```typescript
import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['secrets'],
  strategy: 'redact',
  phase: 'output',
})
```

自訂規則：

```typescript
import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  rules: [{ name: 'internal-id', pattern: /INTERNAL-\d{6}/g, replacement: '[INTERNAL_ID]' }],
  strategy: 'redact',
})
```

如要處理較長的自訂比對項目（例如固定長度的機密資料，或只會在結尾分隔符出現後才符合的值），可增加串流延續視窗：

```typescript
import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  rules: [
    {
      name: 'armored-key',
      pattern: /-----BEGIN KEY-----[A-Z]+-----END KEY-----/g,
      replacement: '[KEY]',
    },
  ],
  strategy: 'redact',
  streamCarryoverSize: 256,
})
```

附加至 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { RegexFilterProcessor } from '@mastra/core/processors'

const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  model: 'openai/gpt-5-nano',
  inputProcessors: [
    new RegexFilterProcessor({
      presets: ['pii', 'secrets'],
      strategy: 'block',
    }),
  ],
})
```

## Constructor 參數

**rules** (`RegexRule[]`): 要套用的自訂正則表達式規則。每項規則均包含名稱、正則表達式模式，以及可選的替代字串。

**rules.name** (`string`): 規則的顯示名稱（用於比對報告和錯誤訊息）。

**rules.pattern** (`RegExp`): 用來比對的正則表達式模式。

**rules.replacement** (`string`): redact 策略使用的替代字串。預設為 '\[REDACTED]'。

**presets** (`('pii' | 'secrets' | 'urls')[]`): 內置預設類別。'pii' 會比對電郵地址、電話號碼、社會安全號碼及信用卡號碼；'secrets' 會比對 API key、bearer token 及 AWS key；'urls' 會比對 HTTP/HTTPS URL。

**strategy** (`'block' | 'redact' | 'warn'`): 找到符合模式的內容時所採用的策略。'block' 會以 TripWire 錯誤中止操作；'redact' 會以替代文字取代符合的內容；'warn' 會記錄警告，但讓內容維持不變並繼續傳遞。 (Default: `'block'`)

**phase** (`'input' | 'output' | 'all'`): 套用篩選器的階段。'input' 會篩選輸入訊息；'output' 會篩選輸出串流及結果；'all' 會同時篩選兩者。 (Default: `'all'`)

**includeRedactedValues** (`boolean`): 在每個報告項目中包含已遮蔽的文字。此選項預設關閉，因為這些值正是 Processor 要移除的資料。 (Default: `false`)

**streamCarryoverSize** (`number`): 串流遮蔽路徑在各資料區塊之間保留的末尾字元數，讓跨越資料區塊邊界的比對項目能夠完整遮蔽。預設值留有充足餘量，足以涵蓋所有內置預設。若自訂規則的比對項目在完成之前都無法被規則識別（例如固定長度的機密資料或有結尾分隔符的值），而該比對項目可能比視窗更長，便應增加此值。 (Default: `128`)

## 傳回值

**id** (`'regex-filter'`): Processor 識別碼。

**name** (`'Regex Filter'`): Processor 顯示名稱。

**processInput** (`(args: ProcessInputArgs) => ProcessInputResult`): 以所有已設定的規則檢查輸入訊息，並按策略封鎖、遮蔽或發出警告。當 phase 為 output 時會略過。

**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null | undefined>`): 以所有已設定的規則檢查串流 text-delta 資料區塊。當 phase 為 input 時會略過。

**processOutputResult** (`(args: ProcessOutputResultArgs) => ProcessorMessageResult`): 以所有已設定的規則檢查輸出訊息，並按策略封鎖、遮蔽或發出警告。當 phase 為 input 時會略過。

## 錯誤行為

啟用 block 策略（預設值）時，如有任何模式相符，`RegexFilterProcessor` 會拋出 `retry: false` 的 `TripWire` 錯誤。TripWire metadata 包含：

- `processorId`：`'regex-filter'`
- `matches`：比對物件的陣列，當中包含 `rule`、`match`（遮蔽為 `'[REDACTED_MATCH]'`）及 `index`
- `strategy`：`'block'`

## 內置預設

| 預設        | 模式                                  | 預設替代內容                                      |
| --------- | ----------------------------------- | ------------------------------------------- |
| `pii`     | 電郵地址、電話號碼、社會安全號碼、信用卡號碼              | `[EMAIL]`、`[PHONE]`、`[SSN]`、`[CREDIT_CARD]` |
| `secrets` | API key、bearer token、AWS access key | `[API_KEY]`、`[BEARER_TOKEN]`、`[AWS_KEY]`    |
| `urls`    | HTTP/HTTPS URL                      | `[URL]`                                     |

## 遮蔽行為

每項規則都會獨立比對，因此兩項規則可能會比對到互相重疊的文字。例如，沒有分隔符的信用卡號碼會同時符合 `phone` 和 `credit-card`。重疊的比對項目會合併成單一區域，只取代一次，並採用最長比對項目的替代內容。

```typescript
const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'redact',
})

// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
```

替代字串可以透過 `$1` 或 `$&` 參照擷取群組。如果只有一個比對項目，且其模式本身亦能符合已比對的文字，這些參照便會被解析。若屬合併區域，或規則透過 lookbehind 或 lookahead 錨定周邊內容，則會直接插入替代字串的原文。不論哪種情況，該區域都會被遮蔽。

## 遮蔽報告

`redact` 策略會就地改寫文字，因此下游無法得知有哪些變更。可指定 `onViolation` 以記錄變更。Processor 會為每則已遮蔽的訊息、訊息部分或串流資料區塊呼叫一次，而 offset 是相對於該段文字計算。系統會等待非同步 callback 完成，並會擷取錯誤，避免因審計資料接收端無法使用而導致請求失敗。

```typescript
import { RegexFilterProcessor, type RegexRedactionDetail } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'redact',
})

filter.onViolation = async ({ detail }) => {
  const redaction = detail as RegexRedactionDetail

  for (const entry of redaction.redactions) {
    await auditLog.write({
      phase: redaction.phase,
      messageId: redaction.messageId,
      rule: entry.rule,
      offset: entry.index,
      length: entry.length,
    })
  }
}
```

系統會等待 callback 完成，包括在 `processOutputStream` 中，凡包含比對項目的每個資料區塊都會執行 callback。請確保 callback 能快速完成，或將工作交給 queue，以免緩慢的審計資料接收端令串流回應停滯。如未附加 callback，`redact` 路徑會維持同步執行。

`block` 策略會透過同一個 callback 報告。Processor runner 會在擷取 `TripWire` 時呼叫 callback，因此 `detail` 會包含[錯誤行為](#error-behavior)所述的 tripwire metadata，而非下方的資料結構。

遮蔽操作的 `detail` 是 `RegexRedactionDetail`：

**strategy** (`'redact'`): 用來區分遮蔽報告與 block 策略的 payload。

**phase** (`'processInput' | 'processOutputStream' | 'processOutputResult'`): 套用遮蔽操作的 Processor 方法。

**messageId** (`string`): 文字所屬訊息的 ID。串流資料區塊不會有此項。

**partIndex** (`number`): 已遮蔽部分在訊息 parts 陣列中的索引；該陣列亦包含非文字部分。字串內容及串流資料區塊不會有此項。

**redactions** (`RegexRedaction[]`): 遮蔽項目，按其在文字中的出現次序排列。

**redactions.rule** (`string`): 所使用替代內容所屬規則的名稱。

**redactions.index** (`number`): 已遮蔽範圍在文字中的起始 offset。

**redactions.length** (`number`): 已遮蔽範圍的長度。

**redactions.replacement** (`string`): 用來取代該範圍的文字。

**redactions.overlappingRules** (`string[]`): 所有與此範圍相符的規則名稱；只有多於一項規則互相重疊時才會設定。

**redactions.value** (`string`): 已遮蔽的文字。只有啟用 includeRedactedValues 時才會設定。

預設不會包含值。若審計記錄複製其原意要保護的資料，便會擴大本來要收窄的資料暴露範圍。只有當目的地受到與原始資料同等程度的保護時，才應設定 `includeRedactedValues`。另請注意，基於相同原因，`block` 策略亦不會在其 `TripWire` metadata 中提供符合的文字。