慢请求慢了 3 秒？用 Archify 时序图追平整条 API 调用链
项目地址: https://gitcode.com/GitHub_Trending/arch/archify 昨晚的值班工单：首页 Dashboard 打开要 3 秒，日志只说"慢"，到底卡在哪一跳？这种问题靠日志猜是猜不出来的，需要一张时序图——而 Archify 时序图干的就是这件事。Archify 是一个面向 AI Agent 的图表技能（Skill），把代码库或系统描述变成可验证的交互式图表，覆盖架构、工作流、时序、数据流、生命周期五种类型，输出自带动画和高清导出的自包含 HTML。这篇拿它自带的"缓存缺失请求"示例，把一次完整的 API 调用链从头追到尾。
先回答一个问题：这张图画的是"谁调谁"
架构图回答"谁和谁相连"，时序图回答"谁在什么时候调用了谁"。排查慢请求时你要看的恰恰是后者：
- 请求走了几跳，每一跳的激活条有多长；
- 缓存是命中还是缺失，缺失后回源数据库付出了什么代价；
- 哪些调用阻塞主路径，哪些只是异步旁路（比如 trace 埋点）。
这也是 Archify 技能路由表里 sequence 的定位：API call chains、request lifecycles、async traces、returns。别急着套模板——拿不准用哪种图时，可以直接问内置的场景指南：
# 在 archify 目录下执行
node bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json --lang zh
指南会返回推荐类型和配方，但图本身仍然要你和 Agent 亲手描述——配方只是起点。
三行命令把 Archify 跑起来
Archify 是 Node.js 渲染与校验系统，适配 Cursor、Claude Code、Codex CLI 和 OpenCode。安装就一行：
npx skills add tt-a1i/archify -g
不想安装就先试一次：
npx skills use tt-a1i/archify@archify --agent codex
装好后对 Agent 说一句话就能开工："Use archify to trace this API request with a cache miss."
7 站、3 幕：拆一张缓存缺失示例
仓库里自带教科书级示例 cache-miss-request.sequence.json，渲染成品在 sequence-cache-miss-request.html。时间从上往下走，7 个参与者横向排开：User → Web App → API → Auth → Redis → Postgres → Trace。
整条链被 3 个 segment 背景色带切成三幕：Request（打开页面、完成 JWT 鉴权）、Fallback（读缓存 miss、回源 Postgres）、Response + trace（写回缓存、异步上报、响应返回）。你注意看 set cache 和 emit trace 这两条紫色虚线——它们是异步旁路，不阻塞主路径，这是整张图里最容易被误读成"主流程变长"的部分。
图例把消息风格分成五类，这套约定直接决定了读图效率：
| 风格（variant） | 在图里的角色 | 本例中的消息 |
|---|---|---|
emphasis | 主请求路径，最醒目 | GET /dashboard、query profile + metrics |
security | 鉴权、权限类调用，单独着色 | verify JWT |
return | 返回消息，画得安静一些 | claims ok、miss、rows、200 JSON、render |
dashed | 异步、非阻塞的旁路工作 | set cache、emit trace |
default | 其余普通消息 | open page、read cache |
这套规则的效果是：用户感知的延迟和可观测性开销在同一张图上自然分离，一眼能看出主路径其实只有 Web App → API → Postgres 这么短。具体设计规则可查 sequence 渲染器文档。
调用链就 4 个 JSON 字段
时序图源文件是一份带类型的 JSON IR，骨架只有四块：
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 像素区间，用来把时间线切成三幕；activations：激活条，相当于参与者"忙不忙的指示灯"——Postgres 只有一小段激活条，直观说明回源窗口很短。
想要更精细的展示，meta.views 里最多可配 5 个命名章节（示例配了 3 章：Request and identity、Cache fallback、Return and trace），再开 meta.animation: "trace" 让箭头按调用顺序逐段点亮。完整字段约束见 sequence.schema.json。
渲染器很"严"：宁报错，不画坏图
写好后管线会先做 schema 校验，再做布局检查——参与者放不下、消息间距过密、箭头越界，都会直接报错而不是产出一张坏图：
# 单文件渲染（仓库根目录执行，内置校验器，无需装依赖）
node archify/renderers/sequence/render-sequence.mjs examples/cache-miss-request.sequence.json output.html
# 进入 archify 目录：探索期校验 + 交付期终检（showcase 级别要求 0 错误 0 警告）
cd archify
node bin/archify.mjs validate sequence examples/cache-miss-request.sequence.json --quality showcase --json
node bin/archify.mjs deliver sequence examples/cache-miss-request.sequence.json examples/sequence-cache-miss-request.html
validate 报错时别急着整图重画，先看诊断定位到具体的 subject：通常是某一个参与者放不下、两条消息间距小于 28px 这类单点问题。deliver 会把规格文件字节级冻结成快照再渲染，输出 HTML 附带 SHA-256 回执——你分享给同事的那个文件，和它背后的 JSON 是对得上的。
整个管线是"从语义到像素"的确定性编译：自然语言或 Mermaid → Agent 推断空间关系 → JSON IR + Schema 校验 → 类型化渲染器 + 布局规则检查 → 独立 HTML + 多倍率导出。
打开渲染出来的 HTML：别只看不玩 🎬
用浏览器打开成品，缓存缺失时序图并不只是张静态图：
- 分章讲解：顶部 3 个章节按钮逐章聚焦相关参与者，
Play story可以自动播放整条调用链，演示时特别好用； - 路由追踪：选中 Web App 到 Postgres 的路径后，面板显示 "3 nodes · 2 directed hops · shortest authored route"，还能一键复制深链、导出 1200×630 的路由分享卡片；
- 主题与导出：右上角 Dark/Live 切换深浅色，Export 菜单可复制 PNG 到剪贴板、下载静态图、带运动的 WebM 或社交分享卡。
换成你自己系统的 API 链
把示例换成你的系统，四步就行：
- 列出这条请求链的参与者（网关、鉴权、缓存、主库……），语义
type各归其位； - 按时间顺序写下每条消息：主路径
emphasis、返回return、鉴权security、旁路埋点dashed； - 用 2–3 个 segment 切分时间线，给关键服务加激活条；
- 跑
validate→deliver，再让visual-check确认多档桌面分辨率下不溢出：
node bin/archify.mjs visual-check output.html --json
这条命令会在 1440×900 到 2048×1320 多档分辨率下测量内容是否完整包含在视口内，退出码就是结论。更多字段约定查 authoring-contract.md 和中文版 authoring-cookbook.zh-CN.md。
那 3 秒的慢请求，从此不用再翻日志猜了——一张时序图，每一跳、每一条旁路都摆在明面上。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
