Latex Paper Formatter

---
name: latex-paper-formatter
description: 当使用者说“整理建模论文 LaTeX”“修编译错误和引用”“统一公式、表格和图注”“按比赛模板排版”“检查交叉引用与缺图”时使用。先冻结内容并做基线编译，再在不改变数学含义、数字、引用或作者措辞的前提下修结构、符号格式、标签、表图、文献与版面；运行静态检查和实际编译，记录引擎、命令、警告与输出。只格式化和诊断，不补造公式、结果、来源或论文内容。
category: modeling/paper
version: 0.1.1
status: draft
priority: P0
compatible_agents:
  - claude-code
  - codex
  - cursor
  - codebuddy
  - nestudy
  - generic-llm-agent
display_name: LaTeX 建模论文排版
outputs:
  - chat
  - document
max_rounds: 35
suggest_hint: 内容定稿后，用「LaTeX 建模论文排版」统一符号、交叉引用、表图和编译结果，不碰数学含义
---

# LaTeX 建模论文排版 / LaTeX Paper Formatter

把内容已经冻结的建模论文整理成可编译、可追踪、符合正式模板的 LaTeX。格式问题与内容问题分开处理：
发现公式疑似错误时报告给作者，不借“排版修复”擅自改数学。

## 何时使用 / When to use

- 论文内容基本确定，需要套官方 class / template 并统一格式
- 有未定义引用、重复标签、缺图、bibliography 或编译警告
- 公式环境、编号、符号样式、单位、表格、图注与交叉引用不一致
- 页面溢出、表格裁切、浮动体乱序、公式断行或 PDF 视觉检查不过
- 需要记录可复现的编译命令、引擎、警告和最终 PDF

**不适用于** / Not for：

- 需要改变论文主张、章节论证或补分析 —— 用 `paper-structure-coach` / `paper-enhancement-builder`
- 需要修改模型方程、数据或代码 —— 方程与假设用 `modeling-assumption-builder`，数据处理与代码用 `modeling-code-builder`
- 要求补写引用、实验或结果以“填满版面” —— 本 skill 不生成内容
- 只有 Word / Google Docs 且不需要 LaTeX —— 使用对应文档格式工具

## 需要的输入 / Inputs

| 输入 | 必填 | 说明 |
|---|---|---|
| LaTeX 根文件 | 是 | 主 `.tex`、子文件、class / style、bibliography 与图表路径 |
| 官方模板 / 规则 | 是 | 编译引擎、页数、纸张、字号、匿名、参考文献和附件规则；没有时保留项目现状 |
| 内容冻结范围 | 是 | 哪些文字、公式、数字、图表和引用不允许改变 |
| 构建方式 | 否 | Makefile、latexmk、tectonic 或项目命令；已有命令优先 |
| 目标环境 | 否 | 本地 / CI / Overleaf、TeX 发行版与版本；用于解释差异 |
| 当前日志 / PDF | 否 | 用于定位错误和做前后视觉对照 |

材料不全时先做静态审计，不新建一套假定模板。正式比赛规则若无法核对，标 `unverified` 并请使用者提供，
不能凭往届经验补页数或匿名要求。

## 内容冻结 / Content preservation

格式化前记录内容指纹或至少保存 diff 基线，并把改动分成三类：

- **安全机械项**：空白、环境、label / ref 连接、文件路径、模板明确要求的样式
- **需作者确认**：符号冲突、单位不一致、疑似错公式、数字精度、图表与正文矛盾、缺引文
- **禁止补造**：新公式、结果、引用元数据、作者信息、实验与结论

公式的括号、上下标、求和范围、微分变量、向量 / 标量、负号和单位都可能改变含义，不属于纯视觉字符。

## 流程 / Process

### 1. 识别模板与构建合同

读取根文件、class / style、构建脚本和正式规则，确定：

- 根入口、引擎、bibliography backend 与完整构建命令
- 允许 / 禁止的 package 和模板不可改区域
- 纸张、边距、栏数、字号、页数、匿名与附件要求
- 生成图表、参考文献和最终 PDF 的依赖

遵循已有模板，不把个人偏好的 class、字体或 package 强加进去。

### 2. 先做基线静态检查与编译

运行：

```bash
python3 scripts/check_latex.py path/to/main.tex
```

命令里的 `scripts/` 相对本 skill 目录；在别的目录运行时写脚本的完整路径。不加 `--root` 时，读取范围是当前目录
（它包含全部根文件时）或根文件所在目录；论文用到这个范围以外的文件（例如 `../figures/`）时，加 `--root <论文项目根>`。
脚本按 TeX 的规则从根文件所在目录解析 `\input / \include`、bibliography 和 figure 路径（子文件里写的也一样），逐级比对
磁盘上文件名的大小写（macOS 默认不分大小写也照报），并检查 label / ref、常用 natbib / biblatex citation、手工编号（含
“公式 (3)”“式（5）”）和占位符；它不判断数学正确，也不能代替编译。`--selftest` 运行脚本自带的回归用例。

随后运行项目原有构建命令并记录：引擎 / 版本、命令、退出状态、首个根因错误、未定义引用、重复 label、缺字形、
overfull / underfull box、package conflict 与 PDF 页数。若不能编译，保留状态 `not-run` 或 `failed`，不能写“已修复”。

### 3. 建格式审计表

按类别列位置、现状、目标、是否会影响内容和验证方式：

1. 模板与文档结构
2. 符号、数学环境、编号和交叉引用
3. 单位、数值精度与符号首次定义
4. 表格、图、图注、浮动与可读性
5. bibliography、citation、数据 / 图表来源
6. 页眉页脚、目录、匿名、页数与提交要求
7. 构建、路径、生成文件与复现

遇到数学、数字、来源或作者决定，移入“需确认”，不要在同一补丁里猜。

### 4. 小批修改机械格式

优先从最可证伪的根因开始，每批只处理一类：

- 用稳定 `\label` + `\ref / \eqref` 替代手工编号
- 将错误数学环境换成语义等价环境，保持表达式原样
- 统一已有符号命令、向量 / 矩阵 / 算子样式和单位接口
- 按模板整理表格宽度、列标题单位、精度、图尺寸与图注
- 修 bibliography 连接与**已有、已核对**条目的格式
- 修相对路径、文件大小写、构建顺序和生成文件位置

详细约定按需读 `references/latex-conventions.md`。新增 package 前检查 class、现有 package、目标引擎与比赛模板，
不为一项局部格式引入冲突。

每个实质批次后立刻重新静态检查和编译；失败就修当前局部，不继续堆改动。

### 5. 处理警告与版面

- 错误、未定义 ref / cite、重复 label 与缺文件必须清零
- overfull 逐项定位：先修长公式 / 表 / URL / 不可断文本，不全局缩字号
- underfull 结合 PDF 目视判断，不为消除日志数字制造更差排版
- 浮动体按论证顺序靠近首次引用，不用大量 `[H]` 把页面挤坏
- 表图过宽时优先修源、拆表或横置，不把文字缩到不可读
- 页数超限先回到内容结构删重复，不能通过改官方边距或字号作弊

### 6. PDF 视觉验收

在目标纸张和实际缩放检查：封面 / 匿名、目录、页码、空白页、章节层级、公式断行、表格裁切、图中文字、图注、
参考文献、附录与最后一页。对照冻结基线确认数字、符号、公式、引用目标和结论没有变化。

编译通过不代表视觉通过；视觉通过也不代表内容正确。

### 7. 交付审计与复现记录

输出修改文件、机械改动、需作者确认项、静态检查结果、编译命令 / 环境 / 状态、警告和 PDF 路径。
有改动无法验证时明确说明，不把“理论上应当”写成完成。

## 输出格式 / Output

```markdown
## 格式审计
| 类别 | 位置 | 发现 | 拟修 / 已修 | 是否影响内容 | 验证状态 |

## 符号与单位
| 符号 / 数值 | 含义 | 单位 | 首次定义 | 冲突 / 决定 |

## 交叉引用与资源
| 对象 | label / key / path | 引用位置 | 状态 |

## 编译验证
- root / template:
- engine / version:
- command:
- static check:
- compile result:
- warnings:
- page count / PDF:

## 内容保全
- 仅格式改动：<文件 / 类型>
- 需作者确认：<公式、数字、来源或措辞>
- 未验证：<工具或环境缺口>
```

## 工具与跨 Agent 降级 / Tool fallback

- 能读写和执行时：基线检查 -> 小补丁 -> 静态检查 -> 编译 -> PDF 目视验收。
- 只能读不能写时：给定位明确的审计和最小 diff 建议，不声称文件已修。
- 能写不能编译时：只做低风险机械改动，返回准确命令并将编译标 `not-run`。
- 没有 Python 时：按脚本检查项人工审计；没有 TeX 时：静态检查不能冒充编译。
- 没有 PDF 查看能力时：报告编译状态，并把视觉验收列为必须由使用者完成的未决项。
- 不依赖某个 Agent API；脚本只用 Python 标准库，核心步骤可由任意 shell / 编辑器映射。

## 边界 / Boundaries

- **不改数学含义**：疑似错误只报告并询问，不能顺手“修正”。
- **不补写内容**：不添加模型、推导、实验、结果、限制或结论来填版面。
- **不造引用**：作者、标题、年份、DOI、页码与访问日期必须可核对；缺 key 不代表可以编一条。
- **不改官方模板作弊**：不缩边距、字号、行距或隐藏内容绕页数与匿名规则。
- **不把静态检查当编译**：脚本没发现问题不等于 TeX 或 PDF 正确。
- **不把编译成功当内容正确**：LaTeX 能排出错误方程和虚假数字。
- **不静默覆盖用户宏与样式**：先判断其用途和调用范围，局部修复优先。
- **不隐藏警告与未验证项**：失败、未运行、通过有警告、完全通过分开报告。
- **不代替作者最终核对**：公式、数字、署名、匿名、引用和 PDF 提交前由团队逐项确认。

## Token 控制 / Token discipline

- 先读根文件、导言区、构建脚本和日志首个根因，不默认展开所有子文件
- 静态脚本一次扫描交叉引用与资源，避免逐个手搜
- 编译日志只保留错误上下文与警告摘要；完整日志留文件
- 按错误类别小批修改，验证后再进入下一类
- 视觉检查按页记录问题，不把 PDF 全文转成对话文本

## 参考资料 / References

- `references/latex-conventions.md` —— 数学、单位、表格、图、文献、构建与视觉约定
- `scripts/check_latex.py` —— 标准库静态检查；支持项目根限制、多个根文件、`--json`、`--strict` 与 `--selftest`；
  退出码 0 无 error，1 有 error（`--strict` 时 warning 也算）或自检失败，2 命令行用法错误
- `../_shared/paper-argument-checklist.md` —— 需要判断表图与主张职责时读取，不用于改内容

## 变更记录 / Changelog

| 版本 | 日期 | 变更 | 类型 |
|---|---|---|---|
| 0.1.1 | 2026-09-26 | check_latex.py 改按根文件目录解析 \input、bibliography、图片与 \graphicspath，只在子文件目录下成立的路径报错；逐级比对真实文件名大小写（macOS 上也报）；补中文“公式 (3)”“式（5）”手工编号与带点文件名补 .tex；不传 --root 时从 skill 目录照文档运行也能读到论文；新增 --selftest；“不适用于”改为实名路由 | patch |
| 0.1.0 | 2026-08-17 | 初始草稿：内容冻结、基线编译、机械格式批次、静态检查脚本与 PDF 视觉验收 | minor |