企业官网建设流程全解析

用Archify时序图跑通一次缓存缺失的API调用链：从零到交付的完整指南

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

Archify 是面向 AI Agent 的 Node.js 渲染与校验系统，能把代码库或系统描述编译成五种可验证的交互式图表，时序图是其一，输出自带动画与导出的自包含 HTML。本文以"缓存缺失请求"为主线：30 秒安装出图，拆解官方示例源文件，再交付一个可直接分享的 HTML，跟完即可复现。

30 秒装好并出第一张图 🚀

这节只做一件事：装好技能，让 Agent 画出第一张时序图。

npx skills add tt-a1i/archify -g

装好后在对话里对 Agent 说一句话即可：Use archify to trace this API request: Redis cache miss, fallback to Postgres.不想安装也可以先试一次：npx skills use tt-a1i/archify@archify --agent codex。

不确定该画哪种图时，问内置场景指南，它会推荐类型并返回配方：node archify/bin/archify.mjs guide "Show an API request with Redis cache miss" --json。注意：指南只负责指路，图仍要由你和 Agent 亲手描述。

它替你解决了什么痛点

• 排查"这次请求为什么慢"：架构图只画"谁和谁相连"，时序图画"谁在什么时候调用了谁"；激活条让你直接看到每一跳忙了多久。
• 手绘图容易画错还难发现：Archify 先过 Schema 与布局规则校验，参与者放不下、箭头过密当场报错，拒绝产出坏图。
• 画完图没法分享：成品是单文件自包含 HTML，内建 PNG / SVG / WebM 与 1200×630 分享卡导出，发出去就能打开。

走读官方示例：7 个参与者、12 条消息的调用链

这节带你读完仓库自带的那个教科书级示例。源文件是 cache-miss-request.sequence.json，渲染成品在 sequence-cache-miss-request.html，全文不到 100 行 JSON。

时间从上往下流动，7 个参与者横向排开，整条链被 3 个分段切成三幕：

留意紫色虚线的set cache和emit trace：它们不阻塞主路径，于是"用户感知的延迟"和"可观测性开销"在图上自然分开了。

拆开源文件：4 个核心字段与 Schema 对齐

这节对照示例逐块讲清撑起整张图的四个字段。字段名以 sequence.schema.json 为准，设计规则见 render-sequence 文档：

• participants：参与者列表，每项含id、语义type（frontend/backend/database/security等）、label、sublabel，示例共 7 个，如{"id":"redis","type":"database","label":"Redis","sublabel":"cache"}。
• messages：消息箭头，指定from/to、垂直坐标y和风格variant（default/emphasis/security/dashed/return五种），共 12 条；缓存缺失那条是{"from":"redis","to":"api","y":391,"label":"miss","variant":"return"}。
• segments：背景分段，from/to是 y 像素区间，就是图里 Request / Fallback / Response + trace 三幕，示例共 3 个。
• activations：激活条，标记某参与者的忙碌时段，如{"participant":"db","from":438,"to":496}——Postgres 只有这么一小段，回源窗口很短一眼可见。

想更精细地讲解，可在meta.views里配最多 5 个命名章节（示例配了 3 个），并开启meta.animation: "trace"让箭头按调用顺序逐段点亮。

从输入到交付：校验与渲染管线 🔍

这节给你从"写完 JSON"到"成品可发"的三条命令。

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

整个管线是"从语义到像素"的确定性编译：自然语言 / Mermaid → Agent 推断空间关系 → JSON IR + Schema 校验 → 类型化渲染器 + 布局规则检查 → 自包含 HTML + 多倍率导出。严格校验的价值一句话：宁可报错退出，也不产出坏图——showcase级别要求 0 错误 0 警告；而deliver会把源文件字节级冻结成快照再渲染，输出 HTML 附带 SHA-256 回执，你分享的那个文件和它背后的 JSON 是对得上的。

打开成品：不止是一张静态图

用浏览器打开交付的 HTML，这张时序图还是"活"的：

• 分章讲解：meta.views在顶部生成 3 个章节按钮，逐章聚焦相关参与者；点Play story可自动按调用顺序播放整条链。
• 路由追踪：选中 Web App 到 Postgres 的路径后，面板显示3 · 2 · shortest authored route（3 节点 · 2 跳 · 最短编写路径），可一键复制深链或导出 1200×630 的Route Share Card。

• 主题切换：右上角 Dark / Light 一键切换（快捷键T），当前视觉预设保持不变。
• 多格式导出：Export 菜单支持复制 PNG 到剪贴板、下载静态或带运动的 WebM、以及 1200×630 分享卡。

换成你自己的项目：4 步出图

把示例换成你自己的系统，只做四步：

1. 列出参与者的语义type（网关 / 缓存 / 主库）
2. 按时间顺序写消息，主路径标emphasis
3. 用 2~3 个segment切幕并补激活条
4. 跑validate→deliver，再做桌面分辨率检查

最后一步建议补一句：node archify/bin/archify.mjs visual-check out.html --json，它会在 1440×900 到 2048×1320 多档分辨率下确认成品不溢出。更多字段约定可查 authoring-cookbook.zh-CN.md。

附录：资源速查

一条缓存缺失的调用链，你只负责讲清"谁在什么时候调了谁"；布局、校验、导出这些容易翻车的事，交给管线兜底。

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