visual-inspector

Visual Inspector Skill

概述

本技能是 PaperFit 视觉排版优化闭环中的关键环节，专门负责 PDF 页图渲染与视觉验收指导。它封装了将 PDF 转换为逐页高分辨率图片的标准化流程，并为 layout-detective-agent 和 quality-gatekeeper-agent 提供详细的逐页视觉检查清单。

该技能由 orchestrator-agent 在每次编译后调用，确保多模态证据链中的“页图”环节可靠、一致且可复现。

适用场景

• 每次编译成功后，需生成页图供视觉 Agent 审查。
• 手动触发视觉检查（如 /check-visual 命令）。
• 修复前后对比验证。

输入规范

输入项	来源	必需	说明
PDF 文件路径	编译输出	✅	通常为 main.pdf
输出目录	配置或默认	✅	页图存放目录，默认为 data/pages/
DPI 参数	配置或调用方指定	✅	渲染分辨率，默认 220 DPI
页码范围	调用方指定	⚠️	若为空，渲染全部页面
局部裁剪参数	调用方指定	⚠️	如 {page: 5, bbox: [x,y,w,h]}，用于表格/公式局部复查
PDF native geometry	编译输出 PDF	⚠️	若安装 PyMuPDF，可作为 B2 宽度和 D1 overflow 的辅助机器信号

输出规范

本技能输出两份产物：

1. 页图文件集：PNG 或 JPG 格式的逐页图片，命名规则为 page_001.png、page_002.png 等。
2. 渲染报告 JSON：

{
  "skill": "visual-inspector",
  "status": "success | partial | failed",
  "pdf_path": "main.pdf",
  "output_dir": "data/pages/",
  "dpi": 220,
  "pages_rendered": 9,
  "page_files": [
    {"page": 1, "file": "data/pages/page_001.png", "width": 1700, "height": 2200},
    {"page": 2, "file": "data/pages/page_002.png", "width": 1700, "height": 2200}
  ],
  "cropped_regions": [
    {
      "page": 5,
      "object": "Table 2",
      "file": "data/pages/page_005_table2.png",
      "bbox": [100, 450, 800, 300]
    }
  ],
  "errors": []
}

渲染流程

第一步：环境检查

1. 确认 PDF 文件存在且可读。
2. 检查 Python 环境及所需依赖：
   • pdf2image 库
   • Poppler 工具（pdftoppm 或 pdftocairo）

若 Poppler 未安装，根据操作系统提供安装指引：

# Debian/Ubuntu
sudo apt-get install poppler-utils

# macOS
brew install poppler

# Windows
# 下载 poppler 并添加到 PATH，或使用 conda install -c conda-forge poppler

1. 若依赖缺失，报告错误并终止，由上层 Agent 提示用户安装。

可选 native geometry 检测依赖：

• PyMuPDF（Python import 名为 fitz）：用于读取 PDF 原生 object/text bbox，辅助检测 B2 宽度不足/超宽与 D1 native overflow。
• 该信号不是页图验收替代品；即使 PyMuPDF 不可用，也应继续渲染页图并完成视觉检查。

第二步：执行渲染

禁止在用户 LaTeX 项目里假设存在 scripts/render_pages.py。页图渲染由 PaperFit npm/CLI 包提供，在论文项目根目录执行：