技术摘要：Code2UML——基于上下文工程的智能体 LLM 用于可扩展的软件可视化

问题陈述

软件文档，尤其是保持最新状态的 UML 图，常因人工创建成本高且易出错而被忽视。虽然大语言模型（LLM）为自动化此任务提供了潜力，但在应用于真实世界代码库时，它们面临根本性的可扩展性障碍。中大型项目的中间表示（IR）往往超出即使是最先进 LLM 的有效上下文窗口。试图将整个代码库表示输入到单次 LLM 调用的朴素方法会导致输出截断、关系幻觉，以及无法捕捉具有架构重要性的结构。此外，UML 图类型的多样性（例如类图、序列图、部署图）需要不同的表示规则和信息服务，使得“一刀切”的生成方法显得不足。

方法论

本文介绍了 Code2UML，这是一种智能体架构，旨在直接从源代码仓库生成 UML 图，同时遵守 LLM 的上下文约束。该系统基于 Claude Agent SDK（使用 Claude Sonnet 4.6）构建，并通过四个阶段的流水线运行：

1. IR 生成与规范化：使用 Tree-sitter 解析 Java、Python、JavaScript 和 PHP 源代码，生成与语言无关的 JSON 中间表示（IR）。一个确定性的后处理步骤将特定于语言的构造（例如访问修饰符、继承）规范化为统一的模式。
2. 上下文工程（IR 视图生成）：为了解决上下文限制，系统采用了一个确定性的、基于重要性的 IR 压缩层。这种纯 Python 转换将完整的项目 IR 转换为特定于图的视图，并保证符合令牌约束（单路径为 60 KB，深路径为 100 KB）。
   • 机制：它根据特定于图类型的重要性分数（例如方法数量、继承存在性）对元素进行排名，并应用迭代收缩。如果超过目标大小，元素预算将减半。
   • 效率：此过程不需要 LLM 调用，并在毫秒级内完成。
3. 多智能体架构：系统利用一个由五个专用智能体组成的层级结构，每个智能体解决不同的认知子任务：
   • PlannerAgent（规划智能体）：根据项目规模将项目分解为逻辑范围（工作流/模块）。
   • AnalyzerAgent（分析智能体）：读取规划器识别的特定源文件，以提取每个范围的高信号上下文（调用链、关系）。多个智能体并行运行。
   • DiagramAgent（绘图智能体）：基于压缩后的 IR 视图（用于架构概览）或丰富的上下文（用于详细的行为/结构图）生成最终的 PlantUML 代码。
   • CorrectorAgent（修正智能体）：使用特定于图类型的规则集验证并修复生成的 .puml 文件中的语法错误。
   • DependencyAnalyzerAgent（依赖分析智能体）：独立分析第三方库的源代码。
4. 编排策略：系统采用两级路由策略：
   • SINGLE 路径：用于架构概览（组件图、部署图、系统上下文图），调用单个 DiagramAgent。
   • DEEP 路径：用于详细图（类图、序列图、活动图、用例图），调用包含流水线修正的三阶段流水线（规划器 → 分析器 → 绘图）。

主要贡献

本文声称有三个主要贡献：

1. 确定性上下文工程：一种新颖的方法，优化的是数据负载而不仅仅是提示文本。它在无需 LLM 调用的情况下，将大型 IR 转换为紧凑的、特定于图的视图，确保具有架构重要性的元素在激进压缩比下得以保留。与检索增强生成（RAG）不同，该方法在结构化 IR 上运行，并采用确定性评分。
2. 专用多智能体层级：一个由五个智能体组成的框架，取代了单体提示方法。这种关注点的分离允许对规划、分析、生成和验证进行独立优化，反映了既定的软件工程原则。
3. 全面的实证评估：在 12 个开源仓库（涵盖 4 种语言，规模跨越两个数量级，从 31 到 4,578 个 IR 实体）和 7 种 UML 图类型上进行了严格评估，生成了 84 个观测值，并在五个自动化指标上进行了评估。

结果

该系统在五个自动化指标上进行了评估：语法有效性、实体召回率、关系精确度、结构质量和结构复杂度指数（SCI）。

• 语法有效性：系统实现了 91.5% 的平均有效性。组件图和部署图达到了 100% 的有效性。系统上下文图的有效性最低（58.3%），这是由于 C4 模型构造型的复杂性所致。
• 关系精确度：平均精确度为 0.858，表明生成的绝大多数关系连接的是源代码中实际声明的实体，幻觉极少。
• 结构质量：平均质量得分为 81.7/100。关键在于，质量得分在项目规模范围内（从 77.5 到 83.6）保持稳定，证明上下文工程层无论规模如何都能成功维持图表质量。
• 实体召回率：平均召回率为 0.313。这被解释为一种有意的架构优先级排序，而非失败；系统关注重要结构而非全面覆盖。类图实现了最高的召回率（0.445），而用例图最低（0.165），这与其抽象性质一致。
• 跨语言一致性：在 Java、JavaScript、PHP 和 Python 之间，性能高度一致，不同语言间的质量得分差异仅为 0.6 分。
• 可扩展性：敏感性分析证实，随着 IR 实体数量从 31 增加到 4,578，质量并未下降。

意义与主张

本文提出，Code2UML 解决了当前基于 LLM 的软件工程工具的一个关键局限性：在上下文窗口约束内可靠地处理和记录大规模代码库的能力不足。

• 方法论转变：这项工作表明，结合确定性上下文工程与专用智能体层级，能够实现可扩展、准确且语法有效的 UML 生成。该方法被呈现为超越单体提示或简单 RAG 以应对复杂仓库级任务的必要演进。
• 实用价值：通过生成在多种语言中架构连贯且语法有效的图表，该系统有助于改进自动化软件文档和架构理解。
• 适度局限性：作者承认自动化指标无法捕捉主观的人类有用性。他们指出，系统上下文图需要进一步扩展规则集以支持 C4 模型构造，且当前的评估虽然广泛，但仅限于开源仓库。该系统优先考虑“架构重要性而非全面覆盖”，这是一种设计选择而非缺陷。

总之，Code2UML 提出了一个可扩展的基于 LLM 的软件可视化框架，证明了通过正确的上下文工程和智能体专业化，LLM 可以有效地处理真实世界软件仓库的复杂性。