半结构化文本字段提取器
把「人看得懂、程序读不了」的文本，用一条正则批量转成表格。
触发规则
| 用户意图 | 处理 |
|---|---|
| 从这批日志里把 IP/状态码/路径抽出来 | 用 --preset access-log 或自定义正则抽取 |
| 把这些 key=value 转成表格 | 用 --preset kv 抽取 |
| 系统日志想按字段拆开看 | 用 --preset syslog 抽取 |
| 我的文本格式特殊，想自定义 | 与用户确认命名组正则后抽取 |
| 帮我统计一下这些字段的分布 | 抽取时加 --stats，重点输出字段统计 |
| 只是问本技能能干嘛 | 仅介绍，不执行任何操作 |
依赖
| 依赖 | 用途 |
|---|---|
| Python 3.8+ | 运行 scripts/extract_fields.py（仅用标准库） |
无需联网、无需安装任何第三方包。
快速开始
# 内置预设：Nginx 日志
python3 scripts/extract_fields.py logs/ --preset access-log --stats --csv out/access.csv
# 自定义正则（注意必须含命名组）
python3 scripts/extract_fields.py report.txt \
--pattern '订单号=(?P<订单>[A-Z0-9]+)\s+金额=(?P<金额>[\d.]+)\s+状态=(?P<状态>\S+)' --stats
# 正则写太长，存成文件
python3 scripts/extract_fields.py logs/ --pattern-file my.pattern --json out/result.json
# 只要前 500 条验证规则是否正确
python3 scripts/extract_fields.py logs/ --preset syslog --limit 500 --show 5
参数
| 参数 | 说明 | 默认 |
|---|---|---|
--pattern RE |
含命名组的正则（逐行匹配） | — |
--pattern-file P |
从文件读取正则 | — |
--preset NAME |
access-log / kv / syslog |
— |
--csv PATH |
输出 CSV（UTF-8 with BOM） | — |
--json PATH |
输出 JSON（含统计与记录样本） | — |
--stats |
终端打印字段统计 | 关 |
--include GLOB |
目录扫描时纳入的文件（可多次） | 按扩展名 |
--limit N |
最多提取 N 条（0 = 不限） | 0 |
--show N |
终端预览前 N 条 | 10 |
--pattern / --pattern-file / --preset 三者必选其一，优先级：--pattern-file > --preset > --pattern。
命名组正则写法
必须含至少一个命名组，否则工具直接报错退出（避免产出无意义的空表）：
(?P<字段名>子表达式)
要点：
- 字段名用中文或英文均可，会原样成为 CSV 表头；
- 字段顺序 = 输出列顺序，按正则里命名组出现的先后排列；
- 值两端若被成对引号包裹，输出时自动去引号（
"abc"→abc）； - 匹配逐行进行，跨行结构（如异常堆栈）需先用其他方式整理成单行；
- 所有命名组都为空的行会被丢弃，不产生空记录。
字段统计口径
| 指标 | 含义 |
|---|---|
| 非空 | 该字段有值的记录数 |
| 缺失 | 该字段为空或未匹配到的记录数 |
| 唯一值 | 不同取值个数（用于判断是否适合做分组维度） |
| 数值 | 当字段中数值占比 ≥50% 且至少 2 个时给出 min / max / mean |
| 高频值 | 出现次数最多的前 3 个取值及其计数 |
统计只做客观汇总，不判断业务含义——例如 status=500 是否算故障，需结合业务上下文。
内置预设的字段
| 预设 | 适用文本 | 输出字段 |
|---|---|---|
access-log |
Nginx/Apache 组合日志（combined） | ip / time / method / path / status / size |
kv |
每行若干 key=value（支持引号包裹） |
key / value（逐对拆行） |
syslog |
传统 syslog 行 | month / day / time / host / process / pid / message |
预设只覆盖最通用的格式；实际日志常因自定义格式而字段偏移，此时改用 --pattern 更可靠。
Agent 执行要求
- 只读优先：本技能不修改、不删除任何被处理的源文件，只产出新的 CSV/JSON。
- 先定规则后跑全量：正则不确定时先
--limit小批量试跑并--show看结果，
确认无误再跑全量，避免产出错误的整表。 - 无匹配要说清：返回「未匹配到任何记录」时，不要自行放宽正则去"凑"数据，
应先向用户展示实际文本样例行，共同确认格式。 - 编码异常要说明：源文件若含非法字节会以替换字符解码，需提示用户文本列可能失真。
- 隐私提示：日志常含 IP、手机号、身份证号等个人信息；输出给用户前应提醒，
必要时先脱敏再对外提供。 - 不改口径：统计规则固定，不得为了让数字"好看"而调整。
输出模板
## 文本字段提取结果
- 提取规则：`(?P<订单号>[A-Z0-9]+)\s+金额=(?P<金额>[\d.]+)\s+状态=(?P<状态>\S+)`
- 扫描文件：3 个 命中记录：1240 条
| 文件 | 命中 |
|---|---|
| app-2026-09-18.log | 820 |
| app-2026-09-19.log | 420 |
### 字段统计
- 订单号：非空 1240 缺失 0 唯一值 1240
- 金额：非空 1240 缺失 0 唯一值 316 数值 min=0 max=98000 mean=312.4
- 状态：非空 1240 缺失 0 唯一值 3 高频值 已付×980、待付×200、已取消×60
（明细已写出至 out/result.csv 与 out/result.json）
注意事项
- 禁止修改、删除、重命名被处理的源文件；本技能只读输入、只写新文件。
- 不负责日志告警、时序聚合、图表可视化；不做日志轮转与压缩包解压（需先自行解压）。
- 不读取与目标无关的目录内容，不扫描用户主目录。
- 报告与输出文件中的路径仅用于本次会话展示，不写入任何远端服务。
