lijianfei.com

如果你曾尝试让大语言模型（无论是 GPT-4o 还是 Claude 3.5 Sonnet）根据实验数据绘制科研图表，大概率体验过那种熟悉的“塑料感”与挫败感：

一敲回车，AI 熟练地掏出 Matplotlib 祖传的 tab10 默认配色（刺眼的亮蓝 #1f77b4 与土橙 #ff7f0e），画出粗糙的 72 DPI 位图；更致命的是，面对缺失的数据它会自作主张地凭空脑补置信带，或者在 10 英寸的大画布上随手设一个 9pt 字体——一旦插进 LaTeX 双栏论文，整个图表同比腰斩缩放，坐标轴上的数字瞬间缩小成辨认不清的“蚂蚁字”。

开源项目 vivid-figures-skill（生动数据图） 正是为此而生。它将原本在数学建模国赛与美赛（MCM/ICM）高强度实战中锤炼出的绘图体系，封装成了面向 Claude Code 等环境的原生 Agent Skill。它没有停留在简单的 Prompt 调教层面，而是构建了一整套包含 108 个生产级图表配方、双风格去指纹色彩体系、物理尺寸前置预计算与多模态闭环审图的严密工业级管线。

flowchart TD
    subgraph Input["1. 输入与契约绑定"]
        Data["真实实验数据 (CSV / JSON / Parquet)"]
        Claim["学术论点与实证绑定 (Claim / Evidence)"]
        Manifest["FIGURE_MANIFEST 结构化契约清单"]
    end

    subgraph Router["2. 确定性渲染路由器 (Router)"]
        R_Data["数值统计数据 -> paper-figure (Python/Matplotlib)"]
        R_Tech["工程/拓扑/结构 -> paper-technical-diagram (Draw.io/TikZ)"]
        R_Illu["机理/场景插图 -> paper-illustration (原生生成)"]
        R_Text["架构/管线流程 -> Mermaid / HTML"]
    end

    subgraph Preflight["3. 物理级前置预计算 (Size Preflight)"]
        Aspect["计算长宽比 r = 高 / 宽"]
        DisplayWidth["查表锚定 LaTeX 上页显示宽 (0.85/0.70/0.50\\textwidth)"]
        FigSize["倒推原生 figsize：原生宽 ≈ 上页显示宽 (缩放比 0.9~1.1)"]
    end

    subgraph CodeGen["4. 规范代码生成 (108 Recipes & Anti-Fingerprint)"]
        RecipePool["检索 108 个配方库 (基础/高阶/竞赛/顶刊/计量)"]
        PaletteEngine["确定性哈希种子色板 (Okabe-Ito/Tol/NPG/莫兰迪)"]
        GenScript["生成独立源码 figures/gen_fig_*.py"]
    end

    subgraph AuditGate["5. 双重门禁与视觉闭环 (Verification & Closed-loop)"]
        ASTCheck["figure_check.sh 静态代码扫描<br/>(禁硬编码色、禁CSS原色、禁plt.title、反模式拦截)"]
        RenderPDF["执行绘图 -> 300 DPI 矢量 PDF + 预览 PNG"]
        VisionReview["Agent 多模态视觉审图 (检查遮挡、重叠与留白)"]
        TeXAudit["audit_final_figure_size.py (逆向提取 PDF 字体流与排版字号)"]
    end

    Input --> Router
    Router --> Preflight
    Preflight --> CodeGen
    CodeGen --> AuditGate
    AuditGate -->|检查未通过/存在遮挡| CodeGen
    AuditGate -->|全部通过| Deliver["交付成果：矢量 PDF + 印刷级 PNG + 100% 可复现 Python 源码"]

一、 痛苦之源：为什么直接让 AI 画图总是充满“民科塑料感”？

在学术论文与工程报告中，审稿人往往只需一眼就能判定一张图表是出自严谨的研究团队，还是用默认脚本随手跑出来的。大模型直接生成的图表通常存在四大顽疾：

1. 默认色板的“AI 指纹”与刺眼视觉

几乎所有大模型在编写 Python 绘图代码时，都极度依赖训练集中的模式偏好：未经定制的 Matplotlib 默认蓝色（#1f77b4）、Seaborn 的默认高饱和度发光条形图，或者红绿对比强烈的 RdYlGn。这些配色不仅对色弱人群极不友好（不符合 Nature Methods 等顶刊的无障碍倡议），更散发着浓郁的“新手作业感”。

2. 幻觉与无中生有的虚假数据

普通的大模型在画折线图时，经常为了视觉好看，随手用 np.random.normal() 脑补一条阴影置信带，或者强行画出未经采样的误差棒（Error Bar）。在科研场景中，没有方差数据就绝对不能画误差带，这种对科学严肃性的漠视直接构成学术不端风险。

3. 排版灾难：“字号腰斩惨案”

这是学术排版中最隐蔽却最普遍的翻车点。大多数人习惯在 Python 里定义一个大画布（比如 figsize=(10, 6)），并设置字体为 fontsize=9。当这个图表被 \includegraphics[width=0.48\textwidth] 插入 LaTeX 双栏论文时，由于单栏宽度仅约 3.25 英寸，整张图被机械压缩了将近 60%——原本 9pt 的字号在纸面上暴跌至 3.6pt，线条细度也随之缩水到印刷极限以下，最终输出的论文中坐标轴糊成一团。

4. 单向输出与缺乏闭环自检

传统的代码生成是“单向开盲盒”：大模型敲完代码便宣布完成，它根本不知道图例（Legend）是否刚好盖住了关键峰值、X 轴标签是否因为文字过长而发生重叠，或者某些点是否超出了坐标边界。

二、 核心架构：从竞赛利器到 Agent Skill 的工业级升维

vivid-figures-skill 的前身是针对高难度数学建模竞赛（如 MCM/ICM、全国大学生数学建模竞赛）打造的 modeling-plot-suite。这类竞赛要求参赛团队在 72 小时内处理海量多模态数据，生成数十张既符合顶刊审稿规范又兼具极高信息密度的专业图表。

在封装为 Anthropic Agent Skill 后，它为 Claude Code 等工具提供了一套规范严谨的状态机：

sequenceDiagram
    autonumber
    actor User as 用户 / 研究员
    participant Agent as Claude Code (Agent)
    participant Skill as vivid-figures-skill 管线
    participant Python as Python 渲染沙箱
    participant Inspector as 审计门禁 (Linter & Vision)

    User->>Agent: "读取 experiment.csv，比较五种模型的收敛性与鲁棒性"
    Agent->>Skill: 触发 Router 路由与前置检索
    Skill->>Agent: 校验 FIGURE_MANIFEST 契约，锁定 Recipe (如收敛对比+置信扇形)
    Skill->>Skill: 执行 Size Preflight，按 0.85\textwidth 锁定 figsize=(6.0, 3.8)
    Skill->>Skill: 注入工作区哈希种子与学术色板 (如 Okabe-Ito / 森林日光)
    Skill->>Python: 生成 figures/gen_fig_convergence.py 并执行渲染
    Python-->>Skill: 产出 300 DPI PDF 与预览 PNG
    Skill->>Inspector: 触发 figure_check.sh 静态扫描
    Inspector-->>Skill: 检查退出码 (0 违规，拦截非法 CSS 色与图内标题)
    Skill->>Agent: 自动调用视觉能力 (Vision) 加载 PNG 审视布局
    Agent-->>Skill: 确认图例无遮挡、字号清晰可读
    Skill->>User: 交付高质量图表、矢量 PDF 与完全可复现源码

该管线明确了以下三条底层原则：

1. 真实证据锚定（Evidence-Anchored）：严禁由 AI 自由发挥数值，图表必须严格映射到真实文件中的字段；没有重复样本就拒绝虚构置信带；
2. 源码独立可维护：每一次绘图必须在任务工作区的 figures/ 目录下留下结构工整、注释详尽的 gen_fig_*.py 独立脚本；
3. 矢量与印刷标准：默认产出 300 DPI PDF（供 LaTeX/InDesign 排版）与高质量预览 PNG。

三、 108 个生产级配方：全学科覆盖的严谨科学图谱

vivid-figures-skill 核心的底牌在于其内置的 recipe_registry.json，它涵盖了 108 个经过大量实战打磨的独立配方，划分为五大专业领域：

mindmap
  root((108 个生产级配方))
    基础统计类 (12)
      分组柱状图 (淡色充+原色边框+参考线)
      渐变面积图 (极值标注箭头)
      KDE 散点回归 (回归公式框)
      聚类热力图 (树状图+下三角遮罩)
      Raincloud 雨云图 (半小提琴+箱线+抖动)
    高阶分析类 (34)
      SHAP Summary 特征重要性
      Bland-Altman 一致性图
      Kaplan-Meier 生存曲线 (风险表+LogRank)
      Taylor Diagram 多模型精度评估
      Dolan-Moré 性能剖面图
      ICE + PDP 可解释机器学习
      Ridgeline 山脊图 (渐变填充+中位数)
    数模竞赛类 (29)
      Pareto 前沿面 (多目标优化)
      Tornado 灵敏度旋风图
      ODE 相空间流线与吸引子
      3D 目标函数地形与损失曲面
      省域 Choropleth 空间分级色彩图
    顶刊学术类 (12)
      ROC + PR 双面板曲线
      Meta 分析森林图 (Forest Plot)
      Boxen Plot 增强箱线图
      混淆矩阵标准化热力图
    实证计量类 (21)
      DID 平行趋势检验 (Parallel Trends)
      Event Study 事件研究动态效应
      安慰剂检验 (Placebo Test 分布)
      断点回归 (RDD)
      PSM 倾向得分匹配平衡性 (Love Plot)
      Moran's I 空间自相关与省级 LISA 聚类

反模式拦截（Anti-pattern Detection）

在 figure_check.sh 中，该 Skill 甚至配置了一套图表类型升级拦截器：

• 拒绝柱状图泛滥：当同一个项目中出现超过 3 个柱状图时，系统会强制触发报警，提示替换为棒棒糖图（Lollipop）、哑铃图（Dumbbell）或斜率图（Slope）；
• 消灭粗糙饼图：若检测到 plt.pie()，直接提醒升级为带有外引连线与中心指标的环形图（Donut Chart）或华夫饼图（Waffle Chart）；
• 特征重要性升级：水平条形图展示模型特征时，自动建议升级为承载更多样本分布细节的 SHAP Summary Plot；
• 矩阵聚类强制：检测到普通相关性矩阵时，提示挂载层次聚类树状图（Dendrogram），避免杂乱无章的特征排列。

四、 双模式体系与去指纹化色彩工程

不同于通用图库盲目堆砌鲜艳色彩，vivid-figures-skill 从学术规范出发，提炼出了两套互补的视觉设计模式：

1. 确定性哈希种子与全篇色彩统一

很多读者在使用 AI 绘图时会发现：Figure 1 是亮绿配紫，Figure 2 突然变成了暗色莫兰迪，整篇论文毫无视觉一致性。

该工具在 plot_utils.py 中引入了极具巧思的 去指纹化随机种子算法：

# 核心机制：基于当前工作区目录名计算确定性哈希
import hashlib

def resolve_workspace_seed(workspace_path: str) -> int:
    hasher = hashlib.sha256(workspace_path.encode('utf-8'))
    return int(hasher.hexdigest()[:8], 16)

• 同一篇论文完全统一：无论在会话中重跑多少次、生成多少张图，只要工作区路径不变，setup_style() 选中的学术色板始终唯一，确保所有图表视觉语言高度协同；
• 不同论文彼此各异：换一个工作区，种子立即平滑切换至 28 套顶刊配色池（包含 Okabe-Ito、Paul Tol 调色盘、Nord 极简风、Morandi 莫兰迪色系等），彻底消灭千篇一律的模型风格指纹。

2. 避免公式误伤与 CommonMark 语法规范

在图表标签与 Markdown 报告的排版中，项目严禁出现未转义的裸美元符号，代币代码必须用行内代码块包裹，数学表达式显式声明，彻底防止 KaTeX 解析器将常规字符误判为公式定界符。

五、 物理尺寸前置计算与字体逆向审计

在学术排版中，很多开发者误以为“高清”就是把图片 DPI 调高或者把尺寸画大。真正的排版工业标准，是让图表的原生绘制尺寸无限逼近其在论文中的实际上页物理宽度。

1. 宽高比分档心算公式

在 original-size-preflight 规范中，团队总结出了针对单双栏论文的黄金计算模型：

$\text{上页字号} = \text{代码字号} \times \left( \frac{\text{论文引用宽}}{\text{原生 figsize 宽}} \right)$

为了让最终缩放比稳定在 0.9 ~ 1.1 的安全区间，代码原生尺寸必须依据长宽比 r = 高度 / 宽度 进行前置分档：

graph LR
    subgraph RatioBins["长宽比 r = 高 / 宽 分档锚定"]
        A["宽横图 (r ≤ 0.80)<br/>引用宽: 0.85\\textwidth (5.53 in)<br/>原生 figsize: (6.0, 3.8)"]
        B["近方图 (0.80 < r ≤ 1.20)<br/>引用宽: 0.70\\textwidth (4.55 in)<br/>原生 figsize: (5.0, 4.9)"]
        C["偏竖图 (1.20 < r ≤ 1.60)<br/>引用宽: 0.50\\textwidth (3.25 in)<br/>原生 figsize: (3.6, 5.0)"]
        D["瘦高图 (r > 1.60)<br/>引用宽: 0.42\\textwidth (2.73 in)<br/>原生 figsize: (3.0, 5.4)"]
    end

如果要做一个 2×2 的 4-Panel 复合面板图（属于近方图），原生宽度必须被严格限制在 5.0in 左右，而不是拍脑袋写 10in。只要原生宽度贴近显示宽度，代码中设定的 8.5pt 刻度标签插进论文后依然是清晰可辨的 8pt。

2. 双重审计门禁：从静态 AST 到 PDF 字体流逆向

该项目的另一项硬核能力在于其自动化测试脚本。它部署了两个阶段的防御机制：

第一道：静态代码扫描 (figure_check.sh)

在脚本执行后立即启动静态审查：

• 严禁图内整图标题：检测到 plt.title() 或 fig.suptitle() 直接判定 CRITICAL 阻断报错（学术规范要求整图大标题必须交由 LaTeX \caption{} 统一排版，图内仅允许面板子标签如 ax.set_title('(a)...', loc='left')）；
• 严禁硬编码默认色：检测到 #1f77b4 或原初 CSS 颜色名（red, blue, green）直接阻断；
• 限制硬编码 Hex 数量：特殊标注允许不超过 2 处协调色，超过则必须强制统一引用 PALETTE[n]。

第二道：编译层字体流逆向审计 (audit_final_figure_size.py)

如果交付包含 LaTeX 文档，工具会调用 PyMuPDF 解析生成的 PDF 矢量流，并结合 .tex 源码中 \includegraphics 的宽度系数，精确逆向换算每一个文本元素的最终物理印刷字号：

# 逆向换算核心伪代码
actual_width_mm = tex_width_ratio * text_width_mm
scale_factor = actual_width_mm / (fig_native_width_inches * 25.4)
effective_font_pt = pdf_text_font_size * scale_factor

if effective_font_pt < 7.0:
    raise HardAuditFailure(f"字号在排版后跌破 7.0pt (实测 {effective_font_pt:.1f}pt)，将被审稿人拒稿！")

六、 实战上手：在 Claude Code 中武装科研绘图力

得益于标准 Agent Skill 规范，将 vivid-figures-skill 引入日常开发非常轻量。

1. 安装与虚拟环境隔离

为避免科研依赖（NumPy、SciPy、Matplotlib、Seaborn、PyMuPDF 等）与宿主环境冲突，推荐配置独立环境：

# 克隆到 Claude 全局 Skill 目录
git clone https://github.com/yjz211/vivid-figures-skill.git "$HOME/.claude/skills/vivid-figures-skill"

# 初始化专用虚拟环境并安装依赖
python3 -m venv "$HOME/.claude/skills/vivid-figures-skill/.venv"
"$HOME/.claude/skills/vivid-figures-skill/.venv/bin/python" -m pip install --upgrade pip
"$HOME/.claude/skills/vivid-figures-skill/.venv/bin/python" -m pip install -r "$HOME/.claude/skills/vivid-figures-skill/requirements.txt"

2. 真实场景调用范式

在 Claude Code 会话中，无需机械地撰写复杂的绘图参数，只需传递真实数据并描述学术意图：

用 vivid-figures-skill 读取 benchmarks.csv。
比较 6 组 baseline 在 10 项测试集上的收敛速度与波动范围。
使用稳重版、海洋暖橙配色，图型由你根据数据形态专业推荐。
要求：输出 300 DPI 矢量 PDF、预览 PNG 与 figures/ 独立绘图脚本。

Agent 会自动经历以下标准流转：

1. 探查数据：分析数据的分布偏态与方差特征，决定采用雨云图（Raincloud）还是分层折线图；
2. 检索配方：从 108 个配方库中拉取基础代码结构，杜绝 AI 从零手写 Matplotlib 时容易遗漏的参数配置；
3. 尺寸预计算：根据长宽比精准锁定 figsize；
4. 代码生成与渲染：调用虚拟环境中的 Python 生成高清图形；
5. 多模态核验：Agent 自行读取生成的 PNG，确认文本无重叠遮挡后，一次性交付包含完整可重现代码的学术级资产。

七、 思考与启示：Agentic Workflow 的真正护城河

在众多开发者争相探索“如何让 AI 写出更长代码”的今天，vivid-figures-skill 给出了一个极其清醒的范式示范：

flowchart LR
    A["浅层 AI 应用<br/>(Prompt 拼凑 + 单向生成)"] -->|容易翻车| F1["幻觉臆造数据<br/>刺眼默认配色<br/>排版字号腰斩"]
    B["深度 Agentic 工程<br/>(规则基线 + 领域配方 + 闭环审计)"] -->|稳定可靠| F2["100% 真实证据<br/>顶刊去指纹色彩<br/>排版物理级保真"]

单纯依靠扩大大模型的参数规模，无法自然消除物理排版中的缩放冲突，也无法杜绝数据可视化中的统计反模式。真正的工业级 AI 工具链，必然是 “结构化领域配方（108 Recipes） + 确定性工程约束（Size Preflight & Linter） + 多模态视觉反思闭环（Multimodal Review）” 的有机结合。

丢掉 Matplotlib 的默认蓝只是第一步；让大模型理解科研的严谨、设计的克制与印刷的物理规律，才是 AI 原生科研工具链演进的核心分水岭。