paperfit-cli 1.0.0

package/skills/taxonomy-vto/SKILL.md

@@ -0,0 +1,486 @@
+# VTO Taxonomy Knowledge Base
+
+## 概述
+
+本技能为 **Visual Typesetting Optimization (VTO)** 任务提供完整的视觉排版缺陷分类知识库。它是 `layout-detective-agent` 进行逐页视觉诊断的核心参考手册，定义了每一类缺陷的**视觉特征、诊断方法、严重等级判定**以及与编译日志信号的对应关系。
+
+**使用方式**：排版侦探 Agent 在对 PDF 页图进行审查时，应逐项对照本手册中的缺陷定义，识别并记录发现的缺陷，输出结构化诊断报告。
+
+---
+
+## 分类体系总览
+
+VTO 缺陷分为五大类别，每个类别下包含若干具体缺陷类型：
+
+| 类别 | 名称 | 缺陷数量 | 默认严重等级 |
+|------|------|----------|-------------|
+| A | 空间利用缺陷 | 4 | Major |
+| B | 浮动体缺陷 | 4 | Major |
+| C | 排版一致性缺陷 | 3 | Minor |
+| D | 溢出与对齐缺陷 | 3 | Major |
+| E | 跨模板迁移缺陷 | 3 | Critical |
+
+严重等级说明：
+- **Critical**：必须修复，否则论文不符合投稿要求（编译失败、页数严重不符等）
+- **Major**：严重影响视觉专业度，强烈建议修复
+- **Minor**：影响美观但不致命，可在时间充裕时修复
+
+---
+
+## Category A：空间利用缺陷
+
+此类缺陷关注页面空间的分配效率与视觉平衡，核心是判断“空白是否合理”、“段落是否完整”。
+
+### A1：孤行/寡行 (Widow/Orphan Lines)
+
+**定义**：
+- **孤行 (Widow)**：段落最后一行单独出现在下一页顶部。
+- **寡行 (Orphan)**：段落第一行单独留在上一页底部。
+- **段尾小尾巴**：段落末尾一行仅含 1-3 个单词，长度不足栏宽的 1/4。
+
+**视觉诊断方法**：
+1. 逐页检查页面的顶部和底部区域。
+2. 若页面顶部第一行为某段落的末行 → **孤行**。
+3. 若页面底部最后一行为某段落的首行 → **寡行**。
+4. 对于任意段落末行，目测其长度：若远短于同行其他行（明显短于栏宽的 1/4），记为**段尾小尾巴**（与孤行/寡行同等对待）。
+
+**严重等级判定**：
+- 出现任意孤行或寡行 → **Major**
+- 仅出现段尾小尾巴（非跨页）→ **Minor**（但若多处出现，升级为 Major）
+
+**与日志信号的关联**：无直接日志警告。
+
+**常见误判提醒**：
+- 公式环境或列表环境后的短行可能为正常现象，需结合上下文判断。
+- 双栏布局中，左右栏的段落独立判断，不要跨栏比较。
+
+**诊断记录格式**：
+```
+- defect_id: A1
+- page: 5
+- location: "第 5 页顶部第一行"
+- description: "段尾小尾巴：仅含单词 'the proposed method'，长度不足栏宽 1/5"
+- severity: minor/major
+```
+
+---
+
+### A2：末页大面积留白 (Excessive Trailing Whitespace)
+
+**定义**：论文最后一页（参考文献之前或之后）存在超过页面高度 20% 的连续空白区域。
+
+**视觉诊断方法**：
+1. 定位 PDF 的最后一页（参考文献所在页或其后的附录/致谢页）。
+2. 目测或估算空白区域占页面内容区域的比例。
+   - 若空白集中在页面下半部分，且面积明显超过 1/5 页面高度，判定为缺陷。
+3. 特别注意：若参考文献后仍有内容（如附录），则最后一页为附录末页。
+
+**阈值参考**：
+- 空白比例 < 15%：可接受
+- 空白比例 15%-20%：建议优化
+- 空白比例 > 20%：**缺陷 (Major)**
+
+**严重等级**：**Major**
+
+**与日志信号的关联**：无。
+
+**常见误判提醒**：
+- 若末页是参考文献的开始且参考文献未满一页，此时空白为正常现象（参考文献允许跨页），不视为缺陷。仅当参考文献后仍有大段空白时才判定。
+
+**诊断记录格式**：
+```
+- defect_id: A2
+- page: 9
+- description: "末页空白面积约占页面高度的 35%"
+- severity: major
+```
+
+
+### A3：页数预算违反 (Page Budget Violation)
+
+**定义**：论文总页数超出或不足用户指定的目标页数（通常来自会议/期刊要求）。
+
+**视觉诊断方法**：
+1. 获取用户输入的目标页数（如未提供，则跳过此项检测）。
+2. 检查 PDF 总页数。
+3. 若实际页数 ≠ 目标页数，记录偏差。
+
+**严重等级**：**Critical**
+
+**与日志信号的关联**：无。
+
+**诊断记录格式**：
+```
+- defect_id: A3
+- description: "实际 10 页，目标 9 页，超出 1 页"
+- severity: critical
+```
+
+---
+
+### A4：双栏末页左右栏高度不齐 (Unbalanced Column Heights)
+
+**定义**：在双栏排版的最后一页，左右两栏的底部高度不一致，高度差超过 2 行。
+
+**视觉诊断方法**：
+1. 仅适用于双栏模板（如 IEEE、ACM、ECCV 等）。
+2. 定位最后一页，在左右栏底部画一条水平参考线。
+3. 若两栏底部高度差超过约 2 行正文的高度，判定为缺陷。
+
+**严重等级**：**Minor**（若与其他缺陷叠加，可升级）
+
+**与日志信号的关联**：无。
+
+**诊断记录格式**：
+```
+- defect_id: A4
+- page: 12
+- description: "左右栏底部高度差约 4 行"
+- severity: minor
+```
+
+
+## Category B：浮动体缺陷
+
+此类缺陷关注图表的放置位置、尺寸匹配度以及对阅读流的干扰。
+
+### B1：浮动体远离首次引用 (Float-Reference Distance)
+
+**定义**：图表出现在距离其首次被引用的页面过远的位置（通常页码差 ≥ 2）。
+
+**视觉诊断方法**：
+1. 在 PDF 中搜索图表标签（如 "Figure 1"、"Table 2"）的首次出现位置。
+2. 找到该图表实际出现的页面。
+3. 计算页码差：`|图表页码 - 首次引用页码|`。
+4. 若差值 ≥ 2，记录缺陷。
+
+**严重等级**：**Major**（若差值 ≥ 3，升级为 Critical）
+
+**与日志信号的关联**：
+- 编译日志中可能出现 `LaTeX Warning: Float too large for page` 或浮动体放置相关的 warning，作为辅助证据。
+
+**诊断记录格式**：
+```
+- defect_id: B1
+- object: "Figure 3"
+- reference_page: 4
+- float_page: 6
+- distance: 2
+- severity: major
+```
+
+---
+
+### B2：浮动体大小不适配栏宽 (Float Width Mismatch)
+
+**定义**：图片或表格的宽度未充分利用栏宽，过窄（两侧留白过大）或超宽（溢出或被截断）。
+
+**视觉诊断方法**：
+1. 对于单栏图表：对比图表宽度与栏宽，目测利用率。
+   - 若图表宽度 < 栏宽的 85%，视为**过窄**。
+   - 若图表宽度 > 栏宽（内容伸出右边界），视为**超宽**。
+2. 对于跨栏图表（`figure*`/`table*`）：对比图表宽度与页宽，标准同上。
+
+**严重等级**：
+- 过窄：**Minor**（若多图表均过窄，升级为 Major）
+- 超宽/溢出：**Major**
+
+**与日志信号的关联**：
+- 超宽常伴随 `Overfull \hbox` 警告（参见 D1）。
+
+**诊断记录格式**：
+```
+- defect_id: B2
+- object: "Figure 2"
+- page: 3
+- description: "图片宽度仅占栏宽约 60%，两侧留白过大"
+- severity: minor
+```
+
+---
+
+### B3：浮动体连续堆叠 (Float Clustering)
+
+**定义**：同一页或连续两页出现 3 个或以上的图表，且中间几乎无正文间隔，形成“图表页”。
+
+**视觉诊断方法**：
+1. 检查每一页的图表数量。
+2. 若某页包含 ≥ 3 个图表，且正文少于 3 行，视为**浮动体堆叠**。
+3. 若连续两页累计图表 ≥ 4 且中间正文极少，同样视为缺陷。
+
+**严重等级**：**Minor**（但若导致阅读体验严重下降，可标为 Major）
+
+**与日志信号的关联**：无直接日志，但大量浮动体可能引发 placement warning。
+
+**诊断记录格式**：
+```
+- defect_id: B3
+- page: 7
+- description: "该页包含 3 个图表，正文仅 2 行"
+- severity: minor
+```
+
+---
+
+### B4：浮动体跨页分裂 (Float Page Orphaning)
+
+**定义**：一个图表（尤其是长表格）在不适当的位置断开，跨两页显示，且第二页未重复表头。
+
+**视觉诊断方法**：
+1. 检查跨页的表格或图表。
+2. 若表格在分页处被截断，且下一页续表中缺少表头（或未使用 `longtable` 的重复表头功能），判定为缺陷。
+
+**严重等级**：**Minor**（若为关键数据表，升级为 Major）
+
+**与日志信号的关联**：无。
+
+**诊断记录格式**：
+```
+- defect_id: B4
+- object: "Table 4"
+- page: 8-9
+- description: "表格跨页分裂，第二页缺少表头"
+- severity: minor
+```
+
+---
+
+## Category C：排版一致性缺陷
+
+此类缺陷关注全篇排版风格的统一性。
+
+### C1：表格字号不统一 (Inconsistent Table Font Sizes)
+
+**定义**：不同表格使用了差异明显的字号，通常由 `\resizebox` 或手动 `\tiny`/`\small` 滥用导致。
+
+**视觉诊断方法**：
+1. 对比全篇至少 3 个表格的字号大小。
+2. 若发现某些表格的字号明显小于或大于其他表格，且差异超过 1 个等级（如一个用 `\small`，另一个用 `\footnotesize`），记录缺陷。
+3. 特别注意使用 `\resizebox` 缩放表格导致的字号异常（文字被整体缩放，视觉上变形）。
+
+**严重等级**：**Minor**
+
+**与日志信号的关联**：无直接日志，但可在源码中搜索 `\resizebox`。
+
+**诊断记录格式**：
+```
+- defect_id: C1
+- description: "Table 1 使用 \small，Table 3 使用 \resizebox 导致字号偏小，全篇表格字号不统一"
+- severity: minor
+```
+
+---
+
+### C2：图片分辨率/风格不一致 (Inconsistent Figure Quality/Style)
+
+**定义**：论文中图片分辨率差异大，或风格（如字体、配色、线条粗细）不统一。
+
+**视觉诊断方法**：
+1. 检查所有图片的清晰度，注意模糊、锯齿、像素化现象。
+2. 对比不同图片的视觉风格：字体类型、字号、配色方案、线条风格。
+3. 若差异明显（例如一张为清晰矢量图，另一张为低分辨率截图），记录缺陷。
+
+**严重等级**：**Minor**
+
+**修复提示**：此缺陷系统无法自动修复，需提示用户替换低质量图片或统一绘制风格。
+
+**诊断记录格式**：
+```
+- defect_id: C2
+- object: "Figure 5"
+- description: "图片分辨率低，锯齿明显，与 Figure 2 的矢量图风格不一致"
+- severity: minor
+```
+
+---
+
+### C3：Caption 格式不统一 (Inconsistent Caption Format)
+
+**定义**：图表标题的字体、间距、编号格式、结尾标点不一致。
+
+**视觉诊断方法**：
+1. 检查至少 3 个图表标题的格式：
+   - 字体是否一致（加粗/不加粗、斜体/正体）？
+   - 与图表主体的间距是否一致？
+   - 结尾是否有标点（有的以句号结尾，有的没有）？
+   - 表格标题位置是否一致（通常表格标题在上方，图片在下方）？
+2. 若发现不一致，记录缺陷。
+
+**严重等级**：**Minor**
+
+**诊断记录格式**：
+```
+- defect_id: C3
+- description: "Figure 1 标题加粗，Figure 2 标题未加粗；Table 1 标题无句号，Table 2 标题以句号结尾"
+- severity: minor
+```
+
+---
+
+## Category D：溢出与对齐缺陷
+
+此类缺陷涉及内容超出边界或未正确断行，通常有明确的日志信号。
+
+### D1：Overfull hbox
+
+**定义**：文本行、表格单元格或公式内容超出栏宽，LaTeX 无法自动断行。
+
+**视觉诊断方法**：
+1. 检查页面的右边界，寻找伸出版心或栏宽的内容（可能被截断或与边界重叠）。
+2. 特别关注：
+   - 长单词（未正确断词）
+   - 表格中的长文本单元格
+   - 超长公式
+3. **必须结合编译日志**：在 `.log` 中搜索 `Overfull \hbox`，获取精确的溢出位置和溢出量（pt）。
+
+**严重等级**：
+- 溢出量 < 5pt 且不影响阅读：**Minor**
+- 溢出量 ≥ 5pt 或内容明显被截断：**Major**
+
+**诊断记录格式**：
+```
+- defect_id: D1
+- page: 4
+- object: "段落第 3 行 / Table 2 某单元格"
+- log_signal: "Overfull \hbox (12.3pt too wide) in paragraph at lines 245--248"
+- visual_evidence: "单词 'implementation' 伸出右边界约 2mm"
+- severity: major
+```
+
+---
+
+### D2：长公式未合理断行 (Unbroken Long Equations)
+
+**定义**：过长的数学公式未在多行环境中断行，导致溢出或视觉拥挤。
+
+**视觉诊断方法**：
+1. 检查所有公式环境（`equation`、`\[...\]`）。
+2. 若公式长度明显超过栏宽的 90% 且未断行，或已溢出，记录缺陷。
+3. 对于多行公式（`align`、`multline`），检查断行位置是否合理（通常在等号或运算符处）。
+
+**严重等级**：**Major**（若溢出）或 **Minor**（若未溢出但明显过长且可优化）
+
+**与日志信号的关联**：常伴随 `Overfull \hbox` 警告。
+
+**诊断记录格式**：
+```
+- defect_id: D2
+- page: 6
+- object: "Equation (12)"
+- description: "单行公式长度超过栏宽，溢出约 8pt"
+- severity: major
+```
+
+---
+
+### D3：URL/长标识符溢出 (URL/Long Identifier Overflow)
+
+**定义**：参考文献或正文中的 URL、DOI、长标识符超出栏宽。
+
+**视觉诊断方法**：
+1. 检查参考文献区域的 URL 和 DOI。
+2. 若某条 URL 伸出右边界，记录缺陷。
+
+**严重等级**：**Minor**（但若多处出现，升级为 Major）
+
+**与日志信号的关联**：常伴随 `Overfull \hbox` 在参考文献区域。
+
+**诊断记录格式**：
+```
+- defect_id: D3
+- page: 10
+- object: "参考文献 [23] 的 URL"
+- description: "URL 超出栏宽约 15pt"
+- severity: minor
+```
+
+---
+
+## Category E：跨模板迁移缺陷
+
+此类缺陷仅在用户执行模板切换任务时激活。
+
+### E1：单栏↔双栏图表尺寸失配
+
+**定义**：模板切换后，原模板的图表尺寸设置不再适用，导致图表在新模板下尺寸不当。
+
+**视觉诊断方法**：
+1. 对比原模板和新模板的栏宽/页宽。
+2. 检查所有图表：
+   - 若原为单栏全宽图，在新双栏模板中仍为单栏宽（应改为跨栏 `figure*`），图表显得过小。
+   - 若原为双栏跨栏图，在新单栏模板中尺寸异常。
+3. 记录所有尺寸不适配的图表。
+
+**严重等级**：**Critical**
+
+**诊断记录格式**：
+```
+- defect_id: E1
+- object: "Figure 1"
+- description: "原为单栏全宽图，在新双栏模板中仅占单栏，宽度利用率不足 50%"
+- severity: critical
+```
+
+---
+
+### E2：页数预算不匹配
+
+**定义**：模板切换后总页数与目标模板预期页数相差较大。
+
+**视觉诊断方法**：
+1. 获取目标模板的预期页数（如 ICLR 9 页 → ECCV 14 页）。
+2. 对比当前 PDF 总页数与预期值。
+3. 若偏差超过 1 页，记录缺陷。
+
+**严重等级**：**Critical**
+
+**诊断记录格式**：
+```
+- defect_id: E2
+- description: "当前 9 页，目标模板预期 14 页，需扩写 5 页内容"
+- severity: critical
+```
+
+---
+
+### E3：模板特定宏兼容性
+
+**定义**：新模板中使用了已废弃或冲突的宏包、命令，导致编译失败或内容缺失。
+
+**视觉诊断方法**：
+1. 检查编译日志中的错误和警告。
+2. 常见信号：`Undefined control sequence`、`Option clash for package`、`Environment XXX undefined`。
+3. 若编译失败，优先处理此类缺陷。
+
+**严重等级**：**Critical**
+
+**诊断记录格式**：
+```
+- defect_id: E3
+- log_signal: "Undefined control sequence \theoremstyle"
+- description: "新模板不支持 amsthm 宏包的 \theoremstyle 命令"
+- severity: critical
+```
+
+---
+
+## 诊断工作流指南
+
+`layout-detective-agent` 应遵循以下步骤：
+
+1. **加载配置**：读取 `config/vto_taxonomy.yaml` 和本技能文档。
+2. **逐页审查**：使用 `visual-inspector` 技能渲染的页图，按页码顺序检查。
+3. **对照分类**：将观察到的视觉异常与上述缺陷类型逐一比对。
+4. **结合日志**：对于 D 类缺陷和编译问题，务必交叉验证 `.log` 文件。
+5. **记录缺陷**：为每个发现的缺陷生成结构化条目（包含 `defect_id`、`page`、`object`、`description`、`severity`）。
+6. **输出诊断报告**：汇总所有缺陷，按严重等级和类别排序，输出 JSON 格式的诊断结果。
+
+## 注意事项
+
+- **上下文敏感**：某些视觉特征在不同模板下可能有不同评判标准（如单栏 vs 双栏），需结合模板类型调整阈值。
+- **优先级排序**：Critical 和 Major 缺陷必须优先修复；Minor 缺陷可在主要缺陷清除后处理。
+- **避免过度诊断**：对于正常排版现象（如公式后的自然短行），不要误判为缺陷。
+- **与代码外科医生的协作**：诊断报告中的 `defect_id` 将直接用于路由到对应的修复 Skill（参见 `config/vto_taxonomy.yaml` 中的 `skill_routing` 映射）。
+
+本知识库将随着系统迭代不断扩充，涵盖更多边界案例和会议特定的排版规范。
+```