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',
}),
],
})
Constructor 參數Constructor 參數 的直接連結
rules?:
name:
pattern:
replacement?:
presets?:
strategy?:
phase?:
includeRedactedValues?:
streamCarryoverSize?:
傳回值傳回值 的直接連結
id:
name:
processInput:
processOutputStream:
processOutputResult:
錯誤行為錯誤行為 的直接連結
啟用 block 策略（預設值）時，如有任何模式相符，RegexFilterProcessor 會拋出 retry: false 的 TripWire 錯誤。TripWire metadata 包含：
processorId：'regex-filter'matches：比對物件的陣列，當中包含rule、match（遮蔽為'[REDACTED_MATCH]'）及indexstrategy：'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。重疊的比對項目會合併成單一區域，只取代一次，並採用最長比對項目的替代內容。
const filter = new RegexFilterProcessor({
presets: ['pii'],
strategy: 'redact',
})
// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
替代字串可以透過 $1 或 $& 參照擷取群組。如果只有一個比對項目，且其模式本身亦能符合已比對的文字，這些參照便會被解析。若屬合併區域，或規則透過 lookbehind 或 lookahead 錨定周邊內容，則會直接插入替代字串的原文。不論哪種情況，該區域都會被遮蔽。
遮蔽報告遮蔽報告 的直接連結
redact 策略會就地改寫文字，因此下游無法得知有哪些變更。可指定 onViolation 以記錄變更。Processor 會為每則已遮蔽的訊息、訊息部分或串流資料區塊呼叫一次，而 offset 是相對於該段文字計算。系統會等待非同步 callback 完成，並會擷取錯誤，避免因審計資料接收端無法使用而導致請求失敗。
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 會包含錯誤行為所述的 tripwire metadata，而非下方的資料結構。
遮蔽操作的 detail 是 RegexRedactionDetail：
strategy:
block 策略的 payload。phase:
messageId?:
partIndex?:
redactions:
rule:
index:
length:
replacement:
overlappingRules?:
value?:
預設不會包含值。若審計記錄複製其原意要保護的資料，便會擴大本來要收窄的資料暴露範圍。只有當目的地受到與原始資料同等程度的保護時，才應設定 includeRedactedValues。另請注意，基於相同原因，block 策略亦不會在其 TripWire metadata 中提供符合的文字。