Archify 的 Mermaid 可视化质量验证实验复盘为何自动布局 换皮 CSS跨不过美学鸿沟以及它如何重塑了产品路线【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify本实验是 archify 规划 v3.0 时的关键决策证据通过盲评对比Stock MermaidAMermaid archify 风格主题Barchify 手放置 HTMLC三版渲染结果验证Mermaid 输入 Claude 布局 archify CSS 能显著优于 Stock Mermaid这一核心假设。读完本文你将掌握这次实验的完整协议三版本设计、盲评流程、预注册通过标准、溯源清理与失败记录并理解布局即产品、而非 CSS的结论如何直接催生了今天仓库中 JSON IR、五个类型化渲染器与 SKILL.md 的 Mermaid 输入约定。实验背景与核心假设实验记录experiments/v3-mermaid-validation/RESULT.md开篇即点名了要验证的核心假设Mermaid input Claude layout archify CSSproduces diagrams rated significantly better than stock Mermaid.即把 Mermaid 作为输入方言让 Claude 负责布局layout再叠加 archify 的 CSS 视觉系统产出的图表应被盲评者评为显著优于Stock Mermaid 的默认输出。这一假设的验证设计最早记载于仓库根部的 ROADMAP.mdValidation experiment一节。在该实验之前v3.0 的三次独立设计评审已汇聚出三条前置判断实验正是为了给它们提供量化证据自动布局dagre / elk-js对 archify 是死胡同——Auth Provider 悬浮在 AWS region 外S3 故意放在 CloudFront 下方以暗示服务关系安全边界恰好留出 30/50 padding把图例塞进留白这些细节本身就是布局决策。把人类或 Claude从布局中剥离等于把产品差异化剥离掉dagre 对典型 8 节点图只输出均匀矩形网格CSS 换皮充其量只能从Stock Mermaid走向archify 手放置的三成距离。更漂亮的 Mermaid 渲染器已有人做——Mermaid 11.14 自身也已加入 Neo/Redux 主题、ELK 布局与 Hand Drawn 外观沿着给 Mermaid 换更美的皮这个方向竞争是逆风仗。JSON 优于 YAML 作为 IR 格式——LLM 生成的 YAML 因空白敏感而看着对、解析错的失败率高JSON 解析无歧义、浏览器原生支持、且足够人读以支撑git diff。三版本实验设计A / B / C实验把同一份真实世界 Mermaid 源图分别用三种方式渲染完整方案如下表原文档表格CodeWhat it isAStock Mermaid viammdc— default theme, dagre layout, no customizationBMermaid viammdc archify-style themeCSS — same dagre layout, archify color palette / font / backgroundCHand-placed archify HTML — Claude-assigned semantic classes hand-placed coordinates archify CSS三者差异的拆解非常有讲究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#CategorySourceNodesDirectionNotes1Mermaid official canonicalmermaid-js/mermaid 官方语法文档flowchart.md5TD官方语法文档中的 decision-loop 示例原 4 节点 showcase 低于 ≥5 节点下限被替换2Kuberneteskubernetes/website 文档observability.md9LRk8s 日志聚合管道用 subgraph 对源做分组3MicroservicesGStones/moke-kit 项目 README12TDGo 游戏服务器工具包5 层 subgraph内嵌classDef配色为公平对比而剥离三份源.mmd均保留在仓库中可完整复现图 1官方 canonical决策循环见 1-mermaid-canonical.mmd5 个节点、TD 方向含条件分支回环flowchart TD A[Start] -- B{Is it?} B --|Yes| C[OK] C -- D[Rethink] D -- B B ----|No| E[End]图 2k8s 日志聚合管道LR 方向 subgraph 源分组见 2-k8s-observability.mmd图 3moke-kit 微服务TD 方向 5 层 subgraph12 节点见 3-moke-kit-stripped.mmd剥离内嵌classDef的公平比较版本原始带样式版本为 3-moke-kit.mmd。多样性自检与透明性标注INDEX.md 还记录了刻意设计的样本多样性节点规模跨度5 / 9 / 12小到中等方向覆盖2 张 TD 1 张 LR复杂度覆盖纯流程图#1、含 subgraph#2 #3、内嵌classDef样式#3A/B 版会同时渲染带/不带内嵌样式两种以验证 moke-kit 手调配色本身是否已达标。同时 INDEX.md 明确标注了三处透明性 caveat图 1 取自语法文档页而非 canonicalexamples.mdshowcase后者仅 4 节点、低于 5 节点下限图 2 是日志管道而非最初设想中的k8s 部署拓扑kubernetes/website 仓库中最突出的 flowchart 即此图图 3 的内嵌classDef在 A/B 版中被同时渲染带/不带两种以保公平。这些自述为后续实验能否复现提供了诚实边界。溯源清理2026-09-01RESULT.md 中有一条重要的 provenance 记录原始实验运行使用了 5 张图、15 张截图图 4、图 5 及其衍生截图因源仓库未能提供可验证的分发许可而在 2026-09-01 被移除。当前仓库保留的是 3 图 / 9 截图的证据集因此原始 5 输入实验已无法从当前树HEAD完整复现。这个细节对文章的可信度很重要仓库宁可损失部分证据也不保留许可存疑的衍生内容。盲评协议如何打分与去匿名盲评的核心是消除评分者对版本的先验偏好RESULT.md 给出了完整可执行的四步流程打开screenshots/中保留的每张文件——文件名已随机化、标签已剥离对每张图按视觉质量打 1–10 分全部 9 张评完后打开screenshots/manifest.txt去匿名de-anonymize填写下方各评分表。随机化映射由 screenshots/manifest.txt 记录例如img-04-12c2.png → diagram1 versionC、img-08-weo4.png → diagram1 versionA、img-13-5mj4.png → diagram2 versionA等9 张截图覆盖 3 个图 × 3 个版本且文件名完全无法看出版本归属。输出目录结构与之一一对应output-A-stockA 版默认主题、output-B-themedB 版注入 archify 风格 themeCSS、output-C-archifyC 版手放置 archify HTML。项目所有者需先填写自评表9 张截图各 1–10 分再填写去匿名汇总表最后给出两个关键统计量B 平均分与B 在几张图中更接近 C而非 A。通过标准预注册的量化门槛通过标准来自 ROADMAP.md 的实验设计属于实验前预注册的硬指标RESULT.md 原样保留B 平均分 ≥ 7/10B 在 5 张图中至少有 4 张被评为比 A 更接近 C。RESULT.md 特别强调4-of-5 阈值按原始预注册标准保留不得事后改写为 2-of-3——在溯源清理之后原 5 图门槛已无法从当前树重新运行。这是实验方法论上非常严谨的一笔门槛一旦预注册就不可为方便结论而事后篡改。实验结果结论性失败但方向性收获所有者自评结论2026-04-16决策记录中所有者自评勾选了FAIL并留下了直白的定性结论Owner self-evaluation result:Carchify 手放置看起来好A 和 B 都不好看。B 相比 A 没有实质性提升——仅换 CSS 而不改布局无法跨越美学鸿沟。实验证实了三次实验前评审的共同判断布局才是产品不是 CSS。这意味着两条通过标准全部未满足B 平均分未达 7/10B 也未能被评得更接近 C。由于自评已结论性失败外部 5 人工程师评审面板被跳过该面板在 RESULT.md 中保留为可选模板含 Rater 1–5 与汇总表结构供未来假设复用。证据图对比同一 k8s 图A 版与 C 版以图 2k8s 日志聚合管道LR 方向为例可以直观看到实验结论。Stock Mermaid版本 Adagre 自动布局 默认主题的输出而同一份.mmd源图由 Claude 手放置坐标、套用 archify CSS 的版本 C 输出两图对比即可感知即便 B 版已把 archify 的深色背景、等宽字体与描边细节全部注入见 archify-mermaid-config.jsondagre 排布下的节点仍呈呆板的均匀网格而 C 版通过语义分组、刻意间距与不对称放置才呈现出信息架构意义上的层次与叙事。其余对比证据含 A/B/C 三版完整 9 图、匿名化盲评集可继续查看 screenshots 目录。决策后果路线收敛与四项落地FAIL 的结论没有浪费——它把 v3.0 的候选路线收敛为清晰的四点逐条在 RESULT.md 的 Consequence 中记录P1Mermaid flowchart 解析器 → IR dagre 布局被砍掉KILLED——实验证明自动布局 CSS不足以达标P0 / P0.5JSON IR render.js 保证坐标稳定仍然可行——它们解决的是与 Mermaid 输入无关的坐标漂移问题Mermaid 输入改为 SKILL.md 提示工程技巧——用户粘贴 MermaidClaude 读取结构后以 archify 风格从零布局无 dagre、无解析器、无自动布局。这与 archify 现今日的工作方式用户描述 → Claude 绘制一致只是把输入方言从自然语言换成 Mermaid外部 5 人评审面板跳过——自评已结论性失败两条标准无需再耗费外部评审资源。ROADMAP.md 中的修订后分期表完整呈现了这条收敛路径PhaseDeliverableTargetValidate原始 5 图盲评实验保留 3 个许可输入DONE — FAILEDP0JSON IR JSON Schema validator schema_version强制DONE——五种图类型均落地运行时经 ajv 强制P0.5纯 JS 渲染器 IR → HTML坐标必填无自动布局DONE——五种渲染器位于 archify/renderersP1Mermaid flowchart parser → IRKILLEDP2更新 SKILL.md 教 Claude 接受 Mermaid 输入并从零布局提示工程无解析器DONE — 2026-06-11P3端到端解析器管线KILLEDP4IR → Mermaid 输出 C4 输入KILLED结论在当前仓库的落地证据实验结论并非停留在文档里当前仓库的代码与约定可以逐条印证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或组件图用architecturesequenceDiagram→sequencestateDiagram→lifecycle。五种类型化渲染器archify/renderers 下的architecture/、workflow/、sequence/、dataflow/、lifecycle/对应 P0.5 的交付且刻意保持受约束的布局助手而非通用图布局引擎——车道/泳道/阶段/生命线提供稳定性语义分组、顺序、标签仍由 Claude 决策。JSON Schema 与schema_version: 1archify/schemas/README.md对应 P0schema 在开发期用 ajv 预编译、运行期由零依赖独立验证器强制。ROADMAP.md 的 Not planned 表把实验结论固化为长期决策记录Auto-layout (dagre / elk-js)、Mermaid flowchart parser dagre auto-layout、YAML as the IR format均被显式拒绝并各自注明拒绝理由——其中 parser 条目直接援引本实验2026-04-16conclusively showed that auto-layout archify CSS is not meaningfully better than stock Mermaid。实验方法论的可复用价值抛开 archify 本身这份记录对任何为视觉质量做技术决策的工程团队都是一份高完成度的参考模板值得沉淀的实践有四条预注册门槛通过标准在实验前写死B ≥ 7/10、4-of-5 更接近 C失败后也不为结果改写门槛杜绝事后找理由变量隔离A/B 共享 dagre 布局、仅差 CSS使布局 vs CSS的归因变得干净C 作为目标形态基准提供锚点盲评去匿名随机化文件名 剥离标签 评分后统一 de-anonymize抑制先验偏好失败记录与溯源清理FAIL 结论、跳过外部评审的决定、因许可问题移除两图的 provenance 说明全部留档甚至明确承认原 5 输入实验已无法从当前树复现——这种诚实边界比粉饰过的成功更具参考价值。正如 ROADMAP.md 所总结的archify 的美学护城河在于 Claude 的布局判断语义分组、刻意间距、不对称放置而非其 CSS。任何把 Claude 从布局环中移除的路径自动布局、解析器管线都是在剥离产品差异化本身。这就是一次失败的实验如何成为最有价值的路线决策证据的完整范本。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考