Template Migrator Skill

概述

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

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

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

能力边界：当前 typed runtime 没有自动模板迁移 executor，可选自动批处理的 --apply 必须报告不支持，不能偷偷回退到旧脚本。用户已授权迁移时，宿主可以用原生编辑工具完成并验证迁移，无需等待自动 executor。先核对建议：请你看看这是否是对的；保留原模板/源码及可回退候选，确认目标模板、当前编译页和内容。

适用场景

输入规范

输出规范

{
  "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": "核对用户页数政策并比较保持内容的布局候选"
  }
}

迁移流程

第一步：加载模板配置

1. 从 config/templates.yaml 读取目标模板的完整配置。
2. 配置项包括：
   • documentclass：如 \documentclass[10pt,twocolumn]{article} 或 \documentclass{iclr2025}
   • column_type：single 或 double
   • default_figure_width：\linewidth 或 \textwidth
   • expected_pages：配置中的页数参考值；不能代替用户指定的 exact/at_most、正文/参考文献/附录范围或当前投稿规则
   • 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. 写入前保留迁移前源码和资源，避免覆盖作者尚未保存的改动。
2. 宿主可用正常 patch/编辑工具形成连贯候选，合理组合 class、宏包和对象适配；无需强制调用指定写盘函数。
3. 编译失败时先检查并修复根因，或恢复最近可用候选；保留失败记录和有用的独立改动。
4. 中间编译可用于定位兼容问题，半完成状态不得当作最终迁移成功。

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 判断单栏/双栏切换方向

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. 按用户授权的目标、exact/at_most 政策和计页范围计算偏差；配置中的 expected_pages 仅为参考。
3. exact 差一页仍未完成；at_most 只判定是否超上限，不能把不足页数当作必须扩写的缺陷。未知范围不得称为已满足。
4. 从迁移开始同时考虑页数和阅读质量。按 space-util-fixer 比较原生布局、人工空白、对象容器和自然流动；增页修改应同步考虑补偿候选。
5. 不默认扩写、删句或填空白。正文编辑只在已有单独授权内进行，并独立核对学术原意；没有 --keep-content 不是改内容的授权。

第七步：生成迁移报告

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

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

双栏迁移的特别注意事项

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

1. 跨栏位置取决于活动模板和输出例程：先检查模板支持的放置方式，并对照当前及邻页编译结果。不要一概断言只能页顶、必然下一页或永远不支持页底；不为某个通用规则盲目添加宏包。
2. 浮动体调度更复杂：双栏中浮动体更容易堆积（B3），可能需要手动插入 \FloatBarrier 或调整源码位置。
3. 公式编号：双栏中公式编号通常在右侧，若原单栏模板编号在左侧，需检查是否冲突。

与其它技能的协作

• 浮动体优化 (float-optimizer)：迁移后检查是否存在新的浮动体问题，需要时配合修复。
• 空间利用修复 (space-util-fixer)：页数调整依赖此技能。
• 语义润色 (semantic-polish-agent)：扩写/缩写时调用。

验证标准

迁移成功的判定标准：

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

Template Migrator Skill 就绪。