plugin-sensitive-filter-xr 0.0.2 → 0.0.5

package/README.md

@@ -1,63 +1,165 @@
 # Xpert Plugin: Sensitive Filter Middleware
 
-`@xpert-ai/plugin-sensitive-filter` 为智能体提供输入/输出敏感内容过滤能力。
-
-## 功能说明
-
-- `beforeAgent`：检测输入命中，决策 `block / rewrite`
-- `wrapModelCall`：
-  - 输入命中 `block`：直接返回拦截提示，不调用模型
-  - 输入命中 `rewrite`：先改写最后一条 human 消息，再调用模型
-  - 输出命中后再次执行 `block / rewrite`
-- `afterAgent`：空实现（不输出审计日志）
-
-## 规则与优先级
-
-- 支持规则类型：`keyword`、`regex`
-- 支持生效范围：`input`、`output`、`both`
-- 冲突优先级：`high > medium`；同级按配置顺序第一条
-- `rewrite` 为整句替换，不做局部替换
-- `normalize=true` 时执行文本标准化（trim + 空白折叠 + 大小写归一）
-- regex 在中间件初始化时预编译，非法 pattern 会直接抛错
-
-## 配置接口
-
-```ts
-type SensitiveRule = {
-  id: string;
-  pattern: string;
-  type: 'keyword' | 'regex';
-  scope: 'input' | 'output' | 'both';
-  severity: 'high' | 'medium';
-  action: 'block' | 'rewrite';
-  replacementText?: string;
-};
-
-type GeneralPackConfig = {
-  enabled?: boolean;          // default false
-  profile?: 'strict' | 'balanced'; // default balanced
-};
-
-type SensitiveFilterConfig = {
-  rules: Array<Partial<SensitiveRule> | null>; // 必填，且至少 1 条业务规则
-  generalPack?: GeneralPackConfig;
-  caseSensitive?: boolean;    // default false
-  normalize?: boolean;        // default true
-};
+`@xpert-ai/plugin-sensitive-filter` 提供输入/输出敏感内容过滤，支持两种互斥模式：
+
+- `rule`：规则匹配过滤（关键词/正则）
+- `llm`：自然语言规则过滤（固定改写策略）
+
+## 快速上手
+
+1. 在工作流中添加“敏感内容过滤中间件”。
+2. 选择 `mode`：`rule` 或 `llm`（二选一）。
+3. `rule` 模式填写规则表；`llm` 模式只需填写模型、范围、审核规则说明。
+4. 运行工作流验证输入与输出阶段效果。
+5. 查看日志中的审计记录。
+
+## 执行流程
+
+- `beforeAgent`：处理输入
+- `wrapModelCall`：处理输出
+- `afterAgent`：记录审计
+
+## 顶层参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `mode` | `'rule' \| 'llm'` | 是 | `rule` | 过滤模式（互斥）。 |
+| `rules` | `Array<Rule>` | `rule` 模式建议配置 | `[]` | 业务规则，仅 `rule` 模式生效。 |
+| `generalPack` | `object` | 否 | 见子项 | 通用规则包（本地词库兜底），仅 `rule` 模式生效。 |
+| `caseSensitive` | `boolean` | 否 | `false` | 是否区分大小写，仅 `rule` 模式生效。 |
+| `normalize` | `boolean` | 否 | `true` | 是否标准化文本，仅 `rule` 模式生效。 |
+| `llm` | `object` | `llm` 模式执行期必填 | - | LLM 过滤配置，仅 `llm` 模式生效。 |
+
+## rule 模式参数
+
+### rules[]
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `id` | `string` | 否 | 自动生成 `rule-{index+1}` | 规则标识。 |
+| `pattern` | `string` | 是 | - | 匹配内容。 |
+| `type` | `'keyword' \| 'regex'` | 是 | - | 匹配方式。 |
+| `scope` | `'input' \| 'output' \| 'both'` | 是 | - | 生效阶段。 |
+| `severity` | `'high' \| 'medium'` | 是 | - | 冲突优先级（`high > medium`）。 |
+| `action` | `'block' \| 'rewrite'` | 是 | - | 命中动作。 |
+| `replacementText` | `string` | 否 | `[已过滤]`（rewrite 时） | 自定义拦截/改写文本。 |
+
+### generalPack
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `enabled` | `boolean` | 否 | `false` | 是否启用通用规则包。 |
+| `profile` | `'strict' \| 'balanced'` | 否 | `balanced` | `strict` 更严格，`balanced` 更保守。 |
+
+## llm 模式参数（简化版）
+
+### llm
+
+| 字段 | 类型 | 必填（执行期） | 默认值 | 说明 |
+|---|---|---|---|---|
+| `model` | `ICopilotModel` | 是 | - | 用于判定的过滤模型。 |
+| `scope` | `'input' \| 'output' \| 'both'` | 是 | - | 生效范围。 |
+| `rulePrompt` | `string` | 是 | - | 审核规则说明（自然语言，不需要 JSON）。 |
+| `outputMethod` | `'functionCalling' \| 'jsonMode' \| 'jsonSchema'` | 否 | `jsonMode` | 结构化输出首选方式（不支持时自动降级）。 |
+| `rewriteFallbackText` | `string` | 否 | `[已过滤]` | 命中但未返回改写文本时兜底文案。 |
+| `timeoutMs` | `number` | 否 | 不限 | 判定超时（毫秒，上限 `120000`）。 |
+
+### llm 模式行为说明
+
+- 用户只需填写自然语言规则，不需要书写 JSON 协议。
+- 命中后统一执行 `rewrite`。
+- LLM 调用异常时也统一执行 `rewrite`。
+- 若配置了 `timeoutMs` 且判定超时，会直接使用 `rewriteFallbackText` 作为改写结果。
+- 若模型不支持当前 `outputMethod` 的 `response_format`，会自动尝试其它结构化方式并最终降级到纯文本 JSON 解析。
+- 若历史配置仍携带 `onLlmError/systemPrompt/errorRewriteText`，会按兼容逻辑处理并给出弃用告警。
+
+## 界面怎么填（最简）
+
+`mode=llm` 时，最少只需要填这 3 项：
+
+1. `llm.model`：选择过滤用模型（建议稳定、低延迟模型）。
+2. `llm.scope`：建议先用 `both`。
+3. `llm.rulePrompt`：写自然语言审核规则，不需要 JSON。
+
+示例（个人信息场景）：
+
+- `llm.rulePrompt`：如果文本包含手机号、身份证号、银行卡号、家庭住址等个人敏感信息，请判定为命中并给出脱敏改写内容。
+- `llm.rewriteFallbackText`：`[已过滤]`
+
+说明：
+
+- `llm` 模式是“只改写不拦截”。如果你要“直接拦截”，请改用 `mode=rule` 并配置 `action=block`。
+
+## 超时与速度说明
+
+- `timeoutMs` 是“单次 LLM 判定调用的最长等待时间（毫秒）”，不是整条工作流总超时。
+- 设置过小（例如 `3000`）时，慢模型更容易超时，超时后会直接走 `rewriteFallbackText`。
+- 不设置 `timeoutMs` 时，判定会一直等待模型返回，稳定性更高，但最坏延迟会变大。
+- 命中输出过滤时，通常会感觉更慢：因为需要先拿到可判定内容，再统一改写返回。
+- 你看到多个 `success` 卡片是正常的：输入判定、输出判定、收尾审计是不同执行步骤。
+
+## 配置示例
+
+### 示例 1：rule 模式
+
+```json
+{
+  "mode": "rule",
+  "rules": [
+    {
+      "pattern": "炸弹",
+      "type": "keyword",
+      "scope": "both",
+      "severity": "high",
+      "action": "block"
+    },
+    {
+      "pattern": "(身份证|手机号)",
+      "type": "regex",
+      "scope": "output",
+      "severity": "medium",
+      "action": "rewrite",
+      "replacementText": "该回答包含敏感信息，已处理。"
+    }
+  ],
+  "normalize": true,
+  "caseSensitive": false
+}
+```
+
+### 示例 2：llm 模式（推荐）
+
+```json
+{
+  "mode": "llm",
+  "llm": {
+    "model": { "provider": "openai", "model": "gpt-4o-mini" },
+    "scope": "both",
+    "rulePrompt": "若内容包含违法、暴力或隐私泄露，请改写为安全且中性的表达。",
+    "rewriteFallbackText": "[已过滤]",
+    "timeoutMs": 3000
+  }
+}
 ```
 
-业务规则字段约束：
-- 必填：`pattern`、`type`、`action`
-- 条件必填：当 `action='rewrite'` 时，`replacementText` 必填
-- 可选：`id`（留空自动生成）、`scope`（默认 `both`）、`severity`（默认 `medium`）
+## 常见问题
+
+### 1) 为什么没生效？
+
+按顺序检查：
+
+1. `mode` 是否正确。
+2. `rule` 模式是否至少有 1 条有效规则（`pattern/type/action/scope/severity`）。
+3. `llm` 模式是否填写了 `model/scope/rulePrompt`。
+4. `scope` 是否覆盖当前阶段（输入或输出）。
+
+### 2) 为什么提示中文校验错误？
 
-## 通用规则包（General Pack）
+中间件采用“编辑期容错、执行期校验”。编辑阶段允许先保存草稿，执行时再提示缺项。
 
-- `enabled=false`：不启用通用规则
-- `enabled=true, profile=balanced`：词库较小，命中后整句替换
-- `enabled=true, profile=strict`：词库更广，命中后直接拦截
+### 3) 旧配置里的 systemPrompt 还能用吗？
 
-说明：通用规则包用于无内建审核能力的本地模型兜底，业务规则仍建议按场景自行配置。
+可以。若未填写 `rulePrompt`，会兼容读取 `systemPrompt`。建议迁移到 `rulePrompt`。
 
 ## 开发验证
 
@@ -65,5 +167,5 @@ type SensitiveFilterConfig = {
 pnpm -C xpertai exec nx build @xpert-ai/plugin-sensitive-filter
 pnpm -C xpertai exec nx test @xpert-ai/plugin-sensitive-filter
 pnpm -C plugin-dev-harness build
-node plugin-dev-harness/dist/index.js --workspace ./xpertai --plugin @xpert-ai/plugin-sensitive-filter
+node plugin-dev-harness/dist/index.js --workspace ./xpertai --plugin ./middlewares/sensitive-filter
 ```

package/dist/lib/sensitive-filter.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sensitive-filter.module.d.ts","sourceRoot":"","sources":["../../src/lib/sensitive-filter.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAI/F,qBAIa,qBAAsB,YAAW,kBAAkB,EAAE,gBAAgB;IAChF,OAAO,CAAC,UAAU,CAAQ;IAE1B,iBAAiB,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,eAAe,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAKxC"}
+{"version":3,"file":"sensitive-filter.module.d.ts","sourceRoot":"","sources":["../../src/lib/sensitive-filter.module.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAI9F,qBAIa,qBAAsB,YAAW,kBAAkB,EAAE,gBAAgB;IAChF,OAAO,CAAC,UAAU,CAAO;IAEzB,iBAAiB,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,eAAe,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAKxC"}

package/dist/lib/sensitive-filter.module.js

@@ -1,5 +1,6 @@
 var SensitiveFilterPlugin_1;
 import { __decorate } from "tslib";
+import { CqrsModule } from '@nestjs/cqrs';
 import { XpertServerPlugin } from '@xpert-ai/plugin-sdk';
 import chalk from 'chalk';
 import { SensitiveFilterMiddleware } from './sensitiveFilter.js';
@@ -20,7 +21,7 @@ let SensitiveFilterPlugin = SensitiveFilterPlugin_1 = class SensitiveFilterPlugi
 };
 SensitiveFilterPlugin = SensitiveFilterPlugin_1 = __decorate([
     XpertServerPlugin({
-        imports: [],
+        imports: [CqrsModule],
         providers: [SensitiveFilterMiddleware]
     })
 ], SensitiveFilterPlugin);

package/dist/lib/sensitiveFilter.d.ts

@@ -1,9 +1,12 @@
-import { TAgentMiddlewareMeta } from '@metad/contracts';
-import { AgentMiddleware, IAgentMiddlewareContext, IAgentMiddlewareStrategy, PromiseOrValue } from '@xpert-ai/plugin-sdk';
+import type { TAgentMiddlewareMeta } from '@metad/contracts';
+import { AgentMiddleware, IAgentMiddlewareContext, IAgentMiddlewareStrategy } from '@xpert-ai/plugin-sdk';
 import { SensitiveFilterConfig } from './types.js';
 export declare class SensitiveFilterMiddleware implements IAgentMiddlewareStrategy<SensitiveFilterConfig> {
+    private readonly commandBus;
     readonly meta: TAgentMiddlewareMeta;
-    createMiddleware(options: SensitiveFilterConfig, _context: IAgentMiddlewareContext): PromiseOrValue<AgentMiddleware>;
+    createMiddleware(options: SensitiveFilterConfig, context: IAgentMiddlewareContext): Promise<AgentMiddleware>;
+    private createRuleModeMiddleware;
+    private createLlmModeMiddleware;
 }
 export type { SensitiveFilterConfig };
 //# sourceMappingURL=sensitiveFilter.d.ts.map

package/dist/lib/sensitiveFilter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sensitiveFilter.d.ts","sourceRoot":"","sources":["../../src/lib/sensitiveFilter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAEvD,OAAO,EACL,eAAe,EAEf,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACf,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAGL,qBAAqB,EAKtB,MAAM,YAAY,CAAA;AA6QnB,qBAEa,yBAA0B,YAAW,wBAAwB,CAAC,qBAAqB,CAAC;IAC/F,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAgKlC;IAED,gBAAgB,CACd,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,uBAAuB,GAChC,cAAc,CAAC,eAAe,CAAC;CA4GnC;AAED,YAAY,EAAE,qBAAqB,EAAE,CAAA"}
+{"version":3,"file":"sensitiveFilter.d.ts","sourceRoot":"","sources":["../../src/lib/sensitiveFilter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAa,oBAAoB,EAA8B,MAAM,kBAAkB,CAAA;AAGnG,OAAO,EACL,eAAe,EAGf,uBAAuB,EACvB,wBAAwB,EAEzB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAOL,qBAAqB,EAMtB,MAAM,YAAY,CAAA;AAienB,qBAEa,yBAA0B,YAAW,wBAAwB,CAAC,qBAAqB,CAAC;IAE/F,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAY;IAEvC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAqRlC;IAEK,gBAAgB,CACpB,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,eAAe,CAAC;IAa3B,OAAO,CAAC,wBAAwB;IAqOhC,OAAO,CAAC,uBAAuB;CA8YhC;AAED,YAAY,EAAE,qBAAqB,EAAE,CAAA"}