log-reducer

日志精简器

你的 AI 编码 Agent 正在花费数千个令牌读取原始日志——DEBUG 噪声、健康检查、重复行、框架堆栈帧、UUID。这些令牌在本次会话的剩余时间里都无法再用。Agent 思考的空间更少，生成的代码更差，也会更快达到上下文限制。

日志精简器介于日志和 AI 之间。它会将文件精简为关键信息——错误、警告、状态变更、唯一事件——通常可减少 70-90% 的令牌。原始日志永远不会进入 AI 的上下文。

它可以作为 MCP 服务运行（AI 使用文件路径调用 reduce_log），也可以作为 CLI 运行（将任意日志通过管道传入）。无需 API 密钥，无网络请求——确定性的文本转换，可即时运行。

示例

你正在运行 FastAPI 开发服务器。你四处点击，遇到一个 500 错误，然后将终端输出复制 到文件中。文件有 218 行——大多是满屏的框架堆栈跟踪：

218 lines, 1185 tokens  →  51 lines, 310 tokens  (74% reduction)

下面是工具对堆栈跟踪的处理结果。这是一个真实的 Python 异常组， 其中包含 uvicorn、starlette 和 FastAPI 的帧：

处理前 — 95 行堆栈跟踪，包含完整的 C:\Users\...\.venv\Lib\site-packages\ 路径：

    |   File "C:\Users\imank\projects\video-editor\src\backend\.venv\Lib\site-packages\
             uvicorn\protocols\http\httptools_impl.py", line 426, in run_asgi
    |     result = await app(  # type: ignore[func-returns-value]
    |              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |   File "C:\Users\imank\projects\video-editor\src\backend\.venv\Lib\site-packages\
             uvicorn\middleware\proxy_headers.py", line 84, in __call__
    |     return await self.app(scope, receive, send)
    |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ... 85 more framework lines ...
    |   File "C:\Users\imank\projects\video-editor\src\backend\app\routers\exports.py",
             line 745, in list_unacknowledged_exports

处理后 — 保留你的代码，折叠框架帧，移除重复的回溯：

    |   [... 10 framework frames (uvicorn, fastapi, starlette, contextlib) omitted ...]
    |   File "app/middleware/db_sync.py", line 107, in dispatch
    |     response = await call_next(request)
    |   [... 6 framework frames (starlette, contextlib) omitted ...]
    |   File "app/main.py", line 97, in dispatch
    |     response = await call_next(request)
    |   [... 16 framework frames (starlette, fastapi) omitted ...]
    |   File "app/routers/exports.py", line 745, in list_unacknowledged_exports
    |     exports=[
    |   File "app/routers/exports.py", line 746, in <listcomp>
    |     ExportJobResponse(
    | pydantic_core._pydantic_core.ValidationError: 1 validation error for ExportJobResponse
    | project_id
    |   Input should be a valid integer [type=int_type, input_value=None, input_type=NoneType]

Traceback (most recent call last):
  [... duplicate traceback omitted ...]

问题一目了然：exports.py:745 将 project_id=None 传给了一个要求整数的 Pydantic 模型。只有三个框架帧，而不是 95 个。没有 C:\Users\...\.venv\ 路径。

（完整的处理前后对比 | 更大型日志的漏斗模式工作原理）

设置

步骤 1 — 安装

npm install -g logreducer

步骤 2 — 将 MCP 服务添加到项目中

在项目根目录中运行：

claude mcp add logreducer -s project -- npx -y logreducer --mcp

这会将配置写入 .mcp.json（Claude Code 读取的文件）。也可以手动添加：

{
  "mcpServers": {
    "logreducer": {
      "command": "npx",
      "args": ["-y", "logreducer", "--mcp"]
    }
  }
}

步骤 3 — 添加 AI 指令

告诉 Claude Code：“按照 https://github.com/launch-it-labs/log-reducer/blob/master/docs/agent-integration.md 中的集成指南操作”——它会将正确的指令添加到你的 CLAUDE.md，并设置 /logdump 斜杠命令。

验证是否成功：“你有哪些 MCP 工具？”——应该会列出 reduce_log。

就这样。现在，你的 AI Agent 会自动精简日志，而不是直接读取原始日志。

使用方法

设置完成后，你无需学习任何命令或参数——AI 会自动处理一切。只需了解两件事：

与 AI 分享日志

将日志复制到剪贴板，然后在聊天中输入 /logdump。 原始日志会保存到临时文件并自动精简——永远不会进入 AI 的上下文。这是分享日志的推荐方式。

你也可以让 AI 查看某个文件：“检查 /var/log/app.log 中的错误”——它会对该文件调用 reduce_log，而不是直接读取原始内容。

CLI（用于脚本和管道）

你也可以在 AI 会话之外直接通过命令行使用：

logreducer < app.log > reduced.log
kubectl logs my-pod | logreducer
logreducer --level error --context 10 < app.log

工作原理

以下内容是为感兴趣的读者准备的——使用日志精简器不需要了解这些。

它如何处理你的日志

影响最大者优先：

• 过滤噪声 — 移除健康检查、心跳和进度条（保留 DEBUG/TRACE 行 — AI 可通过 level 过滤器选择何时排除它们）
• 折叠堆栈跟踪 — 80 个栈帧 → 你的代码栈帧 + [... N framework frames omitted ...]
• 合并重复行 — 6 行相似内容 → 一个模板，并列出变化值
• 提取日志前缀 — 8 行共享 timestamp - module - LEVEL → 1 个标题 + 缩进后的消息
• 检测重复块 — 5 个相同的 3 行块 → 1 个块 + 次数
• 缩短 ID — UUID、十六进制字符串、JWT、令牌 → $1、$2、...
• 简化时间戳 — 2024-01-15T14:32:01.123Z → 14:32:01
• 折叠测试输出 — 连续的 PASS 行 → 计数摘要；始终保留 FAIL 行
• 领域专用处理 — pip 安装、Docker 层、HTTP 访问日志、重试块、日志封装各有专用折叠器

按顺序应用 19 种转换。基于规则且结果确定，无需 API 调用。仅依赖一个依赖项（@modelcontextprotocol/sdk）。可选的 query 参数使用 Claude 进行定向提取（需要 ANTHROPIC_API_KEY）。

[x7] [CacheWarming] Warmed tail of large video ({N}MB) | N = 2574, 3139, 2897, 3063, 2490, 2996, 3043

多轮调查

这个工具不只是一次性缩减器。它支持一种漏斗模式，让 AI 通过多次定向处理来调查大型日志文件 — 总共只需约 1,000 个令牌，而盲目转储则需要 5,000 个以上。AI 会自动完成这些操作，以下是其内部处理过程：

Step 1: SURVEY → reduce_log({ file, tail: 2000 })           ~50 tokens
  If the reduced output exceeds the threshold (default: 1000 tokens),
  the tool automatically returns an enhanced summary instead of the full
  output: unique errors/warnings with counts, time span, and components.

Step 2: SCAN   → level: "error", limit: 3                   ~200 tokens
  See first 3 errors with context. Note timestamps.

Step 3: ZOOM   → time_range: "13:02:28-13:02:35", before: 50  ~500 tokens
  50 lines leading up to the first error — the causal chain.

Step 4: TRACE  → grep: "pool|conn", time_range: "13:00-13:05",  ~300 tokens
                  limit: 15, context: 0
  Follow the connection pool thread.

总计：约 1,050 个令牌。Agent 找到了根本原因（批处理作业导致连接池耗尽），而且从未加载完整日志。

完整的参数参考和过滤器详情，请参阅 docs/agent-integration.md。

设计决策

• 文件路径工作流 — MCP 工具接受文件路径，因此原始日志不会进入 AI 的上下文。只有缩减后的输出会进入对话。
• 优先减少令牌而非行数 — 统计信息以令牌而非行数报告，因为这才是 AI 上下文窗口真正关注的指标。
• 优先考虑通用性而非覆盖率 — 新转换会根据适用范围进行评分。只对某个应用程序的日志有帮助的模式会被标记为偏差风险并跳过，即使它能改善该特定场景。
• 转换顺序很重要 — 在去重前缩短 ID 和时间戳，这样仅这些值不同的行就会变得相同。在提取前缀前过滤噪声，避免分隔行打断分组。
• 每种转换彼此独立 — 输入纯函数，输出字符串。添加、测试和调整顺序都很容易，无需改动管线的其余部分。
• 尽量减少依赖项 — 纯 TypeScript，仅有一个运行时依赖项（@modelcontextprotocol/sdk）。

贡献

最简单的贡献方式是粘贴日志文件。 在 Claude Code 中打开此项目，将日志粘贴到聊天中，AI 就会分析日志、找出流水线遗漏的模式、实现通用性强的修复，并创建 PR。无需了解代码——你的日志会成为测试样例，让这个工具对所有人都更好用。

如果你不使用 Claude Code，也可以通过 GitHub issue 提交日志。

如需贡献代码，请参阅 CONTRIBUTING.md。

许可证

MIT