用途
Sequence Diagram Skill 用于生成 UML 2.x-lite 顺序图,输出为自包含的 SVG 文件。它适用于任何需要展示有时序关系的消息交互请求,例如“绘制 X 的顺序图”、“展示 [OAuth | 登录 | 结账 | Webhook] 的时间流”、“协议 Y 的梯形图”、“展示 A 和 B 之间的消息交换”,或用户将活动图与顺序图混淆但存在明确时间顺序的场景。技能默认在存在命名参与者且有明确消息先后顺序时选择此技能。
主要能力
该技能能够从用户描述中提取命名参与者(典型 3 至 6 个,上限 7 个)和有序消息,每条消息包含源角色、目标角色、标签和类型(同步、异步、返回、自循环)。随后按照内置布局算法计算角色列宽与位置、角色行、生命线几何和消息阶梯,最终生成 SVG。输出遵循统一视觉约定:角色框为圆角矩形并带语义颜色,生命线为虚线垂直下延,同步调用为实线箭头,异步调用为虚线箭头,返回为浅色虚线,自循环为右侧凸起箭头,激活条为生命线上的细矩形,注释为纯 halo 文字。角色类型按语义配色:人类用户(slate #94a3b8)、前端/SPA/移动端(cyan #22d3ee)、后端服务(emerald #34d399)、数据库/存储(violet #a78bfa)、认证/IDP/KMS(rose #fb7185)、云边缘/LB/CDN(amber #fbbf24)、外部系统(slate #94a3b8)。编号为可选,仅在存在跳过或反向引用时添加。
使用方式
用户通过自然语言描述请求,技能提取参与者与消息后按算法布局并生成 SVG。具体流程包括:提取参与者、按顺序提取消息、计算布局、输出 SVG、运行几何审计。输出契约要求自包含 .svg 文件(或带导出工具栏的 .html),使用深色背景、JetBrains Mono 字体和 halo 文字,并且 geometry-audit 必须返回 0 才能完成。
适用场景
适用于展示命名参与者之间具有明确时间顺序的消息交换,判断标准是“如果图中每个箭头都需要编号才能理解,则适合顺序图”。典型场景包括 OAuth 授权码流程、登录、结账、Webhook、协议交互等。使用时需注意限制:参与者达到 6 个时建议拆分为两个图;消息达到 14 条时可考虑合并连续的同对调用;存在大量并行分支(par 片段)时顺序图不适用,应改用带注释边的架构图。v1 不支持 alt/loop/par 片段,需要分支时应绘制两个顺序图并以文字引用。此外,不得使用无 class="lifeline" 的生命线,不得对角色间消息使用贝塞尔曲线,不得在同一 y 坐标拥挤多条消息,不得仅因 UML 允许就编号,不得加载除 Google Fonts JetBrains Mono 之外的外部图片、图标或字体。
限制
几何审计会跳过生命线的边-边交叉和边-组件交叉检查,但组件重叠、标签重叠组件、边交叉标签等检查仍然适用。若出现消息之间的边-边冲突,通常意味着两条消息意外共享 y 坐标或自循环凸起与下一行重叠,需调整间距或重新排序。