结构化示意图绘制技能

根据用户描述或文档内容，生成机制图、框架图、流程图等结构化示意图。 工具链：纯 SVG + CairoSVG（矢量输出，无损高清），配合辅助脚本自动转义和校验。 画图质量的关键在于"理解文档→抽取结构"，必须先分析再动手。

一、核心原则

SVG 是唯一的绘图工具 — SVG 是矢量格式，CairoSVG 渲染后可无损放大到任意分辨率。禁止用 matplotlib 位图、Mermaid 自动布局或 HTML+Chrome 截图替代。
先分析再画图 — 必须完成文档结构分析后才能写 SVG 代码。跳过分析直接画 = 逻辑混乱。
一张图 5-15 个主节点 — 少了空洞，多了要拆分。同级同粒度，主干优先。

二、理论速查

| | 机制图 | 框架图 | |---|---|---| | 核心目的 | 揭示"为什么""如何运作" | 展示"由什么构成""如何组织" | | 关系类型 | 因果关系（有方向、±极性） | 结构关系（可无向） | | 典型结构 | 因果链条、循环回路、网络 | 层级嵌套、矩阵、三角、多维并列 | | 文字特征 | 动词为主（促进、抑制） | 名词为主（概念、维度） |

判断方法：解释"内在机理/传导路径"→ 机制图；展示"系统结构/组成维度"→ 框架图。两者可复合。

三、绘图工作流（7步）

Step 1：文档结构分析（最重要的一步）

⚠️ 必须先完成本步骤再进入 Step 2。 详细方法论见 references/document-analysis.md。

三层提取法：

① 宏观定位 — 用一句话概括核心命题：

❌ "讲数字经济的"
✅ "解释数字经济如何通过数据要素和平台生态驱动传统产业升级"

② 中观拆解 — 根据文档类型用对应框架拆成逻辑块：

| 文档类型 | 拆解框架 | |---------|---------| | 理论构建 | 前提→推论→结论 | | 实证分析 | 问题→方法→发现 | | 方案设计 | 目标→路径→保障 | | 政策解读 | 背景→内容→成效 | | 系统架构 | 层次→关系→机制 |

③ 微观提取 — 每个逻辑块内提取三类元素：

实体（→ 节点）：名词性概念（变量、要素、主体、阶段、维度）
关系（→ 箭头）：连接两个实体的动词（促进、制约、依赖、包含）
属性（→ 副标题/标注）：修饰实体的定语

关系挖掘要点（这是质量分水岭）：

追踪中介变量：A→C 中间是否省略了 B？
区分并列与递进：并列→同层排列，递进→顺序箭头
找出回路和闭环：A→B→C→A 必须标出（R=增强/B=平衡）
识别调节条件：虚线框或标注，不放主链条

粒度控制：

超过15个节点 → 合并同类项或拆分多图
同级同粒度 → "技术创新"和"引入AI客服"不应同层
主干优先 → 核心变量和关键路径必须放，调节变量看空间

结构→布局映射（在分析阶段就决定布局）：

单条因果链 → 横向流程型
闭环回路   → 环形飞轮型
核心+分支  → 中心辐射型
层级分类   → 树形/纵向层级型
双维交叉   → 矩阵分块型
双系统互动 → 左右对称/分栏型
上层框架+下层机制 → 上下分层复合型
多层级嵌套 → 同心圆/嵌套框型

分析完成后，输出结构化结论（节点清单 + 关系清单 + 布局选择 + 粒度说明），再进入 Step 2。如文档内容复杂，先查阅 references/document-analysis.md 获取完整方法论。

Step 2：确认策略 & 配色

配色决策：
- 需区分多主体/多维度 → 功能色分区（查阅 references/style-guide.md 第四节）
- 学术论文/正式报告 → 极简灰度系
画布尺寸：标准 viewBox 1760×1100，内容密集用 1760×1200
如需复用模板，查阅 references/svg-template.md

Step 3：写 SVG 代码（唯一渲染方式）

必须使用纯 SVG。不用 HTML 包装、不用 matplotlib、不用 Mermaid。 SVG 是矢量格式，CairoSVG 渲染后输出 scale=3 高清 PNG（5280px 宽），满足打印和出版要求。

从 references/svg-template.md 复制完整 SVG 模板，修改内容
SVG 文本转义（CairoSVG 解析 XML 时，< > & 在文本中必须转义）：
- E级<40分 → E级<40分
- A & B → A & B
- 用辅助脚本自动转义：python3 scripts/diagram_helper.py escape --svg diagram.svg --out diagram_escaped.svg
防遮挡写码规则：
- 渲染顺序（从下到上）：背景 → 详情框 → 箭头 → 标注框 → 节点
- 圆形与详情框：同列→y 严格分开；同行→x 严格分开，gap ≥ 5px
- 箭头终点：停在目标节点边缘，不画到圆心
- 标注框：不压在箭头路径上
- 主标题：y < 所有顶部详情框 y 起点，差距 ≥ 20px

Step 4：自动校验 & 渲染

# 坐标校验（检查圆形/矩形/标注框之间的遮挡问题）
python3 /sandbox/workspace/skills/diagram-drawing/scripts/diagram_helper.py validate --svg diagram.svg

# 渲染 PNG（自动转义 + 渲染一步到位）
python3 /sandbox/workspace/skills/diagram-drawing/scripts/diagram_helper.py render \
  --svg diagram.svg --out diagram.png --scale 3

如果校验未通过：修复坐标后重新校验，全部通过后再渲染。

scale 说明：

scale=3 → 5280px 宽（适合打印）
scale=2 → 3520px 宽（适合 PPT/文档）

Step 5：用户反馈

有问题 → 修 SVG → 回到 Step 3 → Step 4
确认 OK → 进入 Step 6

Step 6：交付

将渲染好的 PNG 文件通过 provide_file 工具提供给用户下载。

四、完整流程图

Step 1  文档结构分析（三层提取 + 关系挖掘 + 粒度控制 + 布局映射）
          ↓  输出：节点清单 + 关系清单 + 布局选择
Step 2  确认策略 & 配色
          ↓
Step 3  写 SVG 代码（纯 SVG，遵循防遮挡规则 + 文本转义）
          ↓
Step 4  自动校验 + 渲染 PNG
          ├─ 校验失败 → 修代码 → 回 Step 3
          └─ 校验通过 → 渲染
              ↓
Step 5  用户反馈
          ├─ 有问题 → 回 Step 1（逻辑问题）或 Step 3（渲染问题）
          └─ 确认 OK
              ↓
Step 6  交付（provide_file 下载）

五、辅助脚本

脚本位于 scripts/diagram_helper.py，三个子命令：

| 命令 | 用途 | 示例 | |------|------|------| | escape | SVG 文本转义 | python3 diagram_helper.py escape --svg in.svg --out out.svg | | validate | 坐标遮挡校验 | python3 diagram_helper.py validate --svg diagram.svg | | render | 自动转义+渲染PNG | python3 diagram_helper.py render --svg diagram.svg --out diagram.png --scale 3 |

六、参考文件索引

| 文件 | 说明 | 何时查阅 | |------|------|---------| | references/document-analysis.md | 文档结构分析方法论（分层提取、关系挖掘、粒度控制、布局映射、多图规划） | Step 1 必读 — 每次画图前按此方法论分析文档 | | references/style-guide.md | 节点形状库、连接方式库、布局结构库、配色方案、高阶技巧 | Step 2 选配色/布局时 | | references/svg-template.md | 完整 SVG 代码模板、元素速查表、布局坐标参考、渲染层级规则 | Step 3 写代码时 |

参考文件不随技能自动加载，按需读取以节省上下文空间。 document-analysis.md 例外：当用户提供了文档/长文本要求画图时，必须读取后再分析。