目录生成知识图谱工具

catalog-generate-knowledge-graph

将层级化的知识结构数据（JSON / YAML / Markdown）渲染为放射状知识图谱图片。支持多层级节点、自动布局防重叠、分支配色、中文显示，输出 PNG 或 SVG 格式。

生成案例图参考：assets/product_data_analysis.png

功能特性

三种输入格式：JSON、YAML、Markdown 无序列表，自动识别
放射状布局：基于极坐标递归分区算法，按叶子节点数加权分配角度
文字零重叠：使用 matplotlib 实际渲染测量文字宽高 + AABB 矩形碰撞检测 + 自适应缩字
分支配色：一级分支自动分配主色调，连线跟随分支颜色，文字统一黑色
层级字号：一级 9pt 加粗 / 二级 7pt / 三级 6pt，冲突时自动缩字（最小 5pt）
中文支持：自动检测 Windows 系统字体（微软雅黑 / 黑体 / 宋体）
两种主题：明亮（default）、暗黑（dark）
两种输出：PNG（位图）、SVG（矢量图）
层级截断：支持限制最大展示深度

快速开始

安装依赖

pip install matplotlib pyyaml

生成第一张图谱

python scripts/main.py --input examples/sample_input.json --size 3000

输出图片默认保存到：

D:\catalog-generate-knowledge-graph\output\kg_output.png

指定输出文件名

python scripts/main.py --input examples/sample_input.json --output D:/catalog-generate-knowledge-graph/output/my_graph.png --size 3000

命令行参数

| 参数 | 短参 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|------|--------|------| | --input | -i | string | 是 | - | 输入数据文件路径（JSON / YAML / Markdown） | | --output | -o | string | 否 | D:\catalog-generate-knowledge-graph\output\kg_output.png | 输出图片路径 | | --theme | -t | string | 否 | default | 配色主题：default / dark | | --format | -f | string | 否 | png | 输出格式：png / svg | | --depth | -d | int | 否 | 0 | 最大展示层级，0 表示不限制 | | --size | -s | int | 否 | 2500 | 画布目标尺寸（像素） |

输入数据格式

JSON（推荐）

{
  "name": "产品数据分析",
  "children": [
    {
      "name": "数据分析概述",
      "children": [
        {
          "name": "数据分析认知",
          "children": [
            { "name": "数据分析概念" },
            { "name": "数据分析对象" },
            { "name": "基本流程" }
          ]
        }
      ]
    },
    {
      "name": "顾客数据分析",
      "children": [
        { "name": "顾客画像" },
        { "name": "会员数据分析" }
      ]
    }
  ]
}

YAML

name: 产品数据分析
children:
  - name: 数据分析概述
    children:
      - name: 数据分析认知
        children:
          - name: 数据分析概念
          - name: 数据分析对象
  - name: 顾客数据分析
    children:
      - name: 顾客画像
      - name: 会员数据分析

Markdown

- 产品数据分析
  - 数据分析概述
    - 数据分析认知
      - 数据分析概念
      - 数据分析对象
  - 顾客数据分析
    - 顾客画像
    - 会员数据分析

Markdown 格式要求每级缩进 2 个空格，使用 - 作为列表标记。

字段说明

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | 是 | 节点显示名称（根节点也可用 center / title） | | color | string | 否 | 节点自定义背景色，HEX 格式如 #8BC34A | | children | array | 否 | 子节点列表，为空则为叶子节点 |

使用示例

基础用法

python scripts/main.py --input examples/sample_input.json --size 3000

限制展示层级

python scripts/main.py --input data.json --depth 2 --size 2500

暗黑主题 + SVG 矢量图

python scripts/main.py --input data.json --output graph.svg --theme dark --format svg

使用 Markdown 输入

python scripts/main.py --input outline.md --output my_kg.png --size 3000

渲染规则

| 元素 | 样式 | |------|------| | 中心节点 | 浅蓝圆形背景（#E3F2FD），黑色加粗文字，深蓝边框 | | 一级节点 | 浅色圆角矩形背景（分支色 + 透明度），黑色加粗文字 | | 二级节点 | 彩色圆点（半径 = 字号 x 0.5）+ 紧贴黑色文字，无背景 | | 三级节点 | 同二级，字号略小 | | 连线 | 贝塞尔曲线，颜色跟随分支主色调 | | 画布 | 浅灰背景（#F5F7FA），自动居中 + 缩放 |

防重叠机制

文字测量：使用 matplotlib 实际渲染获取文字真实宽高（非经验估算）
碰撞检测：AABB 矩形重叠检测，沿重叠较小的轴推开
自适应缩字：冲突时按层级优先缩小三级节点，最小至 5pt
多轮迭代：最多 300 轮迭代排斥，缩放后二次检测

自定义主题

编辑 templates/style_config.json 可自定义：

中心节点样式（背景色、文字色、字号、圆半径、边框）
分支配色方案（15 种颜色循环）
节点样式（透明度、文字色、字号范围、圆角、边距、边框）
连线样式（粗细、透明度、线型）
画布样式（背景色、边距、DPI）

文件结构

catalog-generate-knowledge-graph/
├── SKILL.md                        # Skill 描述文件
├── README.md                       # 本文件
├── scripts/
│   ├── main.py                     # 统一入口（命令行参数解析）
│   ├── parser.py                   # 数据解析器（JSON / YAML / Markdown）
│   ├── layout.py                   # 布局引擎（极坐标布局 + 碰撞检测 + 缩字）
│   └── renderer.py                 # 渲染引擎（matplotlib 绘制 + 文字测量）
├── templates/
│   └── style_config.json           # 主题配色配置
├── examples/
│   └── sample_input.json           # 示例数据（产品数据分析）
└── assets/
    └── product_data_analysis.png   # 生成案例图

技术栈

Python 3.8+
matplotlib（渲染引擎）
PyYAML（YAML 输入解析）

注意事项

中文显示：自动检测 Windows 系统字体。若出现方框字，请确认 C:\Windows\Fonts\msyh.ttc 存在。
画布尺寸：节点较多时建议 --size 3000 或更大；--size 过小会导致缩放后文字密集。
长文本：节点名称建议控制在 15 字以内，过长会自动缩小字号但可能影响可读性。
默认输出目录：D:\catalog-generate-knowledge-graph\output\，运行时自动创建。
大图性能：100+ 节点时渲染约 3-5 秒，主要耗时在文字测量和碰撞检测迭代。