测试集 Query 清洗工具

两层架构：结构层处理格式/语法问题，语义层处理含义层面的无效数据。

快速上手

用户说"帮我把这个 query 数据洗一下"时：

确认输入文件 — 路径、格式（xlsx/csv）、要清洗的列名
确认清洗需求 — 特别问一下：需不需要做语义清洗？（语气词/上下文片段/语义不明）
调脚本清洗 — 用 scripts/clean_query.py
输出结果 — 清洗后文件 + 报告

核心用法

# ========== 语义层清洗（核心能力） ==========

# 语义层全清：语气词 + 上下文片段 + 语义不明
python clean_query.py 数据.xlsx --semantic --report

# 单独过滤语气词（嗯/好的/知道了/哈哈哈）
python clean_query.py 数据.xlsx --filler --report

# 单独过滤上下文片段（但是/所以/你刚才说的）
python clean_query.py 数据.xlsx --fragment --report

# 单独过滤语义不明（测试/随便/你好/在吗/这个）
python clean_query.py 数据.xlsx --vague --report

# ========== 结构层清洗 ==========

# 推荐组合：基础清洗 + 语义清洗
python clean_query.py 数据.xlsx --empty --dedup --trim --semantic --report

# 全量清洗（结构层 + 语义层全部）
python clean_query.py 数据.xlsx --all

# 敏感信息脱敏
python clean_query.py 数据.xlsx --mask --dedup --trim --report

工作流程

Step 1: 问清楚用户需求

不要直接全量跑，先确认：

文件在哪？ 格式是 xlsx 还是 csv？
列名叫什么？ 默认 query，但可能是"问题"、"用户输入"等
要洗到什么程度？
- 只要去空值去重？（结构层）
- 还是要筛掉语义无效的 query？（语义层 — 推荐）

Step 2: 快速预览

语义清洗的效果最直观，先让用户看看哪些会被筛掉：

python clean_query.py 文件.xlsx --semantic --report

Step 3: 按需执行

根据 Step 1 和 Step 2 的反馈，选择合适的清洗组合。常见组合见 references/cleaning-rules.md。

Step 4: 呈现结果

返回给用户时，报告三个关键信息：

输入 → 输出 行数变化（X 条 → Y 条）
移除了什么 — 特别要用语义层的分类告诉用户：语气词 N 条、上下文片段 M 条、语义不明 K 条
文件在哪（路径）

脚本参数速查

必选: input                       输入文件路径
--column   TEXT   默认 "query"    指定清洗列
--sheet    TEXT                   指定 Excel sheet（默认第一个）
--output   PATH                   输出文件路径
--report                          生成清洗报告 .txt

结构层清洗：
--empty              移除空值
--dedup              精确去重
--fuzzy-dedup        模糊去重（字符集相似度 ≥85%）
--short      [N=2]   过滤少于 N 字
--long       [N=500] 过滤超过 N 字
--gibberish          过滤纯数字/纯标点/重复单字符
--normalize          全角→半角 + 合并空格
--punctuation        中文标点→英文标点
--html               去 HTML 标签
--emoji              去 Emoji
--mask               敏感信息脱敏
--trim               去首尾空白

语义层清洗 ⭐：
--filler             过滤语气词/无效应答（嗯/好的/知道了/然后呢/哈哈哈）
--fragment           过滤上下文片段（但是/然而/你刚才说的/所以这个）
--vague              过滤语义不明（测试/随便/你好/在吗/这个/666）
--semantic           语义层全清（= filler + fragment + vague）

--all                执行全部（结构层 + 语义层）

注意事项

语义层重点

语义清洗是启发式规则，不是 AI 判断，可能会有误杀/漏网：

--filler 最安全，几乎不会误杀正常 query
--fragment 对 ≤15 字且以连词开头的 query 特别敏感，长 query 不受影响
--vague 过滤"测试"、"你好"、"随便"等常见无意义 query，注意这些也可能是某种场景下的合法 query
建议先看报告再决定：--semantic --report 输出清洗报告，确认无误后再全量清洗

通用

先预览再全量 — 默认清洗步骤可能过于激进，先让用户看效果
敏感信息 — --mask 脱敏不可逆，确认用户需要再执行
备份建议 — 全量清洗前建议备份原文件
依赖 — 依赖 openpyxl（已安装），无其他外部依赖

参考文档

详细清洗规则说明和常见组合：见 references/cleaning-rules.md