# log-ai-compressor **Repository Path**: hu-chenyu-dev/log-ai-compressor ## Basic Information - **Project Name**: log-ai-compressor - **Description**: 本机日志取证层:每条结论带行号出处与原文 sha256,可脱离本工具自校验;零出网。附 Loghub 2.0 可复现基准(对照 Drain3 / tail / grep)。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-15 - **Last Updated**: 2026-11-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: llm, root-cause, forensics, MCP, log ## README # log-ai-compressor ### 日志不用喂给大模型,也能给出「你能自己核对」的根因 > 每条结论带原文的**行号区间**和那段原文的 **sha256**;拿不出因果链就说 > **证据不足**,并精确列出还缺什么才能定论。**全部计算在本机完成,日志不出网。** [![Release](https://img.shields.io/badge/release-v2.16.1-c71d23)](https://gitee.com/hu-chenyu-dev/log-ai-compressor/releases/tag/v2.16.1) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://gitee.com/hu-chenyu-dev/log-ai-compressor) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://gitee.com/hu-chenyu-dev/log-ai-compressor/blob/main/LICENSE) [![Tests](https://img.shields.io/badge/tests-2%2C319%20%C2%B7%20green-brightgreen)](https://gitee.com/hu-chenyu-dev/log-ai-compressor/blob/main/docs/REPRODUCIBILITY.md) **English**:[README.en.md](README.en.md)(给国外读者的一版,数字与口径相同) ## 2 分钟试跑 ```bash # 版本必须钉住:国内镜像常落后几天,装到 2.13.1 会没有 -f summary pip install -U --index-url https://pypi.org/simple "log-ai-compressor==2.16.1" log-ai-compressor run examples/app.log -f summary ``` 第二条会直接打印摘要:确定性指纹、每条结论的行号区间、已定位的根因。 下一节整段贴的是默认 `run` 的输出 —— 比它多首行与末行各一句,**摘要主体逐行相同**。 **30 秒看懂它和其他工具差在哪:** | | `grep` / `tail` | Drain3 | 3-shot LLM | **本工具** | |---|---|---|---|---| | 给你什么 | 匹配到的行 | 模板簇 | 模板簇 | **结论 + 行号区间 + sha256** | | 要不要模型 | 不要 | 不要 | 要 | **不要(0 次 API 调用)** | | 十集全量 GA | — | 71.58% | 未跑全量 | **88.68%** | | 同抽样(每集 2,000 行)GA | — | — | 56.37% | **86.86%** | | 同抽样墙钟 | 毫秒级 | 秒级 | 1,471.9 s | **2.57 s** | | 结论能不能被第三方复核 | 不能 | 不能 | 不能 | **能:`verify` 判 VERIFIED / TAMPERED** | > 两行 GA 不是同一把尺子:**88.68%** 是十集 1,940,760 行全量 vs 本机 Drain3; > **86.86%** 是每集 2,000 行抽样 vs 3-shot LLM(我方同一批行)。混着引用就是耍流氓。 > 原始 CSV 与复现命令见 [`docs/REPRODUCIBILITY.md`](docs/REPRODUCIBILITY.md)。 > > 「tests 2,319 · green」是**静态徽章**(数字来自 `pytest --collect-only` 实测), > 不是流水线绿灯 —— CI 目前跑在本地,没有公网可点的流水线。 **目录** - [它长什么样](#它长什么样一份-24-行日志的真实输出) - [装上就用](#装上就用) - [立场:你不必相信这个工具](#-立场你不必相信这个工具) - [它会漏什么](#-它会漏什么先看这个再决定要不要用) / [不能证明什么](#-这些数字不能证明什么) - [基准](#-证据保留率-vs-drain3loghub-20-10-个数据集) / [PA·GA](#-换一把不是自己设计的尺子loghub-标准解析协议-pa--ga) - [工程指标](#-工程指标) / [MCP](#-mcp-registry给-ai-agent-用的入口) / [能力边界](#-能力边界做不了的事与谁行) --- ## 它长什么样:一份 24 行日志的真实输出 `examples/app.log`(24 行、8 条错误、4 种类型)跑出来是这样 —— **下面这段就是它的真实输出**, 你可以自己跑一遍对上: ```console $ log-ai-compressor run examples/app.log ⚠ 报告全文 ≈2.4k tokens,比原始日志(≈379 tokens)还大 —— 建议只用摘要:log-ai-compressor run examples/app.log -f summary 【日志分析摘要】examples/app.log 原始日志 ≈379 tokens → 摘要 ≈234 tokens(压缩 38%) 确定性指纹 `48e5781aafc4b27fe0f68c5847afe6d891936ac9f2e0af59aefaa9860f9c2886`(同一份日志跑两遍必须完全一致) 总行数 24,错误 8 行,去重后 4 种,时间范围 2024-03-15 08:00:00 ~ 2024-03-15 08:00:25。 已定位根因:java.net.ConnectException: Connection refused(另有 1 个根因候选) (证据出处末尾 16 位十六进制 = 该段原文 sha256 前 16 位,可自行复核) 1. [P0 | ERROR | ×3 | 根因 | 行 4~13] authorization failed: connection refused to db-primary:5432 证据出处:L4 bc5b93cec7cde01c -> 因果链源头(1 个错误由其衍生) 2. [P0 | ERROR | ×3 | 行 6~11] request 8812 failed: upstream unavailable 证据出处:L6 21d12907c3115d34 3. [P0 | ERROR | ×1 | 根因 | 行 18~22] java.net.ConnectException: Connection refused 证据出处:L18-L22 68af24f230baff5c -> Caused-by 因果链直连,根因:java.net.ConnectException: Connection refused 4. [P0 | ERROR | ×1 | 行 23~23] stock check timeout after 3000ms item=SKU-7781 证据出处:L23 a72b9f38845a14ed 报告已导出: examples/app_report.md(MD,9.4 KB) ``` > **有四处随环境变**,别拿它们对不上就以为装错了: > > * 路径**回显你给的写法** —— Windows 上是 `examples\app.log`, > Linux 上是 `examples/app.log`; > * 「摘要 ≈234 tokens」**随路径长度变**(摘要里有那一行路径)—— > 同一份日志,给绝对路径会多几个 token。实测(本仓库这个路径): > 相对路径 234、绝对路径 246 —— **绝对路径那个数随路径有多长变**, > 换台机器(用户名 / 目录深度不同)会不一样; > * 「时间范围」两端都带完整日期 —— 这是 2026-10-23 起统一按 UTC 展示的结果 > (此前第二端只显示钟点)。 > * 「报告已导出: …(MD,9.4 KB)」那个大小**随路径长度变**(报告里带着那一行路径) > —— 实测:相对路径 9,604 字节、绝对路径 9,919 字节。 > **但它不随操作系统变**:导出行尾统一钉成 LF,两个平台逐字节相同 > (2026-10-28 第十五轮修的,此前 Windows 写 CRLF、Linux 写 LF)。 > > **指纹与行号区间不随这些变** —— 那两个才是结论本身,也是本工具的承诺。 > 上面那个 234 是**照上面那条命令**(仓库根目录 + 相对路径)跑出来的数; > 这条由 `tests/test_readme_sample_is_reproducible.py` 逐行盯着。 > **两个 token 数不是同一个东西,别混着比。** > > | 出现在哪 | 名词 | 量的是什么 | > | --- | --- | --- | > | 控制台第 2 行 | **摘要 tokens**(本例 ≈234) | `-f summary` 那份投喂摘要的正文 | > | 报告头部 | **报告全文 tokens**(本例 ≈2.4k) | 整份 MD 报告(含样例原文、上下文、降噪堆栈) | > > 同一份 24 行日志,两个数差十倍是**正常的**:摘要只留结论与出处, > 全文还要带原文。2026-11-15 之前两处都写「压缩后」,读者没有任何办法 > 从这两个数里看出「我到底省了多少」—— 术语拆开就是为了这件事。 > 顺带一条:**报告比原文还大时,首行会直接建议改用摘要**(上面第 1 行就是)。 ### 拿到结论之后,三个动作 ```console $ log-ai-compressor run examples/app.log -f json -o examples/app_report.json # 导出 JSON 报告 $ log-ai-compressor verify --report examples/app_report.json # ① 这份结论现在还成立吗 $ log-ai-compressor evidence examples/app_report.json # ② 这条结论说的就是那几行 $ log-ai-compressor run examples/app.log -f summary # ③ 投喂给模型的那份摘要 ``` * **① 自校验**给的是**判定**(`VERIFIED` / `TAMPERED`):重读原始日志, 逐条核对每条结论引用的那段原文的 sha256 —— 对不上就报「报告与日志对不上」 (分不出是哪一方变了),源文件被轮转走了则报「验不了」,**不**指控你。 * **② 看原文**给的是**原文**:每条结论引用的那几行,连同它们的摘要核对结果。 它与 ① 共用同一套回读 —— 不会出现「复核说一致、原文却不是那一段」。 * **③ 投喂**是那份精简摘要(也就是上面首屏那一段),`-f summary` 直接打到 stdout,复制走就是能喂给模型的内容。 > 首屏这几条命令由 `tests/test_readme_sample_is_reproducible.py` **真跑一遍**盯着 —— > 首屏写着的命令跑不起来,就是首屏在骗人。 注意第 3 行:标题点名的**不是**「外层症状」而是**链尾真因**。 这条结论指向日志的**第 18~22 行**,那段原文的 sha256 就印在它下面那一行 (报告里也带同一份摘要)—— ```console $ log-ai-compressor verify --report report.json 模式:复核已导出报告 对象:报告 report.json 证据:共 4 条引用,匹配 4 条,失配 0 条,源不可读 0 条 自校验结论:VERIFIED 每条结论都能在原始日志里逐行复核。 ``` **有人事后改了日志主机名?** 立刻报出来,退出码 1 (下面这段是**真的跑出来的**:把 `examples/app.log` 里的 `db-primary` 改成 `db-primarY` 之后重跑 `verify`): ```console $ log-ai-compressor verify --report report.json 证据:共 4 条引用,匹配 3 条,失配 1 条,源不可读 0 条 ✗ MISMATCH c3801f905159 examples/app.log 期望 bc5b93cec7cde01c 实际 1b8242c1671f1e29 自校验结论:TAMPERED # 退出码 1 ``` 判定**没有「大部分通过」这一档** —— 一份掺了假证据的报告, 不该因为大部分为真就放行。四档是 `VERIFIED` / `TAMPERED` / `UNVERIFIABLE`(**验不了**,不是「查出问题」)/ `NO_EVIDENCE` (本来就没证据),详见 [`docs/CLI.md`](docs/CLI.md)。 --- ## 装上就用 ```bash pip install log-ai-compressor # PyPI 上就是 2.16.1(2026-11-17 发布),硬依赖只有 PyYAML 一个 pip install "log-ai-compressor[web]" # 想要图形界面再装这个 ``` | 你要做的事 | 命令 | | --- | --- | | 分析一份日志 | `log-ai-compressor run app.log -o report.md` | | **接管道**(不用先落盘) | `kubectl logs -f deploy/api \| log-ai-compressor run - -f json` | | **只看最近几千行**(行号仍指回原文件) | `log-ai-compressor run app.log --tail 5000` | | **拿机器可读的 JSON**(stdout 就是 JSON) | `log-ai-compressor run app.log -f json` | | 比对发版前后 | `log-ai-compressor compare v1.log v2.log -f json` | | 复核一份报告的出处 | `log-ai-compressor verify --report report.json` | | 要图形界面 | `pip install "log-ai-compressor[web]" && log-ai-compressor web` | | 让 AI Agent 调本机日志 | `pip install "log-ai-compressor[mcp]" && log-ai-compressor mcp --install claude-code` | **首次运行要多久**(2026-10-22 本机实测,Windows / Python 3.11): 装依赖 **2.3 秒**(`pip install log-ai-compressor`,pip 有缓存;首次拉包会更久), 之后**每份小日志 0.19~0.25 秒**。 大文件同样实测过(**149.0 MB / 1,456,935 行**):**58.9 秒**, 峰值内存 **24.4 MB** —— 内存与文件大小无关,因为是**流式**处理。 报告 457 KB。 Windows 可双击 `start.bat` 自动定位 Python、装依赖、启动并打开浏览器。 ### 常见报错(都是实测出来的真实输出) | 你会看到 | 什么意思 | 怎么办 | | --- | --- | --- | | `错误:xxx 不是文本日志(10 行含 NUL 字节…)—— 已中止分析` | 喂进去的不是文本日志 | 检查路径。**退出码 2**(不是 1)—— 「文件选错了」与「分析失败」是两回事 | | `错误:报告写不出去 —— 目录不存在(报告路径里的父目录还没建)` | `-o` 的父目录不存在 | 先建目录。工具**故意不替你建** —— 那个目录名多半是你打错的 | | `错误:解析规则有问题 —— YAML 解析失败: …` | `--rule` 指向的 YAML 写错了 | 改 YAML | | `错误:日志文件不存在 xxx` | 路径错了 | 用绝对路径试试 | | `⚠ 有 N 行不是主编码 utf-8,已逐行按实际编码解码` | 这份日志**混着两种编码** | 已自动解好;这条提示只是告诉你「有 N 行不是主编码」 | | `⚠ 只看最后 N 行(文件共 M 行,起始行 K)` | 用了 `--tail` | 报告**只覆盖尾部**,不是全量。行号仍指向原文件 | | `⚠ 这份文件是空的(0 行)` | 文件是空的 | — | ### 升级 / 卸载 ```bash pip install -U log-ai-compressor # 升级 pip uninstall log-ai-compressor # 卸载(不删你的日志与报告) ``` ### 拿一份示例日志试试 仓库的 [`examples/`](examples/) 目录里直接可跑: ```bash log-ai-compressor run examples/sample_system.log -f json | head -20 log-ai-compressor compare examples/app_v1.log examples/app_v2.log -f json ``` `sample_system.log` 是带完整 `Caused by:` 链的服务端日志(能走到 `CONFIRMED`),`sample_gbk.log` 是 GBK 编码的(用来试编码适配)。 ### 谁在用 **目前没有外部用户。** gitee 仓库 2026-11-17 实测:**0 star / 0 fork / 1 issue**(就是置顶那条复现邀请), 全部数字都是作者自测的。这一栏会随实际情况更新; **没有就是没有,不拿「有人在用」这种话占位。** > 仓库此前在另一个平台托管,2026-10-29 起该账号被 suspend,仓库整体下架。 > 现在**唯一维护中的地址**是 gitee: > 。 > 本 README 的所有链接都指向这里;别处看到的旧地址不再更新。 --- ## 🧾 立场:你不必相信这个工具 大多数日志工具要你**相信**它的结论。这个工具给的是你可以**自己复核**的东西 —— 每条结论都带原文的**行号区间**和那段原文的 **sha256**。 **同一套立场长成了四件具体的事:** | 我们怎么做 | 通常的反面 | | --- | --- | | 拿不出可落到原文的因果证据(Caused-by / 块链 / 应用链)就只给 `LIKELY`,并**列出还缺什么才能定论**,补上了就划掉 | 给一个听起来很像回事的根因 | | 同一份日志跑两遍,**结论指纹逐字节相同** | 每次结论都不一样,没法归档、没法追责 | | 证据摘要只认**文件原始字节**,剥过 ANSI 的文本不算 | 同一行原文,两条出口给两个摘要 | | **撤回过一个跑不出来的召回率数字(91.4%)**,并公开查了哪六条路径 | 挂着一个复现不了的漂亮数字 | > 第四行是我最想让你注意的一行:一个**主动撤回自己招牌数字**的项目, > 它剩下的每个数字才有分量。见 [`docs/FAQ.md` Q10](docs/FAQ.md)。 --- ## 🚫 它会漏什么(先看这个,再决定要不要用) 一个只会报好数字的项目不值得信。下面是**实测确认的失效场景** —— 不是「理论上可能」,是拿它跑一遍就能复现的。 | 它会漏 / 会错 | 什么时候 | 怎么办 | | --- | --- | --- | | **二进制文件** | 拿 `.bin` / 图片当日志喂进来 | 修复前它会当文本「成功分析」并写下「压缩 95%」;现在直接拒绝并退出码 2 | | **混合编码的日志** | 同一文件里 UTF-8 行与 GBK 行混着 | 修复前 GBK 行静默变成一串替换符(实测 8 个 U+FFFD,数据被改了而报告里看不出异常);现在逐行兜底解码,并在报告里写明「有 N 行不是主编码」 | | **超长单行** | 一行日志 5 MB(实测) | 报告里的样例会截断到 2000 字符;**证据的行号与 sha256 仍按原文算**,可核对性不受影响 | | **UTF-16 无 BOM** | 编码探测走 NUL 密度启发式 | 已支持;但 utf-16 与 utf-8 混排的**那一行解不出来**(实测:标为「按任何候选编码都解不出来」,并按替换符保留、不丢行)。原因:宽编码的换行符是多字节的,必须整块解码,没有「逐行换编码」的余地 | | **跨文件的同一个 trace** | 两个文件各有同一次请求 | `compare` 现在按 `trace_id` 兜底对齐,不再算成「新增 + 消失」两份 —— **但只对结构化日志(JSON Lines / logfmt)成立**:`trace_id` 是从结构化字段里认领的,纯文本里写着的 `trace_id=t1` **认不出来**(不猜),那种情况仍会算成「新增 + 消失」 | | **没有 trace_id 的多服务日志** | 日志不带关联键 | 跨服务链路重建不出来 —— 工具会**明说**「缺调用链关联」,不假装能重建 | | **`--tail` 配管道** | `log-ai-compressor run - --tail 500` | 管道没有「原文件」,行号无处可指 ⇒ **直接报错**。此前它**静默忽略** `--tail`(以为在看最后 500 行、其实看了全部),值班时会误判「最近没有新错误」 | | **打乱行序的日志** | 行序被打乱过 | 折行/堆栈的邻接聚合会被破坏,结论与原文件不同。**这是设计如此**,不是缺陷 | > 顺带一句**已经修好**的:脚本只读 JSON 时(`-f json` 接进 CI), > JSON 里现在**也带**证据缺口(`evidence.gaps`)与提示(`notice`)—— > 此前它们只写给人看的格式,机器侧会把一个 `INSUFFICIENT` 的结论 > 当成定论用。 > 这一节是**输入形态的坑**,与下面那节「不能证明什么」是两回事: > 前者告诉你**什么时候会失灵**,后者告诉你**能力边界在哪**。 --- ## 📌 这些数字不能证明什么 一个只会报好数字的项目不值得信。下面是**所有实测结论都覆盖不到**的地方。 | 我们**不能**证明 | 原因 | | --- | --- | | 根因准确率高于云平台 | RCA100 的结论是 62.5% 的根因案例至少需要两种模态、31% 需要三种。本工具只有日志一种,跟它们不是同一场比赛 | | 在所有日志形态上都优于 Drain3 | 实测 Loghub **10 个**数据集,**没全赢**。同预算档 **7 胜 3 负**(HPC / HealthApp / Zookeeper 输),交付口径(产品默认只给 20 个簇)**1 胜 9 负**。但换一把外部定义的尺子(Loghub 标准解析协议的 GA),本项目 **88.68% vs Drain3 71.58%,反超 17.10pp** | | 压缩比能外推到你的日志 | 20,509 倍是 OpenStack 全级别摘要口径下的数字。换个数据集、换个 `--context`,数量级就变 | | 「召回率 100%」代表真实生产事故 | 只在 **1 个**含链真实数据集上测过(Android_v1 全量,131 条链)。**样本小,结论未必能外推**。原先并列的 Hadoop 91.4% 已于 v2.7.0 撤回 | | 持续监控与告警 | 没有 agent 埋点、没有时序库、没有告警队列 —— 这是有意的取舍,不是没做完 | > 一个云平台说「我不知道」,在产品上读起来像故障。本工具说「我不知道」, > 在方法论上读起来像专业。**但如果你要的是全天候告警,本工具给不了,别选它。** > 想知道「谁能让这个工具说错话、我们明确**不防**什么」, > 见 [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md)。 --- ## 📊 证据保留率 vs Drain3(Loghub 2.0,10 个数据集) 指标:**保住多少种人工标注的事件类型**。事件模板来自 [Loghub-2.0](https://zenodo.org/record/8275861) 的**人工标注**。 我们报**三个口径**,因为它们回答三个不同的问题,混着说就是不诚实: - **交付口径** = 产品默认 `top_n=20`,用户开箱即用**真拿到手**的那 20 个簇 - **同预算 32k** = 和 Drain3 花同样的 token 能保住多少(**主指标**) - **全量口径** = 聚类本身的质量上界,**不是用户能收到的**,别拿它当成绩 | 数据集 | 标注事件 | 交付 top20 | **同预算 32k** | 全量 | Drain3 | LogsLop (AMD) | |---|---:|---:|---:|---:|---:|---:| | Proxifier | 11 | 90.9% | **90.9%** | 90.9% | 72.7% | 27.3% | | Apache | 29 | 65.5% | **100.0%** | 100.0% | 93.1% | 44.8% | | OpenSSH | 38 | 52.6% | **100.0%** | 100.0% | 92.1% | 34.2% | | Zookeeper | 89 | 22.5% | **75.3%** | 75.3% | 76.4% | 23.6% | | Linux | 338 | 4.7% | **77.2%** | 77.2% | 66.6% | 55.6% | | Hadoop | 236 | 8.5% | **98.3%** | 98.3% | 80.5% | 13.1% | | HealthApp | 156 | 12.8% | **82.1%** | 82.1% | 83.3% | 7.1% | | OpenStack | 48 | 39.6% | **75.0%** | 75.0% | 41.7% | 18.8% | | HPC | 74 | 20.3% | **73.0%** | 73.0% | 87.8% | 4.1% | | Mac | 626 | 3.2% | **77.2%** | 92.0% | 72.2% | 16.1% | **对 Drain3 的战绩:交付口径 1 胜 9 负 / 同预算 7 胜 3 负 / 全量 7 胜 3 负。** 交付口径那一列低得难看,是因为 Mac 有 626 种事件、Linux 有 338 种, **20 个簇物理上装不下** —— 不是工具差,是产品只给 20 个簇。 把上限算出来看:Zookeeper / Hadoop / Mac **顶格 100%**,全部 10 个数据集合计 **达成度 91%**(实测覆盖率 ÷ `min(20,事件数)/事件数`,加权)。 这一栏量的是「产品给多少簇」,Drain3 没有这个旋钮,**两栏不是同一条起跑线**。 Proxifier 这一轮**由平手转成赢**(9/11 vs 8/11)。 > **同预算那一格的退步,这一版只追回了一点点,如实记着。** > 2026-11-09 上一轮把聚类换成**词元级模板 + 模板推断**之后(GA 58.19% → > 81.64%,反超 Drain3 约 10pp),本项目的这一格**退了 3.30pp** > (86.04% → 82.74%):HPC / HealthApp / Zookeeper 三个由胜转负。 > **本轮(第二十五轮)把它从 82.74% 抬到 82.82%(+0.08pp)** —— > 退步**基本没被追回**,HPC / HealthApp / Zookeeper 仍然是负例。 > 交付口径从 29.15% 抬到 **30.25%(+1.10pp)**,Proxifier 由平转胜; > 全量口径 84.19% → 84.13%(-0.06pp,Mac 92.65% → 92.01%)。 > 病因已量到,不是「算法变弱」而是**两个口径在这次变化里指向了不同方向**: > 分组更准 ⇒ 簇更少 ⇒ 报告能枚举的**不同问题数**变少 > (Linux 290 簇覆盖 261 种事件,旧版 302 簇覆盖 302 种); > 另有约 10 个事件被拆开(字母变量的第一个变体没被合并), > 以及 Zookeeper 那种「配置键」被吞(模板退化成 `<*> set to <*>`)。 > **诊断脚本可复算**:`python scripts/diagnose_delivery_regression.py`; > **下一步(已定位、未实现)**见 > [`docs/BENCHMARK.md`「结果四·五」](docs/BENCHMARK.md#五能不能全胜--把-ga-的失分逐行拆开量)。 **剩下的负例不藏,病因查到了「修法不存在」这一步(HPC):** - **HPC 73.0% vs Drain3 87.8%** —— 不是簇数不够,是**簇粒度比标注粗**。 116 个簇只装下 54 种事件身份,**20 个未覆盖事件全部落在过度合并的簇上**, 而它们无一例外只差**一两个字面词元**:`Link error`/`Link ok`、 `critical`/`normal`、`power/control ok`/`problem`、`boot`/`wait`/`risBoot`。 试过加「字面词元守卫」拆开:覆盖率从 85.1% 涨到 93.2%, **但报告从 76 个簇炸成 2,690 个、交付口径从 23.0% 崩到 8.1%** —— **已撤回**。 v2.10.0 又走了更远一步:把每一次合并决定都记下来(4,142 次),用 Loghub 标注判定对错,去找能分开两类的特征。**结论是没有这样的特征** —— 字符相似度与词元 Jaccard 的两类分布**完全重叠**,Proxifier 甚至有 Jaccard = 1.000(字面词元集合完全一致)却被 Loghub 判为不同事件的合并。 **Loghub 的事件定义不是模板相似度的函数**,所以这不是调参问题。 诊断脚本可复算:`python scripts/diagnose_merge_decisions.py`。 > 2026-11-09 那一轮把这条结论**收窄**了:它成立的前提是 > **「相似度在整条消息的字符层上算」**。换成**逐词元**之后, > 「同类内变化」与「异类差异」第一次被分开(Linux 23.25% → 88.80%)。 > 剩下切不开的那一类(Zookeeper 的配置键、OpenStack 的方法词), > 判据是**该位置的取值基数**,机制上需要延迟判定 + 归并回填。 > Mac 在 v2.9.8 之前也是负例(58.5% vs 72.2%)。病因不是聚类丢事件,而是报告 > 把 406 条错误消息当成「变更事件」,逐条写了出来 —— 全篇 33% 的 token 花在 > 这个假线索上。收敛后同预算从 58.5% 涨到 82.9%。 > > v2.10.0 又从 82.9% 涨到 **90.4%**,与本版修掉的另一件事直接相关:相似度回退 > 曾经只比级别桶里「最近 256 个簇」,这让聚类结果依赖日志行序,且**让长期只出现 > 在桶尾之后的模板永远找不到同类**(Mac 的 INFO 桶因此多出 1,000 个碎片簇)。 > 改成整桶比较 + 精确长度上界剪枝之后,Mac 的 INFO 桶从 1,604 个簇回到 547 个, > **分析还更快了(25.3s → 14.0s)**。 > > **而 2.13.0 之后,Mac 的同预算档又从 90.4% 掉到 69.8%** —— 这是本项目 > **自己的一次取舍**,不是算法退化:**第十四轮给「投喂口径」的摘要也加上了 > 每条结论的原文 sha256**(头号承诺:可脱离本工具自校验)。Mac 的 INFO 桶有 > 709 个簇,每簇多背二十几个 token,32k 预算里就从 **698 个簇降到 506 个** —— > 少覆盖 20.6% 的事件类型,同预算档由胜转负(69.8% vs Drain3 72.2%)。 > **全量口径(709 个簇全放)仍是 90.7%** —— 聚类本身没变差,变的是 > 「同样的钱能塞下多少条结论」。 > > **本轮把投喂口径的出处行压到最省:去掉 12 位 `evidence_id` 与 `sha256:` 前缀, > 只留「行区间 + 16 位摘要」**(16 位仍是用户自己算得出的 sha256 前 16 位, > 可复核性不变)。同一份摘要 36,674 → 29,393 token(-19.9%),Mac 从 **506 个簇 > 回到 550 个、69.8% → 75.6%,同预算档重新胜 Drain3(72.2%)**。 > (token 数末几位随摘要里那行耗时的位数抖动 ±2~3 —— 本轮实跑值如上, > **可复现的结论是比率与簇数**。) > 但**仍没回到 2.10.0 的 90.4%**:剩下的成本是 16 位摘要本身,而它是那条承诺的 > 落点。90.4% 这个数字仍然作废,别因为回到 75.6% 就以为它复活了。 > 复现:`python scripts/benchmark_loghub.py --budgets 32000` **胜负怎么判的**:一律按**事件种数**比,不用四舍五入后的百分数。 报告只有 1 位小数,0.05pp 以内的差与舍入误差分不开,**落在容差里一律记平** (v2.9.6 之前直接比百分数,把一个 0.005pp 的舍入差判成了胜)。 对照的三个都是真工具:Drain3(ICWS'17 学术标准)、 LogsLop(AMD 2026-07,去重工具,与证据保留**目标相反**)、tail/grep 两条朴素基线。 > **这张表现在有门禁在守。** `docs/benchmark_baseline.json` 存着最近一次全量实测, > `python scripts/prove.py` 的第 11 条主张拿它与这张表**逐格对账** —— 并且不只校这一份: > 同一张表在 `docs/BENCHMARK.md` 与 `docs/FAQ.md` 里各有一份副本,三份逐格对账; > 连「几个数据集赢、几个平、几个输」这种汇总口径也一并重算 —— 这批数字曾在 > `docs/BENCHMARK.md` 上漂过 9 格,另有一处把平局当成了赢。具体数字见上表。 > 上一版(v2.9.9)改了 `mask_text` 让 HPC、Zookeeper、Proxifier 的数字全变了, > 而这张表原地不动、六道门禁全绿 —— 与 v2.9.5 撤回的那次是同一个病,现在补上了对账。 > 完整方法学、**为什么会在一个数据集上输**、以及 v2.9.3「已发布数字系统性偏低」、 > v2.9.5「指标在数用户没收到的东西」、v2.9.8「指标涨了但产品崩了」三次撤回的经过, > 全在 [`docs/BENCHMARK.md`](docs/BENCHMARK.md)。被质疑时先看那里。 ### 换一把不是自己设计的尺子:Loghub 标准解析协议 PA / GA 上面那张表的指标全是**本项目自己定义**的。「簇样例覆盖了多少种 Loghub 事件」 不是任何公认指标的名字,换个定义数字就变 —— 所以它回答不了 「你的聚类放到同行里是什么水平」。 v2.11.5 第一次用**外部定义**的指标量自己的聚类:**PA / GA**(LogParser, ICSE-SEIP'19 提出,Drain / Drain3 / LILAC / LLMParser / LibreLog 全部在用), 口径锚在两份互相独立的实现上(`logpai/logparser` 与 `zeyang919/LibreLog`), 并带同机同口径的 Drain3 对照臂: | 口径 | 本项目 | Drain3 0.9.11 | | --- | ---: | ---: | | PA(解析准确率) | **85.05%** | 58.06% | | GA(归组准确率) | **88.68%** | 71.58% | **两个口径都胜**(逐数据集 **PA 10 胜 0 负**、GA 8 胜 2 负)—— 两个都列。 > **2026-11-10 修了一处口径不对称**:PA 那一列此前取的是**逐行字面模板**, > 而对照臂 Drain3 取的是**簇的最终模板** ⇒ **两侧不是同一个量,我方被系统性低估** > (Linux 15.87% vs 74.88%,而同一批行的 GA 是 88.80% ⇒ 自相矛盾)。 > 修正后 PA 取簇模板 ⇒ **PA 与 GA 是同一个聚类的两个视角**,两侧口径一致。 > 详见 [`docs/BENCHMARK.md`](docs/BENCHMARK.md)「PA 口径修正」一节。 > **这两格能拿去和公开榜单比吗?不能。** 外部有一份公开的 Loghub 2.0 逐数据集 > 榜单(SOTA2 Research,2026-03-28 快照),上面**同一个 Drain、同一个 Linux > 数据集**报的 GA 是 **42.2%**,而本项目同机同口径量到的 Drain3 对照臂是 > **80.21%** ⇒ **两边的地真值与协议不是同一套**,跨表比较毫无意义。 > ⇒ 本项目只主张**同一台机器、同一份输入、同一段口径下 vs Drain3 对照臂**; > 榜单上排前面的多是大模型系方法,而本项目**不把日志交给大模型** > (`AGENTS.md` §1)⇒ 那不是同一场比赛。详见 > [`docs/BENCHMARK.md`](docs/BENCHMARK.md)「公开榜单上的数字」一节。 > **这两格怎么自己算出来,写在 [`docs/REPRODUCIBILITY.md`](docs/REPRODUCIBILITY.md)。** > 它逐项标明哪些口径是**全量**(十集 1,940,760 行、1,621 簇)、哪些是**抽样** > (LLM 对照每集 2,000 行,不与全量同表)、每个数字对应哪个文件与哪条命令, > 并给出十集日志与结果快照的 sha256。校验入口: > `python scripts/verify_repro_manifest.py`。**「全量可复算」不等于「全球领先」**, > 这句话也写在那份文档里。 GA 这一格是 2026-11-09 那一轮(第二十四轮)赢的,**赢在「相似度的单位」 而不是阈值**:以前比的是**整条消息的字符编辑距离**,38 个字符的样板前缀 能把 3 个字符的区分词淹没(「同类内变化」与「异类差异」在字符层长得一样); 而且整段引号内容被掩成 `S`,`"GET /v2/…"` 与 `"POST /v2/…"` 掩完**逐字节 相同** —— Loghub OpenStack 那两个只差一个方法词的事件(E42 占 44% 的行) 在**掩码阶段**就分不开了。 现在比的是**逐词元**的相似度(模板按位置对齐),并加上**模板推断** (取值会变的位置记成 `<*>`,与 Loghub 的 `EventTemplate` 同形)。 **阈值一个字没改**(仍是 0.85)—— 它是发布版既有行为,不是对着评测集挑出来的, **本轮也没有因为基准把它改掉**。GA 58.19% → **83.89%**(第二十五轮再 +2.25pp; 2026-11-16 请求行三词元化再 +4.79pp 到 **88.68%**), PA 58.96% → **79.29%**(同一轮里 PA +20.32pp、GA +23.45pp;第二十五轮再 +0.01pp; 2026-11-16 方法词硬隔离再 +5.76pp 到 **85.05%**)。 > **第二十五轮还改了一个「逐行静态模板」的量**(`PA_static`,**对照臂没有对应输出 > ⇒ 不参与场次判定**):此前用**整条消息**的 `mask_text`,改成「**按空格分段、 > 逐段掩码**」之后,引号串**内含空格**时(`"GET /v2/… HTTP/1.1"`)引号先被切开 ⇒ > **方法词活下来**(事件身份不能丢);引号串**不含空格**时(`'abcd'`)整段被换成 `S` > ⇒ 与地真值里 `<*>` 覆盖引号内容的做法一致。OpenStack 因此从 51.61% 跳到 **99.16%**。 > **上一版把它写成「PA」是张冠李戴** —— 那是另一个量,本轮已更正。 **「那能不能全胜?」—— 量过了:现在 PA / GA 两个口径都赢,但还有两个缺口。** 把 GA 的失分**逐行**拆开后发现它落在两个方向相反的桶里: 过合并(一个簇混了多个 EventId,要调**严**)与过分裂(纯簇但没收全, 要调**宽**)。两桶占比几乎对半,而**主导方向因数据集完全相反** —— 一半的数据集以过分裂为主,另一半以过合并为主。扫**六档**阈值还能量到: **每个数据集的 GA 顶点落在不同的地方**(Apache 0.70、**Linux 0.80**、 Hadoop 0.85、HealthApp 0.80/0.85 并列),而**四集算术平均的顶点在 0.80 (GA 94.91 / PA 89.55)**,0.85 是第二名(94.36 / 89.19)—— **PA 与 GA 两个口径指向同一个位置**,而「哪个数据集该用哪个阈值」 不是产品能回答的问题。 > **这一格 2026-11-15 更正过一次,记着怎么错的**:上一版写的是 > 「0.85 是四集算术平均的顶点(94.36)」,因为旧扫描只采了 > 0.40 / 0.70 / 0.85 / 0.90 / 0.95 **五个点,漏采 0.80**。 > 补上 0.80 之后,0.85 从「顶点」变成「第二名」(GA −0.55pp)。 > **默认值仍然保持 0.85**:把默认值改成 0.80 才是对着评测集调参 > (AGENTS.md §2.3),而这是本轮明令不做的事。 > 复现:`python scripts/bench_ga.py --datasets Apache,Hadoop,HealthApp,Linux`。 > **十集补测(2026-11-16)把上面这一格的适用范围说清了**:那四个数据集之外 > 的六集(HPC / Mac / OpenSSH / OpenStack / Proxifier / Zookeeper)此前 > 从未被扫过。补齐之后**十集六档的 GA 顶点是 0.85(83.89)**,0.80 只有 > 78.01 —— 与上一格的方向相反。逐集全表与「去掉 Proxifier」「看中位数」 > 两种敏感性核对见 `docs/BENCHMARK.md` 的「十集 × 六档全表补测」。 > 默认值仍然是 0.85:这次它不只是既有默认值,还是实测顶点。 ⇒ 任何号称「全胜」的改法,要么是在另一个指标上退让,要么是牺牲掉一部分 数据集,要么动的是结构。**这两版动的都是结构**(换相似度的单位 + 模板推断 + 洞位吸收变长跨度),**阈值一个字没改**。精确数字与逐格对账见 [`docs/BENCHMARK.md`「结果四·五」](docs/BENCHMARK.md#五能不能全胜--把-ga-的失分逐行拆开量)。 **第二十五轮修掉的那一格(OpenSSH 73.40% → 95.43%)赢在「同一件事有两种表面形态」。** Loghub 的 GA 条件 (b) 是「该簇必须包含该事件的**全部**出现」⇒ **差一行整组归零**。 E33 有 140772 行,其中 **4 行**是 10 个词元(`Failed password for invalid user from …`, 少一个用户名、多了两个字)⇒ 落进别的簇 ⇒ **140768 行整组归零**, 单独造成 169956 行失分(占全项目失分 44%)。 修法是**洞位吸收变长跨度**:洞位可以吃掉一段连续词元;关键是 「**每个模板位必须吃掉 ≥1 个词元**」—— E25 的模板是 11 位,10 词元的消息 **原理上放不下** ⇒ 不会被误拖进来。+22.03pp × 638947 = 140760 行, 与 E33 的 140772 行**精确吻合**。 剩下的缺口**不是阈值能解的**(§2.3 那条纪律的正面写法): * **OpenStack 的 `"GET"` / `"POST"`**(GA 41.51%,那个数据集的天花板是 100%):9 个词元里 9 个相同、只有 1 个不同 ⇒ 相似度 0.94 ≥ 0.85 ⇒ 仍被判为同类。**任何单一相似度都切不开它** —— 同样「一个词元不同」, Linux 那边(`cupsd` vs `syslogd`,Loghub 判为**同一个**事件)却要合并 ⇒「9/10 相同 ⇒ 不同」与「2/3 相同 ⇒ 相同」**方向相反**。 ⇒ **这一格本轮试了两种判据,都被实测否掉**(脚本可复算): 1. **该位置的取值基数**(方法词位只有 2~3 个取值 ⇒ 身份位;程序名位几十个 ⇒ 变量位):**不可分** —— k=2 那一档上 78 个「该拆」与 203 个「该合」 **完全交叠**,没有无参数的阈值可用; 2. **该取值出现在多少个不同形状里**(IDF 思路,身份位的取值只出现在 一个形状里、变量位的取值跨形状复用):**判别力不足** —— split 组 判对率只有 27%。 ⇒ **结论写在这里,不藏着:Loghub 的人工标注本身含语义判断, 任何纯统计的局部规则都复现不了它。** 这一格要么引入语义组件 (= 改产品定位,§1 明确禁止,本项目不做),要么接受。 * **字母变量的第一个变体**(Linux 的 `<*> shutdown succeeded`、 `session closed for user <*>`):第一个变体与模板的相似度低于阈值 ⇒ 位置**没机会**被学成变量 ⇒ 事件被拆开(Linux 每 10 个事件里有 1 个)。 **同一个判据**能同时修好它。 这一节还暴露了一个**此前没有任何本项目指标发现过的解析层缺陷**: 喂原始日志时 PA 平均 31.08%,喂 Loghub 的 `Content` 列(剥掉时间戳/主机/ 级别后的正文,也是 Drain 官方要求喂的输入)时是 85.05% —— 差 53.98 个百分点, 其中 4 个数据集在原始日志口径下 PA **恰好是 0.00%**。原因是本项目的解析器 不剥这些数据集的 syslog 头。本版**不修**:修它要先决定「哪些头部格式该剥」, 而对着评测集改规则是 AGENTS.md §2.3 明令禁止的。把缺口量化写出来, 比改一个正则然后宣称修好了更有用。 四张表(含逐数据集明细与对照组)的每一格都由 `tests/test_logparser_pa_ga_table.py` 对着 `docs/logparser_pa_ga.csv` 逐格核对。 完整方法学、协议适配的三处偏离、以及「这一节不能证明什么」, 全在 [`docs/BENCHMARK.md`](docs/BENCHMARK.md) 的「结果四」。 --- ## 🚦 工程指标 | 指标 | 实测值 | | --- | --- | | 生产代码 | 10,685 行(36 个模块),硬依赖只有 PyYAML | | 测试 | **2,319 用例**,覆盖率 **95%**(漏行 260 / 4,819 语句 —— **本机 Windows 实测**;参考矩阵那一格**待 CI 回填**,理由见下),`ruff` 全绿 | | CI | Ubuntu 3.11 / 3.12 / Windows 3.12 三矩阵,**十二道门禁**:ruff / 单测+覆盖率 / 对抗评分卡 / 确定性指纹 / 自证脚本 / 构建可复现性 / **变异存活率记分卡**(只跑参考矩阵一条)/ **SAST** / **依赖漏洞扫描** / **性能回归** / **产物审计**(产物本身,不是源码树)/ **sdist 自测**(源码交付能不能自证) | | 自证脚本 | 现已断言 **11 条**主张,含「README 工程指标与架构树必须与仓库一致」「README 写的条数不许漂」「**每一处基准表逐格对账实测基线(含胜负场次与合计行)**」 | | 构建 | 可复现 —— 同源码两次构建字节相同,且**与构建机的 git 配置无关**(两种 `core.autocrlf` 各导一次,字节必须相同),本地/PyPI/GitHub 三方 sha256 对账 | | 依赖 | **运行时硬依赖只有 PyYAML 一个**,全部 16 条声明依赖(含 web/mcp/ai 三个 extra 与开发工具)经 pip-audit 扫描无已知漏洞;Dependabot 每周一提 PR | > **上面这十二道门禁里的门禁清单本身也有门禁在守**: > `tests/test_ci_gate_wiring.py` 双向核对 —— README 写下的每一道都必须 > 在 `ci.yml` 里有一个真正执行它的步骤(认的是 `run:` 正文,不是步骤名), > 而 `ci.yml` 里的每一道也必须出现在这张表里。 > 这条判据来自一次真实翻车:仓库里有脚本、有测试、本地跑绿, > 但没接进 workflow —— 而那种状态从外面**完全看不出来**。 > 三道新门禁各自「先证明自己会红」的做法,写在 > [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) 与 > [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)。 > **覆盖率的分母比上面那行代码量小**:`pyproject.toml` 的 > `[tool.coverage.run] omit` 排除了 `cli.py`(薄适配层,982 行, > 只做参数解析与格式分发)。所以**这个覆盖率**是在 9,703 行上算的, > 而「10,685 行生产代码」**含**它 —— 两个数字口径不同,别拿它们互推。 > 这个排除列表由 `tests/test_coverage_omit_watchdog.py` 钉住: > 增删任何一项都会红;分母这个数本身由 `prove.py` 重算。 > > **百分比与那句明细的口径都是 ubuntu-3.12 的实测值**,CI 只在参考矩阵上 > 对账。其余矩阵照打不误地报出自己那份数字,不参与判定。 > 其中「4,819 语句」跨平台**必然相同**(它由源码静态解析决定), > 而「漏行」**会差几行** —— 语句数相同而覆盖数不同,只可能是条件分支 > 在另一套上没被执行到。 > > **引用必须写成「run + head + 结论」三件套**(2026-10-29 第十七轮修): > 此前**第十六轮那一格**指向的是**另一个提交**的 CI,而且那个 run **结论是 failure** > (`pull_request` 事件触发);被测的合并提交 `850550f2` 自己的那次 CI 是 > `push` 事件、结论 success —— `run 40765275081,head 850550f2,结论 success`。 > **数字没错(两个 run 报的覆盖率 annotation 一模一样),错的是溯源** —— > 而「数字是谁测的」恰恰是本文件 §4d 规则一要管的事。 > 更正记录见 `CHANGELOG.md` 的 2.13.2 一节(第十七轮第 4 条)。 > `tests/test_ci_run_provenance.py` 现在守着这条:README 里作为测量来源的 > run 必须**结论 success**,且必须写明 head 与结论。 > > **这一格的四个数由参考矩阵(ubuntu-3.12)的 CI 实测回填**: > 2026-11-10 第二十五轮动过 `core/clustering.py`, > coverage 的 `lines-valid`(语句数)变成 **4,819** > —— 语句数由源码静态解析决定,**跨平台必然相同**,本地可量; > 而「漏行」**是平台相关的量**(条件分支在另一套上没被执行到) > ⇒ **只有参考矩阵那次 CI 的实测值算数**(§4d 规则四:本地数不能填那一格)。 > **回填顺序固定:先让门禁报出参考矩阵的真值,再回填** —— > **这一格上一次采信的出处是 `run 40860469360,head 1351c49d,结论 success`** > —— ⚠️ **它测的是本轮改动**之前**的代码**(它报的是 > 「ubuntu-latest 3.12 实测覆盖率 95%,漏行 256 / 语句数 4703」—— **那是上一版的数**; > 两次 annotation 的原文都逐条列在 `CHANGELOG.md` 的 2.13.2 一节); > 本轮改了 `core/clustering.py` 之后,**语句数变成 4,819**(静态解析, > 跨平台必然相同),而「漏行」是平台相关的量 ⇒ **参考矩阵的新值待 CI 回填** > —— 在那之前,本文件里给的是**本机 Windows 实测**的 260。 > **首次量到新数的那一次是红的** —— 数字回填之前必然对不上; > 而那条 annotation 是**无条件**发出的 ⇒ 那一轮红着也能读到数。 > 那次红色 run 的号 / head / 结论记在 `CHANGELOG.md` 的 2.13.2 一节 > (那里把两次的 annotation 原文都逐条列了出来)。 > > | 在哪测的 | 漏行 | 百分比 | > | --- | --- | --- | > | **ubuntu-3.12**(CI 参考矩阵,README 采信这个) | **256** | **95%** | > | ubuntu-3.11(CI) | 256 | 95% | > | windows-3.12(CI) | 252 | 95% | > | windows-3.11(**作者那台 Windows 本机**) | 252 | 95%(94.64%) | > > ⇒ **平台参与**(256 vs 252,差 4 行); > ⇒ **这一次 Python 版本没测出差异**:ubuntu 的 3.11 与 3.12 都是 256, > 本机(3.11)与 CI 的 windows-3.12 也都是 252。 > ⇒ **这一轮四格都是 95%** —— 但**边界仍然贴着**: > ubuntu 那一格的 line-rate 是 0.9456(94.56%),再多 **3** 行没被覆盖 > (漏行 259)它就掉成 94%(94.4929%);windows 那一格要再多 **7** 行。 > 所以「95% 还是 94%」这件事**平台仍然参与**,本地跑出来的那个数 > 不能拿去填参考矩阵那一格。 > ⇒ 上一版这里记的「差 39 行」里,那个本机数(168)是**旧工具链**下测的 —— > 那套 pytest 7.4.4 + pytest-cov 4.1.0 的组合会让 coverage 的 `omit` 失效, > 记的是**另一个分母**上的数 ⇒ 不是一个可比的口径。 > ⇒ 所以本地跑出来的漏行数**不能**拿来填这个位置,**只有参考矩阵的实测值算数**。 > 两个数都被 CI 逐个比对,与参考矩阵对不上就红。 > > **「漏行」这个数是分支口径**(`coverage.xml` 的 `lines-valid` 减 > `lines-covered`),**不是** pytest 报告里那个 `Miss`(那是**语句**口径)。 > 两者差着一两行 —— 2026-10-22 实测:本机同一份代码,语句口径 Miss 168、 > 分支口径漏行 168,而 CI 报的那 207 走的是分支口径。 > **填错口径,数字看起来一样却不是同一个量** —— 所以那一格的值 > 只能用**与 CI 同一个口径**去量,不能拿 pytest 报告里的数凑。 --- ## 🤖 MCP Registry(给 AI Agent 用的入口) 仓库根目录的 [`server.json`](server.json) 就是官方 Registry 的清单格式, 登记名 `io.github.hu-chenyu/log-ai-compressor` **已于 2026-10-18 提交**, 指向 PyPI 上的 `log-ai-compressor` **2.13.1**(stdio,`uvx` 拉起)—— 清单里的版本号跟着每次发版更新(`tests/test_registry_manifest.py` 盯着 它与 `pyproject.toml` 一致)。 自己复核,不必只信这段话: ```bash curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hu-chenyu/log-ai-compressor" ``` 2026-10-18 实查(读满响应全长 12,618 字符,不是只看前几条):全名查返回 `count=3` —— 同一个登记名下挂着 2.11.2 / 2.11.3 / 2.11.4 **三个版本**, `isLatest` 指向 `2.11.4`(`publishedAt` 2026-10-18T14:07:06Z)。所以复核时必须 **全名 + 版本**一起看:只看名字或只看 `count` 都会对着旧版本报「已收录」。 同一接口拿已知存在的 `everything` 做阳性对照返回真实条目 (`com.everythingmeetsai/archive`)—— 所以那个 3 是「查到了」, 不是「这个接口只会回 0」。 **2026-10-23 再查一次**(接口的响应形状变了,所以单独记一段):同一个查询现在 返回 `metadata.count = 12` —— **同一个登记名下挂着 12 个版本**(2.11.2 … 2.12.7)。 两个字段的位置也变了:`count` 从顶层挪进了 `metadata`,版本号在 `servers[].server.version`(不再是顶层 `version`,`isLatest` 这个字段也没了)。 **2.12.7 在册** —— 判据仍是「全名 + 版本」双重精确匹配, 与 [`publish-mcp.yml`](.github/workflows/publish-mcp.yml) 里的回查代码用的是同一套字段。 > 一件今天才看清的事:Registry 上**每个发过的版本都留着条目**, > 而 PyPI 上按「只留最新版本」只留最新版 > ⇒ **Registry 里查得到某个版本,不等于 > `pip install log-ai-compressor==那个版本` 还能装上。** > 复核「能不能装上」请直接查 PyPI。 > 「只看前 N 个版本会得出相反结论」这件事已经踩过两次:响应里**第一条通常是 > 旧版本**,而「找出新登记的那个」这个任务本身要求的恰恰是最后一条。 > 只读前 4000 字符时看到的是 `2.11.2`,照那个写就是错的。 这一段改过三次,三次都是照实写:第一版写着「已收录」而当时实测是 0 条, 第二版写成「清单已备好、尚未提交」,第三版才是真登记。查证日期、版本与阳性对照 都留在上面,好让下一个人不必只能相信作者。 登记由 [`publish-mcp.yml`](.github/workflows/publish-mcp.yml) 在 GitHub Actions 里用 OIDC 提交(推 tag 或手工触发都会跑,不需要存放任何密钥)。 提交前它核对 tag / server.json / pyproject 三份版本号、对官方 checksums 校验发布器 二进制、再跑一遍活校验器;提交后按**全名精确匹配**回查 —— `count > 0` 会被同名 子串命中,那种绿灯是假的。 官方校验包归属时抓该版本 PyPI README 里的这个标记,所以标记一直放在正文里 (`tests/test_registry_manifest.py` 盯着它,防止哪天被压缩进 HTML 注释而失效): ```yaml mcp-name: io.github.hu-chenyu/log-ai-compressor ``` Windows 可双击 `start.bat` 自动定位 Python、装依赖、启动并打开浏览器。 --- ## 🧰 能力 | 领域 | 能做什么 | | --- | --- | | **取证** | 每条结论绑定 `evidence_id` + 文件 + 行号区间 + 原文 sha256;`verify` 重读原文逐条核对,被改动报 `TAMPERED` | | **确定性** | 报告带「确定性指纹」,同一份日志两次分析的**指纹逐字节相同**(耗时与速率已排除)。**注意口径**:指纹相同 ≠ 报告文件逐字节相同 —— 报告里还有 `generated_at` / 耗时 / 速率这类运行期字段(实测 4 个字段会变),要归档请存指纹 | | **置信三档** | `CONFIRMED` / `LIKELY` / `INSUFFICIENT`。`CONFIRMED` 只来自三类能落到原文的证据:条目内 `Caused by:` 链、块级生命周期链(HDFS `blk_`)、应用级生命周期链(YARN `application_*/job_*/attempt_*`,带显式失败签名);三类都必须能取出原文引用,取不到就降 `LIKELY`,并**列出还缺什么才能定论** | | **缺口自闭环** | 缺口清单由日志里实际有什么驱动。日志带 `trace_id` → 调用链重建成功 → 「缺少调用链关联」自动关闭;一条都没有就如实申报 | | **解析** | ISO / syslog / logcat / logfmt / JSON Lines / 中式堆栈;可插拔 YAML 规则改配置不改代码;编码自动适配 UTF-8/GBK/UTF-16/32 + `.gz`/`.zip`。**同一文件里混着两种编码也能解**(逐行兜底),并会在报告里写明有几行不是主编码 | | **调用链** | 结构化日志里存在 `trace_id` 时重建跨服务链路与首个失败点,不需要装 agent、不需要接拓扑 | | **跨行因果链** | 因果挂在资源 ID 上时(HDFS `blk_`、YARN `application_*/job_*/attempt_*`),按 ID 串起生命周期;命中失败阶段即 `CONFIRMED`,每个因各带一条原文引用,取不到就降档 | | **Web 界面** | 主界面零构建零 CDN、**完全离线可用**(实测:页面只引用一个内联 SVG 图标);文件浏览器直选本机文件(不走网络);SSE 实时进度 + 可取消。**唯一例外**:`/api/docs` 是 FastAPI 自带的 Swagger 页,它从 `cdn.jsdelivr.net` 拉样式表 —— 断网时那一个页面是空白(主界面不受影响) | | **AI 解读**(可选) | 在压缩结果之上生成人话解读。**不配 API Key 也能完整用**,AI 只是额外一层 | 完整清单与边界见 [`docs/FEATURES.md`](docs/FEATURES.md)。 --- ## 🧱 能力边界(做不了的事,与谁行) | 它做不到 | 为什么 | 谁行 | | --- | --- | --- | | **比云平台更高的根因准确率** | 多模态根因需要指标 + 链路 + 拓扑。本工具只有日志一种 | Datadog / SLS / Dynatrace | | 持续监控与告警 | 没有 agent 埋点、没有时序库、没有告警队列。**这是有意的取舍** | 全部 APM 平台 | | 调用链追踪 | `traces` 是从日志里的 `trace_id` **重建**的,不是采集的 | Jaeger / Tempo | | 「召回率」实测 | 只有 **1 个**含链真实数据集的全量结果(Android_v1,1,555,005 行 / 131 链)。另有 Hadoop 应用级链(55 个作业 / 30 个失败作业,召回 100%,**样本量小**)与 HDFS 块级链(575,061 块,但 **62.8% 的标注异常在这份日志里没有可用证据**,且原始日志未入库)。原先并列的 Hadoop 91.4% 已于 v2.7.0 撤回。**这些样本撑不起「通用召回率」这个说法,这是本项目最实在的短板** | — | | 隐私合规认证 | 它不处理合规,只保证「数据不出本机」 | — | 还有一条是**写在代码里而不只是文档里**的硬约束: > **调用链只证明顺序,不证明因果。** 有完整 trace 但没有可落到原文的失败证据时, > 工具仍然只给 `LIKELY`、`can_conclude=false`。`CONFIRMED` 只来自 > 「条目内 Caused-by 链 / 块级生命周期链 / 应用级生命周期链」这三类 > 带原文引用的证据。对抗评测里有一个场景专门盯它。 --- ## 🗂 深入 | 文档 | 里面有什么 | | --- | --- | | [`docs/BENCHMARK.md`](docs/BENCHMARK.md) | 全部实测的方法学、口径、公平性说明、**两处落后的病因**、撤回记录、跨行因果链(块级 / 应用级)评测 | | [`docs/SOTA_COMPARISON.md`](docs/SOTA_COMPARISON.md) | 与 LLM few-shot 解析器(DivLog / LogPPT 协议级复刻)的十集同口径对照:PA/GA、成本、不可比理由 | | [`docs/EVALUATION.md`](docs/EVALUATION.md) | 对抗性评测(专门设计来误导本工具的 10 个场景)+ 置信档位实测 | | [`docs/FAQ.md`](docs/FAQ.md) | 逐条回答质疑:「凭什么比 Drain3 强」「自信错误率是不是门槛设高了」… | | [`docs/POSITIONING.md`](docs/POSITIONING.md) | 与全品类日志工具的差异论证 | | [`docs/FEATURES.md`](docs/FEATURES.md) | 完整能力清单 | | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 模块树、分层依赖、核心算法 | | [`docs/CLI.md`](docs/CLI.md) | 完整命令行用法 + 自定义解析规则 | | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | 开发、测试、门禁说明 | | [`docs/security/INDEX.md`](docs/security/INDEX.md) | 每日安全台账:依赖漏洞 / 疑似密钥 / 危险调用,逐日可查(`python scripts/security_daily.py`);口径与决策见 [POLICY.md](docs/security/POLICY.md) | | [`AGENTS.md`](AGENTS.md) | **给 AI agent 的工作契约**:分层与唯一门面、十二道门禁各自守什么、这个仓库特有的坑 | | [`CONTRIBUTING.md`](CONTRIBUTING.md) | 人类贡献流程:分支、提交约定、基准纪律、发版与三方 sha256 对账 | | `SKILL.md` / `INSTRUCTIONS` | 接入 Claude Code / Codex / Mavis 等 Agent | **复现本文所有数字:** ```bash python scripts/fetch_datasets.py --all # 下公开数据集 python scripts/benchmark_loghub.py # 证据保留率对照 python scripts/prove.py # 自证:不必相信作者,自己跑 ``` ## 🙏 外部复现者致谢 这个仓库的每个数字目前都是**作者自证**。下表只登记真正跑过的人(规则见 [docs/REPRODUCIBILITY.md 第八节](docs/REPRODUCIBILITY.md)): | # | 环境 | 结论 | 日期 | |---|---|---|---| | — | 暂无 | 等你来做第一个 | — | 想进这份名单:按 Issue [#IKVUSO](https://gitee.com/hu-chenyu-dev/log-ai-compressor/issues/IKVUSO) 里的两条命令跑一次,回帖写清「操作系统 + Python 版本 + 退出码」,**署名或匿名都行,成败都算数**。 ## License MIT