Easydict 仓库中的 Fireworks Tech GraphSVG 技术图示视觉质量与精确文本校验指南【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict导读Fireworks Tech Graph 是随 Easydict 仓库一并维护的一套可移植 Agent Skill位于 .agents/skills/fireworks-tech-graph用于生成架构图、UML、Agent 关系图、云拓扑与工作流等精确的 SVG 技术图示并支持导出 PNG、离线 HTML 与 GIF 动图。本指南以其配套参考文档 visual-quality.md 为核心讲解两件决定图示成败的事视觉可读性readability与文本完整性text completeness并延伸到统一导出命令export-png与夹具驱动的验证体系。读完本文你将掌握如何度量文字对比度、识别并修复截断文本、理解text_policy: strict的语义以及如何在导出位图前完成可复现的视觉核验——而不是把命令成功执行误当成图质量合格。图同一场景在 12 种样式下的成品对比仓库 fixtures/quality-baseline 以同一拓扑驱动 11 个生成器样式是判断样式签名是否被保留的直观参照。一、可读性在保留样式签名的基础上强化文字对比文档的第一条原则是生成器必须保留每个样式自身的调色板、材质、圆角、描边与动效签名palette, material, radius, stroke, motion质量修正只能加料不能换皮。1.1 对比度目标4.5:1 的度量口径与边界scripts/style_quality.py负责在默认不透明画布上强化辅助文字使其逼近4.5:1 的对比度目标对应 WCAG AA 的普通文本阈值。需要强调的是文档明确标注的口径边界这是token 级token-level的度量针对的是默认不透明画布上的文字 token它不是对自定义填充、半透明玻璃面板glass、字号或每个像素的认证最终判断仍须在预期的阅读尺寸下检查实际光栅图Inspect the final raster at the intended reading size。源码 style_quality.py 中contrast_ratio()严格按 WCAG 相对亮度公式实现先校验颜色必须是六位不透明十六进制#[0-9a-fA-F]{6}否则抛ValueError再把 sRGB 值按v/12.92线性段或((v 0.055) / 1.055) ** 2.4指数段线性化最后以(0.2126, 0.7152, 0.0722)加权求和得到亮度计算对比度(max 0.05) / (min 0.05)。palette_report()会针对text_primary、text_secondary、text_muted、section_sub_fill四类 token 逐一计算相对背景的对比度并输出scope明确声明是default opaque canvas text tokens; not a full rendered accessibility audit默认不透明画布文字 token而非完整渲染可访问性审计minimum_target: 4.5below_target低于 4.5 的 token 清单unsupported_tokens无法度量如非不透明颜色的 token。1.2 样式专项检查清单文档按样式给出了各自的可读性检查重点这是生成后逐项核验的实操清单样式检查重点Flat Icon / Notion / OpenAI保留安静的留白图注与区块标签必须可读不要用近乎不可见的浅灰Dark Terminal / Ops Pulse保留强调色编码的路由与深色表面提升辅助文字而非提高光晕强度状态要同时靠文字和颜色可辨识Blueprint保留工程网格、青色线稿与图签细节registration detailsGlassmorphism保留面板半透明文字必须在合成后的面板上实测Claude保留暖纸色与棕色层级次级文字要可读C4 Review Canvas保留职责与协议中英文两行描述都要用绝不隐藏关键职责Cloud Fabric保留 region/VPC 嵌套强化归属标签而不引入竞争性连接线颜色Event Transit保留路由方向、站点顺序与独立的 DLQDark Luxury保留 AI 创作的克制金/衬线排版精确文本、几何与视觉检查与生成样式同等适用从style_quality.py的READABILITY_TOKENS字典可以看到具体修正值例如Style 1Flat Icontext_muted提到#64748bStyle 2Dark Terminaltext_muted提到#94a3b8Style 6Claudetext_muted提到#75695dStyle 7OpenAItext_muted提到#64748bsection_label_fill使用强调色#087f5bStyle 12Ops Pulsetext_muted提到#8fa8bf。注意该字典覆盖 1、2、4、6、7、9、10、11、12 号样式Blueprint(3)、Glassmorphism(5) 不在此列前者依赖几何网格本身后者必须走合成面板上实测的路线Dark Luxury(8) 为 AI 手写 SVG 特例。这些修正只动小号辅助文字不改变每个主题的色相、材质、连接线与签名。二、文本完整性截断检测、全文保留与 strict 策略2.1 layout.json.typography 报告渲染时通过--report layout.json生成的报告中typography字段会报告可见截断visible truncation哪些文本被省略号截断完整源文本full source copy原始完整文案恢复提示recovery hint修复方向建议。对应实现text_quality_report()位于 style_quality.py遍历 SVG 中所有text元素若某元素带data-full-text属性、可见文本以…结尾且不等于完整文本则判定为截断并输出该文本的data-text-role、完整文本、可见文本与字号。complete_text字段汇总是否存在任何截断。2.2>python3 scripts/fireworks.py export-png diagram.svg diagram.png --width 1920源码 png_export.py 的实现细节印证了文档的稳妥承诺尺寸校验宽度必须是 132768 的整数高度按画布宽高比推导且总像素不超过6400 万64 megapixel、单边不超过 32768px超出直接抛ValueError安全净化导出前先经过与 HTML 导出同一套sanitize_svg()拒绝外部 URL、脚本与 DTD任何渲染器都接触不到活动/外部内容渲染器回退优先 CairoSVG缺失时回退rsvg-convert两者都不可用时明确报错提示安装其一原子写入在输出目录的临时目录中渲染成功后才replace到目标路径避免半成品文件尺寸回读渲染后解析 PNG 头校验\x89PNG魔数与IHDR从字节 16–24 读回实际宽高若与请求不一致则报错——防止渲染器静默缩放。3.2 root-canvas 解析能力导出链路依赖的根画布解析器见 svg_canvas.py支持仅 viewBox 的 SVG无width/height属性时可退化为使用 viewBox 宽高小数与物理单位尺寸px、pt、pc、mm、cm、in均按因子换算如pt→96/72in→96百分比尺寸必须依赖 viewBox 视口非零 SVG 原点parse_viewbox接受任意四个有限数值含非零 min-x/min-y不会假设原点为 0而JSON 布局生成器自身固定使用原点 0 0——理解这一差异才能正确判断第三方/手写 SVG 的导出结果。3.3 导出后的双确认文档要求导出后做两件事确认 PNG 实际尺寸利用上面的尺寸回读并且检查真实文本Inspect actual text——尺寸正确不代表文字渲染正确。四、夹具驱动的质量验证identity / baseline / long-text 三层文档给出三种夹具的分工对应 fixtures 目录公开样式夹具public style fixtures——用于验证样式身份identity如mem0-style1.json、tool-call-style2.json、microservices-style3.json、multi-agent-style5.json、system-architecture-style6.json、api-flow-style7.json、dark-luxury-style8.svg、c4-review-canvas-style9.json、cloud-fabric-style10.json、event-transit-style11.json、ops-pulse-style12.json等确保每个样式的签名不被破坏共享质量基线夹具quality-baseline——fixtures/quality-baseline/agent-runtime-style{1..7,9..12}.json用同一套 Agent Runtime Architecture 拓扑驱动 11 个生成器样式用于横向对比Style 8 是唯一的静态 AI 手写例外无 JSON 生成路径这一点在command_validate中有明确注释长文本夹具/测试long-text fixtures/tests——用于回归长文案场景下的可读性仓库中对应 tests/test_quality_upgrade.py 与快照 tests/snapshots/quality-upgrade.json 等测试资产。文档在此给出一个明确的断言添加元数据或通过 XML 校验单独拿出来永远不能证明一张图在视觉上是成功的Adding metadata or passing XML checks alone never proves a visually successful diagram。元数据、data-full-text、几何校验都是必要条件但不是充分条件。五、完整校验管线把视觉质量装进工作流visual-quality.md定位是渲染/校验管线的视觉层闸门。将其与 SKILL.md 的 CLI 工作流串联一套完整流程是# 1) 校验输入 JSON 的语义与样式合法性Style 8 不接受 JSON python3 scripts/fireworks.py validate architecture input.json # 2) 渲染 SVG 并产出 layout.json 报告含 typography / palette python3 scripts/fireworks.py render architecture input.json diagram.svg --report layout.json # 3) 几何/组成校验XML、marker、collision、geometry、composition python3 scripts/fireworks.py check diagram.svg # 4) 视觉质量闸门本文主题 # - 阅读 layout.json 的 typography处理可见截断加宽/换短标签/拆分视图 # - 需要全标签精确可见时改用 text_policy: strict # - 阅读 palette对照 4.5:1 对比度目标按样式清单逐项检查 # - 参考 composition-quality-contract.md几何通过后再做视觉层验收 # 5) 导出 PNG默认 1920px含安全净化、尺寸回读与原子写入 python3 scripts/fireworks.py export-png diagram.svg diagram.png --width 1920 # 6) 在预期阅读尺寸下目检最终 PNG文字完整性、对比度、字体替换、 # 层级、间距、裁切、箭头方向、交叉与标签从源码结构看composition-quality-contract.md 与本文档是先后两道闸门几何/组成预算0 交叉、0 桥跳、单边弯折 ≤2、最短路由段 ≥16px、节点间距 ≥40px 等先行通过再应用本文档的对比度与文本完整性检查。check命令的报告里排版与调色板范围typography and palette scope值得逐字段阅读因为启发式文本宽度永远不能替代对实际渲染字体的检查。如果环境不支持查看图片则必须明确标记视觉检查已跳过绝不能声称视觉正确。失败后依据check返回的元素 ID 与几何信息做定点修复连续两次相同修复无效就更换方案——加宽/拆分过满的图而不是隐藏必要文案或无限缩小字号也不要为了通过而静默削弱语义或组成约束。一次渲染成功 ≠ PNG/GIF/HTML 包完成每个请求的本地产物及其适用检查都必须完整交付并报告文件路径、尺寸、视觉评审结论与残余限制。【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Easydict 仓库中的 Fireworks Tech Graph：SVG 技术图示视觉质量与精确文本校验指南
Easydict 仓库中的 Fireworks Tech GraphSVG 技术图示视觉质量与精确文本校验指南【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict导读Fireworks Tech Graph 是随 Easydict 仓库一并维护的一套可移植 Agent Skill位于 .agents/skills/fireworks-tech-graph用于生成架构图、UML、Agent 关系图、云拓扑与工作流等精确的 SVG 技术图示并支持导出 PNG、离线 HTML 与 GIF 动图。本指南以其配套参考文档 visual-quality.md 为核心讲解两件决定图示成败的事视觉可读性readability与文本完整性text completeness并延伸到统一导出命令export-png与夹具驱动的验证体系。读完本文你将掌握如何度量文字对比度、识别并修复截断文本、理解text_policy: strict的语义以及如何在导出位图前完成可复现的视觉核验——而不是把命令成功执行误当成图质量合格。图同一场景在 12 种样式下的成品对比仓库 fixtures/quality-baseline 以同一拓扑驱动 11 个生成器样式是判断样式签名是否被保留的直观参照。一、可读性在保留样式签名的基础上强化文字对比文档的第一条原则是生成器必须保留每个样式自身的调色板、材质、圆角、描边与动效签名palette, material, radius, stroke, motion质量修正只能加料不能换皮。1.1 对比度目标4.5:1 的度量口径与边界scripts/style_quality.py负责在默认不透明画布上强化辅助文字使其逼近4.5:1 的对比度目标对应 WCAG AA 的普通文本阈值。需要强调的是文档明确标注的口径边界这是token 级token-level的度量针对的是默认不透明画布上的文字 token它不是对自定义填充、半透明玻璃面板glass、字号或每个像素的认证最终判断仍须在预期的阅读尺寸下检查实际光栅图Inspect the final raster at the intended reading size。源码 style_quality.py 中contrast_ratio()严格按 WCAG 相对亮度公式实现先校验颜色必须是六位不透明十六进制#[0-9a-fA-F]{6}否则抛ValueError再把 sRGB 值按v/12.92线性段或((v 0.055) / 1.055) ** 2.4指数段线性化最后以(0.2126, 0.7152, 0.0722)加权求和得到亮度计算对比度(max 0.05) / (min 0.05)。palette_report()会针对text_primary、text_secondary、text_muted、section_sub_fill四类 token 逐一计算相对背景的对比度并输出scope明确声明是default opaque canvas text tokens; not a full rendered accessibility audit默认不透明画布文字 token而非完整渲染可访问性审计minimum_target: 4.5below_target低于 4.5 的 token 清单unsupported_tokens无法度量如非不透明颜色的 token。1.2 样式专项检查清单文档按样式给出了各自的可读性检查重点这是生成后逐项核验的实操清单样式检查重点Flat Icon / Notion / OpenAI保留安静的留白图注与区块标签必须可读不要用近乎不可见的浅灰Dark Terminal / Ops Pulse保留强调色编码的路由与深色表面提升辅助文字而非提高光晕强度状态要同时靠文字和颜色可辨识Blueprint保留工程网格、青色线稿与图签细节registration detailsGlassmorphism保留面板半透明文字必须在合成后的面板上实测Claude保留暖纸色与棕色层级次级文字要可读C4 Review Canvas保留职责与协议中英文两行描述都要用绝不隐藏关键职责Cloud Fabric保留 region/VPC 嵌套强化归属标签而不引入竞争性连接线颜色Event Transit保留路由方向、站点顺序与独立的 DLQDark Luxury保留 AI 创作的克制金/衬线排版精确文本、几何与视觉检查与生成样式同等适用从style_quality.py的READABILITY_TOKENS字典可以看到具体修正值例如Style 1Flat Icontext_muted提到#64748bStyle 2Dark Terminaltext_muted提到#94a3b8Style 6Claudetext_muted提到#75695dStyle 7OpenAItext_muted提到#64748bsection_label_fill使用强调色#087f5bStyle 12Ops Pulsetext_muted提到#8fa8bf。注意该字典覆盖 1、2、4、6、7、9、10、11、12 号样式Blueprint(3)、Glassmorphism(5) 不在此列前者依赖几何网格本身后者必须走合成面板上实测的路线Dark Luxury(8) 为 AI 手写 SVG 特例。这些修正只动小号辅助文字不改变每个主题的色相、材质、连接线与签名。二、文本完整性截断检测、全文保留与 strict 策略2.1 layout.json.typography 报告渲染时通过--report layout.json生成的报告中typography字段会报告可见截断visible truncation哪些文本被省略号截断完整源文本full source copy原始完整文案恢复提示recovery hint修复方向建议。对应实现text_quality_report()位于 style_quality.py遍历 SVG 中所有text元素若某元素带data-full-text属性、可见文本以…结尾且不等于完整文本则判定为截断并输出该文本的data-text-role、完整文本、可见文本与字号。complete_text字段汇总是否存在任何截断。2.2>python3 scripts/fireworks.py export-png diagram.svg diagram.png --width 1920源码 png_export.py 的实现细节印证了文档的稳妥承诺尺寸校验宽度必须是 132768 的整数高度按画布宽高比推导且总像素不超过6400 万64 megapixel、单边不超过 32768px超出直接抛ValueError安全净化导出前先经过与 HTML 导出同一套sanitize_svg()拒绝外部 URL、脚本与 DTD任何渲染器都接触不到活动/外部内容渲染器回退优先 CairoSVG缺失时回退rsvg-convert两者都不可用时明确报错提示安装其一原子写入在输出目录的临时目录中渲染成功后才replace到目标路径避免半成品文件尺寸回读渲染后解析 PNG 头校验\x89PNG魔数与IHDR从字节 16–24 读回实际宽高若与请求不一致则报错——防止渲染器静默缩放。3.2 root-canvas 解析能力导出链路依赖的根画布解析器见 svg_canvas.py支持仅 viewBox 的 SVG无width/height属性时可退化为使用 viewBox 宽高小数与物理单位尺寸px、pt、pc、mm、cm、in均按因子换算如pt→96/72in→96百分比尺寸必须依赖 viewBox 视口非零 SVG 原点parse_viewbox接受任意四个有限数值含非零 min-x/min-y不会假设原点为 0而JSON 布局生成器自身固定使用原点 0 0——理解这一差异才能正确判断第三方/手写 SVG 的导出结果。3.3 导出后的双确认文档要求导出后做两件事确认 PNG 实际尺寸利用上面的尺寸回读并且检查真实文本Inspect actual text——尺寸正确不代表文字渲染正确。四、夹具驱动的质量验证identity / baseline / long-text 三层文档给出三种夹具的分工对应 fixtures 目录公开样式夹具public style fixtures——用于验证样式身份identity如mem0-style1.json、tool-call-style2.json、microservices-style3.json、multi-agent-style5.json、system-architecture-style6.json、api-flow-style7.json、dark-luxury-style8.svg、c4-review-canvas-style9.json、cloud-fabric-style10.json、event-transit-style11.json、ops-pulse-style12.json等确保每个样式的签名不被破坏共享质量基线夹具quality-baseline——fixtures/quality-baseline/agent-runtime-style{1..7,9..12}.json用同一套 Agent Runtime Architecture 拓扑驱动 11 个生成器样式用于横向对比Style 8 是唯一的静态 AI 手写例外无 JSON 生成路径这一点在command_validate中有明确注释长文本夹具/测试long-text fixtures/tests——用于回归长文案场景下的可读性仓库中对应 tests/test_quality_upgrade.py 与快照 tests/snapshots/quality-upgrade.json 等测试资产。文档在此给出一个明确的断言添加元数据或通过 XML 校验单独拿出来永远不能证明一张图在视觉上是成功的Adding metadata or passing XML checks alone never proves a visually successful diagram。元数据、data-full-text、几何校验都是必要条件但不是充分条件。五、完整校验管线把视觉质量装进工作流visual-quality.md定位是渲染/校验管线的视觉层闸门。将其与 SKILL.md 的 CLI 工作流串联一套完整流程是# 1) 校验输入 JSON 的语义与样式合法性Style 8 不接受 JSON python3 scripts/fireworks.py validate architecture input.json # 2) 渲染 SVG 并产出 layout.json 报告含 typography / palette python3 scripts/fireworks.py render architecture input.json diagram.svg --report layout.json # 3) 几何/组成校验XML、marker、collision、geometry、composition python3 scripts/fireworks.py check diagram.svg # 4) 视觉质量闸门本文主题 # - 阅读 layout.json 的 typography处理可见截断加宽/换短标签/拆分视图 # - 需要全标签精确可见时改用 text_policy: strict # - 阅读 palette对照 4.5:1 对比度目标按样式清单逐项检查 # - 参考 composition-quality-contract.md几何通过后再做视觉层验收 # 5) 导出 PNG默认 1920px含安全净化、尺寸回读与原子写入 python3 scripts/fireworks.py export-png diagram.svg diagram.png --width 1920 # 6) 在预期阅读尺寸下目检最终 PNG文字完整性、对比度、字体替换、 # 层级、间距、裁切、箭头方向、交叉与标签从源码结构看composition-quality-contract.md 与本文档是先后两道闸门几何/组成预算0 交叉、0 桥跳、单边弯折 ≤2、最短路由段 ≥16px、节点间距 ≥40px 等先行通过再应用本文档的对比度与文本完整性检查。check命令的报告里排版与调色板范围typography and palette scope值得逐字段阅读因为启发式文本宽度永远不能替代对实际渲染字体的检查。如果环境不支持查看图片则必须明确标记视觉检查已跳过绝不能声称视觉正确。失败后依据check返回的元素 ID 与几何信息做定点修复连续两次相同修复无效就更换方案——加宽/拆分过满的图而不是隐藏必要文案或无限缩小字号也不要为了通过而静默削弱语义或组成约束。一次渲染成功 ≠ PNG/GIF/HTML 包完成每个请求的本地产物及其适用检查都必须完整交付并报告文件路径、尺寸、视觉评审结论与残余限制。【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考