生成与验证的工具链坑

用 AI/工具生成与验证产出物时反复踩到的一批环境坑，记下来省得再踩。

生成文档

• markdown 内嵌 SVG/HTML 常不渲染：很多 viewer 会把内嵌 <svg> 显示成坐标源码乱码。图表一律走 matplotlib 出 PNG + ![]() 图片语法，或用 Unicode 块字符 sparkline 文本兜底，永不内嵌 SVG。
• .docx 良构 ≠ 能打开：XML 良构 ≠ 符合 OOXML schema ≠ Word 能打开；LibreOffice 宽容（能转 PDF）也测不出问题。须校验**“非命名空间裸元素”**（如把配置对象当 runs 传导致的 <children>）+ 往返解析，才防“内容需修复”弹窗。

验证前端（preview 沙箱）

• IntersectionObserver 在无头沙箱里可能永不 fire；HMR 会累积污染（命中未 hydration 的旧副本）；screenshot 对渐变/动态图表易超时。
• 对策：验证样式/数值改用 preview_inspect/eval 读计算值（别信截图）；动效自写定时兜底“永不隐形”；stop → start 开全新实例避免污染。

度量脚本：假数字最会藏在真数字里（2026-07-16 教训）

这三条比上面的更危险——不是工具坏了，是验证本身给出了假信号。

• 正则 \s 匹配换行 → 跨块吞并：解析 YAML 块标量（key: | 缩进块）时若用 (?:\s{2,}.*)+ 收集内容，\s 会吃掉换行，从本块一路吞进下一块。后果：某字段的统计值把邻块也算进去（一处 182 被算成 616）。块边界必须按缩进判（^\s{0,N}\S 遇更低缩进即止），不能靠 \s+ 贪心。
• 目测数字不许写成“实测”：曾把打印出来的数组用眼睛估了个均值（“首幕平均 99”），写进页面时标成实测——真值 100.2。凡标“实测/测得”的数，必须有一条能重跑的脚本产出它；估的就写“估计”。
• 这类错最难被抓：它混在一组已验证为精确的真数据里（同页 7.7 幕 / 716.9 字 / 93.1 字全部分毫不差），读者没有理由单独怀疑那一个。→ 发布任何“实测”数据前，用独立脚本把整组重算一遍，不逐个抽查——因为你抽查会命中那些真的，放过那个假的。（本页三条均出自 storytelling 首批材料的红队审计，见 fable-theater-craft（把盖曼方法用到寓言剧场) 的口径注。）

Shell 差异坑

• PowerShell if (git … --quiet) 测的是输出，不是退出码：--quiet 命令成功/失败都无 stdout，故 if 恒为假，“无差异”会被误报成“有差异”。判 git 状态用退出码：bash if git diff --quiet; then / PowerShell git diff --quiet; if ($LASTEXITCODE -eq 0)。
• 中文引号打断 PowerShell 参数解析：git commit -m "…「」…" 里的全角引号/特殊符会让 PS 把消息截断成多个 pathspec 报错。多行或含全角标点的 commit message 一律写进文件用 -F file 提交（本会话 3 次踩此坑）。

关系

生成规范面见 word-report-design skill（本页管其未覆盖的技术坑）；“验证要靠可信信号、不信单一截图”的精神与 委派产出的验收 rubric 一致。