SensitiveWords

English | 简体中文

SensitiveWords 是一个使用 C++ 实现的轻量级 AC 自动机示例项目。它面向敏感词检测场景：离线构建敏感词集合，然后扫描长文本并返回所有命中的敏感词 ID。

项目目前处于早期开发阶段，核心匹配流程已经可运行，数据加载、Unicode 规范化、测试和生产级接口仍在规划中。

1. 当前能力

• 使用 SensitiveWord 维护敏感词 ID 和内容。
• 通过 Trie 插入敏感词，并使用 BFS 构建失败指针。
• 一次扫描返回文本中所有命中的敏感词 ID。
• 支持重叠词和后缀词匹配。
• 使用 RAII 管理自动机节点，无需手动释放节点内存。
• 通过 CMake 构建，并生成 compile_commands.json。

当前限制：暂不支持敏感词标签、匹配位置、删除或更新词条、外部数据源、字符规范化和稳定的公共库接口。

2. 快速开始

2.1 环境要求

• 支持 C++11 的编译器
• CMake 4.4 或更高版本
• Bash（仅一键运行脚本需要）

支持平台的完整兼容性矩阵需要补充。

2.2 一键构建并运行

./run.sh

当前示例成功运行后输出：

2
1

2.3 手动构建

cmake -S . -B build
cmake --build build
./build/SensitiveWords

CMake 配置后会在 build/compile_commands.json 生成编译数据库，可供 clangd 等工具使用。

3. 基础用法

#include "ac-automaton.h"
#include "sensitive-word.h"

engine::AcAutomaton automaton;
automaton.insert(type::SensitiveWord(1, "SB"));
automaton.insert(type::SensitiveWord(2, "脑瘫"));
automaton.build();

const std::vector<int> ids = automaton.matching("你这个脑瘫真是个SB");

推荐调用顺序：

1. 使用 insert 插入全部敏感词。
2. 调用一次 build 构建失败指针和输出集合。
3. 使用 matching 扫描一个或多个文本。

结果按文本扫描顺序返回。一个敏感词出现多次时，其 ID 也会出现多次；拥有相同内容但 ID 不同的词条会分别返回。空内容词条会被忽略。

4. 架构与项目结构

flowchart LR
    A[SensitiveWord: ID + 内容] --> B[insert: 构建 Trie]
    B --> C[build: 失败指针与输出集合]
    C --> D[matching: 扫描文本]
    D --> E[vector<int>: 命中 ID]

Loading

.
├── CMakeLists.txt
├── run.sh
├── src
│   ├── main.cpp
│   ├── sensitive-word.h
│   └── engine
│       ├── ac-automaton.h
│       └── ac-automaton.cpp
└── AGENTS.md

• src/sensitive-word.h：敏感词数据结构。
• src/engine/：AC 自动机节点、构建和搜索实现。
• src/main.cpp：最小运行示例。
• run.sh：配置、编译并运行项目。
• AGENTS.md：AI Agent / Codex 协作约束。

5. Roadmap

以下内容是基于当前代码的方向规划，不代表已经交付。

近期：数据模型与接口完整性

• 为 SensitiveWord 增加标签等可选元数据。
• 增加包含敏感词 ID、起止位置和词长的匹配结果结构。
• 明确重复 ID、重复内容和结果去重策略。
• 支持从文本、JSON 或其他配置文件批量加载敏感词。
• 增加大小写、全半角和 Unicode 规范化策略。

中期：质量与性能

• 补充构建、失败指针、重叠匹配和中文匹配测试。
• 建立长文本、大词库下的性能与内存基准。
• 减少输出集合中的敏感词对象复制，评估仅保存 ID 或索引。
• 支持构建后只读的并发搜索和版本化自动机快照。
• 增加输入校验、错误状态和构建状态检查。

长期：工程化与集成

• 将 AC 自动机拆分为可复用的 CMake Library Target。
• 提供稳定的 CLI，并评估按需提供服务接口。
• 支持敏感词库持久化、增量更新或热切换。
• 建立 CI、发布版本、变更日志和性能回归流程。

6. 开发与贡献

提交前至少执行：

./run.sh

当前仓库尚未配置自动化测试和云端 CI，需要补充。贡献流程、分支规范、维护者和公开帮助入口也需要补充。

AI 相关开发约束请阅读 AGENTS.md。

如果发现安全漏洞，请不要提交公开 Issue。安全披露邮箱需要补充。

7. 版本与许可证

• Release、Tag 和 Changelog 策略需要补充。
• 仓库目前没有许可证文件；正式使用、修改或分发前需要补充许可证。