java-debug

预备检查：IntelliJ Debug MCP

此技能是 Spring Agent Toolkit 的一部分，旨在与 IntelliJ Debug MCP 服务配合使用（由 Amplicode IntelliJ 插件与主 Spring MCP 一同提供）。开始任何操作之前，请检查工具列表中是否有任何 Debug MCP 工具——它们由 intellij-debug MCP 服务提供（例如 toggle_breakpoint、evaluate_expression、get_stack_trace）；将 MCP 工具扁平化到工具列表中的运行环境，会在这些工具名称前加上 mcp__intellij-debug__ 前缀。

• 如果至少有一个 Debug 工具可用——MCP 已连接。继续使用下方技能。
• 如果没有可用工具——停止并调用 amplicode-install 技能（随 Spring Agent Toolkit 一同提供）。它会安装 Amplicode 插件，并引导用户点击欢迎屏幕上的 «Настроить Spring Agent» 按钮，然后重启 MCP 客户端。完成后，Debug MCP 工具便会可用——继续此技能。
• 如果技能列表中未注册 amplicode-install，请用用户的语言告知用户："此技能需要 Amplicode IntelliJ 插件及其 Debug MCP 服务。请从 https://amplicode.ru/marketplace 将其安装到 IntelliJ IDEA Ultimate/Community 或 GigaIDE，打开任意项目，点击 Amplicode 欢迎屏幕上的 «Настроить Spring Agent》，然后重启 MCP 客户端。"

---

使用 IntelliJ Debug MCP 调试

此技能将指导你通过 IntelliJ Debug MCP 服务调试应用程序。MCP 服务运行在 IntelliJ IDEA 内，可让你以编程方式控制调试器。

安全规则——请先阅读

这些规则可防止你无限期等待或丢失调试上下文。之所以制定这些规则，是因为被调试的应用程序可能随时因断点而暂停，这意味着它会停止响应所有请求。

暂停进程陷阱

应用程序命中断点时，其线程会被冻结。你向该应用程序发送的任何 HTTP 请求、curl 调用或网络交互都会永远挂起——在恢复应用程序之前，它无法响应。这是最常见的错误。

规则 1：与被调试应用程序通信时，务必设置超时。 使用 curl 时添加 --max-time 5，或在 Bash 工具调用中设置 run_in_background: true。即使你刚确认应用程序正在运行，也要这样做——从检查到发送请求之间，它可能命中断点。

规则 2：发起网络调用前，检查暂停状态。 调用 list_debug_sessions 并查看 isSuspended。如果应用程序已暂停，请先调用 resume，否则就要做好请求会被阻塞的准备。

规则 3：单步执行后，务必确认当前位置。 调用 step_over、step_into 或 step_out 后，请调用 get_current_position。切勿假设执行停在了哪里——它可能跳转到意外的代码行，甚至其他文件。

规则 4：恢复后检查状态。 调用 resume 后，应用程序可能立即命中另一个断点。务必调用 list_debug_sessions 或 get_current_position，确认会话仍在运行，还是再次暂停。

规则 5：求值表达式会产生副作用。 evaluate_expression 会在被调试的 JVM 中运行实际代码。除非这正是你的目的，否则请避免使用会修改状态的表达式（例如 setter 或 System.exit(0)）。

入门

使用任何 Debug 工具前，请先初始化会话：

1. 调用 initialize，并将 projectPath 设为项目根目录的绝对路径
2. 如果收到“project not found”，响应中会列出所有打开的项目——选择正确的项目并重试
3. 后续所有工具调用都会限定在此项目中

工具参考

会话

工具	参数
initialize	projectPath（字符串，必需）——项目根目录的绝对路径

运行配置

工具	参数
list_run_configurations	(无)
debug_run_configuration	configurationName（字符串，必填）— 运行配置的准确名称
list_debug_sessions	(无) — 返回会话名称和 isSuspended 状态
stop_debug_session	sessionName（字符串，必填）

断点

工具	参数
list_breakpoints	(无)
add_breakpoint	filePath（字符串，必填）、line（整数，必填，从 1 开始计数）、condition（字符串，可选）
remove_breakpoint	filePath（字符串，必填）、line（整数，必填，从 1 开始计数）
toggle_breakpoint	filePath（字符串，必填）、line（整数，必填，从 1 开始计数）、enabled（布尔值，可选 — 省略时切换状态）
set_breakpoint_condition	filePath（字符串，必填）、line（整数，必填，从 1 开始计数）、condition（字符串，必填 — 空字符串表示移除条件）

执行控制

工具	参数
resume	sessionName（字符串，可选 — 默认使用第一个活动会话）
pause	sessionName（字符串，可选）
step_over	sessionName（字符串，可选）
step_into	sessionName（字符串，可选）
step_out	sessionName（字符串，可选）

检查

工具	参数
get_current_position	sessionName（字符串，可选） — 返回文件、行号和 isSuspended 状态
get_stack_trace	sessionName（字符串，可选） — 返回包含文件、行号和描述的栈帧
list_threads	sessionName（字符串，可选） — 返回线程名称和顶部栈帧信息
evaluate_expression	expression（字符串，必填）、sessionName（字符串，可选）、frameIndex（整数，可选，从 0 开始计数，默认值为 0）

注意： 断点工具中的所有行号均从 1 开始计数（与源文件中看到的行号一致）。请使用绝对文件路径或相对于项目根目录的路径。

工作流：调查已知位置的 Bug

当你大致知道 Bug 所在的位置（特定文件、方法或行）时使用。

1. 阅读源文件，了解可疑区域的上下文
2. 在要检查的行上使用 add_breakpoint（如果只关注特定情况，请使用 condition）
3. 使用 debug_run_configuration 以调试模式启动应用
4. 触发 Bug — 如果通过 HTTP 触发，请记住：使用 curl 时添加 --max-time 5，或设置 run_in_background: true
5. 使用 get_current_position — 确认已命中断点，并停在预期行
6. 使用 evaluate_expression — 检查变量、调用方法、查看状态。先从简单内容（变量名）开始，再逐步尝试更复杂的表达式
7. 使用 get_stack_trace — 了解执行是如何到达此处的
8. 做出决定：使用 step_over / step_into 继续跟踪、在其他位置使用 add_breakpoint，或得出结论
9. 每执行一步后，调用 get_current_position 确认当前位置
10. 完成后：使用 resume 或 stop_debug_session，然后使用 remove_breakpoint 清理断点

工作流：探索未知代码的运行时行为

当你需要了解不熟悉的代码实际如何执行时使用。

1. 使用 list_run_configurations — 找到合适的应用启动方式
2. 在入口点（控制器方法、主方法、事件处理程序）设置断点
3. 使用 debug_run_configuration 开始调试
4. 触发执行（带超时的 HTTP 请求、CLI 命令，或向用户描述的 UI 操作）
5. 暂停时：使用 get_stack_trace 查看完整调用链
6. 使用 step_into 跟进方法内部的执行，使用 step_over 跳过已知代码，使用 step_out 返回调用方
7. 灵活使用 evaluate_expression — 检查方法参数、返回值和对象字段
8. 每执行一步后：使用 get_current_position 确认当前位置

表达式求值提示

• 只有会话在断点处或单步执行后处于暂停状态时，才能进行求值
• frameIndex 可让你在不同的堆栈帧中求值：0 = 当前（顶部）帧，1 = 调用者，依此类推
• 从简单的变量名开始，再逐步尝试方法调用和复杂表达式
• 谨慎使用有副作用的表达式——它们会在目标 JVM 中运行实际代码

错误恢复

错误	含义	处理方法
"Session not found"	不存在该名称的会话，或没有正在运行的会话	使用 list_debug_sessions 查看可用会话。可能需要启动一个新会话。
"Not suspended"	会话正在运行，未在断点处暂停	尚未命中断点，或会话已恢复运行。等待触发条件，或使用 pause 暂停会话。
"Evaluator not available"	当前帧不支持求值	尝试其他 frameIndex。原生代码或框架帧通常无法进行求值。
会话崩溃／断开连接	被调试的应用崩溃或已被终止	查看 IDE 日志。使用 list_debug_sessions 确认状态。启动新的调试会话。

调试完成后，请清理：对添加的所有断点使用 remove_breakpoint。遗留断点会使后续调试会话变得杂乱。

多个调试会话

当有多个调试会话处于活动状态时，调用工具时始终指定 sessionName，否则工具会默认使用第一个活动会话，而这可能不是你想操作的会话。

操作前，调用 list_debug_sessions 查看所有活动会话及其状态。

已知限制

• 无法访问控制台输出：MCP 服务不会公开被调试应用的 stdout/stderr。变通方法：直接读取日志文件，使用 evaluate_expression 检查状态，或询问用户在 IDE 控制台中看到了什么。
• 不会通知断点命中：服务不会在断点命中时推送事件。执行任何可能触发断点的操作（例如 resume、HTTP 请求或 debug_run_configuration）后，请使用 list_debug_sessions 或 get_current_position 检查状态。不要定时轮询——只需在每项相关操作后检查。