# 中文流程图/图表渲染：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` 指向字体文件**，不靠字体名查找：
```python
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**：
1. **中文渲染零风险**——浏览器直接调系统字体，`font-family:"Microsoft YaHei","PingFang SC","WenQuanYi Zen Hei",sans-serif`，绝不豆腐块。
2. **企微能直接打开**，可缩放。
3. **可自检**——`browser_navigate` 到 `file://` 后看快照里的文字是否正确，比赌 PNG 字体渲染可靠得多。
4. 用 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+纯文字兜底一起发。