Understand-Anything 的 Java 语言上下文片段：java.md 如何驱动知识图谱分析

在 Understand-Anything 项目中，understand-anything-plugin/skills/understand/languages/java.md 是一份"语言提示词片段"（Language Prompt Snippet）：当 /understand 技能扫描到一个 Java 代码库时，该文件会被整体注入到架构分析子代理的提示词中，指导 LLM 正确识别 Java/Spring 项目的关键概念、导入模式、目录约定与常见框架，从而生成更准确的架构分层与节点摘要。读完后，你能掌握这份 Java 片段在分析流水线中的注入时机、每个章节的具体作用，以及它与 core 包中 Java 语言配置、tree-sitter 提取器、语言课程生成器之间的协同关系。

文档定位：一段被注入的提示词，而非独立程序

java.md 本身不执行任何逻辑，它是 /understand 技能 Phase 4（ARCHITECTURE）阶段的上下文素材。SKILL.md 在 Phase 4 明确规定：

Language context injection: For each language detected in Phase 1 … read the file at ./languages/<language-id>.md (e.g., ./languages/python.md, ./languages/dockerfile.md) and append its content after the base template under a ## Language Context header. If the file does not exist for a detected language, skip it silently and continue.

也就是说，当 Phase 1 扫描结果的语言列表中检出 java 时，主会话会读取 ./languages/java.md（即本文分析的 java.md），并将其全文追加到 architecture-analyzer 的基础模板之后。如果某语言没有对应片段文件，流水线会静默跳过——这解释了为什么 languages/ 目录只收录了需要"语言感知"的文件类型。

此外，该片段还提供"非代码语言"的边缘（edge）模式与摘要风格参考：SKILL.md 特别强调 "Include non-code language snippets — they provide edge patterns and summary styles for non-code files"。对 Java 这类纯代码语言，片段的价值则集中在概念清单与框架提示上。

Key Concepts：10 个需要 LLM 主动识别的 Java 概念

原文档的第一节列出了 10 个关键概念，这是提示词中最核心的部分——它告诉分析代理"在 Java 代码中应重点留意这些模式"：

概念	要点
Generics (with Erasure)	泛型在运行时被擦除，仅提供编译期类型安全
Annotations	元数据标记（如 @Override、@Autowired），在编译期或运行时被处理
Interfaces and Abstract Classes	契约 + default 方法（Java 8+）与部分实现
Streams API	集合上的函数式管道操作（filter、map、reduce）
Lambdas	面向函数式接口的简洁匿名函数语法
Sealed Classes	受限类层次结构，显式声明允许的子类（Java 17+）
Records	不可变数据载体，自动生成访问器、equals、hashCode（Java 16+）
Dependency Injection	IoC 模式，Spring 的核心；支持构造器、字段或方法注入
Checked vs Unchecked Exceptions	受检异常必须声明或捕获；非受检异常继承 RuntimeException
Optional	可空值的容器，鼓励显式处理而非 null 检查

这份清单与 core 包中的机器可读配置形成了双轨印证。java.ts 中定义了 javaConfig，其 concepts 数组恰好是上述概念的简写版：

concepts: [
  "generics",
  "annotations",
  "interfaces",
  "abstract classes",
  "streams API",
  "lambdas",
  "sealed classes",
  "records",
  "dependency injection",
  "checked exceptions",
],

两者用途不同：java.md 面向 LLM 提示词，提供带解释的完整描述；javaConfig.concepts 则参与确定性的概念检测——language-lesson.ts 中的 buildConceptPatterns 会把语言配置里的每个 concept 合并进基础概念模式表（若基础表未收录该概念，则以概念名的小写形式作为检测关键词），随后 detectLanguageConcepts 在节点的 tags、summary 和 languageNotes 中做关键词匹配，命中后 buildLanguageLessonPrompt 会要求 LLM 针对这些概念生成 languageLesson。也就是说，java.md 里写的 "Generics (with Erasure)"、"Records" 等条目，最终会通过这条链路体现为知识图谱节点上的语言教学注记。

Import Patterns：Java 的三种导入语法

原文档给出 Java 导入语句的三种形式，供分析器识别 imports 边时参照：

import package.Class;              // 导入特定类
import package.*;                  // 通配符导入包下所有类
import static package.Class.method; // 静态导入，直接访问方法/常量

这些模式在确定性提取层有对应的实现基础。file-analyzer.md 说明捆绑脚本通过 tree-sitter 支持 10 种代码语言的结构性提取，Java 在列（"TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, PHP, C/C++, C#"）。java-extractor.ts 中可以看到 Java 专用提取逻辑：例如 extractScopedIdentifierPath 专门处理 Java 嵌套递归的 scoped_identifier 节点（java.util.List 在语法树中是三层嵌套的 scope/name 结构），lastComponent 则将完整限定名截取为最后一段（java.util.List → List）用于符号匹配。提示词中的"导入语法三形态"与提取器中的"语法树解析细节"互为表里：前者让 LLM 理解 import 的语义，后者让脚本直接解析出 imports 边而无需 LLM 参与。

File Patterns：Maven/Gradle 标准布局约定

原文档列出五个文件/目录模式，用于帮助分析器快速定位 Java 项目的骨架：

• src/main/java/ — 遵循 Maven/Gradle 标准布局的源码根目录
• src/test/java/ — 测试源码根，包结构与主源码镜像对应
• pom.xml — Maven 项目配置与依赖管理
• build.gradle — Gradle 构建脚本（Groovy 或 Kotlin DSL）
• Application.java — 带 @SpringBootApplication 的 Spring Boot 入口点

这些约定同时出现在仓库的三处机器可读位置，构成"提示词—配置—模式匹配"的一致性：

1. 语言配置的 filePatterns：java.ts 定义了入口点 glob（**/Application.java、**/Main.java、src/main/java/**/App.java）、测试文件 glob（*Test.java、*Tests.java、*IT.java）以及配置文件 glob（pom.xml、build.gradle、build.gradle.kts）。
2. 架构分析器的目录模式表：architecture-analyzer.md 的目录模式匹配表中专门为 Java 留了条目——src/main/java → service 层、src/test/java → test 层、文件名为 Application.java → entry、pom.xml/build.gradle → config、*Test.java → test。这与 java.md 的 File Patterns 一节完全对齐。
3. Phase 0 入口点探测：SKILL.md 的预检阶段把 src/main/java/**/Application.java 列入入口点候选清单，命中后作为 $ENTRY_POINT 供 Phase 5 的 tour-builder 用作学习导览的起点。

因此，java.md 中"Application.java 是 Spring Boot 入口"这条看似常识的说明，实际上贯穿了入口点探测、目录分组、层分配三个环节。

Common Frameworks：五个主流框架及其图谱语义

原文档点名五个 Java 生态框架：

• Spring Boot — 面向生产就绪 Spring 应用的强约定框架
• Jakarta EE — 企业级 Java 标准（原 Java EE）
• Quarkus — 针对 GraalVM 与容器优化的云原生框架
• Micronaut — 面向微服务与 serverless 的编译期 DI 框架
• Hibernate — 实现 JPA 规范的 ORM 框架

其中 Spring Boot 拥有独立的框架附录文件 spring.md：当 Phase 1 检出 Spring Boot 框架时，SKILL.md 的 Framework addendum injection 步骤会把该附录全文追加到语言上下文之后。spring.md 定义了 Spring 项目特有的文件角色表（*Controller.java → api-handler、*Repository.java → data-model、*Entity.java → data-model 等）、应识别的边模式（@Autowired 注入产生 depends_on 边、Controller→Service→Repository 链、@Configuration 的 @Bean 方法产生 configures 边），以及推荐的 Spring 分层（layer:api / layer:service / layer:data / layer:types / layer:config / layer:middleware / layer:test）。这解释了 java.md 的 Key Concepts 中为何把 "Dependency Injection: IoC pattern central to Spring" 单列一条——它是连接语言概念与 Spring 框架附录的枢纽。

core 包同样注册了 Spring 框架配置（packages/core/src/languages/frameworks/spring.ts），供 FrameworkRegistry 做确定性的框架识别，与提示词侧的 spring.md 附录形成同构的双轨。

Example Language Notes：languageNotes 的书写范式

原文档末尾给出两段示例性语言注记，演示了理想 languageNotes 字段的风格——结合具体代码事实、附带工程理由：

Uses @Autowired annotation for constructor injection, following Spring IoC container pattern. Constructor injection is preferred over field injection because it makes dependencies explicit and enables immutability.

The Maven standard directory layout (src/main/java, src/test/java) is a strong convention — most build tools and IDEs expect this structure by default.

这两条示例与仓库其他位置的规定相互呼应：

• file-analyzer.md 要求 languageNotes 仅"当结构数据揭示出真正有教育意义的语言特定模式时"才添加（"Only add this when genuinely educational"），示例注记正是这种"值得写"的典型：构造器注入优于字段注入的取舍、Maven 布局是强约定。
• tour-builder.md 的 languageLesson 示例展示了同类风格（如 TypeScript barrel 文件、SQL 迁移幂等性），并建议对 "generic"、"closure" 等术语做"英文术语 + 本地化翻译"的双语解释——这与 SKILL.md 中 $LANGUAGE_DIRECTIVE 的 "Keep technical terms in English when no standard translation exists" 要求一致。
• 生成链路上，buildLanguageLessonPrompt 会先由 detectLanguageConcepts 预检测出概念（如 "dependency injection" 命中 "inject/provider/container/di" 关键词组），再要求 LLM 输出 { languageNotes, concepts } JSON，parseLanguageLessonResponse 则带失败兜底地解析（解析失败返回空 notes 与空 concepts，不阻断流水线）。

一次 Java 项目分析中 java.md 的完整生命周期

把上述证据串起来，可以还原出 java.md 在 /understand 流水线中的实际参与路径：

1. Phase 1（SCAN）：scan-project.mjs 扫描文件，java.ts 的 extensions: [".java"] 与 tree-sitter 配置（tree-sitter-java wasm 包）确定 Java 文件被识别并解析出结构（函数、类、导入等，由 java-extractor.ts 完成）；语言列表中出现 java。
2. Phase 2（ANALYZE）：file-analyzer 子代理基于预解析的导入数据与结构输出 GraphNode/GraphEdge；imports 边由脚本确定性产出，LLM 只补充语义边。
3. Phase 4（ARCHITECTURE）：主会话读取 languages/java.md 全文并追加为 ## Language Context；若同时检出 Spring Boot，再追加 frameworks/spring.md。architecture-analyzer 借助这份上下文完成 3–10 个层的划分（Java 项目典型结果是 API / Service / Data / Config / Test 等 Spring 分层）。
4. Phase 5（TOUR）及之后：tour-builder 依据 $ENTRY_POINT（Phase 0 按 src/main/java/**/Application.java 模式探测）组织导览；languageNotes/languageLesson 由 language-lesson 链路结合概念检测生成。

小结

understand-anything-plugin/skills/understand/languages/java.md 是 Understand-Anything"语言感知分析"机制中 Java 语言的一份提示词素材。它用 10 个概念、3 种导入语法、5 个文件模式、5 个框架和 2 条示例注记，把 Java 生态的关键约定浓缩进 LLM 的上下文；而 packages/core/src/languages/configs/java.ts、plugins/extractors/java-extractor.ts、analyzer/language-lesson.ts 与 agents/architecture-analyzer.md 中的目录模式表则从确定性侧提供了同构的规则。理解这一"提示词 + 确定性提取"的双轨设计，是理解 Understand-Anything 如何为不同语言生成高质量知识图谱的钥匙。