Archify生命周期图解实战：状态机、重试、等待与终态的画法

Archify生命周期图解实战：状态机、重试、等待与终态的画法

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

Archify 是一款开源 Agent Skill，能把 JSON 语义模型变成可交互、可导出的自包含 HTML 图表，其中**生命周期图（lifecycle diagram）**专门用来表达状态机：主流程阶段、重试回路、等待状态与终态出口。本文以项目自带的 Agent 运行示例为主线，手把手讲清状态机、重试、等待与终态的画法，最后用一条命令渲染出支持主题切换和 4 倍高清导出的 HTML。

🧭 为什么状态机需要专门的“生命周期图”

Archify 内置 5 类图：架构图、工作流、时序图、数据流图和生命周期图。按 authoring-cookbook.md 的划分，lifecycle 的定位是“States, retries, waits, and terminal outcomes”——状态、重试、等待与终态。

• 架构图回答“系统长什么样”
• 工作流图回答“事情按什么顺序做”
• 生命周期图回答“对象现在处于哪个状态、还能去哪儿”

一个 Agent 的“排队 → 规划 → 执行 → 审查 → 完成”，加上“需要审批”“失败重试”“已取消/超时”，就是一台典型状态机，正是 lifecycle 的主场。

🧱 搭好骨架：三条泳道 + 状态 + 迁移

lifecycle 输入就是一个 JSON 文件，四要素：lanes（泳道）、states（状态）、transitions（迁移）、cards（摘要卡片，可选）。

泳道（lanes）是理解整张图的钥匙：

"lanes": [ { "id": "main", "label": "Lifecycle phases" }, { "id": "waiting", "label": "Interruptions" }, { "id": "exceptions", "label": "Recovery loop" }, { "id": "terminal", "label": "Terminal exits" } ]

• main泳道必填，映射到顶部的阶段带，承载主生命周期轨道
• terminal泳道映射到底部的终态带
• 其余泳道共享中间事件带，放中断与恢复逻辑

状态（states）只需声明类型和位置：

{ "id": "executing", "type": "active", "label": "Executing", "sublabel": "tool calls", "lane": "main", "col": 2, "step": "03" }

迁移（transitions）只写from/to，其余交给自动路由。最小骨架长这样：

🎨 八种状态类型：选对类型，图就成功了一半

states[].type支持 8 种（定义见 lifecycle.schema.json），官方推荐用法：

图例（Legend）会从这些类型自动派生，不需要手工维护。

🔁 重试回路：让 Failed 回到 Executing

重试的关键是回环迁移不破坏主轨道。官方示例 agent-run.lifecycle.json 中，Failed在事件带，回指Executing时用variant: "emphasis"加粗，并用via显式绕出左侧通道：

{ "id": "failed-retry", "from": "failed", "to": "executing", "variant": "emphasis", "fromSide": "left", "toSide": "top", "via": [[20, 385], [20, 80], [402, 80]] }

设计规则要求避免斜线和交叉线，多段迁移会自动加圆角（cornerRadius可调）。

⏸️ 等待状态：暂停 ≠ 结束

“需要审批”“等待用户输入”这类状态放中间事件带，类型用waiting。要点：等待状态不指向终态带，运行只是暂停而非结束。例如Executing → Needs Approval用route: "straight"垂直落下，语义一目了然。

🏁 终态画法：垂直落下，绝不回头

终态（Cancelled、Expired、Failed耗尽重试预算等）统一放terminal泳道，设计规则很明确：终态出口尽量从来源状态垂直落下，且终态不再指回活跃执行。这样读图的人一眼就能分清“还能继续”和“到此为止”。

⚡ 一条命令渲染：自包含 HTML + 4x 高清导出

node archify/renderers/lifecycle/render-lifecycle.mjs input.lifecycle.json output.html

渲染器（render-lifecycle.mjs）零依赖，会先做 Schema 校验，再做布局体检：泳道缺失、状态重叠、标签碰撞、过短迁移、无关交叉都会直接报错——图错不过夜，渲染前先自检。加上"quality_profile": "showcase"可启用交付级严格检查，"animation": "trace"让箭头沿路径流动。打开生成的 HTML 还能一键导出 PNG / WebP / SVG / WebM，最高 4 倍分辨率。

📂 关键文件速查

小结：生命周期图的核心心法就四条——主流程走main轨道、重试回路显式绕道、等待状态不终结、终态垂直落下不回头。把状态机写进 JSON，Archify 负责校验、排版与导出，你只管讲清“对象的一生”。

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