企业官网建设流程全解析

spark-to-paper-skills 是一个把一句话研究想法变成完整论文草稿的开源技能套件，而 audit_svg.py 是其中最有"匠气"的一部分：一个只用 Python 标准库的 SVG 审计脚本，不依赖渲染器、不需要 API Key、不加载任何模型，却能靠几何测量抓出文字溢出、标签被图标裁半、箭头随线宽暴走、被像素描摹成"路径汤"等一整套肉眼难发现的 SVG 隐藏缺陷。本文带你完整读懂它的工作原理。

为什么"能渲染出来"不算通过？

在 spark-to-paper-skills 的 7 阶段流水线里，第 6 阶段要把论文插图变成可编辑的向量图：官方 PaperBanana 先出候选位图，技能再"原生重绘"成真正的<rect>/<path>/<text>对象。此时最大的风险不是"图好不好看"，而是看不见的缺陷：

• 标签差 2 个像素顶到卡片边缘，1× 缩放时完全看不出；
• 箭头默认按线宽缩放，3px 描边让 6 单位的箭头变成约 18px 的庞然大物；
• 一段✓符号在导出 PDF 时静默回退成另一种字体，整篇论文字体不统一。

脚本开篇的注释一针见血："It renders is not a gate."（能渲染出来不等于通过。）

零依赖是怎么做到的？

打开 audit_svg.py，import区只有argparse、json、math、re、sys、xml.etree.ElementTree、pathlib七件标准库武器。它不截图、不调渲染引擎，所有测量都是纯几何计算：

1. 解析：用ElementTree把 SVG 当 XML 读，按文档顺序遍历（walk方法），同时累乘transform矩阵（支持translate/scale/rotate/matrix）；
2. 建模：每个文本和图形都被解析成一个 Box 包围盒，附带绘制顺序order——这个顺序是判定"谁盖住谁"的关键；
3. 判决：盒与盒之间做交叠面积、边距、端点距离等确定性计算，产出带错误码的 JSON 报告。

核心技巧：不用渲染器，如何精确量出文字宽度？

这是全脚本最"巧"的设计。项目强制插图使用Times New Roman, Nimbus Roman, serif字体栈，而 Times 属于 Adobe core-14 字体——它的每个字符前进宽度是公开的标准数据。脚本直接内嵌了 normal/bold 两套字宽表（audit_svg.py#L36-L50，单位为 1/1000 em）：

text_width = Σ(每个字符的字宽) × font-size / 1000

配合 Times 的 ascender（0.683em）和 descender（0.217em），每段<text>都能算出精确到像素的包围盒，连<tspan>的续行、上下标偏移、text-anchor="middle/end"的整行回移都按渲染规则模拟了。换句话说：它测量文字的方式和渲染器一样，却不需要渲染器。

它到底能抓出哪些隐藏缺陷？

每一个错误码背后，都是真实批次中"实际交付过"的缺陷。核心清单如下：

其中path_soup尤其精彩：它统计"基础图元 ÷ (基础图元 + path)"的比例，低于 0.35 就判定为像素描摹。记录在案的真实案例——自动描摹一张图产生了59,430 条 path、10 MB、0 个可编辑文本，而手绘同内容的手绘图比例在 0.6 以上、不到 100 KB。"可编辑"从此有了机器可检的形式。

配套的 svg-craft.md 把每个缺陷、根因和修法整理成"缺陷目录"，与脚本错误码一一对应，堪称最佳实践文档。

审计不是终点：测量修复循环的门禁

audit_svg.py单独运行只是一次体检，它的价值在循环中兑现。ts-figure-svg/SKILL.md 规定了每轮的标准动作：先快照round_0N.svg（先留证据再检查），再跑审计 + 两种宽度渲染，逐条处理命中项：

python3 skills/ts-figure-svg/scripts/audit_svg.py <work>/round_0N.svg --json <work>/round_0N.audit.json

关键规则有三条：4 轮是地板不是目标，只要还有缺陷就继续；审计通过也不结束——还要在 480px 真实栏宽下人眼复核；最终由总门禁 run_gates.py 校验svg_rounds ≥ 4且审计 JSON 为ok: true，否则整篇论文构建失败。这就是项目"模型负责判断、代码负责诚实"设计哲学的缩影。

上手体验：一条命令的 selftest

脚本内置了自检模式，用 4 段内嵌 SVG（9 类缺陷 + 裁切箭头 + 路径汤 + 一份干净对照）验证自己是否还能抓出所有缺陷，不需要任何准备：

python3 skills/ts-figure-svg/scripts/audit_svg.py --selftest # selftest ok — 9 defect classes + clipped marker + path soup caught; clean SVG passes

常用参数也都很直白：--min-font-px（可读性下限，默认 20）、--pad/--pad-em（文字与卡片的最小边距）、--font-family（强制字体栈）、--min-cleanliness（反描摹阈值）、--json（输出报告）。退出码约定同样清晰：0 = 通过，1 = 有错误，2 = 用法/解析失败——天然适合接入 CI。

小结

audit_svg.py是"用确定性代码兜住 AI 生成物质量"的典范：7 个标准库 import、一张 Times 字宽表、一个包围盒类，就把"能渲染"升级成了"可证明地正确"。它证明了一件事——严谨的质量门禁不一定要重工具，选对测量方式，标准库就是最锋利的审计刀。如果你也在做 SVG 生成或插图流水线，这套"几何审计 + 修复循环 + 硬门禁"的思路非常值得借鉴。

更多上下文可以继续阅读：

• 脚本本体：audit_svg.py（含 selftest 实现）
• 技能说明：ts-figure-svg/SKILL.md · 缺陷目录：svg-craft.md
• 调用方文档：ts-paper-figure/SKILL.md · 总门禁：run_gates.py
• 项目总览：README.md