让 AI 真正"打断点"： Java -debug，一个通用的 Java 远程调试 Agent Skill

别再让 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 中：/java-debug 10.0.1.5:5005 --repo /path/to/repo。可选参数：--bp 预设断点（可重复）、--repo 本地源码路径、--max-bp 每轮最多断点数、--wait-timeout 等待命中的秒数、--manual 只生成命令清单。

接下来 AI 会自己完成整个闭环：

读代码，定位请求入口和可疑路径
给出断点计划，等你确认（你用 --bp 亲自指定的断点视为已确认；之后新增的断点仍需确认）
连接 JVM 并设置断点
提示你触发请求，阻塞等待命中
采集现场：调用栈、局部变量、表达式求值、单步执行
disconnect，被冻结的线程全部恢复
输出结论：执行路径、变量快照、根因、修复建议

为什么不直接用 jdb

维度	jdb	java-debug
挂起范围	`SUSPEND_ALL`，命中即冻结整个 JVM	`SUSPEND_EVENT_THREAD`，只冻结命中的那个线程
交互方式	文本输出，需要解析；依赖 tmux + sleep 抢时序	结构化 JSON 请求/响应，无 tmux 、无 sleep 竞态
命中信息	需要逐条敲 `where` / `locals`	命中响应自动携带调用栈 + 局部变量
等待方式	轮询	事件驱动的阻塞等待（`wait-breakpoint`），带超时
流程约束	无	内置工作流：断点计划先经用户确认，结束必须 disconnect ，结论只能基于实际观测

核心是自研的 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 隧道。

快速开始

前置条件：本机有 Node.js （用于 npx）和 JDK （首次运行时构建客户端 jar ，只有 JRE 不行）。建议先在本地或预发环境跑通一次。

1. 全局安装 Skill （推荐）

把 -a 换成你使用的 Agent （可重复指定多个；不加 -a 则交互选择）：

# 例：一次装给 Claude Code 、Codex 、Cursor
npx skills add https://github.com/Aresxue/java-debug-skill --skill java-debug -g -a claude-code -a codex -a cursor

只想装到当前项目、随项目提交给团队，去掉 -g 即可：

npx skills add https://github.com/Aresxue/java-debug-skill --skill java-debug -a codex

首次运行时，Skill 会用本地 JDK 自动构建客户端 jar （有 Maven 用 Maven ，没有就降级用 javac）。

2. 目标 JVM 开启 JDWP

⚠️ 生产环境禁止把 JDWP 端口暴露到公网，只能对内网 IP 白名单开放，或通过 ssh -L 隧道访问。

# JDK 9+（ zsh 下整个参数要加引号）
java "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" -jar app.jar
# JDK 8
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar app.jar

已经在运行的进程不能临时加 JDWP ，必须带参数重启。目标类需要带 -g 编译才能看局部变量：Maven / Gradle 默认满足，用 -g:none 或部分优化流程构建的产物不满足。

3. 在 Agent 里发起调试

帮我远程 debug 10.0.1.5:5005 ，源码在 /path/to/repo ，断点打在 com.example.OrderService.query

写在最后

AI 写代码已经很熟练了，但排查问题时，它缺的往往不是推理能力，而是眼睛。java-debug 想做的，就是把 Java 程序员最趁手的那件工具（断点调试）交到 AI 手里，并且用工程化的方式把它管住。

找一个开了 JDWP 的本地或预发 JVM ，让你的 Agent 完整跑一次"断点命中到根因结论"的闭环，体验一下它和"猜"的区别。用得顺手的话，欢迎来 GitHub 点个 Star ，也欢迎提 Issue 和 PR 。

👉 https://github.com/Aresxue/java-debug-skill