paperfit-cli 1.0.0

package/skills/overflow-repair/SKILL.md

@@ -0,0 +1,304 @@
+# 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` 文件 | 用于验证修复后溢出是否消除 |
+
+---
+
+## 输出规范
+
+修改完成后，必须返回以下信息：
+
+```json
+{
+  "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 能在该处断行。
+   ```latex
+   % 修改前
+   This is a verylongwordthatdoesnotbreak.
+   % 修改后
+   This is a very\-long\-word\-that\-does\-not\-break.
+   ```
+
+2. **调整段落级容差**  
+   在段落前临时增加 `\emergencystretch` 或调整 `\tolerance`。
+   ```latex
+   {\emergencystretch=1em  % 允许额外拉伸 1em
+    This is the problematic paragraph content...
+   }
+   ```
+   *注意：修改后需恢复默认值，避免影响全局。*
+
+3. **局部微调措辞**（需 `semantic-polish-agent` 介入）  
+   若排版手段无法解决，可替换为稍短的近义词或调整语序。
+   ```latex
+   % 修改前
+   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` 列类型以允许自动换行。
+   ```latex
+   % 修改前
+   \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{宽度}` 列类型固定文本列宽度。
+   ```latex
+   \begin{tabular}{|l|p{4cm}|c|}
+   ```
+
+3. **精简表头或内容**  
+   若表头过长导致溢出，可缩写表头或使用换行。
+   ```latex
+   % 修改前
+   \textbf{Mean Average Precision at IoU 0.5}
+   % 修改后
+   \textbf{mAP@0.5}
+   ```
+
+4. **调整字号（谨慎使用）**  
+   在表格环境内使用 `\small` 或 `\footnotesize`，但需确保与全篇表格风格一致。
+   ```latex
+   \begin{table}
+   \small
+   \begin{tabular}{...}
+   ...
+   \end{tabular}
+   \end{table}
+   ```
+
+5. **旋转表格**  
+   对于列数过多的宽表，使用 `\rotatebox` 或 `sidewaystable` 环境。
+   ```latex
+   \usepackage{rotating}
+   ...
+   \begin{sidewaystable}
+   ...
+   \end{sidewaystable}
+   ```
+
+---
+
+### D2：长公式未断行
+
+**问题特征**：
+- 视觉：公式长度接近或超过栏宽，未在运算符处断行
+- 日志：可能伴随 `Overfull \hbox` 在公式环境
+
+**修复策略（按优先级）**：
+
+1. **替换为多行公式环境**  
+   - 单行公式 → `multline`：首行左对齐，末行右对齐，中间行居中。
+   - 多行对齐公式 → `align` 或 `aligned`：在等号或运算符处对齐。
+   ```latex
+   % 修改前（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` 中**  
+   保留单个公式编号，但内部换行。
+   ```latex
+   \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. **引入中间变量简化表达式**  
+   若公式过长且无明显断点，可拆分为多个子公式。
+   ```latex
+   % 修改前
+   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` 宏包提供）能自动在合适位置断行。
+   ```latex
+   % 修改前
+   https://github.com/very/long/url/that/overflows/the/margin
+   % 修改后
+   \url{https://github.com/very/long/url/that/overflows/the/margin}
+   ```
+
+2. **启用参考文献断行**  
+   在导言区添加：
+   ```latex
+   \usepackage{url}
+   \def\UrlBreaks{\do\/\do-}  % 允许在 / 和 - 处断行
+   ```
+   或对于 `biblatex`：
+   ```latex
+   \usepackage[backend=biber, url=true]{biblatex}
+   \setcounter{biburlnumpenalty}{100}
+   \setcounter{biburlucpenalty}{100}
+   \setcounter{biburllcpenalty}{100}
+   ```
+
+3. **手动添加断行点**  
+   在 URL 中允许断行处插入 `\linebreak[0]` 或使用 `\path` 命令。
+   ```latex
+   \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` 调用，执行溢出类修复任务。

package/skills/space-util-fixer/SKILL.md

@@ -0,0 +1,307 @@
+# Space Utilization Fixer Skill
+
+## 概述
+
+本技能专门处理 **Category A：空间利用缺陷**，包括：
+
+- **A1**：孤行/寡行（Widow/Orphan Lines）
+- **A2**：末页大面积留白（Excessive Trailing Whitespace）
+- **A3**：页数预算违反（Page Budget Violation）
+- **A4**：双栏末页左右栏高度不齐（Unbalanced Column Heights）
+
+该技能由 `code-surgeon-agent` 或 `semantic-polish-agent` 调用，通过对段落级排版控制、浮动体调度和最小语义改写的组合运用，优化页面空间分配，使文档达到专业级的视觉均衡。
+
+空间利用问题的修复常常需要多轮迭代，因为局部调整会影响全局分页。因此，每次修改后必须重新编译并审查页图。
+
+---
+
+## 适用场景
+
+| 缺陷 ID | 描述 | 优先级 | 是否允许语义修改 |
+|---------|------|--------|-----------------|
+| A1 | 孤行/寡行 | High | 是（最后手段） |
+| A2 | 末页大面积留白 | High | 是（最后手段） |
+| A3 | 页数预算违反 | Critical | 是（最后手段） |
+| A4 | 双栏末页左右栏高度不齐 | Medium | 否 |
+
+---
+
+## 输入规范
+
+| 输入项 | 来源 | 说明 |
+|--------|------|------|
+| 主 `.tex` 文件路径 | 项目上下文 | 需修改的源文件 |
+| 排版侦探报告 | `layout-detective-agent` 输出 | 包含 A 类缺陷的页码和描述 |
+| 目标页数（若适用） | 用户约束 | A3 修复必须提供 |
+| 模板类型 | `templates.yaml` 或上下文 | 单栏/双栏 |
+
+---
+
+## 输出规范
+
+```json
+{
+  "skill": "space-util-fixer",
+  "status": "success | partial | failed",
+  "modified_files": ["main.tex"],
+  "changes": [
+    {
+      "defect_id": "A1",
+      "object": "第4页顶部孤行",
+      "action": "在段落前添加 \\looseness=-1",
+      "before_snippet": "The proposed method achieves...",
+      "after_snippet": "{\\looseness=-1 The proposed method achieves...}"
+    }
+  ],
+  "unresolved": []
+}
+```
+
+---
+
+## 修复策略
+
+### 通用原则
+
+1. **先排版，后语义**：优先使用 LaTeX 原生的排版控制命令，仅在无效时才考虑语义级改写。
+2. **局部修改，全局验证**：改动一段可能影响后续多页分页，必须完整编译并检查全文档。
+3. **避免硬性分页**：禁止滥用 `\newpage` 或 `\clearpage` 来“凑页数”，这会破坏文档结构的自然性。
+
+---
+
+### A1：孤行/寡行修复
+
+**问题特征**：
+- 段落最后一行单独出现在下一页顶部（孤行）。
+- 段落第一行单独留在上一页底部（寡行）。
+- 段落末尾仅含 1-3 个单词的短行（段尾小尾巴）。
+
+**修复策略（严格按优先级顺序尝试）**：
+
+#### 策略 1：段落级收紧 (`\looseness=-1`)
+
+通过在段落前设置 `\looseness=-1`，指示 TeX 引擎尝试将段落收缩一行，从而消除孤行或小尾巴。
+
+```latex
+% 修改前
+The proposed method achieves state-of-the-art performance on several
+benchmarks, demonstrating the effectiveness of our approach.
+
+% 修改后
+{\looseness=-1 The proposed method achieves state-of-the-art performance on several
+benchmarks, demonstrating the effectiveness of our approach.}
+```
+
+*注意*：
+- 必须将整个段落用花括号 `{ }` 括起，以限制 `\looseness` 的作用范围。
+- 若段落本身很短，收缩可能导致过紧的行距，需在页图上确认可接受。
+
+#### 策略 2：段落级扩张 (`\looseness=1`)
+
+若段落太紧，可尝试扩张一行，使段末行变长。
+
+```latex
+{\looseness=1 This paragraph will be typeset with one more line...}
+```
+
+#### 策略 3：调整段落间胶水 (`\emergencystretch`)
+
+为特定段落增加紧急拉伸量，允许行间略微拉伸以调整断行。
+
+```latex
+{\emergencystretch=1em This paragraph content...}
+```
+
+#### 策略 4：微调上下文句长分布（需 `semantic-polish-agent`）
+
+若排版控制无效，则进行最小语义改写：
+- 在段落中增删 3-8 个单词（如将 `in order to` 改为 `to`，或将 `demonstrate` 改为 `show`）。
+- 调整从句结构，但不改变学术原意。
+
+```latex
+% 修改前
+The proposed method achieves state-of-the-art performance on several
+benchmarks, demonstrating the effectiveness of our approach.
+
+% 修改后
+The proposed method achieves state-of-the-art results on several
+benchmarks, showing the effectiveness of our approach.
+```
+
+*语义改写必须由 `semantic-polish-agent` 执行，本技能仅提出请求。*
+
+#### 策略 5：全局调整 widow/orphan 惩罚
+
+在导言区增加以下设置（通常模板已包含，可作为兜底）：
+
+```latex
+\widowpenalty=10000
+\clubpenalty=10000
+\displaywidowpenalty=10000
+```
+
+*注意*：此设置影响全局，需谨慎。若模板已设置，则无需重复。
+
+---
+
+### A2：末页大面积留白修复
+
+**问题特征**：
+- 最后一页（参考文献前或后）空白区域超过页面高度的 20%。
+
+**修复策略（按优先级）**：
+
+#### 策略 1：前移浮动体
+
+检查倒数第二、第三页是否有可前移的图表。调整其位置参数 `[htbp]`，使其占据末页空白区域。
+
+```latex
+% 将原本放在倒数第二页的图强制前移
+\begin{figure}[t]  →  \begin{figure}[ht]
+```
+
+#### 策略 2：调整局部垂直间距
+
+在不影响整体美观的前提下，微调末页前的某些垂直间距（如 `\vspace`、章节间距）。
+
+```latex
+% 轻微缩小最后一节前的间距
+\vspace{-0.5em}
+\section{Conclusion}
+```
+
+*注意*：不要制造新的视觉不协调。
+
+#### 策略 3：适当扩写结论或讨论部分（需语义润色）
+
+在结论、讨论或分析段落中增加有实质内容的 2-4 行文本（约 30-60 词），以自然填充空白。
+
+*此操作必须由 `semantic-polish-agent` 执行。*
+
+#### 策略 4：增加附录或致谢（最后手段）
+
+若用户同意，可将部分非核心内容（如额外消融实验）从正文移至附录，或在末页后增加致谢部分。
+
+---
+
+### A3：页数预算修复
+
+**问题特征**：
+- 实际总页数与目标页数不符（如会议要求 9 页，实际 8 页或 10 页）。
+
+**修复策略**：
+
+本缺陷修复需要系统性操作，通常结合多种手段。
+
+#### 情况 1：超页（实际页数 > 目标页数）
+
+**优先级从高到低**：
+
+1. **压缩浮动体**  
+   - 缩小超大图片（`width=0.95\linewidth` 代替 `\linewidth`）。
+   - 将跨页长表格改为 `longtable`（可跨页，避免独占一页）。
+   - 调整浮动体位置，使其更紧凑地填充页面。
+
+2. **缩减垂直间距**  
+   - 使用 `\vspace{-0.2cm}` 微调节标题、图表与正文的间距。
+   - 检查是否有冗余的 `\newline` 或空行。
+
+3. **精炼文字（语义级）**  
+   在非核心段落（Related Work、Introduction 末尾）进行精简：
+   - 删除冗余修饰词。
+   - 合并短句。
+   - 将被动语态改为主动语态（通常更短）。
+
+4. **压缩参考文献**  
+   若参考文献过多，使用 `\bibliographystyle{abbrv}` 或类似缩写样式，或使用 `biblatex` 的压缩选项。
+
+5. **缩小页边距（谨慎）**  
+   若模板允许，使用 `\usepackage[margin=...]{geometry}` 微调边距。*必须在模板允许范围内。*
+
+#### 情况 2：缺页（实际页数 < 目标页数）
+
+**优先级从高到低**：
+
+1. **检查浮动体堆积**  
+   是否因 `\FloatBarrier` 或 `[H]` 导致页面空白？若是，先按 B 类缺陷修复。
+
+2. **适当扩写结论、讨论或分析段落**  
+   增加 5-10 行有实质内容的分析，例如：
+   - 深入解释某个实验结果的含义。
+   - 补充一个简短的局限性讨论。
+   - 强化与相关工作的对比。
+
+3. **增加附录或补充材料**  
+   若会议允许附录且不计入页数限制，可将部分内容移至附录，使正文恰好满页。
+
+4. **微调图表尺寸**  
+   将部分图片略微放大（`width=1.0\linewidth` 代替 `0.95\linewidth`），使其占据更多空间但不溢出。
+
+5. **增加分页点**  
+   在合适位置（如章节末尾）添加 `\newpage` 迫使内容分页，但必须确保不产生孤页。
+
+---
+
+### A4：双栏末页左右栏高度不齐
+
+**问题特征**：
+- 双栏模板最后一页，左栏和右栏底部高度差超过 2 行。
+
+**修复策略**：
+
+#### 策略 1：使用 `\balance` 或 `flushend` 宏包
+
+在导言区加载 `flushend` 宏包，自动平衡末页两栏高度。
+
+```latex
+\usepackage{flushend}
+```
+
+*注意*：`flushend` 与某些宏包（如 `multicol`）可能冲突，需在特定模板下测试。
+
+#### 策略 2：手动平衡
+
+若自动平衡无效，在最后一节结束前插入 `\balance` 命令（需 `balance` 宏包）。
+
+```latex
+\usepackage{balance}
+...
+\section{Conclusion}
+...
+\balance
+\end{document}
+```
+
+#### 策略 3：微调最后一段的断行
+
+对末页最后一段使用 `\looseness=-1` 或 `\looseness=1`，改变其行数，从而影响两栏高度。
+
+#### 策略 4：调整浮动体位置
+
+若末页有浮动体，尝试将其移至前一页或强制放在当前页底部，以改变栏内内容分布。
+
+---
+
+## 修复验证
+
+每完成一项修复后：
+
+1. **重新编译至少两次**（确保交叉引用稳定）。
+2. **渲染页图**，对照缺陷逐项检查：
+   - A1：孤行/寡行是否消失？
+   - A2：末页空白比例是否降至 20% 以下？
+   - A3：总页数是否达到目标？
+   - A4：双栏末页高度差是否 ≤ 2 行？
+3. 若未通过，回滚并尝试下一策略。
+
+---
+
+## 与其它技能的协作
+
+- **浮动体修复 (float-optimizer)**：A2 和 A3 常需配合浮动体调整。
+- **语义润色 (writing-polish)**：当排版手段用尽时，请求语义改写。
+- **一致性检查 (consistency-polisher)**：修改字号、间距后需确保全局一致。
+
+---
+
+**Space Utilization Fixer Skill 就绪。** 等待调用，优化页面空间分配。