java-debug 是 Spring Agent Toolkit 的一部分，旨在配合 IntelliJ Debug MCP 服务器工作。该 MCP 服务器由 Amplicode IntelliJ 插件提供（与主 Spring MCP 一同提供），运行在 IntelliJ IDEA 内部，让使用者能够以编程方式控制调试器。
用途 该技能用于通过 IntelliJ Debug MCP 服务器调试应用程序，覆盖断点设置、调试会话启动与停止、单步执行、表达式求值、堆栈跟踪与线程查看等调试操作。
前置检查 在开始任何操作前，需检查工具列表中是否存在调试 MCP 工具。这些工具暴露在 intellij-debug MCP 服务器下（例如 toggle_breakpoint、evaluate_expression、get_stack_trace）；将 MCP 工具扁平化到工具列表的框架会使用 mcp__intellij-debug__ 前缀。若至少有一个调试工具可用，说明 MCP 已连接，可继续使用本技能。若一个都没有，则需停止并调用 amplicode-install 技能（随 Spring Agent Toolkit 捆绑），它会安装 Amplicode 插件并引导用户完成欢迎界面的「Настроить Spring Agent」按钮及 MCP 客户端重启。若 amplicode-install 未注册，需告知用户：本技能需要 Amplicode IntelliJ 插件及其调试 MCP 服务器，可从 https://amplicode.ru/marketplace 安装到 IntelliJ IDEA Ultimate/Community 或 GigaIDE，打开任意项目，在 Amplicode 欢迎界面点击「Настроить Spring Agent」，然后重启 MCP 客户端。
安全规则 这些规则用于防止无限挂起或丢失调试上下文，因为被调试应用随时可能暂停在断点上，从而停止响应所有请求。
规则 1：与被调试应用通信时始终使用超时。使用 curl 时加 --max-time 5，或在 Bash 工具调用上设置 run_in_background: true。即使刚检查过应用正在运行也要这样做，因为它可能在检查与请求之间命中断点。
规则 2：网络调用前检查暂停状态。调用 list_debug_sessions 并查看 isSuspended。若应用已暂停，先恢复它，或接受请求将被阻塞。
规则 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)）。
入门 使用任何调试工具前，先初始化会话：调用 initialize，将 projectPath 设为项目根的绝对路径。若返回「project not found」，响应会列出所有打开的项目，选择正确的重试。之后所有工具调用都限定在该项目内。
工具参考 会话：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、pause、step_over、step_into、step_out（sessionName 均可选，默认第一个活动会话）。
检查：get_current_position（sessionName 可选，返回 file、line、isSuspended）；get_stack_trace（sessionName 可选，返回带 file、line、description 的帧）；list_threads（sessionName 可选，返回线程名称与顶层帧信息）；evaluate_expression（expression 字符串必填，sessionName 可选，frameIndex 整数可选，从 0 开始，默认 0）。
注意：断点工具中所有行号从 1 开始（与源文件中所见一致）。使用绝对文件路径或相对于项目根的路径。
工作流：调查已知位置的 Bug 适用于大致知道 Bug 位置（特定文件/方法/行）的情况。读取源文件理解可疑区域上下文；在要检查的行 add_breakpoint（若只关心特定情况可用 condition）；debug_run_configuration 以调试模式启动应用；触发 Bug——若通过 HTTP，记得 curl 加 --max-time 5 或 run_in_background: true；get_current_position 确认命中断点且位于预期行；evaluate_expression 检查变量、调用方法、查看状态，先简单（变量名）再构建更复杂表达式；get_stack_trace 理解执行如何到达此处；决定 step_over/step_into 继续追踪、在别处 add_breakpoint 或结束；每步后调用 get_current_position 确认位置；完成后 resume 或 stop_debug_session，再 remove_breakpoint 清理。
工作流：探索未知代码的运行时行为 适用于需要理解不熟悉代码实际如何执行的情况。list_run_configurations 找到启动应用的正确方式；在入口点（控制器方法、main 方法、事件处理器）设置断点；debug_run_configuration 开始调试；触发执行（带超时的 HTTP 请求、CLI 命令、向用户描述的 UI 操作）；暂停时 get_stack_trace 查看完整调用链；用 step_into 跟进方法内部，step_over 跳过已知代码，step_out 返回调用者；大量使用 evaluate_expression 检查方法参数、返回值、对象字段；每步后 get_current_position 保持方向。
表达式求值提示 求值仅在会话暂停于断点或单步之后有效。frameIndex 允许在不同堆栈帧中求值：0 = 当前（顶层）帧，1 = 调用者，依此类推。先简单变量名，再进阶到方法调用和复杂表达式。对副作用表达式要谨慎，它们会在目标 JVM 中运行真实代码。
错误恢复 「Session not found」：没有该名称的会话，或没有运行中的会话。用 list_debug_sessions 查看可用项，可能需要启动新会话。 「Not suspended」：会话正在运行，未暂停在断点。断点尚未命中或已恢复。等待触发，或暂停会话。 「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 检查状态。不要使用定时轮询，只需在每个相关操作后检查。