Help us improve
Share bugs, ideas, or general feedback.
From paperfit
Fixes LaTeX float/figure defects: distance from reference, width mismatch, clustering, and page orphaning. Reads cross-reference JSON and adjusts placement or moves source code.
npx claudepluginhub openraiser/paperfitHow this skill is triggered — by the user, by Claude, or both
Slash command
/paperfit:float-optimizerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
本技能专门处理 **Category B:浮动体缺陷**,包括:
Fixes LaTeX layout defects: widows/orphans, excessive trailing whitespace, page budget violations, unbalanced column heights, and vertical holes in two-column pages. Prioritizes typographic control commands over semantic rewrites.
Audits LaTeX academic manuscripts for typographic conventions including booktabs tables, caption placement, dashes/quotes, units/numbers, cross-references, layout, and polish. Useful for paper review phase.
Automates conversion of LaTeX academic papers between publisher formats (Springer/IPOL to MDPI/IEEE/Nature) via extraction, content injection, formatting fixes, and PDF compilation.
Share bugs, ideas, or general feedback.
本技能专门处理 Category B:浮动体缺陷,包括:
该技能由 code-surgeon-agent 调用,通过对浮动体位置参数、尺寸设置和周围正文结构的精确调整,实现图表与正文的和谐共处。浮动体优化是视觉排版中最具挑战性的环节之一,必须结合页图反馈迭代验证。
当 layout-detective-agent 报告中出现以下缺陷 ID 时,路由至本技能:
| 缺陷 ID | 描述 | 优先级 |
|---|---|---|
| B1 | 浮动体远离首次引用 | High |
| B2 | 浮动体大小不适配栏宽 | High |
| B3 | 浮动体连续堆叠 | Medium |
| B4 | 浮动体跨页分裂 | Medium |
| 输入项 | 来源 | 说明 |
|---|---|---|
主 .tex 文件路径 | 项目上下文 | 需修改的源文件 |
| 排版侦探报告 | layout-detective-agent 输出 | 包含缺陷对象(图表标签)、页码、描述 |
| 源码交叉引用报告 | extract_crossrefs.py 输出 (data/crossrefs.json) | 提供每个图表的首次引用行号、定义行号、行距离、节距离 |
| 当前 PDF 页图 | visual-inspector 输出 | 用于验证修复后视觉效果 |
| 模板类型 | 用户上下文或 templates.yaml | 单栏/双栏,影响浮动体宽度策略 |
输入使用说明:
crossrefs.json 的 distances[] 数组中提取 ref_line 和 figure_line,计算源码距离line_distance < 50 且 section_distance = 0)但视觉距离远 → 典型 LaTeX 浮动体放置问题,使用本技能的浮动体参数调整策略修改完成后,必须返回以下信息:
{
"skill": "float-optimizer",
"status": "success | partial | failed",
"modified_files": ["main.tex"],
"changes": [
{
"defect_id": "B1",
"object": "Figure 3",
"action": "调整浮动体位置参数为 [ht]",
"before": "\\begin{figure}[t]",
"after": "\\begin{figure}[ht]"
},
{
"defect_id": "B2",
"object": "Table 1",
"action": "将 tabular 宽度设为 \\linewidth",
"before": "\\begin{tabular}{|l|c|c|}",
"after": "\\begin{tabularx}{\\linewidth}{|l|X|X|}"
}
],
"unresolved": []
}
[ht],其次调整尺寸,最后才考虑移动浮动体在源码中的位置。Acknowledgements、References、Bibliography 所在页;若发生,按失败处理,并优先在 endmatter 前插入 \FloatBarrier。问题特征:
data/crossrefs.json 读取 ref_line 和 figure_line:
line_distance < 50 且 section_distance = 0 → 源码组织良好,问题出在 LaTeX 浮动体放置算法line_distance > 100 或 section_distance ≥ 1 → 源码层面的引用与定义相距较远诊断流程(新增):
# 第一步:运行源码交叉引用分析
paperfit run scripts/extract_crossrefs.py main.tex --output data/crossrefs.json
# 第二步:解读输出
# {
# "distances": [
# {"label": "fig:result", "ref_line": 245, "figure_line": 260, "line_distance": 15, "section_distance": 0, "severity": "none"}
# ]
# }
# 若源码距离近但视觉距离远 → 浮动体参数调整
# 若源码距离远 → 移动源码位置
修复策略(按优先级):
调整位置参数
将浮动体环境的参数优先改为 [ht]。禁止将正文浮动体修成 [p] 或 [!p];只有模板机制明确限制的跨栏场景才保留页顶策略。
% 修改前
\begin{figure}[t]
% 修改后
\begin{figure}[ht]
参数含义:h = here(尽可能在此处),t = top(页顶)。p = float page(独立浮动页)对正文浮动体视为禁用策略。
使用 \FloatBarrier 强制放置
在引用点之后、期望图表出现的位置之前插入 \FloatBarrier(需 placeins 宏包),并在 Acknowledgements / References / \bibliography 之前再加一道 endmatter barrier,阻止正文浮动体漂入参考文献区域。
\usepackage{placeins}
...
As shown in Figure~\ref{fig:result}, ...
\FloatBarrier % 确保图不会漂到更后
移动浮动体源码位置
将整个 figure 或 table 环境在 .tex 源码中向上移动,使其更接近首次引用点。
注意:移动源码可能改变上下文,需确保不影响前后文语义。
拆分大型浮动体
若一个浮动体包含多个子图且过大,考虑拆分为两个独立的浮动体,或将其部分内容移至附录。
调整前后正文数量
在浮动体前后增删少量文本(由 semantic-polish-agent 协助),改变分页位置,使浮动体自然落在引用附近。
问题特征:
修复策略(按优先级):
图片宽度标准化
将所有图片的 \includegraphics 宽度设为 \linewidth(单栏)或 \textwidth(跨栏)。
% 修改前
\includegraphics[width=0.6\textwidth]{figure.pdf}
% 修改后
\includegraphics[width=\linewidth]{figure.pdf}
区分单栏与跨栏图表
\linewidth。\columnwidth 或 \linewidth;跨栏图表使用 figure* / table* 环境,宽度用 \textwidth。% 双栏中的跨栏图
\begin{figure*}
\includegraphics[width=\textwidth]{wide_figure.pdf}
\end{figure*}
表格宽度自适应
使用 tabularx 将表格宽度设为 \linewidth,并由 X 列自动分配多余空间。
\begin{tabularx}{\linewidth}{|l|X|X|}
旋转超宽表格
对于列数过多的宽表,使用 sidewaystable 环境旋转 90 度展示。
\usepackage{rotating}
...
\begin{sidewaystable}
\centering
\begin{tabular}{...}
...
\end{tabular}
\end{sidewaystable}
缩小超大图片
若原图本身尺寸过大,可使用 width=\linewidth 自动缩放;若仍需保持比例,可同时设置 height 和 keepaspectratio。
\includegraphics[width=\linewidth,height=0.3\textheight,keepaspectratio]{figure.pdf}
问题特征:
修复策略(按优先级):
分散浮动体位置参数
为不同浮动体分配非 p 的位置偏好,优先 [ht] / [t],避免它们挤在同一页。
\begin{figure}[t] ... \end{figure}
\begin{table}[b] ... \end{table}
\begin{figure}[ht] ... \end{figure}
在浮动体之间插入正文
若浮动体在源码中连续出现,可在其间补充或前移若干行正文(需确保语义连贯)。
\begin{figure} ... \end{figure}
% 在此处插入一段正文,哪怕只有 2-3 行
The above results demonstrate...
\begin{table} ... \end{table}
使用 \FloatBarrier 控制浮动页
在适当位置插入 \FloatBarrier,迫使之前的浮动体在下一页之前全部输出,避免后续浮动体继续堆积。
将部分图表移至附录
若正文中图表过多,可将非核心的图表或消融实验移至附录,并在正文中引用。
问题特征:
修复策略(按优先级):
长表格使用 longtable 环境
将普通 table + tabular 替换为 longtable,支持跨页并自动重复表头。
\usepackage{longtable}
...
\begin{longtable}{|l|c|c|}
\caption{Long table caption} \label{tab:long} \\
\hline
\textbf{Header1} & \textbf{Header2} & \textbf{Header3} \\
\hline
\endfirsthead
\hline
\textbf{Header1} & \textbf{Header2} & \textbf{Header3} \\
\hline
\endhead
% 表格内容
\end{longtable}
强制表格不跨页
若表格并非特别长,可用 \begin{table}[!h] 配合 \centering 强制放在一页内。
\begin{table}[!h]
\centering
\begin{tabular}{...}
...
\end{tabular}
\end{table}
拆分过大的图片组
若一个 figure 包含多个子图且总高度过大,拆分为两个独立的 figure 环境。
双栏布局下的浮动体优化更加复杂,需额外注意:
| 场景 | 策略 |
|---|---|
| 单栏图过窄 | 判断图片宽高比:若宽度 > 高度 * 1.5,考虑改为跨栏 figure* |
| 跨栏图位置不受控 | 跨栏图只能放在页顶或单独浮动页,使用 [t] 或 [p] |
| 跨栏图导致正文留白 | 若跨栏图后下一页大片空白,考虑缩小图尺寸或在其后补充内容 |
| 双栏末页浮动体堆积 | 使用 \balance 或 \flushend 平衡末页两栏高度(见 space-util-fixer) |
每完成一项修复后:
[H]:float 宏包提供的 [H] 参数强制图表“在此处”,会破坏 LaTeX 的浮动机制,容易导致大面积留白。仅作为最后手段使用。figure* 总是出现在下一页顶部,这是 LaTeX 的固有行为,不可改变。若引用与图表跨页不可避免,接受并记录。space-util-fixer 协同:浮动体调整可能影响页数预算和末页留白,需联动 space-util-fixer 综合优化。Float Optimizer Skill 就绪。 等待 code-surgeon-agent 调用,执行浮动体优化任务。