@stacksjs/defaults 0.75.360 → 0.75.362

package/ai/skills/stacks-technical-diagrams/examples/delivery.explainer.json

@@ -0,0 +1,155 @@
+{
+  "schema_version": 1,
+  "diagram_type": "explainer",
+  "meta": {
+    "title": "缓存未命中时，请求为什么变慢？",
+    "id": "mechanism",
+    "locale": "zh-CN"
+  },
+  "answer": {
+    "summary": "缓存未命中后，请求要多等**数据库查询和同步写回缓存**两段。",
+    "reasons": [
+      "命中时，接口读到缓存值就能返回。",
+      "未命中时，接口必须先拿到数据库结果。",
+      "同步写回位于响应之前，写完缓存才能结束请求。"
+    ],
+    "scope": "示例采用旁路缓存：GET返回空值后查询PostgreSQL，查询成功后同步SET再响应；无并行、重试或其他缓存层。未实测耗时，具体慢多少由链路测量决定。"
+  },
+  "panels": [
+    {
+      "id": "timeline",
+      "title": "一次未命中，时间花在哪？",
+      "blocks": [
+        {
+          "type": "steps",
+          "id": "cache-path-steps",
+          "items": [
+            {
+              "id": "get-step",
+              "text": "读取缓存",
+              "detail": "GET返回空值，接口继续向数据库查询。[](source:get-doc)"
+            },
+            {
+              "id": "query-step",
+              "text": "查询PostgreSQL",
+              "detail": "等待数据库执行SQL并返回结果。"
+            },
+            {
+              "id": "set-step",
+              "text": "同步写回Redis",
+              "detail": "SET完成后，接口返回响应。[](source:set-doc)"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "diff",
+      "title": "命中和未命中，差在哪几步？",
+      "blocks": [
+        {
+          "type": "comparison",
+          "id": "cache-comparison",
+          "columns": [
+            "命中",
+            "未命中"
+          ],
+          "rows": [
+            {
+              "label": "读Redis",
+              "cells": [
+                {
+                  "text": "取得值",
+                  "assessment": "good",
+                  "verdict": "直接返回"
+                },
+                {
+                  "text": "取得空值",
+                  "assessment": "caution",
+                  "verdict": "继续查询"
+                }
+              ],
+              "id": "row-67fe9814e476"
+            },
+            {
+              "label": "查PostgreSQL",
+              "cells": [
+                {
+                  "text": "跳过",
+                  "assessment": "good",
+                  "verdict": "省去查询"
+                },
+                {
+                  "text": "等待结果",
+                  "assessment": "caution",
+                  "verdict": "增加等待"
+                }
+              ],
+              "id": "row-bb530b3792c8"
+            },
+            {
+              "label": "写回Redis",
+              "cells": [
+                {
+                  "text": "跳过",
+                  "assessment": "good",
+                  "verdict": "省去写回"
+                },
+                {
+                  "text": "同步SET",
+                  "assessment": "caution",
+                  "verdict": "增加等待"
+                }
+              ],
+              "id": "row-cbc9f8528502"
+            },
+            {
+              "label": "响应路径",
+              "cells": [
+                {
+                  "text": "一段读取",
+                  "assessment": "good",
+                  "verdict": "路径短"
+                },
+                {
+                  "text": "三段顺序等待",
+                  "assessment": "caution",
+                  "verdict": "路径长"
+                }
+              ],
+              "id": "row-d108c6645625"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "checks",
+      "title": "想缩短等待，先查什么？",
+      "blocks": [
+        {
+          "type": "list",
+          "ordered": false,
+          "items": [
+            "记录`cache=hit`或`cache=miss`，区分请求路径。",
+            "分别观察GET、SQL和SET耗时，先处理最慢的一段。",
+            "检查SQL索引与执行计划；改为异步写回前，设计写入失败的恢复流程。"
+          ],
+          "id": "list-7e8599e477aa"
+        }
+      ]
+    }
+  ],
+  "sources": [
+    {
+      "id": "get-doc",
+      "title": "Redis GET：不存在的键返回空值",
+      "url": "https://redis.io/docs/latest/commands/get/"
+    },
+    {
+      "id": "set-doc",
+      "title": "Redis SET：设置键值",
+      "url": "https://redis.io/docs/latest/commands/set/"
+    }
+  ]
+}

package/ai/skills/stacks-technical-diagrams/examples/deployment-release.lifecycle.json

@@ -1,49 +1,72 @@
 {
-  "schema_version": 1,
+  "schema_version": 3,
   "diagram_type": "lifecycle",
   "meta": {
     "title": "Deployment Release Lifecycle",
     "output": "examples/deployment-release.html",
-    "viewBox": [980, 680],
     "animation": "trace",
     "visual_preset": "signal-flow",
-    "quality_profile": "showcase",
-    "views": [
-      { "id": "promotion-rail", "label": "Promotion rail", "focus": ["queued", "building", "verifying", "ready", "live"], "note": "Follow the deployment object from accepted change to healthy production." },
-      { "id": "approval-gate", "label": "Approval gate", "focus": ["verifying", "approval", "cancelled", "ready"], "note": "Approval pauses promotion and can terminate the release cleanly." },
-      { "id": "rollback-outcomes", "label": "Rollback outcomes", "focus": ["ready", "rollback", "failed", "live", "paused", "rolled_back"], "note": "Separate pre-promotion failure from post-promotion health regression." }
-    ]
+    "quality_profile": "showcase"
   },
-  "lanes": [
-    { "id": "main", "label": "Release phases" },
-    { "id": "waiting", "label": "Approval + health wait" },
-    { "id": "recovery", "label": "Rollback controller" },
-    { "id": "terminal", "label": "Terminal exits" }
-  ],
+  "mainPath": ["queued", "building", "verifying", "ready", "live"],
   "states": [
-    { "id": "queued", "type": "start", "label": "Queued", "sublabel": "change accepted", "lane": "main", "col": 0, "step": "01", "tag": "pending" },
-    { "id": "building", "type": "active", "label": "Building", "sublabel": "immutable image", "lane": "main", "col": 1, "step": "02", "tag": "running" },
-    { "id": "verifying", "type": "decision", "label": "Verifying", "sublabel": "tests + policy", "lane": "main", "col": 2, "step": "03", "tag": "gate" },
-    { "id": "ready", "type": "waiting", "label": "Ready", "sublabel": "promotion pending", "lane": "main", "col": 3, "step": "04", "tag": "approved" },
-    { "id": "live", "type": "success", "label": "Live", "sublabel": "production healthy", "lane": "main", "col": 4, "step": "05", "tag": "success" },
-    { "id": "approval", "type": "waiting", "label": "Needs Approval", "sublabel": "release owner", "lane": "waiting", "col": 0, "tag": "pause" },
-    { "id": "rollback", "type": "active", "label": "Rolling Back", "sublabel": "last good image", "lane": "recovery", "col": 1, "tag": "automatic" },
-    { "id": "paused", "type": "waiting", "label": "Health Paused", "sublabel": "SLO regression", "lane": "waiting", "col": 2, "tag": "observe" },
-    { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "approval denied", "lane": "terminal", "col": 0, "tag": "terminal" },
-    { "id": "failed", "type": "failure", "label": "Failed", "sublabel": "rollback failed", "lane": "terminal", "col": 1, "tag": "terminal" },
-    { "id": "rolled_back", "type": "success", "label": "Rolled Back", "sublabel": "service restored", "lane": "terminal", "col": 2, "tag": "terminal" }
+    { "id": "queued", "type": "start", "label": "Queued", "sublabel": "change accepted", "tag": "pending", "step": "01" },
+    { "id": "building", "type": "active", "label": "Building", "sublabel": "immutable image", "tag": "running", "step": "02" },
+    { "id": "verifying", "type": "decision", "label": "Verifying", "sublabel": "tests + policy", "tag": "gate", "step": "03" },
+    { "id": "ready", "type": "waiting", "label": "Ready", "sublabel": "promotion pending", "tag": "approved", "step": "04" },
+    { "id": "live", "type": "success", "label": "Live", "sublabel": "production healthy", "tag": "success", "step": "05" },
+    { "id": "approval", "type": "waiting", "label": "Needs Approval", "sublabel": "release owner", "tag": "pause" },
+    { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "approval denied", "tag": "terminal" },
+    { "id": "paused", "type": "waiting", "label": "Health Paused", "sublabel": "SLO regression", "tag": "observe" },
+    { "id": "rollback", "type": "active", "label": "Rolling Back", "sublabel": "last good image", "tag": "automatic" },
+    { "id": "rolled_back", "type": "success", "label": "Rolled Back", "sublabel": "service restored", "tag": "terminal" },
+    { "id": "failed", "type": "failure", "label": "Failed", "sublabel": "rollback failed", "tag": "terminal" },
+    { "id": "aborted", "type": "neutral", "label": "Aborted", "sublabel": "change withdrawn", "tag": "terminal" }
   ],
   "transitions": [
-    { "from": "verifying", "to": "approval", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
-    { "from": "approval", "to": "cancelled", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
-    { "from": "ready", "to": "rollback", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
-    { "from": "rollback", "to": "failed", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
-    { "from": "live", "to": "paused", "variant": "dashed", "route": "straight", "fromSide": "bottom", "toSide": "top" },
-    { "from": "paused", "to": "rolled_back", "variant": "emphasis", "route": "straight", "fromSide": "bottom", "toSide": "top" }
+    { "id": "queued-building", "from": "queued", "to": "building", "label": "pick up" },
+    { "id": "building-verifying", "from": "building", "to": "verifying", "label": "image built" },
+    { "id": "verifying-ready", "from": "verifying", "to": "ready", "label": "checks pass" },
+    { "id": "ready-live", "from": "ready", "to": "live", "label": "promote" },
+    { "id": "verifying-building", "from": "verifying", "to": "building", "label": "tests fail" },
+    { "id": "verifying-approval", "from": "verifying", "to": "approval", "label": "needs sign-off", "variant": "security" },
+    { "id": "approval-ready", "from": "approval", "to": "ready", "label": "approved" },
+    { "id": "approval-cancelled", "from": "approval", "to": "cancelled", "label": "denied", "variant": "security" },
+    { "id": "live-paused", "from": "live", "to": "paused", "label": "SLO alert", "variant": "dashed" },
+    { "id": "paused-live", "from": "paused", "to": "live", "label": "recovered" },
+    { "id": "paused-rollback", "from": "paused", "to": "rollback", "label": "breach persists", "variant": "security" },
+    { "id": "rollback-rolled-back", "from": "rollback", "to": "rolled_back", "label": "restored", "variant": "emphasis" },
+    { "id": "rollback-failed", "from": "rollback", "to": "failed", "label": "rollback error", "variant": "security" },
+    { "id": "building-aborted", "from": "building", "to": "aborted", "label": "abort" },
+    { "id": "verifying-aborted", "from": "verifying", "to": "aborted", "label": "abort" }
   ],
   "cards": [
-    { "dot": "cyan", "title": "Promotion Rail", "items": ["The release object moves through five ordered phases", "Verification and approval remain distinct states", "Live means production health is currently proven"] },
-    { "dot": "amber", "title": "Wait States", "items": ["Human approval can pause without consuming a worker", "A health regression pauses further rollout", "Every wait exposes the event required to continue"] },
-    { "dot": "rose", "title": "Explicit Endings", "items": ["Denied approval ends as Cancelled", "Rollback controller failure ends as Failed", "Successful rollback is a terminal restored outcome"] }
+    {
+      "dot": "cyan",
+      "title": "Promotion Path",
+      "items": [
+        "The release object moves through five ordered phases",
+        "Verification and approval remain distinct states",
+        "Live means production health is currently proven"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Wait States",
+      "items": [
+        "Human approval can pause without consuming a worker",
+        "A health regression pauses further rollout",
+        "Every wait exposes the event required to continue"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Explicit Endings",
+      "items": [
+        "Denied approval ends as Cancelled",
+        "Rollback controller failure ends as Failed",
+        "Successful rollback is a terminal restored outcome"
+      ]
+    }
   ]
 }