不到 100 行 JSON 画出一次 API 调用链：Archify 时序图追出缓存缺失里的每一跳
项目地址: https://gitcode.com/GitHub_Trending/arch/archify Archify 是一个面向 AI Agent 的图表技能，它的时序图能把系统描述变成可验证的交互式图表，输出自带动画和高清导出的自包含 HTML。这篇文章跟着一条真实排障线索走：一次缓存缺失（cache miss）的 API 调用链，全程只靠几行命令和一份不到 100 行的 JSON。
一条请求是怎么变慢的
排查"为什么这次请求慢了"，你真正要看的是四件事：请求一共经过了几跳；每一跳各自花了多久；缓存是命中了还是没查到；哪些调用卡在主路径上，哪些只是异步旁路。架构图画的是"谁和谁相连"，帮你看清拓扑；而时序图画的是谁在什么时候调用了谁，时间从上往下走，每一跳的位置和时长都摆在明面上。慢在哪里，图上直接就能指出来。
两行命令完成安装与首次试跑
Archify 是一套 Node.js 渲染与校验系统，适配 Cursor、Claude Code、Codex CLI 和 OpenCode。装好之后，你对 Agent 说一句 "Use archify to trace this API request with a cache miss" 就行。不确定该用哪种图时，问一下内置场景指南，它会推荐类型并给出配方：
# 全局安装技能包
npx skills add tt-a1i/archify -g
# 不想装？免安装试一次
npx skills use tt-a1i/archify@archify --agent codex
# 场景指南：推荐图表类型并返回配方
node bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json --lang zh
📖 把官方示例当成一张真实排障图来读
仓库自带一份教科书级示例 cache-miss-request.sequence.json：7 个参与者横排开——User、Web App、API、Auth、Redis、Postgres、Trace，12 条消息，整条链被切成三幕。你跟着一次请求走一遍就能读完它。
第一幕：请求进来。 用户打开页面，Web App 向 API 发出 GET /dashboard；API 转头找 Auth 做 verify JWT，拿到 claims ok 后才继续往下走。这几条消息里，主请求用的是高亮样式，鉴权调用单独着色，一眼能分清哪条是正事、哪条是安全手续。
第二幕：缓存没查到。 API 向 Redis 发 read cache，回来的只有一个词：miss。这就是排障的关键帧——用户感知的延迟，从这里开始往上涨。
第三幕：回库并把结果带回。 API 向 Postgres 发 query profile + metrics，拿回 rows 后做两件事：虚线的 set cache 把结果写回 Redis，虚线的 emit trace 把埋点异步丢给 Trace，最后 200 JSON 回到前端、render 完成渲染。
消息的画法一共五类：emphasis 是主路径高亮，return 是安静的返回消息，security 是鉴权类调用，dashed 是异步非阻塞旁路，default 是普通消息。为什么 emit trace 要用虚线？因为它不在主路径上——异步埋点的开销和用户感知的延迟在视觉上被分开了，图上不会再让两条线混在一起抢注意力。
手写一份 IR：四个字段决定一张图
时序图源文件是一份带类型的 JSON IR（IR 即中间表示，可以理解为"给渲染器看的结构化描述"）。完整约束在 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", "y": 391, "variant": "return" }
后切幕——segments 用 y 像素区间把时间线切成易读的段落，官方示例切成 Request / Fallback / Response 三幕：
{ "from": 315, "to": 505, "label": "Fallback" }
最后标忙碌——activations 画激活条（activation bar，参与者忙碌时段的色条）。Postgres 只有一小段激活条，回源窗口很短这件事就不用手说了：
{ "participant": "db", "from": 438, "to": 496, "type": "database" }
还可以选填 meta.views 配最多 5 个命名章节，再开 meta.animation: "trace" 让箭头按调用顺序逐段点亮。关键心态：这四个字段是在描述你的业务本身，不是在套模板——换个系统，填进去的就是你系统里真实发生的消息。
从 JSON 到 HTML：校验先于渲染
Archify 的管线是确定性编译：JSON IR 先过 schema 校验，再做布局检查——参与者放不下、消息间距过密、箭头越界，都会直接报错拒绝出图，而不是画出一张坏图让你自己发现。渲染、校验、交付三条命令各管一段：
# 单文件渲染：内置校验器，无需装依赖，布局不合格直接报错
node archify/renderers/sequence/render-sequence.mjs cache-miss-request.sequence.json out.html
# 交付期终检：showcase 级别要求 0 错误 0 警告
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 out.html
deliver 这一步值得多看一眼：它把规格文件字节级冻结成快照再渲染，输出的 HTML 附带 SHA-256 回执。意思是——你转发给同事的那个 HTML 文件，和它背后那份 JSON 是严格对得上的，不会出现"图改了、源没同步"的扯皮。
🔍 打开 HTML 之后能干什么
渲染出来的不是静态图，而是一个可以探索的页面。官方成品在 渲染器 README 的示例里都能试到：
- 分章讲解：顶部章节按钮逐章聚焦相关参与者，
Play story自动播放整条调用链，箭头按顺序点亮。 - 路由追踪：选中 Web App 到 Postgres 的路径，面板显示节点数与有向跳数（如 "3 nodes · 2 directed hops"），可复制深链，或导出 1200×630 的路由分享卡片。
- 主题切换：右上角 Dark / Live 一键切换深浅色。
- 多格式导出：PNG 复制到剪贴板、下载静态图、带运动的 WebM、社交分享卡，都在 Export 菜单里。
换到你自己的系统：四步出图 + 交付前体检
把官方示例换成你自己系统的 API 链，照这四步做就行：
- 列出这条请求链的参与者（网关、鉴权、缓存、主库……），语义
type各归其位； - 按时间顺序写每条消息：主路径
emphasis、返回return、鉴权security、旁路埋点dashed； - 用 2~3 个 segment 切幕，给关键服务加激活条；
- 跑
validate→deliver，出图后做体检：
# 多分辨率视觉验收：1440×900 到 2048×1320 逐档确认不溢出
node bin/archify.mjs visual-check out.html --json
交付标准就两条：--quality showcase 下 0 错误 0 警告；visual-check 在 1440×900、1600×1000、1920×1080、2048×1320 多档桌面分辨率下全部不溢出。
一条 7 个参与者、12 条消息的调用链，不到 100 行 JSON 就能讲清楚；画得好看、画得正确这两件难事交给 Archify 兜底，你只需要把业务本身讲明白。
- 示例源文件：cache-miss-request.sequence.json
- 时序图 Schema：sequence.schema.json
- 渲染器文档：renderers/sequence README
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
