敏感词过滤中间件教程

本教程对应 xpert-plugins 中的 @xpert-ai/plugin-sensitive-filter，用于在智能体输入与输出阶段执行敏感内容过滤。

​

适用场景

• 过滤身份证、手机号、银行卡等隐私信息
• 对高风险文本直接拦截（block）
• 对可修复文本自动改写（rewrite）

​

安装与启用

1. 在宿主项目安装插件包：

npm install @xpert-ai/plugin-sensitive-filter

2. 在环境变量中启用插件（多插件用逗号分隔）：

PLUGINS=@xpert-ai/plugin-sensitive-filter

3. 参考 插件发布与使用 完成宿主加载。

​

运行机制

• beforeAgent：处理用户输入（可改写或拦截）
• wrapModelCall：处理模型输出（可改写或拦截）
• afterAgent：写入审计快照

​

配置模式

该中间件有两种互斥模式：

• rule：规则匹配（keyword / regex）
• llm：自然语言策略判定（命中后内部按 rewrite 策略处理）

​

Rule 模式最小配置

{
  "mode": "rule",
  "caseSensitive": false,
  "normalize": true,
  "rules": [
    {
      "id": "rule-1",
      "pattern": "身份证",
      "type": "keyword",
      "scope": "both",
      "severity": "high",
      "action": "block",
      "replacementText": "内容包含敏感信息，已拦截。"
    }
  ]
}

rule 模式下每条规则至少需要： pattern、type、scope、severity、action。

​

LLM 模式最小配置

{
  "mode": "llm",
  "llm": {
    "model": {
      "provider": "openai",
      "model": "gpt-4o-mini"
    },
    "scope": "both",
    "rulePrompt": "如果内容包含身份证、手机号、银行卡或家庭住址，请改写为隐私安全回复。",
    "rewriteFallbackText": "[已过滤]",
    "timeoutMs": 3000
  }
}

llm 模式运行时必填： model、scope、rulePrompt。

​

联调建议

1. 先用 rule 模式验证命中链路，确认拦截/改写行为正确。
2. 再切到 llm 模式验证语义判定效果。
3. 检查审计记录中输入/输出阶段是否都有命中信息。

​

常见问题

• rule 模式无效果：通常是规则字段不完整，或 scope 与触发阶段不匹配。
• llm 模式无效果：先确认 model、scope、rulePrompt 都已配置。
• LLM 命中后结果异常：优先查看审计中错误策略痕迹（如 llm-error）以定位模型判定失败原因。