Archify 时序图实战：完整追踪一次缓存缺失的 API 调用链-育师

Archify 时序图实战：完整追踪一次缓存缺失的 API 调用链

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

用 cache-miss-request.sequence.json 描述请求，Archify 渲染出的缓存缺失时序图不是一张静态图：箭头可按调用顺序逐段回放，任意路径可点选追踪，还能导出高清图片。它面向 AI Agent 工作，把系统描述编译成五种可验证的交互式图表，并输出自带动画的自包含 HTML。

这张时序图能回答什么问题

线上偶发慢请求，日志只告诉你"慢"，告诉不了你慢在哪一跳。时序图把时间轴摊开：谁先调用谁、哪一段是同步阻塞、哪一段只是异步旁路，全部落在一张图上。

仓库自带的示例覆盖了这条链路上的七个参与者：User、Web App、API、Auth、Redis、Postgres、Trace，时间自上而下流动，被三个segments切成三幕：

Request：用户打开页面，Web App 发出GET /dashboard，API 向 Auth 完成verify JWT；
Fallback：API 读缓存收到miss，回源 Postgres 执行query profile + metrics；
Response + trace：写回缓存、异步emit trace，200 JSON沿原路返回。

读图时有三个视觉线索值得注意。激活条（activations）标出每个参与者的忙碌区间，Postgres 的激活条只有一小段，回源窗口很短一眼可见；主请求路径用emphasis强调色，返回消息用低饱和的return；set cache与emit trace是紫色虚线的dashed旁路——用户感知的延迟与可观测性开销在图上被刻意分开。

Archify 快速上手与安装

安装只需一行：

npx skills add tt-a1i/archify -g

不想装依赖可以先跑一次：npx skills use tt-a1i/archify@archify --agent codex。之后对 Agent 提出需求，例如"用 archify 把这次 API 请求画成时序图，场景是缓存缺失"。

拿不准该用哪种图时，用内置场景指南问一句，它返回推荐类型和参考配方：

node bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json --lang zh

配方仅供参考，图仍然要按自己的系统重新描述，而不是套模板。

调用链怎么写：时序图的 JSON 描述

源文件是一份带类型的 JSON IR，完整约束在 sequence.schema.json 里。按"参与者 → 消息 → 分段"的顺序理解：

participants定义横轴上每个参与者的id、语义type（frontend、backend、database、security、messagebus等）和标签：

{ "id": "redis", "type": "database", "label": "Redis", "sublabel": "cache" }

messages是时间轴的主体：每条消息给出from、to、垂直坐标y和variant。五种风格对应图例五类——emphasis主路径、return返回消息、security鉴权类调用、dashed异步非阻塞、default普通消息。缓存缺失那条箭头就是{ "id": "cache-miss", "from": "redis", "to": "api", "label": "miss", "variant": "return" }。

segments用 y 像素区间把时间线切成 Request / Fallback / Response 三段背景；activations给忙碌参与者加激活条。长链还可以在meta.views里配置最多 5 个命名章节，并设meta.animation: "trace"让箭头按调用顺序点亮。

如何保证图不出错：校验与交付

Archify 的管线是"从语义到像素"的确定性编译：Agent 推断空间关系生成 JSON IR，schema校验把关字段合法性，layout规则把关排版。渲染器 render-sequence.mjs 内置独立校验器，无需装依赖；参与者放不下画布、消息间距过密、箭头越界这类问题都会直接报错退出，而不是画出一张"看起来还行"的坏图。

校验分探索期和交付期，交付期用deliver把规格文件冻结成快照，输出的 HTML 附带 SHA-256 回执，你分享出去的文件与背后的 JSON 一一对应：

node bin/archify.mjs validate sequence cache-miss-request.sequence.json --quality showcase --json node bin/archify.mjs deliver sequence cache-miss-request.sequence.json examples/sequence-cache-miss-request.html

--quality showcase是交付级门禁：0 错误 0 警告才放行。

图打开之后：分章播放与路由追踪

分章讲解（Guided views）：示例配了 3 个章节，顶部按钮逐章聚焦相关参与者；Play story自动播放整条调用链。
路由追踪（Route probe）：选中 Web App 到 Postgres 的路径，面板显示 "3 nodes · 2 directed hops · shortest authored route"，可复制深链或导出 1200×630 路由分享卡。
主题与导出：右上角切换 Dark/Live；Export 菜单支持复制 PNG、下载静态图、带运动的 WebM 和社交分享卡。

给自己的项目画一张调用链

☐ 列出这条请求链的参与者，语义type各归其位（网关、鉴权、缓存、主库）；
☐ 按时间顺序写messages：主路径emphasis，返回return，鉴权security，旁路埋点dashed；
☐ 用 2–3 个segments切分时间线，给关键服务补activations；
☐ 跑校验闭环：validate --quality showcase→deliver冻结交付 →node bin/archify.mjs visual-check output.html --json，在 1440×900 到 2048×1320 多档桌面分辨率下确认不溢出；
☐ 仍有排版疑虑时，对照 authoring-contract 修正措辞与坐标，或按 authoring-cookbook 的中文字段说明逐项核对。