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 中的loadDiagramJSON 输入 →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 决策矩阵这是整轮研究的决策中枢逐条对应借什么 / 怎么适配 / 明确跳过什么决策对象Archify 的落点Borrow语义化、有界的动效为一个路径位置动画展示一条精确的作者入边绝不凭空合成关系。Borrow有界的视觉 QA保留确定性测试 → 重建生成示例 → 在真实浏览器中检查桌面/移动/嵌入/导出。Adapt动画时间轴在现有 Route Probe 内提供阅读器控制的 Route Journey而非另造独立 GIF 运行时。Adapt视口动画通过现有 Semantic Camera 取景前一个/当前/后一个切片手动导航永远优先。Adapt视觉多样性让同一状态在 Classic、Signal Flow、Blueprint 三种预设下都可读而非新增未验证的风格。Skip连续自动播放路线创建、URL 恢复、聚焦、悬停、页面加载均不触发动画。Skip新的图/运行时依赖有序节点与精确边已存在于 Route Probe第二个图引擎会重复同一份真相。SkipURL 中的旅程状态只分享持久的端点问题播放位置属于临时阅读器状态。Skip规范产物/导出变异旅程叠加层与状态仅存在于查看器中从独立 SVG 导出与打印中剥离。四、Round 36 产品决策把 Route Journey 建成 Route Probe 之上的可检查层最终决策是构建Route Journey 作为 Route Probe 之上的可检查层共 9 条与源码逐条对应保留完整最短作者路径作为上下文——showResult中activeNodeIds result.nodes.slice()、activeEdges result.edges.slice()template.html全路径节点与边打上data-route-match/data-route-step。把路径片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/Spacetemplate.html。阅读器可在 Still 或 Live 模式下手动检查任意位置——selectJourneyIndex(index)调用applyJourneyState可随时定位任意步骤template.html。Play 是显式、有限、可暂停、可从剩余停留时间恢复的——JOURNEY_DWELL_MS 1100scheduleJourney用Math.max(0, JOURNEY_DWELL_MS - journeyElapsedMs)计算剩余时间每次调度journeyGeneration 1作代际守卫template.html注意实现刻意不用setInterval而是递归setTimeout契约测试对此有doesNotMatch断言。位置i 0精确拥有activeEdges[i - 1]位置 0 不拥有任何入边——applyJourneyState中destination journeyIndex ? current : futurejourneyIndex 0时才renderJourneyPulse(activeEdges[journeyIndex - 1])template.html。由现有 Semantic Camera 取景前/当前/后切片——Archify.view.reveal(activeNodeIds.slice(journeyIndex-1, journeyIndex2), { maxScale: 1.65, padding: 64, duration: 360, instant: !journeyMotionAllowed() })template.html相机契约见 test/semantic-camera.test.mjs。分层 Escape暂停 → 总览 → 清除路线——escapeRoute依次返回paused/overview/clearedtemplate.html。#routesource~target仅保留端点恢复时进入总览且不自动播放——syncFromHash只解析两个端点choose(parts[1], { updateUrl: false })后showResult内showJourneyOverview({ reveal: false })URL 从不携带 journey 状态template.html、L13551-L13554。从打印、嵌入与导出 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/箭头/数据属性赋予classroute-journey-flow与pathLength1插入到第一个节点之前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, …)获取所有权 tokenjourneyMotionAllowed()校验嵌入模式、文档可见性、能力与暂停状态任何一方不满足即不播放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对五种渲染器逐一断言五渲染器继承同一套控件与状态机route-journey-controls面板、prev/play/next/overview按钮的aria-label、按钮/span的动态创建且正则确认规范 SVG 内不出现任何data-route-journey/route-journey-(flow|overlay)——即旅程只存在于查看器层L37-L49。精确边所有权与有限调度有专门契约activeEdges[journeyIndex-1]的脉冲归属、data-route-journey的(i1)/N进度标注、禁用querySelector自找边L51-L62。roving tab 停靠、原生激活与手动所有权chips 的tabindex、aria-currentstep、键盘ArrowRight/Home/End/Enter/Space与focusin暂停L64-L75。显式、有限、可恢复且不泄漏到 URLJOURNEY_DWELL_MS1100、代际守卫、剩余时间计算、#route只有source~target且不含 journeyL77-L90。动效、相机、分层 Escape、移动端、打印与嵌入边界maxScale: 1.65、reason: route-journey、44px2.75rem触控目标、media print隐藏叠加层、data-motionstill与prefers-reduced-motion: reduce的禁用规则L92-L112。导出剥离移除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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考