Skip to main content
Glama
java-workbench

java-workbench

by hengdboy
README.md
# 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,排查环境问题 |

## 30 秒上手

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

```bash
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 文件)

```text
$ 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
```

```text
$ 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
```

```text
$ 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
```

```text
$ jw test /path --test ModelPricingTest --yes
通过 · 4 用例 · failure 0 / error 0 / skipped 0 · 3.4s · JDK 21.0.10 / 目标 21
```

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

```text
失败 · 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`):

```bash
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)

```json
{
  "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,把命令交给用户确认。

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

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

```bash
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 上原样跑过的,把路径换成你自己的:

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

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

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

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

```text
我要改 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、火焰图)的,不在这个工具的范围内

## 开发

```bash
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](docs/release-checklist.md)。

## License

MIT