PaperFit — Vision-in-the-Loop Academic Typesetting Agent System

PaperFit 是基于 vision-in-the-loop 的多层智能体系统，面向 LaTeX 学术论文的视觉排版优化（Visual Typesetting Optimization, VTO）：在结构性格式与编译已通过的前提下，用源码 + 编译日志 + PDF + 页图等多模态证据驱动闭环，收敛到更接近出版规范的版式质量。

项目定位与贡献

| 维度 | 说明 | |------|------| | 问题 | 传统「只修编译错误」不足以覆盖孤行、浮动体堆积、双栏空洞、表格一致性等视觉与信息密度问题。 | | 思路 | 将 VTO 缺陷分类体系化（taxonomy），由调度 Agent 串联规则引擎（日志硬约束）、视觉检测（页图 + 可选 OpenCV 机检）与代码级修复，门禁统一验收。 | | 交付形态 | npm 包 paperfit-cli：全局 CLI（渲染页图、状态机、列空洞检测等）+ 可分发到 Claude Code 的 commands / skills / agents / config。 | | 可扩展性 | 技能与 Agent 解耦；config/ 集中维护模板元数据、版式规则与诊断模板；用户论文仓库内主要落盘 data/ 状态与报告。 |

安装

方式 A：npm + 全局 Claude Code（推荐）

npm install -g paperfit-cli
paperfit-install

或从 Git 安装：

npm install -g git+https://github.com/OpenRaiser/PaperFit.git
paperfit-install

克隆后本地一键（等价：安装当前目录包并执行安装脚本）：

git clone https://github.com/OpenRaiser/PaperFit.git
cd PaperFit   # 或你的克隆目录名
bash install.sh --local

安装后建议：

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

一键更新部署（全局 paperfit + ~/.claude）

只装 Claude 插件不会带上 paperfit 命令；命令来自 npm 全局包 paperfit-cli。任选其一：

| 场景 | 命令 | |------|------| | 任意目录（推荐，不依赖 cd 克隆） | npx -y paperfit-cli@latest upgrade（拉最新全局包并同步 ~/.claude；首次会较慢） | | 本机已有 paperfit | paperfit upgrade（registry 最新）或先 cd 到克隆根再 paperfit upgrade --local（npm install -g . + 同步） | | 仅在克隆根目录（该目录下必须有 package.json） | npm run upgrade（等价 bash install.sh --update --local） | | 只从 registry 拉最新、不依赖克隆 | npx -y paperfit-cli@latest upgrade 或 curl -fsSL https://raw.githubusercontent.com/OpenRaiser/PaperFit/main/install.sh \| bash -s -- --update（勿在 ~ 使用 npm run，因无 package.json） | | 已在克隆根、只想跑脚本不写 npx | npm run upgrade:registry（等价 bash install.sh --update） | | 尚未安装过全局 CLI | bash install.sh --update 或 curl -fsSL https://raw.githubusercontent.com/OpenRaiser/PaperFit/main/install.sh \| bash -s -- --update |

注意：npm run upgrade 不能在家目录执行；必须在 PaperFit 克隆仓库根打开终端，否则会报 Could not read package.json。不想记路径就用上一行的 npx … upgrade 或 paperfit upgrade。

上述步骤都会执行 paperfit install-global（或 paperfit-install），把包内 agents/skills/commands 同步到 ~/.claude。Claude 插件仍须在会话里单独更新，例如：/plugin marketplace update paperfit-vto → /plugin update paperfit@paperfit-vto。

Claude Code 插件市场：本仓库含 .claude-plugin/marketplace.json，市场标识 paperfit-vto。在 Claude Code 中：

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

详见 .claude-plugin/README.md。不经 marketplace 时，可在克隆根目录执行 claude plugin add .（视 CLI 版本而定）。

方式 B：仅克隆（开发或离线）

git clone https://github.com/OpenRaiser/PaperFit.git
cd PaperFit
npm install
paperfit install-global --dry-run
paperfit install-global

系统依赖

• Poppler（pdfinfo 等）：页图与部分脚本依赖。
• Python 3.8+：见仓库根目录 requirements.txt（pdf2image、opencv-python-headless、PyYAML、questionary 等）。

# macOS
brew install poppler

使用方法

Claude Code 斜杠命令（主入口）

在已安装插件或已将 .claude/ 同步到 ~/.claude 的前提下，于论文项目根目录打开 Claude Code，使用例如：

| 命令 | 作用 | |------|------| | /paperfit | 对话中确认主 tex、投稿模板、页数口径与目标页等；生成 data/paperfit-portrait.yaml 并同步 state.json 中的画像字段；提示后续命令。 | | /fix-layout | 启动完整 VTO 闭环：编译 → 页图 →（双栏场景）列空洞机检合并 → 规则与视觉检测 → 修复 → 门禁，直至 DONE 或中断。 | | /check-visual | 仅编译与视觉检测，输出诊断，默认不做大规模自动修复。 | | /repair-table | 针对表格的局部修复闭环。 | | /adjust-length | 在页数约束下做版式与必要时语义层面的长度调整。 | | /migrate-template | 跨会议/期刊模板迁移相关闭环。 | | /show-status | 读取 data/state.json 等，展示任务与缺陷摘要。 |

命令正文位于 .claude/commands/*.md，调度逻辑见 agents/orchestrator-agent.md。

CLI（paperfit / npx paperfit-cli）

在论文项目根执行（脚本来自已安装包，勿假设论文仓库内自带同名 scripts/）：

| 子命令 | 说明 | |--------|------| | paperfit render <pdf> --output data/pages … | 将 PDF 渲染为逐页 PNG。 | | paperfit run scripts/<脚本> [参数…] | 运行包内 scripts/ 下 .py / .sh（如 state_manager.py、parse_log.py、detect_column_void.py）。 | | paperfit init | 环境检查；--interactive 可调终端问卷脚本。 | | paperfit wizard | 终端交互：模板、页数口径等 → data/paperfit-project.yaml 并初始化 state。 | | paperfit run scripts/paperfit_portrait.py … | 非交互论文画像：build（参数 + 扫描）或 refresh（重扫），见脚本 --help。 | | paperfit status / paperfit doctor / paperfit root | 状态摘要、依赖体检、打印包根路径。 | | paperfit install-global | 将 commands/skills/agents 等合并到 ~/.claude。 | | paperfit upgrade | 一键：npm install -g paperfit-cli@latest + install-global；--local 在克隆根使用当前目录作为包源。 |

VTO 缺陷分类（摘要）

• A 空间利用（孤行、末页留白、双栏高度等）
• B 浮动体（位置、尺寸、堆叠等）
• C 一致性（表格/图表/Caption 风格）
• D 溢出与对齐（Overfull、公式断行等）
• E 跨模板迁移（单双栏、宏兼容等）

完整定义见 config/vto_taxonomy.yaml 与技能 taxonomy-vto。

Agents 与 Skills（摘要）

| Agent | 职责 | |-------|------| | orchestrator-agent | 主调度与状态机 | | layout-detective-agent | 视觉缺陷检测 | | rule-engine-agent | 编译日志与硬约束 | | code-surgeon-agent | 源码级修复编排 | | semantic-polish-agent | 受控语义微调 | | quality-gatekeeper-agent | 门禁与 DONE/CONTINUE |

| Skill | 侧重 | |-------|------| | taxonomy-vto | 分类体系 | | space-util-fixer / float-optimizer / consistency-polisher / overflow-repair / template-migrator | 对应 A–E 与迁移 | | visual-inspector | 页图与视觉验收 | | writing-polish | 写作层面微调说明 |

项目结构（逐文件说明）

以下路径均相对于本仓库根目录（npm 包内容以 package.json 的 files 字段为准；不含 node_modules）。用户论文项目内常见的 data/ 由运行时生成，通常已 .gitignore，表中仅说明用途。

根目录

| 文件 | 说明 | |------|------| | package.json | npm 包元数据、bin 入口、files 发布清单。 | | package-lock.json | 依赖锁定。 | | requirements.txt | Python 依赖（页图、OpenCV 机检、YAML、问卷等）。 | | install.sh | 根目录一键安装/一键更新：--local、--update、--update --local；内部调用 paperfit install-global。 | | LICENSE | MIT 许可证全文。 | | CONTRIBUTING.md | 贡献指南。 | | README.md | 本说明文档。 | | CLAUDE.md | Claude Code 项目级系统提示与约定，与分发副本配合使用。 | | .gitignore | Git 忽略规则（如 node_modules、data/ 等）。 |

bin/

| 文件 | 说明 | |------|------| | paperfit.js | paperfit CLI：render、run、init、wizard、portrait、status、doctor、install-global 等子命令入口。 |

agents/

| 文件 | 说明 | |------|------| | orchestrator-agent.md | 主调度器：与斜杠命令衔接、迭代闭环与状态更新约定。 | | layout-detective-agent.md | 排版侦探：基于 taxonomy 的视觉缺陷检测。 | | rule-engine-agent.md | 规则引擎：编译日志解析与约束。 | | code-surgeon-agent.md | 代码外科：修复任务分发与回写策略。 | | semantic-polish-agent.md | 语义润色：最小改写边界。 | | quality-gatekeeper-agent.md | 质量门禁：证据汇总与通过/继续决策。 |

skills/（各子目录内主要为 SKILL.md）

| 路径 | 说明 | |------|------| | taxonomy-vto/SKILL.md | VTO 分类知识库，供检测与修复对齐术语。 | | visual-inspector/SKILL.md | PDF/页图视觉检查与验收流程。 | | space-util-fixer/SKILL.md | Category A 空间利用修复。 | | float-optimizer/SKILL.md | Category B 浮动体优化。 | | consistency-polisher/SKILL.md | Category C 一致性。 | | overflow-repair/SKILL.md | Category D 溢出与对齐。 | | template-migrator/SKILL.md | Category E 模板迁移。 | | writing-polish/SKILL.md | 受控扩写/缩写等写作侧说明。 | | latex_fixers/__init__.py | 包初始化。 | | latex_fixers/utils.py | 修复器共用工具函数。 | | latex_fixers/float_fixers.py | 浮动体相关可调用修复逻辑。 | | latex_fixers/space_util_fixers.py | 空间利用相关修复逻辑。 | | latex_fixers/overflow_fixers.py | 溢出相关修复逻辑。 | | latex_fixers/fullwidth_fixers.py | 通栏/宽度相关修复逻辑。 | | latex_fixers/semantic_micro_tuning.py | 语义微调辅助逻辑。 |

config/

| 文件 | 说明 | |------|------| | vto_taxonomy.yaml | VTO 缺陷分类体系与条目定义。 | | templates.yaml | 常见会议/期刊 LaTeX 模板元数据（栏型、页数期望等）。 | | layout_rules.yaml | 版式规则配置。 | | agent_roles.yaml | Agent 角色与边界说明（供编排引用）。 | | writing_rules.yaml | 写作/语义侧规则。 | | diagnostic_report.template.md | 诊断报告 Markdown 模板。 |

scripts/

| 文件 | 说明 | |------|------| | render_pages.py | PDF → 逐页 PNG（供视觉检测）。 | | parse_log.py | 解析 LaTeX 编译日志。 | | compile.sh | 编译封装示例/辅助。 | | state_manager.py | data/state.json 初始化、读写、备份、column-void 报告合并等。 | | configure_wizard.py | 终端交互问卷 → paperfit-project.yaml 与 state 初始化。 | | paperfit_portrait.py | 非交互「论文画像」：build/refresh，写 paperfit-portrait.yaml 并更新 state 画像字段。 | | detect_column_void.py | 双栏页图 OpenCV 列内竖向空洞（A5 辅助）检测，输出 JSON 报告。 | | cv_detector.py | 计算机视觉相关检测能力（与流水线配合）。 | | evidence_collector.py | 多模态证据收集/整理辅助。 | | benchmark_runner.py | 基准/评测运行入口。 | | inject_defects.py | 向用例注入缺陷（评测用）。 | | config_validator.py | 配置校验。 | | session_logger.py | 会话或运行日志辅助。 | | pre_tool_use.py | 工具调用前钩子示例/实现。 | | test_integration.py | 集成测试。 | | test_commands.py | 命令相关测试。 | | test_cv_detector.py | CV 检测单元测试。 | | float_fixers.py / space_util_fixers.py / overflow_fixers.py | 与技能并行的脚本侧修复或演示入口（视仓库演进与 skills 引用关系而定）。 | | install-claude-global.js | paperfit-install / install-global：合并 .claude 等到用户目录。 | | install.js | npm install 相关逻辑（若存在）。 | | postinstall.js | npm postinstall 钩子。 | | scripts/install.sh | 包内 Bash 安装辅助（与根目录 install.sh 不同）。 | | package-for-opensource.sh | 开源打包脚本。 |

.claude/commands/

| 文件 | 说明 | |------|------| | paperfit.md | /paperfit：画像冷启动与刷新流程、与 CLI 脚本衔接说明。 | | fix-layout.md | /fix-layout：完整 VTO 闭环。 | | check-visual.md | /check-visual：仅检测。 | | repair-table.md | /repair-table：表格修复。 | | adjust-length.md | /adjust-length：页数/长度调整。 | | migrate-template.md | /migrate-template：模板迁移。 | | show-status.md | /show-status：状态只读展示。 |

.claude-plugin/

| 文件 | 说明 | |------|------| | marketplace.json | Claude Code 插件市场清单条目。 | | README.md | 插件市场安装与标识说明。 |

docs/

| 文件 | 说明 | |------|------| | ARCHITECTURE_GAPS.md | 架构缺口与改进记录。 | | COMMAND_TEST_GUIDE.md | 命令测试指南。 | | COMMANDS_SETUP.md | 命令与安装/setup 说明。 | | PHASE1_SUMMARY.md | 阶段一总结。 | | ECC_BENCHMARK_20DIM.md | ECC 类基准维度说明。 |

用户论文项目中的 data/（运行时，本仓库仅作示例或忽略）

| 路径/模式 | 说明 | |-----------|------| | data/state.json | 任务状态机：轮次、任务参数、机检摘要引用等。 | | data/paperfit-project.yaml | 终端向导写入的用户侧项目参数（若使用 wizard）。 | | data/paperfit-portrait.yaml | 用户约束 + 扫描摘要的合成画像（若使用 /paperfit 或 portrait）。 | | data/pages/ | 页图输出目录（常见配置）。 | | data/reports/ | 各类 JSON/Markdown 报告（如列空洞）。 | | data/backups/、data/archives/ 等 | 状态与用例备份（由 state_manager 等写入）。 |

License

MIT License — 详见 LICENSE。