Thesis Flowchart / 论文流程图 Skill

English | 中文

English

thesis-flowchart is a Codex skill for creating deterministic, editable, thesis-ready flowcharts from structured JSON. It favors clear academic diagrams over decorative or generative imagery.

Features

• Generates editable SVG with a white background and academic black-and-white styling.
• Supports terminators, processes, decisions, input/output nodes, and subprocesses.
• Handles English, Chinese, and mixed-language labels in UTF-8.
• Validates decision branches, text fit, node overlap, connector routing, and typography references.
• Exports 300-DPI PNG and vector PDF when an optional converter is available.
• Includes English and Chinese examples plus automated tests.

Preview Examples

Research Workflow

Algorithm Iteration Workflow

System Workflow

Why These Shapes Are Used

Flowchart symbols carry meaning. Using standard symbols lets a reader understand the logic before reading every label.

Node type	Shape	Meaning
start / end	Rounded terminator	Marks where the process begins or ends.
process	Rectangle	Represents an action, method step, calculation, or transformation.
decision	Diamond	Represents a condition that branches into Yes/No or equivalent outcomes.
io	Parallelogram	Represents data or user input and generated output.
subprocess	Rectangle with double vertical sides	Represents a reusable module, subroutine, or independently defined procedure.

Arrows show process direction. Every binary decision should have two clearly labeled outgoing branches. In a vertical chart, the main or Yes branch normally continues downward while the No branch moves sideways or loops back.

Requirements

• Python 3.10 or later.
• No third-party package is required for SVG generation and validation.
• PNG/PDF export uses Inkscape when available, then falls back to the optional Python packages in requirements.txt.

Install As A Codex Skill

Place the complete thesis-flowchart folder in your Codex skills directory:

Windows: %USERPROFILE%\.codex\skills\thesis-flowchart
macOS/Linux: ~/.codex/skills/thesis-flowchart

Restart Codex after installation. You can then invoke it explicitly with prompts such as:

Use $thesis-flowchart to turn my thesis method into an editable Chinese SVG flowchart.

Quick Start

Generate and validate an English example:

python scripts/generate_flowchart.py --spec examples/en/simple_research.json --out out/simple_research_en.svg
python scripts/validate_flowchart.py --spec examples/en/simple_research.json --svg out/simple_research_en.svg

Generate and validate a Chinese example:

python scripts/generate_flowchart.py --spec examples/zh/simple_research.json --out out/simple_research_zh.svg
python scripts/validate_flowchart.py --spec examples/zh/simple_research.json --svg out/simple_research_zh.svg

Run the complete test suite and regenerate all bundled examples:

python scripts/test_flowchart_scripts.py
python scripts/run_examples.py out/examples

PNG And PDF Export

Install optional export dependencies:

python -m pip install -r requirements.txt

Then export from the same JSON source:

python scripts/generate_flowchart.py --spec examples/en/simple_research.json --out out/simple_research.png --format png --dpi 300
python scripts/generate_flowchart.py --spec examples/en/simple_research.json --out out/simple_research.pdf --format pdf

Always inspect exported PNG/PDF files because font availability and SVG converters vary across operating systems.

JSON Format

{
  "title": "algorithm_flow",
  "orientation": "vertical",
  "font_size_pt": 10.5,
  "nodes": [
    {"id": "start", "type": "start", "label": "Start"},
    {"id": "read", "type": "process", "label": "Read experimental data"},
    {"id": "valid", "type": "decision", "label": "Data valid?"},
    {"id": "end", "type": "end", "label": "End"}
  ],
  "edges": [
    {"from": "start", "to": "read"},
    {"from": "read", "to": "valid"},
    {"from": "valid", "to": "end", "label": "Yes"},
    {"from": "valid", "to": "read", "label": "No", "kind": "loop"}
  ]
}

Allowed node types are start, end, process, decision, subprocess, and io. Use vertical or horizontal for orientation. Explicit row and col values may be added to nodes when automatic placement is not sufficient.

Repository Layout

thesis-flowchart/
  .github/workflows/ci.yml
  agents/openai.yaml
  examples/en/
  examples/zh/
  preview/en/
  preview/zh/
  references/
  scripts/
  SKILL.md
  README.md
  LICENSE

Contributing And License

Contributions are welcome. Read CONTRIBUTING.md before submitting a change. This project is released under the MIT License, which permits use, modification, distribution, and commercial use while requiring preservation of the copyright and license notice.

---

中文

thesis-flowchart 是一个用于绘制论文流程图的 Codex skill。它把结构化 JSON 转换成确定性、可编辑、适合论文排版的流程图，强调规范和可复现，而不是装饰性或随机生成效果。

主要功能

• 生成白色背景、黑白学术风格的可编辑 SVG。
• 支持开始/结束、处理、判断、输入/输出和子流程节点。
• 支持中文、英文以及中英混排标签，统一使用 UTF-8。
• 检查判断分支、文字溢出、节点重叠、连线路由和字体引用。
• 在安装可选转换工具后，可导出 300 DPI PNG 和矢量 PDF。
• 内置中英文示例和自动化测试。

中文图片示例

论文研究流程

算法迭代流程

系统流程

为什么使用这些形状

流程图中的形状本身带有语义。规范使用形状，可以让读者在逐字阅读之前先理解整体逻辑。

节点类型	形状	含义
start / end	圆角终止框	表示流程开始或结束。
process	矩形	表示操作、方法步骤、计算或数据处理。
decision	菱形	表示需要判断的条件，并分成“是/否”等分支。
io	平行四边形	表示数据输入、用户输入或结果输出。
subprocess	带双竖线的矩形	表示可复用模块、子程序或单独定义的处理过程。

箭头表示执行方向。二元判断节点必须有两条标注清楚的输出分支。纵向流程图通常让主分支或“是”分支向下继续，让“否”分支向侧面移动或回到前面的步骤。

英文 Skill 会影响中文流程图吗

不会。SKILL.md 使用英文，是为了让不同语言环境中的 Codex 更稳定地识别和执行规则；真正显示在图中的文字来自 JSON 的 label 字段。只要 JSON 文件保存为 UTF-8，中文节点、中文“是/否”分支和中英混排都可以正常生成。仓库还提供了独立的中文示例和自动化测试，专门检查中文不会变成 ???。

环境要求

• Python 3.10 或更高版本。
• 生成和检查 SVG 不需要安装第三方软件包。
• 导出 PNG/PDF 时优先使用 Inkscape，也可以使用 requirements.txt 中的可选 Python 软件包。

安装为 Codex Skill

把完整的 thesis-flowchart 文件夹放入 Codex skills 目录：

Windows: %USERPROFILE%\.codex\skills\thesis-flowchart
macOS/Linux: ~/.codex/skills/thesis-flowchart

安装后重启 Codex。之后可以这样调用：

使用 $thesis-flowchart，把我的毕业论文方法流程整理为可编辑的中文 SVG 流程图。

快速使用

生成并检查中文示例：

python scripts/generate_flowchart.py --spec examples/zh/simple_research.json --out out/simple_research_zh.svg
python scripts/validate_flowchart.py --spec examples/zh/simple_research.json --svg out/simple_research_zh.svg

运行全部测试并重新生成所有示例：

python scripts/test_flowchart_scripts.py
python scripts/run_examples.py out/examples

安装可选导出组件并导出 PNG/PDF：

python -m pip install -r requirements.txt
python scripts/generate_flowchart.py --spec examples/zh/simple_research.json --out out/simple_research_zh.png --format png --dpi 300
python scripts/generate_flowchart.py --spec examples/zh/simple_research.json --out out/simple_research_zh.pdf --format pdf

由于不同系统的字体和转换工具可能不同，导出的 PNG/PDF 仍应人工打开检查一次。

中文 JSON 示例

{
  "title": "paper_method_flow",
  "orientation": "vertical",
  "font_size_pt": 10.5,
  "nodes": [
    {"id": "start", "type": "start", "label": "开始"},
    {"id": "collect", "type": "process", "label": "收集实验数据"},
    {"id": "valid", "type": "decision", "label": "数据有效？"},
    {"id": "end", "type": "end", "label": "结束"}
  ],
  "edges": [
    {"from": "start", "to": "collect"},
    {"from": "collect", "to": "valid"},
    {"from": "valid", "to": "end", "label": "是"},
    {"from": "valid", "to": "collect", "label": "否", "kind": "loop"}
  ]
}

允许的节点类型为 start、end、process、decision、subprocess 和 io。orientation 可设置为 vertical 或 horizontal。自动排版不能满足要求时，也可以为节点增加明确的 row 和 col。

贡献与开源协议

欢迎提交改进。参与贡献前请阅读 CONTRIBUTING.md。本项目采用 MIT License，允许使用、修改、分发和商业使用，但必须保留原版权声明和许可证文本。