> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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',
    }),
  ],
})
```

## 构造函数参数

**rules** (`RegexRule[]`): 要应用的自定义正则表达式规则。每条规则都有名称、正则表达式模式和可选的替换字符串。

**rules.name** (`string`): 规则的显示名称（用于匹配报告和错误消息）。

**rules.pattern** (`RegExp`): 用于匹配的正则表达式模式。

**rules.replacement** (`string`): redact 策略的替换字符串。默认为 '\[REDACTED]'。

**presets** (`('pii' | 'secrets' | 'urls')[]`): 内置预设类别。'pii' 匹配电子邮件、电话号码、SSN 和信用卡。'secrets' 匹配 API 密钥、bearer token 和 AWS 密钥。'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 元数据包括：

- `processorId`: `'regex-filter'`
- `matches`：包含 `rule`、`match`（遮盖为 `'[REDACTED_MATCH]'`）和 `index` 的匹配对象数组
- `strategy`: `'block'`

## 内置预设

| 预设        | 模式                           | 默认替换文本                                         |
| --------- | ---------------------------- | ---------------------------------------------- |
| `pii`     | 电子邮件、电话号码、SSN、信用卡号           | `[EMAIL]`, `[PHONE]`, `[SSN]`, `[CREDIT_CARD]` |
| `secrets` | API 密钥、bearer token、AWS 访问密钥 | `[API_KEY]`, `[BEARER_TOKEN]`, `[AWS_KEY]`     |
| `urls`    | HTTP/HTTPS URLs              | `[URL]`                                        |

## 遮盖行为

每条规则都独立匹配，因此两条规则可能命中重叠文本。例如，不带分隔符的卡号会同时匹配 `phone` 和 `credit-card`。重叠的匹配项会合并为单个区域，并使用最长匹配项的替换文本替换一次。

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

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

替换字符串可以使用 `$1` 或 `$&` 引用捕获组。对于模式也能独立匹配已匹配文本的单个匹配项，这些引用会被解析。对于合并区域，或者使用后顾或前瞻锚定周围内容的规则，替换字符串会按原样插入。无论哪种情况，该区域都会被遮盖。

## 遮盖报告

`redact` 策略会就地重写文本，因此下游无法判断发生了哪些更改。可赋值 `onViolation` 进行记录。Processor 会为每条被遮盖的消息、消息部分或流数据块调用一次该回调，偏移量相对于相应文本。异步回调会被等待，错误也会被捕获，因此审计接收端不可用不会导致请求失败。

```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,
    })
  }
}
```

系统会等待该回调，包括在 `processOutputStream` 中；此时，每个包含匹配项的数据块都会运行回调。请确保回调快速完成，或将工作交给队列，以免缓慢的审计接收端阻塞流式响应。未附加回调时，`redact` 路径保持同步。

`block` 策略通过同一个回调进行报告。在这种情况下，Processor runner 会在捕获 `TripWire` 时调用它，因此 `detail` 包含[错误行为](#error-behavior)中所述的 tripwire 元数据，而不是下面的数据结构。

遮盖操作的 `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`): 被遮盖区段在文本中的起始偏移量。

**redactions.length** (`number`): 被遮盖区段的长度。

**redactions.replacement** (`string`): 用于替换该区段的文本。

**redactions.overlappingRules** (`string[]`): 匹配此区段的所有规则名称，仅在多个规则重叠时设置。

**redactions.value** (`string`): 被遮盖的文本。仅在启用 includeRedactedValues 时设置。

默认不包含这些值。审计轨迹如果复制它所保护的数据，就会扩大原本试图缩小的暴露范围。只有当目标位置受到与原始位置同等保护时，才应设置 `includeRedactedValues`。另请注意，出于同样的原因，`block` 策略也不会在其 `TripWire` 元数据中包含匹配文本。