gpt-image-2 时序图模板实战：用结构化 JSON 提示词生成工程感 UML Sequence Diagram

本文基于 garden-skills 仓库中 gpt-image-2 技能的技术示意图模板体系，系统讲解「工程感时序图」模板的定位、主模板 JSON 全字段语义、参数策略、自动补全规则与三套变体，并结合仓库内置的 OAuth 2.0 / 微信支付真实案例 JSON 与 Mode A 生图脚本，帮助你直接复用该模板为 README、博客、协议文档与安全评审产出标准 UML 时序图配图。读完即可把「actor + lifeline + 消息箭头 + 激活条」的工程感时序图生成能力接入你自己的 GPT Image 2 工作流。

模板定位：这是一张「位图时序图」，不是可编辑图表

sequence-diagram.md 属于 technical-diagrams 分类目录，与 system-architecture.md、flowchart-decision.md、state-machine.md 等模板共享同一套「暗色 grid 背景 + 等宽字体 + 角色编码配色」视觉系统。

该模板第一行就给出了明确的边界声明：

本模板生成的是位图（PNG），不是 PlantUML / mermaid 可编辑时序图；需要可编辑请用 mermaid / PlantUML / draw.io。

这意味着它的正确使用场景是视觉呈现——README 头图、博客配图、协议文档插图、PPT 配图——而不是需要二次编辑、对齐、版本化的工程图。SKILL.md 的 Technical Diagrams 索引也补充了同样的说明：本目录产出的是 PNG 位图，需要可编辑请改用 mermaid / draw.io / excalidraw / Figma（见 SKILL.md 第 18 节）。

适用范围与「何时使用」

模板明确列出五类最典型的应用场景：

• API 调用时序（前端 → 后端 → DB）
• 鉴权 / OAuth / 多步握手时序
• 微服务间消息传递时序
• 分布式事务 / Saga / 2PC 时序
• 客户端 - 服务器 - 第三方三方协议时序

触发使用的关键词包括：用户提到「时序图 / sequence diagram / 调用时序 / API 流 / OAuth 流 / 分布式事务」，或希望得到「actor + lifeline + 消息箭头」的标准 UML 时序图样式，且接受位图输出。

模板同时给出了严格的「不要使用」边界，避免模板串用：

• 用户要的是「业务流程 / 决策」→ 改用 flowchart-decision.md
• 用户要的是「状态机」→ 改用 state-machine.md
• 用户要的是「系统架构」→ 改用 system-architecture.md

缺失信息优先提问顺序

模板要求在与用户交互时，按以下优先级补齐关键信息（缺什么问什么，不泛泛而问）：

1. 时序名称（如「OAuth 2.0 授权码流程 / 下单时序 / Saga 事务」）
2. 参与的 actors（按从左到右顺序）
3. 消息序列（按时间顺序，标明 sender → receiver、消息内容、同步 / 异步）
4. 是否有失败 / 重试分支
5. 是否有 self-call（actor 调用自己内部方法）
6. 是否需要消息编号（论文 / 协议描述常需要）
7. 比例（默认 16:9 横版；actor 多时可用 4:3）

这与 prompt-writing.md 中的「参数设计规则」一脉相承：核心参数（主体、消息序列）优先提问，可默认参数（激活条、配色）与可随机参数（图标造型）由 Agent 自行处理。

主模板：标准 UML 时序图 JSON 逐字段拆解

主模板是一份完整的可替换 JSON，字段名、颜色值、字号、间距都写到了像素级，可直接复制使用。下面按区块拆解每个字段的语义与作用。

canvas：画布与背景

"canvas": {
  "aspect_ratio": "{argument name=\"aspect_ratio\" default=\"16:9\"}",
  "background": "deep slate #0F172A with subtle 1px grid #1E293B at 32px spacing",
  "outer_padding": "60px"
}

• aspect_ratio：默认 16:9 横版；当 actor 数量多（接近 6 个）时可切到 4:3 避免横向拥挤。
• background：深石板蓝 #0F172A 底色 + 32px 间距的 1px 网格线 #1E293B，这是整个 technical-diagrams 分类的统一视觉基底。
• outer_padding：画布四周留 60px 安全边距。

title_strip：标题条

"title_strip": {
  "title": "{argument name=\"title\" default=\"OAuth 2.0 Authorization Code Flow\"}",
  "subtitle": "{argument name=\"subtitle\" default=\"with PKCE\"}",
  "position": "top-left, JetBrains Mono / SF Mono, light gray"
}

标题 + 副标题放在左上角，使用 JetBrains Mono / SF Mono 等宽字体浅灰渲染。主标题与副标题是两个独立可替换参数。

actors：参与者与类型编码配色

"actors": {
  "count": "{argument name=\"actor_count\" default=\"4\"}",
  "items": [
    {
      "id": "A1",
      "name": "{argument name=\"actor1_name\" default=\"User\"}",
      "type": "{argument name=\"actor1_type\" default=\"user\"}",
      "icon_glyph": "stick figure outline"
    },
    {
      "id": "A2",
      "name": "{argument name=\"actor2_name\" default=\"Web App\"}",
      "type": "{argument name=\"actor2_type\" default=\"client\"}",
      "icon_glyph": "browser window outline"
    },
    {
      "id": "A3",
      "name": "{argument name=\"actor3_name\" default=\"Auth Server\"}",
      "type": "{argument name=\"actor3_type\" default=\"service\"}",
      "icon_glyph": "shield outline"
    },
    {
      "id": "A4",
      "name": "{argument name=\"actor4_name\" default=\"Resource Server\"}",
      "type": "{argument name=\"actor4_type\" default=\"service\"}",
      "icon_glyph": "database / server outline"
    }
  ],
  "header_box_style": {
    "shape": "rounded rectangle, corner radius 6px",
    "fill": "type-coded color × 12% opacity",
    "border": "1.5px solid type-coded color",
    "size": "160px wide × 64px tall, all headers identical size, evenly spaced",
    "label": "actor name in mono 11pt + small icon glyph above name"
  },
  "type_color_map": {
    "user": "cyan #22D3EE",
    "client": "blue #60A5FA",
    "service": "emerald #34D399",
    "database": "violet #A78BFA",
    "external": "slate #94A3B8"
  }
}

关键约束：

• 每个 actor 有唯一 id（A1/A2/...），供消息的 from / to 引用。
• type 决定图标与配色，5 种类型各有专属色：user→青色、client→蓝色、service→翡翠绿、database→紫色、external→石板灰。
• header 必须是等大小（160×64px）、等间距、水平对齐的圆角矩形，内部为类型色 12% 透明填充 + 1.5px 类型色边框，顶部放小图标 glyph、下方放等宽字体名字。

lifelines：生命线

"lifelines": {
  "rule": "每个 actor header 下方画一条垂直虚线 (1px dashed slate #475569)，从 header 底部一直延伸到画布底部",
  "spacing": "lifelines 之间等距，间距 ≥ 200px"
}

每条 lifeline 是 1px 虚线（slate #475569），从 header 底部贯穿到画布底部，彼此间距 ≥ 200px，保证消息标签有足够的书写空间。

messages：消息序列（时序图的灵魂）

"messages": {
  "count": "{argument name=\"message_count\" default=\"10\"}",
  "items": [
    { "id": "M1", "from": "A1", "to": "A2", "label": "1. Click 'Sign in'", "type": "sync" },
    { "id": "M2", "from": "A2", "to": "A3", "label": "2. GET /authorize?code_challenge=...", "type": "sync" },
    { "id": "M3", "from": "A3", "to": "A1", "label": "3. Show login page", "type": "return" },
    { "id": "M4", "from": "A1", "to": "A3", "label": "4. Submit credentials", "type": "sync" },
    { "id": "M5", "from": "A3", "to": "A2", "label": "5. Redirect with auth_code", "type": "return" },
    { "id": "M6", "from": "A2", "to": "A3", "label": "6. POST /token { code, code_verifier }", "type": "sync" },
    { "id": "M7", "from": "A3", "to": "A2", "label": "7. { access_token, refresh_token }", "type": "return" },
    { "id": "M8", "from": "A2", "to": "A4", "label": "8. GET /api/data (Bearer token)", "type": "sync" },
    { "id": "M9", "from": "A4", "to": "A4", "label": "9. validate token", "type": "self" },
    { "id": "M10", "from": "A4", "to": "A2", "label": "10. { data: ... }", "type": "return" }
  ],
  "message_style": {
    "sync": "solid line 1.5px slate #94A3B8, filled triangle arrowhead at target",
    "async": "solid line 1.5px slate #94A3B8, hollow triangle arrowhead",
    "return": "dashed line 1.5px slate #64748B, hollow triangle arrowhead",
    "self": "horizontal arrow that loops out to the right and back to the same lifeline (bracket shape)"
  },
  "label_format": "<编号>. <消息内容>，例如 '5. Redirect with auth_code'，mono 10pt，标在 arrow 上方居中"
}

消息是时序图的核心信息载体，模板用四种 type 精确映射四种箭头语义，每种箭头风格都有严格的图形约束，不可混用：

type	线型	箭头	语义
sync	实线 1.5px slate #94A3B8	实心三角	同步调用
async	实线 1.5px slate #94A3B8	空心三角	异步消息 / 通知
return	虚线 1.5px slate #64748B	空心三角	返回 / 回调
self	向右绕出的 bracket 环形箭头	—	自身内部调用

每条消息 label 采用「编号 + 内容」格式（如 5. Redirect with auth_code），等宽字体 10pt 居中标注在箭头正上方。self 类型的消息（如示例中的 9. validate token）必须画成从 lifeline 向右绕一圈再回到同一条 lifeline 的 bracket 形状，不能画成水平直线。

activation_bars：激活条

"activation_bars": {
  "enabled": "{argument name=\"activation_bars_enabled\" default=\"true\"}",
  "rule": "在 actor lifeline 上画细长矩形（4-6px 宽）覆盖该 actor 处理消息的时间段；颜色用 actor 的 type color，半透明",
  "vertical_extent": "从该 actor 收到一个 message 开始，到它发出 return 结束"
}

激活条是区分「谁在处理」的关键视觉元素：4-6px 宽的细长矩形，用 actor 的类型色半透明填充，纵向范围从「收到消息」延伸到「发出 return」，即覆盖 actor 处理消息的整段时间。默认开启。

annotations：注释与 alt/loop 框

"annotations": {
  "notes": {
    "enabled": "{argument name=\"notes_enabled\" default=\"false\"}",
    "rule": "可在某段时序旁画黄色便签（amber 半透明圆角矩形），加注释；如 'PKCE prevents code interception'"
  },
  "loops_alts": {
    "enabled": "{argument name=\"loops_alts_enabled\" default=\"false\"}",
    "rule": "可用 UML alt / loop 框：圆角矩形包围多条消息，左上角标 'alt' / 'loop' + 条件文本"
  }
}

两个扩展注释系统，默认都关闭，按需开启：

• notes：在关键消息旁加 amber 半透明圆角便签写注释（如解释 PKCE 防止 code 被截获）。
• loops_alts：用 UML 标准 alt（分支）/ loop（循环）框包围多条消息，框左上角标注 alt / loop + 条件文本，用于表达失败重试、条件分支、循环调用。

legend：图例

"legend": {
  "enabled": true,
  "position": "bottom-right",
  "content": "actor type → color, message style → meaning (sync solid arrow / async hollow / return dashed / self bracket)",
  "style": "small panel, semi-transparent bg, mono 10pt"
}

图例默认必须启用、固定在右下角：左侧解释 actor 类型 → 颜色映射，右侧解释四种消息箭头的含义。它是读者理解颜色与线型语义的唯一入口，模板在 constraints.must_keep 中明确要求「legend 必画」。

constraints：必须遵守与必须避免

"constraints": {
  "must_keep": [
    "actor headers 等大小、等间距、水平对齐",
    "lifelines 垂直、等间距",
    "messages 严格按时间从上到下排列",
    "每条 message 有编号 + 简洁标签",
    "sync / return / async 用不同箭头风格区分",
    "暗色 grid 背景 + 等宽字体",
    "legend 必画"
  ],
  "avoid": [
    "actor header 大小不一",
    "messages 不按时间顺序",
    "self-call 画成水平直线（必须 bracket / loop 形）",
    "return 用实线箭头（破坏语义）",
    "label 与 lifeline 重叠",
    "用 emoji 当 actor 图标",
    "actor > 6 个（拥挤；考虑拆分）",
    "messages > 15 条（视觉爆炸；考虑分子时序）",
    "声称这是可编辑 SVG"
  ]
}

这份约束是「工程感」的保证：actor 上限 6 个、消息上限 15 条，超出就要拆分分子时序图；emoji 禁止作为 actor 图标（破坏工程感）；return 用实线会与 sync 混淆，破坏语义。

参数策略：必问 / 可默认 / 可随机

模板在 JSON 之后明确给出了三档参数策略：

• 必问：title、actors 列表、messages 序列（含 from / to / label / type）
• 可默认：activation_bars_enabled（true）、type_color_map、notes_enabled（false）、loops_alts_enabled（false）
• 可随机：actor icon glyph 具体造型、消息标签字号微调

这套「必问 / 默认 / 随机」的三分法正是 prompt-writing.md 第六章「参数设计规则」的标准实践：核心参数缺失会显著影响结果所以要问，默认参数不影响模板正常工作所以直接给默认值，随机参数允许在风格范围内合理生成。

自动补全策略

模板提供了四条开箱即用的自动补全规则，让 Agent 在用户信息不完整时也能直接开工：

• 用户说「我要画 OAuth 流程」→ 默认 4 actor + 10 消息（用户 → web → auth → resource），即主模板的默认配置
• 用户没说 sync / async → 默认 sync；明显的回调 / 通知场景默认 async
• 用户说「含失败重试」→ 启用 loops_alts_enabled + alt block 包围
• 用户说「加注释解释」→ 启用 notes_enabled
• 用户说要 light 模式 → 用变体 1

三套变体：按场景快速切换

变体都基于主模板做局部 modify，不脱离主结构。

变体 1：浅色 Light 时序图

适用于白底文档、印刷版、Notion / GitHub 白底页面：

{
  "modify": {
    "background": "warm off-white #F8FAFC + faint grid #E2E8F0",
    "actor_header_fill": "type color × 8% opacity",
    "actor_header_border": "1.5px solid (deeper shade for white bg)",
    "label_color": "deep slate #0F172A",
    "lifeline_color": "slate #94A3B8 dashed",
    "vibe": "白底文档 / 印刷版友好"
  }
}

核心变化：背景从深色翻转为暖白 #F8FAFC，标签文字加深为 #0F172A，actor 填充透明度降为 8%，边框用加深后的类型色保证白底可读。

变体 2：协议握手 / OAuth / 鉴权专用风

适用于 OAuth 2.0 / OIDC / SAML / mTLS 等协议教学与鉴权流程文档：

{
  "modify": {
    "messages_emphasis": "为安全 / token 类消息加 🔒 等价 glyph 或 'TLS' / 'signed' 小标签",
    "extras": "在 message 上额外标 HTTP method（GET/POST/PUT），加微小 mono 标签",
    "annotation": "加 PKCE / nonce / state 解释 note，notes_enabled = true",
    "use_case": "OAuth 2.0 / OIDC / SAML / mTLS 等协议"
  }
}

增强点：token / 安全类消息加锁形 glyph 或 TLS / signed 标签；消息上额外标注 HTTP method（GET / POST / PUT）；打开 notes 解释 PKCE / nonce / state 等协议细节。

变体 3：分布式事务 / Saga / 2PC 风

适用于 Saga / 2PC / TCC / outbox pattern 教学、架构 review、failure mode 分析：

{
  "modify": {
    "actor_types": "通常 4-5 个 service actor + 1 个 coordinator + 1 个 message broker",
    "messages_emphasis": "明确标 prepare / commit / rollback / compensate 阶段，用不同颜色 (commit 绿、rollback 红、prepare 蓝)",
    "loops_alts_enabled": true,
    "alt_blocks": "alt 'commit phase' / 'rollback phase' 包围相应消息",
    "use_case": "Saga / 2PC / TCC / outbox pattern 教学和文档"
  }
}

核心变化：actor 阵容换成 service + coordinator + message broker；消息按 prepare / commit / rollback / compensate 分阶段标色（commit 绿、rollback 红、prepare 蓝）；打开 alt 框分别包围 commit phase 与 rollback phase。

仓库实战案例：两套已落地的时序图 JSON

仓库的官网案例目录中内置了两套真实渲染过的时序图 JSON，是主模板的最佳实践样本：

案例一：1.json —— OAuth 2.0 授权码 + PKCE

• 画布 16:9，标题「OAuth 2.0 Authorization Code + PKCE」、副标题「Keycloak 24 · SPA @ app.nimbus.id」
• 4 个 actor：User（user）、Web SPA (React)（client）、Keycloak（service）、BFF (FastAPI + RS256)（service）
• 10 条消息完整走完授权码 + PKCE 主路径：点击登录 → SPA 生成 code_verifier 并推导 code_challenge（self 调用）→ GET /authorize → 302 展示登录页 → 提交凭据 → 302 携带 code + state 回调 → POST /token 携带 code_verifier → 返回 access_token / id_token / refresh_token → BFF 携带 Bearer token 访问 /v1/tenants → 返回租户与权限
• 启用了 notes（M3 旁解释 PKCE 防 code 截获、state 与 OIDC nonce 需校验），loops_alts 关闭（仅主路径）

案例二：2.json —— 微信支付统一下单到回调

• 画布 4:3（actor 较多时的推荐比例），标题「WeChat Pay · unified order to notify」、副标题「mchid 1900006XXX · H5/公众号场景」
• 4 个 actor：Payer（user）、商户后端 order-svc（client）、WeChat pay API v3（external，对应类型色 slate 灰）、手机微信客户端（client）
• 目标是突出商户系统、微信支付平台、手机微信客户端三方的同步调用与 notify_url 回调

这两个案例验证了模板的两个典型场景分支：一个是标准的 OAuth 鉴权时序（变体 2 的实践），一个是第三方支付协议的「客户端 - 服务器 - 第三方」三方时序，且都严格遵守了消息编号、sync / return 箭头区分、legend 必画等 must_keep 约束。

接入 gpt-image-2 运行模式：把渲染好的 prompt 变成图

时序图模板产出的是「渲染后的 prompt」，真正出图需要走 gpt-image-2 技能的运行流程。该技能有 3 种运行模式（详见 SKILL.md 的运行模式章节），任何任务的第一步都是先探测模式：

node skills/gpt-image-2/scripts/check-mode.js
# 想拿结构化结果给上层程序用：
node skills/gpt-image-2/scripts/check-mode.js --json

探测脚本（check-mode.js）依据两个环境变量判定模式：ENABLE_GARDEN_IMAGEGEN 为真（1 / true / yes / on）且存在 OPENAI_API_KEY 时进入 Mode A（Garden 本地生图）；未启用但宿主有图像工具进入 Mode B（委托宿主出图）；两者皆无进入 Mode C（仅产出高质量 prompt 给用户）。

• Mode A：模板渲染完成后，保存 prompt 到 garden-gpt-image-2/prompt/，调用 generate.js 出图，图片落到 garden-gpt-image-2/image/：

node skills/gpt-image-2/scripts/generate.js \
  --promptfile garden-gpt-image-2/prompt/sequence-diagram-oauth-20260424-153045.md \
  --size 1792x1024 \
  --quality high

脚本内部（见 shared.js）会按 OpenAI 兼容接口把渲染后的 prompt 作为 prompt 字段 POST 到 ${OPENAI_BASE_URL}/images/generations，按 data[0].b64_json（兼容 data[0].url）解析图片字节并落盘，文件名按「任务语义 slug + 时间戳」自动生成，如 garden-gpt-image-2/image/sequence-diagram-oauth-20260424-153045.png。

• Mode B：把渲染好的最终 prompt 直接传给宿主自带的 image_generation 类工具，图片去向由宿主决定，prompt 可顺手存副本。
• Mode C：把最终 prompt 保存到 garden-gpt-image-2/prompt/<task-slug>-<timestamp>.md 并展示给用户，附一句在哪些图像工具中可复用的建议。

注意：sequence-diagram.md 里的 JSON 是提示词结构模板，不是 API 请求体模板。最终交给图像模型的是一段「渲染后的 prompt 字符串」，可以是拍平的 JSON，也可以是结构化自然语言段落（规则见 SKILL.md 的「重要约束」与 prompt-writing.md）。

避免事项清单（最容易翻车的地方）

模板在结尾集中列出了最容易让时序图失去「时序性」和「工程感」的失败模式：

• messages 不按时间从上到下排列 → 失去时序性
• 用菱形 / 圆形当 actor（必须矩形 header）
• self-call 画成水平直线（必须 bracket / loop 形）
• return 用实线箭头（与 sync 混淆，破坏语义）
• actor 超过 6 个 → 视觉拥挤，考虑拆分
• messages 超过 15 条 → 视觉爆炸，考虑分子时序
• 用 emoji 当 actor 图标
• 把 actor 头像做成卡通人物 → 失去工程感
• 没有激活条 → 看不出谁在处理
• 没有消息编号（教学场景必须有）
• 把「流程图」画成时序图（节点应该是动作而非 actor）

小结

sequence-diagram.md 是 gpt-image-2 技能 Technical Diagrams 分类中聚焦「时间维度」的模板：它以 5 种 actor 类型编码配色、4 种消息箭头语义、激活条与可选 alt/loop 框，把 UML 时序图的全部语义要素压缩进一份可替换 JSON，并通过「必问 / 默认 / 随机」的参数策略与自动补全规则保证最小输入即可出图。配合 Mode A 生图脚本与仓库内置的 OAuth / 微信支付案例，你可以在 README、博客、协议文档、安全评审与分布式事务教学中快速获得高质量的工程感时序图配图——只要记得：它是位图，不承诺可编辑。