Skip to content
Skills Library
Programming · Analysis

java-log-diagnoser

/java-log-diagnoser

诊断 Java 应用报错日志并输出结构化诊断报告。当用户粘贴 Java 异常堆栈、GC/OOM 日志,或出现 NullPointerException、OutOfMemoryError、StackOverflowError、ClassNotFoundException、NoClassDefFoundError、NoSuchMethodError、BeanCreationException、UnsatisfiedDependencyException、SQLException、HikariPool、Connection refused、Address already in use、依赖冲突、启动失败、接口 500、线上报错等关键词,或说"帮我看看这段报错""定位一下这个异常""为什么启动失败"时使用。输出包含事实证据、根因假设、验证命令与修复建议的 Markdown 报告。

Licence
MIT
Last repository change
01.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

诊断 Java 应用报错日志并输出结构化诊断报告。当用户粘贴 Java 异常堆栈、GC/OOM 日志,或出现 NullPointerException、OutOfMemoryError、StackOverflowError、ClassNotFoundException、NoClassDefFoundError、NoSuchMethodError、BeanCreationException、UnsatisfiedDependencyException、SQLException、HikariPool、Connection refused、Address already in use、依赖冲突、启动失败、接口 500、线上报错等关键词,或说"帮我看看这段报错""定位一下这个异常""为什么启动失败"时使用。输出包含事实证据、根因假设、验证命令与修复建议的 Markdown 报告。

Triggers from the description

帮我看看这段报错定位一下这个异常为什么启动失败
Original author description

诊断 Java 应用报错日志并输出结构化诊断报告。当用户粘贴 Java 异常堆栈、GC/OOM 日志,或出现 NullPointerException、OutOfMemoryError、StackOverflowError、ClassNotFoundException、NoClassDefFoundError、NoSuchMethodError、BeanCreationException、UnsatisfiedDependencyException、SQLException、HikariPool、Connection refused、Address already in use、依赖冲突、启动失败、接口 500、线上报错等关键词,或说"帮我看看这段报错""定位一下这个异常""为什么启动失败"时使用。输出包含事实证据、根因假设、验证命令与修复建议的 Markdown 报告。

How it works

  1. 0. 🚫 绝对红线(Zero-Tolerance Rules)
  2. 1. 何时使用
  3. 2. 何时不使用
  4. 3. 文件职责与加载时机(渐进式加载)
  5. 4. 工作流(严格按顺序,禁止跳步)
  6. 5. 强约束(违反任意一条,本次输出即视为失败)
  7. 6. 提交前自检
  8. 7. 失败与降级
Original SKILL.md headings · 191 lines, 893 words
SKILL.md preview
---
name: java-log-diagnoser
description: 诊断 Java 应用报错日志并输出结构化诊断报告。当用户粘贴 Java 异常堆栈、GC/OOM 日志,或出现 NullPointerException、OutOfMemoryError、StackOverflowError、ClassNotFoundException、NoClassDefFoundError、NoSuchMethodError、BeanCreationException、UnsatisfiedDependencyException、SQLException、HikariPool、Connection refused、Address already in use、依赖冲突、启动失败、接口 500、线上报错等关键词,或说"帮我看看这段报错""定位一下这个异常""为什么启动失败"时使用。输出包含事实证据、根因假设、验证命令与修复建议的 Markdown 报告。
---

# Java 日志诊断

把一段 Java 日志变成一份可执行、可追溯的诊断报告。目标不是"解释异常是什么",
而是回答四个问题:**哪一行代码出错、为什么错、怎么验证、怎么修**。

## 0. 🚫 绝对红线(Zero-Tolerance Rules)

> 本节优先于全文。与"先给个结论""日志太少先猜一个""用户等着要答案"冲突时,以本节为准。
> 违反任意一条,本次输出即作废——从 Step 1 重新走,不要在原文上道歉打补丁。

| 编号 | 红线 | 判定标准 | 违反后果 |
| --- | --- | --- | --- |
| **R1** | 禁止编造日志中不存在的类名、方法名、`Foo.java:nn`、`L<n>`、全限定类名、异常类型 | 提到的每个名字,必须在同一份日志或 `parsed.json` 里**逐字**出现 | 硬校验非 0 退出 → 报告不得交付 |
| **R2** | 必须区分"日志事实"和"推测假设" | 每句结论标 `[事实]` 或 `[推测]`;`[事实]` 必须挂 `E<n>` 且背后是逐字原文;`[推测]` 必须附验证方法,且不得单独支撑结论 | 该段结论作废重写 |
| **R3** | 信息不足必须拒诊,不许硬编 | 缺堆栈 / 缺 `Caused by` / 缺版本 / 只有一行异常消息 → 第一行写 **【信息不足,拒绝盲目诊断】**,并列出 **3 个具体问题**(具体到文件、命令、字段) | 报告作废,改走降级模板 |

**一句话判据**:这句话能不能指到日志里具体的那一行?指不到就只能放 `[推测]`,且不许用它支撑最终结论。

配套两道硬规矩(同样按红线处理):

- 业务帧缺失(`first_business_frame` / `root_business_frame` 均为 null)时,用专用标记
  **【业务包信息缺失,无法定位具体代码行】**——它与 R3 同属拒诊,同样必须列 3 个具体问题,同样禁止输出根因假设与修复建议。
- **硬校验报错时只能改报告**。改脚本放宽规则、用 `|| true` 吞掉退出码、删掉 `Foo.java:52` 却保留"第 52 行未判空"的结论,都属规避红线,按违反处理。

## 1. 何时使用

- 用户粘贴了 Java 堆栈、异常信息、`Caused by` 链、GC 日志、容器/进程退出日志
- 关键词命中:`NullPointerException`、`OutOfMemoryError`、`StackOverflowError`、`ClassNotFoundException`、`NoClassDefFoundError`、`NoSuchMethodError`、`BeanCreationException`、`Connection refused`、`Address already in use`、`HikariPool`、`Deadlock`、`依赖冲突`、`启动失败`、`线上报错`、`接口 500`
- 用户要求"排查 / 定位 / 分析 / 看下这段日志"

## 2. 何时不使用

- 非 Java 技术栈日志(Go / Python / Node)——直接分析,不要套用本流程
- 纯 API 用法、语法、框架特性咨询
- 需要登录生产机器执行变更(重启、回滚、改配置、kill 进程)——超出只读边界,转人工
- 用户只要求翻译或摘要日志,不需要根因

## 3. 文件职责与加载时机(渐进式加载)

| 路径 | 角色 | 何时加载 |
| --- | --- | --- |
| `SKILL.md` | 骨架:三条红线、流程、边界、强约束 | 始终 |
| `scripts/parse_java_log.py` | 事实抽取:Caused by 链、OOM 类型、首个业务帧 | Step 2,必跑 |
| `prompts/extract_root_cause.md` | 根因分析模板(红牌 + 证据链闭环 + 八问自审) | Step 3.2 |
| `prompts/generate_report.md` | 报告结构与措辞规范 | Step 4.1 |
| `scripts/validate_diagnosis.py` | 硬校验:类名/行号/证据引用是否真在日志里 | Step 4.2,**必跑** |
| `prompts/validate_report.md` | 报告审查模板(可选第二关卡) | Step 5,需归档/含变更建议/用户要求复核时 |
| `references/java-exceptions.md` | 异常知识库(按 `primary_signals` 命中节加载) | Step 3.1 |
| `references/safe-commands.md` | 只读排查命令白名单 | Step 3.2 / 4.1 需要验证命令时 |
| `examples/*.md` + `examples/reports/*.md` | 8 个完整样例(含 2 份拒诊、1 份无业务帧) | 需要对齐输出格式时,只看 1 个同类型的 |

**渐进式加载原则**:一次只读一个文件的一节。不要为"全面"把 `references/` 全量塞进上下文——它会让报告变长而不是变准。

## 4. 工作流(严格按顺序,禁止跳步)

| Step | 名称 | 输入 → 产出 | 门禁 |
| --- | --- | --- | --- |
| 1 | 预处理 | 原始日志 → 类型判断、边界、脱敏后的日志 | 信息是否足够(不足直接拒诊) |
| 2 | 脚本解析 | 日志 → `parsed.json` | **禁止跳过**(无 Python 才允许降级) |
| 3 | 结合模板分析 | `parsed.json` + 知识 → 证据表 + 假设 + `SELF_CHECK` | 自审不过不得进 Step 4 |
| 4 | 输出与自动拦截 | 分析 + 日志 → 报告 → 硬校验 | **`validate_diagnosis.py` 非 0 退出不得交付** |
| 5 | 报告审查(可选) | 报告 → `REVIEW: PASS` / `FAIL` | 两轮不过就降级 |

上一步没有产出,就不要进入下一步。**Step 2 没跑脚本、Step 4.2 没跑硬校验的报告,不算"质量差一点",算没做完。**

### Step 1 预处理(在心里完成,不作为输出)

- **类型判断**:启动失败 / 运行时报错 / OOM 被杀 / 请求超时 / 定时任务失败——排查方向完全不同。
- **找边界**:日志是否截断?只有 `Caused by` 没有 `at`、`... 23 more`、`[truncated]` 都说明信息不全。
- **脱敏**:密码、token、AK/SK、手机号、身份证、内网 IP、连接串凭据替换为 `<REDACTED>`,保留字段结构。
- **判够不够**:缺堆栈、缺版本、缺关键配置时,直接走 Step 4.1 的拒诊分支,不在 Step 2/3 用通用建议或低置信度假设凑数。

### Step 2 脚本解析(结构化抽取,禁止跳过)

把日志**原样**交给脚本,不要先自己读一遍再转述——转述就是幻觉入口。产物 `parsed.json`:异常类型/消息、`Caused by` 层级、业务帧 `Xxx.java:nn` 都在里面,后面所有引用只从它取。

```bash
python3 scripts/parse_java_log.py --file app.log --app-package com.yourcompany --pretty > parsed.json
# 或管道输入:cat app.log | python3 scripts/parse_java_log.py --pretty
```

规则:

- **脚本输出是唯一事实来源**。异常类型、消息、行号、`Caused by` 层级、业务帧一律从 `parsed.json` 取。
- **区分信号归属**。`signals[]` 是全文扫描结果,无关错误也会命中。`in_primary_chain=true` 的才能支撑根因;`false` 的(即 `summary.noise_signals`)写进"已排除"。
- **`frame_count=0` 必须降级**:异常只有消息没有堆栈时脚本无从定位代码行,走拒诊分支。
- 日志超 200000 行先 `tail -n 200000`,报告注明只分析尾部。
- 脚本跑不了 → 降级:手工沿 `Caused by` 阅读,注明"脚本未运行",置信度上限压到"中"。
- 业务帧识别不准时,请用户给 `--app-package`,不要猜。

### Step 3 结合模板分析

**3.1 按需加载知识**:依据 `summary.root_cause_type` / `summary.oom_kind` / `summary.primary_signals`(**用 primary,不用 noise**)决定读 `references/java-exceptions.md` 哪几节;需要时读 `references/safe-commands.md` 取只读命令;对齐格式看 `examples/` 同类型一个。

**3.2 生成假设**:以 `prompts/extract_root_cause.md` 为系统指令,输入 = 脱敏日志 + `parsed.json` + 命中知识。按模板填出 **证据表 + 1–3 个假设 + `SELF_CHECK`**:

- 每条判断挂一条 `E<n>`,背后是**逐字原文 + `L` 号**;
- 每条假设写 `- 引用: E<n>`、`推理链`、`反证`、`verify`;引用不到 E 不许写;
- 无业务帧时只允许输出 `【业务包信息缺失,无法定位具体代码行】`,禁止猜代码行;
- 结尾给 `SELF_CHECK: PASS` 或 `PASS_WITH_GAPS`。

**不要先写假设再去知识库找支持**——那是先定结论再凑证据,结论不可信。

### Step 4 输出与自动拦截(硬门禁)

**4.1 生成报告**:以 `prompts/generate_report.md` 为系统指令,报告必须含:结论摘要 / 关键证据(逐字原文+行号+`E` 编号)/ 根因假设(含置信度与验证步骤)/ 修复建议(分止血与根治)/ 分析边界与信息缺口。
**入口门禁**:`SELF_CHECK` 非 `PASS`/`PASS_WITH_GAPS`,或报告以拒诊标记开头时,改用降级模板,不得凭空生成假设与修复建议。

#### 4.2 强制硬校验(非 0 退出不得交付)

报告写完**先跑脚本再交付**,文字约束拦不住模型,这一关用字符串级比对把幻觉钉死。**报告每改一版就重跑一次**,不能只在最后跑一遍。

```bash
python3 scripts/validate_diagnosis.py --log app.log --report report.md --parsed parsed.json
# 退出码:0 通过 / 1 有错误 / 2 无法执行(文件缺失、日志为空)
```

| 退出码 | 含义 | 必须做什么 |
| --- | --- | --- |
| 0 | 通过 | 进入 Step 5 或交付 |
| 1 | 报告有幻觉或引用对不上 | 按输出「报告第 N 行 + 修法」逐条改,改完**重跑**;最多两轮,两轮仍有 V1/V5 就走降级模板 |
| 2 | 无法执行 | 先修输入;确认跑不了,在"分析边界"写明未校验,置信度上限"中" |

它只查**可判定**的五件事(每条都指出报告第几行、怎么改):

| 编号 | 查什么 |
| --- | --- |
| V1 | `Foo.java:52` 必须在日志(或 `parsed.json`)有同名同号的帧 |
| V2 | **断言语境**下提到的异常类名必须真实出现在日志里 |
| V3 | `L<n>` 必须落在 `1..日志总行数` 内,且该行非空 |
| V4 | 证据表里的"逐字原文"必须与该行日志完全一致 |
| V5 | `com.x.Y` 形式类名必须能在日志中找到(支持 `c.a.o.c.X` 缩写还原) |

规则细节:

- **失败就改报告,不要改脚本、不要删校验步骤**。按「修法」逐条修正,最多两轮;两轮仍有 V1/V5 说明那些名字本来是猜的,删掉或走降级模板。
- **不要为过校验把行号删掉却保留结论**。"`OrderAssembler.java:52` 附近"改成"`OrderAssembler` 附近"可以;把"第 52 行未判空"改成"某处未判空"但继续断言,是更隐蔽的编造。
- **`L<n>` 与 `Foo.java:nn` 是两套编号**:前者是日志物理行号,后者是源码位置,不能互相换算。
- **否定与假设语境不算幻觉**:"日志无 `SQLException`""若是依赖没打进包,异常会是 `NoClassDefFoundError`"允许,脚本会跳过记为提示;但同一名字若又在别处被当事实断言,照样报错。
- **没有 Python 环境**时必须在"分析边界"写明"未跑硬校验,类名与行号未经机器核对",置信度上限"中"。

### Step 5 报告审查(可选关卡)

先跑完 Step 4.2。机器能判定的事(类名、行号、引用是否逐字一致)不占审查轮次,否则审查员会把注意力花在"查字符串"上,反而放过"证据撑不撑得起结论"。

以 `prompts/validate_report.md` 为系统指令,输入 = 报告 + 同一份日志 + 同一份 `parsed.json`。审查员只判定、只定位,**不重写报告**。三条硬性打回条件:幽灵事实 / 绝对化措辞 / 缺"需补充的信息"。输出以 `【审查通过】` 或 `【审查失败及修改意见】` 开头,单独一行 `REVIEW: PASS` / `REVIEW: FAIL`。`FAIL` 最多再改两轮;两轮仍 `FAIL` 就降级。

**这道关卡默认关闭**:日常一次性问答不必多绕一圈。报告要进复盘/工单归档、含变更建议、或信息不全却仍要出结论时,再主动开启。审查结论附在报告之后,不替换报告。

## 5. 强约束(违反任意一条,本次输出即视为失败)

1. **不编造**(§0 R1):行号、类名、方法名、异常消息、依赖版本一律来自日志或 `parsed.json`,没有就写"日志未提供"。
2. **事实与推测分离**(§0 R2):每条结论标 `[事实]`/`[推测]`,推测必须附验证方法;指不到逐字引用的结论不许写。
3. **命令只读**:只用 `references/safe-commands.md` 白名单命令;`kill -9`、`rm`、`DROP/TRUNCATE`、落盘 dump、改配置、重启只能写成"建议由值班同学在变更窗口执行",不给一键粘贴命令。
4. **占位符化**:PID/路径/主机名用 `<PID>`、`</path/to/app.log>` 占位并说明取值方式。
5. **不臆断根因**:日志只有 `Connection refused` 时不得断言"数据库挂了",必须写成假设 + 验证命令。
6. **假设 1–3 个**,按可能性降序,每个必须有可执行的验证步骤。
7. **信息不足明说**:第一行写 **【信息不足,拒绝盲目诊断】** 并给 **3 个具体问题**(§0 R3),不用泛泛建议填充。
8. **脱敏**:输出不得出现明文密码、token、AK/SK、完整连接串、身份证、手机号。
9. **中文输出**,技术名词保留英文原名(置信度取值 `high/medium/low`,报告中展示为 高/中/低)。
10. **自审不过不交付**:Step 3.2 必须输出八问自审与 `SELF_CHECK`;任一不过先修正或降级。
11. **审查只判定不改写**:开启 Step 5 时,审查员输出结论与修改意见,不写新版报告;两轮不过降级。
12. **机器校验必须跑**(§4.2):有 Python 时交付前必过 `scripts/validate_diagnosis.py`,每改一版重跑;它报错的类名/`Foo.java:nn`/`L<n>`/证据原文,只有"修正"或"删除"两选项。

## 6. 提交前自检

- [ ] 报告里每个行号、类名、方法名、源文件名,日志或 `parsed.json` 里都有?
- [ ] `scripts/validate_diagnosis.py` 已通过(或已在"分析边界"注明未运行及原因)?
- [ ] 有没有"肯定是""根本原因就是""显然"这类超出证据强度的措辞?
- [ ] 信息不足时,第一行是不是 **【信息不足,拒绝盲目诊断】**,且列了 3 个具体问题(具体到文件/命令/字段)?
- [ ] 每个假设都配了验证步骤?`[事实]`/`[推测]` 是否逐条标注?
- [ ] 有没有白名单外命令?可一键执行的破坏性操作?
- [ ] 敏感信息是否已脱敏?占位符是否说明取值方式?
- [ ] 是否写清了"分析边界"(日志截断、脚本未运行、只分析尾部 N 行)?

## 7. 失败与降级

| 情况 | 处理 |
| --- | --- |
| 日志只有一行异常,无堆栈 | 输出 **【信息不足,拒绝盲目诊断】**,列 3 个具体问题(完整堆栈、框架/依赖版本、触发场景),禁止给假设与修复建议 |
| 脚本运行失败 | 手工解析,报告注明降级,置信度最高"中" |
| 硬校验 exit=1 | 按提示逐条改报告后重跑;最多两轮,两轮仍红走降级模板 |
| 硬校验 exit=2 | 先修输入再跑;确实跑不了注明"未校验",置信度上限"中" |
| 硬校验 V1/V5 | 删掉行号/类名改成可回溯表述;整段依赖它就连结论一起删 |
| 硬校验 V2 | 回日志确认;确实没有就写"日志未出现该异常"并删掉基于它的推断 |
| 硬校验 V3/V4 | 回日志复制原文,不许手改字、不许同义改写绕过 |
| 环境没有 Python | 注明"未跑硬校验",置信度上限"中" |
| 根因在第三方库内部 | 给"绕行 + 升级/替换建议",不下"库有 bug"断论 |
| 用户要求直接改生产 | 拒绝,给变更评审清单 |
Files in this package (5)
  • .gitattributes 1 KB
  • .gitignore 1 KB
  • LICENSE 1 KB
  • README.md 17 KB
  • SKILL.md 16 KB

Versions

The database has no other skills named java-log-diagnoser.

Database snapshot: 13.11.2026 · package version 52fbb3c09e86 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90Java
    Writes, debugs, and tunes Java and the JVM: nulls, equality, collections, generics, concurrency, streams, memory, builds, and upgrades. Use when Java throws NullPointerException, ClassCastException, ConcurrentModificationException, NoClassDefFoundError, NoSuchMethodError,…
  • 96java
    Guidelines for building Java base applications Triggers on: **/*.java
  • 100flaky-test-diagnoser
    Systematically diagnoses why a test is flaky by running multi-run experiments, isolation tests, ordering permutations, and timing analysis. Use when the user says a test is flaky, intermittent, non-deterministic, randomly failing, passes sometimes, or asks to debug test flakiness.
  • 90pulse
    Use when profiling a Java project's memory/GC behavior, diagnosing an OutOfMemoryError or GC pauses, or tuning JVM heap/collector settings. Captures GC+JFR telemetry (local launch, attached to an already-running JVM, or inside a container) and produces a shareable static HTML report.
  • 95java-11-to-java-17-upgrade
    Comprehensive best practices for adopting new Java 17 features since the release of Java 11. Triggers on: ["*"]
  • 92write-script-java
    MUST use when writing Java scripts.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.