mcpField
J
joLink

joLink

本地服务
github.com开发工具102 天前更新

关于 joLink

joLink Runtime 是面向编码 Agent 的无界面 Java 开发环境,提供构建、测试、启动和调试流程。持久化增量编译与运行时检查帮助 Agent 根据应用实际行为验证改动,而不只依赖源代码。

主要功能

  1. 01增量 Java 编译
  2. 02指定 Java 测试运行
  3. 03应用启动与 HotSwap
  4. 04日志和进程状态
  5. 05断点、调用栈与变量

适用场景

  1. 01通过测试验证 Java 改动
  2. 02调查接口响应异常
  3. 03在断点处检查运行状态

MCP 相关

joLink 提供 4 种 MCP 工具,用于控制 Java 应用、快速测试、查看状态和调试。编码 Agent 可借此编译、运行和检查 Java 项目。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"l1ch404-jolink-runtime": {
"command": "uvx",
"args": [
"jolink-runtime"
],
"env": {
"JOLINK_DOWNLOAD_MIRROR": "<JOLINK_DOWNLOAD_MIRROR>",
"JOLINK_JDT_GC_AFTER_BUILD": "<JOLINK_JDT_GC_AFTER_BUILD>"
}
}
}
}
启动命令uvx jolink-runtime
需要配置的环境变量
JOLINK_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+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
pypijolink-runtime0.1.0a9

工具

4

收录的工具列表 · 更新于 1 周前

参数类型必填说明
pidinteger否attach 所需的本地 Java PID。
hostenum否调试连接主机;仅限 localhost。127.0.0.1 | localhost
actionenum是要执行的运行时操作。launch | attach | restart | stop | detach
hotswapboolean否对于 restart,默认值为 true:增量编译编辑内容并优先使用 HotSwap;如果变更无法通过 HotSwap 应用,则使用这些编译输出重启 JVM。设为 false 会在编译后强制重启 JVM。若要重新初始化应用程序状态或重新加载框架/启动配置,请使用 false。没有待处理的代码变更时,也会重启 JVM,但不会重新编译。
timeoutnumber否此调用中等待启动/重启结果的秒数。默认值为 30;超过 30 的值最多只等待 30 秒,不会报错。设为 0 则在提交后立即返回。超时后,同一任务会在后台继续运行。
vm_argsarray否启动/重启时使用的 JVM 参数。替换导入的或当前参数;[] 会清除这些参数。
app_argsarray否启动/重启时使用的应用程序参数。替换导入的或当前参数;[] 会清除这些参数。
jar_pathstring否用于直接启动/重启的可执行 JAR;与 project_path 一起使用时省略。
classpathstring否使用 main_class 直接启动或重启时的类路径;与 project_path 一起使用时省略。
java_homestring否用于通过 project_path 启动的应用程序 JDK 主目录。
jdwp_portinteger否用于启动或附加调试的本地 Java 调试端口。
main_classstring否应用程序入口类的全限定名。使用 project_path 时,无需 IDEA 配置即可启动;否则使用类路径。
maven_homestring否可选的 Maven 安装目录,用于替代项目 Wrapper 或自动选择的 Maven。
ready_portinteger否用于启动/重启就绪状态检查的本地应用程序 TCP 端口;必须与 jdwp_port 不同。
launch_namestring否可选的 IDEA 启动配置名称,必须完全匹配且区分大小写;需要 project_path。指定 main_class 且未指定 launch_name 时,无需 IDEA 启动配置。显式指定的 main_class、java_home、app_args 和 vm_args 会覆盖导入的值。
build_systemenum否项目启动时可选的权威构建系统;如果两者都存在,请指定 maven 或 gradle。maven | gradle
project_pathstring否Maven 或 Gradle 项目目录。提供 main_class 以独立于 IDEA 启动,或导入 IDEA 启动配置(launch_name 用于选择配置)。启动应用程序前会编译已更改的源文件。不要与直接指定的 jar_path 或 classpath 一起使用。
maven_settingsstring否可选的 Maven 用户 settings.xml 路径,包含仓库镜像和凭据。不会修改该文件。
build_java_homestring否通过 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 应用。

安装

  1. 在编码 Agent 中打开一个新聊天。
  2. 点击下方代码块中的复制按钮,将整段提示词粘贴到该聊天中,然后发送。
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 用量并延长任务完成时间。 如果你不想启用这条全局规则,请在发送提示词前删除启用该规则的那一行。

  1. 如果 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。在继续调查前,它还检查了其他边界值。

Agent 启动 Java 应用并检查意外的端点响应

2. 设置断点并检查运行时变量

Agent 使用 java_debugger 在 Medium Risk 分支上设置断点, 触发另一个请求,并在断点命中后检查变量。

对话显示,在程序执行到 Medium Risk 分支时,score=80。这为 Agent 调查其边界条件假设提供了运行时证据,而不是仅依赖源代码推断。

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 映射为 MCP isError=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 源代码和构建,以及历史研究记录。归档的实验命令和限制并非当前产品接口。

许可证

joLink 自有代码采用 MIT 许可证。下载的 Eclipse/Temurin 运行时和已安装的 Python 依赖各自遵循其自身许可证。请参阅第三方声明及对应源代码。 离线运行时套件必须随附匹配的源代码套件和声明。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。