/template-migrator

Template Migrator Skill

概述

本技能专门处理 **Category E：跨模板迁移缺陷**，包括：

• **E1**：单栏↔双栏图表尺寸失配
• **E2**：页数预算不匹配（如 9 页→14 页的内容重分布）
• **E3**：模板特定宏兼容性

该技能由 `code-surgeon-agent` 在 `/migrate-template` 命令触发时调用，负责将一篇论文从原模板平滑迁移至目标模板，并自动适配图表尺寸、页数预算和宏包兼容性。这是 PaperFit 最具差异化价值的能力，直接解决了科研工作者切换会议投稿时的真实痛点。

适用场景

| 缺陷 ID | 描述 | 优先级 | 是否允许语义修改 | |---------|------|--------|-----------------| | E1 | 单栏↔双栏图表尺寸失配 | Critical | 否 | | E2 | 页数预算不匹配 | Critical | 是（最后手段） | | E3 | 模板特定宏兼容性 | Critical | 否 |

输入规范

| 输入项 | 来源 | 说明 | |--------|------|------| | 主 `.tex` 文件路径 | 项目上下文 | 需修改的源文件 | | 目标模板名称 | 用户命令参数 | 如 `ECCV2024`、`ICLR2025` | | 模板配置 | `config/templates.yaml` | 包含目标模板的栏数、默认字号、页宽、预期页数等 | | 原模板信息 | 自动检测或用户指定 | 当前 `\documentclass` 及主要宏包 | | 排版侦探报告 | `layout-detective-agent` | 迁移后首次编译的 E 类缺陷列表 |

输出规范

{
  "skill": "template-migrator",
  "status": "success | partial | failed",
  "modified_files": ["main.tex", "figures/fig1.tex"],
  "changes": [
    {
      "defect_id": "E1",
      "object": "Figure 1",
      "action": "单栏图改为跨栏图",
      "before": "\\begin{figure}\n\\includegraphics[width=\\linewidth]{fig1.pdf}\n\\end{figure}",
      "after": "\\begin{figure*}\n\\includegraphics[width=\\textwidth]{fig1.pdf}\n\\end{figure*}"
    }
  ],
  "macro_fixes": [
    {
      "issue": "\\theoremstyle undefined in ECCV",
      "fix": "改用 \\newtheorem 直接定义"
    }
  ],
  "unresolved": [],
  "page_budget_status": {
    "current_pages": 9,
    "target_pages": 14,
    "gap": 5,
    "action_taken": "触发 adjust-length 子流程"
  }
}

迁移流程

第一步：加载模板配置

1. 从 `config/templates.yaml` 读取目标模板的完整配置。 2. 配置项包括：

• `documentclass`：如 `\documentclass[10pt,twocolumn]{article}` 或 `\documentclass{iclr2025}`
• `column_type`：`single` 或 `double`
• `default_figure_width`：`\linewidth` 或 `\textwidth`
• `expected_pages`：该会议/期刊的典型页数（如 ICLR 9 页，ECCV 14 页）
• `forbidden_packages`：与新模板冲突的宏包列表
• `required_packages`：新模板必须加载的宏包

示例配置（`config/templates.yaml` 片段）：

ECCV2024:
  documentclass: "\documentclass[10pt,twocolumn]{article}"
  column_type: double
  default_figure_width: "\linewidth"
  expected_pages: 14
  forbidden_packages: ["amsthm", "algorithm2e"]
  required_packages: ["graphicx", "amsmath", "amssymb"]
  float_behavior: "figures may use figure* for wide content"

第二步：分析原模板特征

1. 读取当前主 `.tex` 文件的 `\documentclass` 声明。 2. 识别当前栏数（单栏/双栏）。 3. 列出当前加载的宏包列表（`\usepackage{...}`）。 4. 若用户未明确指定原模板，尝试根据 `\documentclass` 自动推断。

第三步：执行模板替换

**写入约束（强制）**：

1. 所有模板迁移修改必须先在内存中完成整组 patch 组装，不得分步直接覆写源文件。 2. 真正写盘时必须通过 `scripts/transactional_patch.py` 的 `atomic_write_text(...)` 一次性提交。 3. 写入前必须保留迁移前备份；若后续编译验证失败，必须回滚到该备份。 4. 不允许一边迁移 `documentclass` / 宏包，一边把半成品状态暴露给后续 agent 或编译轮次。

3.1 替换 `\documentclass`

将原 `\documentclass` 替换为目标模板的声明。

% 修改前（ICLR 2025 单栏）
\documentclass{iclr2025}

% 修改后（ECCV 2024 双栏）
\documentclass[10pt,twocolumn]{article}

**注意**：若目标模板有多个可选参数（如 `review`、`final`），询问用户偏好或使用默认值。

3.2 处理宏包冲突

1. 对比原宏包列表与目标模板的 `forbidden_packages`。 2. 若存在冲突，执行以下操作之一：

• **移除**：直接注释或删除该 `\usepackage` 行。
• **替换**：提供替代方案（如 `algorithm2e` → `algorithmic`）。
• **条件编译**：使用 `\ifdefined` 等实现跨模板兼容。

% 修改前（含 amsthm，与新模板冲突）
\usepackage{amsthm}
\newtheorem{theorem}{Theorem}

% 修改后（改用 LaTeX 原生定义）
% \usepackage{amsthm}  % removed for template compatibility
\newtheorem{theorem}{Theorem}

3.3 添加必需宏包

若目标模板要求特定宏包（如 `graphicx`），确保导言区已加载。若缺失，添加之。

% 确保必需宏包存在
\usepackage{graphicx}
\usepackage{amsmath}

第四步：图表尺寸适配（E1 修复）

这是跨模板迁移中最关键、最易出错的环节。

4.1 判断单栏/双栏切换方向

| 原模板 | 目标模板 | 处理策略 | |--------|----------|----------| | 单栏 | 双栏 | 所有图表默认改为单栏宽（`\columnwidth`），宽图改为跨栏（`figure*`） | | 双栏 | 单栏 | 所有跨栏图（`figure*`）改为普通图（`figure`），宽度改为 `\linewidth` | | 双栏 | 双栏 | 保持原策略，仅检查宽度是否适配新模板的栏宽 | | 单栏 | 单栏 | 基本不变，仅检查页宽是否变化 |

4.2 智能判断哪些图应跨栏（单栏→双栏时）

对于原单栏中的全宽图，在双栏中若仍用单栏会显得过小。需根据图片**宽高比**智能决策：

• 若图片宽度 > 高度 × 1.5（宽高比 > 1.5），建议改为跨栏 `figure*`。
• 若图片宽度 ≤ 高度 × 1.5，保留单栏 `figure`，但宽度设为 `\columnwidth`。

% 原单栏全宽图（宽度 = \linewidth）
\begin{figure}
\includegraphics[width=\linewidth]{wide_arch.pdf}
\end{figure}

% 迁移后（宽高比大，改为跨栏）
\begin{figure*}
\includegraphics[width=\textwidth]{wide_arch.pdf}
\end{figure*}

4.3 处理表格宽度

• 单栏表格在双栏中：宽度改为 `\columnwidth`。
• 若原表格为 `tabularx{\linewidth}`，改为 `tabularx{\columnwidth}`。
• 若表格列数过多，考虑改为跨栏 `table*` 并使用 `\textwidth`。

% 修改前（单栏宽表）
\begin{table}
\begin{tabularx}{\linewidth}{|l|X|X|}
...
\end{tabularx}
\end{table}

% 修改后（双栏单栏宽表）
\begin{table}
\begin{tabularx}{\columnwidth}{|l|X|X|}
...
\end{tabularx}
\end{table}

4.4 特殊对象处理

• **长公式**：双栏中公式宽度受限，可能需将 `equation` 改为 `multline` 或 `align` 并手动断行。
• **算法伪代码**：双栏中宽度减半，可能需要调整缩进或改为跨栏 `figure*`。

第五步：编译并检测遗留问题

1. 完成上述修改后，执行首次编译。 2. 若编译失败，解析日志中的 `Undefined control sequence` 等错误（E3），返回第三步修正宏包冲突。 3. 若编译成功，渲染页图，调用 `layout-detective-agent` 检测 E1/E2 缺陷。

第六步：页数预算调整（E2 修复）

1. 获取当前 PDF 总页数。 2. 与目标模板的 `expected_pages` 对比，计算偏差。 3. 若偏差在 ±1 页以内，通常可接受；若偏差 ≥ 2 页，执行以下操作：

• **若超页**：按 A3 修复策略压缩（见 `space-util-fixer`）。
• **若缺页**：若用户未指定 `--keep-content`，触发 `adjust-length` 子流程进行语义扩写。

4. 页数调整通常需要多轮迭代，应在浮动体和图表稳定后进行。

第七步：生成迁移报告

输出一份 Markdown 迁移报告，包含：

• 目标模板信息
• 已修改的文件列表
• 图表尺寸变更清单（哪些图改为跨栏、哪些保留单栏）
• 宏包冲突及解决方案
• 页数调整结果（初始页数 → 最终页数）
• 人工检查建议（如“请确认 Figure 3 改为跨栏后视觉效果”）

双栏迁移的特别注意事项

双栏模板的排版行为与单栏有本质不同：

1. **跨栏图表只能放在页顶**：`figure*` 和 `table*` 仅支持 `[t]` 或 `[p]` 参数，无法使用 `[h]` 或 `[b]`。这意味着跨栏图必然出现在下一页顶部，可能拉大引用距离（B1 缺陷）。这是 LaTeX 的限制，无法完全消除，需在报告中说明。 2. **浮动体调度更复杂**：双栏中浮动体更容易堆积（B3），可能需要手动插入 `\FloatBarrier` 或调整源码位置。 3. **公式编号**：双栏中公式编号通常在右侧，若原单栏模板编号在左侧，需检查是否冲突。

与其它技能的协作

• **浮动体优化 (float-optimizer)**：迁移后必然产生新的浮动体位置问题，需联动修复。
• **空间利用修复 (space-util-fixer)**：页数调整依赖此技能。
• **语义润色 (semantic-polish-agent)**：扩写/缩写时调用。

验证标准

迁移成功的判定标准：

• [ ] 编译成功，无阻塞性错误
• [ ] 所有图表在新模板下尺寸适配（无溢出、无过窄）
• [ ] 页数符合目标模板预期（或用户接受偏差）
• [ ] 无未解决的宏包冲突
• [ ] 视觉风格与目标模板一致

---

**Template Migrator Skill 就绪。**