[teamai] Push 87 resource(s) from XingfenD

2026-09-10 16:10:45 +08:00
parent 425c9c078a
commit 65c04def51
1314 changed files with 211681 additions and 0 deletions
@@ -0,0 +1,262 @@
+# 时序图模板
+
+> ⚠️ **本模板生成的是位图（PNG）**，不是 PlantUML / mermaid 可编辑时序图。
+> 需要可编辑请用 mermaid / PlantUML / draw.io。
+
+本文件用于生成"工程感时序图"：
+
+- API 调用时序（前端 → 后端 → DB）
+- 鉴权 / OAuth / 多步握手时序
+- 微服务间消息传递时序
+- 分布式事务 / Saga / 2PC 时序
+- 客户端 - 服务器 - 第三方 三方协议时序
+
+特征：
+
+- 顶部一排 actor 框（带名字 + 类型 icon）
+- 每个 actor 下方一条垂直虚线（lifeline）
+- 水平消息箭头连接 actors（实箭头同步、虚线箭头异步 / return）
+- lifeline 上有"激活条"（细长矩形）表示该 actor 正在处理
+- 消息可编号（1, 2, 3...）
+- 暗色 grid 背景 + 等宽字体
+
+## 适用范围
+
+- API 调用时序
+- 鉴权 / OAuth 流程
+- 微服务消息时序
+- 分布式事务 / Saga / 2PC
+- 第三方协议 / SDK 调用流
+
+## 何时使用
+
+- 用户提到 "时序图 / sequence diagram / 调用时序 / API 流 / OAuth 流 / 分布式事务"
+- 用户希望「actor + lifeline + 消息箭头」标准 UML 时序图样式
+- 用户接受位图
+
+不要使用：
+
+- 用户要的是「业务流程 / 决策」 → 用 `technical-diagrams/flowchart-decision.md`
+- 用户要的是「状态机」 → 用 `technical-diagrams/state-machine.md`
+- 用户要的是「系统架构」 → 用 `technical-diagrams/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）
+
+## 主模板：标准 UML 时序图
+
+📖 描述
+
+整张图顶部一排 actor 框，下方每个 actor 一条垂直虚线 lifeline，水平消息箭头连接 actors，激活条标在 lifeline 上，消息编号 + 标签清晰。
+
+📝 提示词
+
+```json
+{
+  "type": "工程感时序图（UML sequence diagram）",
+  "goal": "生成一张工程感时序图作为 README / blog / 协议文档配图",
+  "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"
+  },
+  "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"
+  },
+  "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"
+    }
+  },
+  "lifelines": {
+    "rule": "每个 actor header 下方画一条垂直虚线 (1px dashed slate #475569)，从 header 底部一直延伸到画布底部",
+    "spacing": "lifelines 之间等距，间距 ≥ 200px"
+  },
+  "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 上方居中"
+  },
+  "activation_bars": {
+    "enabled": "{argument name=\"activation_bars_enabled\" default=\"true\"}",
+    "rule": "在 actor lifeline 上画细长矩形（4-6px 宽）覆盖该 actor 处理消息的时间段；颜色用 actor 的 type color，半透明",
+    "vertical_extent": "从该 actor 收到一个 message 开始，到它发出 return 结束"
+  },
+  "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' + 条件文本"
+    }
+  },
+  "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"
+  },
+  "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"
+    ]
+  }
+}
+```
+
+### 参数策略
+
+- **必问**：`title`、actors 列表、messages 序列（含 from/to/label/type）
+- **可默认**：`activation_bars_enabled`（true）、`type_color_map`、`notes_enabled`（false）、`loops_alts_enabled`（false）
+- **可随机**：actor icon glyph 具体造型、消息标签字号微调
+
+### 自动补全策略
+
+- 用户给"我要画 OAuth 流程" → 默认 4 actor + 10 消息（用户 → web → auth → resource）
+- 用户没说 sync / async → 默认 sync；明显的回调 / 通知场景默认 async
+- 用户说"含失败重试" → 启用 `loops_alts_enabled` + alt block 包围
+- 用户说"加注释解释" → 启用 `notes_enabled`
+- 用户说要 light 模式 → 用变体 1
+
+## 变体 1：浅色 Light 时序图
+
+```json
+{
+  "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": "白底文档 / 印刷版友好"
+  }
+}
+```
+
+## 变体 2：协议握手 / OAuth / 鉴权专用风
+
+```json
+{
+  "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 等协议"
+  }
+}
+```
+
+适用：协议教学、鉴权流程文档。
+
+## 变体 3：分布式事务 / Saga / 2PC 风
+
+```json
+{
+  "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 教学和文档"
+  }
+}
+```
+
+适用：分布式事务模式教学、架构 review、failure mode 分析。
+
+## 避免事项
+
+- 时序图但 messages 不按时间从上到下 → 失去时序性
+- 用菱形 / 圆形当 actor（必须矩形 header）
+- self-call 画成直线（必须 bracket）
+- return 用实线（与 sync 混淆）
+- actor > 6 → 视觉拥挤，考虑拆分
+- messages > 15 → 视觉爆炸
+- 用 emoji 当 actor 图标
+- 把 actor 头像做成卡通人物 → 失去工程感
+- 没有 activation 条 → 看不出谁在处理
+- 没有 message 编号（教学场景必须有）
+- 把"流程图"画成时序图（节点应该是动作而非 actor）