Metadata-Version: 2.4
Name: log-ai-compressor
Version: 3.0.1
Summary: 本机日志取证层：每条结论带行号出处与原文 sha256，可脱离本工具自校验；拿不出因果链就说证据不足并列出还缺什么。本地分析不出网；可选 AI 解读将脱敏后的片段发送给所配置的模型服务商（默认关闭）。附 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，改一个字节就露馅。**
给查日志的运维 / 后端 / 安全：本机跑，日志不出网，0 次 API 调用。

每条结论 = 原文行号区间 + 那段原文的 sha256；`verify` 重读原文逐条核对，
日志被改过直接判 `TAMPERED`（退出码 1）——你不必相信工具，自己核。

先看一份 24 行日志的真实输出：根因、4 条引用、每条的原文行号和 sha256，全部在本机算完。

[![Release](https://img.shields.io/badge/release-v3.0.1-c71d23)](https://gitee.com/hu-chenyu-dev/log-ai-compressor/releases/tag/v3.0.1)
[![Tests](https://img.shields.io/badge/tests-2%2C431%20%C2%B7%20green-brightgreen)](https://gitee.com/hu-chenyu-dev/log-ai-compressor/blob/main/docs/REPRODUCIBILITY.md)

[90 秒跑样例](#它长什么样一份-24-行日志的真实输出) · [三分钟自证](#三分钟自证装--跑--复核) · [复现全部数字](docs/REPRODUCIBILITY.md) · [English](README.en.md) · [我要一条真实复现](https://gitee.com/hu-chenyu-dev/log-ai-compressor/issues/IKWWD3)

<img src="https://gitee.com/hu-chenyu-dev/log-ai-compressor/raw/main/docs/images/web-ui-home-top.png" width="720"
     alt="本机日志取证层首页：拖入日志或浏览文件，级别默认只留 ERROR/WARN，点开始分析">

**改一个字节会怎样**：

```console
$ log-ai-compressor verify --report examples/app_report.json
证据：共 4 条引用，匹配 3 条，失配 1 条，源不可读 0 条，缺行号 0 条，缺摘要 0 条

自校验结论：TAMPERED        # 退出码 1

  ✗ MISMATCH c3801f905159 examples\app.log 期望 bc5b93cec7cde01c 实际 1b8242c1671f1e29
```

这 6 行不是手写的：先跑下方三分钟自证生成 `examples/app_report.json`，再把 `examples/app.log` 里的 `db-primary` 改成 `db-primarY`，重跑 `verify` 即得上图；改回即 `VERIFIED`。

判定没有「大部分通过」这一档，四档见 [`docs/CLI.md`](docs/CLI.md)。

## 三分钟自证：装 → 跑 → 复核

```console
$ pip install log-ai-compressor
$ log-ai-compressor run examples/app.log -f json -o examples/app_report.json
$ log-ai-compressor verify --report examples/app_report.json
模式：复核已导出报告
对象：报告 app_report.json
证据：共 4 条引用，匹配 4 条，失配 0 条，源不可读 0 条，缺行号 0 条，缺摘要 0 条

自校验结论：VERIFIED
每条结论都能在原始日志里逐行复核。
```

同一条命令加 `--json`，机器可读字段是 `checked: 4 / matched: 4 / mismatched: 0`。

## 它长什么样：一份 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）
```

### 拿到结论之后，三个动作

```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   # ① 自校验：重读原文，逐条核对 sha256
$ log-ai-compressor evidence examples/app_report.json           # ② 看原文：这条结论引用的那几行
$ log-ai-compressor run examples/app.log -f summary             # ③ 投喂：只把精简摘要交给模型
```

① 只给判定（`VERIFIED` / `TAMPERED` / `UNVERIFIABLE` / `NO_EVIDENCE`），不指控你；② 与 ① 共用同一套回读；③ 默认输出到 stdout。第 3 条标题指向链尾真因（L18–L22），不是外层症状。

> 首屏这几条命令由 `tests/test_readme_sample_is_reproducible.py` 真跑一遍盯着。

## 打开界面（推荐入口）

<img src="https://gitee.com/hu-chenyu-dev/log-ai-compressor/raw/main/docs/images/web-ui-result.png" width="720"
     alt="本机日志取证层：24 行样例日志跑出的「已定位根因」+「全部核对通过 VERIFIED」">

| 你的环境 | 一条命令 |
| --- | --- |
| Windows | 双击仓库根目录的 `start.bat` —— 自己找 Python、缺依赖就装、装完开浏览器 |
| 任意平台 | `pip install "log-ai-compressor[web]" && log-ai-compressor web` |

三步就到结论：**① 拖日志进窗口（或点「浏览…」）→ ② 级别默认只留 ERROR/FAIL/WARN →
③ 点「开始分析」**。第一屏给的是「已定位根因 / 证据不足」这一张卡，不是一堆模板簇；
点卡下方**复核证据出处**，工具重读原始日志逐条核对，给出 `VERIFIED` 或 `TAMPERED`。

> 界面零构建、零 CDN（唯一例外：`/api/docs` 的 Swagger 样式表走 jsdelivr），断网可用。

## 装上就用

```bash
pip install log-ai-compressor==3.0.1   # PyPI 上就是 3.0.1（2026-11-20 发布），硬依赖只有 PyYAML 一个
```

| 你要做的事 | 命令 |
| --- | --- |
| 分析一份日志 | `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` |
| **试带 Caused by 链的样例** | `log-ai-compressor run examples/sample_system.log -f json` |
| **试 GBK 编码** | `log-ai-compressor run examples/sample_gbk.log -f summary` |
| **拿机器可读的 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` |
| **要界面**（拖拽 + 卡片 + 复核按钮） | 见上文[打开界面](#打开界面推荐入口)：`start.bat` 或 `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 缓存），之后每份小日志 0.19~0.25 秒；大文件流式处理，Python 堆峰值约 12 MB，不随文件增大。Windows 可双击 `start.bat` 自动装依赖并打开浏览器。

## 你不必相信这个工具

每条结论带原文行号区间 + sha256；`verify` 重读原文逐条核对，改一个字节就 `TAMPERED`。
我们撤回过一个复现不了的 91.4% 召回率，记录在 [FAQ Q10](docs/FAQ.md)。一个主动撤回招牌数字的项目，剩下的数字才有分量。

## 它会漏什么

二进制、混合编码、超长单行、没有 `trace_id` 的多服务日志、`--tail` 配管道等场景，实测边界见 [docs/LIMITS.md](docs/LIMITS.md)。

## 这些数字不能证明什么

不证明根因准确率高于云平台，不证明在所有日志上都赢 Drain3，不证明压缩比能外推到你的日志。完整边界见 [docs/LIMITS.md](docs/LIMITS.md)。

## 证据：十集全量 GA 88.68% vs Drain3 71.58%

| 数据集 | 标注事件 | 本项目(交付 top20) | **本项目(同预算 32k)** | 本项目(全量) | Drain3 | **LogsLop** | tail @32k | grep @32k |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| Proxifier | 11 | 90.9% | **90.9%** | 90.9% | 72.7% | **27.3%** | 63.6% | 45.5% |
| Apache | 29 | 65.5% | **100.0%** | 100.0% | 93.1% | **44.8%** | 27.6% | 34.5% |
| OpenSSH | 38 | 52.6% | **100.0%** | 100.0% | 92.1% | **34.2%** | 55.3% | 26.3% |
| Hadoop | 236 | 8.5% | **98.3%** | 98.3% | 80.5% | **13.1%** | 32.6% | 13.1% |
| Zookeeper | 89 | 22.5% | **75.3%** | 75.3% | 76.4% | **23.6%** | 79.8% | 9.0% |
| Linux | 338 | 4.7% | **77.2%** | 77.2% | 66.6% | **55.6%** | 3.6% | 3.6% |
| HealthApp | 156 | 12.8% | **82.1%** | 82.1% | 83.3% | **7.1%** | 32.1% | 3.8% |
| Mac | 626 | 3.2% | **77.2%** | 92.0% | 72.2% | **16.1%** | 24.8% | 5.1% |
| HPC | 74 | 20.3% | **73.0%** | 73.0% | 87.8% | **4.1%** | 1.4% | 4.1% |
| OpenStack | 48 | 39.6% | **75.0%** | 75.0% | 41.7% | **18.8%** | 20.8% | 8.3% |

> 三个口径：交付口径 **1 胜 9 负**；同预算 32k **7 胜 3 负**；全量口径 **7 胜 3 负**。同机同口径，不是全球榜单；CSV、分母、复现命令见 [docs/BENCHMARK.md](docs/BENCHMARK.md) 与 [docs/PROOF.md](docs/PROOF.md)。

### 换一把尺子：PA / GA

PA **85.05%** vs 58.06%（**+27.00pp**），GA **88.68%** vs 71.58%（**+17.10pp**）。**两个口径都胜**（逐数据集 **PA 10 胜 0 负**、GA 8 胜 2 负）。

## 工程指标（可对账）

| 指标 | 实测值 |
| --- | --- |
| 生产代码 | 10,950 行（36 个模块），硬依赖只有 PyYAML |
| 测试 | **2,431 用例**（2026-11-20 本机 Windows 实测：2,429 passed / 2 skipped / 0 failed），覆盖率 **94.15%**（漏行 312 / 5,332 语句） |
| CI | Ubuntu 3.11 / 3.12 / Windows 3.12 三矩阵，**十二道门禁**：ruff / 单测+覆盖率 / 对抗评分卡 / 确定性指纹 / 自证脚本 / 构建可复现性 / **变异存活率记分卡** / **SAST** / **依赖漏洞扫描** / **性能回归** / **产物审计** / **sdist 自测** |
| 自证脚本 | 现已断言 **11 条**主张；这里再复述一次：**11 条**主张，含「README 工程指标与架构树必须与仓库一致」「README 写的条数不许漂」「每一处基准表逐格对账实测基线」 |
| 依赖 | 运行时硬依赖只有 PyYAML 一个，全部 16 条声明依赖经 pip-audit 扫描无已知漏洞 |
| 隐私 | 本地分析不出本机；可选 AI 解读只发送脱敏后的片段（默认关闭、需显式同意） |
| CI 参考 run | run 40765275081，head 850550f2，结论 success（ubuntu-3.12 覆盖率出处） |

> 其中「5,332 语句」跨平台**必然相同**（它由源码静态解析决定），漏行数才随平台变。

> **覆盖率的分母比上面那行代码量小**：`pyproject.toml` 的 `[tool.coverage.run] omit` 排除了 `cli.py`（薄适配层，1,041 行，只做参数解析与格式分发）。所以**这个覆盖率**是在 9,909 行上算的，而「10,950 行生产代码」**含**它 —— 两个数字口径不同，别拿它们互推。

| 不能证明什么 | 实测边界 |
| --- | --- |
| 压缩比能外推到你的日志 | **20,509 倍是 OpenStack 全级别摘要的单集上限，不是通用承诺**：15,299,983 → 746 tokens ≈ 20,509 倍（15,299,983 ÷ 746）；换数据集、换 `--context`，数量级就变 |

## MCP（给 Agent 用）

`server.json` 已提交官方 Registry；Registry 上的条目落后于本地 3.0.1，**能不能装以 PyPI 为准**。
安装：`pip install "log-ai-compressor[mcp]" && log-ai-compressor mcp --install claude-code`。
Registry 验证 PyPI 包时抓的标记：

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

查证记录见 [docs/MCP.md](docs/MCP.md)。

## 🧰 能力

- **取证**：每条结论绑定 `evidence_id` + 文件 + 行号区间 + 原文 sha256；`verify` 改一个字节即 `TAMPERED`。
- **确定性**：同一份日志两次分析的指纹逐字节相同（耗时/速率已排除）；归档存指纹，不存报告文件。
- **置信三档**：`CONFIRMED` / `LIKELY` / `INSUFFICIENT`；`CONFIRMED` 必须能取出原文引用，取不到就降档并列出还缺什么。
- **解析与调用链**：ISO / syslog / logcat / logfmt / JSON Lines / 中式堆栈，UTF-8/GBK/UTF-16/32 + `.gz`/`.zip`；有 `trace_id` 时重建跨服务链路。
- **界面与 AI**：Web 界面零构建、离线可用；AI 解读可选，不配 Key 也能完整用。

完整清单与边界见 [`docs/FEATURES.md`](docs/FEATURES.md)。


## 能力边界

不做持续告警、不做 tracing、不比云平台根因准确率；这三条是有意取舍，不是没做完。
完整边界与“谁行”见 [docs/LIMITS.md](docs/LIMITS.md) 和 [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)。

## 🗂 深入

| 文档 | 里面有什么 |
| --- | --- |
| [`docs/BENCHMARK.md`](docs/BENCHMARK.md) | 全部实测的方法学、口径、公平性说明、两处落后的病因、撤回记录 |
| [`docs/REPRODUCIBILITY.md`](docs/REPRODUCIBILITY.md) | 工程指标、CI 门禁、run 出处与逐步复现 |
| [`docs/CLI.md`](docs/CLI.md) | 完整命令行用法 + 自定义解析规则 |
| [`docs/FAQ.md`](docs/FAQ.md) | 逐条回答质疑：「凭什么比 Drain3 强」「自信错误率是不是门槛设高了」… |
| [`docs/LIMITS.md`](docs/LIMITS.md) | 实测边界、它会漏什么、这些数字不能证明什么 |
| [`docs/security/INDEX.md`](docs/security/INDEX.md) | 每日安全台账：依赖漏洞 / 疑似密钥 / 危险调用，逐日可查 |

其余（架构 / 评测 / 定位 / 贡献 / Agent 契约）见 [`docs/`](docs/) 与 [`AGENTS.md`](AGENTS.md)。

**复现本文所有数字：**

```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
