Archify 视觉验收实践以 Issue #52 为例构建可复现的浏览器级图例回归验证【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify本篇指南围绕 Archify 仓库中 docs/issue-52-visual-evidence/README.md 记录的 Issue #52 视觉验收过程系统讲解如何用无头 Chrome 在暗色/亮色双主题下对 dataflow 与 lifecycle 两类图表进行图例只渲染真实语义的自动化验收包括复现夹具的构造、机器可读验收结果的解读、npm run test:webm浏览器门禁的覆盖范围以及将 PNG 作为确定性证据工件保留的工程实践。读完本文你将掌握一套可直接复用的复现-渲染-浏览器断言-留档视觉回归流程并理解 Archify 图例系统的语义过滤、可访问性与导出净化机制。一、背景Issue #52 暴露的图例语义泄漏问题Archify 是一套将 JSON-IRarchitecture / workflow / sequence / dataflow / lifecycle渲染为自带交互与导出的自包含 HTML 图的渲染器其图例legend并非装饰性色块而是由meta.legend配置与图表内真实出现的语义种类kind共同决定的产物。Issue #52 复现出的典型缺陷是图例渲染了图表中根本不存在的语义条目。例如只声明了默认 flow 的数据流图图例却多出 PII、async、emphasis、data-store 等条目生命周期图只经历 start → active → success图例却仍然出现 waiting 与 failure。这类问题本质上来自按目录全量渲染图例与按实际内容过滤图例两条渲染路径的分歧。修复的核心机制位于 renderers/shared/legend.mjs 的mode解析逻辑const mode config?.mode || auto; if (mode hidden) return []; const selectedByMode mode all || present.has(catalogEntry.kind); const visible override.visible true || (selectedByMode override.visible ! false);即auto默认模式下图例条目必须满足该 kind 确实出现在当前图表中才可见all模式强制全量显示hidden模式完全关闭图例而meta.legend.entries中的visible与label覆盖项拥有最高优先级。legend.mjs还提供了legend/label-too-wide这类诊断码在条目标签超出可用宽度时给出带subject路径与supportedFixes建议的结构化错误[legend/label-too-wide] ... needs ${width}px but only ${width}px is available供上层的 renderers/shared/diagnostics.mjs 统一呈现。Issue #52 的验收目标就是用真实浏览器证明修复后图例中出现的每个条目都能在图谱中找到对应的真实语义且不引入布局回归。二、验收环境的确定性与前置条件验收在 2026-08-02 通过使用的基线信息在 README 中有明确记录浏览器Google Chrome headless视口宽度 1280px主题矩阵dark / light 双主题Before 基线渲染自origin/maina097c2d63eceeff9603a911a9075f0694d381f83旧提交After 实测渲染自当前工作树worktree。Before/After 双基线是本次验收的关键设计只有同时在旧提交与新代码上渲染同一份复现夹具并逐项对比才能证明修复不是靠改动复现数据作弊得到的。这与仓库中 delta/architecture-delta.mjs 维护 base/head 双快照的思想一致——对比本身需要可复现、可审计的输入。三、复现夹具最小化但语义完整的 JSON-IR 输入验收使用的两个复现夹具分别是docs/issue-52-visual-evidence/dataflow-repro.jsondiagram_type: dataflow两个节点Input → Output一条requestflowroute: straight无任何 PII / async / emphasis />node renderers/dataflow/render-dataflow.mjs dataflow-repro.json after-dataflow.html node renderers/lifecycle/render-lifecycle.mjs lifecycle-repro.json after-lifecycle.html四、验收矩阵与判读只显示真实语义README 的验收矩阵是整份文档的核心结论原文如下ReproductionDarkLightResultDataflow default-onlybefore / afterbefore / afterAfter shows onlydata flow; PII, async, emphasis, and />五、机器可读证据browser-results.json 的字段含义除截图外验收还产出机器可读结果 docs/issue-52-visual-evidence/browser-results.json顶层ok: true且runtimeErrors: []表示无任何运行时异常与console.error。逐项字段对应 README 列出的检查点字段含义验收断言kinds图例中出现的语义种类取自data-legend-semantic-kinddataflow 仅[default]lifecycle 仅[start,active,success]roles/aria每个图例条目的 ARIA role 与 accessible name仅可交互条目为button且带Inspect label, N node(s)命名其余为nullinside所有图例条目是否落在 SVG viewBox 内truedataflow 与 lifecycle 均通过nonOverlapping条目之间是否无重叠truebridge是否生成了交互桥接层data-legend-bridgedataflow 无无交互条目lifecycle 有start/active/success 可点击legendTitle图例标题是否存在true值得注意的是custom与longLabels两个附加用例custom验证了自定义标签传播如Reader UI ops、Future integration与强制 unused 种类仅视觉呈现longLabels则用中英混排长标签开始 / Start of the complete lifecycle等 8 种 kind验证长混合标签不重叠、且仅前两个可交互条目带 button role。这组字段直接对应 test/semantic-legend-gateway.test.mjs 与 test/legend-contract.test.mjs 中对图例语义契约的单元级约束。六、浏览器门禁npm run test:webm 如何守住回归截图验收之外仓库用 archify/package.json 的test:webm脚本把图例行为固化进持续集成test:webm: node test/webm-artifact.smoke.mjs node --test test/site-language-integration.mjs其实现位于 archify/test/webm-artifact.smoke.mjs是一个 1800 行的无头 Chrome CDP 冒烟框架它按 README 所述覆盖了 roving 键盘导航ArrowRight 移动焦点、Enter 打开 Semantic Lens、计数与选择、canonical SVG 清理、打印/嵌入行为、guided views以及 Classic / Signal Flow / Blueprint / Editorial × dark/light 的 8 格视觉矩阵。它通过freePort()寻找空闲端口、以--headlessnew启动 Chrome 并通过 WebSocket 连接 DevTools 协议然后用Runtime.evaluate直接在页面里执行断言脚本。Dataflow 图例门禁的具体断言verifyResolvedLegendContract真实 database 节点只暴露 1 个data store按钮data-legend-count为1tabindex0的焦点停止点恰好 1 个相邻的 flow-variant 条目保持视觉-only无data-legend-kind、role 为null对[data-legend-kinddatabase]按 Enter 后Archify.semanticLens.active()返回[database]且isOpen()为truestable kinddatabase的语义透镜捕获导出的 canonical SVG 后断言[data-legend-bridge]、[data-legend-kind]、[data-legend-label]、[data-legend-count]等桥接/运行时残留计数为 0——即canonical export 会剥离全部交互桥接层交付的 SVG 是干净的纯图形。Hidden 模式的完整性legend: { mode: hidden }的夹具被断言为根节点[data-legend]、桥接层与标题全部不存在{ root: false, bridge: false, title: false }对应legend.mjs中mode hidden直接返回空数组的分支。打印与嵌入行为Emulation.setEmulatedMedia切到print后图例容器 display 不为none而运行时徽标data-legend-bridge-runtime全部隐藏embed1模式下桥接与运行时元素计数为 0。这些断言把图例可读、交互桥接不泄漏到静态输出钉死在回归测试里。七、为什么用 PNG 而非 HTML 作为留档证据README 末尾解释了一个工程决策PNG 是确定性证据工件而生成的 HTML 不入库。理由有二生成 HTML 已被公开渲染器测试golden 测试与render-output-checks覆盖重复入库只会让同一份 viewer runtime 在仓库里出现八份拷贝放大 diff 噪音与维护成本PNG 是渲染结果的快照语义作为 issue 验收证据时不可被源代码演进无声改写审计性更强。这解释了docs/issue-52-visual-evidence/下同时存在browser-results.json结构化断言与八张 before/after 主题截图视觉留档的原因——两者互为补充共同构成可回溯的验收记录。八、把该方法复用到你自己的图例回归场景如果你需要为 Archify 渲染出的 HTML 图建立类似的视觉回归门禁可以按本文流程落地最小复现为每个被质疑的语义维度各写一个 JSON-IR 夹具显式固定viewBox只包含必要的节点/状态与 transition双基线渲染在origin/main的旧提交与当前工作树分别渲染同一夹具保证对比公平双主题断言在 dark/light 下分别校验kinds、roles、aria、inside、nonOverlapping、bridge、legendTitle七项交互与导出验证用 CDP 驱动 Enter/ArrowRight 验证 roving 焦点与 Semantic Lens 联动并对导出的 canonical SVG 断言零桥接残留证据留档截图 browser-results.json一同入库HTML 交给渲染器测试覆盖。上述断言所需的 DOM 契约data-legend-semantic-kind、data-legend-kind、data-legend-bridge、data-legend-count等由 renderers/shared/legend.mjs 在渲染期写入你可以在自己的验收脚本中直接复用这些选择器对图例语义、几何与可访问性更细粒度的约束可继续阅读 test/legend-contract.test.mjs、test/semantic-legend-gateway.test.mjs 与 test/grid.test.mjs。整个流程不依赖人工目测任何一次改动只要让图例渲染了图中不存在的语义门禁就会在 CI 中立即失败。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考