/overflow-repair

Overflow Repair Skill

概述

本技能专门处理 **Category D：溢出与对齐缺陷**，包括：

• **D1**：Overfull hbox（段落文本、表格单元格、公式溢出栏宽）
• **D2**：长公式未合理断行
• **D3**：URL/长标识符溢出

该技能由 `code-surgeon-agent` 调用，执行对 `.tex` 源码的精确修改，以消除或缓解溢出问题。所有修复遵循 **最小修改原则**，不改变学术内容。

---

适用场景

当 `layout-detective-agent` 或 `rule-engine-agent` 报告中出现以下缺陷 ID 时，路由至本技能：

| 缺陷 ID | 描述 | 优先级 | |---------|------|--------| | D1 | Overfull hbox（段落/表格/公式） | High | | D2 | 长公式未断行 | High | | D3 | URL/长标识符溢出 | Medium |

---

输入规范

| 输入项 | 来源 | 说明 | |--------|------|------| | 主 `.tex` 文件路径 | 项目上下文 | 需修改的源文件 | | 规则引擎报告 | `rule-engine-agent` 输出 | 包含溢出位置（行号）、溢出量、对象 | | 排版侦探报告 | `layout-detective-agent` 输出 | 包含视觉确认的溢出页面和对象 | | 当前编译日志 | `.log` 文件 | 用于验证修复后溢出是否消除 |

---

输出规范

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

{
  "skill": "overflow-repair",
  "status": "success | partial | failed",
  "modified_files": ["main.tex", "tables/table1.tex"],
  "changes": [
    {
      "defect_id": "D1",
      "object": "Table 2",
      "action": "替换 tabular 为 tabularx，设置列宽比例",
      "before": "\\begin{tabular}{|l|c|c|}",
      "after": "\\begin{tabularx}{\\linewidth}{|l|X|X|}"
    }
  ],
  "unresolved": []
}

---

修复策略

策略选择流程

1. 根据日志和视觉报告定位溢出位置与类型（段落/表格/公式/URL）。 2. 按照下文各类型的修复策略依次尝试，从最不侵入的方案开始。 3. 每次修改后，通知 `orchestrator-agent` 触发重新编译以验证效果。 4. 若当前策略无效，回退并尝试下一策略。

---

D1：段落文本溢出

**问题特征**：

• 日志：`Overfull \hbox (Xpt too wide) in paragraph at lines A--B`
• 视觉：某行文本伸出右边界

**修复策略（按优先级）**：

1. **引入断词点** 在溢出单词的合适位置添加 `\-` 连字符，使 LaTeX 能在该处断行。

   % 修改前
   This is a verylongwordthatdoesnotbreak.
   % 修改后
   This is a very\-long\-word\-that\-does\-not\-break.

2. **调整段落级容差** 在段落前临时增加 `\emergencystretch` 或调整 `\tolerance`。

   {\emergencystretch=1em  % 允许额外拉伸 1em
    This is the problematic paragraph content...
   }

*注意：修改后需恢复默认值，避免影响全局。*

3. **局部微调措辞**（需 `semantic-polish-agent` 介入） 若排版手段无法解决，可替换为稍短的近义词或调整语序。

   % 修改前
   the implementation of the proposed methodology
   % 修改后
   the implementation of our method

---

D1：表格单元格溢出

**问题特征**：

• 日志：`Overfull \hbox (Xpt too wide) in alignment at lines A--B`
• 视觉：表格某单元格内容超出列宽，与相邻列重叠或伸出表格边界

**修复策略（按优先级）**：

1. **改用 `tabularx` 环境** 将 `tabular` 替换为 `tabularx`，并为文本列分配 `X` 列类型以允许自动换行。

   % 修改前
   \begin{tabular}{|l|c|c|}
   \hline
   Method & Description & Score \\
   \hline
   Ours & A very long description that causes overflow & 0.95 \\
   \hline
   \end{tabular}

   % 修改后
   \usepackage{tabularx}  % 确保导言区已引入
   ...
   \begin{tabularx}{\linewidth}{|l|X|X|}
   \hline
   Method & Description & Score \\
   \hline
   Ours & A very long description that causes overflow & 0.95 \\
   \hline
   \end{tabularx}

*规则*：多个文本列应共同使用 `X` 列，避免单列过宽。

2. **手动设置列宽** 使用 `p{宽度}` 列类型固定文本列宽度。

   \begin{tabular}{|l|p{4cm}|c|}

3. **精简表头或内容** 若表头过长导致溢出，可缩写表头或使用换行。

   % 修改前
   \textbf{Mean Average Precision at IoU 0.5}
   % 修改后
   \textbf{mAP@0.5}

4. **调整字号（谨慎使用）** 在表格环境内使用 `\small` 或 `\footnotesize`，但需确保与全篇表格风格一致。

   \begin{table}
   \small
   \begin{tabular}{...}
   ...
   \end{tabular}
   \end{table}

5. **旋转表格** 对于列数过多的宽表，使用 `\rotatebox` 或 `sidewaystable` 环境。

   \usepackage{rotating}
   ...
   \begin{sidewaystable}
   ...
   \end{sidewaystable}

---

D2：长公式未断行

**问题特征**：

• 视觉：公式长度接近或超过栏宽，未在运算符处断行
• 日志：可能伴随 `Overfull \hbox` 在公式环境

**修复策略（按优先级）**：

1. **替换为多行公式环境**

• 单行公式 → `multline`：首行左对齐，末行右对齐，中间行居中。
• 多行对齐公式 → `align` 或 `aligned`：在等号或运算符处对齐。

   % 修改前（equation 环境）
   \begin{equation}
   f(x) = a_1 x^1 + a_2 x^2 + a_3 x^3 + a_4 x^4 + a_5 x^5 + a_6 x^6
   \end{equation}

   % 修改后（multline 环境）
   \begin{multline}
   f(x) = a_1 x^1 + a_2 x^2 + a_3 x^3 \\
   + a_4 x^4 + a_5 x^5 + a_6 x^6
   \end{multline}

   % 或 align 环境（在等号处对齐）
   \begin{align}
   f(x) &= a_1 x^1 + a_2 x^2 + a_3 x^3 \nonumber \\
        &\quad + a_4 x^4 + a_5 x^5 + a_6 x^6
   \end{align}

2. **使用 `split` 环境嵌套在 `equation` 中** 保留单个公式编号，但内部换行。

   \begin{equation}
   \begin{split}
   f(x) &= a_1 x^1 + a_2 x^2 + a_3 x^3 \\
        &\quad + a_4 x^4 + a_5 x^5 + a_6 x^6
   \end{split}
   \end{equation}

3. **引入中间变量简化表达式** 若公式过长且无明显断点，可拆分为多个子公式。

   % 修改前
   P(y|x) = \frac{\exp(\sum_i w_i f_i(x,y))}{\sum_{y'}\exp(\sum_i w_i f_i(x,y'))}

   % 修改后
   Let $S(x,y) = \sum_i w_i f_i(x,y)$, then
   \begin{equation}
   P(y|x) = \frac{\exp(S(x,y))}{\sum_{y'}\exp(S(x,y'))}
   \end{equation}

---

D3：URL/长标识符溢出

**问题特征**：

• 视觉：参考文献中的 URL 或 DOI 伸出右边界
• 日志：`Overfull \hbox` 在参考文献区域

**修复策略（按优先级）**：

1. **使用 `\url` 命令** `\url` 命令（由 `hyperref` 或 `url` 宏包提供）能自动在合适位置断行。

   % 修改前
   https://github.com/very/long/url/that/overflows/the/margin
   % 修改后
   \url{https://github.com/very/long/url/that/overflows/the/margin}

2. **启用参考文献断行** 在导言区添加：

   \usepackage{url}
   \def\UrlBreaks{\do\/\do-}  % 允许在 / 和 - 处断行

或对于 `biblatex`：

   \usepackage[backend=biber, url=true]{biblatex}
   \setcounter{biburlnumpenalty}{100}
   \setcounter{biburlucpenalty}{100}
   \setcounter{biburllcpenalty}{100}

3. **手动添加断行点** 在 URL 中允许断行处插入 `\linebreak[0]` 或使用 `\path` 命令。

   \path{https://github.com/very/long/url/\linebreak[0]that/overflows}

---

修复验证

每执行一项修复后，必须：

1. 通知 `orchestrator-agent` 重新编译。 2. 检查编译日志中对应行的 `Overfull \hbox` 是否消除或溢出量显著减少。 3. 若问题持续存在，尝试下一优先级策略。 4. 若所有策略均无效，标记为 `partial` 或 `failed`，并在报告中说明原因（如“公式语义复杂，无法自动断行，建议人工调整”）。

---

注意事项

• **表格修复后需检查视觉一致性**：改用 `tabularx` 后，确保全篇表格风格仍统一（参见 `consistency-polisher` 技能）。
• **公式断行需保持数学语义正确**：不要在括号或函数名中间断行。
• **URL 修复需保留超链接功能**：使用 `\url` 时自动包含超链接（若加载 `hyperref`）。
• **避免全局字号修改**：表格内的字号调整应局部化，并在同一文档中保持一致。

---

与其它技能的交互

• 若表格溢出修复后仍需调整列宽均衡，可联动 `consistency-polisher` 技能。
• 若段落溢出需语义微调，转交 `semantic-polish-agent` 处理。
• 修复结果最终由 `quality-gatekeeper-agent` 验收。

---

**Overflow Repair Skill 就绪。** 等待 `code-surgeon-agent` 调用，执行溢出类修