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 交叉工件左侧关系右侧关系可见交叉点Production Deployment Ownershipapi_a - eventspostgres - replica[1000, 276]Incident Response Runbooktriage - containdeclare - update[356, 290]Order Event-stream Topologyenrich - statevalidate - dlq[610, 385]Agent Run Lifecycleexecuting - failedapproval - cancelled约[322.1, 339]前三处存在于正交路径骨架中而 lifecycle 交叉是由两个圆角二次曲线Q 曲线引入的渲染器侧的 raw-polyline 校验接受它渲染后的可见路径检查却拒绝它。这是两份独立实现的交叉计算必然漂移的直接证据——可见构图必须基于最终路径图元包括曲线来评估。同时docs/gallery/manifest.json 仍声称 44 项旧检查全部通过而新的五合一检查器却拒绝了四个已存储工件。这说明未来的回执必须原子地生成与消费避免检查器契约变更后 Gallery 仍然展示过期的全绿声明。语料基线哪些信号该是硬错误、哪些该是度量研究对 111 条业务关系排除图例箭头、lifecycle 轨道、生命线、动画回显与装饰形状做了审计圆角路径按确定性容差展平以分析可见交叉弯折与线段度量则从路径骨架恢复并归一化掉重复与共线途经点。基线数据如下信号当前语料解读无关 proper X 交叉4 对关系真实的 showcase 欠账但不证明每种工程拓扑都必须平面化共享端点共线通道对13多数是刻意的分支/合并路由无条件禁止重叠会误伤弯折超过 2 次的关系8均为 3 弯折有用的压力信号不是普遍的正确性失败单条关系最大弯折数3有界的小额欠账无阶梯式爆炸拉伸比高于 1.35 的路径4含合法的底部/反馈走廊需要路由类别上下文最大 Manhattan 拉伸2.34approval - cancelled作者刻意的恢复绕行正向骨架线段低于 16px5最小 13px端点 stub在确定渲染器专属下限前先告警与结构框边框共线的路径2机械意义上无歧义的视觉缺陷两条边框运行路径是具体的Product Analytics 的web - edge沿 Sources 阶段右边框x184运行了 114pxWeb App 的auth - api沿安全分组顶边框y270运行了 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 分。Graphvizsplines文档明确样条绕开节点但不承诺零边边交叉concentrate刻意合并多重边并允许部分平行关系共享路径samehead/sametail允许边指向公共头/尾点。借用节点避让是安全、交叉消减是构图的二分适配共享语义源/目标通道的分类跳过每个共线重叠或公共端点都是意外。ELK/LibavoidELK Layered 通过重排节点最小化交叉再计算弯折点支持端口、多重边、复合图与 junction 输出Libavoid 的 shared-endpoint nudging 默认分离公共端点中间路径但允许整体共享路径重叠Junction Points 是正交超边的显式输出而非从几何接触推断Cluster Crossing Penalty 把边界穿越当作可配置的路由代价而非无条件错误。借用显式问题类别与 junction 语义适配当前只有边框共线在 Archify 中是普遍错误必要的垂直穿越容器仍合法跳过从 T 触或坐标巧合猜测 junction。D2其 ELK 对比文档承认正交路径虽有干净的绕障与交叉最小化但也会产生不必要弯折序列图规则赋予消息顺序、生命线、激活跨度、分组与自消息专门语义。借用在保留渲染器语义的前提下评估最终路径适配序列消息是普通回执关系但生命线、激活条与帧不是业务边自消息没有普通拉伸分母跳过把同一个几何阈值盲目套到每条可见线上。Structurizr 与 LikeC4Structurizr 在自动布局不够好时明确建议回到手动模式作者可增删关系顶点、移动标签、切换直连/正交/曲线路由LikeC4 的 Graphviz 打印器与 AI 布局提示要求最小化交叉、偏好平衡更直的边但不会把剩余交叉重新定义为无效模型内容。借用每个问题都必须指向一个作者可控制的修复旋钮适配指向via、route、fromSide、toSide、通道坐标、行列摆放或档位选择跳过静默修改作者 JSON 或用桥接装饰隐藏未解路由。双层契约两个质量档位与严重度矩阵Round 44 的最终决策是不要把每个几何边交叉都升级为无条件布局错误保留 Round 43 的 edge-through-unrelated-node 作为通用安全门把 route-on-container-border 提升为第二个通用硬错误其余构图信号按档位分类为错误、警告或度量。产品一句话可概括为Archify 告诉作者一个图是否安全、是否精修以及具体是哪条路由决策使它无法进入下一个质量档位。档位定义档位适用场景退出行为standard默认真实工程图与向后兼容渲染安全错误失败构图问题告警并保持机器可读showcase显式选择官方 Gallery 场景、README 头图工件、精修交付安全错误、无关 proper X 交叉、无关共线重叠与边框运行失败校准后的路由预算问题在 v1 中告警研究文档明确反对仅为逃生而增加stress档位现有standard已能支撑密集工程图未来的压力语料可以作为测试套件分类而不必成为公开 JSON API。这一点与 common.schema.json 中qualityProfile枚举[standard, showcase]完全一致。严重度矩阵代码分类standardshowcase理由safety/edge-through-node无关关系穿过语义节点errorerrorRound 43 机械意义上无歧义的不变量safety/non-finite-path不可用的路径坐标errorerror无效工件composition/container-border-run业务路径与结构边框共线超过容差errorerror业务与分组语义在视觉上不可区分composition/proper-crossing无共享语义端点的 proper 内部 Xwarningerror复杂图中合法显式精修档位不可接受composition/unrelated-overlap无共享语义端点的正长度共线重叠warningerror可能意外但 standard 不得猜测未声明的 junctioncomposition/touch无显式 junction 的端点/T 触warningwarning在 junction 语义出现前是歧义的composition/shared-channel共享语义源/目标的正面重叠metricmetricGraphviz/ELK 表明它可能是刻意的composition/stacked-arrowhead多个业务箭头在同一端点坐标warningwarningFireworks 拒绝但 Archify 目前缺乏端口偏移控制composition/bend-budget归一化方向变化超过建议预算warningwarning语料中 8 条真实路径合法地使用 3 弯折composition/stretch-budget路径/直接 Manhattan 比超过建议预算warningwarning反馈与底部走廊需要路由类别上下文composition/short-segment归一化正线段低于建议预算warningwarning端点 stub 需要渲染器校准composition/boundary-crossing-count必需的帧进出次数metricmetric穿越容器本身不是缺陷研究文档同时给出升级路径当显式port、junction与路由角色语义出现后Archify 可以把未声明触与堆叠箭头提升为showcase错误在此之前贸然升级等于把校验器变成死胡同。归一化与测量规则共享几何引擎的十一条契约回执的准确性依赖一组无歧义的测量规则文档原文共 11 条全部继承如下只有带稳定from、to、集合索引与可选id的语义关系才进入回执。装饰、发光/描边回显、lifecycle 轨道、生命线、激活条、分段帧、图例与查看器覆盖层按语义角色排除而非按 CSS 类名猜测。保留最终路径图元。在确定性容差下展平Q曲线用于交叉分析但不要用弦代替曲线。从路径骨架恢复弯折与线段。移除连续重复点并折叠共线途经点。弯折是真实的方向变化圆角控制点不增加弯折数。proper 交叉要求两条路径内部真正相交坐标是任一线段端点的相交属于 touch不是 proper 交叉。共享端点豁免要求两条关系共享同一语义节点 ID仅坐标相等永不构成豁免。共线正长度相交是重叠并保留其总重叠长度按语义端点分类为 shared 或 unrelated。拉伸 路径 Manhattan 长度 ÷ 端点直接 Manhattan 长度。自环或零分母返回null而非无穷。归一化后只统计正线段报告最小线段长度及其所属关系/线段。结构帧是类型化的architecture 边界、workflow 泳道/分组、dataflow 阶段、sequence 分段、lifecycle 分隔符/色带。只有帧边框上的正长度共线运行是硬缺陷点状进出仍属于度量。内部保留精确测量值仅序列化展示值四舍五入问题按严重度、代码、关系集合/索引、另一关系索引与线段索引排序保证输出确定性。从 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 typeapplication/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 与布局报告的集成方式CLIarchify 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 x184. 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等标签修复旋钮。十二项必需的反误报豁免原文档明确列出回执实现必须遵守的反误报规则完整继承共享语义源或目标的关系不因其端点坐标相同而被判 proper-crossing 错误。共享通道保持为度量不推断 junction 或桥接。T 触不是 proper X在显式 junction 语义出现前只告警。关系可以在入口/出口点穿越 architecture 边界、workflow 泳道/分组、dataflow 阶段、sequence 帧与 lifecycle 色带。序列消息穿越生命线不是关系交叉。生命线、激活条、lifecycle 轨道、边框、图例箭头、动画回显与发光/描边层都不是业务关系。自环没有普通直接距离的拉伸预算。反馈、恢复与显式走廊路径保留度量但可使用渲染器专属的建议拉伸预算。重复或共线途经点不产生弯折也不产生零长度短线段。曲线相交必须使用可见曲线本身而非仅其端点或原始尖角。所有坐标必须在比较前解析到同一 SVG 用户空间transforms 与 viewBox 缩放不得混用。圆角帧的角弧在半径附近不应被建模为完整矩形边框线。第 10 条正是 lifecycle 四叉交叉案例的核心教训第 12 条与 geometry.mjs 中frameBorderSegments()对圆角半径的裁剪逻辑一致。实施顺序与测试计划实施顺序七步降级当前无条件的 proper-crossing 实验保留其有用的 proper 相交原语但通过档位严重度映射而不是把每个命中都加入渲染器problems。抽取共享可见路径构图几何替换渲染器/检查器中重复的交叉计算加入曲线、触、重叠、语义端点与类型化帧记录。在全部五个渲染器中生成结构化回执通过writeDiagram()嵌入通过validate --json暴露。修复已知 showcase 欠账而非将其祖父化在规范来源中清除四处无关 X 交叉与两处边框运行保留来源意图与命名视图。添加度量而不过度设闸把 13 对共享通道、8 条超过两弯折的路径、4 条拉伸 1.35 的路径与 5 条 16px 线段记录为校准后的警告/度量。原子升级 Gallery 回执加入构图档位/状态并在 stale 检查器/manifest 契约时使生成失败。在内置浏览器中视觉验证检查每条修复后的路由再检查 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 下完成六项检查打开 Gallery确认每张卡片区分工件检查与构图档位/状态且不截断主操作。打开四个原交叉工件与两个原边框运行工件在普通视图与命名故事视图下确认独立走廊与箭头方向/标签保留。对每个渲染器至少一个工件切换暗/亮主题、焦点、路由追踪、演示与引导播放确认几何与回执状态不随查看器状态改变。确认告警详情披露键盘可达且不覆盖 SVG 或放大冷工件架。确认移动端无水平溢出、无回执文本裁剪、无浏览器控制台错误、settled flow 后无持续动画。导出 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.mjsarchitecture 专属布局序列化与构图回执保持分离SKILL.md作者工作流中对--quality showcase与 9 项检查的验收要求delivery-contract.md交付、视觉证据与感知审阅的三层契约docs/gallery/manifest.json构图回执在真实 Gallery 条目中的落地样例common.schema.jsonqualityProfile枚举定义standard/showcase【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 4:50:12 · 阅读 1.2k 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 交叉工件左侧关系右侧关系可见交叉点Production Deployment Ownershipapi_a - eventspostgres - replica[1000, 276]Incident Response Runbooktriage - containdeclare - update[356, 290]Order Event-stream Topologyenrich - statevalidate - dlq[610, 385]Agent Run Lifecycleexecuting - failedapproval - cancelled约[322.1, 339]前三处存在于正交路径骨架中而 lifecycle 交叉是由两个圆角二次曲线Q 曲线引入的渲染器侧的 raw-polyline 校验接受它渲染后的可见路径检查却拒绝它。这是两份独立实现的交叉计算必然漂移的直接证据——可见构图必须基于最终路径图元包括曲线来评估。同时docs/gallery/manifest.json 仍声称 44 项旧检查全部通过而新的五合一检查器却拒绝了四个已存储工件。这说明未来的回执必须原子地生成与消费避免检查器契约变更后 Gallery 仍然展示过期的全绿声明。语料基线哪些信号该是硬错误、哪些该是度量研究对 111 条业务关系排除图例箭头、lifecycle 轨道、生命线、动画回显与装饰形状做了审计圆角路径按确定性容差展平以分析可见交叉弯折与线段度量则从路径骨架恢复并归一化掉重复与共线途经点。基线数据如下信号当前语料解读无关 proper X 交叉4 对关系真实的 showcase 欠账但不证明每种工程拓扑都必须平面化共享端点共线通道对13多数是刻意的分支/合并路由无条件禁止重叠会误伤弯折超过 2 次的关系8均为 3 弯折有用的压力信号不是普遍的正确性失败单条关系最大弯折数3有界的小额欠账无阶梯式爆炸拉伸比高于 1.35 的路径4含合法的底部/反馈走廊需要路由类别上下文最大 Manhattan 拉伸2.34approval - cancelled作者刻意的恢复绕行正向骨架线段低于 16px5最小 13px端点 stub在确定渲染器专属下限前先告警与结构框边框共线的路径2机械意义上无歧义的视觉缺陷两条边框运行路径是具体的Product Analytics 的web - edge沿 Sources 阶段右边框x184运行了 114pxWeb App 的auth - api沿安全分组顶边框y270运行了 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 分。Graphvizsplines文档明确样条绕开节点但不承诺零边边交叉concentrate刻意合并多重边并允许部分平行关系共享路径samehead/sametail允许边指向公共头/尾点。借用节点避让是安全、交叉消减是构图的二分适配共享语义源/目标通道的分类跳过每个共线重叠或公共端点都是意外。ELK/LibavoidELK Layered 通过重排节点最小化交叉再计算弯折点支持端口、多重边、复合图与 junction 输出Libavoid 的 shared-endpoint nudging 默认分离公共端点中间路径但允许整体共享路径重叠Junction Points 是正交超边的显式输出而非从几何接触推断Cluster Crossing Penalty 把边界穿越当作可配置的路由代价而非无条件错误。借用显式问题类别与 junction 语义适配当前只有边框共线在 Archify 中是普遍错误必要的垂直穿越容器仍合法跳过从 T 触或坐标巧合猜测 junction。D2其 ELK 对比文档承认正交路径虽有干净的绕障与交叉最小化但也会产生不必要弯折序列图规则赋予消息顺序、生命线、激活跨度、分组与自消息专门语义。借用在保留渲染器语义的前提下评估最终路径适配序列消息是普通回执关系但生命线、激活条与帧不是业务边自消息没有普通拉伸分母跳过把同一个几何阈值盲目套到每条可见线上。Structurizr 与 LikeC4Structurizr 在自动布局不够好时明确建议回到手动模式作者可增删关系顶点、移动标签、切换直连/正交/曲线路由LikeC4 的 Graphviz 打印器与 AI 布局提示要求最小化交叉、偏好平衡更直的边但不会把剩余交叉重新定义为无效模型内容。借用每个问题都必须指向一个作者可控制的修复旋钮适配指向via、route、fromSide、toSide、通道坐标、行列摆放或档位选择跳过静默修改作者 JSON 或用桥接装饰隐藏未解路由。双层契约两个质量档位与严重度矩阵Round 44 的最终决策是不要把每个几何边交叉都升级为无条件布局错误保留 Round 43 的 edge-through-unrelated-node 作为通用安全门把 route-on-container-border 提升为第二个通用硬错误其余构图信号按档位分类为错误、警告或度量。产品一句话可概括为Archify 告诉作者一个图是否安全、是否精修以及具体是哪条路由决策使它无法进入下一个质量档位。档位定义档位适用场景退出行为standard默认真实工程图与向后兼容渲染安全错误失败构图问题告警并保持机器可读showcase显式选择官方 Gallery 场景、README 头图工件、精修交付安全错误、无关 proper X 交叉、无关共线重叠与边框运行失败校准后的路由预算问题在 v1 中告警研究文档明确反对仅为逃生而增加stress档位现有standard已能支撑密集工程图未来的压力语料可以作为测试套件分类而不必成为公开 JSON API。这一点与 common.schema.json 中qualityProfile枚举[standard, showcase]完全一致。严重度矩阵代码分类standardshowcase理由safety/edge-through-node无关关系穿过语义节点errorerrorRound 43 机械意义上无歧义的不变量safety/non-finite-path不可用的路径坐标errorerror无效工件composition/container-border-run业务路径与结构边框共线超过容差errorerror业务与分组语义在视觉上不可区分composition/proper-crossing无共享语义端点的 proper 内部 Xwarningerror复杂图中合法显式精修档位不可接受composition/unrelated-overlap无共享语义端点的正长度共线重叠warningerror可能意外但 standard 不得猜测未声明的 junctioncomposition/touch无显式 junction 的端点/T 触warningwarning在 junction 语义出现前是歧义的composition/shared-channel共享语义源/目标的正面重叠metricmetricGraphviz/ELK 表明它可能是刻意的composition/stacked-arrowhead多个业务箭头在同一端点坐标warningwarningFireworks 拒绝但 Archify 目前缺乏端口偏移控制composition/bend-budget归一化方向变化超过建议预算warningwarning语料中 8 条真实路径合法地使用 3 弯折composition/stretch-budget路径/直接 Manhattan 比超过建议预算warningwarning反馈与底部走廊需要路由类别上下文composition/short-segment归一化正线段低于建议预算warningwarning端点 stub 需要渲染器校准composition/boundary-crossing-count必需的帧进出次数metricmetric穿越容器本身不是缺陷研究文档同时给出升级路径当显式port、junction与路由角色语义出现后Archify 可以把未声明触与堆叠箭头提升为showcase错误在此之前贸然升级等于把校验器变成死胡同。归一化与测量规则共享几何引擎的十一条契约回执的准确性依赖一组无歧义的测量规则文档原文共 11 条全部继承如下只有带稳定from、to、集合索引与可选id的语义关系才进入回执。装饰、发光/描边回显、lifecycle 轨道、生命线、激活条、分段帧、图例与查看器覆盖层按语义角色排除而非按 CSS 类名猜测。保留最终路径图元。在确定性容差下展平Q曲线用于交叉分析但不要用弦代替曲线。从路径骨架恢复弯折与线段。移除连续重复点并折叠共线途经点。弯折是真实的方向变化圆角控制点不增加弯折数。proper 交叉要求两条路径内部真正相交坐标是任一线段端点的相交属于 touch不是 proper 交叉。共享端点豁免要求两条关系共享同一语义节点 ID仅坐标相等永不构成豁免。共线正长度相交是重叠并保留其总重叠长度按语义端点分类为 shared 或 unrelated。拉伸 路径 Manhattan 长度 ÷ 端点直接 Manhattan 长度。自环或零分母返回null而非无穷。归一化后只统计正线段报告最小线段长度及其所属关系/线段。结构帧是类型化的architecture 边界、workflow 泳道/分组、dataflow 阶段、sequence 分段、lifecycle 分隔符/色带。只有帧边框上的正长度共线运行是硬缺陷点状进出仍属于度量。内部保留精确测量值仅序列化展示值四舍五入问题按严重度、代码、关系集合/索引、另一关系索引与线段索引排序保证输出确定性。从 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 typeapplication/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 与布局报告的集成方式CLIarchify 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 x184. 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等标签修复旋钮。十二项必需的反误报豁免原文档明确列出回执实现必须遵守的反误报规则完整继承共享语义源或目标的关系不因其端点坐标相同而被判 proper-crossing 错误。共享通道保持为度量不推断 junction 或桥接。T 触不是 proper X在显式 junction 语义出现前只告警。关系可以在入口/出口点穿越 architecture 边界、workflow 泳道/分组、dataflow 阶段、sequence 帧与 lifecycle 色带。序列消息穿越生命线不是关系交叉。生命线、激活条、lifecycle 轨道、边框、图例箭头、动画回显与发光/描边层都不是业务关系。自环没有普通直接距离的拉伸预算。反馈、恢复与显式走廊路径保留度量但可使用渲染器专属的建议拉伸预算。重复或共线途经点不产生弯折也不产生零长度短线段。曲线相交必须使用可见曲线本身而非仅其端点或原始尖角。所有坐标必须在比较前解析到同一 SVG 用户空间transforms 与 viewBox 缩放不得混用。圆角帧的角弧在半径附近不应被建模为完整矩形边框线。第 10 条正是 lifecycle 四叉交叉案例的核心教训第 12 条与 geometry.mjs 中frameBorderSegments()对圆角半径的裁剪逻辑一致。实施顺序与测试计划实施顺序七步降级当前无条件的 proper-crossing 实验保留其有用的 proper 相交原语但通过档位严重度映射而不是把每个命中都加入渲染器problems。抽取共享可见路径构图几何替换渲染器/检查器中重复的交叉计算加入曲线、触、重叠、语义端点与类型化帧记录。在全部五个渲染器中生成结构化回执通过writeDiagram()嵌入通过validate --json暴露。修复已知 showcase 欠账而非将其祖父化在规范来源中清除四处无关 X 交叉与两处边框运行保留来源意图与命名视图。添加度量而不过度设闸把 13 对共享通道、8 条超过两弯折的路径、4 条拉伸 1.35 的路径与 5 条 16px 线段记录为校准后的警告/度量。原子升级 Gallery 回执加入构图档位/状态并在 stale 检查器/manifest 契约时使生成失败。在内置浏览器中视觉验证检查每条修复后的路由再检查 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 下完成六项检查打开 Gallery确认每张卡片区分工件检查与构图档位/状态且不截断主操作。打开四个原交叉工件与两个原边框运行工件在普通视图与命名故事视图下确认独立走廊与箭头方向/标签保留。对每个渲染器至少一个工件切换暗/亮主题、焦点、路由追踪、演示与引导播放确认几何与回执状态不随查看器状态改变。确认告警详情披露键盘可达且不覆盖 SVG 或放大冷工件架。确认移动端无水平溢出、无回执文本裁剪、无浏览器控制台错误、settled flow 后无持续动画。导出 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.mjsarchitecture 专属布局序列化与构图回执保持分离SKILL.md作者工作流中对--quality showcase与 9 项检查的验收要求delivery-contract.md交付、视觉证据与感知审阅的三层契约docs/gallery/manifest.json构图回执在真实 Gallery 条目中的落地样例common.schema.jsonqualityProfile枚举定义standard/showcase【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考