Metadata-Version: 2.4
Name: log-ai-compressor
Version: 2.16.5
Summary: 本机日志取证层：每条结论带行号出处与原文 sha256，可脱离本工具自校验；拿不出因果链就说证据不足并列出还缺什么。零出网。附 Loghub 2.0 可复现基准（对照 Drain3 / tail / grep）。
License-Expression: MIT
Project-URL: Homepage, https://gitee.com/hu-chenyu-dev/log-ai-compressor
Project-URL: Repository, https://gitee.com/hu-chenyu-dev/log-ai-compressor
Project-URL: Changelog, https://gitee.com/hu-chenyu-dev/log-ai-compressor/blob/feat/a2-http-request-skeleton/CHANGELOG.md
Project-URL: Releases, https://gitee.com/hu-chenyu-dev/log-ai-compressor/releases
Keywords: log,analyzer,llm,compressor,troubleshooting,benchmark,reproducible,root-cause,local-first,forensics,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Logging
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: pydantic>=2; extra == "web"
Requires-Dist: uvicorn[standard]>=0.27; extra == "web"
Requires-Dist: sse-starlette>=1.6; extra == "web"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: ai
Requires-Dist: httpx>=0.27; extra == "ai"
Provides-Extra: all
Requires-Dist: log-ai-compressor[ai,mcp,web]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: drain3>=0.9.11; extra == "dev"
Requires-Dist: logslop>=0.1.2; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Dynamic: license-file

# log-ai-compressor

### 日志不用喂给大模型，也能给出「你能自己核对」的根因

> 每条结论带原文的**行号区间**和那段原文的 **sha256**；拿不出因果链就说
> **证据不足**，并精确列出还缺什么才能定论。**全部计算在本机完成，日志不出网。**

[![Release](https://img.shields.io/badge/release-v2.16.5-c71d23)](https://gitee.com/hu-chenyu-dev/log-ai-compressor/releases/tag/v2.16.5)
[![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%2C328%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.5"
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,328 · 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.5（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：
> <https://gitee.com/hu-chenyu-dev/log-ai-compressor>。
> 本 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,328 用例**（2,325 passed / 3 skipped，跳过原因见 [`docs/REPRODUCIBILITY.md`](docs/REPRODUCIBILITY.md) §7），覆盖率 **95%**（漏行 260 / 4,819 语句 —— **本机 Windows 实测**；参考矩阵那一格**待 CI 回填**，理由见下），`ruff` 全绿 |
| CI | Ubuntu 3.11 / 3.12 / Windows 3.12 三矩阵，**十二道门禁**：ruff / 单测+覆盖率 / 对抗评分卡 / 确定性指纹 / 自证脚本 / 构建可复现性 / **变异存活率记分卡**（只跑参考矩阵一条）/ **SAST** / **依赖漏洞扫描** / **性能回归** / **产物审计**（产物本身，不是源码树）/ **sdist 自测**（源码交付能不能自证） |
| 自证脚本 | 现已断言 **11 条**主张，含「README 工程指标与架构树必须与仓库一致」「README 写的条数不许漂」「**每一处基准表逐格对账实测基线（含胜负场次与合计行）**」 |
| 构建 | 可复现（**口径：`python scripts/build_repro.py`**）—— 同源码两次构建字节相同，且**与构建机的 git 配置无关**（两种 `core.autocrlf` 各导一次，字节必须相同），本地/PyPI/GitHub 三方 sha256 对账。裸 `python -m build` 不在这个口径内：那样出来的 sdist 每次都带新 mtime，字节不同 |
| 依赖 | **运行时硬依赖只有 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 等 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
