defluff

用途

defluff 是一个确定性的“废话检测器”，专门用于识别 AI 生成文本中的填充短语和陈词滥调。与常见的“AI 检测器”不同，它不判断文本是否由 AI 生成，而是回答一个可确定的问题：这段文本是否包含可移除的填充内容？无论文本由人类还是 LLM 撰写，只要包含如“at the end of the day”之类的短语，就会被标记。

主要能力

• 确定性匹配：基于精心整理的短语列表进行匹配，无模型、无 API 密钥，每次运行结果完全一致。
• 精确片段与评分：返回被标记的精确文本片段（含类别）和一个 0-1 的“填充密度”评分（slop_score = 被标记词数 ÷ 总词数，按类别加权）。
• 多格式感知：在匹配前会剥离代码块、行内代码、URL 和 Markdown 标记。
• 全词匹配：例如“foster”不会在“fostering”内部触发。
• 重叠处理：最长匹配优先，每个词只计一次（如“at the end of the day”与“end of the day”重叠时）。
• 可定制的词库：支持用户级覆盖（~/.config/defluff/）、项目级覆盖（.defluff/ 于 git 根目录）、自定义短语文件（.txt / .md / .json），以及预置领域包。
• MCP 服务器：暴露三个工具，任何支持 MCP 的智能体无需额外接线即可自我检查文本。
• CI 集成：提供退出码、JSON 输出和字符偏移片段，可轻松接入 CI、pre-commit 和编辑器工具。
• 可固定词库哈希：每次运行打印词库内容哈希（如 lexicon: 2cc05ba84457），确保评分标准在不同运行间不变。

使用方式

安装

• 通过 uvx 零安装运行（推荐）：uvx defluff 或 uvx defluff[mcp] 首次运行会拉取包和 mcp 附加组件。
• 在 macOS/Linux 上通过 Homebrew 安装。
• 直接安装并运行入口点。
• 作为 MCP 服务器发布在 MCP Registry，名称为 io.github.ahmedak/defluff。

基本使用

• 指向变更日志、文档或智能体输出，即可获得需要删除的填充短语列表，以及 CI 退出码和可固定的评分。
• 常用场景包括：智能体自我纠正（对草稿调用 slop_detect 并修订被标记短语）、CI 门禁（当 AI 草拟的变更日志或文档充满填充词时使构建失败）、写作助手反馈（高亮编辑会删除的精确短语）、微调奖励组件（实验性，单独使用易被博弈）。

词库覆盖与版本化

• 用户覆盖：~/.config/defluff/，机器范围，不提交。
• 项目覆盖：.defluff/ 于 git 根目录，每个仓库，可提交给团队。
• 写入是原子且跨进程锁定的；损坏的覆盖文件会警告并跳过，detect() 永不崩溃。
• 每个解析后的词库（内置 + 覆盖 + 包）都带有短内容哈希，可通过 SlopReport.lexicon_version 获取。

输出解读与阈值设置

• 片段：精确的填充短语，含类别，确定可靠，应据此行动。
• 评分：加权后的填充密度，0.20 约表示“五分之一文本是列表中的填充词”，通常 0.0–1.0，它是触发 CI 退出码的绊线，而非质量量化器。
• 默认阈值 0.08 是临时手选的，未在标注语料上校准。对于硬 CI 门禁，建议设置自己的阈值并先抑制领域词汇。

与 pre-commit 和奖励循环使用

• 可用于 pre-commit。
• 在奖励循环中（实验性）：可作为奖励混合的小组件，但单独使用易被博弈，需搭配真实质量信号（人类或 LLM 评判）。

适用场景

• 智能体自我纠正、CI 门禁、写作助手反馈、微调奖励组件。

限制

• 基于列表匹配：不理解文本，无法检测新颖的流行词（如“operationalize the ideation funnel”），这是确定性和可重现性的代价。如需语义检测，需搭配 LLM 评判。
• 领域术语是上下文的：如“leverage”在金融文档中可能是真实内容，需阅读被标记片段并通过 defluff lexicon rm 抑制误报。
• 片段偏移基于清理后的文本：由于会剥离代码块、行内代码、URL 和 Markdown 标记，偏移与原始文档不对齐，应基于 span.text 匹配。
• custom 类别只读：通过 --lexicon 文件添加的短语落入 custom，但 defluff lexicon add --category custom 会被拒绝。
• 仅支持英语（v0）。
• 短文本（< 20 词） 会得到 low_confidence: true，分母下限为 20，避免两句话输入因一个短语而显示 100% 废话。

评估与贡献

• 在 50 个手工标注示例上，默认阈值下精度表现可复现：python eval/score.py eval/validation.jsonl。遗漏主要是词库未见过的新颖流行词，召回率对列表中填充词为 1.00，但无法覆盖开放式新词。
• 贡献方式：将遗漏的填充短语添加到 src/defluff/data/lexicon-v1.json，运行 pytest，提交 PR 并附带一两个实际例子。详见 CONTRIBUTING.md。