mcpField
S
svg-flowchart

svg-flowchart

github.com/mercatorprojDesign & UI852 installsUpdated 3w ago
Repository

About svg-flowchart

An academic-style SVG flowchart skill for thesis and report figures. It converts structured lists, natural-language steps, or JSON specs into diagrams, and includes style checks and PDF export guidance.

Key features

  1. 01Generate SVG from text or JSON specs
  2. 02Layout nodes, links, and branches
  3. 03Create scalable, print-ready diagrams
  4. 04Check SVG style conventions
  5. 05Provide PDF export methods

Use cases

  1. 01Drawing a methods flowchart for a thesis
  2. 02Turning natural-language steps into a diagram
  3. 03Laying out grouped or multi-column diagrams
  4. 04Checking an SVG and exporting a PDF for LaTeX

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mercatorproj/vibe-thesis-skills --skill svg-flowchart

After installing, type/svg-flowchartin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

examples.md
LICENSE
README.md
scripts/
batch_svg2pdf_flows.bat
render_flowchart.py
svg2pdf.py
validate_flowchart_style.py

Details

From the project README

SVG 流程图绘制（学术风格）

适用场景（触发）

  • 用户提到“流程图 / flowchart / 画流程图 / 用 SVG / 生成 svg 代码”
  • 需要论文/报告中可直接插入的流程图（风格稳重、线条克制、可打印）

目标输出

  • 默认输出 SVG 代码，并 保存为 .svg 文件（项目内可引用）
  • SVG 应满足：viewBox 完整、可缩放、不依赖外部字体资源、中文可读、对齐规整

转化为 SVG 的多种方式

本技能支持从多种输入转化为标准 SVG 文件，便于论文插图与版本管理。

输入形式转化方式输出
结构化文本（节点清单 + 连线清单）Agent 按规范抽取 DAG，计算布局，写出 SVG 代码并保存{{THESIS_DIR}}/figures/flows/<名称>.svg（默认 论文章节/figures/flows/）
自然语言描述（“先 A 再 B，若 C 则 D…”）Agent 抽取节点与连线，生成 SVG 并保存同上
JSON spec 文件使用 render_flowchart.py --spec <spec.json> --out <out.svg>指定路径的 .svg
已有 SVG使用 validate_flowchart_style.py 做样式规范检查与修正建议不改变格式，仅校验

推荐：复杂/多列流程图优先用 JSON spec + render_flowchart.py，可保证端口偏移、分组框与中文实体编码一致。

导出为 PDF（供 LaTeX 使用）

XeLaTeX 的 \includegraphics 对 SVG 的 BoundingBox 支持有限，建议将流程图导出为 PDF 后再插入论文，可避免编译报错。

方式一：使用本技能提供的脚本（优先尝试 cairosvg，否则提示用 Inkscape）

脚本路径以仓库内 {{SKILLS_ROOT}}/svg-flowchart/scripts/ 为准（本仓库默认 .opencode/skills/svg-flowchart/scripts/）。目录占位符见仓库根目录 README.md。

python .opencode/skills/svg-flowchart/scripts/svg2pdf.py <input.svg> [output.pdf]
# 未指定 output 时，生成与 input 同名的 .pdf
python .opencode/skills/svg-flowchart/scripts/svg2pdf.py 论文章节/figures/flows/示例流程.svg

方式二：Inkscape 命令行（若已安装并加入 PATH）

inkscape --export-type=pdf "论文章节/figures/flows/流程图.svg" -o "论文章节/figures/flows/流程图.pdf"

方式三：在 Inkscape / 浏览器中打开 SVG，另存为 PDF，保存到 figures/flows/ 下与 SVG 同名。

导出 PDF 后，在 LaTeX 中使用 \includegraphics[width=...]{figures/flows/流程图.pdf} 即可。

推荐工作流（更美观、更稳定）

当流程图包含分组框/多列结构/多条汇入箭头时，优先采用脚本自动排版（可避免“箭头重叠、对齐不齐、中文乱码”等问题）：

python .opencode/skills/svg-flowchart/scripts/render_flowchart.py --spec <spec.json> --out <out.svg>

脚本会自动：

  • 按分组列布局（适合“三层数据流/三模块框图”）
  • 端口偏移（同一节点多条入边不叠在同一点）
  • 全量将中文转换为 HTML 数字实体，减少 Windows/查看器的编码坑

样式自检（可选）：生成或修改 SVG 后，可用样式检测脚本检查是否符合技能规范（配色、线条圆角、viewBox、禁止渐变/阴影等）：

python .opencode/skills/svg-flowchart/scripts/validate_flowchart_style.py <file.svg> [<file2.svg> ...]
# 严格模式（禁止 filter/阴影）：
python .opencode/skills/svg-flowchart/scripts/validate_flowchart_style.py --strict <file.svg>

检测到不规范项会列出并返回非零退出码；全部通过则输出 OK。

先收集输入（最少 6 项）

让用户用下面任一方式给信息；缺失项自行补全为合理默认，并在输出前用 1 句话声明默认假设。

  1. 标题（可空）
  2. 节点清单：每个节点 id、label、type
  3. 连线清单：from -> to，判断分支写 yes/no（或“是/否”）
  4. 方向：vertical（默认）或 horizontal
  5. 字号：默认 14（正文）/ 12（辅助）
  6. 保存路径：默认 {{THESIS_DIR}}/figures/flows/<slug>.svg（见仓库根 README.md）

可接受两种输入格式：

A. 结构化（优先）

标题：……
方向：vertical
节点：
- start: 开始 (start)
- a: 数据准备 (process)
- b: 生成速度场 (process)
- c: 是否可达？ (decision)
- d: 输出路径与时间代价矩阵 (process)
- end: 结束 (end)
连线：
- start -> a
- a -> b
- b -> c
- c(是) -> d
- c(否) -> end

B. 自然语言

把步骤、判断点、输入输出按顺序描述即可；你负责抽取成节点与连线。

绘制规范（默认学术风格）

画布与布局
  • 默认垂直布局：节点居中对齐，统一间距（推荐：gapY=40~48，避免连线与节点贴太近）
  • 尺寸策略：先按节点数估算高度，再设置 viewBox="0 0 W H"；同时 width="100%"，确保可缩放；四边留白 pad≥28
  • 单列流程优先；分支仅在 decision 节点处做左右分叉（保持对称）
多列分组版式（建议用于论文框图）
  • 列间距：col_gap=70~90，确保组框之间留白，连线不挤
  • 组框：包住全部所属节点后四周再加 20~28px 内边距；标题放在组框内左上角（比“悬在框外”更规整）
  • 连线策略：先画连线、再画节点，避免线压字；优先正交折线（elbow），多条入/出边做端口偏移
图形语义（type → 形状）
  • start/end：圆角胶囊（pill）
  • process：圆角矩形（rounded rect）
  • decision：菱形（diamond）
  • data（可选）：平行四边形（parallelogram）
线条与箭头
  • 统一线宽 stroke-width=1.5~1.6；颜色可用灰色系（#64748B、#94A3B8）或柔和的有色线（如淡蓝 #7DD3FC、淡绿 #6EE7B7、淡紫 #C4B5FD），与节点色系协调即可
  • 箭头使用 marker-end，填充与线条同色，尺寸克制（markerWidth/Height 6~7）
  • 圆角线条：stroke-linecap="round"、stroke-linejoin="round"，避免生硬直角
  • 分支线优先正交折线（elbow），必要时做端口偏移避免多线重合
配色与字体（清新学术，可淡彩）
  • 不必拘泥灰色：节点与分组可采用清新淡雅的淡彩色，低饱和、明度偏高即可，整体保持学术感
  • 推荐淡彩色板（填充用，描边取同色系深 1–2 档）：
    • 淡蓝：#E0F2FE / #BAE6FD，描边 #0EA5E9 / #0284C7
    • 淡绿：#DCFCE7 / #BBF7D0，描边 #16A34A / #15803D
    • 淡紫：#EDE9FE / #DDD6FE，描边 #7C3AED / #6D28D9
    • 淡杏/橙：#FFEDD5 / #FED7AA，描边 #EA580C / #C2410C
    • 淡青：#CFFAFE / #A5F3FC，描边 #0891B2 / #0E7490
    • 灰色系（仍可用）：节点 #F1F5F9，描边 #475569；分组 #F8FAFC，描边 #E2E8F0
  • 核心/起点节点：可用同色系稍深（如 #E0E7FF+#4F46E5）或淡彩中选一作为强调
  • 主文字：#1E293B 或深灰；辅助/边标注：#64748B 或与连线同色系
  • 字体：font-family="Microsoft YaHei UI, Microsoft YaHei, PingFang SC, Noto Sans CJK SC, Arial, sans-serif"
  • 避免高饱和、荧光色；同一图内色相不宜过多（2–3 种主色即可）
美观要点（必守）
  • 无重叠：节点与节点、文字与连线、边标注与箭头之间留足间距；先算坐标再画线
  • 端口偏移：同一节点多条入边或出边时，在节点边缘错开落点（±10~24px），避免多线叠在一点
  • 对齐规整：同列节点水平居中、垂直等距；分组框包住全部所属节点并留 20~28px 内边距
  • 中文编码：手写 SVG 时中文优先用 HTML 数字实体（如 &#x8F93;&#x5165;），或统一 UTF-8 保存，减少查看器乱码
  • viewBox 完整：宽高覆盖全部图形与边标注，四边留 pad≥24~28

生成 SVG 的步骤（务必按序）

  1. 从输入抽取 DAG：节点、连线、分支标签（是/否）
  2. 确定布局参数：节点宽高（默认 w=320, h=56），边距（pad=28），间距
  3. 计算坐标：
    • 单列：x = (W-w)/2，y = pad + i*(h+gapY)
    • 分支：在菱形后拆成左右两列（xLeft/xRight），并在汇合处回到主列
  4. 输出 SVG：<defs>（marker + CSS）→ 先画连线 → 再画分组框（若有）→ 再画节点（避免线压字）
  5. 保存文件：按用户/默认路径写入 .svg
  6. 回传：给出保存路径 + SVG 代码（便于用户复制）

输出模板（直接复用）

生成 SVG 时遵循此骨架（可增删）；配色可采用灰色系或清新淡彩（见上节色板），下例为淡蓝主色示例：

<svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 900 700">
  <defs>
    <style>
      .node { fill:#E0F2FE; stroke:#0EA5E9; stroke-width:1.5; }
      .node-core { fill:#BAE6FD; stroke:#0284C7; stroke-width:1.6; }
      .node-decision { fill:#EDE9FE; stroke:#7C3AED; stroke-width:1.5; }
      .label { fill:#1E293B; font-size:14px; font-family:Microsoft YaHei UI, Microsoft YaHei, PingFang SC, Noto Sans CJK SC, Arial, sans-serif; }
      .label-sub { fill:#64748B; font-size:12px; font-family:Microsoft YaHei UI, Microsoft YaHei, PingFang SC, Noto Sans CJK SC, Arial, sans-serif; }
      .edge { fill:none; stroke:#0EA5E9; stroke-width:1.5; stroke-linecap:round; stroke-linejoin:round; }
      .edge-label { fill:#475569; font-size:12px; font-family:Microsoft YaHei UI, Microsoft YaHei, PingFang SC, Noto Sans CJK SC, Arial, sans-serif; }
      .group { fill:#F0F9FF; stroke:#7DD3FC; stroke-width:1.2; }
      .group-title { fill:#0369A1; font-size:13px; font-weight:600; font-family:Microsoft YaHei UI, Microsoft YaHei, PingFang SC, Noto Sans CJK SC, Arial, sans-serif; }
    </style>
    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 z" fill="#0EA5E9"/>
    </marker>
  </defs>
  <!-- edges first -->
  <!-- groups (optional) -->
  <!-- nodes -->
</svg>

灰色系版本：节点 fill:#F1F5F9; stroke:#475569，连线 stroke:#64748B，分组 fill:#F8FAFC; stroke:#E2E8F0。

质量自检（输出前 10 秒检查）

  • 无重叠：节点与节点、文字与连线、边标注与箭头之间无压盖；必要时增大 gap 或平移标注
  • 节点对齐与间距一致，文本不溢出（长标签换行：<tspan x="..." dy="...">）
  • 箭头方向正确，分支线清晰，分支标签靠近对应边；多入/多出时使用端口偏移
  • viewBox 覆盖全部内容且四边留白（无裁切）
  • 风格克制：无渐变、无阴影、线条圆角（stroke-linecap/join round），配色低饱和（灰色或清新淡彩均可）

可选：对生成的 SVG 运行 validate_flowchart_style.py 做样式规范检测，确保无遗漏。

示例

需要样例参考时，见 examples.md。

Comments

Markdown supported