plotting-agent

绘图 Agent（第 2 步）

忠实实现 PaperOrchestra 中的绘图 Agent （Song 等，2026，arXiv:2604.05018，§4 第 2 步及附录 F.1 第 45 页）。

成本：约 20–30 次 LLM 调用。 论文使用 PaperBanana（Zhu 等，2026）作为默认骨干模型，并通过 VLM 批判进行闭环优化。此技能以宿主 Agent 的方式实现这一流程：你（宿主 Agent）使用自己的 LLM 生成 matplotlib 代码，通过 Bash/Python 工具渲染，可选用视觉模型批判渲染后的 PNG，然后重新绘制，最后生成图注。

输入

• workspace/outline.json——具体来说，是其中的 plotting_plan 数组
• workspace/inputs/idea.md 和 workspace/inputs/experimental_log.md——源数据
• workspace/inputs/figures/——可选的现有图表（PlotOn 模式）

输出

• workspace/figures/<figure_id>.png——每个 plotting_plan 条目对应一个 PNG（300 DPI，尺寸符合要求的宽高比）
• workspace/figures/captions.json——{figure_id: caption_text} 映射

工作流

每张图（针对每个 figure_id 独立执行）

1. 读取图表规格，从 outline.json 中获取：

   {
     "figure_id": "fig_main_results",
     "title": "Main Results on Dataset X",
     "plot_type": "plot",
     "data_source": "experimental_log.md",
     "objective": "Visual summary (Grouped Bar Chart) demonstrating ...",
     "aspect_ratio": "5:4"
   }
   

2. 少样本检索（视觉规划）：从 references/chart-patterns.md（适用于 plot_type=="plot"）或 references/diagram-patterns.md（适用于 plot_type=="diagram"）中选择匹配的模式。

3. 提取数据：解析 idea.md 和/或 experimental_log.md（data_source 字段会告知你使用哪个文件），获取图表所需的数值或概念实体。对于 experimental_log.md，## 2. Raw Numeric Data 部分包含 Markdown 表格。

4. 渲染：

   如果设置了 PAPERBANANA_PATH——使用 PaperBanana 骨干模型（Zhu 等，2026）。它运行 Retriever → Planner → Stylist → Visualizer → Critic 流程，尤其擅长处理 plot_type == "diagram"。 请参阅 references/paperbanana-cookbook.md 了解设置方法（需要 Gemini API 密钥）。

   python skills/plotting-agent/scripts/paperbanana_render.py \
       --figure-id <figure_id> \
       --caption   "<objective from figure spec>" \
       --content-file workspace/inputs/idea.md \
       --task      <diagram|plot> \
       --aspect-ratio <aspect_ratio> \
       --out       workspace/figures/<figure_id>.png
   

   否则——编写 matplotlib 脚本并通过 Bash 工具运行，或者使用捆绑的辅助工具：

   python skills/plotting-agent/scripts/render_matplotlib.py \
       --spec spec.json \
       --out workspace/figures/<figure_id>.png
   

   脚本必须应用 chart-patterns.md 中的学术风格，采用 aspect-ratios.md 中规定的正确像素尺寸，以 300 DPI 保存，并在调用 savefig 后调用 plt.close()。

5. VLM 批判循环（可选，仅当宿主具备视觉能力时）：

   • 将渲染后的 PNG 作为多模态输入重新载入 LLM。
   • 根据大纲中图表的 objective 对其进行批判。检查是否存在视觉伪影、坐标轴标注错误、文字难以辨认、颜色冲突、比例尺误导、图例缺失、标签重叠等问题。
   • 如果发现问题，则修正 matplotlib 脚本并重新生成渲染结果。每张图最多进行 3 轮批判。
   • 这是论文从 PaperBanana 继承的闭环优化步骤。完整流程说明请参阅 references/plotting-pipeline.md。
   • 如果宿主不支持视觉输入，请完全跳过此步骤。 图表仍会正确渲染，只是不会经过迭代优化。

6. 生成图注：使用 references/caption-prompt.md 中原文不变的 Caption Generation 提示词。提示词的输入：

   • task_name——图表所属的章节（例如，“Methodology”“Experiments”）
   • raw_content——周边章节的文本（如果章节尚未起草，则使用 section_plan 中的 content_bullets）
   • description——图表规格中的 objective 字段
   • figure_desc——对渲染后的图表实际内容的一句话描述（来自 VLM 批判环节；如果没有视觉能力，则根据脚本计划生成）

   将图注写入 workspace/figures/captions.json，以 figure_id 为键。图注不得包含 Figure N: 或 Caption N: 前缀——LaTeX 模板会负责编号。仅使用纯文本，不要使用 Markdown。

概念图

对于 plot_type == "diagram"，如果 PaperBanana 可用，优先使用它——它的 Retriever 会以真实发表的论文图示为 Planner 提供依据。如果未设置 PAPERBANANA_PATH，请遵循 references/diagram-patterns.md。模式包括框图、系统概览图、流程图和算法图。捆绑的辅助工具：

python skills/plotting-agent/scripts/render_diagram.py \
    --spec diagram_spec.json \
    --out workspace/figures/<figure_id>.png

适用于简单情况（方框和箭头）。对于复杂的 Fig-1 风格概览图，请自行编写 matplotlib patches 代码。

硬性规则

• 所有图均须为 300 DPI。在会议模板的 LaTeX 编译步骤中，低于此值的图会被拒绝。
• 纵横比必须精确。图示规范中的 aspect_ratio 是 12 个枚举字符串之一。请使用 references/aspect-ratios.md 中的像素目标。
• 隐藏图表的上边框和右边框。（概念图：不显示任何边框。）
• 仅使用低饱和度的学术配色。配色方案见 chart-patterns.md。切勿使用 matplotlib 默认配色（用于印刷时饱和度过高）。
• **禁止使用 3D 图、饼图和装饰性视觉元素。**论文评审会对此类内容扣分。
• 每张图都必须在 captions.json 中配有说明文字。如果大纲引用的图缺少说明文字，章节撰写 Agent 将停止执行。
• 说明文字中不得添加 Figure N: 前缀——LaTeX 会自动添加。
• **绝不可描述未绘制的数据。**绘图 Agent 不得臆造坐标轴、基线或趋势。数据的唯一依据是 experimental_log.md 或 idea.md。

验证关卡（交接给步骤 3/4 前运行）

以上硬性规则虽到处都有说明，却没有任何地方强制执行。此关卡可检查其中可机械验证的部分：

python skills/plotting-agent/scripts/figure_lint.py \
    --figures workspace/figures \
    --captions workspace/figures/captions.json

ERROR：已渲染的图没有说明文字、说明文字没有对应文件、说明文字为空、栅格图尺寸太小而无法印刷。WARN：单栏宽度下的分辨率低于约 300 DPI、纵横比超过 4:1、说明文字给自身编号（Figure 3: ...）、说明文字少于八个单词，以及图集中没有架构图／流程图／概览图。

PNG 几何信息直接从 IHDR 和 pHYs 数据块读取——不使用图像处理库，符合仓库仅使用确定性辅助工具的规则。

步骤 4 生成 paper.tex 后，使用 --paper 重新运行，以确认草稿使用了步骤 2 渲染的所有图片，且未引用不存在的文件：

python skills/plotting-agent/scripts/figure_lint.py \
    --figures workspace/figures \
    --paper   workspace/drafts/paper.tex

继续之前，请修复所有 ERROR。缺少说明文字是唯一一种会悄无声息地向后传播的错误：步骤 4 会将图片与它臆造的说明文字拼接在一起，而步骤 5 无法得知该说明文字从未有依据。

预先存在的图片（PlotOn 模式）

如果 workspace/inputs/figures/ 非空，请检查其中是否有文件与大纲中的 figure_id 匹配（按文件名前缀判断）。如果有，原样复制到 workspace/figures/，并且仍须使用说明文字提示词生成说明文字。仅从头生成没有预先存在对应图片的 figure_id。

资源

• references/caption-prompt.md — 附录 F.1 中逐字引用的说明文字生成提示词
• references/plotting-pipeline.md — 完整的少样例 → 渲染 → 评审 → 说明文字工作流
• references/chart-patterns.md — matplotlib 样式和图表类型示例
• references/diagram-patterns.md — 概念图示例
• references/aspect-ratios.md — 12 种允许的纵横比在 300 DPI 下对应的像素目标
• references/paperbanana-cookbook.md — 新 PaperBanana 设置、用法、成本说明和署名要求
• scripts/render_matplotlib.py — 将 JSON 绘图规范渲染为 PNG（matplotlib 后备方案）
• scripts/render_diagram.py — 将 JSON 概念图规范渲染为 PNG（matplotlib 后备方案）
• scripts/paperbanana_render.py — 新 PaperBanana 骨干封装器（从环境变量读取 PAPERBANANA_PATH）
• scripts/figure_lint.py — 新 分辨率／纵横比／说明文字覆盖率关卡；--paper 会交叉检查 \includegraphics