Sunrich-HT/figure-extractor

图表提取技能

当用户需要从 PDF、arXiv 论文或 HTML 文章页面中提取完整图表或图像时，使用本技能。

本技能实际是什么（请先阅读）

figure-extractor 是一个命令行工具（Python + PyMuPDF）。所谓“使用它”，即在 shell 中运行其 CLI——例如 figure-extractor extract paper.pdf。它不是可在智能体内部直接调用的函数、托管服务或可激活的“页面”，也无法在无法运行 Shell 或安装 Python 包的环境中执行（例如 Notion 智能体、纯浏览器智能体）。

调用约定

• 机制： shell 命令 figure-extractor <子命令> ...（通过 pip install -e . 安装）。
• 输入： 本地 PDF/HTML 路径或 PDF/arXiv/HTML URL。
• 输出： PNG 文件 + manifest.json + contact_sheet.jpg（+ 可选的 figures.zip），写入到 --out 目录。

步骤 0 — 前提条件检查（始终先做）

在承诺进行图表提取之前，务必验证该工具在此环境中确实可运行：

figure-extractor --help     # 如果此命令报错，或没有 shell，则该工具不可用

• 可用（命令可运行）→ 遵循首选算法。
• 不可用（无 shell / 未安装 / 沙箱限制）→ 转到降级模式。 工具不可用不算失败，也不违反规则——请优雅降级并告知用户你所做的处理。

核心规则（当提取器可用时）

不要仅依赖内嵌的 PDF 图像提取。许多图表由矢量图形、文字标签、图例和光栅片段组成。内嵌图像提取常返回不完整的片段——应优先使用标题边界框渲染裁剪管线。

首选算法（需要 shell + CLI）

1. 解析输入源：
   • 本地 PDF
   • PDF URL
   • arXiv 摘要 URL（/abs/ 会自动规范化为 /pdf/）
   • HTML URL
   • 本地 HTML
2. 如果可获得 HTML，首先尝试从 <figure>、<img>、<picture>、srcset 和懒加载属性中提取原始图表图像。
3. 如果 HTML 提供的图表质量不够，则定位或下载 PDF。
4. 对于 PDF：
   • 定位所有标题：Figure 2.1、Figure B.1、Extended Data Fig. 1、 Supplementary Table S3、Scheme/Algorithm/Listing/Box、图 1；
   • 恢复页面的列网格，并将每个裁剪限制在其标题所在的条带内；
   • 从图形基元生长边界框，在其他标题和正文处停止；
   • 以 300 DPI 渲染页面并进行裁剪；
   • 生成 PNG、manifest.json 和 contact_sheet.jpg。
5. 读取 manifest.json 中每个条目的 status 字段。 任何标记为 suspect 或 failed 的条目都包含 quality_reasons 以解释问题所在。 不要将 failed 的裁剪结果当作图表呈现给用户。
6. 如果裁剪错误，使用 crop --bbox 进行修正，以 manifest 已记录的边界框为起点。

降级模式（无 shell / CLI 不可用 / 位图无法访问）

当 无法运行 figure-extractor（没有 shell、没有 Python/pip、沙箱化运行环境）或 无法获取实际位图（例如 HTML 剥离了 <img> src、arXiv 图像 URL 返回 404、页面需要认证）时，使用此模式。此路径明确允许，不视为违反“核心规则”：

1. 提供原始链接。 给出直接的图表 URL、源页面或 arXiv PDF 页码 + 图表编号，以便用户打开真实图像。
2. 准确描述。 根据标题和周围文本对每个图表进行结构化解读：展示内容、坐标轴/分面板/图例、关键趋势。切勿编造你实际无法看到的图表内容。
3. 标注差距。 明确说明，例如： 位图未嵌入 — 原因：无可用 shell（或 图像 404、 src 被清理器剥离、需认证）。

降级输出 = 原始链接 + 准确的结构化描述 + 明确的“位图缺失原因”说明。这是一个可接受的结果，不构成违规。

安装

缺少包不是降级的理由——请安装它。 依赖集很小（PyMuPDF、Pillow、beautifulsoup4）；无需 GPU、无需模型、无需服务。

pip install git+https://github.com/Sunrich-HT/figure-extractor

从检出目录安装：pip install -e .

有 PDF？直接在 PDF 上运行。

如果用户附加了 PDF，或者你可以下载到一份，这是最简单最可靠的路径。不要从 HTML 或浏览器开始。

figure-extractor extract <pdf-path> --out ./figures --dpi 300 --zip

仅在无法获得 PDF 时，才尝试 HTML 路线。注意，某些环境的 HTML 抓取器会剥离 <img src>，只留下文本——遇到这种情况时，停止处理 HTML 并回头去获取 PDF。

命令

# 自动提取（本地 PDF、PDF URL、arXiv 摘要 URL 或 HTML 文章）
figure-extractor extract paper.pdf --out ./figures --dpi 300 --zip
figure-extractor extract https://arxiv.org/abs/2606.23443 --out ./figures --zip
figure-extractor extract https://openreview.net/forum?id=XXXX --out ./figures
figure-extractor extract https://example.com/article --prefer html --fallback pdf

# 仅提取图表，或仅最可能承载论点的裁剪结果
figure-extractor extract paper.pdf --kinds figure --tiers A,B

# 对单个图表手动修正边界框
figure-extractor crop paper.pdf --page 5 --bbox 295,245,556,475 --out fig04.png --dpi 300

默认设置

• dpi：300
• margin：8 PDF 点
• prefer：auto
• fallback：pdf
• kinds：all — 默认穷举提取
• tiers：A,B,C — 默认不进行任何过滤；层级是分类信号， 而非关于哪些展项承载论点的判断
• contact_sheet：true

质量控制指引

当提取器运行后，务必检查 contact_sheet.jpg 以及每个 manifest 条目的 status。suspect 和 failed 的裁剪结果在联系表上以橙色和红色标记。如果一个图表包含了周围的正文或缺少了图表的某一部分，请使用手动边界框重新运行 crop。

manifest 记录了工具所见的每个候选对象。如果 containers_found 超过实际渲染的数量，dropped 列表会说明每个未被渲染的原因——将无法解释的差异视为 bug，而非正常运行结果。