kuml-dev/kUML
GitHub: kuml-dev/kUML
kUML 是一款基于类型安全 Kotlin DSL 的 diagrams-as-code 建模工具，原生支持 UML 2.x、SysML 2 和 C4，专为 LLM 辅助建模与 Git 版本控制而设计。
Stars: 1 | Forks: 0
= kUML
:toc:
:toc-placement: preamble
:icons: font
image::docs/images/kuml-banner.png[kUML — Kotlin UML Modelling,link=https://github.com/kuml-dev/kUML]
*官网：* https://kuml.dev · *手册：* https://docs.kuml.dev · *发布：* https://github.com/kuml-dev/kUML/releases
*kUML* 是一款建模工具，以类型安全的 Kotlin DSL 形式表达 UML 2.x、SysML 2 和 C4——这是第一款专为 LLM 时代设计的 UML 工具。
image:https://img.shields.io/maven-central/v/dev.kuml/kuml-core-dsl[Maven Central]
image:https://img.shields.io/github/license/kuml-dev/kUML[Apache 2.0]
image:https://img.shields.io/github/actions/workflow/status/kuml-dev/kUML/ci.yml[CI]
== 为什么选择 kUML？
[.lead]
kUML 中的每一个特性都存在于市面上的_某些_工具中。但这种特定的组合在其他任何地方都找不到：*类型安全的 Kotlin DSL · UML 2.x + SysML 2 + C4 作为一等公民 · 可执行的行为 runtime · LLM 优先设计 · Apache 2.0。*
现有的 UML 工具分为两类：
* *图形化 CASE 工具*（Enterprise Architect、MagicDraw）——建模正规，但价格昂贵且不亲和 Git。
* *基于文本的绘图工具*（PlantUML、Mermaid）——支持版本控制，但仅能绘图且对 UML 的支持较弱。
kUML 填补了这一空白：一款真正的建模工具，以 Kotlin 源代码表达，完全支持 Git 版本控制，并且从根本上为 LLM 辅助工作流而构建。
=== 无人填补的两个空白
市面上有数十种 UML、SysML 和架构工具。但没有一款能填补这两个象限：
. *没有严肃的建模工具运行在类型化的宿主语言上。* 市面上有 Python 绘图库、围绕 EMF 的 Java API，以及数不胜数的自定义文本语法。但没有一款成熟的工具能将模型视为现代静态类型语言中的普通代码，并提供 IDE 重构、编译时检查和自然的构建系统集成。kUML 使用 Kotlin 的类型安全 builder，因为它们是目前最合适的方案——重点在于原则，而非语言的选择。
. *没有工具是为 LLM 时代设计的。* PlantUML 和 Mermaid 恰好对 LLM 友好，因为它们拥有庞大的训练足迹。那是运气，而非设计。kUML 是专门为 AI 辅助建模而构建的：编译或快速失败的类型安全输出、一致的命名参数、用于 agent 内省的 MCP server、`kuml ai` 子命令，以及衡量 LLM 生成的模型实际验证通过率的 benchmark。
== 快速开始
## [source,kotlin]
// order-domain.kuml.kts — 无需导入，kUML 脚本宿主已提供它们
classDiagram(name = "Order Domain") {
val status = enumOf(name = "OrderStatus") {
literal(name = "DRAFT")
literal(name = "CONFIRMED")
literal(name = "SHIPPED")
literal(name = "CANCELLED")
}
```
val order = classOf(name = "Order") {
attribute(name = "id", type = "UUID")
attribute(name = "status", type = status) // enum val used as attribute type
operation(name = "confirm")
operation(name = "cancel")
}
val orderItem = classOf(name = "OrderItem") {
attribute(name = "quantity", type = "Int")
attribute(name = "unitPrice", type = "BigDecimal")
}
association(source = order, target = orderItem) {
aggregation = AggregationKind.COMPOSITE
source { multiplicity(spec = "1") }
target { multiplicity(spec = "1..*"); role = "items" }
}
```
## }
## [source,bash]
## kuml render order-domain.kuml.kts --format svg
该命令会生成下图——直接通过 ELK Sugiyama 布局和 kUML 主题从上面的脚本渲染而成：
image::docs/images/order-domain.svg[Order Domain — 包含 OrderStatus 枚举和 OrderItem 组合的类图,align=center]
== 安装
[cols="1,3"]
|===
| 方式 | 命令 / 链接
| *Homebrew* (macOS/Linux)
| `brew install kuml-dev/kuml/kuml`
| *SDKMAN!*
| `sdk install kuml` — 支持 Linux x86_64、Linux ARM64、macOS、Windows x86_64。
| *Docker*
| `docker pull ghcr.io/kuml-dev/kuml-cli:v0.12.0` — 最小化 CLI 镜像。
| *原生安装包*
| 由 `release-installers.yml` CI 工作流在每个版本标签 (v0.12.0) 上构建的 DEB、RPM、DMG、MSI 软件包。可从 GitHub Releases 页面下载。
| *Maven Central* (库模块)
| `implementation("dev.kuml:kuml-core-dsl:0.12.0")` — 库模块已发布至 Maven Central。
|===
== 功能
[cols="1,3"]
|===
| 功能 | 描述
| *类型安全的 DSL*
| 将 UML 2.x、SysML 2 和 C4 作为地道的 Kotlin 实现——支持编译时验证和全面的 IDE 支持。
| *LLM 原生*
| 命名参数、规范化格式化工具、结构化 JSON 错误、MCP server——专为可靠的 LLM 代码生成而设计。
| *模型驱动架构*
| M2M 转换（设计 → 实现 → 部署）和 M2T 代码生成。五个内置 transformer：`uml-to-jpa`、`uml-to-rest` (OpenAPI 3.0 YAML)、`uml-to-k8s` (Kubernetes manifests)、`uml-to-docker` (Dockerfiles)、`c4-to-uml`。可通过 ServiceLoader 注册额外的 transformer。
| *纯 Kotlin 元模型*
| 核心不依赖 EMF——仅使用 `sealed`/`data class` 层次结构。XMI 互操作作为可选的 `kuml-io-emf` 模块提供。
| *OCL 子集*
| 直接在 Kotlin 模型上使用对象约束语言进行约束。
| *内置 UML profile*
| v0.3.0 附带五个 profile——*AUTOSAR* (Classic Platform R22-11)、JavaEE / Jakarta EE、Spring、OpenAPI、SoaML。通过 `ServiceLoader` 发现；无需修改 CLI 即可添加自己的 profile。
| *Web UI (浏览器)*
| `kuml serve` 启动一个带有 CodeMirror 6 编辑器、300 ms 实时 SVG 预览、主题和布局下拉菜单，以及 SVG / PNG / LaTeX 下载按钮的 Ktor/Netty HTTP server。无需 IDE。(V2.0.34)
| *快照 / 恢复*
| `StateMachineRuntime.snapshotFull()` 和 `restoreFrom()` 持久化并恢复完整的 runtime 状态——顶点、变量作用域、内部事件队列、trace。`MigrationPolicy` 控制模型更改时的兼容性：`Reject` · `AcceptIfFingerprintMatches` · `AcceptIfVerticesPresent`。(V2.0.35)
| *交互式执行 (`kuml run`)*
| 交互式驱动状态机和活动图。三种 adapter：`stdin` (REPL)、`mcp` (用于编程式事件注入的本地 REST server)、`batch` (重播事件 JSON)。支持 `--restore` / `--snapshot-out` 以实现持久化会话。支持 UML、SysML 2 STM 和 ACT。(V2.0.38)
| *逆向工程*
| `kuml reverse` 从现有源代码重建 UML 类图。支持 Java（通过 JavaParser，V3.0.7）和 Kotlin（通过 Compiler PSI，V3.0.8）。可选的 `--transformer` 标志将恢复的模型通过任何已注册的 M2M transformer 进行处理。
| *XMI 导入 / 导出*
| 通过 `kuml-io-emf` 实现完全双向的 XMI (Eclipse EMF/UML2)。支持 Class、Interface、Enum、Association、Generalization、InterfaceRealization、Dependency。兼容 Enterprise Architect、Papyrus 和 MagicDraw。(V3.0.15–17)
| *AI 助手*
| `kuml-ai` 模块嵌入了一个基于 Koog 的多 LLM agent（OpenAI、Anthropic、Google、DeepSeek、OpenRouter、Ollama），并在桌面应用中提供 AI 面板和补丁预览工作流。(V3.0.22–23)
|===
== UML 2.x 支持
kUML 实现了所有 14 种 UML 2.x 图表类型，并将其作为与 SysML 2 和 C4 并列的一等公民：
[cols="1,3,1"]
|===
| 图表类型 | 描述 | 模拟
| *类图 (Class Diagram)*
| 类、接口、枚举、关联、泛化、依赖、实现
| —
| *对象图 (Object Diagram)*
| 实例级对象图和槽值的快照
| —
| *包图 (Package Diagram)*
| 包层次结构、导入、合并和 namespace 依赖
| —
| *组件图 (Component Diagram)*
| 逻辑组件、提供/必需的接口以及连接器
| —
| *组合结构图 (Composite Structure Diagram)*
| classifier 及其连接器的内部部件/端口结构
| —
| *部署图 (Deployment Diagram)*
| 节点拓扑、制品部署和通信路径
| —
| *轮廓图 (Profile Diagram)*
| 元类扩展、stereotype、标签值和约束
| —
| *用例图 (Use Case Diagram)*
| 参与者/用例关系、包含/扩展关联以及系统边界
| —
| *活动图 (Activity Diagram)*
| Token 流动活动语义、分区（泳道）、决策和分叉/汇合节点
| ✅ `kuml simulate`
| *状态机图 (State Machine Diagram)*
| 具有守卫条件、效果、内部转换和历史伪状态的分层状态机
| ✅ `kuml simulate`
| *序列图 (Sequence Diagram)*
| 生命线交互、同步/异步消息和组合片段（alt/opt/loop/par）
| —
| *通信图 (Communication Diagram)*
| 沿关联路径带有编号消息流的对象交互
| —
| *定时图 (Timing Diagram)*
| 跨多个生命线的状态/条件时间轴及时间约束
| —
| *交互概览图 (Interaction Overview Diagram)*
| 结合活动图和序列图片段的控制流概览
| —
|===
== SysML 2 支持
kUML 实现了所有 8 种 SysML 2 图表类型，并将其作为与 UML 2.x 和 C4 并列的一等公民：
[cols="1,3,1"]
|===
| 图表类型 | 描述 | 模拟
| *BDD* — 模块定义图 | 系统结构、模块、值属性、关联 | —
| *IBD* — 内部模块图 | 内部连接和端口绑定 | —
| *UC* — 用例图 | 系统上下文中的参与者/用例关系 | —
| *REQ* — 需求图 | 需求层次结构，满足/细化/派生 trace | —
| *STM* — 状态机图 | 具有守卫条件和效果的分层状态机 | ✅ `kuml simulate`
| *ACT* — 活动图 | 带有分区（泳道）的 Token 流动活动语义 | ✅ `kuml simulate`
| *SEQ* — 序列图 | 带有组合片段的生命线交互 | —
| *PAR* — 参数图 | 约束块和参数方程 | —
|===
自 v0.5.0 起新增的显著功能：
* `kuml simulate` 端到端支持 SysML 2 *STM* (V2.0.17) 和 *ACT* (V2.0.18)——事件驱动的状态机执行和 Token 流动活动模拟。
* SEQ 图中的*组合片段*（alt、opt、loop、par、…）(V2.0.15)。
* ACT 图中的*活动分区 / 泳道* (V2.0.16)。
* *类型化表达式验证* (`kuml validate --strict`) 通过具有类型推断的类型化 AST 解析类 OCL 守卫条件、效果和 PAR 约束 (V2.0.20b)。
* *Web UI LaTeX 下载* —— `kuml serve` 中的 `POST /api/render` 接受所有 10 种图表类型的 `format = "latex"`，包括全部 8 种 SysML 2 类型 (V2.0.36)。
* *SysML 2 的快照/恢复* —— `snapshotFull` / `restoreFrom` 为 SysML 2 STM 和 ACT 实例保留完整的 runtime 状态 (V2.0.35)。
* *`kuml run` SysML 2 支持* —— 所有三个 adapter（stdin / mcp / batch）均接受 SysML 2 STM 和 ACT 脚本 (V2.0.38)。
== C4 支持
kUML 实现了所有 6 种 C4 图表类型，并将其作为与 UML 2.x 和 SysML 2 并列的一等公民：
[cols="1,3"]
|===
| 图表类型 | 描述
| *文图 (Context Diagram)*
| 系统边界、外部参与者（人员和外部系统）及其关系
| *容器图 (Container Diagram)*
| 系统边界内的应用程序、服务和数据库及其交互
| *组件图 (Component Diagram)*
| 容器内的内部组件及其依赖关系
| *部署图 (Deployment Diagram)*
| 包含节点、基础设施元素和容器实例的部署拓扑
| *动态图 (Dynamic Diagram)*
| 人员、系统、容器或组件之间带编号的交互序列
| *系统景观图 (Landscape Diagram)*
| 多系统企业概览——跨越组织边界的人员和系统
|===
通过 `kuml import --format structurizr` 和 `kuml export --format structurizr` 支持 Structurizr DSL 的往返转换，允许与现有的 Structurizr 工作空间进行互操作。
== kUML 的比较
[cols="3,^1,^1,^1,^1,^1,^1,^1,^1", options="header"]
|===
| 功能
| kUML
| PlantUML
| Mermaid
| D2
| Structurizr
| MagicDraw
| Modelio
| Diagrams (Py)
| UML 2.x（所有图表类型） | ✅ | ⚠️ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌
| SysML 2 一等公民支持 | ✅ | ⚠️ | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌
| C4 一等公民支持 | ✅ | ⚠️ | ⚠️ | ❌ | ✅ | ❌ | ❌ | ⚠️
| 类型安全的 DSL | ✅ | ❌ | ❌ | ❌ | ⚠️ | ❌ | ❌ | ⚠️
| 真正的元模型 | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ❌
| OCL 约束 | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌
| AUTOSAR profile (内置) | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ❌ | ❌
| 内置 UML profile (5) | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌
| 代码生成 (M2T) | ✅ | ❌ | ❌ | ❌ | ⚠️ | ✅ | ✅ | ❌
| MDA 转换 (M2M) | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ⚠️ | ❌
| 可执行行为模拟 | ✅ | ❌ | ❌ | ❌ | ❌ | ◐ | ❌ | ❌
| M2M 代码生成 (transformer) | ✅ | ❌ | ❌ | ❌ | ❌ | ◐ | ◐ | ❌
| 类型化表达式验证 | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ❌ | ❌
| 原生支持 Git | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ⚠️ | ✅
| 开源 | ✅ | ✅ | ✅ | ✅ | ⚠️ | ❌ | ✅ | ✅
| LLM 优先设计 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌
| CLI + Gradle + IDE + Web | ✅ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ✅ | ✅ | ⚠️
| 优美的自动布局 | ✅ | ❌ | ⚠️ | ✅ | ✅ | ⚠️ | ⚠️ | ✅
| 网格布局（可选，实验性） | ✅ | ❌ | ❌ | ⚠️ | ❌ | ⚠️ | ⚠️ | ❌
| M2M 代码生成（5 个 transformer） | ✅ | ❌ | ❌ | ❌ | ❌ | ◐ | ◐ | ❌
| 原生安装包 (DEB/RPM/DMG/MSI/Docker) | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ◐ | ❌
|===
✅ 具备 · ⚠️ 有限或部分支持 · ◐ 专有/闭源 · ❌ 不具备
=== kUML 的优势
* *在一个工具中实现建模深度、Git 版本控制和 LLM 友好性。* 没有其他工具能将这三者结合起来。
* *以类型安全的 DSL 作为模型基底* —— 在工具链集成和 AI 辅助生成方面具有结构性优势。
* *将 UML、SysML 和 C4 作为同等的一等公民语言。* 其他所有工具都迫使你只能选其一。
* *采用 Apache 2.0 协议的现代技术栈*（Kotlin、GraalVM Native Image、Compose）。摆脱了 Eclipse 的历史遗留问题。
* *从第一天起就为 LLM 时代设计* —— 具备结构化而非偶然性的 AI 辅助建模契合度。
=== 我们对竞争对手的客观评价
* *PlantUML 的生态系统非常庞大* —— wikis、IDEs、AsciiDoc 工具、CI 插件。kUML 致力于搭建桥梁（AsciiDoc 扩展、Gradle 插件、IDE 插件），而不是在数量上竞争。
* *Structurizr 在情感上拥有 C4。* kUML 提供 Structurizr DSL 往返转换——为了互操作，而非竞争。
* *Mermaid 拥有 GitHub 原生渲染* —— 阻力最低。kUML 的目标是从第二步开始创造价值。
* *MagicDraw 和 Cameo 统治着企业级汽车领域——但它们的 AUTOSAR 支持是付费附加组件。* kUML 开箱即用附带了 AUTOSAR profile (v0.3.0)：带有 kind/packageName 的 `«SoftwareComponent»`、带有 version/isService 的 `«ComInterface»`、带有 direction 的 `«AutosarPort»`（D17 —— 故意不使用 `Port` 以避免与 UML 元类冲突）、包含 periodic/event-triggered/init/shutdown 类型的 `«Runnable»`，以及状态机上的 `«BehaviorSpec»` 可馈送至 `kuml simulate` 以进行基于 trace 的 RTE 验证。
== CLI 命令
[cols="1,3"]
|===
| 命令 | 描述
| `kuml render`
| 将 `*.kuml.kts` 模型渲染为 SVG 或 PNG（ELK 布局 + KumlSvgRenderer / KumlPngRenderer）。
| `kuml watch`
| 文件更改时重新渲染；500 ms 轮询，遇到脚本错误永不退出。
| `kuml validate`
| 评估 OCL `constraint(name, body)` 声明；支持 `--output text\|json`，违规时退出代码为 `4`。
| `kuml fmt`
| 针对 `*.kuml.kts` 的幂等文本格式化工具；`--check` 模式下如果需要重新格式化则退出代码为 `5`。
| `kuml generate`
| 通过插件进行代码生成（内置 `--plugin kotlin\|java\|sql`）。
| `kuml import`
| 从其他格式导入图表：`--format structurizr`（Structurizr DSL → `*.kuml.kts`）或 `--format xmi`（XMI/EMF → `*.kuml.kts`）。
| `kuml export`
| 将模型导出为其他格式：`--format structurizr` (Structurizr DSL) 或 `--format xmi` (XMI/EMF)。
| `kuml reverse`
| 从现有源代码重建 UML 类图。`--lang java\|kotlin\|auto` 选择解析器引擎（Java 使用 JavaParser，Kotlin 使用 Kotlin Compiler PSI）。可选的 `--transformer ` 将恢复的模型通过已注册的 M2M transformer 进行处理。(V3.0.9)
| `kuml markdown`
| 将 Markdown 文件中 `kuml` 围栏代码块渲染为内联 SVG、链接 SVG 或链接 PNG。
| `kuml completion`
| 输出适用于 `bash`、`zsh` 或 `fish` 的 shell 自动补全脚本（Clikt 内置）。
| `kuml simulate