JVM Source Lens

jvmsrc — 为你的编码 Agent 配备 Java IDE

问题所在

你用 IDE 编写 Java。你的编码 Agent 却没有 IDE。

当 Agent 遇到不熟悉的库类型时——比如某个专有内部库中的超类——它会花费 25+ 轮遍历 ~/.gradle/caches、用 jar tf 手动打开 JAR、凭猜测挑选一个，然后试图回答一个 IDE 只需一次按键就能回答的问题：这个超类是否有一个名为 X 的公共实用方法？

解决方案

jvmsrc 会查询你的构建工具（Gradle），获取此项目解析后的类路径，然后为你的 Agent 提供真实源码、真实签名和真实结构——与你的构建实际使用的版本完全一致。

• 作为 MCP 服务 – 连接到 Claude Code、Cursor、Windsurf 或任何其他 MCP 宿主，为你的 Agent 配备六种专用类路径工具。
• 作为 jvmsrc CLI – 使用相同引擎，可编写脚本、便于管道传递；如果你只想阅读某个类，它本身也很实用。

Claude Code 通过 jvmsrc 解析 HandlerInterceptor 签名——调用 3 次，答案准确，无需遍历缓存。

每天节省的时间与精力

对于使用私有库且没有公开 Javadoc 的 JVM 项目，jvmsrc 能大幅提升效率：

• 每次调查“这个外部类里有什么”时可节省 约 50K 个 token——成本约降低 70%。
• 每天避免 15+ 次 Agent 陷入慌乱的循环——不必再费力翻查 Gradle 缓存、打开错误的 JAR，或放弃尝试。
• 解锁任务委派，处理涉及内部 SDK 的复杂任务；这些任务以前只能由你亲自完成。

实际效果对比

不使用 jvmsrc（盲目折腾 25 轮）

用户： 重写 AbstractTradingService 中的审计钩子——它有可复用的公共实用方法吗？

Agent：

1. 在工作区中搜索 AbstractTradingService.java ➔ 0 hits
2. 运行： find ~/.gradle -name "trading-core*"
3. 找到 4 个版本： 2.1.0、2.3.0、2.4.1、3.0.0-SNAPSHOT
4. 猜测： 选中 trading-core-2.4.1.jar（项目实际使用的是 3.0.0-SNAPSHOT！）
5. 运行： 对错误的 JAR 执行 jar tf 和 javap -p
6. [22 轮后] “我没看到实用方法，你得自己实现。”

实际情况： 3.0.0-SNAPSHOT 新增了 maskSensitiveFields()，正是针对这种情况的受保护辅助方法。Agent 并没有产生幻觉——它只是看不到。

使用 jvmsrc（3 轮即可立即解决）

用户： 重写 AbstractTradingService 中的审计钩子——它有可复用的公共实用方法吗？

Agent：

1. search_classes("AbstractTradingService") ➔ 找到 FQN 和精确解析出的库。
2. get_class_structure(scope: "overview") ➔ 在 3.0.0-SNAPSHOT 中发现 maskSensitiveFields()。
3. get_method_signature("maskSensitiveFields") ➔ 获取准确的签名和泛型。

结果： 首次尝试就正确编写了重写代码。无需遍历缓存、无需猜测、不会用错版本。

工作原理

1. 构建工具查询：jvmsrc 会向你当前使用的构建工具（例如 Gradle）查询精确解析后的类路径配置。
2. **智能缓存：**它会缓存解析后的类路径，并跟踪构建文件的变更以保持最新。
3. **精准 AI 工具：**它不倾倒完整代码，而是提供精准、高粒度的工具（签名、结构、搜索），以缩小上下文窗口并将令牌用量降至极低。

安装与快速入门

1. 安装 CLI

npm install -g jvmsrc

或者通过 npx 直接使用：

npx jvmsrc mcp

重要

需要 Node ≥ 20，且 Java 必须位于 PATH 中（用于 CFR 反编译器和 javap）。

2. 添加 MCP 服务

将以下内容粘贴到你的 AI 助手配置中（Cursor、Claude Code、Windsurf 等），然后重启宿主：

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

可选：运行 jvmsrc config（或 jvmsrc config --project /path/to/gradle-project），即可打印可直接粘贴的配置块和环境提示。大多数用户可以跳过此步骤，直接复制上面的代码片段。

MCP 服务参考

MCP 服务通过 jvmsrc mcp 使用 stdio 运行。默认配置无需环境变量：

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

私有仓库凭据（可选）

仅当你的 Gradle 构建需要凭据环境变量才能访问私有 Maven/Artifactory/Nexus 类仓库时才需要。MCP 宿主通常不会继承你的交互式 shell，因此必须在 jvmsrc MCP 进程上设置这些变量（然后重启服务）。

下面的 REPO_USER / REPO_PASS 仅为示例名称，并非 jvmsrc 必需。请使用项目 Gradle 脚本中说明的变量名称：

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"],
      "env": {
        "REPO_USER": "your-username",
        "REPO_PASS": "your-password"
      }
    }
  }
}

如果项目不需要这些变量，请完全省略 env 块。

Agent 可使用的工具

提示

每个源码响应都包含 sourceAvailable：真实源码（Javadoc、参数名称、泛型）对应 true，CFR 反编译内容对应 false（结构可靠，但名称可能是合成的）。

说明

**多模块：**省略 modulePath 后，jvmsrc 会自动选择唯一的所属模块；若未找到，则会列出候选 modulePath。**方法：**如果索引包含源码增强信息，search_classes 会匹配已声明的方法名称；若要搜索已知 JAR 中的方法体文本，请使用 search_in_artifact。对于未匹配的名称，get_class_source 的 methodNames 也会遍历超类。

让你的 Agent 使用它

工具描述很有帮助，但 Agent 通常更信任内置的 Bash 工具。只需添加两项简单配置，就能让 jvmsrc 成为依赖问题的默认选择。

1. 在 Agent 的指令中添加规则（CLAUDE.md、AGENTS.md、Cursor 规则）——许多客户端根本不会显示 MCP 服务的 instructions：

## Dependencies (jvmsrc)
For any question about a third-party library class, method or version, use the jvmsrc MCP tools
(search_classes → get_class_structure → get_class_source with methodNames; resolve_dependencies for versions).
When working inside one module, pass modulePath (':app' or the file you are editing) to get that module's versions.
Never use javap, unzip/jar on JARs, or ~/.gradle/caches. Code under this repo's src/ → grep/read as usual.

2.（Claude Code）通过钩子屏蔽 Shell 回退方案。 docs/hooks/block-jvm-fallbacks.mjs 会拒绝对 JAR 使用 javap、unzip/jar，以及访问 ~/.gradle/caches / ~/.m2，并告知 Agent 改用 jvmsrc，使其转而使用正确方案，而不是悄悄读取错误的版本。将脚本保存在稳定的位置，并添加到 .claude/settings.json（项目级）或 ~/.claude/settings.json（所有项目）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "node /absolute/path/to/block-jvm-fallbacks.mjs" }]
      }
    ]
  }
}

设置 JVMSRC_HOOK_DISABLE=1 可暂时关闭它。其他客户端有各自的钩子机制；移植前请查看其最新文档。

确认客户端会显示服务指令： 询问 Agent：“jvmsrc MCP 服务提供了哪些指令？” 如果它无法回答，请依赖步骤 1 中的规则。

说明

输入要求宽松。 可省略 projectRoot（将使用工作区，或设置 JVMSRC_PROJECT_ROOT）；modulePath 接受 app、/app、:app，或模块中的文件/目录（省略它或传入 "*"，即可搜索所有模块）；className 接受简单名称、Outer.Inner，或以 .class/.java 结尾的名称。项目上的首次调用会运行 Gradle（通常需要 5–10s）；后续调用将使用缓存。只有在构建文件无法体现的内容发生变化后（例如重新发布了 SNAPSHOT），才传入 forceRefresh: true。

对比

目标受众

主要面向使用 Gradle 的 Java + Spring Boot 项目。其他 JVM 语言（Kotlin、Scala）和 Android 目前也能尽力支持，未来将作为一等目标；详情请参阅 ROADMAP.md。

如果你使用 Maven 或 Bazel，目前已列入计划，但尚未发布。请为代码仓库点星或提交 issue，我会据此安排优先级。

详细参考

jvmsrc com.example.MyClass -p /path/to/gradle-project          # shorthand for get
jvmsrc get com.example.MyClass -p /path/to/project -q > MyClass.java
jvmsrc resolve -p /path/to/project --force-refresh
jvmsrc config jdk-roots add /path/to/jdks                      # one-time JDK roots setup
jvmsrc doctor java -p /path/to/project                         # check JDK requirement + selection
jvmsrc diagnostics last                                         # latest failure message
jvmsrc mcp                                                     # run as MCP server

项目文档

从源代码构建

git clone https://github.com/Sintexer/jvm-source-lens.git
cd jvm-source-lens
bun install && bun run setup:cfr && bun run build
node dist/cli.js --version

完整的贡献者工作流程：CONTRIBUTING.md。

我开发 jvmsrc，是因为我总是遇到同一个难题：Agent 擅长编写 Java，却看不到实际的类路径。如果它能帮你省下和我一样反复折腾 25 轮的时间，那正是它存在的意义。发现了 Bug、有了想法，或者只是想说它帮到了你？欢迎提交 issue 或 PR——我会阅读每一条反馈。

许可证

MIT——详见 LICENSE。