4.0 KiB
4.0 KiB
中文流程图/图表渲染：matplotlib 坑 + HTML 首选方案
2026-06-16 实战教训：给 Maggie 画流程图，matplotlib 反复把中文渲染成"豆腐块"（空心方块 tofu），折腾数轮。根因与可靠方案如下。
matplotlib 中文豆腐块根因
- 系统装了文泉驿
wqy-zenhei.ttc，但 matplotlib 默认不把.ttc注册进字体缓存——rcParams['font.sans-serif']=['WenQuanYi Zen Hei']按"字体名"查找会静默失败、回退成豆腐块，不报错。 fc-list :lang=zh能看到字体 ≠ matplotlib 能按名字用它。
可靠修复（若必须用 matplotlib）
给每个 text 显式传 fontproperties 指向字体文件，不靠字体名查找：
import matplotlib.font_manager as fm
FP = fm.FontProperties(fname="/usr/share/fonts/truetype/droid/DroidSansFallbackFull.ttf")
# Droid Sans Fallback 是 .ttf、已在缓存、支持全中文，比 .ttc 可靠
ax.text(x, y, "租赁合同", fontproperties=FP) # 每处都带 fontproperties
验证某字体文件能否渲染中文：渲染单字 '租'，统计中心 1/3 区域笔画占比，>0.08 是真字、<0.05 是空心豆腐块。
★ 首选方案：用 HTML 而非 matplotlib PNG
给非技术用户（Maggie，经企微/OnlyOffice 看）的中文图表/流程图，优先做成自包含 HTML：
- 中文渲染零风险——浏览器直接调系统字体，
font-family:"Microsoft YaHei","PingFang SC","WenQuanYi Zen Hei",sans-serif，绝不豆腐块。 - 企微能直接打开，可缩放。
- 可自检——
browser_navigate到file://后看快照里的文字是否正确，比赌 PNG 字体渲染可靠得多。 - 用 div + border + 颜色块画节点、
↓/→字符画箭头，配色用语义色（蓝=主审、绿=subagent、金=交付）。
可复制的起始模板：templates/lease-review-flowchart.html。
⚠️ 语义色点用纯 CSS 圆点，不要用 emoji（🔵🟢🔴）（2026-06-22 workflow流程图实证）
图例/节点里标语义色，别用 emoji 彩色圆点——无头浏览器截图环境（Browserbase 等）常缺 emoji 字体，截图里 emoji 渲染成空心方框 ▢（文本层 emoji 字符其实完好、browser_console 测 looksLikeBox:false，只是那个截图环境字体缺失）。但你无法保证 Maggie 的企微/设备一定有 emoji 字体，交付物要万无一失。
- 正解：用纯 CSS 圆点
<span class="dot b"></span>：.dot{display:inline-block;width:11px;height:11px;border-radius:50%;border:1.5px solid;}，各色.dot.b{background:#BBD9F0;border-color:#2E6DA4;}…。任何设备、任何环境稳定显示，不依赖 emoji 字体。 - 节点本身已有语义底色时，标题里的 emoji 色点是冗余，直接删（靠底色表达语义即可）。
- 表意标记 emoji（⚠️📌✅）可保留——渲染更稳，且是真正的语义标记，不是纯装饰色点。
- 自检：
browser_navigate到file://后用browser_console读.lg的 textContent 确认文本层完整；再vision_analyze/browser_vision看截图确认色点真渲染成彩色圆点（不是方框）。
图像自检：vision 已配好，是主路径（2026-06-22）
vision_analyze/browser_vision 已由技术支持配好可用——交付 PNG/HTML 截图前先自己 vision 看一遍验证版面/配色/截断/乱码，这是主路径（实测能准确读出渲染图的配色、文字截断、版面错位、色点是否方框）。
- HTML 双层自检：
browser_navigate到file://看快照验证中文/结构（文本层）+browser_vision看视觉层（配色/排版/emoji 方框）——两层都过才发。 - 兜底（vision 万一又报 "No LLM provider configured for task=vision" 或连不上）：不把"看不见的 PNG"直接甩用户，改用能推理正确性的格式——HTML（看
browser_navigate快照验证文本层）或纯文字版流程图（方框+箭头字符，零字体依赖），HTML+纯文字兜底一起发。