structviz 0.2

声明式股权图与组织架构图生成工具 — YAML 驱动，D2/Graphviz/Excalidraw 三引擎

StructViz

声明式股权图与组织架构图生成工具。YAML 定义结构，一键输出 PNG / PDF / SVG / HTML / Excalidraw 图表。

双引擎：D2（直角线 SVG） + Graphviz DOT（自动布局） + Excalidraw（精确定位）。

安装

# D2 引擎
sudo pacman -S d2              # Arch
# 或从 https://github.com/terrastruct/d2/releases 下载

# DOT 引擎
sudo pacman -S graphviz        # Arch
sudo apt install graphviz      # Debian

# Python 包
pip install structviz

快速开始

# D2 引擎（直角线 SVG）
structviz examples/org_siku.yaml -t org -f d2 -o output/

# DOT 引擎
structviz examples/org_bingong.yaml -t org -f png,pdf -p a4 -o output/

# Excalidraw 引擎
structviz examples/org_bingong.yaml -t org -f excalidraw -o output/

# 股权图
structviz examples/equity_sample.yaml -t equity -f png -o output/

CLI

structviz YAML_FILE [OPTIONS]

Options:
  -t, --type [equity|org]   图表类型 (必填)
  -f, --formats TEXT        输出格式: png,pdf,svg,html,excalidraw,d2
  -o, --output TEXT         输出目录
  -p, --papersize TEXT      纸张: a4|a3|letter 或自定义 "W,H[mm|in]"
  -d, --dpi INTEGER         输出 DPI

YAML 结构

组织架构图 (org)

meta:
  type: org
  title: "组织架构"
  theme: corporate
  papersize: a4
  dpi: 150
  layout:                    # 全局布局参数
    max_columns: 3           # 底族每行最多数
    nodesep: 0.3             # 同行节点间距 (英寸)
    ranksep: 0.6             # 行间距 (英寸)
    block_pad: 0.15          # block 内边距
    row_gap: 1               # 换行间距 (minlen)
    # D2 专用
    deputy_gap: 40           # 中心领导框内间距
    wrap_width: 12           # 部门名自动换行宽度（0=不换）
    dept_gap: 6              # 板块内部门间距
    dept_width: 150          # 部门节点宽度

groups:
  - level: 0
    label: "权力机构"
    gap: 0.8                 # 到下层间距
    nodes:
      - id: 股东大会
        title: "股东大会"
        style: large         # large | default | external

  - level: 1
    label: "决策层"
    blocks:
      - id: 专业委员会
        position: right      # right=同行右侧 | bottom=下一行 | left=同行左侧
        max_columns: 3       # 块内每行节点数
        block_align: left    # left | center
        edge_from: 董事会    # 箭头到块边框
        nodes:
          - id: 战略委员会
            title: "战略委员会"

  - level: 2
    gap: 1.5
    nodesep: 3               # 本层节点间距 (覆盖全局)
    nodes:
      - id: 业务运营
        title: "业务运营"
        style: large
        reports_to: 总经理   # 自动连线

  - level: 3
    blocks:
      - id: 业务运营板块
        position: bottom
        max_columns: 2
        edge_from: 业务运营
        nodes:
          - id: 债贷业务部
            title: "债贷业务部"

OrgNode 字段

字段	说明
id	唯一标识
title	显示标题，\n 换行
name	副标题 (可选)
role	小字职务 (可选)
style	large(居中加粗) / default / external(橙色)
reports_to	上级节点 id
is_cluster_head	板块标题 (仅 block 内)

OrgGroup 布局参数

字段	说明
gap	到下层垂直间距
offset	水平偏移 (英寸)
nodesep	本层节点间距 (覆盖全局)
max_columns	blocks 每行数 (覆盖全局)
max_right_columns	right_nodes 每行数

OrgBlock 字段

字段	说明
position	right / bottom / left
max_columns	块内每行节点数
row_gap	块内换行间距 (minlen)
block_align	left / center
edge_from	箭头源节点 id

纸张尺寸

预设	尺寸
a4	210×297mm
a3	297×420mm
letter	8.5×11in
自定义	"200,260" (mm) 或 "8.5,11in"

输出文件

引擎	格式	文件
D2	d2	name.d2 (源码) + name_d2.svg
DOT	png, pdf, svg	name.png, name.svg
DOT	html	name.html
Excalidraw	excalidraw	name.excalidraw + name_ex.png

项目结构

structviz/
├── pyproject.toml
├── README.md
├── examples/
│   ├── equity_sample.yaml
│   ├── org_siku.yaml
│   └── org_bingong.yaml
└── structviz/
    ├── models.py               # Pydantic 模型
    ├── themes.py               # 主题 + 纸张
    ├── cli.py                  # CLI 入口
    ├── render.py               # DOT 渲染
    ├── d2_render.py            # D2 渲染 + 直角后处理
    ├── html_wrapper.py         # HTML 包装
    ├── excalidraw_render.py    # Excalidraw → PNG
    └── generators/
        ├── equity.py           # 股权图 DOT
        ├── org.py              # 组织架构 DOT
        ├── d2.py               # 组织架构 D2
        └── excalidraw.py       # 组织架构 Excalidraw

许可

MIT