> 别再让 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 里，直接用自然语言发起即可：

```text
帮我远程 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 会自己完成整个闭环：

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

---

## 为什么不直接用 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](https://github.com/Aresxue/java-debug-skill/blob/main/README.zh-CN.md)。

---

## 安全：先说清楚风险

远程调试本身是高危操作：**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` 则交互选择）：

```bash
# 例：一次装给 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` 即可：

```bash
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` 隧道访问。

```bash
# 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 里发起调试**

```text
帮我远程 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>

GitHub：https://github.com/Aresxue/java-debug-skill

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

别再让 AI 对着日志猜根因。java-debug 是一个通用的 Java 远程调试 Agent Skill，让 Claude Code、Codex、Cursor 等 Agent 自己打断点、看调用栈和局部变量、求值、单步，根据真实运行时数据找出根因。

技术专家

数据库

java-debug是一款开源的Agent Skill工具，让AI能像程序员在IDEA中一样连上远程JVM、打断点、查看调用栈和变量，基于真实运行时数据定位Java问题根因，告别猜日志。只冻结命中线程、结构化JSON交互、支持表达式求值和单步执行，兼容ClaudeCode、Codex、Cursor等主流Agent。

远程调试

代码解释

敏感数据

GitHub

Agent

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

让 AI 真正"打断点"：java-debug，一个通用的 Java 远程调试 Agent Skill-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐