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. 先做基线静态检查与编译

运行：

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

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

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

## 交叉引用与资源
| 对象 | 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