paperfit-cli

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。