企业官网建设流程全解析

Archify 的 Mermaid 可视化质量验证实验复盘：为何"自动布局 + 换皮 CSS"跨不过美学鸿沟，以及它如何重塑了产品路线

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

本实验是 archify 规划 v3.0 时的关键决策证据：通过盲评对比"Stock Mermaid（A）""Mermaid + archify 风格主题（B）""archify 手放置 HTML（C）"三版渲染结果，验证"Mermaid 输入 + Claude 布局 + archify CSS 能显著优于 Stock Mermaid"这一核心假设。读完本文，你将掌握这次实验的完整协议（三版本设计、盲评流程、预注册通过标准、溯源清理与失败记录），并理解"布局即产品、而非 CSS"的结论如何直接催生了今天仓库中 JSON IR、五个类型化渲染器与 SKILL.md 的 Mermaid 输入约定。

实验背景与核心假设

实验记录（experiments/v3-mermaid-validation/RESULT.md）开篇即点名了要验证的核心假设：

"Mermaid input + Claude layout + archify CSS"produces diagrams rated significantly better than stock Mermaid.

即：把 Mermaid 作为输入方言，让 Claude 负责布局（layout），再叠加 archify 的 CSS 视觉系统，产出的图表应被盲评者评为显著优于Stock Mermaid 的默认输出。这一假设的验证设计最早记载于仓库根部的 ROADMAP.md（"Validation experiment"一节）。

在该实验之前，v3.0 的三次独立设计评审已汇聚出三条前置判断，实验正是为了给它们提供量化证据：

1. 自动布局（dagre / elk-js）对 archify 是死胡同——"Auth Provider 悬浮在 AWS region 外""S3 故意放在 CloudFront 下方以暗示服务关系""安全边界恰好留出 30/50 padding""把图例塞进留白"这些细节本身就是布局决策。把人类（或 Claude）从布局中剥离，等于把产品差异化剥离掉；dagre 对典型 8 节点图只输出均匀矩形网格，CSS 换皮充其量只能从"Stock Mermaid"走向"archify 手放置"的三成距离。
2. "更漂亮的 Mermaid 渲染器"已有人做——Mermaid 11.14 自身也已加入 Neo/Redux 主题、ELK 布局与 Hand Drawn 外观；沿着"给 Mermaid 换更美的皮"这个方向竞争是逆风仗。
3. JSON 优于 YAML 作为 IR 格式——LLM 生成的 YAML 因空白敏感而"看着对、解析错"的失败率高；JSON 解析无歧义、浏览器原生支持、且足够人读以支撑git diff。

三版本实验设计：A / B / C

实验把同一份真实世界 Mermaid 源图分别用三种方式渲染，完整方案如下表（原文档表格）：

三者差异的拆解非常有讲究：

• A 与 B 共享同一套 dagre 自动布局，区别只在视觉皮肤——B 注入 archify 风格的 themeCSS（调色板、字体、背景）。这样设计是为了隔离变量：若 B 相比 A 没有显著提升，则证明差距不来自 CSS，而来自布局本身。
• C 代表 archify 的产品形态：Claude 理解语义后手放置坐标、分配语义 class，再套 archify CSS。它同时改动了"布局"与"CSS"两个变量，是实验的"目标基准"。

版本 B 的 themeCSS 具体配置

版本 B 的实际注入配置完整保留在 theme/archify-mermaid-config.json，值得逐项解读（它正是"换皮"尝试的可复现实证）：

{ "theme": "base", "themeVariables": { "background": "#020617", "primaryColor": "rgba(30, 41, 59, 0.6)", "primaryTextColor": "#f1f5f9", "primaryBorderColor": "#94a3b8", "lineColor": "#64748b", "secondaryColor": "rgba(30, 41, 59, 0.6)", "tertiaryColor": "rgba(30, 41, 59, 0.6)", "mainBkg": "rgba(30, 41, 59, 0.6)", "secondBkg": "rgba(30, 41, 59, 0.6)", "tertiaryBkg": "rgba(30, 41, 59, 0.6)", "nodeBorder": "#94a3b8", "clusterBkg": "rgba(15, 23, 42, 0.4)", "clusterBorder": "#334155", "edgeLabelBackground": "#020617", "labelBoxBkgColor": "rgba(15, 23, 42, 0.9)", "labelBoxBorderColor": "#334155", "labelTextColor": "#cbd5e1", "fontFamily": "'JetBrains Mono', ui-monospace, Menlo, Consolas, monospace", "fontSize": "14px", "titleColor": "#f1f5f9", "textColor": "#e2e8f0", "errorBkgColor": "rgba(136, 19, 55, 0.4)", "errorTextColor": "#fb7185" }, "themeCSS": ".node rect, .node polygon, .node circle, .node ellipse, .node path { stroke-width: 1.5px !important; rx: 6 !important; ry: 6 !important; } .cluster rect { stroke-width: 1px !important; stroke-dasharray: 4,4 !important; rx: 8 !important; ry: 8 !important; } .edgePath .path { stroke-width: 1.5px !important; } .edgeLabel { font-size: 11px !important; } .nodeLabel { font-weight: 500 !important; }", "flowchart": { "htmlLabels": true, "curve": "basis", "padding": 20, "nodeSpacing": 50, "rankSpacing": 60 } }

可以看到 B 版已经尽力逼近 archify 的观感：深蓝黑背景（#020617）、半透明冷灰蓝节点、JetBrains Mono 等宽字体、节点/边 1.5px 描边、子图虚线边框，以及flowchart布局参数（curve: basis、padding: 20、nodeSpacing: 50、rankSpacing: 60）。但注意一个关键点：这些变量只改变了颜色、字体和线条样式，节点仍由 dagre 按默认策略排布——这正是实验要检验的"换皮不换布局"。

样本选择：真实世界 Mermaid 图与多样性自检

实验输入并非手工捏造的样例，而是从真实开源仓库中提取的 3 张 Mermaidflowchart图，来源与特征记录在 experiments/v3-mermaid-validation/INDEX.md：

三份源.mmd均保留在仓库中，可完整复现：

• 图 1（官方 canonical，决策循环）见 1-mermaid-canonical.mmd，5 个节点、TD 方向，含条件分支回环：

flowchart TD A[Start] --> B{Is it?} B -->|Yes| C[OK] C --> D[Rethink] D --> B B ---->|No| E[End]

• 图 2（k8s 日志聚合管道，LR 方向 + subgraph 源分组）见 2-k8s-observability.mmd；
• 图 3（moke-kit 微服务，TD 方向 + 5 层 subgraph，12 节点）见 3-moke-kit-stripped.mmd（剥离内嵌classDef的公平比较版本，原始带样式版本为 3-moke-kit.mmd）。

多样性自检与透明性标注

INDEX.md 还记录了刻意设计的样本多样性：

• 节点规模跨度：5 / 9 / 12（小到中等）；
• 方向覆盖：2 张 TD + 1 张 LR；
• 复杂度覆盖：纯流程图（#1）、含 subgraph（#2 #3）、内嵌classDef样式（#3，A/B 版会同时渲染带/不带内嵌样式两种，以验证 moke-kit 手调配色本身是否已达标）。

同时 INDEX.md 明确标注了三处透明性 caveat：图 1 取自语法文档页而非 canonicalexamples.mdshowcase（后者仅 4 节点、低于 5 节点下限）；图 2 是日志管道而非最初设想中的"k8s 部署拓扑"（kubernetes/website 仓库中最突出的 flowchart 即此图）；图 3 的内嵌classDef在 A/B 版中被同时渲染带/不带两种以保公平。这些自述为后续"实验能否复现"提供了诚实边界。

溯源清理（2026-09-01）

RESULT.md 中有一条重要的 provenance 记录：原始实验运行使用了 5 张图、15 张截图；图 4、图 5 及其衍生截图因源仓库未能提供可验证的分发许可而在 2026-09-01 被移除。当前仓库保留的是 3 图 / 9 截图的证据集，因此"原始 5 输入实验"已无法从当前树（HEAD）完整复现。这个细节对文章的可信度很重要：仓库宁可损失部分证据，也不保留许可存疑的衍生内容。

盲评协议：如何打分与去匿名

盲评的核心是消除评分者对版本的先验偏好，RESULT.md 给出了完整可执行的四步流程：

1. 打开screenshots/中保留的每张文件——文件名已随机化、标签已剥离；
2. 对每张图按视觉质量打 1–10 分；
3. 全部 9 张评完后，打开screenshots/manifest.txt去匿名（de-anonymize）；
4. 填写下方各评分表。

随机化映射由 screenshots/manifest.txt 记录，例如img-04-12c2.png → diagram=1 version=C、img-08-weo4.png → diagram=1 version=A、img-13-5mj4.png → diagram=2 version=A等，9 张截图覆盖 3 个图 × 3 个版本，且文件名完全无法看出版本归属。输出目录结构与之一一对应：output-A-stock（A 版，默认主题）、output-B-themed（B 版，注入 archify 风格 themeCSS）、output-C-archify（C 版，手放置 archify HTML）。

项目所有者需先填写自评表（9 张截图各 1–10 分），再填写去匿名汇总表，最后给出两个关键统计量：B 平均分与B 在几张图中更接近 C（而非 A）。

通过标准：预注册的量化门槛

通过标准来自 ROADMAP.md 的实验设计，属于实验前预注册的硬指标，RESULT.md 原样保留：

• B 平均分 ≥ 7/10；
• B 在 5 张图中至少有 4 张被评为比 A 更接近 C。

RESULT.md 特别强调：4-of-5 阈值按原始预注册标准保留，不得事后改写为 2-of-3——在溯源清理之后，原 5 图门槛已无法从当前树重新运行。这是实验方法论上非常严谨的一笔：门槛一旦预注册就不可为方便结论而事后篡改。

实验结果：结论性失败，但方向性收获

所有者自评结论（2026-04-16）

决策记录中，所有者自评勾选了FAIL，并留下了直白的定性结论：

Owner self-evaluation result:C（archify 手放置）看起来好；A 和 B 都不好看。B 相比 A 没有实质性提升——仅换 CSS 而不改布局，无法跨越美学鸿沟。实验证实了三次实验前评审的共同判断：布局才是产品，不是 CSS。

这意味着两条通过标准全部未满足：B 平均分未达 7/10，B 也未能被评得更接近 C。由于自评已结论性失败，外部 5 人工程师评审面板被跳过（该面板在 RESULT.md 中保留为可选模板，含 Rater 1–5 与汇总表结构，供未来假设复用）。

证据图对比：同一 k8s 图，A 版与 C 版

以图 2（k8s 日志聚合管道，LR 方向）为例，可以直观看到实验结论。Stock Mermaid（版本 A，dagre 自动布局 + 默认主题）的输出：

而同一份.mmd源图由 Claude 手放置坐标、套用 archify CSS 的版本 C 输出：

两图对比即可感知：即便 B 版已把 archify 的深色背景、等宽字体与描边细节全部注入（见 archify-mermaid-config.json），dagre 排布下的节点仍呈呆板的均匀网格；而 C 版通过语义分组、刻意间距与不对称放置，才呈现出"信息架构"意义上的层次与叙事。其余对比证据（含 A/B/C 三版完整 9 图、匿名化盲评集）可继续查看 screenshots 目录。

决策后果：路线收敛与四项落地

FAIL 的结论没有浪费——它把 v3.0 的候选路线收敛为清晰的四点，逐条在 RESULT.md 的 Consequence 中记录：

1. P1（Mermaid flowchart 解析器 → IR + dagre 布局）被砍掉（KILLED）——实验证明"自动布局 + CSS"不足以达标；
2. P0 / P0.5（JSON IR + render.js 保证坐标稳定）仍然可行——它们解决的是与 Mermaid 输入无关的"坐标漂移"问题；
3. Mermaid 输入改为 SKILL.md 提示工程技巧——用户粘贴 Mermaid，Claude 读取结构后以 archify 风格从零布局；无 dagre、无解析器、无自动布局。这与 archify 现今日的工作方式（用户描述 → Claude 绘制）一致，只是把输入方言从自然语言换成 Mermaid；
4. 外部 5 人评审面板跳过——自评已结论性失败两条标准，无需再耗费外部评审资源。

ROADMAP.md 中的修订后分期表完整呈现了这条收敛路径：

结论在当前仓库的落地证据

实验结论并非停留在文档里，当前仓库的代码与约定可以逐条印证：

• SKILL.md 的 Mermaid 输入约定（archify/SKILL.md 中 "Mermaid input" 一节）正是 P2 的产物："Read Mermaid for topology and meaning, then author fresh Archify JSON; do not mechanically render Mermaid styling."——读取 Mermaid 只取其拓扑与语义，然后重新创作 Archify JSON，绝不机械搬运 Mermaid 样式。映射规则为：flowchart/graph→workflow（或组件图用architecture）；sequenceDiagram→sequence；stateDiagram→lifecycle。
• 五种类型化渲染器（archify/renderers 下的architecture/、workflow/、sequence/、dataflow/、lifecycle/）对应 P0.5 的交付，且刻意保持"受约束的布局助手"而非通用图布局引擎——车道/泳道/阶段/生命线提供稳定性，语义分组、顺序、标签仍由 Claude 决策。
• JSON Schema 与schema_version: 1（archify/schemas/README.md）对应 P0，schema 在开发期用 ajv 预编译、运行期由零依赖独立验证器强制。
• ROADMAP.md 的 "Not planned" 表把实验结论固化为长期决策记录：Auto-layout (dagre / elk-js)、Mermaid flowchart parser + dagre auto-layout、YAML as the IR format均被显式拒绝，并各自注明拒绝理由——其中 parser 条目直接援引本实验"（2026-04-16）conclusively showed that auto-layout + archify CSS is not meaningfully better than stock Mermaid"。

实验方法论的可复用价值

抛开 archify 本身，这份记录对任何"为视觉质量做技术决策"的工程团队都是一份高完成度的参考模板，值得沉淀的实践有四条：

1. 预注册门槛：通过标准在实验前写死（B ≥ 7/10、4-of-5 更接近 C），失败后也不为结果改写门槛，杜绝"事后找理由"；
2. 变量隔离：A/B 共享 dagre 布局、仅差 CSS，使"布局 vs CSS"的归因变得干净；C 作为目标形态基准提供锚点；
3. 盲评去匿名：随机化文件名 + 剥离标签 + 评分后统一 de-anonymize，抑制先验偏好；
4. 失败记录与溯源清理：FAIL 结论、跳过外部评审的决定、因许可问题移除两图的 provenance 说明全部留档，甚至明确承认"原 5 输入实验已无法从当前树复现"——这种诚实边界比粉饰过的"成功"更具参考价值。

正如 ROADMAP.md 所总结的：archify 的美学护城河在于 Claude 的布局判断（语义分组、刻意间距、不对称放置），而非其 CSS。任何把 Claude 从布局环中移除的路径（自动布局、解析器管线）都是在剥离产品差异化本身。这就是一次"失败的实验"如何成为最有价值的路线决策证据的完整范本。

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