RegexFilterProcessor
RegexFilterProcessor 使用零成本的正则表达式模式匹配来过滤、遮盖或阻止 Agent 消息中的内容。它不会进行 LLM 调用。所有检测都基于正则表达式。
支持常见模式（PII、密钥、URL）的内置预设和自定义正则表达式规则。可应用于输入、输出或两个阶段。
用法示例用法示例的直接链接
阻止输入消息中的 PII：
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
presets: ['pii'],
strategy: 'block',
phase: 'input',
})
遮盖输出中的密钥：
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
presets: ['secrets'],
strategy: 'redact',
phase: 'output',
})
自定义规则：
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
rules: [{ name: 'internal-id', pattern: /INTERNAL-\d{6}/g, replacement: '[INTERNAL_ID]' }],
strategy: 'redact',
})
对于较长的自定义匹配项（例如固定长度的密钥，或只有在结束分隔符到达后才能匹配的 值），请增大流式延续窗口：
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：
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?:
name:
pattern:
replacement?:
presets?:
strategy?:
phase?:
includeRedactedValues?:
streamCarryoverSize?:
返回值返回值的直接链接
id:
name:
processInput:
processOutputStream:
processOutputResult:
错误行为错误行为的直接链接
启用 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。重叠的匹配项会合并为单个区域，并使用最长匹配项的替换文本替换一次。
const filter = new RegexFilterProcessor({
presets: ['pii'],
strategy: 'redact',
})
// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
替换字符串可以使用 $1 或 $& 引用捕获组。对于模式也能独立匹配已匹配文本的单个匹配项，这些引用会被解析。对于合并区域，或者使用后顾或前瞻锚定周围内容的规则，替换字符串会按原样插入。无论哪种情况，该区域都会被遮盖。
遮盖报告遮盖报告的直接链接
redact 策略会就地重写文本，因此下游无法判断发生了哪些更改。可赋值 onViolation 进行记录。Processor 会为每条被遮盖的消息、消息部分或流数据块调用一次该回调，偏移量相对于相应文本。异步回调会被等待，错误也会被捕获，因此审计接收端不可用不会导致请求失败。
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 包含错误行为中所述的 tripwire 元数据，而不是下面的数据结构。
遮盖操作的 detail 是 RegexRedactionDetail：
strategy:
phase:
messageId?:
partIndex?:
redactions:
rule:
index:
length:
replacement:
overlappingRules?:
value?:
默认不包含这些值。审计轨迹如果复制它所保护的数据，就会扩大原本试图缩小的暴露范围。只有当目标位置受到与原始位置同等保护时，才应设置 includeRedactedValues。另请注意，出于同样的原因，block 策略也不会在其 TripWire 元数据中包含匹配文本。