内容
# jdbg
**适用于 Agent 的 Java 调试器** CLI，用于 Claude Code 和人类，封装 JDK `jdb`，具有持久会话、结构化输出和原生 MCP 工具。
## 亮点
- **基于提示，而不是睡眠** — 读取 `jdb` 输出，直到提示返回；永不使用超时进行猜测。
- **有状态守护进程** — 后台进程在 CLI 调用期间保持调试会话活跃。
- **Windows 优先，跨平台** — 纯 Rust 实现，无 Bash/WSL/临时文件依赖。
- **两条访问路径** — CLI (`jdbg <cmd>`) 和 MCP 服务器 (`jdbg __mcp`)，适用于 Claude Code 的原生工具调用。
- **结构化输出** — 默认人类可读文本，`--json` 选项用于机器消费。
## 快速开始
### 1. 安装 CLI
安装程序从最新的 GitHub Release 中获取适用于您操作系统/架构的正确构建，并将 `jdbg` 添加到您的 `PATH` 中。
**macOS / Linux**
```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/PieceOfFall/jdbg/releases/latest/download/java-agent-debugger-installer.sh | sh
```
**Windows (PowerShell)**
```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/PieceOfFall/jdbg/releases/latest/download/java-agent-debugger-installer.ps1 | iex"
```
> 安装程序编辑您的**用户级** `PATH` （无需管理员权限）。**请在之后打开新的终端**，以便 `jdbg` 生效。
<details>
<summary><b>已经安装 Rust？</b> 通过 cargo 或从源代码安装。</summary>
```bash
# 通过 cargo 安装（安装到 ~/.cargo/bin/jdbg）
cargo install --git https://github.com/PieceOfFall/jdbg.git
# 从源代码安装
git clone https://github.com/PieceOfFall/jdbg.git
cd jdbg
cargo build --release # 二进制文件位于 target/release/jdbg
```
</details>
### 2. 注册到 Claude Code
一条命令将 `jdbg` 注册到 Claude Code 作为 MCP 服务器：
```bash
jdbg setup
```
这将 MCP 服务器条目写入 `~/.claude.json`，并将自动允许权限 (`mcp__jdbg__*`) 写入 `~/.claude/settings.json`。**重启 Claude Code** 以生效，新服务器的工具将显示为 `mcp__jdbg__<tool>`。
```bash
jdbg setup --print # 预览配置片段而不写入任何内容
```
### 3. 开始调试
```bash
# 编译目标程序并包含调试信息
javac -g Main.java
# 启动调试会话（守护进程自动启动）
jdbg launch Main --classpath .
# 设置断点并运行
jdbg break-at Main 9
jdbg run
# 检查状态
jdbg locals
jdbg where
jdbg print myVar
# 步进和继续
jdbg step
jdbg cont
# 清理
jdbg kill
jdbg daemon stop
```
在 Claude Code 中，只需询问它调试 — 它通过 `mcp__jdbg__*` 工具驱动相同的流程。
### 卸载
```bash
jdbg setup --remove # 删除 MCP 服务器条目和权限；保留二进制文件
```
## 要求
- JDK 8–21+，`jdb` 在 PATH 中或可通过 `JAVA_HOME` 发现
- Rust 1.85+（2024 版）— 仅适用于 `cargo`/从源代码安装方法
- 用于调试：使用 `javac -g` 编译 Java 代码（用于局部变量/行断点的调试信息）
## CLI 命令
```
# 会话生命周期
jdbg launch <MainClass> [--classpath CP] [--sourcepath SP] [--name N] [-- app-args...]
jdbg attach [--host H] [--port P] [--sourcepath SP] [--name N]
jdbg status | list | kill [--session ID]
jdbg daemon start | stop | status
# 断点
jdbg break-at <Class> <line>
jdbg break-in <Class> <method> [--args types]
jdbg catch <Exception> [--mode caught|uncaught|all]
jdbg breakpoints | clear <spec>
# 执行控制
jdbg run | cont | step | next | step-out
# 检查
jdbg where [--all] | locals | print <expr> | dump <obj> | eval <expr>
jdbg threads | thread <id> | frame <up|down> [n] | list-source [line]
jdbg raw <jdb command...>
# 设置 / 全局标志
jdbg setup [--remove] [--print]
--session <id> 目标特定会话（默认为唯一的活动会话）
--json 机器可读的 JSON 输出
--timeout <secs> 覆盖每个命令的超时时间
--jdb-path <p> 显式指定 jdb 可执行文件的路径
```
## MCP 服务器（Claude Code 原生工具）
`jdbg __mcp` 运行一个 stdio JSON-RPC 2.0 MCP 服务器，公开 CLI 接口作为 **25 个原生工具**（`launch`、`break_at`、`run`、`locals`、`cont` 等），以便 Claude Code 可以驱动调试会话，而无需通过 Bash。工具显示为 `mcp__jdbg__<tool>`。
`jdbg setup`（[快速开始步骤 2](#2-注册到-claude-code)）为您配置此项。要手动配置 — 或在开发 jdbg 本身时指向 **开发构建**：
```json
{
"mcpServers": {
"jdbg": { "command": "target/debug/jdbg", "args": ["__mcp"] }
}
}
```
存储库附带 `.mcp.json`（开发）和 `.claude-plugin/plugin.json`（分发），配置了此项。
## 架构
两个客户端 → 一个守护进程 → N × jdb 子进程：
```
CLI (jdbg) ─┐ ┌─ jdb 子进程 A → JVM A
├─► 守护进程 (SessionManager) ┤
MCP (jdbg __mcp)┘ 命名管道 / 套接字 └─ jdb 子进程 B → JVM B
```
- **CLI / MCP 服务器** — 两个对等客户端；每个客户端将其输入转换为 `Request`，并通过 `client::send_request` 发送到守护进程。
- **守护进程** (`jdbg __daemon`，自动生成) — 拥有 IPC 监听器和 `HashMap<SessionId, Session>`，多路复用 N 个并发会话。
- **jdb 引擎** (`src/jdb/`) — 使用强制英文区域和管道 stdio 启动 `jdb`，读取字节直到提示，并使用正则表达式（根据捕获的 jdb 转录验证）将输出解析为结构化结果。
分层依赖流从上到下：
```
bin (main.rs) → cli / output → client / daemon → session → jdb / jdkpath → error / protocol / registry
```
参见 [`DESIGN.md`](DESIGN.md) 以获取完整的设计参考（中文）。
## 构建和测试
```bash
cargo build # 调试构建
cargo build --release
cargo test # 48 个单元测试（解析器、协议映射、MCP 工具、会话、设置）
```
解析器根据 `tests/fixtures/jdb/` 下捕获的真实 jdb 转录进行验证。纯逻辑（解析器、协议映射、JSON-RPC）遵循 TDD；平台副作用通过端到端运行验证。
## 许可证
在 [Apache License 2.0](LICENSE) 下许可。
