7个参与者、12条消息、不足100行JSON：Archify时序图如何追出一条缓存缺失的API调用链

7个参与者、12条消息、不足100行JSON：Archify时序图如何追出一条缓存缺失的API调用链

【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify

接口变慢，你却说不清慢在哪一跳：是鉴权慢了、缓存白跑了，还是数据库回源太贵？这类问题靠口述很难对齐，靠日志又要拼半天。本文用 Archify 的时序图（sequence，按时间轴把"谁在何时调用了谁"画出来的图型）复现一次缓存缺失请求，从安装、跑通示例到迁移到你自己的 API 链路，全部是可粘贴运行的短命令。

Archify一行命令装好：给编码Agent加上出图技能

Archify 是一个面向 AI Agent 的图表渲染与校验系统：Agent 产出带类型的JSON IR（Intermediate Representation，中间表示——图内容的结构化描述文件），它把它确定性编译成自包含 HTML——单个文件即可分享，内置动画与多格式导出，支持架构图、工作流图、时序图、数据流图、生命周期图五种图型。

它适配 Cursor、Claude Code、Codex CLI 和 OpenCode，安装只需一行：

npx skills add tt-a1i/archify -g npx skills use tt-a1i/archify@archify --agent codex

第一条是全局安装，装完对 Agent 说一句"用 archify 画这个仓库的架构图"即可；第二条免安装直接试一次，适合先体验再决定装不装。装好后让 Agent 描述场景，它会生成 JSON IR 并渲染，不需要你手动写渲染代码。

不确定该用哪种图时，可以问零依赖的场景指南命令：

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss" --json --lang zh

它会推荐图型并返回配方，--lang zh输出中文——但图本身要由你和 Agent 亲手描述场景，而不是套模板。

跑通缓存缺失示例：一次API请求的12跳调用链

仓库内置一个现成样例 cache-miss-request.sequence.json：用户打开一个需要鉴权的仪表盘页面，缓存没命中，API 回源数据库再写回缓存。7 个参与者（User、Web App、API、Auth、Redis、Postgres、Trace）、12 条消息，整个文件不足 100 行 JSON。渲染成品见 sequence-cache-miss-request.html。

调用链按 3 个分段（segment，timeline 上的背景色块，用来把长流程切成几幕）推进，时间从上往下走：

第 1–4 跳 · Request（请求幕）

1. User → Web App：open page，用户打开页面；
2. Web App → API：GET /dashboard，主请求，标记为emphasis（强调样式）；
3. API → Auth：verify JWT，鉴权调用，标记为security（安全样式）；
4. Auth → API：claims ok，鉴权通过，标记为return（返回样式）。

第 5–8 跳 · Fallback（回源幕）5. API → Redis：read cache，先查缓存； 6. Redis → API：miss——缓存缺失，这是整条链的转折点； 7. API → Postgres：query profile + metrics，回源主库，同样是emphasis； 8. Postgres → API：rows，数据到手。

第 9–12 跳 · Response + trace（响应幕）9. API → Redis：set cache，写回缓存，dashed虚线表示异步、不阻塞主路径； 10. API → Trace：emit trace，上报链路埋点，也是虚线旁路； 11. API → Web App：200 JSON，响应返回； 12. Web App → User：render，页面渲染完成。

两条虚线旁路很关键：写缓存和埋点都不卡着用户等，用户感知的延迟和可观测性开销在图上天然分离——这正是排查"慢在哪一跳"时最想知道的事实。

缓存缺失时序图怎么看：图例五分类与激活条

打开渲染产物后，建议按下面这张清单看：

这套风格约定写在时序渲染器文档里：主路径用强调样式，安全调用单独着色，异步埋点一律降调。

数据源文件里，决定这张图的骨架是四组字段（完整约束见 sequence.schema.json）：

• participants：参与者横排列表，每项带id、语义type（frontend/backend/database/security等）和标签——{ "id": "redis", "type": "database", "label": "Redis", "sublabel": "cache" }
• messages：每条箭头消息，from/to定端点，y定时间轴位置，variant定样式——{ "id": "cache-miss", "from": "redis", "to": "api", "label": "miss", "variant": "return" }
• segments：背景分段，from/to是 y 像素区间——{ "from": 315, "to": 505, "label": "Fallback" }
• activations：激活条，标注某参与者的忙碌时段——{ "participant": "db", "from": 438, "to": 496, "type": "database" }

想要分幕讲解，还能在meta.views里配最多 5 个命名章节，示例配了 3 章（Request and identity / Cache fallback / Return and trace）：

{ "id": "cache-fallback", "label": "Cache fallback", "focus": ["api", "redis", "db"] }

再开meta.animation: "trace"，箭头会按调用顺序逐段点亮，适合演示。

它凭什么画得对：schema校验、布局门禁与SHA-256回执

整条管线是确定性的"从语义到像素"编译，每一步都有门禁：

1. schema 校验：渲染前先用内置校验器按 JSON Schema 逐项检查，字段缺了、类型错了当场报错，无需安装任何依赖；
2. 布局检查：参与者放不进画布、消息间距过密、箭头越出时间轴、标签比盒子还宽……这些"画得出来但画错了"的问题都会直接报错退出，而不是给你一张坏图。showcase档位还额外拒绝无关消息交叉、过短的路由片段；
3. 确定性渲染：同一份 JSON 永远编译出同一份 HTML，布局规则（消息最小垂直间距 28px、箭头水平跨度 60px 等）写死在渲染器里，不靠模型"感觉"。

失败时也不是给你一坨堆栈：validate --json会返回稳定的规则码、具体出错对象和可用修复项，只改被点名的地方再跑一遍即可。

交付环节的可信度来自deliver：它把规格文件字节级冻结成快照再渲染，输出的 HTML 附带SHA-256 回执（一种哈希值——相当于文件的数字指纹）和字节数。你转给同事的那一个 HTML 文件，和它背后的 JSON 是可以对上指纹的；验收标准要求0 错误 0 警告。

交互与导出：分章播放、路由追踪与1200×630分享卡

用浏览器打开渲染好的 HTML，它不是一张死图：

• 分章讲解：顶部 3 个章节按钮各自聚焦相关参与者；按P或点Play story自动播放整条调用链；
• 路由追踪（Route probe——沿图上已画好的边找出一条最短路径并亮出来）：选中 Web App 到 Postgres 的路径，面板显示"3 nodes · 2 directed hops · shortest authored route"，还能复制深链或导出该路径的分享卡片；
• 主题切换：右上角一键切 Dark / Light，深浅两套配色；
• 多格式导出：Export 菜单支持复制 PNG 到剪贴板、下载静态图、带运动的 WebM，以及 1200×630 的社交分享卡。

迁移到你自己的项目：5步checklist

把示例换成你自己的系统，照着做即可：

1. 列参与者：网关、鉴权、缓存、主库各归其位，语义type按实际角色选（frontend/backend/database/security/messagebus等）；

2. 按时间写消息：主路径emphasis、返回return、鉴权security、埋点旁路dashed，每条给一个稳定id；

3. 切分段时间线：用 2–3 个 segment 划分"请求 / 回源 / 响应"，给关键服务加激活条；

4. 校验到 0 错误 0 警告：

   node archify/bin/archify.mjs validate sequence my-request.sequence.json --quality showcase --json

   只改诊断点名的对象，改完重跑，直到 0 错误 0 警告；

5. 交付 + 视觉复查：

   node archify/bin/archify.mjs deliver sequence my-request.sequence.json out.html --quality showcase --json node archify/bin/archify.mjs visual-check out.html --json

   第一条冻结快照、渲染并给出 SHA-256 回执；第二条在 1440×900 到 2048×1320 多档桌面分辨率下确认不溢出，退出码 0 即通过。

单文件快速渲染也可以直接调渲染器（自带校验，无需装依赖）：

node archify/renderers/sequence/render-sequence.mjs cache-miss-request.sequence.json output.html

成功后浏览器打开output.html就能看到可交互成品；更多字段约定查 authoring-contract.md 和中文撰写手册。

资源速查表

回到开头那个问题：慢在哪一跳？现在你手里有了一张 7 参与者、12 条消息、指纹可核对的调用链图——鉴权窗口多长、缓存为什么 miss、回源窗口多窄，都在激活条和分段里摆着。业务事实由你讲，画得对、画得稳、可复现可核对这件事，交给 Archify 的校验管线和确定性渲染去把关。

【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify