Archify 构图回执（Composition Receipt）：从“看起来乱“到确定性渲染与修复的质量门禁

Archify 构图回执（Composition Receipt）：从"看起来乱"到确定性渲染与修复的质量门禁

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

导读

本文基于 Archify 开源仓库的视觉演化研究文档 docs/research-visual-evolution-round-44.md，系统讲解其核心决策：构建一个确定性的构图回执（Composition Receipt），让图表在"安全可用"与"精修交付（showcase）"两个质量档位之间拥有可复现、可机器校验、可修复的评价体系。读完本文，你将掌握standard与showcase两个质量档位的完整语义、回执的 JSON 契约与测量规则、CLI 与 Gallery 的接入方式，以及这套设计如何借助共享几何引擎，把"图看起来很乱"这类主观感受转化为作者可以逐条修复的稳定诊断。

为什么需要构图回执：现状审计揭示的缺口

Round 44 的研究起点是审计现有 Gallery 收据体系。当时生成的 docs/gallery/manifest.json 记录着 11 个类型化来源、111 条语义关系（覆盖 architecture、workflow、sequence、dataflow、lifecycle 五种图表），每个工件 4 项检查，合计 44 项通过：单一 SVG、有限输出、不存在单段对角箭头、图例避让。

从源码看，这四项确实只覆盖了"工件完整性"：

• check-render-output.mjs 中的single_svg、finite_svg、orthogonal_arrows、legend_clearance检查只证明"文件能打开、SVG 结构正确"；
• layout-report.mjs 只针对 architecture 序列化组件与连线的几何，archify inspect与validate --layout-json同样仅限 architecture；
• 其余四个渲染器内部已经算出精确路径，却没有暴露任何公共的布局或构图报告。

因此研究文档的结论非常明确：当时的 Gallery 回执是工件完整性回执，不是构图回执。它无法回答以下问题：关系与关系之间是否交叉？是否存在共享通道或堆叠箭头？路径弯曲、拉伸或存在过短线段？路径是否沿容器/阶段/分组/泳道边框运行？某个工件是否满足指定的精修交付档位？

在线交叉实验：为什么必须引入档位

研究中一个并发工作树改动为全部五个渲染器加入了cleanCrossingProblems()，并在check-render-output.mjs中加入了relationship_crossings检查。对照 11 个已生成工件，该检查器发现4 处无关 proper 交叉：

前三处存在于正交路径骨架中，而 lifecycle 交叉是由两个圆角二次曲线（Q 曲线）引入的：渲染器侧的 raw-polyline 校验接受它，渲染后的可见路径检查却拒绝它。这是两份独立实现的交叉计算必然漂移的直接证据——可见构图必须基于最终路径图元（包括曲线）来评估。同时，docs/gallery/manifest.json 仍声称 44 项旧检查全部通过，而新的五合一检查器却拒绝了四个已存储工件。这说明未来的回执必须原子地生成与消费，避免检查器契约变更后 Gallery 仍然展示过期的"全绿"声明。

语料基线：哪些信号该是硬错误、哪些该是度量

研究对 111 条业务关系（排除图例箭头、lifecycle 轨道、生命线、动画回显与装饰形状）做了审计：圆角路径按确定性容差展平以分析可见交叉，弯折与线段度量则从路径骨架恢复，并归一化掉重复与共线途经点。基线数据如下：

两条边框运行路径是具体的：Product Analytics 的web -> edge沿 Sources 阶段右边框（x=184）运行了 114px；Web App 的auth -> api沿安全分组顶边框（y=270）运行了 99px。两者语义上合法、也能通过 Clean Flow，却把业务连线与结构框在视觉上混为一体。这正是下一个最值得升级为通用硬不变量的信号——从源码看，geometry.mjs 中的collectBorderRuns()与cleanBorderRunProblems()如今已将其实现为跨档位硬错误。

借他山之石：Fireworks、Graphviz、ELK、D2、Structurizr 与 LikeC4 的借鉴边界

研究文档对六个外部方案做了"借用（Borrow）/适配（Adapt）/跳过（Skip）"三分类，核心是不要照搬阈值，而要借边界设计：

• Fireworks Tech Graph：其 Composition Quality Contract 将样式与几何分离，定义了严格的showcase档位（零边交叉与桥接、每边至多 2 弯折、Manhattan 拉伸 ≤ 1.35、16px 最短线段、明确的间距/gutter 预算、开放容器穿越走廊、同侧共享边使用独立端口、禁止堆叠箭头）。其实现是显式档位化的：standard远宽松于showcase，拉伸定义为折线 Manhattan 长度除以端点直接 Manhattan 距离。借用命名交付档位、结构化度量、"渲染成功不等于精修交付"的规则；适配：用共享语义端点与渲染器路由类别替代坐标相等判断，用 Archify 真实语料校准告警预算；跳过：六节点参考拓扑的总弯折预算、拓扑相关的 0–100 分。
• Graphviz：splines文档明确样条绕开节点但不承诺零边边交叉；concentrate刻意合并多重边并允许部分平行关系共享路径；samehead/sametail允许边指向公共头/尾点。借用"节点避让是安全、交叉消减是构图"的二分；适配共享语义源/目标通道的分类；跳过"每个共线重叠或公共端点都是意外"。
• ELK/Libavoid：ELK Layered 通过重排节点最小化交叉再计算弯折点，支持端口、多重边、复合图与 junction 输出；Libavoid 的 shared-endpoint nudging 默认分离公共端点中间路径但允许整体共享路径重叠；Junction Points 是正交超边的显式输出而非从几何接触推断；Cluster Crossing Penalty 把边界穿越当作可配置的路由代价而非无条件错误。借用显式问题类别与 junction 语义；适配当前只有边框共线在 Archify 中是普遍错误，必要的垂直穿越容器仍合法；跳过从 T 触或坐标巧合猜测 junction。
• D2：其 ELK 对比文档承认正交路径虽有干净的绕障与交叉最小化，但也会产生不必要弯折；序列图规则赋予消息顺序、生命线、激活跨度、分组与自消息专门语义。借用在保留渲染器语义的前提下评估最终路径；适配序列消息是普通回执关系，但生命线、激活条与帧不是业务边，自消息没有普通拉伸分母；跳过把同一个几何阈值盲目套到每条可见线上。
• Structurizr 与 LikeC4：Structurizr 在自动布局不够好时明确建议回到手动模式，作者可增删关系顶点、移动标签、切换直连/正交/曲线路由；LikeC4 的 Graphviz 打印器与 AI 布局提示要求最小化交叉、偏好平衡更直的边，但不会把剩余交叉重新定义为无效模型内容。借用"每个问题都必须指向一个作者可控制的修复旋钮"；适配指向via、route、fromSide、toSide、通道坐标、行列摆放或档位选择；跳过静默修改作者 JSON 或用桥接装饰隐藏未解路由。

双层契约：两个质量档位与严重度矩阵

Round 44 的最终决策是不要把每个几何边交叉都升级为无条件布局错误：保留 Round 43 的 edge-through-unrelated-node 作为通用安全门，把 route-on-container-border 提升为第二个通用硬错误，其余构图信号按档位分类为错误、警告或度量。产品一句话可概括为：Archify 告诉作者一个图是否安全、是否精修，以及具体是哪条路由决策使它无法进入下一个质量档位。

档位定义

研究文档明确反对仅为逃生而增加stress档位：现有standard已能支撑密集工程图，未来的压力语料可以作为测试套件分类，而不必成为公开 JSON API。这一点与 common.schema.json 中qualityProfile枚举["standard", "showcase"]完全一致。

严重度矩阵

研究文档同时给出升级路径：当显式port、junction与路由角色语义出现后，Archify 可以把未声明触与堆叠箭头提升为showcase错误；在此之前贸然升级，等于把校验器变成死胡同。

归一化与测量规则：共享几何引擎的十一条契约

回执的准确性依赖一组无歧义的测量规则（文档原文共 11 条，全部继承如下）：

1. 只有带稳定from、to、集合索引与可选id的语义关系才进入回执。
2. 装饰、发光/描边回显、lifecycle 轨道、生命线、激活条、分段帧、图例与查看器覆盖层按语义角色排除，而非按 CSS 类名猜测。
3. 保留最终路径图元。在确定性容差下展平Q曲线用于交叉分析，但不要用弦代替曲线。
4. 从路径骨架恢复弯折与线段。移除连续重复点并折叠共线途经点。弯折是真实的方向变化，圆角控制点不增加弯折数。
5. proper 交叉要求两条路径内部真正相交；坐标是任一线段端点的相交属于 touch，不是 proper 交叉。
6. 共享端点豁免要求两条关系共享同一语义节点 ID，仅坐标相等永不构成豁免。
7. 共线正长度相交是重叠，并保留其总重叠长度，按语义端点分类为 shared 或 unrelated。
8. 拉伸 = 路径 Manhattan 长度 ÷ 端点直接 Manhattan 长度。自环或零分母返回null而非无穷。
9. 归一化后只统计正线段，报告最小线段长度及其所属关系/线段。
10. 结构帧是类型化的：architecture 边界、workflow 泳道/分组、dataflow 阶段、sequence 分段、lifecycle 分隔符/色带。只有帧边框上的正长度共线运行是硬缺陷，点状进出仍属于度量。
11. 内部保留精确测量值，仅序列化展示值四舍五入；问题按严重度、代码、关系集合/索引、另一关系索引与线段索引排序，保证输出确定性。

从 geometry.mjs 的现有实现可以印证这些规则：normalizeRoutePoints()（L966 起）去重并折叠共线途经点；forwardCollinearAnalysisSegments()（L408 起）把共线前进段合并以免 proper X 落在途经点上被隐藏；properSegmentIntersection()（L1065 起）用叉积判断真正的内部交叉；collectBorderRuns()（L671 起）配合frameBorderSegments()（L1001 起）从圆角矩形四边建模边框线段，圆角半径从直边两侧裁掉，避免短角触被误判为边框运行；routeBudgetMetrics()（L758 起）计算maxBends、maxStretch、minSegmentPx等预算指标，其中bendsPerRelationship: 2、stretch: 1.35、segmentPx: 16、microSegmentPx: 8与文档建议完全对应。

回执形状（Receipt shape）

回执不是单个绿色布尔值，而是结构化 JSON。原文档示例完整如下：

{ "schemaVersion": 1, "profile": "showcase", "status": "fail", "summary": { "errors": 1, "warnings": 3 }, "metrics": { "relationshipCount": 12, "properCrossings": 1, "touches": 0, "unrelatedOverlapPairs": 0, "sharedChannelPairs": 2, "stackedArrowheads": 1, "maxBends": 3, "overBendBudget": 1, "maxStretch": 1.45, "overStretchBudget": 1, "minSegmentPx": 25, "shortSegmentCount": 0, "containerBorderRuns": 0, "boundaryCrossings": 4 }, "issues": [ { "severity": "error", "code": "composition/proper-crossing", "relationship": { "collection": "connections", "index": 6, "from": "api_a", "to": "events" }, "otherRelationship": { "collection": "connections", "index": 9, "from": "postgres", "to": "replica" }, "point": [1000, 276], "suggestion": "Move one via point or choose a separate boundary corridor." } ] }

注意：不要序列化单一评分。计数与比率只能在同一工件/档位内或同一拓扑的确定性版本之间比较，不能在无关图之间横向排名。如今 docs/gallery/manifest.json 中每个条目的composition字段已经采用这一形状（含schemaVersion、profile: "showcase"、status、summary、metrics与suggestedLimits），可作为实现后的真实样例。

单一几何真源：共享模块的边界

文档强调实现不得在每个渲染器留一套交叉算法、在check-render-output.mjs再留一套——lifecycle 曲线案例已经证明这种安排不一致。合适的边界是一个纯共享模块，它接收语义路由记录与类型化帧，返回回执，并负责：

• M/L/H/V/Q/Z的 SVG 路径分词与展平；
• 路径骨架归一化；
• 线段交叉与重叠分类；
• 帧边框分析；
• 度量聚合与确定性诊断；
• 档位严重度映射。

每个渲染器只需提供最终渲染的d、未取整的路由点、语义端点 ID、集合/索引/ID、路由角色与类型化帧。同一模块可在写入前运行；writeDiagram()应把回执作为转义 JSON 嵌入一个不可执行的<script type="application/json">块。从 cli.mjs 的writeDiagram()（L53 起）看，它目前通过applyTemplate组装独立 HTML，并已支持meta.quality_profile（见svgRootAttrs()L149 起的data-quality-profile与data-quality-gates属性），为嵌入回执预留了明确的落点。

check-render-output.mjs则应解析并校验该回执，只独立确认廉价的工件不变量（单一 SVG、有限标记、语义路径计数、回执 schema/版本），不重新实现完整几何引擎；若需要更强的防篡改能力，可在回执中加入规范语义路径/帧记录的确定性摘要。

CLI、Gallery 与布局报告的集成方式

CLI

• archify validate <type> <input> --json对全部五种类型返回checks外加compositionReceipt。
• 人类可读输出形如ok workflow ... (artifact 5/5; composition standard: 0 errors, 2 warnings)。
• 新增--quality standard|showcase；显式 CLI 选择覆盖meta.quality_profile，否则默认standard。
• showcase错误非零退出，打印稳定代码、两条关系身份、点/线段/帧几何与渲染器专属修复提示。
• 通用化仅限 architecture 的inspect有价值但不应阻塞本回执，validate --json才是跨渲染器的交付面。

从 SKILL.md 的实际工作流看，这一契约已经落地并被严格使用：作者路径要求node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json，且"只有 4 项工件检查的回执只是基础校验，绝不等于 showcase 验收；showcase 通过必须报告全部 9 项工件检查、0 构图错误与 0 警告"。最终交付命令为node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json（详见 delivery-contract.md）。

Gallery

• 把完整紧凑回执或其摘要/度量存入 docs/gallery/manifest.json，与哈希及工件检查并列。
• 用Artifact 5/5与Composition SHOWCASE · PASS取代含糊的4/4 pass声明。
• 若仍有警告，显示PASS · 2 notes，而不是虚假的全绿标签。
• 详细问题放在可访问的披露区或来源/manifest 链接中，不在图上新增常驻面板。
• Gallery 生成在以下情况必须失败：配置为showcase的工件存在构图错误，或存储的回执计数与当前检查器契约不匹配。

既有布局报告

不要在这一切片里通过复制五个渲染器专属对象序列化器来扩充 layout-report.mjs。两者分工明确：布局报告回答"渲染器把东西放在哪里"，构图回执回答"最终可见构图包含哪些质量信号"。它们以后可以共享路由记录类型，但当前分开，避免把 architecture 的 inspect schema 变成 sequence 与 lifecycle 的事实契约。

诊断格式：紧凑且可操作

诊断必须同时包含稳定代码与严重度、档位与图表类型、关系集合/索引/ID/from/to、另一关系或帧身份（如适用）、点/线段索引/重叠长度/测量比值、生效预算与路由类别，以及一个具体受支持的修复旋钮。原文档的三个示例：

[composition/proper-crossing] showcase architecture connections[6] "api_a" -> "events" crosses connections[9] "postgres" -> "replica" at [1000, 276] (segments 2/1). Move a via point or use separate boundary corridors. [composition/container-border-run] standard dataflow flows[0] id "web-clickstream" "web" -> "edge" overlaps stage "01 / Sources" right border for 114px at x=184. Move via/channelX into the 47px inter-stage corridor. [composition/stretch-budget] warning workflow edges[3] "contain" -> "recover" stretch 1.91 (suggested 1.35 for showcase direct routes). This bottom-channel route remains valid; move the nodes or select standard if the detour is intentional.

这在现有源码中有直接对应：例如 geometry.mjs 的cleanCrossingProblems()在 showcase 档位产生[composition/proper-crossing]消息（qualityProfileForGate()只在showcase时放行），cleanBorderRunProblems()产生[composition/container-border-run]，routeBudgetMetrics()提供拉伸与弯折数据，cleanLabelRouteClearanceProblems()则指导使用labelAt、labelDx、labelDy、labelSegment等标签修复旋钮。

十二项必需的反误报豁免

原文档明确列出回执实现必须遵守的反误报规则（完整继承）：

1. 共享语义源或目标的关系，不因其端点坐标相同而被判 proper-crossing 错误。
2. 共享通道保持为度量，不推断 junction 或桥接。
3. T 触不是 proper X，在显式 junction 语义出现前只告警。
4. 关系可以在入口/出口点穿越 architecture 边界、workflow 泳道/分组、dataflow 阶段、sequence 帧与 lifecycle 色带。
5. 序列消息穿越生命线不是关系交叉。
6. 生命线、激活条、lifecycle 轨道、边框、图例箭头、动画回显与发光/描边层都不是业务关系。
7. 自环没有普通直接距离的拉伸预算。
8. 反馈、恢复与显式走廊路径保留度量，但可使用渲染器专属的建议拉伸预算。
9. 重复或共线途经点不产生弯折，也不产生零长度短线段。
10. 曲线相交必须使用可见曲线本身，而非仅其端点或原始尖角。
11. 所有坐标必须在比较前解析到同一 SVG 用户空间，transforms 与 viewBox 缩放不得混用。
12. 圆角帧的角弧在半径附近不应被建模为完整矩形边框线。

第 10 条正是 lifecycle 四叉交叉案例的核心教训；第 12 条与 geometry.mjs 中frameBorderSegments()对圆角半径的裁剪逻辑一致。

实施顺序与测试计划

实施顺序（七步）

1. 降级当前无条件的 proper-crossing 实验：保留其有用的 proper 相交原语，但通过档位严重度映射，而不是把每个命中都加入渲染器problems。
2. 抽取共享可见路径构图几何：替换渲染器/检查器中重复的交叉计算，加入曲线、触、重叠、语义端点与类型化帧记录。
3. 在全部五个渲染器中生成结构化回执：通过writeDiagram()嵌入，通过validate --json暴露。
4. 修复已知 showcase 欠账而非将其祖父化：在规范来源中清除四处无关 X 交叉与两处边框运行，保留来源意图与命名视图。
5. 添加度量而不过度设闸：把 13 对共享通道、8 条超过两弯折的路径、4 条拉伸 >1.35 的路径与 5 条 <16px 线段记录为校准后的警告/度量。
6. 原子升级 Gallery 回执：加入构图档位/状态，并在 stale 检查器/manifest 契约时使生成失败。
7. 在内置浏览器中视觉验证：检查每条修复后的路由，再检查 Gallery 呈现与响应式回执行为。

测试计划要点

• 共享几何单元测试：proper 正交 X、对角线/曲线 X、两个曲线角 X 夹具；端点触、T 触、平行不相交、共线触、正共线重叠；同坐标/无共享 ID 不豁免；共享源、共享目标、共享源-目标通道；重复与共线途经点归一化；弯折数与 Manhattan 拉伸（含零分母自环）；矩形边框穿越与正边框运行（含圆角）；确定性问题排序与序列化。
• 渲染器夹具：architecture/workflow/dataflow/lifecycle 各一个刻意 proper 交叉；sequence 消息保持有序且生命线交叉豁免；圆角 lifecycle 曲线交叉在写入前后被一致捕获；合法的边界/泳道/阶段/帧进出；architecture 与 dataflow 各一个 route-on-border 失败；共享分支/合并通道接受并给出度量；装饰与图例箭头永不增加关系计数。
• 语料与 CLI 验收：11 个规范来源语义关系计数一致；路由修复后 showcase 在官方 Gallery 上零无关 proper X、零边框运行；初始回执基线保留 13 对共享通道、8 条 >2 弯折、4 条 >1.35 拉伸与 5 条 <16px 线段（除非定向修复刻意改变）；默认standard对仅告警夹具零退出；showcase对 proper X/无关重叠/边框运行夹具非零退出；渲染器回执、嵌入回执、CLI JSON、检查器结果与 Gallery manifest 在规范回执摘要上逐字节一致；Gallery 构建拒绝 stale 检查计数或回执 schema 版本。

值得对照的是，当前 docs/gallery/manifest.json 的每个条目已经记录了 9 项检查（single_svg、finite_svg、orthogonal_arrows、label_route_clearance、relationship_crossings、relationship_corridors、container_border_runs、route_rhythm、legend_clearance）与完整的composition回执——这正是"检查器契约变更后回执与 manifest 必须原子一致"在代码库中已落地的证据。

内置浏览器验收

文档要求在桌面 1280×720 与移动 390×844 下完成六项检查：

1. 打开 Gallery，确认每张卡片区分工件检查与构图档位/状态且不截断主操作。
2. 打开四个原交叉工件与两个原边框运行工件，在普通视图与命名故事视图下确认独立走廊与箭头方向/标签保留。
3. 对每个渲染器至少一个工件切换暗/亮主题、焦点、路由追踪、演示与引导播放，确认几何与回执状态不随查看器状态改变。
4. 确认告警详情披露键盘可达，且不覆盖 SVG 或放大冷工件架。
5. 确认移动端无水平溢出、无回执文本裁剪、无浏览器控制台错误、settled flow 后无持续动画。
6. 导出 SVG/PNG，确认质量 UI/回执脚本不成为可见图表内容。

这与 delivery-contract.md 中的视觉验收纪律一脉相承：确定性交付证明的是"字节一致"，自动化浏览器证据证明的是"真实浏览器行为"，感知层视觉审阅则需要真人或具备读图能力的评审者，三者互相独立、不得互相冒用。

成功标准与设计取舍

Round 44 的成功标准是一句话（原文引用）：每个工件都携带确定性的构图回执；安全缺陷永远失败；精修 showcase 缺陷按档位失败；合法的共享与渲染器专属几何作为证据保留可见，而不是被猜测掉。

这一设计同时改善美感与稳定性：规范路由变得更干净，质量门禁不再以遗漏的方式撒谎，密集的用户图则保留可行的"渲染—修复"路径。最终，正如研究文档所说，回执的价值大于"又一个视觉控制"——它把"这张图看起来乱"转译为稳定的作者修复循环，让 Gallery 的证明诚实可信，并让 Archify 可以在不拒绝合法工程拓扑的前提下收紧精修示例。

延伸阅读

• research-visual-evolution-round-44.md：本文所依据的原始研究决策文档
• geometry.mjs：共享几何引擎，含交叉、边框运行、预算度量与路由节奏的实现
• check-render-output.mjs：工件检查器，解析并独立确认回执的廉价不变量
• cli.mjs：共享 CLI 头尾，含writeDiagram()与质量档位属性输出
• layout-report.mjs：architecture 专属布局序列化，与构图回执保持分离
• SKILL.md：作者工作流中对--quality showcase与 9 项检查的验收要求
• delivery-contract.md：交付、视觉证据与感知审阅的三层契约
• docs/gallery/manifest.json：构图回执在真实 Gallery 条目中的落地样例
• common.schema.json：qualityProfile枚举定义（standard/showcase）

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