如何用 Archify 时序图完整追踪缓存缺失的 API 调用链

如何用 Archify 时序图完整追踪缓存缺失的 API 调用链

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

为什么这次请求慢了 300 毫秒？答案通常藏在调用链里：请求穿过 API 后，缓存恰好缺失，被迫回源数据库多跑一趟。本文用Archify 时序图走通缓存缺失场景的完整 API 调用链：从一行命令安装，到描述、校验、交付出一张自包含 HTML 成品。Archify 是一个面向 AI Agent 的图表技能（Skill），其sequence类型在技能路由表中明确对应 API call chains、request lifecycles 与 async traces。

一行命令安装，渲染出第一张成品

先装技能，再渲染仓库自带的教科书示例，两步就有可分享的 HTML：

npx skills add tt-a1i/archify -g node archify/renderers/sequence/render-sequence.mjs archify/examples/cache-miss-request.sequence.json output.html

不想装也可以先试一次：npx skills use tt-a1i/archify@archify --agent codex。拿不准该用哪种图时，问内置场景指南，它会推荐类型并返回配方：

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

渲染这一步并非"照单全画"。渲染器会先按 sequence.schema.json 做 schema 校验（schema 即定义 JSON 字段结构的约束文件），再跑布局检查——参与者排不下、消息间距过密、箭头越界，都会直接非零退出，而不是给你一张坏图。

读懂 7 个参与者、12 条消息、3 个分段

这张图的时间从上往下流动，7 个参与者横向排开：User → Web App → API → Auth → Redis → Postgres → Trace。整条链被 3 个分段（segments，背景色块）切成易读的三幕：

视觉语言的核心是 5 种消息风格（messages[].variant），由时序渲染器设计规则约定，图例会自动按它们生成：

另外 6 条激活条（activations，表示参与者忙碌时段的竖条）里，Postgres 只占了一小段——回源窗口很短，一眼可见。两条紫色虚线则把"用户感知的延迟"和"可观测性开销"在图上自然分开。

把业务写进图里：4 个核心字段

时序图源文件是一份带类型的 JSON IR（IR 即中间表示，渲染器消费的结构化规格）。缓存缺失示例的骨架由 4 块组成，其余都是可选增强：

• participants：每项含id、语义type（external、frontend、backend、database、security、messagebus、cloud共 7 种）和标签，如{ "id": "redis", "type": "database", "label": "Redis" }；
• messages：箭头指定from、to、垂直坐标y和风格，缓存缺失就是{ "from": "redis", "to": "api", "y": 391, "label": "miss", "variant": "return" }；
• segments：y 像素区间，如{ "from": 315, "to": 505, "label": "Fallback" }，用来划分三幕；
• activations：参与者的忙碌时段，如{ "participant": "db", "from": 438, "to": 496 }。

想要分章讲解，在meta.views配最多 5 个命名章节（示例配了 3 章），再开meta.animation: "trace"让箭头按调用顺序逐段点亮。

用 validate、deliver、visual-check 三道关卡确认图是对的

校验分三步，各自兜住一类质量问题，命令都在安装后的技能包内跑：

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 output.html --quality showcase node bin/archify.mjs visual-check output.html --json

• validate管"结构和几何对不对"：schema 违规与布局问题（消息垂直间距不足 28px、箭头跨距小于 60px、参与者超出 viewBox 等）都会以带元素定位的诊断信息报错，showcase质量档要求 9 项 artifact 检查全部 0 错误 0 警告；
• deliver管"交付物可追溯"：它把规格文件字节级冻结成快照再渲染，输出的 HTML 附带 SHA-256 回执——你分享给同事的那一个文件，和它背后的 JSON 是对得上的；
• visual-check管"在大屏上溢不溢出"：在 1440×900、1600×1000、1920×1080、2048×1320 四档桌面分辨率下测量 containment，并抓浅/深色截图生成对照表，命令本身从不改动已交付的 HTML。

🎬 打开 HTML：分章播放、路由追踪与多格式导出

成品不是一张静态图，而是一个自带查看器的独立页面。用浏览器打开渲染好的 HTML，你可以：

• 分章讲解：顶部 3 个章节按钮（Request and identity / Cache fallback / Return and trace）逐章聚焦相关参与者，Play story自动播放整条调用链；
• 路由追踪：点选 Web App 到 Postgres 的路径，面板给出最短路径的节点数与有向跳数，可一键复制深链或导出 1200×630 分享卡；
• 主题与导出：右上角切换 Deep/Live 深浅色，Export 菜单支持 PNG 复制到剪贴板、静态图下载、WebM 动效和社交分享卡。

换成你自己系统：4 步模板

把主线场景换成你项目的请求链，照抄这四步即可：

1. 列出这条链的参与者（网关、鉴权、缓存、主库……），语义type各归其位，主路径节点不超过 12 个；
2. 按时间顺序写消息，主路径用emphasis、返回用return、鉴权用security、旁路埋点用dashed，标签短而保留方向与行为；
3. 用 2–3 个segments切时间线，给关键服务加activations激活条；
4. 依次跑validate→deliver→visual-check，交付后不再改规格文件——交付即冻结，改动意味着重新走完整条校验链。

更多字段约定见 authoring-contract.md 与中文 cookbook。

资源速查

一条缓存缺失的调用链，7 个参与者、12 条消息、3 个分段，不到 100 行 JSON 就表达得清楚。你负责把业务讲明白，"画得对"这件事，交给三道校验关卡去兜底。

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