企业官网建设流程全解析

Archify 实操：一张时序图讲清缓存缺失的 API 调用链

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

排查"这次请求为什么慢"时，日志给你的是碎片，而一张时序图给你的是因果。Archify 是一个面向 AI Agent 的图表技能，把代码库或一段系统描述编译成五种可验证的交互式图表——架构图、工作流图、时序图、数据流图、生命周期图，产物是一份带动画、可多倍率导出的自包含 HTML。下面用官方"缓存缺失请求"示例，把这条链路从写、到验、到讲给人看，完整走一遍。

排查一次变慢的请求，从一张能讲清楚的图开始

设想这个场景：用户打开仪表盘页面，接口比平时慢了 300ms。你要给同事讲清楚钱花在哪：请求经过几跳、鉴权花了多久、缓存是命中还是缺失、回源数据库的窗口有多短。口头讲容易丢细节，Mermaid 手画又常常画错、画丑，最后还得截图贴文档。

Archify 的思路是把"画图"拆成两半：语义由你和 Agent 描述，空间布局与美观交给渲染器兜底。你只写一份带类型的 JSON IR，渲染器按 schema 严格校验、做布局检查，参与者放不下或消息间距过密会直接报错，而不是给你一张坏图。对时序图（sequence）而言，它专门负责"谁在什么时候调用了谁"：主请求路径、返回、鉴权、异步旁路各占一种视觉风格，延迟与可观测性开销在图上自然分离。

Archify 是什么：五类图表，一份自包含 HTML

一句话定位：Archify 是"从语义到像素"的确定性编译管线——自然语言或 Mermaid 输入 → Agent 推断空间关系 → JSON IR + Schema 校验 → 类型化渲染器 + 布局规则检查 → 独立 HTML + 多倍率导出。

能力清单：

• 五种图表类型：architecture（谁和谁相连）、workflow（流程分支）、sequence（调用时序）、dataflow（数据流动）、lifecycle（状态机）
• 输出物：单一 HTML 文件，内嵌 SVG，深浅色主题，可选 trace 动画，导出 PNG/静态图/WebM/社交分享卡
• 质量门禁：validate 探索期校验、deliver 交付期终检，showcase 级别要求 0 错误 0 警告
• 适配环境：Node.js 渲染与校验系统，适配 Cursor、Claude Code、Codex CLI、OpenCode

安装 Archify 技能，装完先说这一句话

安装是一行命令：

npx skills add tt-a1i/archify -g

装完的第一句话可以直接这样说："Use archify to trace this API request with a cache miss." Agent 会按技能路由表选择sequence类型并产出 JSON 源文件。不想装、只想试一次，也可以用npx skills use tt-a1i/archify@archify --agent codex跑一回合。

拿不准该用哪种图时，问内置场景指南：node bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json --lang zh，它会推荐图表类型并返回配方。注意配方只是参考，图要由你亲手描述业务，而不是机械套模板。

读一张缓存缺失时序图：7 个参与者、3 个分段、12 条消息

仓库里有个教科书级示例，源文件在 archify/examples/cache-miss-request.sequence.json，渲染成品是 examples/sequence-cache-miss-request.html。时间从上往下流，7 个参与者横向排开：User → Web App → API → Auth → Redis → Postgres → Trace。

整条链被 3 个分段切成三幕：

图例把消息风格分成五类，每类在图上有明确的"戏份"：

• emphasis：主请求路径，用强调色，是视线第一落点；
• return：返回消息，安静克制，不抢正向调用的风头；
• security：鉴权类调用单独着色，一眼定位安全交互；
• dashed：异步/非阻塞（示例里set cache和emit trace两条紫色虚线），绝不压过主链；
• default：常规交互，无特殊语义时默认使用。

激活条（activations）表示参与者的忙碌时段：Postgres 只有一小段激活条，直观说明回源窗口很短；Auth 的激活条只覆盖鉴权窗口。这套约定写在 archify/renderers/sequence/README.md 里。

四步描述法：把一条 API 调用链写成 JSON

时序图源文件是一份带类型的 JSON IR，字段约束以 sequence.schema.json 为准。按四步写，每步都有最小示例可参照缓存缺失示例的对应块。

第 1 步：参与者。列出链路上每个角色，给id、语义type（frontend/backend/database/security 等）和标签：

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

第 2 步：消息。按时间顺序写每条箭头，指定from、to、垂直坐标y和风格variant：

{ "id": "cache-miss", "from": "redis", "to": "api", "label": "miss", "variant": "return" }

第 3 步：分段与激活条。用segments的from/to（y 像素区间）把时间线切成 2–3 幕，再给关键参与者加activations忙碌时段。

第 4 步：命名章节（可选）。在meta.views里配最多 5 个命名章节，每章声明focus参与者列表，用于成品里的分章讲解；再开"animation": "trace"让箭头按调用顺序逐段点亮。缓存缺失示例配了 3 章：Request and identity、Cache fallback、Return and trace。

写完就走管线。渲染器内置校验器，无需装依赖：

node archify/renderers/sequence/render-sequence.mjs cache-miss-request.sequence.json output.html

交付阶段两条命令收口：

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

deliver会把规格文件字节级冻结成快照再渲染，输出 HTML 附带 SHA-256 回执——你分享给同事的那一个文件，和它背后的 JSON 对得上。交付后再跑node bin/archify.mjs visual-check output.html --json，在 1440×900 到 2048×1320 多档桌面分辨率下确认不溢出。核心原则始终是：布局有问题就报错，绝不画出一张坏图。更多字段约定见 archify/references/authoring-contract.md 与中文 authoring-cookbook。

打开成品 HTML：分章播放、路由追踪与换你自己的项目

用浏览器打开渲染好的 HTML，它不是一张静态图：

• 分章讲解（Guided views）：顶部 3 个章节按钮逐章聚焦相关参与者，Play story自动按调用顺序点亮整条链；
• 路由追踪（Route probe）：选中 Web App 到 Postgres 的路径，面板显示"3 nodes · 2 directed hops · shortest authored route"，可复制深链或导出 1200×630 的路由分享卡片：

• 主题与导出：右上角切换 Deep 深浅色；Export 菜单支持复制 PNG 到剪贴板、下载静态图、WebM 运动格式和社交分享卡。

现在把示例换成你自己的系统，落地清单就四步：

1. 列出这条请求链的参与者（网关、鉴权、缓存、主库……），语义type各归其位；
2. 按时间顺序写消息，主路径用emphasis，返回用return，鉴权用security，旁路埋点用dashed；
3. 用 2–3 个 segment 切分时间线，给关键服务加激活条；
4. 跑 validate → deliver → visual-check，多档分辨率确认不溢出。

7 个参与者、3 个分段、不到 100 行 JSON，一条完整的 API 调用链就讲完了。画得好看、画得正确这两件难事由 Archify 兜底，你只需要讲清楚业务本身。

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