JinDaGe - paperbanana MCP Details

article

README

🚀 PaperBanana

PaperBanana 是一个为人工智能科学家打造的自动化学术插图生成框架，能根据文本描述生成高质量的学术图表和统计绘图。它支持多种图像生成模型，如 OpenAI（GPT - 5.2 + GPT - Image - 1.5）、Azure OpenAI / Foundry 以及 Google Gemini 等。

🚀 快速开始

前提条件

Python 3.10 及以上版本
拥有 OpenAI API 密钥（[platform.openai.com](https://platform.openai.com/api - keys)）或 Azure OpenAI / Foundry 端点
或者拥有 Google Gemini API 密钥（免费，Google AI Studio）

步骤 1：安装

pip install paperbanana

若要进行开发，可从源码安装：

git clone https://github.com/llmsresearch/paperbanana.git
cd paperbanana
pip install -e ".[dev,openai,google]"

步骤 2：获取 API 密钥

cp .env.example .env
# 编辑 .env 文件并添加你的 API 密钥：
#   OPENAI_API_KEY=your - key - here
#   GOOGLE_API_KEY=your - key - here
#
# 对于 Azure OpenAI / Foundry：
#   OPENAI_BASE_URL=https://<resource>.openai.azure.com/openai/v1
#
# 可选的 Gemini 覆盖设置：
#   GOOGLE_BASE_URL=https://your - gemini - proxy.example.com
#   GOOGLE_VLM_MODEL=gemini - 2.0 - flash
#   GOOGLE_IMAGE_MODEL=gemini - 3 - pro - image - preview

或者使用 Gemini 的设置向导：

paperbanana setup

步骤 3：生成图表

paperbanana generate \
  --input examples/sample_inputs/transformer_method.txt \
  --caption "Overview of our encoder - decoder architecture with sparse routing"

使用输入优化和自动优化功能：

paperbanana generate \
  --input my_method.txt \
  --caption "Overview of our encoder - decoder framework" \
  --optimize --auto

输出结果将保存到 outputs/run_<timestamp>/final_output.png，同时保存所有中间迭代和元数据。

✨ 主要特性

采用两阶段多智能体管道，支持迭代优化
支持多种视觉语言模型（VLM）和图像生成提供商，如 OpenAI、Azure、Gemini
具备输入优化层，可提升生成质量
支持自动优化模式，并可根据用户反馈继续运行
提供命令行界面（CLI）、Python API 以及 MCP 服务器，方便与 IDE 集成
支持从清单文件（YAML/JSON）进行批量生成，一次运行可生成多个图表
具备 Claude Code 技能，可用于 /generate - diagram、/generate - plot 和 /evaluate - diagram

📦 安装指南

从 PyPI 安装

pip install paperbanana

从源码安装（用于开发）

git clone https://github.com/llmsresearch/paperbanana.git
cd paperbanana
pip install -e ".[dev,openai,google]"

💻 使用示例

基础用法

# 基本生成
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework"

高级用法

# 使用输入优化和自动优化
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

# 根据用户反馈继续上一次运行
paperbanana generate --continue \
  --feedback "Make arrows thicker and colors more distinct"

# 继续特定运行
paperbanana generate --continue - run run_20260218_125448_e7b876 \
  --iterations 3

📚 详细文档

CLI 参考

`paperbanana generate` -- 方法图表生成

# 基本生成
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework"

# 带输入优化和自动优化
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

# 继续最新运行并提供用户反馈
paperbanana generate --continue \
  --feedback "Make arrows thicker and colors more distinct"

# 继续特定运行
paperbanana generate --continue - run run_20260218_125448_e7b876 \
  --iterations 3

| 标志 | 简写 | 描述 | |------|-------|-------------| | --input | -i | 方法文本文件路径（新运行时必需） | | --caption | -c | 图表标题 / 交流意图（新运行时必需） | | --output | -o | 输出图像路径（默认：在 outputs/ 中自动生成） | | --iterations | -n | 可视化器 - 评估器优化轮数（默认：3） | | --auto | | 循环直到评估器满意（有 --max - iterations 安全上限） | | --max - iterations | | --auto 模式的安全上限（默认：30） | | --optimize | | 使用并行上下文丰富和标题锐化预处理输入 | | --continue | | 从 outputs/ 中的最新运行继续 | | --continue - run | | 从特定运行 ID 继续 | | --feedback | | 继续运行时提供给评估器的用户反馈 | | --vlm - provider | | VLM 提供商名称（默认：openai） | | --vlm - model | | VLM 模型名称（默认：gpt - 5.2） | | --image - provider | | 图像生成提供商（默认：openai_imagen） | | --image - model | | 图像生成模型（默认：gpt - image - 1.5） | | --format | -f | 输出格式：png、jpeg 或 webp（默认：png） | | --config | | YAML 配置文件路径（见 configs/config.yaml） | | --verbose | -v | 显示详细的智能体进度和时间 |

`paperbanana plot` -- 统计绘图

paperbanana plot \
  --data results.csv \
  --intent "Bar chart comparing model accuracy across benchmarks"

| 标志 | 简写 | 描述 | |------|-------|-------------| | --data | -d | 数据文件路径，CSV 或 JSON（必需） | | --intent | | 绘图的交流意图（必需） | | --output | -o | 输出图像路径 | | --iterations | -n | 优化迭代次数（默认：3） |

`paperbanana batch` -- 批量生成

paperbanana batch --manifest examples/batch_manifest.yaml --optimize

清单文件格式（YAML 或 JSON，包含 items 列表）：

items:
  - input: path/to/method1.txt
    caption: "Overview of our encoder - decoder"
    id: fig1
  - input: method2.txt
    caption: "Training pipeline"
    id: fig2

清单中的路径相对于清单文件所在目录解析。

# 从现有批量运行生成人类可读报告（Markdown 或 HTML）
paperbanana batch - report --batch - dir outputs/batch_20250109_123456_abc --format markdown
# 或按批量 ID（在默认输出目录下）
paperbanana batch - report --batch - id batch_20250109_123456_abc --format html --output report.html

| 标志 | 简写 | 描述 | |------|-------|-------------| | --manifest | -m | 清单文件路径（必需） | | --output - dir | -o | 批量运行的父目录（默认：outputs） | | --config | | 配置 YAML 文件路径 | | --iterations | -n | 每个项目的优化迭代次数 | | --optimize | | 对每个项目的输入进行预处理 | | --auto | | 每个项目循环直到评估器满意 | | --format | -f | 输出图像格式（png、jpeg、webp） | | --auto - download - data | | 需要时下载扩展参考集 |

`paperbanana evaluate` -- 质量评估

paperbanana evaluate \
  --generated diagram.png \
  --reference human_diagram.png \
  --context method.txt \
  --caption "Overview of our framework"

| 标志 | 简写 | 描述 | |------|-------|-------------| | --generated | -g | 生成图像的路径（必需） | | --reference | -r | 人类参考图像的路径（必需） | | --context | | 源上下文文本文件的路径（必需） | | --caption | -c | 图表标题（必需） | 评估将在 4 个维度上打分（按论文进行分层聚合）：

主要维度：忠实度、可读性
次要维度：简洁性、美观性

`paperbanana setup` -- 首次配置

paperbanana setup

交互式向导，首先询问是否使用官方 Gemini API。如果选择官方 API，将遵循默认的 AI Studio 密钥流程；否则，将要求输入自定义的 Gemini 兼容 URL 和 API 密钥。

Python API

import asyncio
from paperbanana import PaperBananaPipeline, GenerationInput, DiagramType
from paperbanana.core.config import Settings

settings = Settings(
    vlm_provider="openai",
    vlm_model="gpt-5.2",
    image_provider="openai_imagen",
    image_model="gpt-image-1.5",
    optimize_inputs=True,   # 启用输入优化
    auto_refine=True,       # 循环直到评估器满意
)

pipeline = PaperBananaPipeline(settings=settings)

result = asyncio.run(pipeline.generate(
    GenerationInput(
        source_context="Our framework consists of...",
        communicative_intent="Overview of the proposed method.",
        diagram_type=DiagramType.METHODOLOGY,
    )
))

print(f"Output: {result.image_path}")

继续之前的运行：

from paperbanana.core.resume import load_resume_state

state = load_resume_state("outputs", "run_20260218_125448_e7b876")
result = asyncio.run(pipeline.continue_run(
    resume_state=state,
    additional_iterations=3,
    user_feedback="Make the encoder block more prominent",
))

完整的工作示例请参考 examples/generate_diagram.py 和 examples/generate_plot.py。

MCP 服务器

PaperBanana 包含一个 MCP 服务器，可与 Claude Code、Cursor 或任何 MCP 兼容的客户端一起使用。通过 uvx 使用时，添加以下配置，无需本地克隆：

{
  "mcpServers": {
    "paperbanana": {
      "command": "uvx",
      "args": ["--from", "paperbanana[mcp]", "paperbanana-mcp"],
      "env": { "GOOGLE_API_KEY": "your-google-api-key" }
    }
  }
}

暴露了三个 MCP 工具：generate_diagram、generate_plot 和 evaluate_diagram。仓库还附带了 3 个 Claude Code 技能：

/generate - diagram <file> [caption] - 从文本文件生成方法图表
/generate - plot <data - file> [intent] - 从 CSV/JSON 数据生成统计绘图
/evaluate - diagram <generated> <reference> - 将生成的图表与人类参考图表进行评估

完整的设置细节请参考 mcp_server/README.md。

配置

默认设置位于 configs/config.yaml，可通过 CLI 标志或自定义 YAML 文件进行覆盖：

paperbanana generate \
  --input method.txt \
  --caption "Overview" \
  --config my_config.yaml

关键设置：

vlm:
  provider: openai           # openai, gemini, or openrouter
  model: gpt-5.2

image:
  provider: openai_imagen    # openai_imagen, google_imagen, or openrouter_imagen
  model: gpt-image-1.5

pipeline:
  num_retrieval_examples: 10
  refinement_iterations: 3
  # auto_refine: true        # 循环直到评估器满意
  # max_iterations: 30       # auto_refine 模式的安全上限
  # optimize_inputs: true    # 预处理输入以提高生成质量
  output_resolution: "2k"

reference:
  path: data/reference_sets

output:
  dir: outputs
  save_iterations: true
  save_metadata: true

环境变量（.env）：

# OpenAI（默认）
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1    # 或 Azure 端点
OPENAI_VLM_MODEL=gpt-5.2                      # 覆盖模型
OPENAI_IMAGE_MODEL=gpt-image-1.5              # 覆盖模型

# Google Gemini（替代方案，免费）
GOOGLE_API_KEY=your-key
GOOGLE_BASE_URL=                            # 可选的自定义 Gemini 兼容端点
GOOGLE_VLM_MODEL=gemini-2.0-flash          # 覆盖 Gemini VLM 模型
GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview  # 覆盖 Gemini 图像模型

🔧 技术细节

工作原理

PaperBanana 实现了一个多智能体管道，最多包含 7 个专门的智能体：

阶段 0 -- 输入优化（可选，`--optimize`）

输入优化器 并行运行两个 VLM 调用：
- 上下文丰富器 将原始方法文本转换为适合图表生成的格式（组件、流程、分组、输入输出）
- 标题锐化器 将模糊的标题转换为精确的视觉规格

阶段 1 -- 线性规划

检索器 从精心挑选的 13 个方法图表参考集中选择最相关的示例，这些图表涵盖了智能体/推理、视觉/感知、生成/学习以及科学/应用等领域
规划器 通过从检索到的示例中进行上下文学习，生成目标图表的详细文本描述
风格器 使用 NeurIPS 风格指南（调色板、布局、排版）优化描述以提升视觉美感

阶段 2 -- 迭代优化

可视化器 将描述渲染为图像
评估器 根据源上下文评估生成的图像，并提供修订后的描述以解决任何问题
步骤 4 - 5 重复固定次数的迭代（默认 3 次），或直到评估器满意（--auto）

支持的提供商

PaperBanana 支持多种 VLM 和图像生成提供商： | 组件 | 提供商 | 模型 | 说明 | |-----------|----------|-------|-------| | VLM（规划、评估） | OpenAI | gpt - 5.2 | 默认 | | 图像生成 | OpenAI | gpt - image - 1.5 | 默认 | | VLM | Google Gemini | gemini - 2.0 - flash | 免费层 | | 图像生成 | Google Gemini | gemini - 3 - pro - image - preview | 免费层 | | VLM / 图像 | OpenRouter | 任何支持的模型 | 灵活路由 | Azure OpenAI / Foundry 端点会自动检测，设置 OPENAI_BASE_URL 为你的端点。也支持 Gemini 兼容的网关，必要时设置 GOOGLE_BASE_URL。

📄 许可证

本项目采用 MIT 许可证。

免责声明

本项目是基于公开可用论文的独立开源重新实现，与原作者、Google Research 或北京大学没有任何关联、认可或联系。实现可能与论文中描述的原始系统有所不同，请自行决定是否使用。

引用

这是一个 非官方 实现。如果使用此项目，请引用 原始论文：

@article{zhu2026paperbanana,
  title={PaperBanana: Automating Academic Illustration for AI Scientists},
  author={Zhu, Dawei and Meng, Rui and Song, Yale and Wei, Xiyu
          and Li, Sujian and Pfister, Tomas and Yoon, Jinsung},
  journal={arXiv preprint arXiv:2601.23265},
  year={2026}
}

原始论文：https://arxiv.org/abs/2601.23265

paperbanana

README

🚀 PaperBanana

🚀 快速开始

前提条件

步骤 1：安装

步骤 2：获取 API 密钥

步骤 3：生成图表

✨ 主要特性

📦 安装指南

从 PyPI 安装

从源码安装（用于开发）

💻 使用示例

基础用法

高级用法

📚 详细文档

CLI 参考

`paperbanana generate` -- 方法图表生成

`paperbanana plot` -- 统计绘图

`paperbanana batch` -- 批量生成

`paperbanana evaluate` -- 质量评估

`paperbanana setup` -- 首次配置

Python API

MCP 服务器

配置

🔧 技术细节

工作原理

阶段 0 -- 输入优化（可选，`--optimize`）

阶段 1 -- 线性规划

阶段 2 -- 迭代优化

支持的提供商

📄 许可证

免责声明

引用

Runtime guide

Hosted runtime

Local runtime / other methods

paperbanana

README

🚀 PaperBanana

🚀 快速开始

前提条件

步骤 1：安装

步骤 2：获取 API 密钥

步骤 3：生成图表

✨ 主要特性

📦 安装指南

从 PyPI 安装

从源码安装（用于开发）

💻 使用示例

基础用法

高级用法

📚 详细文档

CLI 参考

paperbanana generate -- 方法图表生成

paperbanana plot -- 统计绘图

paperbanana batch -- 批量生成

paperbanana evaluate -- 质量评估

paperbanana setup -- 首次配置

Python API

MCP 服务器

配置

🔧 技术细节

工作原理

阶段 0 -- 输入优化（可选，--optimize）

阶段 1 -- 线性规划

阶段 2 -- 迭代优化

支持的提供商

📄 许可证

免责声明

引用

Runtime guide

Hosted runtime

Local runtime / other methods

`paperbanana generate` -- 方法图表生成

`paperbanana plot` -- 统计绘图

`paperbanana batch` -- 批量生成

`paperbanana evaluate` -- 质量评估

`paperbanana setup` -- 首次配置

阶段 0 -- 输入优化（可选，`--optimize`）