Diagram Design时序图制作教程：消息传递与OAuth鉴权流程可视化
项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design 时序图（Sequence Diagram）是表达消息传递、API 调用与鉴权流程最直观的图表类型，而 Diagram Design 正是一款为 Claude Code 等 AI 编码助手打造的时序图制作工具。这个开源项目内置 27 种编辑器级图表类型，能把请求/响应、OAuth token 刷新这类流程，输出为自包含的 HTML + SVG 文件——无阴影、无千篇一律的 Mermaid 风格，浏览器打开即用。本教程将带你从零上手，用 Diagram Design 制作消息传递与 OAuth 鉴权流程可视化时序图。
上图就是项目内置的时序图成品：Reader Browser、Cloudflare、Astro Origin 三个参与者从上到下传递消息，生命周期线、激活条、异步消息一眼可辨。下面我们就从原理到实战，一步步拆解。
为什么要用时序图表达消息传递与OAuth鉴权流程？
时序图天然擅长表达"谁在什么时间、向谁发送了什么消息"，这正是以下场景的刚需：
- 🎯 API 调用轨迹：客户端 → 网关 → 服务 → 数据库的完整调用链
- 🎯 OAuth 鉴权流程：携带 Bearer token 访问资源、401 后刷新 token 并重试的分支逻辑
- 🎯 协议交互与多参与者协作：登录、支付、下单等跨系统流程
相比文字描述，时序图把"时间顺序"这个维度可视化，读者 3 秒就能看懂一次完整的鉴权握手。相比通用流程图，时序图多了生命线和激活条，能精确表达"谁持有控制权"。
Diagram Design 是什么：为 AI 助手设计的时序图制作工具
Diagram Design 是一个面向 Claude Code、Codex、Pi 等 AI 编码助手的 Agent Skill，核心思路是"让 AI 画图，但画的是有编辑水准的图"：
- 27 种图表类型：时序图之外，还有架构图、状态机图、泳道图、数据流图等，参考 SKILL.md
- 三种变体：每张图都提供 minimal light（浅色）、dark（深色）、full（编辑排版风）三种版本
- 自包含输出：单个 HTML 文件内嵌 SVG 与 CSS，无构建步骤、无外部图片依赖
- 严格设计系统：无阴影、1px 细边框、4px 网格对齐、单一强调色（珊瑚色）只留给 1–2 个焦点元素
时序图的具体规范集中在 type-sequence.md，包括布局约定、消息类型、组合片段语法与复杂度预算。
时序图核心要素：参与者、生命线与消息（新手必读）
画时序图前，先认识四个基础构件：
| 构件 | 视觉特征 | 作用 |
|---|---|---|
| 参与者（Actor） | 顶部横向排列的方框 | 系统中的角色，如 Client、API、Auth |
| 生命线（Lifeline） | 参与者下方延伸的虚线 | 表示参与者在时间轴上的存在 |
| 消息（Message） | 生命线之间的水平箭头 | 表示一次调用或返回，时间自上而下流动 |
| 激活条（Activation bar） | 生命线上的细长矩形 | 表示该参与者持有控制权的时间段 |
当流程出现分支（token 有效 vs 无效、重试、可选步骤）时，必须使用**组合片段（Combined Fragment）**框架，而不是随意画几组游离的 if/else 箭头。type-sequence.md 中定义了三种操作符：opt（可选）、alt（二选一分支）、loop（循环），标签统一用等宽字体大写显示。
四种消息类型：同步调用、返回、异步与高亮成功
时序图制作中最容易混淆的就是箭头样式，Diagram Design 用四种明确的组合来区分：
| 消息类型 | 线条 | 箭头 | 适用场景 |
|---|---|---|---|
| 同步调用（Call） | 实线 | 实心箭头 | 期望回复的请求 |
| 返回（Return） | 虚线 | 实心箭头 | 同步调用的回复，永不使用实线 |
| 异步（Async） | 虚线 | 空心箭头 | 事件、通知、单向消息 |
| 高亮成功（Headline） | 实线（强调色） | 强调色实心 | 主成功路径，整图最多 1–2 条 |
📌 记住两个易错点：返回消息即使画成虚线，箭头也必须是实心；异步消息则必须用空心箭头，两者不能混用。
实战：用 ALT 组合片段绘制 OAuth 鉴权流程图
项目自带一个教科书级的 OAuth 时序图样例：example-sequence-oauth.html，完整演示了"携带 Bearer token 调用 + 401 刷新"的流程：
- Client → API：发送
GET /resource + Bearer（蓝色链路箭头） - ALT 组合片段 第一分支
[token valid]：API 返回200 · body（珊瑚色高亮成功） - ALT 第二分支
[else · 401]：API 返回401（虚线实心返回箭头） - Client → Auth：发起
POST /token · refresh刷新令牌 - Auth → Client：返回
200 · new access - Client → API：携带新令牌重试
GET /resource - Client → Auth：异步发送
AUDIT审计消息（空心箭头，在片段外）
整张图只有 3 条生命线、1 个 alt 片段，严格控制在复杂度预算内。type-sequence.md 的硬性上限是：生命线 ≤5、消息 ≤12、组合片段 ≤1（默认），超出就拆分。
当鉴权成为跨层服务：DP 集成图怎么画
时序图画的是"一次交互的过程"，而当你需要表达"身份认证服务覆盖整个平台"时，更适合用 DP 集成图（DP Integration）。上图中的数据平台集成拓扑展示了：CRM、POS 导出、事件流三类数据源接入平台，Store 与 Query engine 对外服务，而 Identity provider 通过一条虚线 AUTH 连到平台底部边缘——这表示它是跨层服务，认证每一个组件，而不是只连某个工具。规范见 type-dp-integration.md。
更多相关图表类型：状态机图与数据流图
如果你要表达的不是"消息顺序"，而是"状态如何迁移"，可以选用状态机图：
上图展示了 Draft → In Review → Published → Archived 的完整生命周期，以及 REJECT/REVISE 回退、PURGE 删除等转移，非常适合描述 OAuth 令牌的"有效/过期/已刷新"状态，参考 type-state.md。
如果关注的是"谁在流水线哪个环节做了什么"，则用数据流图，参考 type-data-flow.md。
5分钟上手：制作你的第一张消息传递时序图
最快路径是让 AI 助手直接画。在 Claude Code 中安装后，只需一句：
"Give me a sequence of a bearer call with token refresh on 401."
AI 会自动选择时序图类型、构建 HTML 并保存。想手动起步，可以复制模板：
cp skills/diagram-design/assets/template.html my-diagram.html
几个实用入口：
- 📌 时序图规范：type-sequence.md
- 📌 OAuth 样例：example-sequence-oauth.html
- 📌 导入已有 Mermaid / draw.io 图：import-mermaid.md、import-drawio.md
- 📌 导出 PNG/SVG：export.md、export-diagram.md
- 📌 品牌定制（让图表匹配你的网站配色）：onboarding.md
- 📌 输出质检：
python3 skills/diagram-design/scripts/self_check.py <file>
时序图避坑指南：这些错误不要再犯
结合 type-sequence.md 的 anti-patterns，新手最容易踩的坑：
- ❌ 向上的箭头：消息指向上方等于反转时间，永远不允许
- ❌ if/else 不画组合片段：两个游离的箭头簇没有 ALT 框架，读者无法理解分支归属
- ❌ 嵌套 alt：alt 里再套 alt 必须拆成两张图
- ❌ 珊瑚色滥用：强调色只给 1 条主成功消息，两个分支都上色等于没上色
- ❌ 激活条永不关闭：持有控制权后必须明确释放
- ❌ 超复杂度预算：超过 5 条生命线或 12 条消息，就拆成"总览 + 细节"两张图
总结
时序图制作并不难，难的是画出"让设计师不皱眉"的图。Diagram Design 用 27 种类型、严格的设计系统和清晰的复杂度预算，把这件事交给了 AI——你只需要描述消息传递与 OAuth 鉴权流程，就能得到自包含、可导出、可品牌化的专业时序图。先从 example-sequence-oauth.html 开始吧，改一改参与者和消息，你的第一张鉴权流程时序图就诞生了。🚀
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
