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 报告。
- Author
- TrieTulip ↗
- Repository
- java-log-diagnoser ↗
- Licence
- MIT
- Last repository change
- 01.11.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 01.11.2026, without references to retired models or APIs.
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
- 0. 🚫 绝对红线(Zero-Tolerance Rules)
- 1. 何时使用
- 2. 何时不使用
- 3. 文件职责与加载时机(渐进式加载)
- 4. 工作流(严格按顺序,禁止跳步)
- 5. 强约束(违反任意一条,本次输出即视为失败)
- 6. 提交前自检
- 7. 失败与降级
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.