关于 joLink
joLink Runtime 是面向编码 Agent 的无界面 Java 开发环境,提供构建、测试、启动和调试流程。持久化增量编译与运行时检查帮助 Agent 根据应用实际行为验证改动,而不只依赖源代码。
主要功能
- 01增量 Java 编译
- 02指定 Java 测试运行
- 03应用启动与 HotSwap
- 04日志和进程状态
- 05断点、调用栈与变量
适用场景
- 01通过测试验证 Java 改动
- 02调查接口响应异常
- 03在断点处检查运行状态
MCP 相关
joLink 提供 4 种 MCP 工具,用于控制 Java 应用、快速测试、查看状态和调试。编码 Agent 可借此编译、运行和检查 Java 项目。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
uvx jolink-runtimeJOLINK_DOWNLOAD_MIRRORDownload source for Java tooling. Use cn in China.JOLINK_JDT_GC_AFTER_BUILDRequest memory cleanup after compilation: 1 enables it, 0 disables it.本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。
工具
4收录的工具列表 · 更新于 1 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pid | integer | 否 | attach 所需的本地 Java PID。 |
| host | enum | 否 | 调试连接主机;仅限 localhost。127.0.0.1 | localhost |
| action | enum | 是 | 要执行的运行时操作。launch | attach | restart | stop | detach |
| hotswap | boolean | 否 | 对于 restart,默认值为 true:增量编译编辑内容并优先使用 HotSwap;如果变更无法通过 HotSwap 应用,则使用这些编译输出重启 JVM。设为 false 会在编译后强制重启 JVM。若要重新初始化应用程序状态或重新加载框架/启动配置,请使用 false。没有待处理的代码变更时,也会重启 JVM,但不会重新编译。 |
| timeout | number | 否 | 此调用中等待启动/重启结果的秒数。默认值为 30;超过 30 的值最多只等待 30 秒,不会报错。设为 0 则在提交后立即返回。超时后,同一任务会在后台继续运行。 |
| vm_args | array | 否 | 启动/重启时使用的 JVM 参数。替换导入的或当前参数;[] 会清除这些参数。 |
| app_args | array | 否 | 启动/重启时使用的应用程序参数。替换导入的或当前参数;[] 会清除这些参数。 |
| jar_path | string | 否 | 用于直接启动/重启的可执行 JAR;与 project_path 一起使用时省略。 |
| classpath | string | 否 | 使用 main_class 直接启动或重启时的类路径;与 project_path 一起使用时省略。 |
| java_home | string | 否 | 用于通过 project_path 启动的应用程序 JDK 主目录。 |
| jdwp_port | integer | 否 | 用于启动或附加调试的本地 Java 调试端口。 |
| main_class | string | 否 | 应用程序入口类的全限定名。使用 project_path 时,无需 IDEA 配置即可启动;否则使用类路径。 |
| maven_home | string | 否 | 可选的 Maven 安装目录,用于替代项目 Wrapper 或自动选择的 Maven。 |
| ready_port | integer | 否 | 用于启动/重启就绪状态检查的本地应用程序 TCP 端口;必须与 jdwp_port 不同。 |
| launch_name | string | 否 | 可选的 IDEA 启动配置名称,必须完全匹配且区分大小写;需要 project_path。指定 main_class 且未指定 launch_name 时,无需 IDEA 启动配置。显式指定的 main_class、java_home、app_args 和 vm_args 会覆盖导入的值。 |
| build_system | enum | 否 | 项目启动时可选的权威构建系统;如果两者都存在,请指定 maven 或 gradle。maven | gradle |
| project_path | string | 否 | Maven 或 Gradle 项目目录。提供 main_class 以独立于 IDEA 启动,或导入 IDEA 启动配置(launch_name 用于选择配置)。启动应用程序前会编译已更改的源文件。不要与直接指定的 jar_path 或 classpath 一起使用。 |
| maven_settings | string | 否 | 可选的 Maven 用户 settings.xml 路径,包含仓库镜像和凭据。不会修改该文件。 |
| build_java_home | string | 否 | 通过 project_path 启动时,用于准备 Maven 或 Gradle 项目的 JDK 主目录。与应用程序的 java_home 分开。省略时使用项目/环境设置。重启时会沿用启动选项。 |
详细介绍
joLink Runtime
English | 简体中文
面向 AI 编码 Agent 的轻量级无头 Java IDE。
为自主 Java 开发闭合反馈环。
设计原则: 一切皆为降低大模型的不确定性。
joLink 不提供编辑器 UI。相反,它通过 MCP 向你已在使用的编码 Agent 提供增量编译、 测试、应用启动和断点调试功能,让它能够运行代码、检查真实状态,并验证自身的更改。
持久化编译状态和 HotSwap 可减少重复的完整重编译和 JVM 重启。当测试、日志和端点响应不足以解决问题时,Agent 可以使用断点并检查异常事件、堆栈帧和变量。
免费且在本地运行。它不需要 joLink 账户、模型 API 密钥、推理服务提供商或单独的 Agent 应用。
安装
- 在编码 Agent 中打开一个新聊天。
- 点击下方代码块中的复制按钮,将整段提示词粘贴到该聊天中,然后发送。
Follow this guide:
https://github.com/L1ch404/jolink-runtime/blob/main/INSTALL.md
Install joLink MCP and its English Skill for my current agent.
Enable the global Java change-verification rule for this agent across projects.
Use user-level installation by default and preserve existing configuration.
Check the saved configuration, Skill and rule. If a client UI action or reload is needed,
stop and tell me what to do; leave connection and rule-loading verification to a chat after reloading.
警告
按照上述提示词操作,会在当前 Agent 中添加一条全局 Java 验证规则,并应用于所有项目。 这会促使 Agent 执行额外测试和运行时检查,可能增加 token 用量并延长任务完成时间。 如果你不想启用这条全局规则,请在发送提示词前删除启用该规则的那一行。
- 如果 Agent 提示需要重新加载,请按说明重新连接 MCP 或重启客户端, 然后打开一个新聊天。配置已完成但尚未加载,并不代表安装失败。 在已加载的聊天中,你可以发送:
Verify the existing joLink MCP and jolink-java Skill in this client without reinstalling them.
Call the joLink status tool exposed by this client once, and check its Skill list or loading facility.
If I enabled it, also check whether the global Java change-verification rule is loaded through the client's native instructions view.
If anything is unavailable or its loading cannot be confirmed, report it and stop; do not write a standalone verification script.
Do not start applications or run tests.
本指南提供适用于 Codex、
Claude Code、Cursor、VS Code/Copilot、CodeBuddy、Gemini CLI、OpenCode、Cline、
Roo Code、Windsurf 和 Kiro 的官方客户端专属位置及示例。它们均使用 uvx jolink-runtime@latest 启动 MCP,并使用相同的
English Skill;无需插件包或通用安装程序。
MCP 执行操作;Skill 说明工作流;可选的
全局验证规则会将适度的
Java 验证纳入所有项目的实现任务。上述提示词会明确启用该规则;如果你只需要 MCP 和 Skill,请删除该行。
本指南还介绍 uv 设置、配置保留、重新连接和验证。
如需中文说明,请参阅中文安装指南。
为什么选择 joLink
编码 Agent 擅长阅读和修改代码,但有时会陷入静态假设的循环:
analyze
-> patch
-> assume the patch works
-> patch again
joLink 补上了缺失的运行时反馈环:
analyze
-> change
-> run
-> observe
-> update the hypothesis
-> change again if necessary
适用于以下情况:
- Java 应用尚未运行;
- 需要根据真实行为验证代码更改;
- 多次修补仍未解决问题;
- 端点结果与对源代码的解读不符;
- 日志或测试不足以解释实际执行路径;
- 业务命名不一致,静态搜索无法找到相关代码;
- 需要更深入的运行时证据,例如断点、堆栈或变量。
目标不是为每个问题都使用调试器。
先从成本最低且有用的证据入手:
application status
-> logs and actual outputs
-> exception events
-> executed path
-> breakpoints, stack frames, and variables
仅在必要时深入调试。
功能
joLink 提供四个专用 MCP 工具:
java_application— 启动项目、感知编译结果地重启(默认使用 HotSwap)、 停止和附加;java_fast_test— 运行所选 Java 测试、查看结果详情并取消测试,不启动应用;java_status— 发现 Java 进程、查看精简状态、按需获取详情和日志;java_debugger— 设置断点、捕获异常事件、查看堆栈和变量,以及恢复执行。
编辑受管理的项目后,请调用 java_application(action=restart)。
它会在现有 JDT 工作区中增量编译更改,并优先使用 HotSwap;如果更改不兼容,
则使用相同的编译输出重启 JVM。设置 hotswap=false 可强制重新初始化进程/应用。结果中的
apply_method 用于区分 HotSwap 和真正的重启。请参阅
重启工作流。
只有在小型配置缓存不存在或发生更改时,Fast Test 才会使用 Maven 或 Gradle Probe。 导出的测试 Build World 和 JDT 工作区会在 MCP 进程之间持久保留。 JDT 会保持主类和测试类为最新状态,并在隔离的 JVM 中运行 明确指定的 JUnit 4/5 或 TestNG 测试:
java_fast_test(action=run,
project_path=/path/to/project,
source_files=[src/main/java/example/Service.java],
tests=[example.ServiceTest#works], timeout=60)
-> if unfinished, choose a suitable waiting interval, then call java_status(action=status)
-> read diagnostics/failures with java_fast_test(action=result, test_run_id=...)
-> cancel with java_fast_test(action=cancel, test_run_id=...)
java_status(status).fast_test 会保持精简。如果 run 返回前编译失败,回复中会直接包含编译器诊断信息。
超时回复后发生的错误和失败测试详情可通过 result 获取;请按摘要中的 next_action 操作,
或使用其 test_run_id,无需重新运行测试。
完整的编译器文件列表会被省略。在当前 MCP 会话中,只保留正在进行和最近完成的测试尝试;
如果 ID 不可用,则返回 TEST_RUN_NOT_FOUND。
passed=false 表示所选测试已执行且发现失败;这不是工具基础设施错误。Fast Test 不需要
也不会修改正在运行的应用。当前 JDT 支持 Java 8 到 26 的 source/target 级别;
产品回归测试覆盖 8、11、17 和 21,并包括独立的主类/测试类级别。
目标库以及应用和测试 JDK 仍由项目决定。支持的构建布局包括 Maven jar 项目、标准 Reactor 中
一个明确选定的 jar 模块,以及 Gradle Java 构建(包括多 Project 依赖,已使用 7.4.2、8.10 和 8.14 测试)。
Maven 和 Gradle 多模块启动及 Fast Test 会将所选模块的上游依赖解析为同一个 Worker 中的独立 JDT 项目。
未更改的模块会复用其输出;JavaBuilder 会将更改后的 API 和常量传播到受影响的下游源文件。
本地模块依赖使用当前工作区输出,而不是已安装的 JAR;Maven 还支持 test-jar 依赖。请参阅
Gradle 多模块流程与验证。
演示
从意外的 API 响应到运行时调查。
阅读源代码可以让 Agent 了解可能发生什么。运行应用并检查其状态,有助于 Agent 确认实际发生了什么。
以下截图展示了一个调试示例:Agent 启动 Java 应用、检查端点、发现意外结果,然后使用 joLink 调查执行路径。
这是一个构造的演示场景,并非真实业务事件的记录。 为保护隐私,截图中的部分敏感信息已打码。
1. 启动应用并检查实际响应
Agent 使用 java_application 启动应用,使用 java_status
检查其状态,然后向一个示例风险评分端点发送 HTTP 请求。
对于 score=80,预期类别为 High Risk,但 Agent 返回了
Medium Risk。在继续调查前,它还检查了其他边界值。

2. 设置断点并检查运行时变量
Agent 使用 java_debugger 在 Medium Risk 分支上设置断点,
触发另一个请求,并在断点命中后检查变量。
对话显示,在程序执行到 Medium Risk 分支时,score=80。这为 Agent
调查其边界条件假设提供了运行时证据,而不是仅依赖源代码推断。

此示例展示了应用程序启动和运行时调查。 这不是 Fast Test 性能基准测试;截图展示的是调查阶段,不包括后续修复和重新验证。
私有诊断
joLink 将 stdout 专用于 MCP JSON-RPC。Python 生命周期日志和 traceback 也会写入一个有大小限制的私有轮转文件:
Windows: %LOCALAPPDATA%\jolink-runtime\logs\mcp.log
macOS/Linux: $XDG_CACHE_HOME/jolink-runtime/logs/mcp.log
or ~/.cache/jolink-runtime/logs/mcp.log
即使设置了 details=true,status 也不会返回 mcp.log 路径或日志配置。
诊断 joLink 本身时,请读取上述路径中的本地文件。诊断文件写入失败不会阻止 MCP 服务启动。文件大小上限为
4 MiB,最多保留三个轮转备份;stdout 不会受到影响。
java_status(action=status) 提供精简概览:就绪状态、进程/调试状态、
当前操作以及最近的重启/Test 摘要。读取 java_status(action=status, details=true)
可查看当前启动错误、完整的 last_reload、编译器/缓存设置和耗时。
已完成的 launch/restart 调用会直接返回各自的详细结果;当某项操作在同步回复超时后仍继续运行时,此
标志很有用。这两个调用都不会读取或嵌入构建日志。使用 java_status(action=logs, source=build)
查看当前启动的构建日志,或省略 source 以读取应用程序输出;
两者都接受 tail。重启摘要包含一个指向详细信息的 next_action。
launch/restart 回复包含 previous_startup_ms:同一启动项此前成功的 JVM
启动耗时,该值保存在本地,并在
新操作开始前获取。不包括 Probe/JDT 编译。设置了 ready_port 时,
它测量从启动到观测到 TCP 就绪的耗时;否则只测量 JVM/
JDWP 启动耗时。HotSwap 和启动失败不会替换此记录。
启动成功后,该值会写入 joLink
缓存目录 startup-timings/ 下的一个小型 JSON 文件中。停止、新建对话或重启 MCP
都不会删除此记录。下次启动时会读取该文件;没有过期机制、构建输入验证或重复状态写入。尚无记录的启动项会返回
null。请将其视为等待时长参考,而非预测或就绪检查。
在 MCP 服务的环境中设置 JOLINK_LOG_LEVEL,然后重启服务:
WARNING(默认值)仅保留警告/错误;INFO 会记录 JDT
缓存/源代码/构建/保存摘要以及原生 FULL 回退原因;
DEBUG 还会保留详细的 Worker 输出;ERROR 仅保留错误;
OFF 会禁用 joLink 诊断日志。应用程序日志和工具结果不受影响。
Worker 使用固定的增量传播上限,即 10 轮。
请参阅 JDT 构建诊断。
公开操作如下:
launch
stop
restart
attach
detach
breakpoint
exception
wait_event
threads
stack
variables
resume
cleanup_debug_state
processes / status / logs
这些操作支持:
- 将 Java 应用程序作为由自身管理的 JVM 进程启动;
- 使用
project_path和main_class启动 Maven/Gradle 项目,或 可选地导入 IntelliJ IDEA Application/Spring Boot 配置,在不运行 Maven/Gradle 编译的情况下 导出其 Build World,在 JVM 启动前使用 JDT 编译,并在不打包胖 JAR 的情况下启动; - 代码更改后停止或重启应用程序;
- 在持久化的私有 JDT 会话中编译检测到的编辑,并通过 HotSwap 应用兼容的已加载类定义;
- 检查应用程序状态和日志;
- 附加到已运行的本地 JVM;
- 设置语义断点和异常监视;
- 等待运行时事件;
- 检查线程、堆栈帧和变量;
- 恢复挂起的执行;
- 安全地清理调试状态。
当前状态
当前软件包版本:
0.1.0a9
状态:
Alpha / controlled dogfood
第一个适配器面向通过 JDWP 连接的本地 Java 应用程序。
当前 MCP 实现包括:
- stdio 传输;
- stdout 专用于 MCP 协议消息;
- JSON
TextContent,并包含匹配的structuredContent; - 将 Runtime
ok=false映射为 MCPisError=true; - 可取消的
wait_event; - 可选的两阶段等待,使用
arm和await; - 仅在 JDWP 完成布防后才启动的可选环回 HTTP 触发器,支持一次调用的
blocking快捷方式,或显式调用arm/await; - 限定于等待期间的 JDWP 请求;
- 感知所有权的关闭机制;
- 自动清理和恢复路径;
- 在短轮询超时期间持续维护 JDWP 数据包帧状态。
当前的两阶段实现旨在用于受控的内部试用。已知的取消、清理抢占、句柄发布和响应交付方面的限制记录在:
docs/stage-2.1.2-lifecycle-backlog.md
请勿在无人值守的生产 JVM 调试中使用此 alpha 版本。
要求
- JDK 8 或更高版本
- uv
uv 会自动管理 Python 环境。通常无需单独安装 Python。
使用以下命令确认是否满足要求:
java -version
uv --version
快速开始
连接 MCP 服务后,确认以下工具可用:
java_application
java_fast_test
java_status
java_debugger
打开一个本地 Java 项目,并向编码 Agent 提问:
Use joLink to start this Java application, inspect its status and logs,
and verify the latest code changes against real runtime behavior.
对于已经尝试多种修复方法但仍未解决的问题:
Do not apply another speculative patch yet.
Use joLink to run the current Java application and collect actual runtime
evidence. Start with status, logs, tests, and actual outputs. Re-evaluate the
root-cause hypothesis before changing the code again.
如需深入调查:
Use joLink to reproduce this issue.
Start with actual outputs and logs. If that evidence is insufficient, use a
breakpoint or exception watch, inspect the relevant stack frames and variables,
then resume or clean up the suspended JVM.
joLink 会启动并监控 Java 应用。编码 Agent 可以使用常规的 HTTP、终端、浏览器或测试工具来触发相应场景。
对于通过 project_path 启动的应用中的方法体编辑,Agent 可以避免完整的 Maven 重建和重启:
java_status(action=status; confirm runtime_active and compile_ready=true)
-> java_application(action=restart)
-> if still running, java_status(action=status; observe last_reload)
-> trigger a fresh request
-> verify the new runtime behavior
restart 会自动检测并增量编译源代码更改,然后默认使用 HotSwap。已删除或卸载的类、生成的资源更改或 JVM 明确拒绝 HotSwap 时,会使用已编译的输出执行真正的重启。hotswap=false 会强制重新初始化进程。没有待处理的代码更改时,重启不会触发编译。编译错误不会影响旧进程的运行。丢失的 HotSwap 回复仍会被视为未知状态,而不会误判为明确拒绝。调用最多等待 timeout 指定的时长(上限为 30 秒);如果尚未完成,则会返回 restart_started 以及现有的 reload_id,可通过 active_operation 和 last_reload 查看状态。apply_method 会区分 HotSwap 和进程重启。构建完成后,会立即将 JDT 状态和源代码索引保存到本地持久化工作区。不会额外复制类输出。HotSwap 不会重新运行初始化或刷新 Spring 元数据;请使用新请求进行验证。重新定义类中的断点会过期,必须重新设置。
首次使用时,会将锁定版本的 JDT Worker 安装到内容寻址的用户缓存中。joLink 旧缓存中的有效 Eclipse bundle 会继续复用;缺失的 bundle 会下载并验证,而产品 Worker 和 Equinox 配置则随 Python 包提供。构建配置变更或会话不可用时,会通过现有项目启动路径刷新。需要重新创建启动或框架状态时,请使用 restart(hotswap=false)。
产品使用 Eclipse 4.40 / JDT 3.46 及匹配的 APT bundle。其 Worker 面向 Java 17 字节码,默认使用一次性安装在用户缓存中的专用锁定版 Temurin 21 运行时。Maven/Gradle 及应用程序/测试 JVM 会继续使用各自项目的 JDK。也可通过 JOLINK_WORKER_JAVA_HOME 指定公司提供的 64 位 JDK 17+。旧版 Lombok 1.18.20 的兼容性问题仍会记录,不会通过替换项目依赖来悄悄修复。离线设置和实际兼容性结果请参阅 JDT 3.46 and private Worker JDK。
首次下载 JDK/Eclipse 时,默认使用其锁定的官方 URL。设置 JOLINK_DOWNLOAD_MIRROR=cn 可依次尝试 TUNA、joLink 镜像 https://7355608.net/jolink/assets,并在连接或传输失败时回退到上游源。自定义镜像基 URL 会先使用该镜像,再回退到上游源;official(或空值)则只使用上游源。不会进行 IP/地理位置检测。现有的 SHA256 校验和已安装的缓存不受影响。本地验证期间无法访问 TUNA;选择 cn 并不保证其可用。请参阅运行时镜像设置。
导入的 IDEA Make/Build 标记不会触发 Maven 或 Gradle 编译。首次启动时,Probe 会导出编译器/运行时信息,由 JDT 执行完整编译。后续启动会复用持久化的 Probe 模型,并使用已保存的源文件大小/修改时间检测编辑。受跟踪的 Maven/Gradle 配置发生更改时,会刷新模型。未跟踪的外部脚本和隐藏输入仍记录在兼容性后续跟进中;删除缓存不是常规启动或安装步骤。
有关当前单模块启动和缓存行为,请参阅 JDT-first startup。
典型工作流
常规验证流程如下:
read the code
-> change the code
-> java_application(launch or restart, ready_port=<application port>)
-> if startup_state=starting, call java_status(status) until ready
-> if startup_state=failed, inspect java_status(logs)
-> trigger a test or endpoint
-> inspect the actual result
-> update the diagnosis
更深入的调试流程如下:
run or attach
-> for an owned HTTP application, confirm startup_state=ready
-> configure a breakpoint or exception watch
-> for a managed local HTTP request:
wait_event(wait_mode=blocking, http_trigger=...)
-> otherwise:
wait_event(wait_mode=arm)
-> trigger the scenario after status=armed
-> wait_event(wait_mode=await, wait_handle=...)
-> inspect stack frames and variables
-> resume or cleanup_debug_state
对于本地 HTTP 端点,blocking 会将现有的
arm -> trigger -> await 生命周期组合为一次调用:
{
"action": "wait_event",
"wait_mode": "blocking",
"timeout": 30,
"http_trigger": {
"method": "POST",
"url": "http://127.0.0.1:8080/example",
"json_body": {"id": 1},
"timeout_seconds": 30
}
}
如果必须在布防和观察之间执行外部操作,请先显式调用 arm,再调用 await。终止结果会消耗其 wait_handle;该句柄用于观察 Runtime 事件,并非 HTTP 响应句柄。
对于由 joLink 启动的 HTTP 应用,请区分进程/调试器启动与应用 TCP 就绪状态:
{
"action": "launch",
"jar_path": "target/app.jar",
"jdwp_port": 5005,
"ready_port": 8080,
"timeout": 30
}
对于 java_application(launch/restart) 和 java_fast_test,timeout 限制同步结果等待时间,包括 Runtime 准备和编译。默认值为 30 秒;可以接受更大的值,但最多只等待 30 秒。设为零时,会在提交任务后返回。原任务会在此回复时限之后继续运行。Test Runner 执行有单独的内部 300 秒限制;timeout 不再控制该限制。如果任务仍在运行,请选择适合当前阶段的等待间隔(例如使用 sleep 或 PowerShell Start-Sleep),然后查询 java_status。不要快速轮询或重新提交任务。旧的就绪等待参数已移除,并未保留为别名。
直接启动 JAR/classpath 时,仍会在返回任务观察结果前执行现有的进程创建和 JDWP 握手。timeout=0 会跳过额外的就绪等待,但不会让初始握手变为异步。如果进程仍在运行,但应用端口尚未接受连接,结果仍为成功,且 startup_state=starting;进程会保持运行,next_action=status。之后每次调用 status 都会再次探测已存储的端口。startup_state=ready 仅表示配置的环回 TCP 端口已接受连接;这并不能证明所有依赖项、缓存或业务端点都运行正常。
如果未提供 ready_port,joLink 会报告 startup_state=unverified,而不会声称应用已就绪。对于已附加以及其他未验证的 JVM,仍允许执行 HTTP 触发,但结果会包含警告。如果已配置的就绪状态仍为 starting,joLink 会拒绝 HTTP 触发,不会发送请求。
Runtime 安全性
joLink 0.1.0a9 专为本地、可信的开发环境设计。
当前安全边界:
- MCP 传输方式为 stdio;
- JDWP 访问仅限本地 JVM;
- 一个 joLink 服务一次只控制一个 Java 目标;
- 由 joLink 启动的 JVM 视为其拥有的进程;
- joLink 可以停止其拥有的 JVM;
- 外部启动的 JVM 会被附加、恢复并分离;
- 绝不会有意终止已附加的 JVM;
- 仅当等待器持有原始 JDWP 请求时,才会布防这些请求;逻辑断点和异常定义会一直保留,直到被移除或清理;
- 内置 HTTP 触发器仅接受
http://127.0.0.1,不使用环境代理或重定向,也绝不会在验证错误中返回请求 URL、标头、正文或其原始值; - 启动前,配置的
ready_port必须未被占用,且必须与 JDWP 端口不同;TCP 探测仅在本地进行,不会发送应用请求; response_headers_received仅报告 HTTP 状态/响应标头;joLink 不会读取或返回响应正文;- 取消 HTTP 客户端等待会关闭 joLink 一侧的连接,但无法保证服务端业务操作已撤销;
- 成功的
cleanup_debug_state包含自身的调试状态验证;单独的 HTTP 清理状态可以继续保持settling,而不会延迟 JVM 清理; - 收到
suspension_id后,Agent 必须调用resume或cleanup_debug_state。
不要将 JDWP 端口暴露给不可信网络。
不要将当前的 alpha 版本用于远程或生产环境调试。
客户端说明
CodeBuddy
某些当前的 CodeBuddy 环境最初可能会显示:
Description: No description
请使用宿主的工具定义加载/搜索功能获取实际架构。
不要仅凭工具名称推断参数。独立安装的
jolink-java Skill 提供发现和工作流入口;它不能替代 MCP 连接,也不保证工具选择正确。请根据具体的 CodeBuddy 形态(CLI、IDE 或
编辑器插件),遵循安装指南,不要假设它们的配置文件可以互换。
开发
克隆仓库并安装开发依赖:
uv sync --extra dev --locked
运行默认测试套件:
uv run pytest
从源代码检出目录运行 stdio 服务:
uv run jolink-runtime
等效的模块入口:
uv run python -m jolink_runtime.transport.stdio
通用 MCP 客户端配置可以直接从检出目录启动它:
{
"mcpServers": {
"jolink-runtime": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/jolink-runtime",
"run",
"jolink-runtime"
]
}
}
}
测试
修改 joLink 源代码后,不要仅仅杀掉 MCP 服务,就假设现有宿主工具句柄会重新连接。请通过真实的 stdio 协议,从当前工作树启动新的服务:
uv run python scripts/jolink_mcp_dev_client.py
客户端会在接受 JSONL tools/call 请求前,打印 Git 提交、工作树是否干净、源代码指纹、Python 可执行文件和 stderr 路径。发送 {"command":"quit"} 以关闭客户端并触发正常的服务清理流程。对于未提交代码,这是规范的交互式验证路径;只有在被测代码冻结后,才应建立 Codex/IDE MCP 连接。
真实的子进程验收测试会测试 MCP stdio 边界:
uv run pytest -q tests/e2e/test_stdio_mcp.py
该测试会执行:
initialize
-> tools/list
-> java_status(status)
-> close the stdio client
-> wait for the server process to exit
本地可选择运行较重的真实 MCP/JVM 套件:
JOLINK_RUN_MCP_JAVA_E2E=1 \
uv run pytest -q -m mcp_java_e2e tests/e2e/test_stdio_mcp_java.py
受管 Temurin 21 Worker 和 Java 8 应用程序生命周期分别有独立的深度验证器(Worker JDK 与应用程序/目标 JDK 用途不同):
uv run python scripts/validate_jdt_worker_matrix.py \
--target-java-home <jdk8> \
--worker-java-home <jdk21>
uv run python scripts/validate_jdt8_product_mcp.py \
--jdk8-home <jdk8> \
--maven-home <maven-home>
JOLINK_RUN_FAST_TEST_E2E=1 \
JOLINK_FAST_TEST_JAVA8_HOME=<jdk8> \
uv run pytest -q -m fast_test_e2e \
tests/e2e/test_fast_test_product.py
uv run python scripts/validate_fast_test_build_jdk_matrix.py \
--target-java8-home <jdk8> \
--build-java-home <jdk8> \
--build-java-home <jdk11> \
--build-java-home <jdk17>
uv run python scripts/build_jdt_worker_release.py \
--java-home <jdk8> \
--maven <maven-executable> \
--gradle <gradle-executable>
较重测试套件的规范 CI 环境为:
Linux
Python 3.11
Application/target JDK 8/11/17/21; managed Worker JDK 21
契约
请参阅当前文档、产品 Java 源代码和构建,以及历史研究记录。归档的实验命令和限制并非当前产品接口。
- MCP v0.1:
docs/mcp-contract-v0.1.md - Runtime lineage 2.4.0:
docs/runtime-lineage-contract-2.4.0.md
许可证
joLink 自有代码采用 MIT 许可证。下载的 Eclipse/Temurin 运行时和已安装的 Python 依赖各自遵循其自身许可证。请参阅第三方声明及对应源代码。 离线运行时套件必须随附匹配的源代码套件和声明。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。