别再让 AI 对着日志猜根因了。给它一个断点，让它自己去看现场。
GitHub：https://github.com/Aresxue/java-debug-skill
----------------------
痛点：AI 排查 Java 问题，大多数时候是在"猜"
线上一个接口偶发返回错误数据，你把代码和日志丢给 AI ，它给出三种"可能的原因"，但哪一个是真的，它也不知道。因为它看不到运行时：那一刻的入参是什么、走了哪个分支、某个字段到底是不是 null 。
Java 程序员排查这类问题的终极武器是断点调试。可让 AI 去用
jdb？输出是要解析的文本，要靠 tmux + sleep 去赌时序，命中后默认冻结整个 JVM ，这根本不是给 AI 设计的。java-debug 就是为这件事而生的：它是一个标准格式的 Agent Skill （
SKILL.md），Claude Code 、Codex 、Cursor 等支持 Skills 的 Agent 都能用。装上之后，AI 可以像你在 IDEA 里一样，连上远程 JVM 、打断点、等命中、看调用栈和局部变量、求值、单步，并且被要求只能基于实际采集到的运行时数据下结论。----------------------
一次调试长什么样
在已安装该 Skill 的 Agent 里，直接用自然语言发起即可：
帮我远程 debug 10.0.1.5:5005 ，源码在 /path/to/repo ，查一下订单查询为什么偶发返回空
支持斜杠命令的 Agent 也可以显式调用，例如 Claude Code 中：接下来 AI 会自己完成整个闭环：/java-debug 10.0.1.5:5005 --repo /path/to/repo。 可选参数：--bp预设断点（可重复）、--repo本地源码路径、--max-bp每轮最多断点数、--wait-timeout等待命中的秒数、--manual只生成命令清单。
1. 读代码，定位请求入口和可疑路径
2. 给出断点计划，等你确认（你用
--bp 亲自指定的断点视为已确认；之后新增的断点仍需确认）3. 连接 JVM 并设置断点
4. 提示你触发请求，阻塞等待命中
5. 采集现场：调用栈、局部变量、表达式求值、单步执行
6. disconnect，被冻结的线程全部恢复
7. 输出结论：执行路径、变量快照、根因、修复建议
----------------------
为什么不直接用 jdb
核心是自研的 JDI 客户端：只依赖 JDK 内置的
com.sun.jdi，零外部依赖，以常驻 HTTP 服务模式运行，所有操作都是一条 JSON 命令，curl 即可驱动。不绑定任何 Agent 。----------------------
亮点能力
● 断点不漏装：方法入口断点、行断点；类还没加载时自动转为延迟断点；重载方法、同一行的多个可执行位置（含 lambda ）都会装上
● 多 ClassLoader / 热部署：同名类的所有已加载副本都装断点，之后加载的副本自动补装；某个副本装不上时会给出原因
● 表达式求值（相当于 IDEA 的 Evaluate Expression ）：局部变量、字段访问、实例方法、链式调用、静态方法 / 静态字段
● 单步执行：
over / into / out，响应自动带上新位置的栈和局部变量● 命中不跑业务代码：对象按字段展开，从不自动调用
toString()● 无法直连时（
--manual）：生成一份命令清单，在目标机或跳板机上执行后把输出贴回来分析更多能力（并发命中隔离、断线重连、错误码、JDK 8 / 9+ 兼容性等）见 README。
----------------------
安全：先说清楚风险
远程调试本身是高危操作：JDWP 没有认证，能连上就能执行任意代码。java-debug 尽量把边界做成硬约束，但它降低的是风险，不是消除风险。
客户端强制的防护（写在代码里）
● 命令端口只绑定
127.0.0.1，没有开关能对外开放；校验 Host 头、拒绝带 Origin 的请求，挡掉浏览器跨站和 DNS rebinding● 客户端最多保留 64 个命中现场，超出后新命中直接放行并提示
dropped_events●
eval 内置硬拒绝名单：System.exit、Runtime.exit / halt / exec、ProcessBuilder.start、Thread.stop / suspend●
disconnect 后目标 JVM 中所有被冻结的线程自动恢复Skill 工作流规则（要求 Agent 遵守）
● 断点计划必须先经你确认；无论正常结束、失败还是被打断，都必须 disconnect
● 禁止 eval 有副作用的方法（写库、发 MQ 、改状态、清缓存）
● 认证、支付、隐私相关的敏感数据（ token 、身份证号、银行卡号、密码）不得原样贴进对话或结论
⚠️ 使用边界，务必读完
● 只冻结命中线程 ≠ 不影响服务：被冻结的线程如果持有锁、数据库连接或连接池槽位，争用同一资源的线程会一起卡住，影响可能扩散到整个服务。
● 64 只限制客户端保留的现场数，不限制目标 JVM 同时被挂起的线程数：热路径上的断点遇到并发命中，会瞬间挂起大量线程。
● 超时不会自动恢复线程：wait-breakpoint/step超时后，要按frozen_threads逐一resume，或直接disconnect兜底。
● 拒绝名单只防手滑，不是沙箱，其他有副作用的方法仍然可以调用。
● 生产环境：断点放在冷路径、无锁的位置，尽快 resume ； JDWP 端口必须只对内网 IP 白名单开放，或者走 SSH 隧道。
----------------------
快速开始