clean-log-toolkit v0.1.0
这是一个小型、诚实的本地工具包，用于工作代理经常执行的任务：读取某人发送给您的日志，找出格式，查找实际问题，并生成可以粘贴到票据中的摘要。仅使用Python 3标准库构建。不使用awk/sed/jq包装器，不使用pip安装，不使用远程调用。
此技能是“clean-”三件套的第三个部分：
clean-csv-toolkit — 结构化表格数据
clean-text-toolkit — 非结构化文本
clean-log-toolkit — 半结构化时间戳日志
此技能的功能
scripts/parse.py — 将日志文件解析为结构化行。通过嗅探前约50行自动检测apache-common、apache-combined、nginx-access、syslog和json-line格式。当没有匹配时，回退到通用时间戳+级别+消息提取器。传递--regex模式带有命名组来定义自定义格式。输出为.csv、.tsv或.jsonl。
scripts/errors.py — 聚合日志文件中的错误。按级别（默认为WARN / ERROR / FATAL）计数，按分钟/小时/天对时间线进行分组，规范化每条消息为“指纹”（用占位符替换数字、UUID、十六进制令牌、文件：行对和嵌入时间戳），并显示前N个最常见的错误组。写入JSON / Markdown / CSV报告或打印一屏摘要。
scripts/grep.py — grep，但日志感知。将--pattern正则表达式、--not-pattern正则表达式、--level LVL[,LVL2...]、--since时间戳、--until时间戳和-B / -A / -C上下文行合并为一个过滤器传递。输出到标准输出或文件。至少一个匹配返回退出0，零匹配返回1。
scripts/check_deps.sh — 验证python3是否可用。
此技能不执行的操作
它不跟踪/跟随实时日志文件（但可能在v0.2功能中实现，如果有需求）。
它不调用任何LLM、Web服务或远程API。
它不写入调用者提供的输入/输出路径之外的任何内容。
快速入门
# 自动检测格式
python3 scripts/parse.py app.log app.csv
# 或显式
python3 scripts/parse.py access.log out.jsonl --format apache-combined
python3 scripts/parse.py syslog.txt out.csv --format syslog
python3 scripts/parse.py events.log out.csv --format json-line --fields ts,level,msg
python3 scripts/parse.py app.log structured.csv \
--regex '^(?P\S+)\s+(?P\S+)\s+(?P.)$'
# 一屏幕摘要
python3 scripts/errors.py app.log
# 按分钟分组，前20条消息
python3 scripts/errors.py app.log --bucket minute --top 20
# 只计算特定级别
python3 scripts/errors.py app.log --level ERROR,FATAL
# 写入Markdown报告，准备粘贴到票据中
python3 scripts/errors.py app.log --output report.md
# 或JSON报告，用于下游工具
python3 scripts/errors.py app.log --output report.json --bucket hour
# 或时间线的CSV
python3 scripts/errors.py app.log --output timeline.csv --bucket minute
errors.py指纹消息，因此重复错误仅在数字/UUID/文件行引用方面有所不同，会折叠为一个带有计数的组。示例：50次连接超时到10.0.0.5后的1234ms和连接超时到10.0.0.7后的567ms折叠为一个组连接超时到...后的ms，计数为50。
# 模式+级别过滤
python3 scripts/grep.py app.log --pattern "Database" --level ERROR,FATAL
# 时间窗口
python3 scripts/grep.py app.log \
--since "2026-05-10T10:00:00Z" \
--until "2026-05-10T11:00:00Z"
# 上下文行（每个匹配项前后各一行）
python3 scripts/grep.py app.log --pattern "FATAL" -C 1 --with-line
# 排除噪音行，同时保留其余内容
python3 scripts/grep.py app.log --level ERROR --not-pattern "heartbeat"
# 反转：保留所有不匹配的内容
--since和--until接受parse.py理解的相同时间戳格式：ISO 8601（2026-05-10T10:00:00Z，2026-05-10 10:00:00，带或不带微秒/时区），apache风格（10/May/2026:10:00:00 +0000）和syslog（May 10 10:00:00 — 假设当前年份）。
退出代码
代码 含义
0 成功/一行或多行/一个或多个匹配
1 解析产生零行/ grep找不到匹配/ 错误找不到匹配日志条目
2 坏参数/不安全路径/缺少输入/坏正则表达式/未知格式/不支持输出扩展名
此0/1/2分裂在所有三个脚本中保持一致，因此它们可以轻松地插入shell管道：
# 解析为JSONL，然后总结错误，然后发布到票据
python3 scripts/parse.py raw.log structured.jsonl \
&& python3 scripts/errors.py raw.log --output ticket.md \
&& cat ticket.md
安全属性
纯Python 3标准库。没有第三方依赖。没有子进程调用。没有shell调用。所有文件路径都经过严格的允许列表正则表达式验证，拒绝shell元字符。相同
by