figure-spec

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

在每个审阅者席位开始前，请遵循 可选审阅者： 通过规范的辅助解析器解析调用 → .aris/reviewer.json → Claude Code 默认设置（Codex MCP）， 并通过 reviewer_route.py 保留此席位的层级、新鲜上下文、源文件／图像输入和确定性门控。 下方的 Codex 示例／固定配置仅适用于 backend=codex；其他路由使用各自的首次调用／回复约定。保存路由和实际返回的身份； 不可用的选项标记为 REVIEW_UNAVAILABLE。根据实际的系列／完成状态／范围对验收结果分类。 将调用中的审阅者／模型／effort 覆盖项 传递给包含审阅者的子项。生成工作线程保持不变。

使用确定性的 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（此 SKILL 自带的 scripts/ 子目录）。tools/figure_renderer.py 中的向后兼容垫片会通过 os.execv 转发到规范文件，因此使用 .aris/tools/figure_renderer.py 或手动复制的 tools/figure_renderer.py 的现有用户无需做任何更改即可继续使用。

通过混合链解析 $FIGURE_RENDERER（第 0 层优先使用所属 SKILL 的 自包含位置；第 1–4 层使用 shared-references/integration-contract.md §2 中说明的共享运行时链， 策略 A——技能本地门控）：

# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
FIGURE_RENDERER=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/figure_renderer.py" ]; then
  FIGURE_RENDERER="$CLAUDE_SKILL_DIR/scripts/figure_renderer.py"
fi
# Layers 1-4: shared-runtime chain (legacy compatibility + non-CC hosts).
if [ -z "$FIGURE_RENDERER" ]; then
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
  fi
  if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
      ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
  fi
  FIGURE_RENDERER=".aris/tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER="tools/figure_renderer.py"
  [ -f "$FIGURE_RENDERER" ] || { [ -n "${ARIS_REPO:-}" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"; }
  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER=""
fi
[ -z "$FIGURE_RENDERER" ] && {
  echo "ERROR: figure_renderer.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-4: .aris/tools/, tools/, \$ARIS_REPO/tools/, \$ARIS_REPO/tools/ via ~/.aris/repo)." >&2
  echo "       /figure-spec cannot produce SVG output. Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), or copy the helper from \$ARIS_REPO/skills/figure-spec/scripts/." >&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 的路径）中确定：

• 用途：架构、工作流、管道、审计级联，还是拓扑？
• 主要实体：框中应包含什么？
• 关系：它们如何连接？（使用、生成、调用、验证、链接）
• 分组：这些实体是否聚集在带名称的区域中？
• 层级还是网络：堆叠式分层、从左到右的流程，还是中心辐射结构？

步骤 2：起草 FigureSpec JSON

画布尺寸指南：

• 单栏图：约 500×350 px
• 双栏（全宽）图：约 900×500 px
• 高纵横比拓扑图：约 700×700 px

根据图表类型从模板开始：

架构（堆叠行）：

{
  "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"}
  ]
}

工作流（从左到右的链）：

{
  "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"}
  ]
}

决策菱形：

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

步骤 3：渲染并验证

# Validate first ($FIGURE_RENDERER was resolved in "Tool Location" above)
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

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

步骤 4：视觉审查

打开 SVG/PDF 并检查：

• 无重叠：节点之间以及节点与分组边界之间没有碰撞
• 可读性：字体大小一致，标签没有被裁切
• 边线清晰度：箭头以合适的角度指向节点，边线附近的标签清晰可读
• 分组对齐：背景矩形能整齐地框住其中的节点
• 颜色区分度：类别在彩色和灰度下都能明显区分

如果发现问题，请编辑 JSON 规范（不要编辑生成的 SVG）并重新渲染。

步骤 5：使用 Codex Review 迭代（可选，适用于重要图表）

对于论文架构图，请调用跨模型审查：

请先解析此审查者插槽；以下是 backend=codex 示例。

mcp__codex__codex:
  model: gpt-6-astra
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    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.

持续迭代，直到三个维度都达到 ≥ 7/10。ARIS 技术报告中的图表经过 5 轮此类迭代，最终达到 C:7/R:7/S:8。

Schema 快速参考

运行 python3 "$FIGURE_RENDERER" schema（按照上文“工具位置”解析 $FIGURE_RENDERER）以获取权威 schema。

节点

字段	必填	默认值	备注
id	✓	—	唯一
label	✓	—	多行文本使用 \n
x、y	✓	—	中心坐标
width、height		120, 50
shape		rounded	rect / rounded / circle / ellipse / diamond
fill、stroke		自动从调色板获取	#RRGGBB
text_color		#333333
font_size		14	覆盖样式默认值

边

字段	默认值	备注
from、to	必填	相同表示自环
label	—	简短的边标签
style	solid	solid / dashed / dotted
color	#555555
curve	false	曲线路径

分组

框住一组节点的矩形背景区域：

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

设计模式

模式 1：分层架构

将相关节点按行堆叠，每行作为一个分组，并添加带语义标签的层间箭头（uses↓、produces↑、checks↓）。

模式 2：中心辐射

中心节点（例如 Executor），外围节点（技能、工具）；主要关系使用实线箭头，反馈使用虚线箭头。

模式 3：带反馈的流水线

主流程从左向右，反馈箭头在下方弯曲，并设置 curve: true。

模式 4：审计级联

采用三个阶段的水平级联布局，输入从顶部进入，输出从右侧离开，每个阶段各自位于一个分组中。

反模式

• 不要用分组表示层级：分组用于框住同级节点，而非表示包含关系
• 不要嵌套分组：渲染器会将它们绘制为背景矩形；嵌套分组看起来像俄罗斯套娃
• 不要绘制交叉的长对角线：如果箭头跨越 3 行或更多，请重新考虑布局
• 不要混用同一角色的字体大小：每种节点类别统一使用一种字号

输出约定

• SVG 文件保存在 figures/ 中（矢量格式、可编辑且便于手动调整）
• 源 FigureSpec JSON 保存在 figures/specs/ 中，以便复现
• 通过 rsvg-convert 生成 PDF 版本，以便纳入 LaTeX

与其他技能的集成

• /paper-writing（工作流 3）：当 illustration: figurespec（架构图的默认值）时，此技能负责阶段 2b
• /paper-figure：负责数据图表；两者相辅相成（数据 + 架构 = 完整的图表集）
• /paper-illustration：适用于需要自然／定性风格的图表（含照片的方法插图、定性结果网格）的备用方案
• /mermaid-diagram：适用于简单流程图的轻量替代方案

审查追踪

每次 mcp__codex__codex 或 mcp__codex__codex-reply 审查者调用后，按照 shared-references/review-tracing.md 保存追踪记录（Policy C — forensic；不得悄然跳过）。使用 save_trace.sh（按照 shared-references/integration-contract.md §2 中的链解析），或直接将文件写入 .aris/traces/<skill>/<date>_run<NN>/。遵循 --- trace: 参数（默认值：full）。