科研技能库/FigureSpec:确定性 JSON 转 SVG 图形生成
图表可视化

FigureSpec:确定性 JSON 转 SVG 图形生成

从结构化 JSON(FigureSpec)确定性生成可编辑的 SVG 出版物级架构图、工作流程图和管道图。适用于用户提及“架构图”“workflow 图”“pipeline 图”“确定性矢量图”等场景,或需要精确、可编辑、出版准备的矢量图表时。推荐用于正式的架构/工作流图形,优先于 AI 插图。

文件预览

1 个文件
SKILL.md
10.6 KB · 可预览
---
name: figure-spec
description: "Generate deterministic publication-quality architecture, workflow, and pipeline diagrams from structured JSON (FigureSpec) into editable SVG. Use when user says \"架构图\", \"workflow 图\", \"pipeline 图\", \"确定性矢量图\", \"figure spec\", \"draw architecture\", or needs precise, editable, publication-ready vector diagrams. Preferred over AI illustration for formal architecture/workflow figures."
argument-hint: [description-of-diagram]
allowed-tools: Bash(*), Read, Write, Edit
---

# FigureSpec: Deterministic JSON → SVG Figure Generation

Generate publication-quality **architecture diagrams**, **workflow pipelines**, **audit cascades**, and **system topology** figures as editable SVG vector graphics using a deterministic JSON → SVG renderer.

## When to Use This Skill

**Use `figure-spec`** for:
- System architecture diagrams (layered, hub-and-spoke, multi-plane)
- Workflow / pipeline figures
- Audit cascade / flow-control diagrams
- Any structured diagram where node positions, connections, and groupings are semantically important
- Figures that need to be edited/tweaked later (SVG is plain text)
- Figures where determinism matters (same spec → same SVG)

**Do NOT use for:**
- Data plots (bar/line/scatter) — use `/paper-figure`
- Natural/qualitative illustrations — use `/paper-illustration`
- Quick state-machine / flowchart — use `/mermaid-diagram` (lighter syntax)

## Core Properties

- **Deterministic**: identical FigureSpec JSON always produces identical SVG output (for a fixed renderer version + fonts)
- **Editable**: SVG output is plain-text, can be post-edited by hand or programmatically
- **Validated**: renderer enforces schema, rejects malformed specs with clear error messages
- **Shape-aware**: edge clipping works correctly for rect/rounded/circle/ellipse/diamond
- **CJK support**: multi-line labels with proper Chinese character width estimation
- **No external API**: runs fully local, no network, no API keys

## Tool Location

Phase 3.1 (Arch C) move: the canonical implementation now lives at
`skills/figure-spec/scripts/figure_renderer.py`. `tools/figure_renderer.py`
is kept as a backwards-compatible `os.execv` shim so legacy layers
continue to resolve. Codex-side install layouts that previously
copied the canonical into `~/.codex/skills/figure-spec/figure_renderer.py`
must now place it at `~/.codex/skills/figure-spec/scripts/figure_renderer.py`
to match the new layout (re-run `install_aris_codex.sh` to pick up
the new symlink target).

Resolve `$FIGURE_RENDERER` via the Codex-side hybrid chain (layer 0
preferred for self-contained owner SKILL; layers 1-4 are legacy
shared-runtime compatibility):

```bash
# Layer 0: self-contained at the new canonical location (Phase 3.1).
FIGURE_RENDERER=""
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
fi
[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/skills/figure-spec/scripts/figure_renderer.py" ] && FIGURE_RENDERER="$ARIS_REPO/skills/figure-spec/scripts/figure_renderer.py"

# Layers 1-3: legacy shared-runtime chain via shim at tools/figure_renderer.py.
[ -z "$FIGURE_RENDERER" ] && [ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/figure_renderer.py" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"
[ -z "$FIGURE_RENDERER" ] && [ -f tools/figure_renderer.py ] && FIGURE_RENDERER="tools/figure_renderer.py"

# Layer 4: Codex-side skill-local install (`install_aris_codex.sh` may place it here).
[ -z "$FIGURE_RENDERER" ] && [ -f ~/.codex/skills/figure-spec/scripts/figure_renderer.py ] && FIGURE_RENDERER="$HOME/.codex/skills/figure-spec/scripts/figure_renderer.py"
[ -z "$FIGURE_RENDERER" ] && [ -f ~/.codex/skills/figure-spec/figure_renderer.py ] && FIGURE_RENDERER="$HOME/.codex/skills/figure-spec/figure_renderer.py"  # pre-Phase-3.1 layout

[ -n "$FIGURE_RENDERER" ] || {
  echo "ERROR: figure_renderer.py not found at any of: \$ARIS_REPO/skills/figure-spec/scripts/, \$ARIS_REPO/tools/, tools/, ~/.codex/skills/figure-spec/scripts/, ~/.codex/skills/figure-spec/. Set ARIS_REPO, rerun install_aris_codex.sh, or copy the canonical \$ARIS_REPO/skills/figure-spec/scripts/figure_renderer.py next to this skill." >&2
  exit 1
}

python3 "$FIGURE_RENDERER" render <spec.json> --output <out.svg>
python3 "$FIGURE_RENDERER" validate <spec.json>
python3 "$FIGURE_RENDERER" schema
```

## Workflow

### Step 1: Understand the Diagram Goal

From `$ARGUMENTS` (description or path to `PAPER_PLAN.md` / `NARRATIVE_REPORT.md`), identify:
- **Purpose**: architecture, workflow, pipeline, audit cascade, topology?
- **Main entities**: what are the boxes?
- **Relationships**: how do they connect? (uses, produces, calls, verifies, chains)
- **Grouping**: do entities cluster into named regions?
- **Hierarchy vs network**: stacked layers, left-to-right flow, or central hub?

### Step 2: Draft the FigureSpec JSON

Canvas sizing guide:
- Single-column figure: ~500×350 px
- Two-column (full-width): ~900×500 px
- Tall topology: ~700×700 px

Start from a template based on the diagram type:

**Architecture (stacked rows)**:
```json
{
  "canvas": {"width": 900, "height": 520},
  "nodes": [
    {"id": "layer1_label", "label": "Layer 1", "x": 450, "y": 60, ...},
    {"id": "node_a", "label": "A", "x": 180, "y": 120, ...},
    {"id": "node_b", "label": "B", "x": 350, "y": 120, ...}
  ],
  "edges": [...],
  "groups": [
    {"label": "Layer 1", "node_ids": ["node_a", "node_b"], "fill": "#F0F9FF", "stroke": "#BAE6FD"}
  ]
}
```

**Workflow (left-to-right chain)**:
```json
{
  "canvas": {"width": 900, "height": 300},
  "nodes": [
    {"id": "step1", "label": "Step 1", "x": 100, "y": 150, "shape": "rounded"},
    {"id": "step2", "label": "Step 2", "x": 280, "y": 150, "shape": "rounded"}
  ],
  "edges": [
    {"from": "step1", "to": "step2", "label": "produces"}
  ]
}
```

**Decision diamond**:
```json
{"id": "check", "label": "Passes?", "shape": "diamond", "x": 450, "y": 200}
```

### Step 3: Render and Validate

```bash
# Validate first
python3 "$FIGURE_RENDERER" validate /tmp/spec.json

# Render to SVG
python3 "$FIGURE_RENDERER" render /tmp/spec.json --output figures/fig_arch.svg

# Convert to PDF for LaTeX inclusion
rsvg-convert -f pdf figures/fig_arch.svg -o figures/fig_arch.pdf
```

If validation fails, inspect the error (missing field, duplicate ID, overlap warning, invalid hex color) and fix the JSON.

### Step 4: Visual Review

Open the SVG/PDF and check:
- **No overlaps**: nodes don't collide with each other or group boundaries
- **Readability**: font sizes are consistent, labels aren't clipped
- **Edge clarity**: arrows hit nodes at clean angles, labels near edges are legible
- **Group alignment**: background rectangles frame their members cleanly
- **Color distinction**: categories are visually distinct in both color and grayscale

If issues found, edit the JSON spec (never the generated SVG) and re-render.

### Step 5: Iterate with Codex Review (Optional, for High-Stakes Figures)

For paper architecture figures, invoke cross-model review:

```text
spawn_agent:
  model: gpt-5.5
  reasoning_effort: xhigh
  message: |
    Review this SVG figure for a technical paper (architecture / workflow diagram).

    Spec file: /path/to/spec.json
    Rendered: /path/to/fig.svg

    Evaluate:
    1. Clarity (C): can a reader understand the system from this figure alone?
    2. Readability (R): font sizes, label placement, visual hierarchy
    3. Semantic accuracy (S): do relationships match the described system?

    Score each axis 1-10 and list specific issues to fix.
```

Iterate until all three axes ≥ 7/10. The ARIS tech report figures went through 5 rounds of this loop to reach C:7/R:7/S:8.

## Schema Quick Reference

Run `python3 "$FIGURE_RENDERER" schema` for the authoritative schema.

### Nodes

| Field | Required | Default | Notes |
|-------|----------|---------|-------|
| `id` | ✓ | — | Unique |
| `label` | ✓ | — | `\n` for multi-line |
| `x`, `y` | ✓ | — | Center coordinates |
| `width`, `height` | | 120, 50 | |
| `shape` | | `rounded` | `rect` / `rounded` / `circle` / `ellipse` / `diamond` |
| `fill`, `stroke` | | auto from palette | `#RRGGBB` |
| `text_color` | | `#333333` | |
| `font_size` | | 14 | Override style default |

### Edges

| Field | Default | Notes |
|-------|---------|-------|
| `from`, `to` | required | Same = self-loop |
| `label` | — | Short edge label |
| `style` | `solid` | `solid` / `dashed` / `dotted` |
| `color` | `#555555` | |
| `curve` | `false` | Curved path |

### Groups

Rectangular background regions framing a set of nodes:
```json
{"label": "Layer Name", "node_ids": ["a", "b", "c"], "fill": "#EFF6FF", "stroke": "#BFDBFE"}
```

## Design Patterns

### Pattern 1: Layered Architecture
Stack rows of related nodes, each row is a group, add inter-layer arrows with semantic labels (`uses↓`, `produces↑`, `checks↓`).

### Pattern 2: Hub-and-Spoke
Central node (e.g., Executor), peripheral nodes (skills, tools), solid arrows for primary relations, dashed for feedback.

### Pattern 3: Pipeline with Feedback
Left-to-right main flow, feedback arrows curve below with `curve: true`.

### Pattern 4: Audit Cascade
Three-stage horizontal cascade with inputs feeding in from top, outputs exiting right, each stage in its own group.

## Anti-Patterns

- **Don't use groups as hierarchy**: groups frame peer nodes, not containment
- **Don't nest groups**: renderer draws them as background rectangles; nested groups look like Russian dolls
- **Don't cross-draw long diagonals**: if an arrow crosses 3+ rows, rethink the layout
- **Don't mix font sizes for same role**: keep one size per node category

## Output Contract

- SVG file in `figures/` (vector, editable, hand-tweakable)
- Source FigureSpec JSON saved in `figures/specs/` for reproducibility
- PDF version via `rsvg-convert` for LaTeX inclusion

## Integration with Other Skills

- **`/paper-writing`** (Workflow 3): when `illustration: figurespec` (default for architecture figures), this skill handles Phase 2b
- **`/paper-figure`**: handles data plots; they complement each other (data + architecture = complete figure set)
- **`/paper-illustration`**: fallback for figures that need natural/qualitative style (method illustrations with photos, qualitative result grids)
- **`/mermaid-diagram`**: lighter alternative for simple flowcharts

## Review Tracing

After each reviewer agent call, save the trace following `shared-references/review-tracing.md` (Policy C — forensic; never silently skip). Use `save_trace.sh` (resolved per the chain in `shared-references/integration-contract.md` §2) or write files directly to `.aris/traces/<skill>/<date>_run<NN>/`. Respect the `--- trace:` parameter (default: `full`).

SKILL.md

元数据
namefigure-spec
description从结构化 JSON(FigureSpec)确定性生成可编辑的 SVG 出版物级架构图、工作流程图和管道图。适用于用户提及“架构图”“workflow 图”“pipeline 图”“确定性矢量图”等场景,或需要精确、可编辑、出版准备的矢量图表时。推荐用于正式的架构/工作流图形,优先于 AI 插图。
argument-hint["图表描述"]
allowed-toolsBash(*), Read, Write, Edit

FigureSpec:确定性 JSON → SVG 图形生成

通过确定性 JSON → SVG 渲染器,生成出版级质量的架构图、工作流管道、审计级联和系统拓扑图作为可编辑的 SVG 矢量图形。

何时使用本技能

在以下场景使用 figure-spec:

  • 系统架构图(分层、中心辐射型、多平面)
  • 工作流 / 管道图
  • 审计级联 / 流控图
  • 任何节点位置、连接和分组具有语义重要性的结构化图表
  • 需要后续编辑/调整的图表(SVG 是纯文本)
  • 要求确定性的图表(相同规格 → 相同 SVG)

请勿用于:

  • 数据图(柱形/折线/散点)—— 使用 /paper-figure
  • 自然/定性插图 —— 使用 /paper-illustration
  • 快速状态机/流程图 —— 使用 /mermaid-diagram(语法更轻量)

核心特性

  • 确定性:相同的 FigureSpec JSON 总是产生相同的 SVG 输出(在固定渲染器版本和字体下)
  • 可编辑:SVG 输出为纯文本,可手工或程序化后编辑
  • 验证:渲染器强制执行模式,拒绝格式错误的规格并给出清晰错误消息
  • 形状感知:边裁剪对矩形/圆角/圆形/椭圆/菱形正确处理
  • CJK 支持:多行标签并正确估计中文字符宽度
  • 无外部 API:完全本地运行,无网络,无需 API 密钥

工具位置

阶段 3.1(Arch C)迁移:规范实现现在位于 skills/figure-spec/scripts/figure_renderer.py。tools/figure_renderer.py 作为向后兼容的 os.execv 垫片保留,以便旧层继续解析。此前将规范版本复制到 ~/.codex/skills/figure-spec/figure_renderer.py 的 Codex 侧安装布局,现在必须将其放置在 ~/.codex/skills/figure-spec/scripts/figure_renderer.py 以匹配新布局(重新运行 install_aris_codex.sh 以获取新的符号链接目标)。

通过 Codex 侧混合链解析 $FIGURE_RENDERER(对于自包含所有者 SKILL 首选第 0 层;第 1-4 层为传统共享运行时兼容性):

bash
# 第 0 层:自包含于新规范位置(阶段 3.1)。
FIGURE_RENDERER=""
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
fi
[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/skills/figure-spec/scripts/figure_renderer.py" ] && FIGURE_RENDERER="$ARIS_REPO/skills/figure-spec/scripts/figure_renderer.py"

# 第 1-3 层:通过 tools/figure_renderer.py 垫片的传统共享运行时链。
[ -z "$FIGURE_RENDERER" ] && [ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/figure_renderer.py" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"
[ -z "$FIGURE_RENDERER" ] && [ -f tools/figure_renderer.py ] && FIGURE_RENDERER="tools/figure_renderer.py"

# 第 4 层:Codex 侧技能本地安装(`install_aris_codex.sh` 可能将其放置在此)。
[ -z "$FIGURE_RENDERER" ] && [ -f ~/.codex/skills/figure-spec/scripts/figure_renderer.py ] && FIGURE_RENDERER="$HOME/.codex/skills/figure-spec/scripts/figure_renderer.py"
[ -z "$FIGURE_RENDERER" ] && [ -f ~/.codex/skills/figure-spec/figure_renderer.py ] && FIGURE_RENDERER="$HOME/.codex/skills/figure-spec/figure_renderer.py"  # 阶段 3.1 之前的布局

[ -n "$FIGURE_RENDERER" ] || {
  echo "ERROR: figure_renderer.py not found at any of: \$ARIS_REPO/skills/figure-spec/scripts/, \$ARIS_REPO/tools/, tools/, ~/.codex/skills/figure-spec/scripts/, ~/.codex/skills/figure-spec/. Set ARIS_REPO, rerun install_aris_codex.sh, or copy the canonical \$ARIS_REPO/skills/figure-spec/scripts/figure_renderer.py next to this skill." >&2
  exit 1
}

python3 "$FIGURE_RENDERER" render <spec.json> --output <out.svg>
python3 "$FIGURE_RENDERER" validate <spec.json>
python3 "$FIGURE_RENDERER" schema

工作流

步骤 1:理解图表目标

从 $ARGUMENTS(描述或指向 PAPER_PLAN.md / NARRATIVE_REPORT.md 的路径)中识别:

  • 目的:架构、工作流、管道、审计级联、拓扑?
  • 主要实体:有哪些框?
  • 关系:它们如何连接?(使用、产生、调用、验证、链式)
  • 分组:实体是否聚集成命名区域?
  • 层次 vs 网络:堆叠层、从左到右流,还是中央枢纽?

步骤 2:草拟 FigureSpec JSON

画布尺寸指南:

  • 单栏图:约 500×350 像素
  • 双栏(全宽):约 900×500 像素
  • 高拓扑图:约 700×700 像素

从基于图表类型的模板开始:

架构(堆叠行):

json
{
  "canvas": {"width": 900, "height": 520},
  "nodes": [
    {"id": "layer1_label", "label": "Layer 1", "x": 450, "y": 60, ...},
    {"id": "node_a", "label": "A", "x": 180, "y": 120, ...},
    {"id": "node_b", "label": "B", "x": 350, "y": 120, ...}
  ],
  "edges": [...],
  "groups": [
    {"label": "Layer 1", "node_ids": ["node_a", "node_b"], "fill": "#F0F9FF", "stroke": "#BAE6FD"}
  ]
}

工作流(从左到右链):

json
{
  "canvas": {"width": 900, "height": 300},
  "nodes": [
    {"id": "step1", "label": "Step 1", "x": 100, "y": 150, "shape": "rounded"},
    {"id": "step2", "label": "Step 2", "x": 280, "y": 150, "shape": "rounded"}
  ],
  "edges": [
    {"from": "step1", "to": "step2", "label": "produces"}
  ]
}

决策菱形:

json
{"id": "check", "label": "Passes?", "shape": "diamond", "x": 450, "y": 200}

步骤 3:渲染并验证

bash
# 先验证
python3 "$FIGURE_RENDERER" validate /tmp/spec.json

# 渲染为 SVG
python3 "$FIGURE_RENDERER" render /tmp/spec.json --output figures/fig_arch.svg

# 转换为 PDF 用于 LaTeX 导入
rsvg-convert -f pdf figures/fig_arch.svg -o figures/fig_arch.pdf

如果验证失败,检查错误(缺失字段、重复 ID、重叠警告、无效十六进制颜色)并修复 JSON。

步骤 4:视觉审查

打开 SVG/PDF 并检查:

  • 无重叠:节点彼此之间以及组边界无碰撞
  • 可读性:字体大小一致,标签不被裁剪
  • 边清晰度:箭头以干净的角度到达节点,边附近的标签清晰可辨
  • 组对齐:背景矩形清晰地框住其成员
  • 颜色区分:类别在彩色和灰度下视觉上均清晰可辨

如果发现问题,编辑 JSON 规格(切勿编辑生成的 SVG)并重新渲染。

步骤 5:通过 Codex 审查迭代(可选,用于重要图表)

对于论文架构图,调用跨模型审查:

text
spawn_agent:
  model: gpt-5.5
  reasoning_effort: xhigh
  message: |
    审查此技术论文(架构/工作流图)的 SVG 图形。

    规格文件:/path/to/spec.json
    渲染结果:/path/to/fig.svg

    评估:
    1. 清晰度(C):读者能否仅从此图理解系统?
    2. 可读性(R):字体大小、标签放置、视觉层次
    3. 语义准确性(S):关系是否与所描述的系统匹配?

    对每个轴打分(1-10)并列出需要修复的具体问题。

迭代直到三个轴均达到 ≥ 7/10。ARIS 技术报告的图形经过了 5 轮此循环,才达到 C:7/R:7/S:8。

模式快速参考

运行 python3 "$FIGURE_RENDERER" schema 获取权威模式。

节点

字段必需默认值备注
id✓—唯一
label✓—\n 用于多行
x, y✓—中心坐标
width, height120, 50
shaperoundedrect / rounded / circle / ellipse / diamond
fill, stroke自动从调色板#RRGGBB
text_color#333333
font_size14覆盖样式默认值

边

字段默认值备注
from, to必需相同则自循环
label—短边标签
stylesolidsolid / dashed / dotted
color#555555
curvefalse弯曲路径

组

矩形背景区域框定一组节点:

json
{"label": "Layer Name", "node_ids": ["a", "b", "c"], "fill": "#EFF6FF", "stroke": "#BFDBFE"}

设计模式

模式 1:分层架构

将相关节点排成行,每行是一个组,添加层间箭头并附上语义标签(uses↓、produces↑、checks↓)。

模式 2:中心辐射型

中央节点(例如,Executor),外围节点(技能、工具),实线箭头表示主要关系,虚线表示反馈。

模式 3:带反馈的管道

从左到右主流,反馈箭头以曲线在下方返回,设置 curve: true。

模式 4:审计级联

三级水平级联,输入从上方馈入,输出从右侧流出,每个阶段位于自己的组中。

反模式

  • 不要将组用作层次结构:组框定同级节点,而非包含关系
  • 不要嵌套组:渲染器将它们绘制为背景矩形;嵌套组看起来像俄罗斯套娃
  • 不要绘制长对角线:如果箭头跨越多行,重新考虑布局
  • 不要为同一角色的节点混用字体大小:为每个节点类别保持统一字号

输出约定

  • figures/ 中的 SVG 文件(矢量、可编辑、可手动微调)
  • 源 FigureSpec JSON 保存在 figures/specs/ 中以供复现
  • 通过 rsvg-convert 生成 PDF 版本用于 LaTeX 导入

与其他技能的集成

  • /paper-writing(工作流 3):当 illustration: figurespec(架构图的默认值)时,此技能处理阶段 2b
  • /paper-figure:处理数据图;二者互补(数据 + 架构 = 完整的图形集)
  • /paper-illustration:对需要自然/定性风格的图形(带照片的方法插图、定性结果网格)的后备方案
  • /mermaid-diagram:用于简单流程图的更轻量替代

审查追踪

每次调用审查代理后,按照 shared-references/review-tracing.md(策略 C — 取证;切勿静默跳过)保存追踪。使用 save_trace.sh(按 shared-references/integration-contract.md §2 中的链解析)或直接写入文件到 .aris/traces/<skill>/<date>_run<NN>/。遵守 --- trace: 参数(默认值:full)。