# sensitive-word **Repository Path**: superLake/sensitive-word ## Basic Information - **Project Name**: sensitive-word - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-23 - **Last Updated**: 2026-09-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 敏感词过滤 · 从 20 行代码到企业级 > 一个**零框架依赖**的敏感词过滤教学项目:五种匹配实现的横向评测,加一套零曝光的分层测试体系。 **本仓库不含任何词条原文。** 词库需自行获取并现场清洗(见[快速开始](#快速开始))。 仓库里带的两份词库产物 —— `data/built/report.md` 与 `data/built/manifest.tsv` —— 是**脱敏**的, 只由指纹、长度、分类和计数构成。 --- ## 这个项目在做什么 一句话:**把"敏感词过滤"从"能跑"做到"可测量"。** 大多数教程到"AC 自动机比 Trie 快"就结束了。但真实系统里更贵的问题不是"快不快",而是: | 问题 | 对应能力 | |---|---| | 用户把词拆开、插空格、插零宽字符,你还认不认得? | **召回**(能力边界) | | 你说没有误杀,是真没有,还是**根本没认出来**? | **误杀率**(口径问题) | | 你改了词库,怎么证明**改好了**而不是更糟? | **回归**(工程闭环) | 所以这个项目的重心是**测试体系**,算法只是被测量的对象。 如果只想看算法,直接读 [`algo/`](algo/);想看整套方法论,从 [`tests/README.md`](tests/README.md) 开始。 --- ## 环境要求 | 项 | 要求 | |---|---| | PHP | >= 7.2(实测 7.2.34 与 7.4 均通过) | | 扩展 | `mbstring`、PCRE(PHP 默认自带) | | Composer | **不需要** | | 第三方依赖 | **零** | 这不是口号,是可验证的:把 `algo/`、`tests/`、`tools/` 三个目录单独拷出去, 不装 composer、不装任何依赖,全部脚本照样跑通。 --- ## 快速开始 ### 1. 取词库并清洗 ```bash # 上游词库(MIT 协议):https://github.com/Konsheng/Sensitive-lexicon git clone --depth=1 https://github.com/Konsheng/Sensitive-lexicon.git /tmp/Sensitive-lexicon # 清洗成机器可用的索引。产物落在 data/built/(权限 0700,已 gitignore) php tools/clean_lexicon.php \ --raw=/tmp/Sensitive-lexicon/Vocabulary \ --out=data/built ``` 产出两类东西,**判据完全不同**: | 产物 | 含原文? | 进版本库? | |---|---|---| | `lexicon_cn.txt` 等(机器索引用) | 是 | **否**(`.gitignore` 挡住) | | `report.md` / `manifest.tsv`(体检报告 + 指纹清单) | 否(只有指纹与计数) | 是 | ### 2. 生成用例并跑分 ```bash php tests/gen_cases.php # L0/L1 用例(含原文,已 gitignore) php tests/run_eval.php --matcher=05_normalized # 跑一个实现 php tests/compare.php # 多个实现的横评表 ``` > ⚠️ `01_naive` 单条约 120 ms,全量 174,300 条要跑 5 小时以上。 > 跑它必须带 `--sample`:`php tests/run_eval.php --matcher=01_naive --sample=1000 --latency-sample=100` ### 3. 生成 L2 良性语料(误杀率的唯一来源) ```bash php tests/gen_corpus_l2.php # 6,000 段,含 5 种排版配对 php tests/l2_diff.php --matcher=05_normalized --compare=04_ac ``` ### 4. 自检套件 ```bash php tests/check_determinism.php # 同 seed 两次输出必须字节级一致 php tests/check_corpus_l2.php # L2 产物的 13 项只读审计(含确定性审计) php tests/check_no_leak.php # 零曝光审计(脚本 stdout 不得含词条原文) php tests/check_eval_report.php --report=<跑分报告路径> # 报告本身也不得含词条原文 ``` --- ## 目录结构 ``` ├── algo/ # 五种匹配实现,共用 Matcher 接口 │ ├── Matcher.php # ★ 唯一接口:build / scan / name │ ├── 01_naive.php # 逐词扫描(基准线) │ ├── 02_regex.php # 一条超长正则(分片编译) │ ├── 03_trie.php # Trie 前缀树 │ ├── 04_ac.php # AC 自动机 │ └── 05_normalized.php # AC + 归一化(唯一能做能力层的实现) ├── tests/ # 测试体系(本项目的重心) │ ├── README.md # ★ 使用手册,最详细的一份 │ ├── run_eval.php # 跑分器(不含任何匹配算法,后端靠 --matcher 注入) │ ├── compare.php # 横评表(只读 baselines/*.json,不 require 任何 algo) │ ├── gen_cases.php # L0/L1 用例生成器 │ ├── gen_corpus_l2.php # L2 良性语料生成器(配对排版) │ ├── l2_diff.php # 误杀候选清单 + 归一化差异分析 │ ├── triage_l2.php # 人工判决工位(唯一允许 reveal 词条的脚本) │ │ # 顺带落一张零曝光的待填判定表到 docs/test/ │ ├── decide_l2.php # 读回填的表 → 生成判定文件(核对身份/数字,绝不猜判定词) │ ├── check_*.php # 四个只读自检器 │ ├── lib/ # 共用读取层(口径只允许有一份) │ ├── cases/ # ★ 可提交的输入:config.php + 两份手写语料 │ └── baselines/ # 五份实测基线 JSON(脱敏,可提交) ├── tools/ │ ├── clean_lexicon.php # 词库清洗器(零曝光:报告里只有指纹) │ ├── measure_baseline.php # 算法基准脚本 │ └── verify_*.php # 文档结论核对工具 ├── data/built/ # 只提交脱敏产物;lexicon_*.txt 与 .salt 被 gitignore └── docs/ # 三份设计文档 + 一门 12 课教学课 ``` --- ## 五种实现横评(实测) 统一口径:`--sample=1000 --latency-sample=100`,L2 全量 6,170 段。 原始数据在 [`tests/baselines/`](tests/baselines/),横评表由 `php tests/compare.php` 现场生成。 | 实现 | L1 召回 | L2 误杀·手写 | L2 误杀·生成 | 布局极差 | P50 | 加速比 | |---|---:|---:|---:|---:|---:|---:| | `01_naive` | 0.0% | 24.12% | 6.70% | 28.33pp | 112.8 ms | 1× | | `02_regex` | 0.0% | 24.12% | 6.70% | 28.33pp | 1.51 ms | 74.8× | | `03_trie` | 0.0% | 24.12% | 6.70% | 28.33pp | 0.084 ms | 1,344× | | `04_ac` | 0.0% | 24.12% | 6.70% | 28.33pp | 0.079 ms | 1,430× | | `05_normalized` | **100%** | 24.12% | 11.17% | **0.00pp** | 0.317 ms | 356× | L0 召回与位置准确率:五个实现全部 **100%**。 **三句话读这张表:** 1. **L1 全 0% 不是 bug,是设计。** 01~04 不做归一化,"测 试"对它们就是"测"+"空格"+"试", 永远不等于词库里的"测试"。这一列的 0% 恰好证明:**归一化不是可选优化,是能不能用的分界线。** 2. **正则把成本从"扫描"搬到了"编译"**:单条快 75 倍,但建索引要 6 秒(要编译 26,073 个词的分片模式), 而且耗时随词库线性增长 —— 词库每次热更新都要重付这笔钱。 3. **Trie 与 AC 基本打平。** 中文本 + 2~10 字短词这个场景下,Trie 每个起点最多走 10 步, "退回根重来"的浪费本来就不大。**AC 的主场是长模式、大字符集、流式匹配 —— 结论是场景给的,不是算法名给的。** **"布局极差"这一列是这张表里最容易被误读的:** 01~04 在逐字空格的文本上误杀率是 0.00%, 看起来比 05 干净得多。但那不是"干净",是**整体失能** —— 它们在那种文本上连真命中都认不出 (L1 的 `insert_space` 召回 0.00%)。**"不误报"和"不工作"是同一件事。** 判据要换成**布局不变性**:同一批句子换 5 种排版后,命中集合是否不变。结果 05 = **100.00%**、04 = 88.83%。 --- ## 测试体系:四层材料 + 三个口径 | 层 | 内容 | 判据性质 | 实测 | |---|---|---|---| | **L0** | 合成正例(词库直拼) | **硬判据**,必须 100% | 五个实现全 100% | | **L1** | 变形正例(9 类 Tier 1 变形) | **能力判据**,召回低不算失败 | 只有 05 是 100% | | **L2** | 良性负例(**误杀率唯一来源**) | 越低越好,但要看口径 | 见上表 | | **L3** | 对抗集 | 待建 | — | ### 误杀率有**三个不可合并的口径** | 口径 | 数值 | 为什么不能合并 | |---|---:|---| | 手写语料(170 段) | 24.12% | 最可信,是人工设计的真实形态 | | 生成语料(过滤素材) | 11.17% | **下界** —— 过滤本身朝"少误报"方向挑样本 | | 生成语料(不过滤) | 31.00% | 上界 —— 素材里含真敏感词片段 | **素材过滤会让误杀率被低估 2.8 倍**(11.17% vs 31.00%),这个偏差是可实测的: `php tests/gen_corpus_l2.php --no-filter`。 ### L2 语料为什么必须**配对** 同一批 base 句子同时产出 5 种排版(`plain` / `cjk_space` / `fw_space` / `indent_fw` / `mixed_ascii`), 字序列完全一致。这样指标差异**只能归因于排版**,不能归因于"恰好抽到不同句子"。 没有配对,你分不清是排版引起的还是样本引起的。 --- ## 文档索引 | 文档 | 内容 | |---|---| | [`docs/敏感词过滤服务搭建课.md`](docs/敏感词过滤服务搭建课.md) | **12 课教学课**,从 `str_replace` 一路到企业级骨架,每课都撞一次墙 | | [`docs/敏感词过滤原理与方案设计.md`](docs/敏感词过滤原理与方案设计.md) | 原理与方案设计 | | [`docs/测试体系设计方案与实施计划.md`](docs/测试体系设计方案与实施计划.md) | 测试体系设计、实施计划与进度看板(含所有被推翻的假设) | | [`tests/README.md`](tests/README.md) | 测试体系使用手册 —— 最详细、最该先读的一份 | | [`algo/README.md`](algo/README.md) | 五种实现的代码约定(为什么故意不抽公共方法) | --- ## 已知缺口 - **T4.3 误杀候选的人工二分类未完成** —— 所以现在只能说"候选",不能说"误报"。 工具链**已全部就绪**(出表 → 填表 → 出门三步): ```bash php tests/triage_l2.php --source=all --samples=3 --limit=6 # ⚠️ 唯一会打印词条原文,直接看别重定向 # 在 docs/test/l2_decision_table.md 里填「误报 / 可接受」 php tests/decide_l2.php # 干跑核对 php tests/decide_l2.php --out=tests/cases/l2_decisions.json # 写出 ``` 欠的只是**人去看一眼、给个结论**——那一步的定义就是人工判决,不能由脚本代劳。 - **真实 L3 对抗/回流集仍待补齐** —— 已有 40 条精确例外的合成边界示例,运行 `php tests/gen_cases_l3.php`、`php tests/run_l3.php`;详见 [S4 工具说明](tests/README.md)。合成通过不代表真实误报已修复。 - **Tier 2/3 变形完全没测**(繁简、拼音、形近字),需要外部词表。 - **L1 只覆盖 `cn` 通道**;`url` / `ascii` 通道的变形语义完全不同,需要单独设计用例。 - **延迟数字跨轮次不可直接比较**:五份基线是五次独立运行测的,同代码的 P50 在 0.266→0.317 ms 之间漂了 19%。量级结论稳,小数位不稳。要严格比延迟,得让几个实现在同一进程内交替测同一批文本。 - **L2 语料有"模板味"**:词汇集中在 4 个领域的词池里。它的强项是排版配对,弱项是覆盖面。 - **L2 语料里有重复文本**:6,170 行去重后 6,043 行(107 组)。不影响配对比较, 但"命中 211 段"里少数是同一句被重复计;判定文件按「原文+词+区间」去重,条数会略小于逐段计数。 --- ## 零曝光约定(改代码前请先读) 这个项目的所有工具都遵守一条约定:**报告、日志、标准输出里不出现词条原文**, 需要指向某一条目时使用「带盐指纹 + 长度 + 通道」。只有 `tests/triage_l2.php` 例外 —— 人工判决必须看到词条,所以它被单独关进笼子(同屏只暴露一个词条,其余 ≥3 字命中用等长 `▓` 遮掉)。 改动这条链路时请注意: - **审计器要站在生成器外部**,不引用生成器素材,否则"素材被改坏"永远查不出来; - **零曝光审计不能沿用"0 命中"当判据扫源码**:源码注释是中文散文,与一个 26,073 条的分类词库 必然碰撞(实测全仓库去重后 19 条,全是"要不要""第一次"这类日常词)。 正确的判据是**泄露的形态**:单文件成百上千条才是词表泄露,少量词散落在几十个文件里是碰撞。 - 审计器必须带**阳性对照**(塞一个 200 条词的人造泄露文件,断言它被抓到)。 审计器自己坏了却报 PASS,比没有审计更糟。 --- ## 开源许可与致谢 - 词库来自 [Konsheng/Sensitive-lexicon](https://github.com/Konsheng/Sensitive-lexicon)(MIT 协议)。 本仓库**不包含**该词库的任何词条原文。 - 本项目代码用于**防御性内容安全系统**的技术研究与教学:评测过滤引擎的召回率、 误杀率与性能,以及如何在不泄露词表的前提下建立回归体系。