uml-modeling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UML Modeling

UML建模

Purpose

用途

Use this skill to design UML, not merely to emit diagram text. The goal is a model that is semantically correct, visually legible, audience-appropriate, and useful for the decision the user needs to make.

Also use this skill when the user asks generically for a graphical representation, schema, diagram, or visual explanation of a software/system concern and does not name UML. In that case, infer whether UML is appropriate and choose the UML diagram type autonomously.

Treat UML as a modeling language with forms of thought:

structural form: what exists and how it is organized;
behavioral form: what happens and how behavior is constrained;
interaction form: who communicates with whom, in what order or timing;
extension form: how the modeling language is tailored.

Only after the model is conceptually right should you choose a notation or documentation format.

使用该技能设计UML图，而非仅生成图表文本。目标是创建一个语义准确、视觉清晰、符合受众需求且对用户决策有实际价值的模型。

当用户未明确提及UML，仅笼统要求提供软件/系统相关问题的图形化表示、架构图、图表或可视化解释时，也可使用该技能。这种情况下，需自行判断UML是否适用，并选择合适的UML图类型。

将UML视为一种具备多种思维形式的建模语言：

结构形式：存在哪些元素以及它们的组织方式；
行为形式：会发生什么以及行为的约束条件；
交互形式：谁与谁进行通信，通信的顺序或时机；
扩展形式：如何针对特定领域调整建模语言。

只有在模型的概念设计正确后，才选择符号表示或文档格式。

Non-Negotiable: Self-Contained UML, No Meta Leakage

不可妥协原则：独立自洽的UML，无元信息泄露

Every UML diagram must stand on its own for an external reader who has no prior knowledge of the project, conversation, source files, or user request.

This is mandatory for every diagram:

Do not include meta-information about the prompt, conversation, requester, repository, task history, uncertainty, or how the diagram was produced.
Do not leak user-request wording into titles, notes, labels, legends, or diagram comments.
Do not use labels that only make sense to someone who already knows the project.
Do not rely on implicit context, hidden assumptions, unexplained acronyms, unnamed boundaries, or unnamed external systems.

Do not write labels such as

as requested

current project

existing code

the user

this service

same as above

TODO

unknown

, or

assumed

Make the modeled subject, scope, boundary, actors/participants, external systems, and important constraints explicit inside the model when they are needed for understanding.
If a fact is necessary to understand the UML and cannot be inferred safely, ask for clarification before finalizing or use a neutral, explicit domain name such as
```
External Service
```
,
```
Authorization Provider
```
, or
```
Data Store
```
.

UML is not a transcript of the request. It is a standalone model of the subject.

每一张UML图必须能独立被不了解项目、对话、源文件或用户请求的外部读者理解。

以下要求适用于所有图表：

不得包含关于提示词、对话、请求者、代码库、任务历史、不确定性或图表生成过程的元信息；
不得将用户请求中的措辞泄露到标题、注释、标签、图例或图表说明中；
不得使用仅对项目内部人员有意义的标签；
不得依赖隐含上下文、隐藏假设、未解释的缩写、未命名的边界或未命名的外部系统；

不得使用如

as requested

、

current project

、

existing code

、

the user

、

this service

、

same as above

、

TODO

、

unknown

或

assumed

这类标签；

当理解模型需要相关信息时，需在模型中明确标注建模主题、范围、边界、参与者/角色、外部系统以及重要约束；
如果某个信息对理解UML至关重要且无法安全推断，需在最终确定前请求澄清，或使用中立且明确的领域名称，如
```
External Service
```
、
```
Authorization Provider
```
或
```
Data Store
```
。

UML不是请求内容的转录，而是对主题的独立模型呈现。

Knowledge Priority

知识优先级

Use the bundled references as the operational knowledge base:

Treat the reference files in this skill as the already-digested UML modeling guidance.
Prefer the specific diagram deep dive over the general catalog when working on one diagram type.
Prefer
```
modeling-foundations.md
```
when the problem is semantic: subject, viewpoint, state vs action, structure vs behavior, boundaries, or abstraction level.
Use external official UML material only when maintaining or updating this skill, or when the bundled references are insufficient for a specific unresolved semantic conflict.
Use notation/tool documentation only after the UML form is chosen.

Read references as needed:

```
references/modeling-foundations.md
```
: semantic foundations extracted from the official UML specification and converted into modeling rules.
```
references/uml-form-and-design.md
```
: modeling method and form principles.
```
references/diagram-design-catalog.md
```
: complete UML diagram catalog and selection guidance.
```
references/diagram-type-playbooks.md
```
: index of the per-diagram deep dives.
```
references/state-machines.md
```
: state machine design, lifecycle modeling, composite states, anti-patterns.
```
references/activities.md
```
: activity diagram design, control/object flow, decisions, partitions.
```
references/interactions.md
```
: sequence, communication, timing, and interaction overview design.
```
references/structure-diagrams.md
```
: class, object, package, component, composite structure, deployment, profile design.
```
references/use-cases.md
```
: actor-goal modeling and system boundaries.
```
references/review-rubric.md
```
: semantic review checklist and repair workflow.

For a specific diagram type, load only the matching deep dive:

```
references/class-diagram.md
```
```
references/object-diagram.md
```
```
references/package-diagram.md
```
```
references/component-diagram.md
```

references/composite-structure-diagram.md

```
references/deployment-diagram.md
```
```
references/profile-diagram.md
```
```
references/use-case-diagram.md
```
```
references/activity-diagram.md
```
```
references/state-machine-diagram.md
```
```
references/sequence-diagram.md
```
```
references/communication-diagram.md
```
```
references/timing-diagram.md
```

references/interaction-overview-diagram.md

使用内置参考资料作为操作知识库：

将该技能中的参考文件视为已整理好的UML建模指导；
针对特定类型的图表时，优先使用该类型的深度指南而非通用目录；
当问题涉及语义层面（如主题、视角、状态与动作、结构与行为、边界或抽象层级）时，优先参考
```
modeling-foundations.md
```
；
仅在维护或更新该技能，或内置参考资料无法解决特定语义冲突时，才使用外部官方UML资料；
仅在确定UML形式后，才使用符号表示/工具文档。

根据需求阅读以下参考资料：

```
references/modeling-foundations.md
```
：从官方UML规范中提取并转化为建模规则的语义基础；
```
references/uml-form-and-design.md
```
：建模方法与形式原则；
```
references/diagram-design-catalog.md
```
：完整的UML图目录与选型指南；
```
references/diagram-type-playbooks.md
```
：各类型图表深度指南索引；
```
references/state-machines.md
```
：状态机设计、生命周期建模、复合状态、反模式；
```
references/activities.md
```
：活动图设计、控制/对象流、决策、分区；
```
references/interactions.md
```
：序列图、通信图、时序图、交互概览图设计；
```
references/structure-diagrams.md
```
：类图、对象图、包图、组件图、复合结构图、部署图、Profile图设计；
```
references/use-cases.md
```
：参与者-目标建模与系统边界；
```
references/review-rubric.md
```
：语义评审清单与修复流程。

针对特定类型的图表，仅加载对应的深度指南：

```
references/class-diagram.md
```
```
references/object-diagram.md
```
```
references/package-diagram.md
```
```
references/component-diagram.md
```

references/composite-structure-diagram.md

```
references/deployment-diagram.md
```
```
references/profile-diagram.md
```
```
references/use-case-diagram.md
```
```
references/activity-diagram.md
```
```
references/state-machine-diagram.md
```
```
references/sequence-diagram.md
```
```
references/communication-diagram.md
```
```
references/timing-diagram.md
```

references/interaction-overview-diagram.md

Mandatory Workflow

强制工作流程

0. Recognize Implicit Diagram Requests

0. 识别隐含的图表请求

Recognize intent categories, not exact phrases. Treat a request as a possible UML modeling request even when the word "UML" is absent if the user asks to:

create a diagram, schema, graphical representation, or visual model;
represent states, modes, lifecycle, availability, validity, or expiration;
explain a flow, process, procedure, algorithm, or sequence of steps;
draw architecture, topology, modules, components, packages, or deployment;
map relationships, dependencies, ownership, containment, or interfaces;
visualize interactions, messages, timing, actors, or responsibilities.

Apply this recognition regardless of the user's language. Do not rely on locale-specific phrase matching.

Use UML when the subject is software, architecture, state, workflow, interaction, deployment, domain structure, or system behavior. If the user asks for a purely decorative image, infographic, chart, or non-model visual, do not force UML.

When UML is appropriate and the user did not specify a type, choose the type yourself. Ask a clarification only when two materially different interpretations would produce different, risky models.

识别意图类别，而非精确短语。即使用户未提及“UML”一词，若用户提出以下请求，也应视为潜在的UML建模请求：

创建图表、架构图、图形化表示或可视化模型；
表示状态、模式、生命周期、可用性、有效性或过期规则；
解释流程、步骤、算法或操作序列；
绘制架构、拓扑、模块、组件、包或部署方式；
映射关系、依赖、所有权、包含或接口；
可视化交互、消息、时序、参与者或职责。

无论用户使用何种语言，均需应用此识别规则，不要依赖特定语言的短语匹配。

当主题涉及软件、架构、状态、工作流、交互、部署、领域结构或系统行为时，使用UML。若用户要求的是纯装饰性图像、信息图、图表或非模型类可视化内容，请勿强制使用UML。

当UML适用且用户未指定类型时，自行选择类型。仅当两种截然不同的解读会产生不同的高风险模型时，才请求澄清。

1. Frame The Modeling Problem

1. 明确建模问题

Before drawing, identify:

the diagram's audience: developer, architect, analyst, product owner, tester, operator;
the question the diagram must answer;
the subject being modeled;
the boundary of the system or element;
the abstraction level: conceptual, logical, implementation, runtime, physical;
whether the model describes structure, behavior, interaction, or deployment.

If the user asks for a diagram type that does not match the intent, say so briefly and choose the correct type. If the user did not name a type, do not ask them to choose one unless the modeling subject is ambiguous.

在绘制之前，确定：

图表的受众：开发人员、架构师、分析师、产品负责人、测试人员、运维人员；
图表需要解答的问题；
建模的主题；
系统或元素的边界；
抽象层级：概念层、逻辑层、实现层、运行时层、物理层；
模型描述的是结构、行为、交互还是部署。

若用户要求的图表类型与意图不符，简要说明并选择正确类型。若用户未指定类型，除非建模主题存在歧义，否则无需让用户选择。

2. Choose The UML Form Autonomously

2. 自主选择UML形式

Choose one primary diagram type. Do not blend diagram types just to include everything.

Use this quick decision tree:

"What are the types/modules/components/nodes and relationships?" -> structure diagram.
"What is the lifecycle of one thing?" -> state machine diagram.
"What steps happen in a workflow?" -> activity diagram.
"What messages happen over time?" -> sequence diagram.
"What user goals exist at the system boundary?" -> use case diagram.
"Where does software run?" -> deployment diagram.
"How do runtime instances look at one moment?" -> object diagram.
"How should UML be extended for this domain?" -> profile diagram.

Use more than one UML diagram only when the user is really asking more than one modeling question. For example, a stateful subsystem may need a state machine for lifecycle and a sequence diagram for external calls, but those should be separate diagrams with separate purposes.

选择一种主要的图表类型，不要为了涵盖所有内容而混合多种类型。

使用以下快速决策树：

“有哪些类型/模块/组件/节点及其关系？” -> 结构图；
“某个事物的生命周期是怎样的？” -> 状态机图；
“工作流包含哪些步骤？” -> 活动图；
“随时间推移会发生哪些消息交互？” -> 序列图；
“系统边界处存在哪些用户目标？” -> 用例图；
“软件运行在何处？” -> 部署图；
“某一时刻的运行时实例是什么样的？” -> 对象图；
“如何针对该领域扩展UML？” -> Profile图。

仅当用户实际提出多个建模问题时，才使用多张UML图。例如，一个有状态的子系统可能需要一张状态机图描述生命周期，一张序列图描述外部调用，但这些应为独立的、各有明确用途的图表。

3. Model Semantics Before Layout

3. 先建模语义，再考虑布局

Draft the semantic inventory first:

elements;
relationships;
events and transitions;
actions/activities;
actors and system boundary;
messages and ordering;
nodes/artifacts;
constraints and notes.

Then remove anything that does not answer the diagram's main question.

首先草拟语义清单：

元素；
关系；
事件与转换；
动作/活动；
参与者与系统边界；
消息与顺序；
节点/工件；
约束与注释。

然后移除所有与图表核心问题无关的内容。

4. Design The Form

4. 设计图表形式

Apply visual/form rules:

the diagram must be understandable without the surrounding chat, documentation, or source files;
one diagram, one main question;
one abstraction level per diagram;
group by semantic containment, not decoration;
prefer fewer stronger labels over many long labels;
place stable/static things before dynamic annotations;
avoid crossing lines by reorganizing responsibility, not only by spacing;
use notes for explanation, not to compensate for wrong modeling;
use legends for compressed labels;
split when the diagram needs two different grammars.

应用视觉/形式规则：

图表无需依赖上下文对话、文档或源文件即可被理解；
一张图表只解决一个核心问题；
每张图表保持单一抽象层级；
按语义包含关系分组，而非装饰性分组；
优先使用少量精准标签，而非大量冗长标签；
先放置稳定/静态元素，再添加动态注释；
通过调整职责划分而非仅调整间距来避免线条交叉；
使用注释进行解释，而非弥补建模错误；
使用图例简化压缩后的标签；
当图表需要两种不同语法时，拆分图表。

5. Validate Against UML Semantics

5. 依据UML语义验证

Use the relevant checklist from

references/review-rubric.md

Examples:

In a state machine, a state is a condition that can persist. "Validate request" is normally an activity/action, not a state.
In an activity diagram, nodes are actions and control/object flows. "Order approved" is normally a state/condition, not an action.
In a use case diagram, use cases are user goals, not buttons, pages, or internal functions.
In a sequence diagram, messages are ordered interactions, not dependencies.
In a class diagram, composition implies strong whole-part lifetime ownership, not just "has a reference".

使用

references/review-rubric.md

中的相关检查清单。

示例：

在状态机图中，状态是一种可持续的条件。“Validate request”通常是活动/动作，而非状态；
在活动图中，节点是动作与控制/对象流。“Order approved”通常是状态/条件，而非动作；
在用例图中，用例是用户目标，而非按钮、页面或内部功能；
在序列图中，消息是有序的交互，而非依赖关系；
在类图中，组合关系意味着强整体-部分生命周期所有权，而非仅仅“拥有引用”。

6. Notation Last

6. 最后确定符号表示

Only after the model is correct, choose notation:

a textual diagram notation when the repository or user asks for one;
Markdown tables or prose when UML would overcomplicate;
a split set of diagrams when one notation surface would distort the model.

Notation is subordinate to modeling. If a requested notation pushes the model into a wrong shape, change the notation, split the diagram, or explicitly tell the user that the requested representation is distorting the UML form.

仅在模型正确后，选择符号表示方式：

当代码库或用户要求时，使用文本式图表符号；
当UML会使内容过于复杂时，使用Markdown表格或 prose；
当单一符号表示会扭曲模型时，使用拆分的多组图表。

符号表示从属于建模。若要求的符号表示会导致模型变形，需更改符号表示、拆分图表，或明确告知用户所要求的表示方式会扭曲UML形式。

When Fixing A Bad Diagram

修复不良图表的步骤

Use this order:

Identify the intended question.
Identify the actual diagram type and the diagram type it should be.
Name the semantic errors first.
Redesign the model form.
Only then repair notation/layout.

Do not keep polishing a diagram that is the wrong UML type.

按以下顺序操作：

确定图表原本要解答的问题；
识别当前图表类型以及它应归属的正确类型；
首先指出语义错误；
重新设计模型形式；
最后修复符号表示/布局。

不要继续优化类型错误的UML图。

Completion Standard

完成标准

A finished UML answer should usually include:

the chosen UML diagram type and why;
the diagram;
a short legend only if labels were intentionally compressed;
explicit model boundaries and domain constraints needed to understand the diagram;
a note when a requested diagram type was changed for semantic correctness.

For documentation edits, preserve the surrounding language and style, but improve the modeling quality even if that means replacing the diagram rather than tweaking it.

一份合格的UML回答通常应包含：

所选的UML图类型及选择原因；
图表本身；
仅在标签被有意压缩时提供简短图例；
理解图表所需的明确模型边界与领域约束；
若因语义正确性更改了用户要求的图表类型，需添加说明。

对于文档编辑，需保留原有语言风格，但即使需要替换图表而非微调，也要提升建模质量。