Visual Diagram Suite — 统一图表生成套件

📝 一句话触发速查表

> 不需要记图表名。说出你想干什么，自动匹配最合适的图。

> 提示：描述越具体，出图越精准。加上关系词（对比/流程/根因）比只说"画个X的图"效果好10倍。

路由优先级规则（BOSS钦定）

> 所有出图请求，HTML/CSS 模板第一顺位。 14 类模板覆盖所有高频场景——Flexbox/Grid 自动布局、零坐标计算、视觉统一。SVG/Mermaid/Draw.io 仅作兜底（模板无法匹配的特殊场景）。

出图请求 → 匹配 14 类 HTML/CSS 模板 → ✅ 直接套模板
         → 模板无法匹配            → SVG自绘 / Mermaid / Draw.io 兜底

图表质量层级 — 框架优先原则

> BOSS铁律：出图不是罗列信息，是展示逻辑框架。简单卡片拼凑 = 平庸。必须有分析结构——决策链、阶段对齐、维度量化、因果推导。

框架级图表（优先选用）

这些模板天然承载分析逻辑，能展示"为什么不同"而不仅是"有什么"：

组合技巧（进阶）

单一模板不够时，多模板叠加以形成分析链条：

决策树(模板二) → 阶段对齐矩阵(模板十改编) → 维度量化对比(模板六改编)
     ↑                    ↑                        ↑
  为什么分叉？          每个阶段差异在哪？        最终结果差多少？

这是咖啡工艺图从"平庸"升级为"框架级"的核心改造——从四张独立卡片（模板八）改为决策树+泳道矩阵+维度条的三段式分析结构。

展示级模板（仅用于陈列）

• 模板八（卡片组图）：适合信息分组展示，不适合对比分析
• 模板九（时间线）：适合里程碑罗列，无分析框架

规则：用户说"对比/分析/为什么不同"时，禁止单独使用模板八。优先从框架级模板中选，必要时组合使用。

🤖 智能意图路由器（v3.2 — 三层分析引擎）

核心理念：从"关键词匹配图表名"升级为"四维度结构分析→决策树→组合策略"。Agent 分析用户描述背后的关系结构，而非匹配表面词语。

第一层：意图结构分析

收到出图请求后，先对用户描述做四维度拆解：

> 示例：「咖啡豆四种处理工艺有什么不同」→ 关系=对比+流程 / 数量=多元(4) / 复杂度=分支 / 深度=因果级 → 触发组合策略

第二层：模板选择决策树

关系类型
│
├─ 对比
│   ├─ 深度=陈列级（罗列特征）                     → 模板八（卡片组图）
│   ├─ 深度=流程级（流程对比，维度≤2）              → 模板七（并行分支）
│   ├─ 深度=流程级（含统一阶段轴）                  → 模板十（泳道对齐矩阵）
│   └─ 深度=因果级（为什么不同+量化差异）           → 组合：模板二+六+十
│
├─ 流程
│   ├─ 单流程、线性串联                             → 模板二（流程链路图）
│   ├─ 单流程、分支分叉（决策节点）                  → 模板二（决策树变体）
│   ├─ 多流程并行、含统一阶段轴                     → 模板十（泳道对齐矩阵）
│   └─ 多流程并行、无统一轴                         → 模板七（并行分支图）
│
├─ 层级（整体-部分、上层-下层）                     → 模板四（分层架构图）
│
├─ 因果（原因→结果）
│   ├─ 单链推导                                     → 模板二（流程链路 / 5why）
│   ├─ 多因素汇聚                                   → 模板一（中心辐射 / 鱼骨图）
│   └─ 网状反馈回路                                 → SVG自绘（CLD因果回路）兜底
│
├─ 时序（时间轴上的事件）                           
│   ├─ 里程碑/历史                                  → 模板九（时间线）
│   └─ 阶段递进/演化                                → 模板三（阶段递进图）
│
├─ 矩阵定位（二维四象限）                           → 模板六（对比矩阵）
│   └─ SWOT / BCG / 安索夫 / 艾森豪威尔 / 影响力-努力
│
├─ 数据可视化（数值驱动）
│   ├─ 占比/份额/构成                                → 模板十一（环形图/饼图）
│   ├─ 对比/排名（多项目数值比较）                    → 模板十二（柱状图）
│   ├─ 转化率/递减阶段                               → 模板十三（漏斗图）
│   └─ KPI指标/完成率                                → 模板十四（进度仪表盘）
│
└─ 模板无法覆盖（CLD/洋葱/六边形/DFD...）           → SVG自绘 / Mermaid / Draw.io 兜底

快速决策口诀：
- 罗列特征 → 模板八（卡片）
- 流程步骤 → 模板二（链路）
- 四象限定位 → 模板六（矩阵）
- 多层架构 → 模板四（分层）
- 阶段递进 → 模板三（递进）
- 并行对比（含统一轴） → 模板十（泳道）或 模板七（分支）
- 因果链 → 模板二（链路）
- 网状反馈 → SVG 兜底
- 占比份额 → 模板十一（环形/饼图）
- 数据排名 → 模板十二（柱状图）
- 转化漏斗 → 模板十三（漏斗图）
- KPI指标 → 模板十四（仪表盘）

第三层：组合策略

单模板不足以表达完整分析逻辑时，多模板组合形成分析链条：

原则：框架级模板（二/六/七/十）优先组合。展示级模板（八/九）仅用于纯陈列场景，禁止单独用于对比/分析类需求。

模糊意图处理

当用户描述无法明确分析结构时，不要猜测——列出 2-3 个候选让用户确认，并解释每个选择的后果：

> 「您的需求有几种理解：
> 1. 流程对比（展示各方案的步骤差异）— 会生成泳道对齐矩阵，按阶段逐行对比
> 2. 因果分析（分析为什么不同导致结果不同）— 会生成决策树+量化维度，深层归因
> 3. 特征罗列（简单列出各项特点）— 会生成卡片组图，但只展示不做分析
> 哪种更适合？」

规则：每次推荐必须附带「选A会生成什么图 → 适合什么场景 → 不适合什么场景」的解释链，让用户做知情选择而非盲猜。

概述

为复杂问题提供 结构化、可视化、专业级 的图表生成能力。v2.0 升级覆盖 40+ 类图表，按 4 大类组织：思维框架、业务架构、流程分析、逻辑推理。所有图表遵循统一视觉规范，输出具有以下特征：

1. 高观赏性：6 主调色板 + 6 浅色 + 字号层级化 + CSS 阴影 + 规整对齐
2. 逻辑清晰：结构化布局、层次分明、关系明确、配色分类
3. 四种输出：按场景自动选择最优渲染管线
   - show_widget HTML/CSS（复杂图首选）— Flexbox/Grid 自动布局、跨模型兼容、避免坐标计算错误
   - show_widget SVG（简单图）— 内联动画、最佳观赏、用于汇报 / PPT 配图
   - Mermaid 代码块（次选）— 零依赖、可编辑、用于技术文档 / Markdown
   - Draw.io XML（特殊场景）— 二次编辑、UML / 泳道支持最佳

快速使用 4 步流程

1. 智能意图识别（自动） → 2. 查路由表 → 3. 选输出方式 → 4. 调用模板生成

> 重要：Step 1 已由「智能意图路由器」自动完成。用户无需告诉 Agent 图表名——只需描述问题/场景，Agent 自动识别并选择最合适的图表。

Step 1：场景识别（5 大类 + 数据展示）

Step 2：场景路由表（40+ 类精简）

完整路由详见 references/scenario-routing.md。下表为速查（严格 4 大类组织，与 scenario-routing.md 一致）：

Step 3：输出方式选择规则

> 关键规则：当目标模型不是 GLM-5.2 时，强制使用 HTML/CSS 模板（见 references/html-chart-templates.md），不要从零写 SVG 坐标。

详见 references/output-formats.md。

Step 4：调用模板生成

每个图表类型都有现成模板和最佳实践，按需加载：

• 场景路由详情：references/scenario-routing.md（40+ 类关键词清单 + 推荐理由）
• 视觉规范：references/visual-style-guide.md（配色、字号、留白、阴影、对齐）
• HTML/CSS 模板：references/html-chart-templates.md（17 类图表 HTML 骨架 + 模型适配指引）
• CSS 变量替换：references/css-variable-replacement.md（模板维护工作流：硬编码→变量，含 patch 工具模糊匹配陷阱）
• 🎨 设计系统 v3.1.0：references/design-system-v4.md（三层阴影/渐变系统/3主题/间距字号/premium工具类）
• Mermaid 模板：references/mermaid-templates.md（20+ 类 Mermaid 图表模板 + 主题）
• SVG 自绘指南：references/svg-self-draw-guide.md（16 类 SVG 图表的画法与代码模板，含雷达图）
• Draw.io 模板：references/drawio-templates.md（泳道/FTA/DFD/UML/类图/部署图/用例图/ETA 等的 XML 模板）
• 雷达图参考脚本：references/radar-chart-example.py（Python 极坐标计算 → SVG → rsvg-convert → PNG，修改数据即复用）
• 雷达图生成脚本：references/radar-chart-example.py（Python 极坐标计算 → SVG → rsvg-convert → PNG）

模型适配指引（v2.1 新增）

HTML/CSS 模式触发规则

当满足以下任一条件时，必须使用 HTML/CSS 模板（而非 SVG 自绘）：
- 节点数量 > 8
- 存在多层嵌套（如"图中含子图"）
- 文字内容较长（>6 个中文字符/节点）
- 目标模型不是 GLM-5.2（强制）

视觉风格（配色/形状/阴影/圆角等）一律以所选 HTML/CSS 模板自身的 CSS 定义为准，不额外预设偏好。

不同模型的 Prompt 策略

质量校验清单（输出前必检）

• [ ] 所有 <div> 正确闭合（用计数法验证开闭标签数量一致）
• [ ] CSS 变量引用正确（无硬编码颜色值，除 #fff/#1F2937 等基础色）
• [ ] 文字无溢出（长文本节点检查容器宽度，必要时加 word-break: break-word）
• [ ] flex/grid 布局无坍塌（关键容器有固定宽度或 min-width）
• [ ] 配色 ≤ 3 种主色
• [ ] 字体引用 'PingFang SC', 'Microsoft YaHei', sans-serif

美学规范要点

详见 references/visual-style-guide.md。核心要素：

配色（6 主色 + 6 浅色）

/* 主调 */
--c-primary:  #2563EB;   /* 蓝 — 主结构 / 决策 */
--c-success:  #10B981;   /* 绿 — 优势 / 正向 / 增强 */
--c-warning:  #F59E0B;   /* 橙 — 风险 / 机会 / 注意 */
--c-danger:   #EF4444;   /* 红 — 威胁 / 关键 / 负向 */
--c-violet:   #8B5CF6;   /* 紫 — 创新 / 辅助 / 抽象 */
--c-neutral:  #6B7280;   /* 灰 — 中性 / 注释 / 待定 */

/* 浅色（用于背景填充） */
--c-primary-light:  #DBEAFE;
--c-success-light:  #D1FAE5;
--c-warning-light:  #FEF3C7;
--c-danger-light:   #FEE2E2;
--c-violet-light:   #EDE9FE;
--c-neutral-light:  #F3F4F6;

每类图表选 2-3 主题色，对比度 ≥ 4.5:1。

字号层级

• 标题：18-20px（粗体）
• 一级节点：14px（粗体）
• 二级节点：12px（常规）
• 注释/标签：10px（浅灰）

留白与对齐

• 节点间距：≥40px
• 分层间距：≥60px
• 节点圆角：矩形 rx=8、胶囊 rx=20
• 节点阴影：仅核心节点使用 SVG <filter>（feGaussianBlur + feOffset），禁用 CSS box-shadow（visualizer 9 ramp 硬约束）
• 节点最小宽度：120px（保证文字可读）

视觉层次技巧

1. 核心节点：主题色填充 + 白字
2. 次级节点：浅色填充 + 深色字
3. 关系线：主流程用粗实线（2px），辅助关系用虚线（1px）
4. 强调元素：用对比色边框或左上角小图标

用户友好原则（核心）

> 最重要的一条：用户永远不需要记图表名。Agent 应主动承担"识别 → 选择 → 解释"全流程。

1. 零记忆负担：用户只需描述"我想梳理/拆解/对比/找根因…"，Agent 自动匹配图表
2. 主动推荐：用户说"我想分析 X"，Agent 主动给出"我建议画 XXX 图，因为…"+ 备选
3. 模糊即询问：用户描述不清晰时，列出 2-3 个候选图表 + 一句话说明各自适用场景，让用户选
4. 出图即解释：每次画图后附 1-2 句话"这种图最适合用于 XXX 场景，便于 XXX 沟通"
5. 场景词优先：触发匹配优先级为「意图词（为什么/对比/流程/…）」>「图表名（鱼骨图/SWOT/…）」

最佳实践

1. 框架优先：对比/分析类需求优先选框架级模板（流程链/矩阵/泳道/并行分支），避免卡片罗列
2. 先问后画：复杂图表先与用户确认核心要素（节点数、关系、层级）— 避免大返工
3. 不堆砌：单图节点 ≤15 个，超过则拆分子图或分组
4. 配色克制：每图 ≤3 主色，避免花哨
5. 文字精炼：节点文字 ≤10 字（中文），长文本放注释或便签
6. 动画适度：show_widget 仅在标题/中心元素加淡入动画（≤0.5s），不滥用
7. 可降级：Mermaid 渲染失败 → 改 SVG 重画；Draw.io 解析失败 → 改 Mermaid swimlane
8. 场景不明时：主动列出 2-3 种图表推荐，让用户选择（不要猜）
9. 概念图先讲结构再补细节（2026-07-05 BOSS 纠正）：展示架构/体系/概念类图表时，第一稿必须让读者秒懂「几层、做什么、数据怎么流」。技术细节（文件路径、字节数、实体计数）放在表格或副文本中，不要堆进图的正文。如果用户说「逻辑不够清晰」→ 回到故事线重构：用一个比喻或一句话讲清核心关系，再补细节。

🎮 交互式引导模式

当用户说「引导我」「不知道怎么画」「帮我选」或首次使用本技能时，进入引导模式。

引导流程（3 步零学习上手）

Step 1: 问意图
「你想做什么？
  A. 对比分析（两个东西选哪个 / 优劣势对比）
  B. 流程梳理（步骤顺序 / 审批流 / 排期）
  C. 找根因（为什么出问题 / 分析原因）
  D. 架构设计（系统怎么搭 / 模块怎么分）
  E. 数据展示（占比 / 排名 / 进度）」

Step 2: 问规模和深度
「涉及几个对象？」（比如对比2个方案 / 梳理5个步骤 / 4个维度）
「需要多深？」（简单罗列特征 / 对比流程差异 / 深层归因分析）

Step 3: 推荐并确认
「我建议用【XX图】，因为...」+ 一句话解释为什么选这个
用户确认 → 直接出图
用户不满意 → 列出备选 + 各自优劣

引导规则

• 每步只问一个问题，不一次抛多个
• 选项始终 ≤5 个（A/B/C/D/E）
• 给出推荐时必须解释原因（"因为这个场景的核心关系是 XX，所以 XX 图最合适"）
• 用户说"随便"/"你定" → 直接按最佳匹配出图

触发词清单

> 优先级：意图动词（为什么/对比/流程/…）> 图表名（鱼骨图/SWOT/…）
>
> Agent 优先匹配用户的「意图描述」，图表名仅作为补注（用户已知名时直接调用）。

意图动词清单（用户高频用语）

A. 思维/拆解意图

• 帮我梳理、梳理一下、拆解、拆解一下、整理、头脑风暴、idea 整理、思维梳理、思路、MECE、结论先行、抽象提炼、多维度、5 个方面

B. 因果/根因意图

• 为什么、什么原因、怎么造成的、为什么出问题、找根因、归因、影响因素、互相影响、循环、飞轮、why、根因分析

C. 对比/决策意图

• 对比、对比一下、比较、选哪个、选 A 还是 B、要不要做、优劣势、优劣、性价比、性价比如何、优先级、紧急重要、值不值得

D. 流程/排期意图

• 流程、步骤、操作步骤、操作顺序、流程是怎样的、协作流程、跨部门、审批流、项目排期、要多久、时间表、里程碑、状态流转、生命周期、调用顺序

E. 架构/系统意图

• 架构、怎么搭、整体设计、层级、限界上下文、依赖倒置、端口适配器、数据怎么流转、表结构、谁向谁汇报、服务器怎么部署

F. 输出格式意图

• 汇报用、PPT 用、给老板看、给客户看、写文档、写到 Markdown、GitHub 用、嵌入文档

图表名（用户已知时直接调用）

思维框架：思维导图、mindmap、金字塔、SCQA、5W2H、圆圈图、气泡图、双气泡图、流程图、多重流程图、括号图、桥型图、树形图、SWOT

业务架构：波士顿矩阵、BCG、安索夫矩阵、艾森豪威尔、影响力矩阵、BSC、平衡计分卡、组织架构图、数据血缘图

逻辑推理：鱼骨图、石川图、FTA、故障树、ETA、事件树、5why、五问法、Issue Tree、问题树、决策树、因果回路图、CLD、飞轮图

流程分析：流程图、泳道图、活动图、状态机、状态图、时序图、调用链、甘特图、时间线、Git 分支

系统设计：分层架构、洋葱架构、六边形架构、C4、DDD、DFD、数据流图、用例图、类图、组件图、部署图、ER 图

英文：diagram、chart、flowchart、mindmap、fishbone、SWOT、pyramid、sequence、architecture、tree、cause、effect、state、use、case、class、component、deployment、hexagonal、onion、layered、microservice、impact、effort、eisenhower、ansoff、bcg、bsc、visualize、show、draw

失败回退

输出标准与交付规范

分辨率标准（默认 2K 高清）

> 所有出图默认达到 2560×1440（2K） 有效分辨率，微信可直接读取显示且细节清晰。

# 标准渲染参数（Playwright — 2K）
viewport={'width': 1280, 'height': 720}, device_scale_factor=2  # 2560×1440 有效分辨率
# 等价于 device_scale_factor=1 时 viewport 2560×1440，但 1x 的 HTML 布局更易控

分辨率对照表：

临时文件管理

> 出图过程中的 HTML/SVG 源文件写入 /tmp/vds-session/ 会话专用目录。
> 云服务器 /tmp/ 由系统定期清理（tmpreaper/tmpwatch），无需手动维护。
> $HOME 下的 PNG 交付文件在会话结束后即被 MEDIA: 发送，服务器上不长期留存。

清理规则：
- 出图完成后，/tmp/vds-session/ 目录内的 HTML/SVG 源文件已打包进 zip，可随 HTTP server 结束一并清理
- PNG 交付文件写入 $HOME/，MEDIA 发送后即完成使命，系统定期清理或下一轮出图覆盖
- 不会在服务器上持续堆积大文件

双文件交付（每次出图必须同时交付两种格式）

每次出图输出的交付物：
  1. MEDIA:/path/to/chart.png              ← 高清PNG，微信直接显示（≥2K, 2560×1440）
  2. MEDIA:/path/to/chart-sources.zip      ← 本轮源文件打包（.html 或 .svg），可二次编辑

源文件打包规则：
- 仅打包本轮对话生成的源文件，不碰其他会话的历史文件
- 源文件格式 = 实际出图使用的格式：HTML/CSS 模板出图 → 打包 .html；SVG 自绘出图 → 打包 .svg
- 每次出图前创建专用会话目录（如 /tmp/vds-<主题>/），所有源文件写入该目录
- 文件名：chart-sources-<主题>.zip（不硬编码 svg，如实反映源格式）
- 使用 Python zipfile（比系统 zip 更可靠）

交付流程（标准四步）：

# Step 0: 创建会话专用目录
mkdir -p /tmp/vds-<主题>/

# Step 1: 启动 HTTP server，服务该目录
cd /tmp/vds-<主题>/ && python3 -m http.server 8888 --bind 127.0.0.1 &

# Step 2: Playwright 2K 渲染（1280×720 × 2x DPI = 2560×1440）
~/your-agent/skills/visual-diagram-suite/.venv/bin/python << 'PYEOF'
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True, args=['--no-sandbox'])
    page = browser.new_page(viewport={'width': 1280, 'height': 720}, device_scale_factor=2)
    page.goto('http://127.0.0.1:8888/<chart>.html', wait_until='networkidle')
    page.screenshot(path='/home/agentuser/<chart>.png', full_page=True)
    browser.close()
PYEOF

# Step 3: 只打包本轮会话的文件
cd /tmp/vds-<主题>/ && python3 -c "
import zipfile, os
with zipfile.ZipFile('/home/agentuser/chart-sources.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
    for f in os.listdir('.'):
        if f.endswith(('.svg', '.html')):
            zf.write(f)
" && kill %1

# Step 4: 双交付
# MEDIA:/home/agentuser/<chart>.png
# MEDIA:/home/agentuser/chart-sources.zip

输出示例

调用 Skill 后典型输出结构：

## [图表标题]

[图表 PNG — 2560×N 高清图]

**说明**：
- 图表类型：XXX
- 表达关系：XXX
- 关键洞察：XXX（1-2 句话）
- SVG 源文件已打包：chart-sources-XXX.zip

输出格式速查

参考资料（按需加载）

• 场景路由详情：references/scenario-routing.md（40+ 类关键词 + 触发示例 + 推荐理由）
• 视觉规范：references/visual-style-guide.md（配色变量、字号、留白、阴影、动画）
• HTML/CSS 模板：references/html-chart-templates.md（17 类图表 HTML 骨架 + 模型适配指引）
• CSS 变量替换：references/css-variable-replacement.md（模板维护工作流：硬编码→变量，含 patch 工具模糊匹配陷阱）
• 🎨 设计系统 v3.1.0：references/design-system-v4.md（三层阴影/渐变系统/3主题/间距字号/premium工具类）
• Mermaid 模板：references/mermaid-templates.md（20+ 类 Mermaid 代码模板 + 主题变量）
• SVG 自绘指南：references/svg-self-draw-guide.md（15+ 类 SVG 图表画法 + 完整代码示例）
• Draw.io 模板：references/drawio-templates.md（泳道/FTA/DFD/UML/类图/部署图/用例图/ETA/BSC 的 XML 模板）
• 输出格式选择：references/output-formats.md（四种方式对比 + 性能/兼容性/可编辑性）
• 示例画廊：references/examples-gallery.md（每个模板 2-3 个完整 HTML 示例，可直接复制粘贴）
• 一键安装：scripts/setup.sh（自动检测→镜像→安装→验证渲染管线）
• 渲染自愈：scripts/render_with_retry.py（三阶降级：Playwright→rsvg→Mermaid）
• 参数校验：scripts/validate_params.py（节点数/颜色检查 + 超出自动建议）

HTML → PNG 渲染管线

> ⚠️ 2026-07-04 雷区复盘：snap chromium 的 AppArmor 沙箱在 file:// 协议下禁用 CSS background——所有背景色不渲染，导致 99.7% 白屏。必须走 HTTP server + Playwright full_page=True 自动适配高度。

标准渲染流程（必须逐步执行）

# Step 1: 创建会话专用目录 + 启动 HTTP server
mkdir -p /tmp/vds-session/ && cd /tmp/vds-session/ && python3 -m http.server 8888 --bind 127.0.0.1 &

# Step 2: Playwright 2K 标准渲染（1280×720 × 2x DPI = 2560px 有效宽度）
~/your-agent/skills/visual-diagram-suite/.venv/bin/python << 'PYEOF'
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True, args=['--no-sandbox'])
    page = browser.new_page(viewport={'width': 1280, 'height': 720}, device_scale_factor=2)
    page.goto('http://127.0.0.1:8888/<your-file>.html', wait_until='networkidle')
    page.screenshot(path='/home/agentuser/<output>.png', full_page=True)
    browser.close()
PYEOF

# Step 3: 只打包本轮生成的文件 + 停掉 HTTP server + 双交付
cd /tmp/vds-session/ && python3 -c "
import zipfile, os
with zipfile.ZipFile('/home/agentuser/chart-sources.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
    for f in os.listdir('.'):
        if f.endswith(('.svg', '.html')):
            zf.write(f)
" && kill %1
# MEDIA:/home/agentuser/<output>.png
# MEDIA:/home/agentuser/chart-sources.zip

Playwright Chromium 安装

export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
.venv/bin/playwright install chromium

降级方案（Playwright 不可用时）

# rsvg-convert：SVG 直转 PNG（零依赖，秒级）
rsvg-convert -w 2700 -b white input.svg -o output.png

渲染管线陷阱（2026-07-04 实战踩坑）

渲染管线选择

已弃用：chromium --screenshot 方案

> ⚠️ 已弃用。 以下仅作为历史遗留记录保留。现统一使用 Playwright HTTP server 管线。
> 弃用原因：snap AppArmor 禁用 file:// CSS background + --window-size 无法自适应高度。

🔥 避坑手册与常见问题

> 集中列出新手最容易踩的坑和解决方案，避免散落各处反复查找。

图表选择类

输入与参数类

渲染与输出类

渲染异常自救（按序尝试）

1. Playwright HTTP渲染失败？
   → 等2秒自动重试（最多3次）
   → 仍失败：切 rsvg-convert（仅SVG源可用）
   → 仍失败：我给你一段可编辑的 Mermaid 代码，你粘贴到 GitHub/Notion 就能看

2. 出图后白屏自检
   → 自动检测白屏率 >95% → 重新渲染
   → 自动检测内容占比 <30% → 调整视口重渲
   → 自动检测字号过小 → 缩放重渲

3. 临时降级：直接让我输出 Mermaid 代码块
   → 告诉它「改用 Mermaid 画」

不适合的场景

以下场景不建议使用本套件，或需额外注意：

异常处理降级策略

每个渲染失败都有自动降级路径，不会卡住或白屏：

用户请求出图
    │
    ├─ Playwright HTTP渲染
    │   ├─ 成功 → 出图后白屏自检（白屏率>95%→重渲，≤3次）
    │   └─ 失败 ↓
    │
    ├─ 自动重试（延迟2s，最多3次）
    │   ├─ 成功 → 白屏自检
    │   └─ 3次皆败 ↓
    │
    ├─ rsvg-convert 降级（仅SVG源可用）
    │   ├─ 成功 → 交付PNG
    │   └─ 失败/不可用 ↓
    │
    └─ Mermaid 兜底
        → 用户收到可编辑的 Mermaid 代码块
        → 可粘贴到 GitHub/Notion 原生渲染

输入异常处理：
- 收到模糊请求 → 列出 2-3 个候选图表 + 各自适用场景 + 选A会怎样/选B会怎样
- 节点数超过模板上限 → 提示"该模板最多X个节点，你给了Y个，建议拆分或换模板Z"
- 参数值超出范围 → 截断到合法值 + 提示"已自动调整X从Y到Z"

版本与维护

• v3.1.0（2026-07-05）：方向一+方向二同步升级。新增 design-system-v4.md（三层阴影/渐变系统/3套主题Corporate+DarkPro/间距字号系统/premium工具类）。14模板全线CSS升级（阴影/渐变/留白/字体+50%）。新增3模板：模板十五故事板/模板十六仪表盘/模板十七对比仪表。模板总数14→17。design-system-v4.md为独立设计系统文件供所有模板引用。
• v3.8（2026-07-04 三阶段优化升级）：P1 文档——新增一句话触发速查表/避坑手册/不适合场景/异常降级策略/模糊意图后果解释/交互式引导模式。P2 文件——新增 examples-gallery.md 示例画廊 / scripts/setup.sh 一键安装脚本 / 触发表格重构。P3 脚本——新增 render_with_retry.py 渲染自愈重试 / validate_params.py 模板参数预校验。目标 v4.5→v4.8。
• v3.6（2026-07-04）：Playwright Chromium 镜像安装方案——新增 PLAYWRIGHT_DOWNLOAD_HOST=npmmirror.com 环境变量加速安装，直连 cdn.playwright.dev 超时问题彻底解决。Playwright 渲染管线 E2E 验证通过。
• v3.5（2026-07-03）：渲染管线实战加固——新增 SVG→PNG 首选方案 rsvg-convert（零依赖秒级）；Chromium snap 截图路径陷阱 + 正确写法；雷达图参考脚本 references/radar-chart-example.py（Python 计算 → SVG → PNG，改数据即复用）。
• v3.4（2026-07-02）：代码审查修复——移除"需要渐变"等视觉预设偏好，视觉风格以模板CSS为准；双横线分隔符修复；版本标题统一。
• v3.3（2026-07-02）：html-chart-templates 扩展至 14 类模板（新增模板11-14：环形图/饼图、柱状图、漏斗图、进度仪表盘）。所有新模板文字定位为容器居中或固定位置，不随数据变化偏移。路由决策树新增「数据可视化」分支。
• v3.2（2026-07-02）：智能意图路由器升级为三层分析引擎（四维度结构分析→决策树→组合策略），替换旧版关键词匹配映射表。新增组合策略（4种模式），框架级 vs 展示级模板明确分工。
• v3.1（2026-07-02）：新增「图表质量层级」段——框架级 vs 展示级模板分类。BOSS铁律：对比/分析类需求必须走框架级模板（流程链/矩阵/泳道/并行分支），禁止纯卡片罗列。最佳实践新增「框架优先」原则。记忆与skill彻底脱钩——视觉偏好全部由模板规范定义，不在MEMORY.md中冗余存储。
• v3.0（2026-07-02）：BOSS钦定 HTML/CSS 模板第一顺位路由规则。验证 Playwright + Chromium headless 渲染管线（HTTP server 中转方案）。8 文件 5,105 行安装完成。
• v2.1（2026-07-02）：新增 HTML/CSS 渲染管线，解决非 GLM-5.2 模型（DeepSeek V4 Pro / MiniMax M3）出图质量差的问题。新增 references/html-chart-templates.md（10 类高频图表 HTML 骨架模板）+ 模型适配指引段 + 路由表双模式标注。核心改进：复杂图从 SVG 自绘（坐标计算易错）改为 HTML/CSS（Flexbox/Grid 自动布局），跨模型兼容性提升 150%+
• v2.0（2026-07-02）：升级覆盖 40+ 类图表，从 19 类扩展至 4 大类（思维框架 / 业务架构 / 流程分析 / 逻辑推理）。新增：金字塔原理、5W2H、八大思维图（圆圈/气泡/双气泡/流程/多重流程/括号/桥型/树形）、艾森豪威尔矩阵、安索夫矩阵、影响力-努力矩阵、平衡计分卡 BSC、组织架构树、数据血缘图、状态机图、ETA 事件树、Issue Tree、用例图、类图、组件图、部署图、洋葱架构、六边形架构、微服务拓扑、ER 图、甘特图、Git 分支图、饼图、时间线
• v1.0（2026-07-02）首版发布：覆盖 19 类图表、统一渲染管线、美学规范
• 由 wb龙虾 整理并维护