企业官网建设流程全解析

Archify 视觉进化第 36 轮：在语义确定性边界内构建可检查的 Route Journey 路径漫游

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

导读

本文基于 docs/research-visual-evolution-round-36.md 研究纪要，完整还原 Archify 第 36 轮视觉进化研究的背景、四份一手资料的可迁移结论、Borrow/Adapt/Skip 决策矩阵，以及最终落地的Route Journey（路由路径漫游）产品决策。你将看到 Archify 如何在"不新增任何 schema、依赖、布局引擎或编辑面"的前提下，把路线探针（Route Probe）升级为一个有明确状态机、精确边所有权、有限调度器、可暂停可恢复、且完全符合 WCAG 2.2 与prefers-reduced-motion的阅读器级动效层。文末给出仓库源码与契约测试的一一印证，方便你直接深入archify/assets/template.html与archify/test/route-journey.test.mjs验证每一条设计承诺。

一、研究的核心问题：在不打破最强边界的前提下借用"丰富动效"

Archify 的产品形态与大多数图表工具不同：它的交付物是单个自包含、可离线检查、确定性生成的 HTML 工件，内容完全由作者定义的语义（architecture / workflow / sequence / dataflow / lifecycle 五种模式的 JSON）编译而来，参见 renderers/shared/cli.mjs 中的loadDiagram：JSON 输入 →validateSchema校验 → 模板填充 →writeDiagram输出独立 HTML。

第 36 轮研究提出的问题是：

How can Archify borrow the appeal of richer animated diagram products without weakening its strongest boundary: one offline, inspectable, deterministic HTML artifact built from authored semantics?

换句话说：如何借用"更丰富动画图表产品"的吸引力，却不削弱自身最强的边界——由作者语义构建的、单个离线、可检查、确定性的 HTML 工件？

研究结论非常明确：值得借鉴的不是"更多会动的像素"，而是"动效与视觉多样性只有在拥有可执行契约和可见的验证回执时才值得信赖"。这一判断直接决定了后面 Borrow/Adapt/Skip 决策的方向。

二、四份一手资料：可迁移教训的原始依据

2.1 fireworks-tech-graph：动效可信度的来源是"契约 + 回执"

该仓库（研究快照日期 2026-07-19）是一个面向 Codex / Claude Code 的 Agent Skill，走"自然语言 → 语义 JSON → 确定性 SVG → 校验 → 可选 PNG/HTML/GIF"流水线。详细调研见 docs/research-fireworks-tech-graph.md。

Round 36 提炼出的四条可迁移结论：

• 动效是聚焦且语义化的，不是无约束的环境装饰；
• 每种视觉风格保留独立的场景，但共享几何、文本适配、布线和动效门控；
• 确定性检查先于感知回读；
• 迭代循环是有界的，当回读不可用时不会声称完成了视觉验证。

对 Archify 而言，最大的教训是：动效与视觉多样性变得可信，是因为每个都配有可执行契约和可见的验证回执——而非仅仅增加更多动画像素。

2.2 Cytoscape.js 动画 API：一个"小的所有权模型"

Cytoscape 的图动画 API 把有序动画、视口取景、暂停/停止、进度四件事明确分离：排队动画按顺序执行；暂停保留当前进度；停止把任务从队列移除；视口 fit/center 是显式的动画目标。

这为 Archify 强化了一个小型所有权模型：

• 一个有限的路径调度器（one finite route scheduler）；
• 一个精确的当前位置（one exact current position）；
• 一个相机请求（one camera request）；
• 手动导航时的立即取消（immediate cancellation on manual navigation）。

2.3 W3C WCAG 2.2 — Pause, Stop, Hide：播放的触发与恢复规则

WCAG 2.2 区分了"有意激活"与"因偶然聚焦、悬停或滚动而开始的运动"，并明确指出：对于非实时的说明性内容，从同一点暂停并恢复是正确的行为。

由此推导出的硬性要求：

• 路径回放只能从原生 Play 按钮启动；
• 在聚焦/手动导航时暂停；
• 恢复时续上剩余停留时间（dwell），而不是跳到前面。

2.4 MDN — prefers-reduced-motion：大范围平移缩放的触发警示

prefers-reduced-motion是广泛可用的"减少/移除/替换非必要动画"信号，其中大范围平移（panning）与缩放（scaling）是前庭系统（vestibular）触发风险的重点对象。因此 Archify 在减少动效模式下：

• 保留可手动检查的路径位置；
• 禁用自动播放旅程；
• 相机取景改用瞬时定位（instant framing）。

三、Borrow / Adapt / Skip 决策矩阵

这是整轮研究的决策中枢，逐条对应"借什么 / 怎么适配 / 明确跳过什么"：

四、Round 36 产品决策：把 Route Journey 建成 Route Probe 之上的可检查层

最终决策是构建Route Journey 作为 Route Probe 之上的可检查层，共 9 条，与源码逐条对应：

1. 保留完整最短作者路径作为上下文——showResult中activeNodeIds = result.nodes.slice()、activeEdges = result.edges.slice()（template.html），全路径节点与边打上data-route-match/data-route-step。
2. 把路径片（chips）变成原生按钮，单一 roving Tab 停靠点——renderPath(ids, { interactive: true })用document.createElement(options.interactive === true ? 'button' : 'span')生成按钮；tabindex按index === 0 ? '0' : '-1'设置（template.html），键盘支持ArrowLeft/ArrowRight/Home/End/Enter/Space（template.html）。
3. 阅读器可在 Still 或 Live 模式下手动检查任意位置——selectJourneyIndex(index)调用applyJourneyState，可随时定位任意步骤（template.html）。
4. Play 是显式、有限、可暂停、可从剩余停留时间恢复的——JOURNEY_DWELL_MS = 1100；scheduleJourney用Math.max(0, JOURNEY_DWELL_MS - journeyElapsedMs)计算剩余时间；每次调度journeyGeneration += 1作代际守卫（template.html）；注意实现刻意不用setInterval，而是递归setTimeout（契约测试对此有doesNotMatch断言）。
5. 位置i > 0精确拥有activeEdges[i - 1]；位置 0 不拥有任何入边——applyJourneyState中destination === journeyIndex ? 'current' : 'future'，journeyIndex > 0时才renderJourneyPulse(activeEdges[journeyIndex - 1])（template.html）。
6. 由现有 Semantic Camera 取景"前/当前/后"切片——Archify.view.reveal(activeNodeIds.slice(journeyIndex-1, journeyIndex+2), { maxScale: 1.65, padding: 64, duration: 360, instant: !journeyMotionAllowed() })（template.html）；相机契约见 test/semantic-camera.test.mjs。
7. 分层 Escape：暂停 → 总览 → 清除路线——escapeRoute依次返回'paused'/'overview'/'cleared'（template.html）。
8. #route=<source>~<target>仅保留端点，恢复时进入总览且不自动播放——syncFromHash只解析两个端点，choose(parts[1], { updateUrl: false })后showResult内showJourneyOverview({ reveal: false })，URL 从不携带 journey 状态（template.html、L13551-L13554）。
9. 从打印、嵌入与导出 SVG 中剥离所有临时旅程状态——beforeprint暂停旅程；导出时移除data-route-journey、data-route-journey-state、data-route-journey-current及[data-route-journey-overlay]叠加层（template.html）。

五、源码级原理：Route Journey 的四个核心机制

5.1 语义化的有界动效：一个位置 = 一条精确入边

Route Journey 的动效对象是作者语义中真实存在的一条边。renderJourneyPulse克隆该边的path/line/polyline几何，去掉 id/class/style/箭头/数据属性，赋予class="route-journey-flow"与pathLength="1"，插入到第一个节点之前（template.html）。@keyframes archify-route-journey-flow以 780mscubic-bezier(0.22, 1, 0.36, 1)运行一次both填充模式。注意它从不通过querySelector按data-edge-from重新查找边——边对象来自 BFS 求出的activeEdges数组，契约测试专门用doesNotMatch断言杜绝了这种"自找边"的实现（test/route-journey.test.mjs）。

动效还受Motion Governor管控：Archify.motionGovernor.claim('route', …)获取所有权 token，journeyMotionAllowed()校验嵌入模式、文档可见性、能力与暂停状态，任何一方不满足即不播放（template.html）。

5.2 有限调度器：代际守卫 + 剩余停留时间

var remaining = Math.max(0, JOURNEY_DWELL_MS - journeyElapsedMs); journeyStartedAt = Date.now(); journeyTimer = window.setTimeout(function () { if (generation !== journeyGeneration || !journeyPlaying) return; // 代际守卫 ... applyJourneyState(journeyIndex + 1, { pulse: true, reveal: true }); journeyElapsedMs = 0; journeyStartedAt = 0; scheduleJourney(); // 递归调度，而非 setInterval }, remaining);

stopJourneyTimer({ preserveElapsed: true })在暂停时把已流逝时间累积进journeyElapsedMs（上限 1100ms），因此从同一位置、同一剩余停留恢复播放，符合 WCAG 2.2 对说明性内容的要求（template.html）。

5.3 分层 Escape 与手动导航优先

escapeRoute三态：播放中 → 暂停（'paused'）；已在某位置 → 回总览（'overview'）；否则清除路线（'cleared'）。任何手动交互（路径片点击/聚焦、focusin、beforeprint、系统动效暂停、文档隐藏）都会调用pauseJourney({ preserveElapsed: true, reason: … })，相机在instant: !journeyMotionAllowed()下做瞬时取景，让"手动检查"始终可用（template.html、L11537-L11539）。

5.4 状态只属于查看器：导出与打印剥离

独立导出与打印路径把data-route-journey与所有旅程状态属性移除，canonicalStateClean校验保证导出的 SVG 是纯净的作者语义，旅程只是叠加在查看器里的一层（template.html、L5869、L5898）。这就是第 9 条决策"Journey overlays and state remain viewer-only"的直接实现。

六、成功证据：契约测试如何验证每一条承诺

archify/test/route-journey.test.mjs 用node:test对五种渲染器逐一断言：

1. 五渲染器继承同一套控件与状态机：route-journey-controls面板、prev/play/next/overview按钮的aria-label、按钮/span的动态创建，且正则确认规范 SVG 内不出现任何data-route-journey/route-journey-(flow|overlay)——即旅程只存在于查看器层（L37-L49）。
2. 精确边所有权与有限调度有专门契约：activeEdges[journeyIndex-1]的脉冲归属、data-route-journey的(i+1)/N进度标注、禁用querySelector自找边（L51-L62）。
3. roving tab 停靠、原生激活与手动所有权：chips 的tabindex、aria-current="step"、键盘ArrowRight/Home/End/Enter/Space与focusin暂停（L64-L75）。
4. 显式、有限、可恢复且不泄漏到 URL：JOURNEY_DWELL_MS=1100、代际守卫、剩余时间计算、#route=只有source~target且不含 journey（L77-L90）。
5. 动效、相机、分层 Escape、移动端、打印与嵌入边界：maxScale: 1.65、reason: 'route-journey'、44px（2.75rem）触控目标、@media print隐藏叠加层、data-motion="still"与prefers-reduced-motion: reduce的禁用规则（L92-L112）。
6. 导出剥离：移除data-route-journey及所有状态属性，canonicalStateClean校验（L114-L121）。

移动端触控目标、打印隐藏与prefers-reduced-motion的具体 CSS 位于 template.html、L3032、L4477-L4529、L4757。semantic-camera.test.mjs则验证了maxScale钳制、instant ? 'auto' : 'smooth'滚动行为与相机"让位于手动导航"的契约（test/semantic-camera.test.mjs）。

七、这轮决策带来的边界收益

• 没有新增 schema：五种模式的 JSON schema 保持不变（schemas）；
• 没有新增依赖：不引入第二个图引擎或动效运行时，Route Probe 已有的有序节点与精确边即真相；
• 没有新增布局引擎：几何、文本适配、布线仍由各渲染器与共享工具承担（renderers/shared/geometry.mjs、renderers/shared/text-fit.mjs）；
• 没有新增编辑面：旅程是纯查看器行为，作者 JSON 与导出工件完全不受影响；
• 浏览器验证覆盖交互、视觉状态、刷新、嵌入、导出与控制台洁净：对应契约测试可在archify/test/route-journey.test.mjs中直接运行验证。

八、动手验证

仓库根目录下运行以下命令可自行复现与验证：

# 渲染一个含 Route Probe / Route Journey 的示例工件 node archify/renderers/architecture/render-architecture.mjs \ archify/examples/web-app.architecture.json /tmp/route-journey.html # 运行 Route Journey 契约测试 node --test archify/test/route-journey.test.mjs

打开渲染出的 HTML：用r键或工具栏进入 Route Probe，选择起点与终点后，路径片会变为原生按钮；点击 Journey 按钮可观察有限、可暂停、可恢复的语义化入边脉冲；按Esc依次体验"暂停 → 总览 → 清除"三层退出；在操作系统开启"减少动态效果"或直接按v切换到 Still 模式后，Play 被禁用而手动检查与瞬时取景仍然可用。你可以在 archify/examples 与 archify/assets/template.html 中对照每一行实现继续深入。

附图：Route Probe 界面（含 Journey 控件、3 节点 2 跳路径与 Guided Views 步骤指示器），图片来自 docs/assets/archify-demo-route.png。

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