umple-diagram-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umple Diagram Generator Skill

Umple 图表生成工具 Skill

Overview

概述

Generate an Umple

.ump

model from requirements and render it to SVG (Umple + Graphviz).

从需求生成Umple

.ump

模型，并渲染为SVG（基于Umple + Graphviz）。

Supported diagram types

支持的图表类型

Type	Umple generator	Read before writing Umple
`state-machine`	`GvStateDiagram`	`references/state-machine-guidance.md`
`class-diagram`	`GvClassDiagram`	`references/class-diagram-guidance.md`

类型	Umple 生成器	编写Umple前请阅读
`state-machine`	`GvStateDiagram`	`references/state-machine-guidance.md`
`class-diagram`	`GvClassDiagram`	`references/class-diagram-guidance.md`

Script

脚本

Entry point:

scripts/main.ts

(run with Bun via

npx -y bun

入口文件：

scripts/main.ts

（通过

npx -y bun

运行）。

Quick start

快速开始

bash

undefined

bash

undefined

Folder mode: organized output with all files (.ump, .gv, .svg)

npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./diagrams --name "light-controller"

Exact path mode: save SVG to specific file path

npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./my-diagram.svg

Class diagram with custom name

npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./diagrams --name "user-system" --type class-diagram


Replace `${SKILL_DIR}` with the absolute path to this skill directory.

npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./diagrams --name "user-system" --type class-diagram


将 `${SKILL_DIR}` 替换为该工具目录的绝对路径。

Script options

脚本选项

Option	Description
`-i, --input <path>`	Input `.ump` file (required)
`-o, --output <path>`	Output path: directory for folder mode, or `.svg` file for exact path (required)
`-n, --name <name>`	Diagram name for folder mode (optional, triggers folder mode)
`-t, --type <type>`	Diagram type: `state-machine` (default), `class-diagram`
`-s, --suboption <opt>`	GvStateDiagram suboption (repeatable)
`--json`	JSON output with details
`-h, --help`	Show help

选项	描述
`-i, --input <path>`	输入 `.ump` 文件（必填）
`-o, --output <path>`	输出路径：文件夹模式对应目录，精确路径模式对应 `.svg` 文件（必填）
`-n, --name <name>`	文件夹模式下的图表名称（可选，指定后触发文件夹模式）
`-t, --type <type>`	图表类型： `state-machine` （默认）、 `class-diagram`
`-s, --suboption <opt>`	GvStateDiagram 子选项（可重复使用）
`--json`	输出包含详细信息的JSON格式结果
`-h, --help`	显示帮助信息

Output modes

输出模式

Folder Mode (when

--name

is specified or

--output

is a directory):

Creates organized folder with timestamped name
Includes all files:
```
.ump
```
(source),
```
.gv
```
(graphviz),
```
.svg
```
(diagram)

Folder naming:

With
```
--name
```
:
```
<sanitized-name>_<timestamp>/
```
Without
```
--name
```
:
```
<diagram-type>_<timestamp>/
```

Example:

diagrams/
└── light-controller_20260121_183045/
    ├── model.ump
    ├── model.gv
    └── model.svg

Exact Path Mode (when

--output

ends with

.svg

Saves only the SVG file to the exact specified path
Useful when user specifies a specific output location

Example:

bash

npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output /path/to/my-diagram.svg

文件夹模式（当指定

--name

或

--output

为目录时）：

创建带时间戳的规整文件夹
包含所有文件：
```
.ump
```
（源文件）、
```
.gv
```
（Graphviz文件）、
```
.svg
```
（图表）

文件夹命名规则：

指定
```
--name
```
时：
```
<清理后的名称>_<时间戳>/
```
未指定
```
--name
```
时：
```
<图表类型>_<时间戳>/
```

示例：

diagrams/
└── light-controller_20260121_183045/
    ├── model.ump
    ├── model.gv
    └── model.svg

精确路径模式（当

--output

以

.svg

结尾时）：

仅将SVG文件保存到指定的精确路径
适用于用户指定具体输出位置的场景

示例：

bash

npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output /path/to/my-diagram.svg

Result: /path/to/my-diagram.svg (only SVG, no folder created)

结果：/path/to/my-diagram.svg（仅生成SVG，不创建文件夹）

undefined

undefined

Exit codes

退出码

Code	Meaning
0	Success
1	Missing dependencies (umple or dot)
2	Umple validation/compilation failed
3	SVG generation failed or unsupported diagram type

代码	含义
0	执行成功
1	缺少依赖（umple 或 dot）
2	Umple 验证/编译失败
3	SVG生成失败或不支持的图表类型

Workflow

工作流程

Pre-flight: verify deps
- ```
command -v umple
```
- ```
command -v dot
```
  If missing, stop and ask the user to install them.
Clarify only what you must
- State machine: initial state, events, finals, guards/actions
- Class diagram: entities, attributes, relationships, multiplicities
Write Umple
- Read the relevant guidance file (table above) before writing.
Render
- Prefer folder mode unless the user explicitly provides an
```
.svg
```
  output path.
Validate
- On failure: fix Umple and retry up to 3 times.

预检查：验证依赖
- 执行
```
command -v umple
```
- 执行
```
command -v dot
```
  若缺失，停止操作并提示用户安装。
仅澄清必要信息
- 状态机：初始状态、事件、终态、守卫/动作
- 类图：实体、属性、关系、多重性
编写Umple代码
- 编写前请阅读对应指南文件（见上方表格）。
渲染图表
- 除非用户明确提供
```
.svg
```
  输出路径，否则优先使用文件夹模式。
验证结果
- 若失败：修改Umple代码并重试最多3次。

Repair loop

修复循环

If rendering fails: read script output, apply a focused fix, re-run the same command.

若渲染失败：读取脚本输出，针对性修复问题，重新运行相同命令。

Output contract

输出约定

Diagram type
Generated Umple (single
```
umple
```
block)
Exact command run
Output paths (folder + SVG, or exact SVG path)

图表类型
生成的Umple代码（单个
```
umple
```
代码块）
执行的精确命令
输出路径（文件夹+SVG，或精确SVG路径）

Guardrails

约束规则

Prefer a smaller valid Umple model over guessing syntax.
Use exact path mode only when the user provides an
```
.svg
```
path.
Do not install system dependencies.
Keep actions/guards minimal (no secrets, no I/O).

优先选择小型但有效的Umple模型，而非猜测语法。
仅当用户提供
```
.svg
```
路径时使用精确路径模式。
不要安装系统依赖。
动作/守卫保持最简（不包含敏感信息，无输入输出操作）。