paperbanana

paperbanana — 路由优先的学术插图

关键词：paperbanana · methodology diagram · statistical plot · figure evaluation · plan-then-refine

这是 PaperBanana 论文（arXiv:2601.23265）的非官方社区实现。 请遵守服务提供商条款、API 预算以及各出版场所关于插图和再利用的政策。

PaperBanana 通过两阶段、多 Agent、先规划再优化的流水线，将文本或论文转换为可供发表的高质量插图。最实用的方式是选择可行的最轻量模式，而不是每次都运行完整的生成流程：

• 使用 plot 绘制数据驱动的图表（matplotlib 代码，无需图像生成密钥），先尝试再消耗图像额度
• 使用 polish 或 evaluate 修复现有插图，再考虑从头重新生成
• 使用 generate 生成单个示意图，再考虑批处理、参数扫描或编排
• 只有在有依据时才增加迭代次数、候选数量并启用 --optimize，不要默认启用
• 如果生成式插图不是合适的工具，则转用矢量编辑器、TikZ 或人工设计师

何时使用此技能

• 用户希望根据 .txt、.md 或 .pdf 生成方法论／架构示意图，而你需要选择最轻量的生成路径
• 用户有表格结果（CSV/JSON）并希望绘制图表——这比示意图成本更低，因为无需图像生成服务提供商
• 用户已有插图，希望对其进行评估（evaluate）或改进（polish），而不是重新创建
• 用户需要许多插图（清单批处理、参数扫描或整篇论文的插图套件）
• 用户希望通过 MCP 服务或 Claude Code 技能，将 PaperBanana 提供给 Agent／IDE 使用
• 用户总是倾向于手绘每张插图、硬编码使用某个服务提供商，或将迭代次数／候选数量拉满，需要坦诚地为其指出其他方案

说明

第 1 步：选择模式前，先收集一份基本信息

收集以下必要信息：

• 产物类型：方法论示意图、统计图表、待修复／评估的现有插图、多张插图，或整篇论文的插图套件
• 来源：原始方法文本、论文（.pdf/.md）、数据文件（CSV/JSON）或现有图像
• 预算／密钥：可用的服务提供商密钥（仅 VLM 或图像生成），以及任何美元预算上限
• 质量需求：快速草稿、自动优化至评审模型满意，还是扩展生成多个候选结果

按以下升级阶梯选择（从最轻量开始）：

1. 数据要绘制成图表？使用 plot / plot-batch（由 VLM 生成 matplotlib 代码，无需图像生成密钥）
2. 根据文本／PDF 生成一张示意图？使用 generate
3. 已有插图？使用 evaluate（评审）或 polish（引导式编辑），而不是重新生成
4. 根据清单生成多张示意图／图表？使用 batch / plot-batch；使用 sweep 扫描参数
5. 生成整篇论文的插图套件？使用 orchestrate
6. 生成式插图不是合适的工具（需要精确的矢量图、简单图表或受品牌设计规范限制的设计）？转用其他方案

详细的信息收集示例和替代方案见 references/intake-and-route-outs.md。

第 2 步：只安装所需配置

除非用户明确要求系统级安装，否则请使用虚拟环境。

bash bash scripts/install.sh --profile plot # 仅 VLM：统计图表 bash scripts/install.sh --profile diagram # 用于示意图的图像生成服务提供商 bash scripts/install.sh --profile pdf # + 用于 PDF 输入的 PyMuPDF bash scripts/install.sh --profile studio # + Gradio 本地 Web 界面 bash scripts/install.sh --profile mcp # MCP 服务接口 bash scripts/install.sh --profile all # 仅在确实需要完整功能时使用

然后只设置一个服务提供商密钥（OPENAI_API_KEY、GOOGLE_API_KEY、ATLASCLOUD_API_KEY 等）。 服务提供商选择和配置见 references/providers-and-config.md。

第 3 步：先了解流水线，再调整参数

每次图表生成都遵循相同的“规划后优化”循环，因此应调整各个阶段，而不是盲目猜测参数：

• 阶段 0 — 输入优化（--optimize，可选）：Context Enricher 整理原始方法文本；Caption Sharpener 精炼说明文字。并行调用两个 VLM。
• 阶段 1 — 线性规划：Retriever 选择参考示例 → Planner 通过上下文学习编写目标描述 → Stylist 应用会议风格。
• 阶段 2 — 迭代优化：Visualizer 渲染图像 → Critic 修订描述；重复 --iterations 指定的次数（默认值为 3），或直到通过 --auto 满意为止。

逐个 Agent 的完整细节见 references/pipeline-and-agents.md。

第 4 步：选择满足需求的最轻量模式

bash

成本最低：根据数据生成统计图（无需图像生成密钥）

bash scripts/run.sh plot --data results.csv --intent "Bar chart of accuracy across benchmarks"

根据文本生成单张方法图

bash scripts/run.sh generate --input method.txt --caption "Overview of our framework"

只有在普通运行效果不佳时，才添加优化和自动精修

bash scripts/run.sh generate --input method.txt --caption "Overview" --optimize --auto

完整命令列表（generate、plot、batch、plot-batch、sweep、orchestrate、 composite、evaluate、polish、venues、studio、setup、data）及其参数见 references/modes-and-cli.md。

第 5 步：先修正，再重新生成

已有图表时，不要重新运行整个流水线：

bash

根据人工参考图评估现有图表（VLM-as-Judge）

bash scripts/run.sh evaluate --generated out.png --reference human.png
--context method.txt --caption "Overview of our framework"

根据会议风格指南进行引导式编辑（使用支持图像编辑的提供方）

bash scripts/run.sh polish --input figure.png --venue icml --iterations 2

评估维度（Faithfulness、Readability、Conciseness、Aesthetics）和会议风格包见 references/evaluation-and-venues.md。

第 6 步：只有在规模确实构成问题时，才升级为批处理、参数扫描或编排

• batch / plot-batch — 根据一个清单处理多个项目；可选用 composite 将多个面板拼接为一张带标签的图
• sweep — 对同一张图按参数网格生成多个版本，并依据质量代理评分排序
• orchestrate — 解析完整论文，规划多张方法图和数据图，并生成 figure_package.json + figures.tex 文件包

只需生成一两张图时，单次运行 generate / plot 更简单、成本更低。

第 7 步：只有在重点并非运行脚本时，才向 Agent 开放

如果目标是让 Agent / IDE 访问，而不是执行定制运行，可使用 MCP 服务（11 个工具：generate_diagram、generate_plot、continue_run、evaluate_diagram、 orchestrate_figures、batch_diagrams、batch_plots、download_references、……）或随附的 Claude Code 技能（/generate-diagram、/generate-plot、/evaluate-diagram）。

bash bash scripts/run-mcp.sh # 通过 uvx --from paperbanana[mcp] 启动 stdio MCP 服务

示例

示例 1：用户有一个 CSV 文件，想要生成图表

使用 plot（或 plot-batch）——它通过 VLM 渲染 matplotlib 图表，无需图像生成密钥，因此成本最低。

示例 2：用户有一段方法描述，想要生成一张图

使用 generate 并提供清晰的 --caption；只有在首次生成效果不佳时，才添加 --optimize / --auto。

示例 3：用户已有一张“基本正确”的图

使用 polish（引导式编辑）或 evaluate（评估），不要重新运行 generate。

示例 4：用户想要重新生成论文中的所有图

对论文源文件使用 orchestrate；花费额度前，先通过 --dry-run 检查 orchestration_plan.json。

示例 5：用户想让 Agent 按需生成图表

开放 MCP 服务或 Claude Code 技能，而不是手写一次性脚本。

示例 6：图形只是简单的双柱状图或精确的矢量图

改用普通的 matplotlib、TikZ 或矢量编辑器——多 Agent 生成流程要么大材小用，要么根本不是合适的工具。

最佳实践

1. 从最简单的模式（plot < generate < batch/sweep/orchestrate）开始，只有在有证据表明需要时才升级。
2. 处理数据时优先使用 plot——它会完全跳过图像生成服务商，成本也更低。
3. 付费全面重新生成前，先用 polish/evaluate 修复现有图形。
4. 将 --optimize、--auto、--iterations 和 --num-candidates 视为成本调节项——只有普通运行效果不佳时才调高。
5. 选择满足质量要求的最低成本服务商（Gemini/Atlas VLM 成本较低）；此流水线不依赖特定服务商。
6. 使用会议风格包（neurips、icml、acl、ieee 或自定义风格包），不要每次运行都手动调整美学设置。
7. 在宣称图形已达到发表标准前，先使用 VLM-as-Judge 的 evaluate 命令进行评判。
8. 当生成式图形不是合适的工具时，应如实改用 matplotlib/TikZ/矢量编辑器，或交由人工设计师处理。

参考资料

• references/intake-and-route-outs.md
• references/pipeline-and-agents.md
• references/modes-and-cli.md
• references/providers-and-config.md
• references/evaluation-and-venues.md
• scripts/install.sh
• scripts/run.sh
• scripts/run-mcp.sh
• PaperBanana GitHub 仓库
• PaperBanana 论文（arXiv:2601.23265）