float-optimizer

Float Optimizer Skill

概述

本技能专门处理 Category B：浮动体缺陷，包括：

• B1：浮动体远离首次引用（Float-Reference Distance）
• B2：浮动体大小不适配栏宽（Float Width Mismatch）
• B3：连续多个浮动体堆叠无正文间隔（Float Clustering）
• B4：浮动体跨页分裂（Float Page Orphaning）

该技能由 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 浮动体放置问题，使用本技能的浮动体参数调整策略
• 若源码距离本身远 → 优先建议移动源码位置（策略 3），而非调整浮动体参数

---

输出规范

修改完成后，必须返回以下信息：

{
  "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": []
}

---

修复策略

通用原则

1. 浮动体是“浮动”的：LaTeX 的浮动体放置算法具有不确定性，同一份源码在不同编译中可能产生不同输出。因此，修复后必须多次编译以验证稳定性。
2. 最小侵入：优先调整位置参数 [ht]，其次调整尺寸，最后才考虑移动浮动体在源码中的位置。
3. Endmatter 硬约束：正文浮动体不得进入 Acknowledgements、References、Bibliography 所在页；若发生，按失败处理，并优先在 endmatter 前插入 \FloatBarrier。
4. 视觉验证必须：浮动体修复的效果必须在页图上肉眼确认，不能仅凭日志判断。