企业官网建设流程全解析

缓存 miss 的 12 步分解：Archify 时序图实操

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

Archify是面向 AI Agent 的图表技能，把系统描述转成五种可校验的交互图，时序图（sequence diagram）是其一。本文的产出物是一张还原缓存缺失场景的单文件可分发交互页面：7 个参与者、12 条消息、3 个阶段切分。读完后你能在自己的项目里跑通 validate 到 deliver 的完整链路。

先看成品：Cache Miss Request Sequence

时间从上往下流动，7 个参与者横排铺开：User、Web App、API、Auth、Redis、Postgres、Trace。12 条消息箭头贯穿整条 API 调用链，3 个背景分段（Request / Fallback / Response + trace）把时间线切成三个阶段。Postgres 列上的激活条不到一行高，回源窗口极短；set cache与emit trace两条紫色虚线是异步旁路。图例把消息风格分成五类：emphasis主路径、return返回、security鉴权、dashed异步、default其余。

这张图回答的问题只有一个：缓存缺失的那次请求，延迟花在哪一跳，可观测性写入是否拖累了主路径。

不画这张图，你会漏掉什么

• 日志只有首尾时间戳，300ms 花在哪一跳看不出来；
• 缓存命中还是缺失，从单条日志里很难判断；
• 异步埋点和主路径调用混在一起，阻塞代价的边界模糊。

archify/SKILL.md 的路由表把sequence分给 API 调用链、请求生命周期、异步追踪与返回流——正是"谁在什么时候调用了谁"这类问题。

两条命令跑起来

• 全局安装：npx skills add tt-a1i/archify -g，适配 Cursor、Claude Code、Codex CLI、OpenCode 四类 Agent 环境
• 不想安装，可先单次试用：npx skills use tt-a1i/archify@archify --agent codex
• 不确定该用哪种图，让内置指南推荐：node archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json --lang zh

cache-miss-request.sequence.json 里 4 个字段撑起整条链

源文件 81 行，骨架就是 4 块：

两个可选配置值得开：meta.views最多 5 个命名章节（本例配了 3 章：Request and identity、Cache fallback、Return and trace）；meta.animation: "trace"让箭头按调用顺序逐段点亮。完整字段约束在 archify/schemas/sequence.schema.json。

从语义到像素：5 步编译管线

1. 你用自然语言或 Mermaid 描述系统；
2. Agent 推断空间关系，落成带类型的Typed JSON IR；
3. 内置 Validator 按sequence.schema.json逐字段核对规格；
4. 类型化渲染器执行布局规则，消息间距小于 28px、箭头越界这类问题直接报错；
5. 输出单文件可分发的交互页面，支持动画与多倍率导出。

validate分两种用法：探索期在每次候选编辑后跑一遍，快速定位问题；交付期做终检，showcase级别要求 0 错误 0 警告。

deliver更彻底：把规格字节冻结成同目录快照，渲染并检查那份快照，全部门禁通过才原子替换目标 HTML，回执里附规格与产物各自的SHA-256和字节数。你发给同事的那个 HTML 能与仓库里的 JSON 字节级对上，回执就是证据。

第一条命令在仓库根目录执行，后两条在archify/目录下：

node archify/renderers/sequence/render-sequence.mjs cache-miss-request.sequence.json out.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 out.html # 原子交付

打开 HTML：这不是静态图

• 分章播放：顶部 3 个章节按钮逐章聚焦相关参与者，每章带独立说明；按下Play story，整条调用链自动播放，箭头按调用顺序点亮。
• 路由追踪：选中 Web App 到 Postgres 的路径，面板显示 "3 nodes · 2 directed hops · shortest authored route"，可一键复制深链，也能导出 1200×630 的路由分享卡。

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

换成你的系统：4 步出图

1. 列出这条请求链的参与者（网关、鉴权、缓存、主库），语义type各归其位。注意：参与者要按读者跟读故事的顺序横排。
2. 按时间顺序写消息，主路径emphasis、返回return、鉴权security、旁路埋点dashed。注意：消息垂直间距需 ≥28px，否则布局检查直接报错。
3. 用segments把时间线切成 2–3 段，给关键服务加激活条。注意：from/to是 y 像素坐标，不是参与者 id。
4. 跑validate→deliver，再验证桌面分辨率不溢出：node bin/archify.mjs visual-check out.html --json，覆盖 1440×900 到 2048×1320 四档视口。

字段约定详见 authoring-contract.md 与 authoring-cookbook.zh-CN.md。

路径速查

7 个参与者、12 条消息、81 行 JSON。Archify 只接住画得正确、交付可核验这两件难事，你只需要把业务讲清楚。

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