Skip to main content
Glama
java-workbench

java-workbench

by hengdboy

dsh-java-workbench

给 Java/Maven 工程做五件事:陌生工程导读、项目地图、调用链、变更影响、测试反馈。离线解析 pom.xml 和 .java,不跑构建、不联网。

面向 DeepSeek Harness(DSH)插件、MCP agent 和命令行三种入口,同一套实现。

你要的 → 它怎么给 → 省掉什么

你的处境

它给什么

省掉什么

刚接手仓库,先看哪几条链路

jw onboard:按静态可达性排序的核心链路、先读的 8–10 个类型(角色 + 文件行号)、直接关联的测试、明确写出的盲区

从 300 多个入口里瞎点,或者先花半天通读目录

想知道项目全貌

jw map:父 POM、Spring Boot / Java 版本、profile、启动方式、HTTP / @Tool / @Agent / @Scheduled / main 入口、包与文件树

逐个 grep @RestController、翻 pom.xml 拼版本

改一个接口前想知道它怎么跑

jw flow:从入口往下展开调用链,每条边有置信度,三方库边界单独汇总,附 application.yml 配置线索

在十几层调用里靠猜,漏掉 @Bean 装配和配置项

改完不知道会碰坏什么

jw impact:git diff → 变更类型 → 反向依赖 → 受影响入口 → 最小测试集 → 建议命令

全量跑测试,或者凭印象点几个类

测试失败只给一屏日志

jw test:结构化失败用例、断言消息、指向业务代码的栈帧、日志落盘路径、JDK 不匹配提示

翻 target/surefire-reports XML,排查环境问题

Related MCP server: Java JAR MCP Server

30 秒上手

需要 Node ≥ 22.6(DSH 运行时是 24.x)。只有 jw test / java_run_tests 会调用本机的 mvn,其余四个工具不需要 Maven、JDK 或网络。

npm install && npm run build
node lib/cli.js onboard /path/to/project
node lib/cli.js map  /path/to/project --format compact
node lib/cli.js tree /path/to/project --package controller --members
node lib/cli.js flow /path/to/project "POST /api/chat"
node lib/cli.js impact /path/to/project
node lib/cli.js test /path/to/project --test ModelPricingTest --yes

jw 是同一个入口,npm i -g . 之后可直接用。

真实输出(spring-boot + LangChain4j 项目,94 个 Java 文件)

$ jw map /path --format compact
P smart-doc-assistant 0.19.0-SNAPSHOT boot=3.5.13 java=21 modules=1
B pom.xml parent=org.springframework.boot:spring-boot-starter-parent:3.5.13 test="mvn test"
S files=94 tests=12 types=104 packages=12 lines=8358 endpoints=44 tools=10 agents=2
PROFILE mcp 打 classifier=mcp 的包(主类 com.example.assistant.mcp.McpServerStarter)
RUN java -jar target/smart-doc-assistant-0.19.0-SNAPSHOT-mcp.jar main=com.example.assistant.mcp.McpServerStarter
E main com.example.assistant.AssistantApplication com.example.assistant.AssistantApplication#main src/main/java/com/example/assistant/AssistantApplication.java:11
E http POST /api/chat com.example.assistant.controller.AssistantController#chat src/main/java/com/example/assistant/controller/AssistantController.java:65
$ jw onboard /path/to/resumai-backend   # 节选,长链路在终端里不断行
RuoYi-Vue-Plus · maven · 37 模块 · 730 Java 文件 · 357 个 HTTP 入口 · 去重后 324 个入口方法
按静态可达性排序,不代表业务重要性

核心链路 Top 5
1. POST /resumai/resume/upload   ResumeUploadController.upload   …/controller/ResumeUploadController.java:70
   别名:POST /api/v1/resume/upload
   ResumeUploadController → LoginHelper → R → EventLogService → ResumeUploadApplicationService → I18nMessageService → LocaleContextHolder → ResumeServiceImpl~ → ResumeMapper
   到达 11 个项目内类型(7 个 Service/Mapper/组件) · 深度 5 · 15 条候选链路共用下游 · 创建型入口
2. GET /resumai/resume/{id}/structured   ResumeStructuredController.structured   …/controller/ResumeStructuredController.java:63
   别名:GET /api/v1/resume/{id}/structured
   ResumeStructuredController → LoginHelper → R → ResumeServiceImpl~ → ResumeParsingService~ → StringUtils~ → AtsScoreServiceImpl~ → DefaultResumeParser~ → DecryptRequestBodyWrapper~
   到达 11 个项目内类型(5 个 Service/Mapper/组件) · 深度 5 · 15 条候选链路共用下游
3. POST /resumai/resume/{id}/score   ResumeScoringController.score   …/controller/ResumeScoringController.java:63
   别名:POST /api/v1/resume/{id}/score
   ResumeScoringController → LoginHelper → R → EventLogService → ResumeServiceImpl~ → ResolvedResumeInput~ → ResumeParsingService~ → StringUtils~ → LocaleContextHolder~
   到达 11 个项目内类型(4 个 Service/Mapper/组件) · 深度 5 · 15 条候选链路共用下游 · 创建型入口

先读这 10 个类型
   1  ResumeParsingService  4 条链路到达 · Service  …/service/ResumeParsingService.java:21
   2  ResumeServiceImpl     4 条链路到达 · Service  …/impl/ResumeServiceImpl.java:22
   3  EventLogService       3 条链路到达 · Service  …/observability/EventLogService.java:20
$ jw flow /path "POST /api/chat"

调用链(├─ 调用;~ 名字匹配,置信度中/低;[外部] 三方边界;[装配] 框架/配置注入)
├─ ChatAssistant.chat(@MemoryId String sessionId, @V("it") String message)  …/assistant/ChatAssistant.java:29
│     @AiService 接口,LangChain4j 运行时生成代理实现;方法调用会组装消息、读写 ChatMemory、再调用 ChatModel
├─ [外部] ChatMemoryProvider.get()  …/controller/AssistantController.java:69
│     来自 dev.langchain4j.memory.chat.ChatMemoryProvider
  └─ [装配] AiServiceConfig.chatMemoryProvider()  …/config/AiServiceConfig.java:29
        本项目 @Bean 提供 ChatMemoryProvider 的实现

运行期配置线索
  langchain4j.open-ai.chat-model.model-name: qwen3.7-flash-2026-07-15
  langchain4j.open-ai.chat-model.base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
$ jw test /path --test ModelPricingTest --yes
通过 · 4 用例 · failure 0 / error 0 / skipped 0 · 3.4s · JDK 21.0.10 / 目标 21

失败时给到断言原文和业务栈帧(用一个故意写错的测试验证过):

失败 · 3 用例 · failure 1 / error 1 / skipped 0
  ✗ demo.CalcTest.wrong  (failure)
    2+3 应该是 5 ==> expected: <6> but was: <5>
    at demo.CalcTest.wrong(CalcTest.java:6)
  ✗ demo.CalcTest.boom  (error)
    故意炸一个
    at demo.CalcTest.boom(CalcTest.java:7)

在 DSH 里用

插件注册五个工具,名字和 CLI 子命令一一对应:

工具

关键参数

行为

java_project_onboarding

path、limit(1–10)、depth(2–5)、view

核心链路 Top N + 先读类型 + 相关测试 + 盲区;给 agent 的阅读计划

java_project_map

path、view=compact|text|tree、focus、package、members

构建信息 + 入口 + 包/文件树

java_call_flow

path、entry(必填)、depth、view

从入口展开调用链,带置信度与三方边界

java_change_impact

path、base、files、depth

git diff → 反向依赖 → 受影响入口 → 测试集

java_run_tests

path、test、profile、module、javaHome

跑固定形态的 Maven 测试,返回结构化结果;每次都要用户批准

安装到 profile(<profile> 换成你的,例如 headless;桌面版没把 dsh 放进 PATH 时,用应用包内的那一个:/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh):

dsh plugin --profile <profile> add /绝对路径/dsh-java-workbench

这一条就够了:包里带了 dsh.bundle.patch,安装器会把 bundle 追加进 profile 的 package.json,dsh --profile <profile> --dump-config 能看到 # == dsh-java-workbench 节点,不需要手改 cordis.patch.yml。

实测过的一条完整链路:DSH 0.2.2-rc.2 + headless profile,会话里列出 java_project_map、java_project_onboarding、java_call_flow、java_change_impact、java_run_tests 五个工具,并且真的调用了一次 java_project_onboarding(compact 输出)。

桌面版 profile 由应用独占管理,CLI 的 --dump-config 会直接拒绝;在应用内的插件面板里安装本地目录即可,装完重启会话。

在 Claude Code / Cursor 里用(MCP)

{
  "mcpServers": {
    "java-workbench": {
      "command": "node",
      "args": ["/绝对路径/dsh-java-workbench/lib/mcp.js"]
    }
  }
}

MCP 端同样有 java_project_onboarding,另外多一个 java_test_command:只打印将要执行的 Maven 命令,不执行;java_run_tests 必须显式传 confirm: true。没有审批通道的客户端,建议先调 preview,把命令交给用户确认。

第一次怎么用(原话可以直接复制)

命令行,先看全貌再看链路:

node lib/cli.js map     /绝对路径/项目 --format compact
node lib/cli.js onboard /绝对路径/项目

第一条给版本 / 模块 / 入口计数,第二条给 Top 5 链路 + 先读的 10 个类型 + 盲区。730 个 Java 文件的 37 模块工程,第二条大约 2 秒。

DSH 会话里,装好插件重启会话后的第一句。下面三条是 2026-11-13 在 DSH 0.2.2-rc.2 上原样跑过的,把路径换成你自己的:

用 java_project_onboarding 看 /绝对路径/项目,limit=3,view=compact。
把 Top 3 链路和「先读哪几个类型」原样贴出来,不要总结成一段话。

回来的是 ONBOARD ... 一行 + 三条 CORE/PATH + 十行 READ。要求“原样贴出来”是因为 ~(置信度不是 high)和 GAP 盲区这两类信息在被模型转述成一段话时最容易丢。

对同一个项目调 java_call_flow,entry="POST /api/candidates",depth=5,view=compact。
把 FLOW 行、EDGE 行和最后的 BOUNDARY 行原样贴出来,不要替我判断哪个调用更重要。

回来的是逐跳带 d=(深度)和 conf=(置信度)的 EDGE,末尾一行 BOUNDARY 汇总三方调用。[装配] 只在项目里真的用 @Bean 提供实现时才出现,没看到不等于漏了。

我要改 src/main/java/.../CandidateService.java,用 java_change_impact
列出影响类型、受影响入口和最小测试集,给出建议命令但先不要执行测试。

跑测试是唯一有副作用的:DSH 里每次都会弹审批,拒绝就不执行。MCP 客户端没有审批通道,所以先调 java_test_command 拿命令给用户看,确认后再调 java_run_tests 并带 confirm: true。

第一次别期待这些:排序只代表静态可达性,不代表业务重要性;Gradle 工程只会告诉你不支持;MQ 监听、@Async、反射和动态代理追不到;没有任何运行时数据。

它到底解析了什么

Maven(离线):沿 relativePath 找父 POM,找不到再读 ~/.m2/repository;父 POM 与 BOM 的属性各自插值;合并 dependencyManagement、scope=import 的 BOM、模块列表、profile(JDK 条件、额外依赖、classifier 打包)、插件 execution。网络不可达也能出结果,读不到的 BOM 会记成 warning,不编造版本。

Java:用 java-parser 的 CST 而不是正则。收集类型/字段/方法/构造器、注解、HTTP 映射(类级和方法级都支持多个路径,按前缀 × 方法路径展开)、@Tool / @Agent / @Scheduled 入口,以及 token 级的调用点。Maven 的 <modules> 会递归展开,RuoYi / Spring Cloud 这种“聚合模块里再套聚合模块”的结构不会漏。传项目目录或直接传 pom.xml 都可以,项目根统一取文件所在目录。

调用链置信度:

  • high:字段类型、方法参数类型、本类方法、或全项目唯一同名方法,能定位到定义

  • medium:只靠方法名唯一匹配;字段声明成接口时,向下找到项目内唯一的实现类(标“接口 X 的实现”)

  • low:多个候选里挑了一个(多个实现类、多个同名方法)

  • 重载:按调用点的实参个数选方法,不会把 f(a, b) 算到 f(a, b, c) 上

  • [外部]:三方库,尽量用 import 标出来源包;没有项目内实现的接口(例如 MyBatis Mapper)也留在这里;链式调用/方法返回值不按同名硬猜,直接记为外部边界

  • [装配]:@Bean 提供的实现,按返回类型关联

变更影响:git diff 拿到变更文件 → 映射到类型 → 建反向依赖图(默认追 2 层)→ 找受影响的入口 → 按 import 和类名匹配测试类。每一条都带“为什么被算进来”。反向依赖和 flow 共用同一套调用解析:字段声明成接口时,调用方会同时记到接口和实现类上,改 ScoreServiceImpl 也能把只依赖 ScoreService 的 Controller 找出来。base 会先经 git rev-parse 解析成提交 SHA 再参与 diff,以 - 开头的值直接拒绝;--max-chars 控制输出预算。

调用解析只有一份:flow(正向展开)和 impact(反向依赖)都走 src/core/resolve.ts,字段 / 参数 / 静态调用 / 接口实现 / @Bean / 链式边界的判定不会两边漂移。CLI、DSH 工具和 MCP 三个入口也只走 src/ops,参数裁剪(深度、步数、字符预算)和“入口没找到”的提示保持一致。

核心链路导读:先把同一个方法因类级多路径产生的别名合并成一条入口;入口方法不超过 60 个时全部展开,超过 60 个才采样——采样只看 Controller 注入的业务类型数(字段和构造器参数都算)以及是不是写入口,不看方法体里的调用点数量,否则“一行委托给 Service”的正常写法和构造器注入的 Controller 会被日志最多的接口挤掉。每条候选按 traceEntry 展开后,再按“到达的 Service/Mapper/组件数、项目内类型总数、被多少条链路共用的业务下游、直接关联测试数”打分,创建型入口(POST 集合路径)略加分,/demo、/debug、/health 这类辅助路径降权。R、StringUtils 这类全局工具不计入共用度,否则每条链路都会得到同一个大数字。没有任何项目内调用的入口(健康检查、静态响应)不占推荐位;下游重合度 ≥ 0.8 的入口合并,并在盲区里写出被合并的是谁。排名只说明静态可达性,不冒充业务重要性;MQ 监听、@Async、反射和动态代理没有静态入口,会明确列为盲区。项目里一个入口都识别不到时,降级成按被调用次数推荐类型,并标明这是降级结果。

测试:只允许 mvn test 加 -Dtest / -P / -pl 三种形态,不接受任意 goal;环境变量走白名单;输出最多 2MB,完整日志落到 .dsh/java-workbench/runs/;超时和取消都杀进程组;surefire 报告递归扫描所有模块,并按本次运行的 mtime 过滤,不会把上次的失败算进来;用 mvn -v 读实际 JDK,和 pom.xml 目标版本不一致时给出可直接执行的修复命令。pom 里 skipTests=true、没有 surefire 报告、或报告里 0 个用例时,都明确报“未执行”,不会把“什么都没跑”显示成通过。

实测

在 langchain4j-in-production/smart-doc-assistant(94 个 Java 文件、8358 行、12 个包、44 个 HTTP 端点、10 个 @Tool、2 个 @Agent)上:

  • 全量解析约 0.3s(jw map 统计口径),无网络

  • 正确读出 parent spring-boot-starter-parent:3.5.13、Java 21、beta32 固定版本、mcp profile 的 classifier 与主类

  • jw flow "POST /api/chat" 解析出 ChatAssistant 的 @AiService 代理、ChatMemoryProvider 的三方边界和对应的 @Bean 装配

  • jw onboard 0.8s 给出 5 条链路:EngineeringAgent 对话(9 个项目内类型、5 个关联测试)排第 1,文档入库 ingest(4 个项目内类型、4 个 Service)第 2,随后是 RAG 评测、语义搜索、条件式 agentic 入口

  • jw test --test ModelPricingTest 在 JDK 21 下 3.4s 通过 4 个用例;同一命令在 JDK 25 下编译失败时,工具报告 mvn 用的是 Java 25.0.2,项目目标是 Java 21 并给出 export JAVA_HOME=$(/usr/libexec/java_home -v 21)

在 resumai-backend(RuoYi 多模块,根 POM 下两层聚合模块,734 个 Java 文件、87,275 行、37 个模块、357 个 HTTP 端点)上:

  • 全量解析 1.66s,无网络;递归索引到 ruoyi-modules/ruoyi-resumai、ruoyi-common/ruoyi-common-* 等二级子模块

  • 类级 @RequestMapping({"/resumai/ai", "/api/v1/ai"}) 正确展开成两条入口,而不是拼成 /resumai/ai/api/v1/ai/...

  • jw flow "POST /api/v1/ai/score" 从接口字段 IAtsScoreService 下钻到 AtsScoreServiceImpl,再按实参个数选中 7 参重载,继续展开到 AtsScoringEngine

  • jw onboard 1.9s 从 324 个入口方法里采样 60 个候选,Top 3 是简历上传、结构化解析、ATS 评分三条产品链路,第 4 才是注册;类级双路径产生的 /api/v1/... 作为别名合并,没有重复占位

  • jw impact --file .../IAtsScoreService.java --depth 3 列出 9 个反向依赖类型、42 个受影响入口,并带上“为什么被算进来”

  • 改成实现类 AtsScoreServiceImpl.java 后同样能反查到 5 个只依赖接口的 Controller、32 个入口;via 写明“接口 IAtsScoreService 的实现”

  • jw test --test ParamUnitTest --module ruoyi-admin 读到 pom 的 skipTests=true,明确报“未执行”并给出去掉该属性的提示,而不是误报通过

在 langchain4j-in-production/hiring-ai-assistant(83 个 Java 文件、21 个 HTTP 端点、37 个入口方法)上:

  • jw onboard 0.6s:投递入口 POST /api/candidates(8 个项目内类型、5 个 Service、5 个关联测试)排第 1,评审、事件推送、面试完成紧随其后

  • POST /api/demo/run 在结构上同样穿透到 pipeline,被辅助路径降权后落到第 3,输出里写明“demo/debug 类入口,已降权”

  • 这一组是排名回归的起因:早期版本按方法体里的调用点数量预筛候选,一行委托给 Service 的 submit 直接落榜,所以现在的预筛只看注入的业务类型数和是否写入口

安全边界

  • 前四个工具只读:只读 pom.xml、.java、application.yml 和 git diff,不改文件

  • flow 输出的配置线索会按 key 脱敏:api-key、password、token、secret 等值显示为 ***(已脱敏),${ENV} 占位符保留

  • java_run_tests 是唯一有副作用的工具:命令形态固定、逐次审批、无审批通道时失败关闭

  • 测试产物只写到项目自己的 target/ 和 .dsh/java-workbench/runs/

  • MCP 端没有审批服务,用 confirm: true 作为显式同意位

已知边界

  • Gradle:只识别工程类型,不解析构建模型(v0.1 不支持)

  • 调用点是 token 级判断,不做完整类型推导:链式调用、局部变量、反射、动态代理、AOP 织入都可能标成 medium / low / [外部],不会假装确定

  • 接口实现只在项目内找;@Mapper、Feign、运行时生成代理这类没有源码实现的接口,仍然停在接口/三方边界

  • 多模块:传根目录会递归聚合所有层级的 <modules>;只传子模块目录时只索引该模块

  • JDK:用 mvn 实际使用的 JDK,不自动切换;只在结果里提示怎么切

  • 大仓库:所有输出都有字符预算(默认 6k–12k),超出会明确标截断

  • 导读排名是启发式:只看静态可达性和测试关联,不读业务语义;入口超过 60 个时只采样前 60 个候选,并在盲区里写明

  • 想要运行时链路(APM、火焰图)的,不在这个工具的范围内

开发

npm run build        # tsc → lib/
npm run smoke        # 对示例项目跑一次 map
npm run probe        # 在真实 cordis 容器 + 官方 native executor 里验收五个工具
node lib/cli.js --help

npm run probe 会验证:工具注册与 schema、必填参数校验、输出 schema、无审批时失败关闭、审批通过后真的跑完 Maven 并解析 surefire。

第 5、7 步用的是一个故意失败的临时最小工程 /tmp/jw-fail(一个 pom.xml + demo.CalcTest,一条断言失败、一条抛异常)。macOS 重启会清空 /tmp,重建后再跑,否则这两步会报“没有找到 Java 源码”。

src/core/    Maven 模型、Java 索引、入口、调用链、影响分析、链路导读
src/render/  文本 / compact / 树 / 流程 / 影响 / 测试 / 导读的渲染
src/exec/    Maven 测试执行与 surefire 解析
src/ops/     纯操作层,CLI、DSH 工具、MCP 共用
src/tools/   DSH defineTool 定义(含审批门禁)
src/cli.ts   jw 命令
src/mcp.ts   MCP stdio 服务器
src/index.ts DSH 插件入口

发布前检查见 docs/release-checklist.md。

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to look up Java class definitions and list dependencies from Maven projects by analyzing local JAR files via the Model Context Protocol.
      12 npm
      4
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Analyzes Java Spring Boot Maven repositories by scanning source code, building a dependency graph, and exposing tools for architecture overview, change impact, dependency cycles, rule validation, and refactoring targets so LLMs can answer architecture questions without rereading the codebase.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to perform Java semantic navigation, diagnostics, compilation, JUnit testing, debugging, coverage, affected-test discovery, and safe refactoring previews without modifying source files.
      MIT