name	make_latex_model
version	2.7.1
author	ChineseResearchLaTeX Project
maintainer	project-maintainers
status	stable
category	normal
description	LaTeX 模板高保真优化器，支持任意 LaTeX 模板的样式参数对齐、标题文字对齐、标题格式对比（加粗）、HTML 可视化报告、LaTeX 自动修复建议和像素级 PDF 对比验证
tags	latex, template, optimization, nsfc, pdf-analysis, style-alignment, iterative-optimization
dependencies	[object Object]
requires	xelatex, pdflatex, bibtex
compatibility	[object Object]
last_updated	Tue Jan 06 2026 00:00:00 GMT+0000 (Coordinated Universal Time)
changelog	../../CHANGELOG.md

NSFC LaTeX 模板高保真优化器

📋 文档目录

深度参考 - 文档参考范围
核心目标 - 样式要素与关键点
执行模式说明 - 硬编码工具 + AI 规划
工作空间说明 - 专用工作空间管理
触发条件 - 何时使用本技能
输入参数 - 必需与可选参数
执行流程 - 完整的 6 步工作流程
迭代优化闭环 - 自动化迭代优化
输出规范 - 修改摘要与代码变更
核心原则 - 绝对禁区与修改原则
验证清单 - 验收标准
常见问题 - FAQ 解答

深度参考

本项目的 CLAUDE.md 和 skills/README.md 规范
现有某个 project 的 @config.tex 的样式定义模式
⚠️ 关于 main.tex 的参考范围：
- ✅ 允许参考：main.tex 中的 \section{}、\subsection{} 标题文本
- ❌ 禁止参考：main.tex 中的 \input{} 引用的正文内容文件

核心目标

确保 LaTeX 渲染的 PDF 与 Word 版打印的 PDF 像素级对齐：

样式要素（必须完全一致）

标题层级格式（一级、二级、三级、四级）
⚠️ 标题文字内容（每年度的 Word 模板标题可能不同）
字体（中文楷体 + 英文 Times New Roman）
字号（三号、四号、小四等）
颜色（MsBlue RGB 0,112,192）
间距（行距、段前段后、缩进）
列表样式（编号格式、缩进）
页面设置（边距、版心）

⚠️ 关键 1：标题文字对齐

标题的文字内容必须与 Word 完全相同
标题的编号格式必须与 Word 完全相同（如"1." vs "1．"）
标点符号必须与 Word 完全相同（如全角/半角符号）
例如：Word 是"1. 项目的立项依据"，LaTeX 必须完全一致

⚠️ 关键 2：每行字数对齐

每行的字数必须与 Word 完全相同
换行位置必须与 Word 完全一致
这需要精确调整：字号、字间距、行距、段间距

执行模式说明

本技能采用**"硬编码工具 + AI 规划"**的混合模式：

自动模式（硬编码脚本）

以下步骤由 Python 脚本自动执行，无需 AI 干预：

步骤	脚本工具	输入	输出
状态检查	`scripts/check_state.py`	项目路径	状态报告
PDF 样式分析	`scripts/analyze_pdf.py`	Word PDF	`*_analysis.json`
标题文字对比	`scripts/compare_headings.py`	Word .docx + LaTeX	对比报告
样式参数验证	`scripts/run_validators.py`	项目路径	验证报告
编译检查	`xelatex` 命令	.tex 文件	.pdf

AI 规划模式（需要智能决策）

以下步骤需要 AI 根据分析结果进行规划和执行：

决策点	输入数据	AI 任务	输出
决策点 1: 是否需要修改样式？	PDF 分析结果 + 当前配置	判断差异是否超出容忍度	修改清单或跳过
决策点 2: 生成具体修改方案	差异分析结果	规划 LaTeX 代码修改	具体修改内容
决策点 3: 应用修改到配置文件	修改方案	使用 Edit 工具修改	修改后的 @config.tex
决策点 4: 验证结果是否达标	修改前后的验证报告	判断是否需要迭代	继续微调/完成

协作流程

Word 模板 → [自动] analyze_pdf.py → 分析结果
                                    ↓
                          当前 @config.tex
                                    ↓
                         [AI 决策点 1] 是否需修改？
                                    ↓
                           是 → [AI 决策点 2] 生成方案
                                    ↓
                          [AI 决策点 3] 应用修改
                                    ↓
                          [自动] 编译 + 验证
                                    ↓
                         [AI 决策点 4] 是否达标？
                                    ↓
                     否 → 微调 → 返回 [AI 决策点 2]
                     是 → 完成

关键原则:

✅ 数据提取 由硬编码工具完成（精确、稳定）
✅ 决策判断 由 AI 完成（灵活、可解释）
✅ 代码修改 由 AI + Edit 工具完成（可控、可回溯）

注：AI 决策点的详细规范已整合到"第 3 节执行流程"的相应步骤中。

工作空间说明

本 skill 使用专用工作空间存储所有工作产物，避免污染用户项目目录。

工作空间结构

skills/make_latex_model/workspace/{project_name}/
├── baseline/          # Word PDF 基准文件
│   ├── word.pdf
│   ├── word_analysis.json
│   └── quality_report.json
├── iterations/        # 迭代历史记录
│   ├── iteration_001/
│   │   ├── main.pdf
│   │   ├── config.tex
│   │   └── metrics.json
│   └── iteration_002/
├── reports/           # 生成的报告
│   ├── diff_report.html
│   └── optimization_report.html
├── backup/            # 备份文件
│   └── main_*.tex.bak
└── cache/             # 缓存文件
    └── pdf_renders/

路径管理

所有脚本统一使用 WorkspaceManager 获取路径：

from core.workspace_manager import WorkspaceManager

ws_manager = WorkspaceManager()
baseline_dir = ws_manager.get_baseline_path("NSFC_Young")
report_path = ws_manager.get_reports_path("NSFC_Young")

清理策略

缓存文件默认保留 24 小时
迭代历史默认保留最近 10 轮
可通过 config.yaml 的 workspace 节配置清理策略

触发条件

用户在以下场景触发本技能：

NSFC 发布了新的年度 Word 模板
当前 LaTeX 模板与 Word 模板存在明显样式差异
用户主动要求"对齐 Word 样式""更新模板格式"

输入参数

参数	类型	必需	说明
`project`	string	是	项目名称（如 `NSFC_Young`、`NSFC_General`）
`word_template_year`	string	是	Word 模板年份（如 `2025`）
`optimization_level`	string	否	优化级别：`minimal`（最小改动）\|`moderate`（中等）\|`thorough`（彻底），默认 `moderate`
`dry_run`	boolean	否	预览模式，不实际修改文件，默认 `false`

执行流程

步骤 0：预检查（AI 必须首先执行）

AI 在开始任何优化工作前，必须先执行状态检查：

python3 skills/make_latex_model/scripts/check_state.py projects/{project}

根据状态报告决定后续行动：

如果 has_baseline=false：提示用户先生成 Word PDF
如果 compilation_status=failed：先修复编译错误
如果 baseline_source=quicklook：调整像素对比权重

AI 决策点 1：是否需要修改样式？

输入数据:

*_analysis.json: Word PDF 分析结果
extraTex/@config.tex: 当前样式配置
config.yaml: 容忍度配置

判断逻辑:

# 伪代码
for 参数 in ["行距", "字号", "颜色", "边距"]:
    word_value = analysis[参数]
    latex_value = extract_from_config(config_tex)
    diff = abs(word_value - latex_value)
    tolerance = config["validation"]["tolerance"][参数]

    if diff > tolerance:
        需要修改 = True
        修改清单.append({
            "参数": 参数,
            "当前值": latex_value,
            "目标值": word_value,
            "差异": diff
        })

输出格式:

| 参数 | 当前值 | 目标值 | 差异 | 容忍度 | 是否需修改 |
|------|--------|--------|------|--------|-----------|
| 行距 | 1.5 | 1.2 | 0.3 | 0.1 | ✅ 是 |
| MsBlue RGB | (0,112,190) | (0,112,192) | 2 | 2 | ⚠️ 边界 |

步骤 1：理解现状（深度阅读）

读取 projects/{project}/extraTex/@config.tex，重点分析：
- 宏包加载
- 页面设置（geometry）
- 颜色定义（definecolor）
- 字体设置（fontspec、xeCJK）
- 字号系统（newcommand 字号命令）
- 标题格式（titlesec 定制）
- 列表样式（enumitem 配置）

步骤 2：分析 Word 模板（像素级测量）

2.1 获取 Word PDF 基准

方案 0：用户已提供 PDF（最快）

如果用户已经从 Word 模板导出了 PDF 文件，直接使用即可：

# 复制用户提供的 PDF 到工作空间
cp /path/to/user/provided/word.pdf \
   skills/make_latex_model/workspace/{project}/baseline/word.pdf

要求：

PDF 必须是 Word/LibreOffice 导出的，不能用 QuickLook 预览
PDF 应包含完整的模板样式（标题、正文、列表等）

方案 1：LibreOffice 命令行自动转换（主推）

如果用户只有 Word 模板文件（.doc/.docx），使用 LibreOffice 自动转换：

# 自动检测并转换 Word 模板为 PDF
python3 skills/make_latex_model/scripts/generate_baseline.py \
  --project NSFC_Young \
  --template-year 2025

脚本会自动完成：

定位 Word 模板文件（支持 .doc 和 .docx）
使用 LibreOffice 无头模式转换为 PDF
保存到工作空间 workspace/{project}/baseline/word.pdf
生成高分辨率 PNG 用于像素对比（通过 pdftoppm）

环境要求：

LibreOffice（安装命令见下方）
pdftoppm（poppler-utils）

LibreOffice 安装：

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
sudo apt-get install libreoffice

# Windows
# 从 https://www.libreoffice.org/ 下载安装

方案 2：Microsoft Word COM 自动化（Windows 仅）

如果在 Windows 环境且无法安装 LibreOffice，可使用 Microsoft Word COM 自动化（需 Python pywin32 库）：

python3 skills/make_latex_model/scripts/generate_baseline.py \
  --project NSFC_Young \
  --template-year 2025 \
  --use-msword

渲染质量说明：

渲染引擎	精度	自动化程度	推荐度
用户已提供 PDF	取决于来源	零操作	⭐⭐⭐⭐⭐
LibreOffice	高（与 Word 99% 一致）	完全自动化	⭐⭐⭐⭐⭐
Microsoft Word COM	最高（100% Word 原生）	自动化（Windows 仅）	⭐⭐⭐⭐
QuickLook 预览	低（断行/行距有差异）	自动化但不准确	⚠️ 不推荐

为什么不用 QuickLook：

QuickLook 预览渲染引擎与 Word 本质不同（行距、字体渲染、断行算法都有差异）
使用 QuickLook 基准会导致正确的样式修改反而显示像素对比指标恶化
如果只能使用 QuickLook 基准，应降低像素对比指标的权重，以样式参数正确性为主要验收标准

2.2 自动提取样式参数（推荐）

使用 analyze_pdf.py 工具自动提取 Word PDF 的样式参数：

# 安装依赖（首次使用）
pip install PyMuPDF

# 分析 Word PDF 基准
python3 skills/make_latex_model/scripts/analyze_pdf.py \
  projects/NSFC_Young/template/word_baseline.pdf

输出内容：

📐 页面布局：页面尺寸、边距（左/右/上/下，单位：cm）
🔤 字体统计：字体名称、使用频率、字号列表、颜色（RGB）
📏 行距分析：平均行距（pt）
💾 详细分析结果：自动保存为 *_analysis.json，可用于后续对比

输出示例：

============================================================
页面布局
============================================================
页面尺寸: 21.01 cm x 29.71 cm
边距:
  左:   3.20 cm
  右:   3.14 cm
  上:   2.54 cm
  下:   2.54 cm

============================================================
字体使用统计
============================================================
字体: TimesNewRomPSMT
  使用次数: 245
  字号: [12.0, 14.0, 15.0]
  颜色 (RGB): [[0, 0, 0], [0, 112, 192]]
  是否加粗: False

字体: KaiTi_GB2312
  使用次数: 128
  字号: [12.0, 15.0, 16.0]
  颜色 (RGB): [[0, 0, 0], [0, 112, 192]]
  是否加粗: True

============================================================
行距分析
============================================================
平均行距: 18.00 pt

详细分析结果已保存到: word_baseline_analysis.json

优势：

✅ 自动化：无需手动测量，减少人为误差
✅ 精确：直接从 PDF 提取参数，精度 ±0.01pt
✅ 可追溯：保存 JSON 分析结果，便于版本对比
✅ 快速：几秒内完成分析

步骤 2.5：提取标题结构

自动化工具：使用 compare_headings.py 自动对比标题文字

安装依赖（首次使用）：
```
pip install python-docx
```

自动对比 Word 和 LaTeX 标题：

# 生成 HTML 可视化报告
python3 skills/make_latex_model/scripts/compare_headings.py \
  projects/NSFC_Young/template/最新word模板-青年科学基金项目（C类）-正文.docx \
  projects/NSFC_Young/main.tex \
  --report heading_report.html

查看报告：
- 打开 heading_report.html 查看可视化对比结果
- 报告会显示：
  - ✅ 完全匹配的标题（绿色）
  - ⚠️ 有差异的标题（黄色，并排显示 Word 和 LaTeX 内容）
  - ❌ 仅在一方的标题（红色）
格式对比（加粗）：
```
# 检查标题内的加粗格式是否一致
python3 skills/make_latex_model/scripts/compare_headings.py \
  projects/NSFC_Young/template/最新word模板-青年科学基金项目（C类）-正文.docx \
  projects/NSFC_Young/main.tex \
  --check-format \
  --report heading_format_report.txt
```
- Word 模板中的标题可能包含混合格式，例如"立项依据与研究内容"
- 使用 --check-format 参数可以检测 LaTeX 是否正确实现了加粗样式
- 报告会显示：
  - ✅ 文本和格式都完全匹配
  - ⚠️ 文本差异（传统的文字内容不匹配）
  - 🔶 格式差异（加粗位置不一致，并标注具体位置）

🎨 HTML 可视化报告：

# 生成包含格式对比的 HTML 报告
python3 skills/make_latex_model/scripts/compare_headings.py \
  projects/NSFC_Young/template/最新word模板-青年科学基金项目（C类）-正文.docx \
  projects/NSFC_Young/main.tex \
  --check-format \
  --report heading_format_report.html

HTML 报告直观显示 Word 和 LaTeX 的格式差异
加粗文本用 <b> 标签高亮显示
格式差异用黄色背景和详细位置标注
支持并排对比（Word vs LaTeX）

🔧 LaTeX 修复建议：

# 自动生成 LaTeX 修复代码
python3 skills/make_latex_model/scripts/compare_headings.py \
  projects/NSFC_Young/template/最新word模板-青年科学基金项目（C类）-正文.docx \
  projects/NSFC_Young/main.tex \
  --check-format \
  --fix-file heading_fix_suggestions.tex

自动生成可直接复制的 LaTeX 修复代码
根据 Word 格式生成正确的 \textbf{} 标记

输出文件示例：

% LaTeX 标题格式修复建议
% section_1: （一）立项依据与研究内容
\section{\textbf{（一）立项依据}与研究内容}

自动转换 .doc 为 .docx（如需要）：

# 脚本会自动检测并转换 .doc 格式
python3 skills/make_latex_model/scripts/compare_headings.py \
  projects/NSFC_Young/template/最新word模板-青年科学基金项目（C类）-正文.doc \
  projects/NSFC_Young/main.tex \
  --auto-convert \
  --report heading_report.html

手动验证（可选，用于调试）：
- ⚠️ 不推荐手动对比，应使用自动化工具
- 如需验证，可打开生成的 HTML 报告查看可视化结果
- 或使用 --fix-file 参数自动生成修复代码

步骤 3：差异分析与优化策略（像素级）

对比当前 LaTeX 样式与 Word 模板，识别差异：
- 字号差异（如 14pt vs 15pt）—— 精度 ±0.1pt
- 颜色差异（MsBlue RGB 值）
- 间距差异（行距、段前段后）—— 精度 ±0.5pt
- 编号格式差异（1.1 vs 1.1.）
- ⚠️ 换行位置差异 —— 需要调整字间距或字号微调
根据 optimization_level 确定修改策略：
- minimal：仅修改明显错误的样式（如颜色值错误）
- moderate（默认）：调整与 Word 不一致的样式，保持结构稳定
- thorough：重构样式系统，实现最大保真度

AI 决策点 2：生成修改方案

输入: 修改清单（来自决策点 1）

AI 任务:

定位 @config.tex 中的相关代码段
生成具体的 LaTeX 代码修改
确保修改符合"轻量级修改原则"（见 5.1 节）

输出示例:

% 修改行距：1.5 → 1.2
- \renewcommand{\baselinestretch}{1.5}
+ \renewcommand{\baselinestretch}{1.2}

% 修改 MsBlue 颜色
- \definecolor{MsBlue}{RGB}{0,112,190}
+ \definecolor{MsBlue}{RGB}{0,112,192}

约束条件:

✅ 优先调整参数值
✅ 新增自定义命令（如需要）
❌ 不删除或重命名现有命令
❌ 不改变宏包加载顺序

步骤 4：轻量级修改原则（像素级精度）

优先调整参数，不重构结构：
- 调整 \titleformat 中的字号（精度 0.1pt）、颜色、间距参数
- 调整 \geometry 中的边距值（精度 0.1mm）
- 调整 \newcommand 字号定义中的 pt 值
- 如需换行对齐：微调 \XeTeXinterchartokenstate、字间距、或字号 ±0.1pt
保留老样式的稳定性：
- 不修改宏包加载顺序
- 不删除已有的自定义命令
- 不改变条件判断结构（如 \ifwindows）
增量添加新样式（如有必要）：
- 新增 \newcommand 而非修改现有命令
- 使用注释标记新增内容：% 新增样式注释

步骤 5：执行修改

修改 @config.tex（样式配置层）：
- 调整颜色定义
- 调整字号系统
- 调整标题格式（titlesec）
- 调整列表样式
- 调整页面设置（geometry）
修改 main.tex 中的标题文本（⚠️ 仅限标题，不触碰正文内容）：
- 更新章节标题以匹配 Word 模板
- 保持 LaTeX 结构（\section{}、\subsection{}）不变
- 仅修改花括号内的标题文字
- ⚠️ 绝不修改正文段落内容
保留原有结构：
- 不改变 \input{extraTex/xxx.tex} 的引用关系
- 不修改正文内容文件（extraTex/*.tex）
- 唯一例外：用户明确要求修改示例内容

AI 决策点 3：应用修改

工具: 使用 Edit 工具精确修改

流程:

使用 Read 工具读取 @config.tex
使用 Edit 工具应用每一处修改
保留原有注释和代码风格

验证:

# 检查编译是否成功
cd projects/{project}
xelatex -interaction=nonstopmode main.tex

步骤 6：验证与迭代（像素级验证）

编译检查：

cd projects/{project}
xelatex -interaction=nonstopmode main.tex

自动化验证（推荐）：
```
# 运行完整验证脚本（包括标题文字一致性检查）
cd skills/make_latex_model
./scripts/validate.sh
```
验证脚本会自动检查：
- ✅ 编译状态
- ✅ 版本号一致性
- ✅ 样式参数（行距、颜色、边距等）
- ✅ 标题文字一致性（新增，使用 compare_headings.py 自动对比）
像素级 PDF 对比验证：
- ⚠️ 必须使用 Word 导出的 PDF 作为基准（QuickLook 预览或其他工具的渲染与 Word 不同）
- 将 LaTeX 生成的 PDF 与 Word 打印的 PDF 叠加对比
- 检查每行的文字是否完全对齐
- 检查换行位置是否完全一致
- 使用工具：
  - Adobe Acrobat 的"比较文件"功能
  - 或手动叠加（将两个 PDF 导出为 PNG，使用图像编辑软件叠加）
  - 或使用脚本对比（如 pdftoppm + Pillow）
微调与迭代（最多 3 轮）：
- 如发现换行不一致：微调字号 ±0.1pt 或字间距
- 如发现位置偏移：微调边距或缩进 ±0.5pt
- 如发现标题文字不一致：根据 compare_headings.py 报告修改 main.tex 中的标题
- 每轮调整后重新编译验证
- 使用验证脚本：运行 ./scripts/validate.sh 自动检查各项指标
验收标准（优先级从高到低）：
- ✅ 第一优先级：编译无错误和警告
- ✅ 第二优先级：样式参数与 Word 模板一致（行距、字号、颜色、间距等）
- ✅ 第二优先级：标题文字与 Word 模板完全一致
- ✅ 第三优先级：视觉上与 Word PDF 高度相似（考虑到字体渲染差异，允许轻微差异）
- ⚠️ 第四优先级：像素对比指标（仅作为辅助验证，非硬性要求）

AI 决策点 4：验证结果是否达标？

输入:

修改前的验证报告（如存在）
修改后的验证报告（run_validators.py 输出）

判断逻辑:

# 伪代码
优先级1_通过 = 编译成功 and 无警告
优先级2_通过 = 样式参数一致 and 标题文字一致

if 优先级1_通过 and 优先级2_通过:
    返回 "完成"
elif 失败项减少:
    返回 "方向正确，继续微调"
elif 失败项增加:
    返回 "回滚修改，重新分析"
else:
    返回 "保持现状，人工判断"

迭代策略:

最多执行 3 轮迭代
每轮只调整 1-2 个参数
记录每轮的修改和结果

迭代优化闭环

本步骤实现全自动的"优化-对比-调整"循环，推荐在需要精细调整时使用。

一键启动

# 全自动迭代优化
python3 skills/make_latex_model/scripts/enhanced_optimize.py \
  --project NSFC_Young \
  --max-iterations 10 \
  --report

脚本会自动完成：

预处理 main.tex（注释 \input{} 行）
生成可靠 Word PDF 基准
分析 PDF 样式参数
迭代优化循环（最多 10 轮）
恢复 main.tex
生成详细报告

预计耗时：5-15 分钟（取决于迭代轮数）

迭代循环逻辑

WHILE 未达到收敛条件:
  1. 编译 LaTeX 项目（xelatex -> bibtex -> xelatex -> xelatex）
  2. 执行像素级 PDF 对比（compare_pdf_pixels.py）
  3. 检测是否收敛（convergence_detector.py）
  4. IF 未收敛:
       - 分析差异特征（intelligent_adjust.py）
       - 生成参数调整方案
       - 应用调整到 @config.tex（需 AI 介入）
  5. 记录本轮指标
  6. 保存或回滚配置
END WHILE

收敛条件（优先级从高到低）

条件	阈值	说明
编译失败	-	立即停止，需人工修复
像素差异收敛	`changed_ratio < 0.03`	达到像素级对齐
连续无改善	3 轮	指标不再优化，收敛
最大迭代	10 轮	强制停止

智能参数调整策略

脚本 intelligent_adjust.py 根据差异特征自动推断参数调整：

差异特征	推断参数	调整策略
换行位置大面积差异	字间距/字号	±0.1pt
文本垂直偏移	行距	±0.05 倍
颜色不一致	RGB 值	±1
左右边距差异	geometry	±0.05cm
标题位置偏移	titleformat	调整 spacing

输出规范

修改摘要

将变更记录有机地追加到 projects/{project}/extraTex/@CHANGELOG.md：

记录原则：

自然流畅，避免生硬套用模板
重点说明“为什么改”（Word 模板的变化）和“改了什么”（具体参数）
保留历史追溯性，方便后续版本对比

记录内容：

修改的文件（仅 @config.tex）
修改前后的参数对比（如字号从 14pt → 15pt）
优化理由（基于 Word 模板的哪个特征变化）
验证结果（是否达到像素级对齐）

格式参考：

## [v1.0.1] - YYYY-MM-DD

### Changed（样式优化）
- **一级标题字号**：14pt → 15pt（Word 最新模板要求）
- **行距**：1.5 → 1.45（通过 PDF 叠加对比确定）
- **页边距**：调整上下边距为 2.54cm（与 Word 完全一致）

### Added（新增样式）
- 新增三级标题编号格式 1.1、1.2（Word 最新模板新增要求）

### Fixed（修复）
- 修复 MsBlue 颜色值误差（原 RGB 0,112,190 → 正确的 0,112,192）

代码变更

对 @config.tex 进行精确修改，保留：

原有注释
代码风格
条件判断结构（如 \ifwindows）
⚠️ 绝不触碰 main.tex

验证清单

📋 完整验证清单：参见第 6 节"验证清单（按优先级排序）"

快速验证（推荐）：

cd skills/make_latex_model
./scripts/validate.sh

这将自动检查：

✅ 编译状态
✅ 版本号一致性
✅ 样式参数（行距、颜色、边距等）
✅ 标题文字一致性（使用 compare_headings.py）

核心原则（底线）

绝对禁区

⚠️ 永不触碰 main.tex 中的正文段落内容

main.tex 中的 \input{extraTex/*.tex} 引用的正文内容文件
extraTex/*.tex 文件中的用户撰写内容
正文段落、表格、图片、公式等内容

✅ 允许修改 main.tex 中的标题文本

\section{标题文字} 中的标题文字
\subsection{标题文字} 中的标题文字
标题的编号格式、标点符号等
理由：标题的文本结构也是模板样式的一部分，需要与 Word 模板对齐

⚠️ 边界示例：

% ✅ 允许修改：标题文字
\section{{\bfseries（一）立项依据与研究内容}(建议8000字以内)：} % 修改为
\section{{\bfseries（一）研究依据与内容}(建议8000字以内)：}

% ❌ 禁止修改：正文内容
\input{extraTex/1.1.立项依据.tex}  % 不改变引用关系
% extraTex/1.1.立项依据.tex 中的具体内容不修改

轻量级修改优先

✅ 调整参数值（字号 pt 值、颜色 RGB 值、间距 em/cm 值）
✅ 新增自定义命令
❌ 删除或重命名现有命令
❌ 改变宏包加载顺序
❌ 重构条件判断结构

保真度与稳定性平衡

过度开发的风险：引入 bug、破坏已有功能、增加维护成本
开发不足的风险：样式不一致、不符合基金委要求
平衡策略：
- 默认使用 moderate 级别
- 仅在必要时使用 thorough 级别
- 保留老样式的核心架构

跨平台兼容性

保留 \ifwindows 条件判断
确保 Mac/Windows/Linux 都能正确编译
外挂字体路径保持不变（./fonts/）

验证清单（完成后自检，按优先级排序）

快速验证（推荐）

使用自动化验证脚本进行快速检查：

cd skills/make_latex_model
./scripts/validate.sh

这将自动检查：

✅ 编译状态
✅ 版本号一致性
✅ 样式参数（行距、颜色、边距等）
✅ 配置文件完整性

性能基准测试（可选）

运行性能基准测试,评估编译性能：

cd skills/make_latex_model
./scripts/benchmark.sh

这将输出：

⏱️ 平均编译时间
📄 PDF 文件大小
📊 性能报告 (JSON)

第一优先级：基础编译检查

编译检查：xelatex -> bibtex -> xelatex -> xelatex 无错误
跨平台：在至少两个操作系统上验证编译
向后兼容：老用户的内容文件（extraTex/*.tex）无需修改即可使用

第二优先级：样式参数一致性

行距：与 Word 模板一致（误差 < 0.1）
字号：与 Word 模板一致（误差 < 0.5pt）
颜色：与 Word 模板一致（RGB 误差 < 2）
边距：与 Word 模板一致（误差 < 0.5mm）
标题样式：缩进、间距、编号格式与 Word 一致
标题文字：与 Word 模板完全一致
- 一级标题文字完全匹配
- 二级标题文字完全匹配
- 标题编号格式、标点符号完全匹配

第三优先级：视觉相似度

视觉对比：PDF 与 Word 模板高度相似（考虑到字体渲染差异）
每行字数：与 Word 接近（允许 ±1 字差异）
换行位置：与 Word 大致对齐（考虑到断行算法差异）

第四优先级：像素对比（辅助验证）

像素对比（仅当使用 Word 打印 PDF 基准时）：
- 叠加对比 PDF 无明显偏移
- changed_ratio < 0.20（考虑到换行位置变化）
- 重点检查"每行字数"和"换行位置"对齐
⚠️ 如使用 QuickLook 基准，跳过像素对比

文档更新

文档更新：如有新增命令或配置，在 @config.tex 顶部添加注释说明

常见问题

Q1: 如何获取 Word PDF 基准？

A: 本技能支持用户已提供 PDF 或自动生成

方案 0：用户已提供 PDF（最快）

如果用户已经从 Word 模板导出了 PDF 文件，直接复制到工作空间即可：

# 复制用户提供的 PDF 到工作空间
cp /path/to/user/provided/word.pdf \
   skills/make_latex_model/workspace/{project}/baseline/word.pdf

要求：

PDF 必须是 Word/LibreOffice 导出的，不能用 QuickLook 预览
PDF 应包含完整的模板样式（标题、正文、列表等）

方案 1：LibreOffice 命令行自动转换（主推）

如果用户只有 Word 模板文件（.doc/.docx），使用 LibreOffice 自动转换：

# 一键生成 Word PDF 基准
python3 skills/make_latex_model/scripts/generate_baseline.py \
  --project NSFC_Young \
  --template-year 2025

脚本会自动完成：

定位 Word 模板文件
使用 LibreOffice 无头模式转换为 PDF
保存到工作空间
生成高分辨率 PNG 用于像素对比

环境准备：

# macOS
brew install --cask libreoffice poppler

# Ubuntu/Debian
sudo apt-get install libreoffice poppler-utils

方案 2：Microsoft Word COM 自动化（Windows 仅）

python3 skills/make_latex_model/scripts/generate_baseline.py \
  --project NSFC_Young \
  --template-year 2025 \
  --use-msword

渲染引擎对比

渲染引擎	精度	自动化程度	推荐度
用户已提供 PDF	取决于来源	零操作	⭐⭐⭐⭐⭐
LibreOffice	高（与 Word 99% 一致）	完全自动化	⭐⭐⭐⭐⭐
Microsoft Word COM	最高（100% Word 原生）	自动化（Windows 仅）	⭐⭐⭐⭐
QuickLook 预览	低（断行/行距有差异）	自动化但不准确	⚠️ 不推荐

为什么不用 QuickLook？

渲染引擎差异：QuickLook 预览渲染引擎与 Word 本质不同（行距、字体渲染、断行算法都有差异）
像素对比失真：使用 QuickLook 基准会导致正确的样式修改反而显示像素对比指标恶化
精确基准：只有 LibreOffice 或 Word 导出的 PDF 才能准确反映模板的真实样式

像素对比指标的陷阱

问题场景：修改行距从 1.8 倍 → 1.2 倍（更接近 Word 模板）

预期结果：像素对比指标应该改善（changed_ratio 降低）
实际结果：像素对比指标恶化（changed_ratio 从 0.1652 → 0.1829）

原因分析：

行距减小后，每页容纳更多文本
换行位置完全改变，导致大规模像素差异
如果基准是 QuickLook 预览（而非 LibreOffice/Word PDF），差异会更加放大

正确判断：

✅ 样式参数正确（行距 1.2 倍与 Word 一致）
✅ 视觉上更接近 Word 模板
⚠️ 像素对比指标恶化是副作用，不代表修改错误

行动建议：

优先使用用户提供的 PDF 或 LibreOffice/Word 生成的 PDF 作为基准
如果只能用 QuickLook，应降低像素对比指标的权重
以样式参数正确性和视觉相似度为主要验收标准

Q2: 修改后老用户的模板还能用吗？

A: 能。本技能仅修改样式定义（@config.tex），不改变内容文件的接口。

Q3: 如何判断优化是否"过度"？

A: 参考以下标准：

✅ 参数调优（如 14pt → 15pt）：合理
✅ 新增命令：合理
⚠️ 删除命令：需谨慎，确保无引用
❌ 重构核心架构：过度

Q4: Word 模板章节结构变化了怎么办？

样式配置层面：在 @config.tex 中添加必要的样式定义
内容层面：提示用户自己在 main.tex 或 extraTex/*.tex 中添加新章节
⚠️ 本技能不负责内容结构的调整，那是用户的责任

脚本	功能
`enhanced_optimize.py`	一键迭代优化入口
`prepare_main.py`	预处理/恢复 main.tex
`generate_baseline.py`	生成 Word PDF 基准
`convergence_detector.py`	收敛检测与报告
`intelligent_adjust.py`	智能参数调整建议

Install Skill

SKILL.md

NSFC LaTeX 模板高保真优化器

📋 文档目录

深度参考

核心目标

样式要素（必须完全一致）

⚠️ 关键 1：标题文字对齐

⚠️ 关键 2：每行字数对齐

执行模式说明

自动模式（硬编码脚本）

AI 规划模式（需要智能决策）

协作流程

工作空间说明

工作空间结构

路径管理

清理策略

触发条件

输入参数

执行流程

步骤 0：预检查（AI 必须首先执行）

AI 决策点 1：是否需要修改样式？

步骤 1：理解现状（深度阅读）

步骤 2：分析 Word 模板（像素级测量）

2.1 获取 Word PDF 基准

2.2 自动提取样式参数（推荐）

步骤 2.5：提取标题结构

步骤 3：差异分析与优化策略（像素级）

AI 决策点 2：生成修改方案

步骤 4：轻量级修改原则（像素级精度）

步骤 5：执行修改

AI 决策点 3：应用修改

步骤 6：验证与迭代（像素级验证）

AI 决策点 4：验证结果是否达标？

迭代优化闭环

一键启动

迭代循环逻辑

收敛条件（优先级从高到低）

智能参数调整策略

相关脚本

输出规范

修改摘要

代码变更

验证清单

核心原则（底线）

绝对禁区

轻量级修改优先

保真度与稳定性平衡

跨平台兼容性

验证清单（完成后自检，按优先级排序）

快速验证（推荐）

性能基准测试（可选）

第一优先级：基础编译检查

第二优先级：样式参数一致性

第三优先级：视觉相似度

第四优先级：像素对比（辅助验证）

文档更新

常见问题

Q1: 如何获取 Word PDF 基准？

方案 0：用户已提供 PDF（最快）

方案 1：LibreOffice 命令行自动转换（主推）

方案 2：Microsoft Word COM 自动化（Windows 仅）

渲染引擎对比

为什么不用 QuickLook？

像素对比指标的陷阱

Q2: 修改后老用户的模板还能用吗？

Q3: 如何判断优化是否"过度"？

Q4: Word 模板章节结构变化了怎么办？