/float-optimizer

name: float-optimizer
description: PaperFit advice for LaTeX figure/table placement, width, clustering and breakable-table flow, verified against current page images.

浮动体优化

供 Codex、Claude Code、Cursor 宿主直接参考，也可用于可选 typed runtime。无需注册专用 agent。PaperFit 给出诊断和候选；宿主结合当前源码、模板和 PDF 判断是否采纳：**请你看看这是否是对的**。不确定的锚点、几何或视觉反馈应保留不确定性，不盲改整个文档。

先找实际原因

将图表 label、首次引用、定义位置与当前物理页对齐。Figure 1 与 Table 1 不混用。需要源码导航时运行：

paperfit run scripts/extract_crossrefs.py <root.tex> --output .paperfit/reports/crossrefs.json

源码行距与页距只是线索：定义靠近引用仍可能被前面的浮动体队列阻塞；跨页引用也可能是正常模板行为。先检查对象大小、放置参数、前面的队列、显式分页/间距和模板原生机制。页数目标与可读性同时考虑，不把全篇页数修复留到所有局部动作之后。

LaTeX 的浮动体布局取决于输入、辅助文件、引擎和宏包状态。使用原编译链，让引用与辅助文件收敛；不因“浮动具有随机性”无条件重复两次编译。每个有意义的候选编译后看实际页图。

按原因选择策略

B1：浮动体远离引用或侵入后文

• 可以移动完整对象到适合的源码锚点，或调整该对象的放置参数；没有固定先后顺序。保留标签、引用含义和正文顺序。
• `[ht]`、`[tbp]`、`[!t]`、`[p]` 等取决于模板和对象。浮动页可以是合理方案，不能一概禁止；`h` 是偏好而不是强制，`!` 也不能让不适合页面的对象自动放下。
• 只有实际参考文献区域侵入或另一条确定边界问题才考虑 `\FloatBarrier` / 清空队列；检查空白、页数和上游浮动体。插在引用后、对象定义前的 barrier 不会约束尚未进入队列的对象。不要给每个图表机械加 barrier。
• 双栏 `figure*` / `table*` 常有页顶约束，但具体行为取决于类和宏包；并非永远只能到下一页顶部。先了解原模板，不为了靠近引用引入不兼容的浮动宏包。

B2：宽度或可读性不合适

• 以当前容器 `\linewidth` / `\columnwidth` / 跨栏 `\textwidth` 为准。过窄的几何候选不等于应该撑满栏宽；一律将所有图片放大可能制造高图、页数增长和标签问题。
• 图像缩放保留宽高比，并看最小图内标签；不得靠裁切、隐藏内容或不可读缩放满足页数。
• 表格优先考虑列宽、长表头换行、`tabularx` 或合理跨栏。保留每个有序数据格、单位、注释、caption、label。不机械删除所有 `resizebox`，也不把全表缩小当默认解法。
• 只有常规布局不足且模板允许时，考虑旋转或等价分面；查看阅读方向、邻页和总页数。跨栏更宽，也可能加剧浮动队列与留白。

B3：图表聚集或大片留白

聚集是否妨碍阅读取决于图表关联、可读性和引用顺序。三个小对象排在同页可以很好；一个大对象也可能形成糟糕页面。没有“每页最多两个图表”的通用约束。

检查强制 `[H]`、多余 barriers、过严浮动比例和大显式间距。可以分散放置偏好、改变完整对象的源码位置，或将关联对象组成布局，但应保留各自科学对象和标签。不要生成几行填充正文、删除句子或擅自把结果搬到附录。若需要改变文章结构或文本，必须来自用户的授权。

B4：跨页表格、裁切或过高对象

普通 `figure` / `table` 浮动体通常不可分页；看到被“切开”的图，先确认是裁切、出页、组合容器错误还是实际分页。不要把 `[!h]` 当作保证单页的办法。

对于真正可分页的长表，在适配模板的环境中重复表头并保留完整数据；标准 `longtable` 不能直接作为普通双栏长表的通用替代。对于过高图组，考虑横排、合理跨栏或保留完整内容的分面；重新检查子图标签、caption、顺序和引用。

验证与执行边界

把相关动作作为一个可解释的候选；不必每个参数单独占一轮。编译后查看改变对象、邻近浮动页、受影响末页和图表的正常阅读大小。大的全篇重排扩大检查范围；最终接受前查看每个物理页。保留更好的前序源码/PDF，发生编译失败或部分写入时先恢复/纠正。

检查内容保护报告，并独立复核不支持的结构；解析器未证明安全不等于图表真的丢失。确认损坏、隐藏内容和禁用操作仍需恢复。不能因工具不支持便放弃合理的宿主原生编辑；也不能将视觉建议直接当作权限或保护例外。

typed runtime 的 B1 只处理放置，B2 单独处理尺寸。无精确锚点或全篇 B1 候选需要宿主独立证据和相应复核；具体接口见 `docs/HOST_NATIVE_WORKFLOW.md`。源码写回需 `--apply` 或用户已有的宿主修复授权。可选 batch 的上限与用户目标是否完成分开报告。

简洁记录实际对象、改动、当前页图改善、页数影响和剩余问题即可。无需生成专用 JSON 汇报，除非调用接口或用户明确要求。