paperfit-cli 1.0.0

package/skills/template-migrator/SKILL.md

@@ -0,0 +1,251 @@
+# 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 类缺陷列表 |
+
+## 输出规范
+
+```json
+{
+  "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` 片段）：
+
+```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` 自动推断。
+
+### 第三步：执行模板替换
+
+#### 3.1 替换 `\documentclass`
+
+将原 `\documentclass` 替换为目标模板的声明。
+
+```latex
+% 修改前（ICLR 2025 单栏）
+\documentclass{iclr2025}
+
+% 修改后（ECCV 2024 双栏）
+\documentclass[10pt,twocolumn]{article}
+```
+
+**注意**：若目标模板有多个可选参数（如 `review`、`final`），询问用户偏好或使用默认值。
+
+#### 3.2 处理宏包冲突
+
+1. 对比原宏包列表与目标模板的 `forbidden_packages`。
+2. 若存在冲突，执行以下操作之一：
+   - **移除**：直接注释或删除该 `\usepackage` 行。
+   - **替换**：提供替代方案（如 `algorithm2e` → `algorithmic`）。
+   - **条件编译**：使用 `\ifdefined` 等实现跨模板兼容。
+
+```latex
+% 修改前（含 amsthm，与新模板冲突）
+\usepackage{amsthm}
+\newtheorem{theorem}{Theorem}
+
+% 修改后（改用 LaTeX 原生定义）
+% \usepackage{amsthm}  % removed for template compatibility
+\newtheorem{theorem}{Theorem}
+```
+
+#### 3.3 添加必需宏包
+
+若目标模板要求特定宏包（如 `graphicx`），确保导言区已加载。若缺失，添加之。
+
+```latex
+% 确保必需宏包存在
+\usepackage{graphicx}
+\usepackage{amsmath}
+```
+
+### 第四步：图表尺寸适配（E1 修复）
+
+这是跨模板迁移中最关键、最易出错的环节。
+
+#### 4.1 判断单栏/双栏切换方向
+
+| 原模板 | 目标模板 | 处理策略 |
+|--------|----------|----------|
+| 单栏 | 双栏 | 所有图表默认改为单栏宽（`\columnwidth`），宽图改为跨栏（`figure*`） |
+| 双栏 | 单栏 | 所有跨栏图（`figure*`）改为普通图（`figure`），宽度改为 `\linewidth` |
+| 双栏 | 双栏 | 保持原策略，仅检查宽度是否适配新模板的栏宽 |
+| 单栏 | 单栏 | 基本不变，仅检查页宽是否变化 |
+
+#### 4.2 智能判断哪些图应跨栏（单栏→双栏时）
+
+对于原单栏中的全宽图，在双栏中若仍用单栏会显得过小。需根据图片**宽高比**智能决策：
+
+- 若图片宽度 > 高度 × 1.5（宽高比 > 1.5），建议改为跨栏 `figure*`。
+- 若图片宽度 ≤ 高度 × 1.5，保留单栏 `figure`，但宽度设为 `\columnwidth`。
+
+```latex
+% 原单栏全宽图（宽度 = \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`。
+
+```latex
+% 修改前（单栏宽表）
+\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 就绪。**

package/skills/visual-inspector/SKILL.md

@@ -0,0 +1,217 @@
+# Visual Inspector Skill
+
+## 概述
+
+本技能是 PaperFit 视觉排版优化闭环中的关键环节，专门负责 **PDF 页图渲染与视觉验收指导**。它封装了将 PDF 转换为逐页高分辨率图片的标准化流程，并为 `layout-detective-agent` 和 `quality-gatekeeper-agent` 提供详细的逐页视觉检查清单。
+
+该技能由 `orchestrator-agent` 在每次编译后调用，确保多模态证据链中的“页图”环节可靠、一致且可复现。
+
+## 适用场景
+
+- 每次编译成功后，需生成页图供视觉 Agent 审查。
+- 手动触发视觉检查（如 `/check-visual` 命令）。
+- 修复前后对比验证。
+
+## 输入规范
+
+| 输入项 | 来源 | 必需 | 说明 |
+|--------|------|------|------|
+| PDF 文件路径 | 编译输出 | ✅ | 通常为 `main.pdf` |
+| 输出目录 | 配置或默认 | ✅ | 页图存放目录，默认为 `data/pages/` |
+| DPI 参数 | 配置或调用方指定 | ✅ | 渲染分辨率，默认 220 DPI |
+| 页码范围 | 调用方指定 | ⚠️ | 若为空，渲染全部页面 |
+| 局部裁剪参数 | 调用方指定 | ⚠️ | 如 `{page: 5, bbox: [x,y,w,h]}`，用于表格/公式局部复查 |
+
+## 输出规范
+
+本技能输出两份产物：
+
+1. **页图文件集**：PNG 或 JPG 格式的逐页图片，命名规则为 `page_001.png`、`page_002.png` 等。
+2. **渲染报告 JSON**：
+
+```json
+{
+  "skill": "visual-inspector",
+  "status": "success | partial | failed",
+  "pdf_path": "main.pdf",
+  "output_dir": "data/pages/",
+  "dpi": 220,
+  "pages_rendered": 9,
+  "page_files": [
+    {"page": 1, "file": "data/pages/page_001.png", "width": 1700, "height": 2200},
+    {"page": 2, "file": "data/pages/page_002.png", "width": 1700, "height": 2200}
+  ],
+  "cropped_regions": [
+    {
+      "page": 5,
+      "object": "Table 2",
+      "file": "data/pages/page_005_table2.png",
+      "bbox": [100, 450, 800, 300]
+    }
+  ],
+  "errors": []
+}
+```
+
+## 渲染流程
+
+### 第一步：环境检查
+
+1. 确认 PDF 文件存在且可读。
+2. 检查 Python 环境及所需依赖：
+   - `pdf2image` 库
+   - Poppler 工具（`pdftoppm` 或 `pdftocairo`）
+
+若 Poppler 未安装，根据操作系统提供安装指引：
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install poppler-utils
+
+# macOS
+brew install poppler
+
+# Windows
+# 下载 poppler 并添加到 PATH，或使用 conda install -c conda-forge poppler
+```
+
+3. 若依赖缺失，报告错误并终止，由上层 Agent 提示用户安装。
+
+### 第二步：执行渲染
+
+使用 `scripts/render_pages.py` 脚本（或直接调用 `pdf2image` 库）进行渲染。
+
+#### 基础渲染命令
+
+```python
+from pdf2image import convert_from_path
+
+pages = convert_from_path(
+    pdf_path,
+    dpi=220,
+    fmt='png',
+    thread_count=2,
+    grayscale=False,
+    size=None
+)
+
+for i, page in enumerate(pages, start=1):
+    page.save(f"{output_dir}/page_{i:03d}.png", "PNG")
+```
+
+#### 渲染参数建议
+
+| 场景 | DPI | 说明 |
+|------|-----|------|
+| 整页常规检查 | 180-220 | 平衡清晰度与文件大小 |
+| 表格/公式细节复查 | 260-320 | 需清晰辨认小字号或密集内容 |
+| 局部裁剪复查 | 320 | 聚焦特定区域，可接受较大文件 |
+
+### 第三步：局部区域裁剪（可选）
+
+当 `layout-detective-agent` 需要对特定表格、公式或段落进行高精度复查时，可请求渲染局部区域。
+
+1. 首先以较高 DPI（如 320）渲染整页。
+2. 根据调用方提供的边界框（bbox）裁剪图片。
+3. 保存裁剪后的图片，命名包含对象标识（如 `page_005_table2.png`）。
+
+裁剪示例：
+
+```python
+from PIL import Image
+
+full_page = Image.open(f"{output_dir}/page_005.png")
+cropped = full_page.crop((x1, y1, x2, y2))
+cropped.save(f"{output_dir}/page_005_table2.png")
+```
+
+### 第四步：生成渲染报告
+
+记录渲染结果，包括：
+- 成功渲染的页数
+- 每页图片的路径和尺寸
+- 裁剪区域信息（如有）
+- 错误或警告（如某些页渲染失败）
+
+## 视觉检查清单
+
+以下清单供 `layout-detective-agent` 在逐页审查时参考。本技能不执行检查，仅提供指导框架。
+
+### 通用检查项（每页必查）
+
+- [ ] 页面整体信息密度是否均衡？是否存在大面积无意义留白？
+- [ ] 页眉、页脚、页码是否完整且位置正确？
+- [ ] 是否有内容伸出页边距或栏宽？
+- [ ] 图表是否清晰可读，无模糊或锯齿？
+- [ ] 段落末尾是否有孤行或短尾巴？
+
+### 首页专项
+
+- [ ] 标题、作者、机构信息是否完整，格式是否正确？
+- [ ] 摘要段是否与模板风格一致？
+- [ ] 是否有不必要的空白或过大的标题间距？
+
+### 正文页专项
+
+- [ ] 章节标题是否突出且一致？
+- [ ] 图表与正文的衔接是否自然？图表是否在引用附近？
+- [ ] 跨页段落是否合理断开？
+- [ ] 双栏布局中左右栏高度是否平衡（尤其末页）？
+
+### 末页专项
+
+- [ ] 参考文献是否完整，无被浮动体切断？
+- [ ] 末页留白是否在可接受范围（<20%）？
+- [ ] 若为双栏，左右栏底部是否对齐？
+
+### 表格专项
+
+- [ ] 表格宽度是否匹配栏宽？有无超宽或过窄？
+- [ ] 列宽分配是否均衡？有无单列过宽挤压其他列？
+- [ ] 表格字号是否与全篇其他表格一致？
+- [ ] 表格线是否清晰？推荐使用 `booktabs` 风格。
+
+### 图片专项
+
+- [ ] 图片是否清晰，分辨率足够？
+- [ ] 图片宽度是否充分利用栏宽？
+- [ ] 图片标题是否在图片下方（表格标题在上方）？
+- [ ] 图片中的文字（坐标轴标签、图例）是否可读？
+
+### 公式专项
+
+- [ ] 公式是否超出栏宽？
+- [ ] 多行公式是否在合理位置断行并对齐？
+- [ ] 公式编号是否在正确位置（通常右侧）？
+
+## 与其它 Agent 的协作
+
+- **上游调用者**：`orchestrator-agent` 在编译成功后调用本技能。
+- **下游消费者**：
+  - `layout-detective-agent` 使用页图进行视觉缺陷检测。
+  - `quality-gatekeeper-agent` 使用页图进行最终验收对比。
+  - `code-surgeon-agent` 在修复后可能请求局部页图验证特定修改。
+
+## 异常处理
+
+| 异常情况 | 处理方式 |
+|----------|----------|
+| Poppler 未安装 | 返回明确错误信息，包含安装指引 |
+| PDF 文件损坏 | 报告错误，请求重新编译 |
+| 部分页渲染失败 | 记录失败页码，尽可能渲染其余页，状态标记为 `partial` |
+| 磁盘空间不足 | 报告错误，清理临时目录或提示用户释放空间 |
+
+## 性能优化建议
+
+- 对于大型 PDF（>20 页），可考虑仅渲染指定页码范围，避免不必要开销。
+- 缓存机制：若 PDF 文件未修改且渲染参数相同，可复用已有页图。通过比较 PDF 文件哈希和渲染参数实现。
+
+## 注意事项
+
+- **页图是视觉验收的唯一依据**：严禁仅凭 PDF 文本抽取或日志判断排版质量。
+- **保持页码对应**：页图文件名必须明确反映页码，便于缺陷定位。
+- **高 DPI 不宜滥用**：过高 DPI 会导致图片体积庞大，影响传输和加载速度，按需使用。
+
+---
+
+**Visual Inspector Skill 就绪。**