用途
JavaLens 存在的理由是：AI 系统需要编译器级准确的洞察，而仅仅阅读源码文件无法提供这一点。当 AI 使用 grep 或 Read 查找某个方法的用法时，它无法区分：方法调用与无关类中同名的方法；字段读取与字段写入；接口实现与无关类；对类型的强制转换与该类型的其他引用。这会导致错误的重构、遗漏的用法以及对代码行为不完整的理解。JavaLens 为 AI 智能体提供语义 Java 代码分析。
主要能力
JavaLens 是一个 MCP 服务器，为 Java 提供约 75 个语义分析工具，直接构建在 Eclipse JDT 之上，以实现编译器级准确的代码理解。它提供超越简单文本搜索的语义分析、导航、重构和代码智能工具。
Language Server Protocol 是为 IDE 自动补全和基本导航设计的，并非为需要深度语义分析的 AI 智能体工作流而设计。JavaLens 通过 OSGi 直接封装 Eclipse JDT Core，提供：细粒度引用类型——精确查找强制转换、注解、throws 子句、catch 块、instanceof 检查、方法引用、类型参数；读与写访问区分——跟踪字段被修改与仅被读取的位置；索引化搜索——JDT 在加载时预建索引，因此符号/引用查询无需遍历源文件；完整 AST 访问——用于复杂重构的直接操作。
编译器级分析方面，JavaLens 通过 Eclipse JDT（驱动 Eclipse IDE 的同一引擎）提供编译器级代码分析。不同于文本搜索，JDT 能理解：跨继承体系的类型解析、方法重载与覆写、泛型类型参数、导入解析与类路径依赖、从 Java 1.1 到 Java 25 的 Java 源码（Markdown Javadoc、模块导入、紧凑源文件、灵活构造器体），以及 Lombok 生成的成员——捆绑的代理使 @Data 访问器等能够解析，因此使用它们的代码不会被标记为未定义。
工具按类别组织：导航（10 个工具）、细粒度引用搜索（9 个工具，使用 JDT 独有的引用类型常量，LSP 不提供）、分析（20 个工具）、复合分析（4 个工具，合并多个查询以减少往返）、重构（16 个工具）、快速修复（5 个工具）、度量（5 个工具）、项目与基础设施（6 个工具）。
使用方式
运行要求：Java 21 或更高版本（必须在 PATH 中或设置 JAVA_HOME）——两条安装路径都需要。Node.js 18+——仅在使用 npm/npx 安装路径时需要。JavaLens 是分析服务器而非编译器。它使用 Eclipse JDT 2025-12 解析和理解 Java 1.1 至 25 的源码。Java 21 仅作为服务器运行时要求。
从 GitHub Releases 安装（推荐——仅需 Java）：从 Releases 下载并解压到任意位置（例如 /opt/javalens 或 C:\javalens），然后将 MCP 客户端指向捆绑的 jar。
通过 npm 安装（需要 Node.js 18+）：如果已有 Node.js，npx 会在首次运行时下载并缓存 JavaLens 发行版（约 23 MB）。
配置 MCP 客户端：添加到 MCP 配置（例如 Claude Code 的 .mcp.json）。-data 参数指定 JavaLens 存储工作区元数据的位置。
自动加载项目：设置 JAVA_PROJECT_PATH 以在服务器启动时自动加载项目。注意：项目加载在后台异步进行。MCP 服务器在项目加载时立即响应。使用 health_check 监控加载状态——在完成前会显示 "project.status": "loading"，准备好后显示 "loaded"。
工作区机制：与内存代码模型不同，Eclipse JDT 需要工作区目录来存储搜索索引（用于快速符号查找）、编译状态和缓存、项目元数据。工作区位于源码之外以避免污染源码树、避免冲突、实现会话隔离。会话生命周期：JavaLens 启动并创建唯一工作区 {base}/{uuid}/；load_project 创建指向源码的链接文件夹；JDT 在工作区（而非项目）中建立索引；会话结束时清理工作区。
坐标系统：所有行/列参数从零开始（第 0 行、第 0 列 = 文件第一个字符）；响应路径默认相对；所有路径使用正斜杠以跨平台一致；输入路径可相对或绝对。
磁盘同步：每个答案在查询时都会与磁盘上的文件进行验证。在任何工具逻辑运行前，JavaLens 对已知源文件做内容哈希，检测编辑、新增和删除（智能体不报告——服务器自行发现变更），精确修复变更部分，等待搜索索引吸收修复，然后才作答。没有文件监视器，也没有后台线程——验证在智能体发出的查询内同步进行，因此没有竞态条件。智能体的循环就是：编辑 → 查询。load_project 仅在首次使用时、响应报告 RELOAD_REQUIRED 时（例如 pom.xml 等构建文件变化需要重建类路径），或从头重建一切时需要。如果验证本身失败，查询返回 VERIFICATION_FAILED 而非未验证的答案。成本：验证基于哈希且并行——实测 72 文件项目每次查询约 2 ms，1,000 文件约 25 ms，10,000 文件约 180 ms。修复只花费变更部分（一个被编辑文件在一秒内完成协调），从不全量重建索引。手动模式：设置 JAVALENS_DISK_SYNC=manual 可恢复 1.5.0 之前的契约——答案反映上次加载状态，智能体在编辑文件后调用 load_project。
重构返回编辑内容：重构工具返回文本编辑但不修改文件。这样可以先看到将发生的变化再应用。所有重构工具返回文本编辑（以及重构创建新文件时的文件内容），而不是直接应用变更。
会话隔离：每个 MCP 会话独立，拥有自己的工作区 UUID。多个会话可以并发分析同一项目。
构建系统支持：JavaLens 加载三种真实构建系统以及普通 Java 目录。每个都在 CI 中针对合成的真实形态夹具（带跨模块依赖的多模块反应器、真实外部库、注解处理器）进行端到端测试。项目加载期间会调用 mvn/gradle 子进程。如果工具缺失或失败，JavaLens 会在 load_project 响应中显示结构化 LoadWarning（例如 MAVEN_SUBPROCESS_FAILED、GRADLE_SUBPROCESS_FAILED、COMPLIANCE_LEVEL_UNKNOWN），让调用者知道分析质量下降，而不是静默地得到空类路径。
从源码构建：发行版输出到 org.javalens.product/target/products/。构建要求：Java 21+（服务器运行时）、Maven 3.9+（包含包装器 ./mvnw）。运行完整测试套件（包含针对真实 Maven、Gradle 和 Bazel 构建的端到端测试）还要求相应工具在 PATH 中：Maven（由包装器提供）、Bazel 9+（或 bazelisk）。测试在开发者机器上缺失工具时会优雅跳过。设置 JAVALENS_TESTS_REQUIRE_TOOLS=true 可翻转门控：缺失工具导致硬失败而非跳过。CI 在设置此标志下运行，因此任何配置缺口都会成为真实失败，而不是静默削弱测试套件。构建系统覆盖结构为针对每个 bug 的聚焦测试加上真实的端到端测试。端到端测试为每个构建系统加载一个代表性项目，一次遍历中覆盖所有修复——带 Lombok APT 和跨模块引用的多模块 Maven；带注解处理器的多项目 Gradle；带跨目标依赖的多目标 Bazel。CI 在 Linux、macOS 和 Windows 上运行它们。
AI 训练偏差警告：AI 模型可能表现出对原生工具（Grep、Read、LSP）而非 MCP 服务器工具的训练偏差，即使语义分析提供更好的结果。原因：训练数据包含大量 grep/文本搜索模式；原生工具在模型经验中“始终可用”；模型可能无法识别何时语义分析更优。为获得最佳结果，在项目指令或系统提示中（例如 Claude Code 的 CLAUDE.md）添加指引。
许可证：MIT License。
适用场景
适合让 AI 助手在 Java 项目中执行需要编译器级准确理解的任务：跨继承体系与方法重载/覆写的符号解析、精确查找方法调用与字段读写、细粒度引用定位（强制转换、注解、throws、catch、instanceof、方法引用、类型参数）、安全重构（以文本编辑形式预览）、代码度量，以及分析带 Lombok 注解或使用 Java 25 新特性的代码。也适合多模块 Maven/Gradle/Bazel 项目的并发分析（会话隔离）。
限制
JavaLens 是分析服务器而非编译器。运行需要 Java 21+；npm 安装路径额外需要 Node.js 18+。源码解析支持 Java 1.1 至 25。重构工具不直接修改文件，而是返回文本编辑。项目加载异步进行，需通过 health_check 监控状态。构建系统加载依赖 mvn/gradle 子进程，工具缺失或失败时分析质量会下降并通过 LoadWarning 提示。验证失败时返回 VERIFICATION_FAILED 而不提供未验证答案。
