Archify Lifecycle Renderer 完全指南用 JSON 构建可验证的阶段生命周期图【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archifyArchify 的 Lifecycle Renderer 是一种将diagram_type: lifecycle的 JSON 描述文件渲染成自包含 HTML 图表的专用渲染器专为表达阶段、事件与终态并存的生命周期而设计——例如 Agent 任务运行的生命周期、部署发布流程、订单履约链路等。读完本文你将掌握生命周期 JSON 的完整编写语法lane/state/transition 语义、布局预算与路由预设的使用方法并能利用渲染器内置的零依赖校验与质量门禁standard/showcase 双档产出可验证、可交付的高质量 SVG/HTML 图表。一、快速开始渲染一个生命周期图Lifecycle Renderer 的入口是 render-lifecycle.mjs它是一个零依赖安装的 Node.js 命令行渲染器用法如下node archify/renderers/lifecycle/render-lifecycle.mjs input.lifecycle.json output.html其输入为遵循 lifecycle.schema.json 的 JSON 文件输出为套用标准 Archify HTML 模板的独立 HTML 文件。渲染器使用仓库内置的 standalone 校验器进行 Schema 校验无需安装任何 npm 依赖。output.html是可省略的省略时渲染器会按以下优先级决定输出路径对应 cli.mjs 中的resolveOutputPath逻辑命令行第二个参数显式输出路径JSON 中meta.output字段兜底为当前工作目录下的lifecycle.html。如果你想直接看到效果仓库已内置一个完整可运行的示例直接执行node archify/renderers/lifecycle/render-lifecycle.mjs archify/examples/agent-run.lifecycle.json即可按示例 JSON 中的meta.outputexamples/lifecycle-agent-run.html生成渲染结果。渲染器入口的默认示例正是agent-run.lifecycle.json见 render-lifecycle.mjs。二、输入结构Lifecycle JSON 的顶层骨架一份合法的 Lifecycle JSON 必须包含以下顶层字段最小骨架如下摘自 README{ schema_version: 1, diagram_type: lifecycle, meta: { title: Agent Run Lifecycle, viewBox: [980, 660] }, lanes: [], states: [], transitions: [], cards: [] }依据 lifecycle.schema.json各字段的约束为字段必填约束schema_version是固定为1constdiagram_type是固定为lifecycleconstmeta是至少包含非空titlelanes是数组长度 14每项必填id与labelstates是数组至少 2 项transitions是数组每项至少包含from与tocards否摘要卡片数组见下文整个 Schema 采用additionalProperties: false严格模式任何未声明字段都会被直接判为非法。2.1 语义化且保留的 Lane ID生命周期图的三个横向带band完全由 lane 的 id 决定这是整个布局体系的核心约定源码实现在 render-lifecycle.mjs 的bandFor()main必填映射到顶部阶段带Phase band承载主生命周期横轨terminal映射到底部结果带Outcome band承载终态退出其他任意 id最多 4 条 lane 总数内所有非main/terminal的 lane共享同一个中部事件带Event band彼此之间通过yOffset在视觉上错开。三条带的标题文字直接取自你的 lane label见bandTitles()与renderBands()中部事件带会把所有事件 lane 的 label 用拼接例如Interruptions Recovery loop。2.2 完整实战示例Agent Run Lifecycle仓库中的 agent-run.lifecycle.json 是文档明确指出的完整工作示例它演示了主阶段带 事件带 终态带的全部语义{ schema_version: 1, diagram_type: lifecycle, meta: { title: Agent Run Lifecycle, output: examples/lifecycle-agent-run.html, viewBox: [980, 660], animation: trace, quality_profile: showcase, views: [ { id: main-lifecycle, label: Main lifecycle, focus: [queued, planning, executing, reviewing, completed], note: Follow the ordered phases from accepted request to completed response. }, { id: human-waits, label: Human and input waits, focus: [executing, approval, reviewing, blocked], note: See where the run pauses without becoming terminal. }, { id: recovery-and-exits, label: Recovery and terminal exits, focus: [executing, failed, blocked, cancelled, expired], note: Separate retryable failure from cancellation and expiry. } ] }, lanes: [ { id: main, label: Lifecycle phases }, { id: waiting, label: Interruptions }, { id: exceptions, label: Recovery loop }, { id: terminal, label: Terminal exits } ], states: [ { id: queued, type: start, label: Queued, sublabel: request accepted, lane: main, col: 0, step: 01, tag: entry }, { id: planning, type: active, label: Planning, sublabel: build task graph, lane: main, col: 1, step: 02, tag: model }, { id: executing, type: active, label: Executing, sublabel: tool calls, lane: main, col: 2, step: 03, tag: work }, { id: reviewing, type: decision, label: Reviewing, sublabel: quality gate, lane: main, col: 3, step: 04, tag: check }, { id: completed, type: success, label: Completed, sublabel: final response, lane: main, col: 4, step: 05, tag: done }, { id: approval, type: waiting, label: Needs Approval, sublabel: human gate, lane: waiting, col: 0, tag: pause }, { id: blocked, type: waiting, label: Blocked, sublabel: missing input, lane: waiting, col: 1, tag: wait }, { id: failed, type: failure, label: Failed, sublabel: recoverable error, lane: exceptions, col: 0, yOffset: 78, tag: retryable }, { id: cancelled, type: failure, label: Cancelled, sublabel: user stopped, lane: terminal, col: 0, tag: terminal }, { id: expired, type: failure, label: Expired, sublabel: timeout, lane: terminal, col: 1, tag: terminal } ], transitions: [ { id: approval-needed, from: executing, to: approval, variant: security, fromSide: bottom, toSide: top, route: straight }, { id: review-blocked, from: reviewing, to: blocked, variant: default, route: drop }, { id: execution-failed, from: executing, to: failed, variant: security, fromSide: left, toSide: left, via: [[320, 157], [320, 385]] }, { id: failed-retry, from: failed, to: executing, variant: emphasis, fromSide: left, toSide: top, via: [[20, 385], [20, 80], [402, 80]] }, { id: block-expired, from: blocked, to: expired, variant: security, fromSide: bottom, toSide: top, route: straight }, { id: approval-cancelled, from: approval, to: cancelled, variant: security, fromSide: bottom, toSide: top, via: [[480, 336], [480, 432], [402, 432]] } ], cards: [ { dot: emerald, title: Main Path, items: [The run has five ordered phases from queue to completion, The primary lifecycle is carried by one horizontal rail, Completion is a phase, not a detached side box] }, { dot: amber, title: Human Input Gates, items: [Approval pauses execution without ending the run, Blocked waits for missing user input, Wait states remain non-terminal until cancellation or expiry] }, { dot: rose, title: Terminal Recovery, items: [Failed loops back while retry budget remains, Cancelled and Expired are exits from the lifecycle, Terminal exits do not point back into active execution] } ] }这个示例同时体现了meta.views引导视图最多 5 个每个含focus语义 id 列表、animation: trace轨迹动画、quality_profile: showcase与cards摘要卡片等高级特性。仓库还在 test/fixtures/v1-baseline/agent-run.lifecycle.json 提供了一份不依赖任何高级特性的 v1 基线版本用于兼容性回归验证。三、State 与 Transition 字段详解3.1 State 字段依据 lifecycle.schema.json每个 state 必填id、type、label、lane、col可选字段如下字段类型/约束说明type枚举start/active/waiting/decision/success/failure/neutral/external决定配色、图例项与语义标记见typeClass/textClass映射render-lifecycle.mjssublabel字符串主标签下方的次要说明随详情层detail展示tag字符串状态右下角的角标文本如entry、pausestep字符串有序阶段序号如01、02渲染在状态左上角brand字符串或{url, sha256}对象品牌标记brand mark见共享品牌协议col整数 04列号对应所在带的列中心表见下文布局预算width/height数字分别 ≥48 / ≥36覆盖该带默认状态尺寸yOffset数字纵向偏移用于在同一事件带内错开不同 lane 的状态3.2 Transition 字段每个 transition 必填from、to均引用 state id可选字段字段说明id可选但推荐一旦提供即成为查看器链接的持久身份且全局唯一见 cli.mjs 的validateRelationshipIdslabel/note连线标签与附注variant枚举default/emphasis/security/dashed决定线型与箭头样式route路由预设auto默认、straight、drop、bottom-channel、top-channel、right-channel、left-channelfromSide/toSide端点出口/入口方向left/right/top/bottomchannelX/channelY手动指定通道坐标覆盖路由预设的默认通道位置cornerRadius多段连线圆角半径默认 100为直角折线via显式途经点数组每点为[x, y]作者指定的点具有最高优先级width线宽≥0.5labelAt/labelDx/labelDy/labelSegment标签位置微调绝对点位、dx/dy 偏移、所在线段索引3.3 meta 共享字段meta还支持来自 common.schema.json 的共享定义localeen或zh-CN渲染器内部文本与无障碍文案据此本地化见 i18n.mjsanimationtrace轨迹动画或nonevisual_presetclassic/signal-flow/blueprint/editorialquality_profilestandard默认或showcaseviews引导视图最多 5 个legend图例覆盖配置viewBox[宽度, 高度]数组宽度 ≥420、高度 ≥566Schema 最小值默认[980, 660]。四、布局预算三带坐标系Lifecycle 渲染器采用固定化的三带布局坐标在 render-lifecycle.mjs 中定义为常量。README 给出了完整的布局预算表带Lane idTop y列中心默认状态尺寸阶段带 Phasemain必填126col0–4 → x 94, 248, 402, 556, 710118×62事件带 Event其他任意 id278col0–2 → x 402, 556, 710126×58结果带 Outcometerminal450col0–2 → x 402, 556, 710118×58关键设计事件带与结果带的列是相对主阶段轨有意偏移的——下带col: N与主带col: N 2使用相同的 x 坐标。也就是说下带第 0、1、2 列分别对齐在主带第 2、3、4 列的正下方。这种对齐让中断/终态天然落在主流程后半段的下方视觉上形成稳定的竖直出口通道。4.1 布局常量汇总常量值viewBox默认[980, 660]Schema 最小[420, 566]状态水平边界x 落在[32, width − 32]内状态底部不得低于height − 122状态间距任意两个状态之间 ≥10px——跨 lane 检查因为所有事件 lane 共享同一条带同带内靠col或yOffset分开连线长度端点间距 ≥32px图例行基线最终基线 y height − 36额外测量的图例行向上回绕主生命周期轨primary lifecycle rail沿阶段带运行并延伸到最右侧被占用的阶段列见renderLifecycleRail()轨线从x154起以 2.2px 强调线 箭头收尾。4.2 路由预设过渡连线的路径完全由route预设 通道坐标 via途经点决定源码实现在routeVia()render-lifecycle.mjs预设行为straight直线无中间点drop在channelY处折弯默认取起终点纵向中点bottom-channel在channelY处水平折弯默认max(两状态底边) 34top-channel在channelY处水平折弯默认min(两状态顶边) − 28right-channel在channelX处竖直折弯默认max(两状态右边) 36left-channel在channelX处竖直折弯默认min(两状态左边) − 36via显式途经点完全由作者指定最高优先级auto默认按端点出/入方向自动推断单弯或双弯多段连线会统一做圆角处理cornerRadius默认 10设为0得到锐利直角折线。自动路由的端点还会经过automaticPortSpread自动端口分散处理同侧多条连线会自动在状态边上分散锚点避免端口重叠见 render-lifecycle.mjs。五、图例Legend生命周期图例默认从states[].type推导需要展示的种类。meta.legend.entries支持按稳定顺序覆盖以下 keystart、active、waiting、decision、success、failure、neutral、external该稳定顺序同时被渲染器的LEGEND_CATALOG固化见 render-lifecycle.mjs。共享图例契约legend.mjs支持三种模式与逐项覆盖legend: { mode: auto, entries: { success: { label: 完成, visible: true }, failure: { label: 失败/终态, visible: true }, neutral: { visible: false } } }modeauto只展示图中出现的种类、all展示全部、hidden不渲染图例每项可覆盖label与visible只有被图中实际渲染状态支撑的种类才会获得 Semantic Legend 交互控件interactive标记取决于该 kind 是否 present见resolveLegend()。图例的布局由共享measureLegend()统一计算自动换行、多行向上回绕、行数超限时在unfit: error作者显式声明图例时与unfit: hide未声明时之间选择失败或隐藏行为。六、设计规则把生命周期画成阶段地图README 明确给出了一套创作纪律这是 Lifecycle 类型区别于普通状态机图的核心哲学把生命周期图当作阶段地图phase map而不是密集的状态转移图——不要试图塞进所有状态细节用mainlane 把主生命周期放在一条水平轨上用step标签标记有序阶段如01、02、03下带只用于中断、恢复与终态退出除非必要不要把连线标签放进主 SVG——优先使用节点标签、tag、图例项与摘要卡片传达信息避免斜线与交叉线终态退出应尽可能从源事件竖直下坠语义选型约定success表示完成、failure表示失败/终态退出、waiting表示暂停、decision表示质量门禁。七、校验与质量门禁渲染失败即交付失败Lifecycle Renderer 的校验分两层执行全部在写文件之前完成validateLifecycle()在 render-lifecycle.mjs 中定义出错时通过throwDiagnosticProblems以非零退出码结束。7.1 Schema 层违反 Schema 的输入会以带路径前缀path-prefixed的错误消息退出消息会标注到具体元素的 id 或 label方便快速定位。7.2 布局层可检测即失败渲染器在 Schema 之外还做了大量几何级检测任一失败都会阻止输出缺少mainlane、重复的 state id、未知 lane、未知连线端点状态超出生命周期区域水平越界或越过height − 122下边界状态重叠含跨 lane、标签与状态或其他标签碰撞、标签宽于所属状态、过短到不可读的连线连线穿越无关状态2px Clean Flow 净空生命周期带是有意的直通容器pass-through containers不作为障碍物参与路由文本宽度采用CJK 感知估算全角字形按 2 个单位计宽textUnits中文标签不会出现宽度误判。7.3 quality_profilestandard 与 showcase 双档设置meta.quality_profile: showcase可获得更严苛的交付级校验检测项standard默认showcase无关连线 proper X 交叉作为 artifact-receipt 警告失败报composition/proper-crossing无关连线重叠 ≥8px共线走廊警告失败任意路由段 8px容忍失败内部拐弯段 16px容忍失败8–15px 的普通端点短桩有效仍有效最后的产品检查还会抽样验证圆角Q命令是否存在保证圆角真正落到 SVG 输出中。另外作者显式指定的via途经点在 v1 Schema 中是权威性的即使处于 showcase 档也会被原样渲染而不做端点侧门禁的二次篡改只有自动路由才应用端点侧门禁见 render-lifecycle.mjs 的注释与shouldCheckRelation。八、渲染流水线与产物渲染器的执行流程renderSvg()render-lifecycle.mjs依次组装背景网格url(#grid)填充三条生命周期带renderBands()绘制 112/264/436 处的虚线段stroke-dasharray3,8与带标题标题带01 /、02 /、03 /前缀主生命周期轨renderLifecycleRail()连线路径renderTransitionPath()输出带data-composition-points供后续几何审计的 path并按variant选择箭头 marker状态节点renderState()输出带data-node-*语义属性、可聚焦tabindex0的节点组按animateAttr附加--step动画步进连线标签renderTransitionLabel()图例renderLegend()。最后writeDiagram()cli.mjs把 SVG 与摘要卡片填充进 assets/template.html写入独立 HTML 文件——该产物自带查看器交互节点聚焦、引导视图、语义图例、动画可离线打开。此外产物还会附带仓库证据repository evidence数据verifyRepositoryEvidence让图表可被追溯。九、进阶动画、引导视图与摘要卡片9.1 动画meta.animation: trace会为节点与连线附加data-animate与--step步进样式实现按拓扑顺序的轨迹动画步进数上限 12见animateAttr以保证在固定时长的 WebM 捕获窗口内完成。9.2 引导视图Guided Viewsmeta.views数组最多 5 项把复杂生命周期拆成可讲解的焦点视图每项含id、label、focus语义 id 列表与可选note。共享校验validateGuidedViews会强制focus引用的 id 必须真实存在且无重复避免出现视图指向不存在的状态。9.3 摘要卡片Cardscards数组把核心结论沉淀为图下方的摘要卡点色可选cyan/emerald/violet/amber/rose/orange/slate适合用三张卡片分别总结主路径 / 人工与输入门禁 / 终态与恢复。十、把 Lifecycle 渲染器接入你的流程Lifecycle Renderer 可以被任何语言/脚本以子进程方式调用传入 JSON 路径读取 stdout 的输出路径检查退出码即可判断校验是否通过。批量渲染场景可以参考 render-examples.mjs 中[lifecycle, agent-run.lifecycle.json, lifecycle-agent-run.html]的注册方式把 lifecycle 渲染纳入统一渲染管线。若希望以当前仓库为证据根目录做仓库证据注入可通过ARCHIFY_REPO_ROOT环境变量指定。适用场景总结Agent 任务运行生命周期、CI/CD 流水线阶段与恢复、部署发布流程、人工审批门禁、任何有序阶段 中断/恢复 终态并存的过程建模。记住一句话主流程上横轨中断与终态下坠质量门禁用decision交付前记得打开showcase。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
