PaperFit

Vision-in-the-Loop Academic Typesetting Agent System

PaperFit 是面向 Claude Code、Codex、Cursor 的 LaTeX 论文排版 Agent System。你只需要在论文项目根目录描述目标，PaperFit 会自动完成编译、页图渲染、视觉诊断、源码修复与最终验收。

为什么需要 PaperFit

论文的 LaTeX 编译通过，并不代表版面已经合格。真实投稿前常见的问题往往发生在视觉层面：浮动体堆在一起、双栏页面出现大面积空洞、表格风格不一致、公式或表格溢出、模板迁移后对象位置失控。这些问题很难只靠 .log 文件发现，也很难靠一次性文本改写稳定解决。

PaperFit 把论文排版视为一个视觉闭环任务：先把 PDF 渲染成页面图像，再结合 LaTeX 日志、交叉引用和模板规则判断问题，最后回写源码并重新渲染验收。它的目标不是替代作者写论文，而是把“看版面、修源码、再检查”的重复劳动交给 Agent。

核心能力

真实效果展示

下面的案例来自 PaperFit 的真实排版修复效果展示。

适合场景

• 投稿前检查论文是否存在明显视觉排版缺陷。
• 将已有论文迁移到新的会议模板，并尽量保持内容和对象稳定。
• 把正文压缩到目标页数，同时尽量不改变学术含义。
• 修复宽表、浮动体堆叠、双栏空洞、overfull、caption 不一致等问题。
• 在 Agent 宿主中用自然语言发起排版任务，而不是手动串脚本。

快速开始

安装完成后，在论文项目根目录直接对宿主说目标即可：

用 PaperFit 分析这篇论文的排版问题

Use the paperfit agent to inspect this paper's layout and tell me the main visual defects

用 PaperFit 把这篇论文迁移到 CVPR 模板，并尽量保持图表和引用稳定

用 PaperFit 把正文压到 8 页，尽量不要改学术内容

PaperFit 会自动推断主 .tex 文件、当前模板、页面预算和需要进入的修复路径。只有在项目结构不清楚、环境缺失或目标本身有歧义时，它才需要你补充信息。

安装

环境要求

• Node.js 18+
• Python 3.8+
• Poppler：用于 PDF 信息读取和页图渲染
• LaTeX 编译环境：如 tectonic、pdflatex 或模板要求的工具链

macOS 上可安装 Poppler：

brew install poppler

npm 安装

npm install -g paperfit-cli
paperfit-install --target claude

也可以安装到其他宿主：

paperfit-install --target codex
paperfit-install --target cursor --project /path/to/paper
paperfit-install --target all

安装后建议运行一次体检，并安装 Python 依赖：

paperfit doctor --target claude
pip3 install -r "$(npm root -g)/paperfit-cli/requirements.txt"

从源码安装

git clone https://github.com/OpenRaiser/PaperFit.git
cd PaperFit
npm install
bash install.sh --local --target claude

Claude Code 插件市场安装：

/plugin marketplace add OpenRaiser/PaperFit
/plugin install paperfit@paperfit-vto

Codex provider 相关说明见 docs/CODEX_PROVIDER_SETUP.md。

使用方法

PaperFit 的推荐入口是自然语言，而不是记忆内部命令。

常见任务：

工作流

PaperFit 的闭环可以概括为：

LaTeX project
  -> compile and parse logs
  -> render PDF pages
  -> diagnose visual defects
  -> plan source-level repairs
  -> patch LaTeX safely
  -> recompile and rerender
  -> gatekeeper acceptance

视觉检查是交付前的必要步骤。PaperFit 不会只因为编译通过就宣称排版完成，也不会为了压缩页数静默删除 figure、table、caption、label 或交叉引用。

VTO 缺陷分类

PaperFit 使用 Visual Typesetting Optimization (VTO) taxonomy 来统一诊断和修复语言：

完整定义见 config/vto_taxonomy.yaml。

架构

PaperFit 由 Agent 角色、技能包、配置和执行层组成。Agent 负责判断任务和组织闭环；CLI 与脚本负责渲染、状态记录、日志解析和可重复执行的修复动作。

简化目录：

PaperFit/
├── agents/                 # Agent role definitions
├── skills/                 # PaperFit capability bundle
├── config/                 # templates, layout rules, taxonomy
├── scripts/                # render, inspect, repair, gatekeeper
├── plugins/paperfit/       # Codex plugin assets
├── .claude/commands/       # Claude Code commands
├── bin/paperfit.js         # CLI entry
├── install.sh
└── README.md

开发与验证

在仓库根目录准备开发环境：

npm install
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

运行基础验证：

npm run verify

常用开发命令：

paperfit doctor --target claude
paperfit render paper.pdf --output data/pages
paperfit status

更多安装和命令细节见：

• docs/COMMANDS_SETUP.md
• docs/RELEASE_AND_LOCAL_UPDATE.md
• .claude-plugin/README.md

内容保护

PaperFit 的自动修复必须保护学术内容和关键对象：

• 不静默删除 figure、table、caption、label、引用或实验结果。
• 不用 \resizebox、\scalebox 作为默认的表格压缩手段。
• 优先使用 table*、tabularx、列宽重构、浮动体重排等版式级方案。
• 语义编辑必须最小、可审计，并保留修复依据。

相关协议见 protocols/content-integrity-protection.md。

引用

如有帮助，请引用：

@article{yu2026paperfit,
  title={PaperFit: Vision-in-the-Loop Typesetting Optimization for Scientific Documents},
  author={Yu, Bihui and Xu, Xinglong and Jiang, Junjie and Cheng, Jiabei and Jia, Caijun and Li, Siyuan and He, Conghui and Wei, Jingxuan and Tan, Cheng},
  journal={arXiv preprint arXiv:2605.10341},
  year={2026}
}

许可证

MIT 许可证，见 LICENSE。