log-ai-compressor · 本机日志取证层

我们不把日志交给大模型。我们用确定性算法把日志变成可复核的证据，大模型只读证据。 拿不出因果链就说证据不足，并精确列出还缺什么才能定论 —— 而且会对这些缺口负责：补上了就把缺口划掉。 全部计算在本机完成，日志不出网。

🧾 立场：你不必相信这个工具

大多数日志工具要你相信它的结论。这个工具给的是你可以自己复核的东西 —— 每条结论都带原文的行号区间和那段原文的 sha256。

$ log-ai-compressor run app.log -f json -o report.json
$ log-ai-compressor verify --report report.json
证据：共 8 条引用，匹配 8 条，失配 0 条，源不可读 0 条

事故复盘时，有人把日志里的主机名改了：

$ log-ai-compressor verify --report report.json
证据：共 8 条引用，匹配 7 条，失配 1 条
  ✗ MISMATCH ca0e981df461 app.log 期望 c33aeb824ce67aaf 实际 4a1689f3780880ae
自校验结论：TAMPERED        # 退出码 1

判定只有三档，没有「大部分通过」 —— 一份掺了假证据的报告，不该因为大部分为真就放行。

同一套立场长成了四件具体的事：

第四行是我最想让你注意的一行：一个主动撤回自己招牌数字的项目， 它剩下的每个数字才有分量。见 docs/FAQ.md Q10。

📌 先读这一节：这些数字不能证明什么

一个只会报好数字的项目不值得信。下面是所有实测结论都覆盖不到的地方。

一个云平台说「我不知道」，在产品上读起来像故障。本工具说「我不知道」， 在方法论上读起来像专业。但如果你要的是全天候告警，本工具给不了，别选它。

📊 证据保留率 vs Drain3（Loghub 2.0，10 个数据集）

指标：保住多少种人工标注的事件类型。事件模板来自 Loghub-2.0 的人工标注。

我们报三个口径，因为它们回答三个不同的问题，混着说就是不诚实：

• 交付口径 = 产品默认 top_n=20，用户开箱即用真拿到手的那 20 个簇
• 同预算 32k = 和 Drain3 花同样的 token 能保住多少（主指标）
• 全量口径 = 聚类本身的质量上界，不是用户能收到的，别拿它当成绩

对 Drain3 的战绩：交付口径 1 胜 9 负 / 同预算 8 胜 1 平 1 负 / 全量 8 胜 1 平 1 负。

交付口径那一列低得难看，是因为 Mac 有 626 种事件、Linux 有 338 种， 20 个簇物理上装不下 —— 不是工具差，是产品只给 20 个簇。 把上限算出来看：Zookeeper / Hadoop / Mac 顶格 100%，全部 10 个数据集合计 达成度 82%（实测覆盖率 ÷ min(20,事件数)/事件数）。 这一栏量的是「产品给多少簇」，Drain3 没有这个旋钮，两栏不是同一条起跑线。 OpenSSH 两边都是 35/38，是平手不是赢。

剩下的一个负例不藏，病因查清了：

• HPC 85.1% vs Drain3 87.8% —— 不是簇数不够，是簇粒度比标注粗： action start ... boot 与 action start ... risBoot 在 41/44 字符的模板上 编辑距离相似度高达 0.965，于是在 0.85 阈值下被并成一簇，而 Loghub 把它们 算两类事件。

  试过加「字面词元守卫」把它拆开：覆盖率确实从 85.1% 涨到 93.2%， 但报告从 76 个簇炸成 2,690 个、交付口径从 23.0% 崩到 8.1% —— 那是坏掉的工具。已撤回，根因（mask_text 没归一化主机名）与完整数据 写在 CHANGELOG 与 tests/test_cluster_token_guard.py 里。

Mac 在 v2.9.8 之前也是负例（58.5% vs 72.2%）。病因不是聚类丢事件，而是报告 把 406 条错误消息当成「变更事件」，逐条写了出来 —— 全篇 33% 的 token 花在 这个假线索上。收敛后同预算从 58.5% 涨到 82.9%。

胜负怎么判的：一律按事件种数比，不用四舍五入后的百分数。 报告只有 1 位小数，0.05pp 以内的差与舍入误差分不开，落在容差里一律记平 （v2.9.6 之前直接比百分数，把一个 0.005pp 的舍入差判成了胜）。

对照的三个都是真工具：Drain3（ICWS'17 学术标准）、 LogsLop（AMD 2026-07，去重工具，与证据保留目标相反）、tail/grep 两条朴素基线。

完整方法学、为什么会在两个数据集上输、以及 v2.9.3「已发布数字系统性偏低」 与 v2.9.5「指标在数用户没收到的东西」两次撤回的经过，全在 docs/BENCHMARK.md。被质疑时先看那里。

🚦 工程指标

🚀 90 秒上手

# 本地 Web 界面（自动开浏览器，端口 8765 起，被占用自动顺延）
pip install "log-ai-compressor[web]"
log-ai-compressor web

# 只在命令行里压缩日志：硬依赖只有 PyYAML
pip install log-ai-compressor
log-ai-compressor run app.log --top 20 -o report.md

# 复核一份报告的结论出处（报告发出去后日志可能已被改动或轮转清理）
log-ai-compressor verify --report report.json

# 让 AI Agent 直接调用本机日志（MCP Server，已收录官方 Registry）
pip install "log-ai-compressor[mcp]"
log-ai-compressor mcp --install claude-code

Agent 客户端可直接按官方 Registry 名发现安装：

mcp-name: io.github.hu-chenyu/log-ai-compressor

Windows 可双击 start.bat 自动定位 Python、装依赖、启动并打开浏览器。

🧰 能力

完整清单与边界见 docs/FEATURES.md。

🚫 它做不到什么

还有一条是写在代码里而不只是文档里的硬约束：

调用链只证明顺序，不证明因果。 有完整 trace 但没有 Caused by: 时， 工具仍然只给 LIKELY、can_conclude=false。CONFIRMED 的唯一来源 始终是条目内 Caused-by 链。对抗评测里有一个场景专门盯它。

🗂 深入

复现本文所有数字：

python scripts/fetch_datasets.py --all   # 下公开数据集
python scripts/benchmark_loghub.py       # 证据保留率对照
python scripts/prove.py                  # 自证：不必相信作者，自己跑

License

MIT