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]}，用于表格/公式局部复查

输出规范

本技能输出两份产物：

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 提示用户安装。

第二步：执行渲染

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

paperfit render <相对或绝对路径的.pdf> --output data/pages --dpi 220
# 示例
paperfit render main.pdf --dpi 300

前提：npm install -g paperfit-cli（或等价全局安装），paperfit 在 PATH 中。输出目录 --output 相对于当前工作目录（一般为论文根目录）。

其它包内 Python/Bash（如 parse_log.py、state_manager.py）一律在论文根目录使用 paperfit run scripts/<文件名> [参数…]，勿在用户项目里假设存在同名 scripts/。