Thu Thesis

清华 MBA 论文 Word → PDF 一键转换

⚠️ 核心操作原则（不得违反）

只从 Word 中提取信息，不修改 thuthesis 模板格式。

• thuthesis 的封面、页眉、目录、参考文献、图表样式等，全部由 thuthesis.cls 自动生成
• 脚本只负责把 Word 里的内容（标题、摘要、章节、图表、参考文献等）提取出来填入 .tex 文件
• 若 Word 中某字段缺失，对应 LaTeX 字段留空，不删除、不跳过、不用占位符替代
• 任何格式上的"改进"都必须以 assets/databk/ 中的官方示例为准，不得自行发挥

架构：新三层 AI-native 流程

Word 文件
  ↓ [extract_raw.py]  纯机械提取，无 LLM
raw_xxx.json + 文档骨架（段落 idx + 样式 + 文字）
  ↓ [我（AI）阅读骨架]  理解章节结构
struct_xxx.json（章节划分、段落 idx 映射）
  ↓ [build_parsed.py]  纯 Python 组装，无 LLM
parsed_xxx.json
  ↓ [render.py]        填充 thuthesis LaTeX 模板
LaTeX 项目目录
  ↓ [xelatex + bibtex] 编译
thesis.pdf ✅
  ↓ [我（AI）Rubric 评测]  阅读产物，逐项打分 + 自动修复
evaluation_report.md

关键设计原则：Python 脚本不调用任何 LLM，不持有 API key。AI 在两个关键环节介入：(1) 阅读骨架生成 struct.json；(2) Rubric 评测 + 自动修复。

依赖

pip3 install python-docx jinja2 matplotlib
# 需要已安装 TeX Live

格式参考：assets/databk/

assets/databk/ 是从官方 thuthesis 项目备份的原始示例 data 文件，是本工具一切格式决策的黄金标准：

遇到任何格式问题，先查 databk/ 里的对应文件，再动代码。

初次使用 / 更新格式参考

# SKILL_DIR = 本 skill 的根目录（thu-thesis/）
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"   # 在 scripts/ 内执行时
# 或直接写绝对路径，例如：
# SKILL_DIR="/path/to/skills/thu-thesis"
bash "$SKILL_DIR/scripts/setup.sh" "$SKILL_DIR"

setup.sh 做三件事：

1. 从 GitHub clone（首次）或 git pull（已有）最新 thuthesis 到 /tmp/thuthesis-latest
2. 编译生成 thuthesis.cls（如尚未生成）
3. rm -rf assets/databk/ && cp -r data/ assets/databk/ → 保持格式参考始终为最新版本

每次 thuthesis 版本有重大更新时，重跑 setup.sh 即可刷新 databk。

输出路径规范

LaTeX 工程输出位置：与输入 .docx 同目录，子文件夹命名为 <原文件名去扩展>-latex。

例如：输入 /path/to/foo.docx，则 LaTeX 工程输出到 /path/to/foo-latex/。

• 中间临时文件（raw/struct/parsed JSON）放在 workspace 临时目录，转换完成后可清理
• 最终交付给用户的是 -latex/ 目录（含 thesis.pdf）

完整转换流程

Step 1：机械提取（同时创建 LaTeX 工程目录）

# SKILL_DIR = 本 skill 根目录，按实际安装路径设置
SKILL_DIR="/path/to/skills/thu-thesis"

python3 "$SKILL_DIR/scripts/convert.py" extract /path/to/论文.docx output/

extract 会立即做两件事：

1. 在 .docx 同目录创建 <stem>-latex/ 工程目录（项目开始即确定输出位置）
2. 机械提取，输出 output/raw_xxx.json + 终端骨架

终端输出示例：

📄 输入: /path/to/foo.docx
📁 中间文件: output/
📁 LaTeX 工程: /path/to/foo-latex/      ← 已创建
📊 图片: 5 张  | para_idx: [102, 115, ...]
📊 表格: 3 张  | before_para: [88, 134, ...]

Step 2：AI 阅读骨架，生成 struct.json

AI（我）读取骨架，识别：

• 摘要范围（abstract_cn_range, abstract_en_range）
• 各章节标题段落 idx（title_para）、正文范围（content_range）
• 各级小节（sections）的 idx 和编号
• 参考文献、致谢、简历的范围

如何输出：使用 Write 工具，把 struct.json 写到与 raw_xxx.json 同一目录，命名为 struct_<论文标题>.json（与 raw 文件保持同级）：

output/
  raw_论文标题.json      ← Step 1 生成
  struct_论文标题.json   ← AI 用 Write 工具写到这里  ✅
  figures/               ← Step 1 提取的图片

写入前必须检查（防图表丢失）：

1. 列出 raw_xxx.json 中所有图片的 para_idx → 确保每个都落在某章 content_range 内
2. 列出所有表格的 before_para → 确保都 ≥ 第一章 content_range[0] 且在某章范围内
3. 相邻章节 content_range 不能有间隙

输出 struct_xxx.json，格式：

{
  "cover": {
    "abstract_cn_range": [27, 31],
    "abstract_en_range": [35, 44],
    "keywords_cn_para": 31,
    "keywords_en_para": 44
  },
  "chapters": [
    {
      "number": "第1章",
      "title": "引言",
      "title_para": 109,
      "content_range": [110, 142],
      "sections": [
        {"level": 2, "number": "1.1", "title": "选题背景", "title_para": 110},
        {"level": 3, "number": "1.1.1", "title": "子节标题", "title_para": 115}
      ]
    }
  ],
  "references_range": [388, 409],
  "acknowledgements_range": [412, 412],
  "resume_range": [423, 428]
}

Step 3-5：组装、渲染、编译

Step 1 已经创建好 LaTeX 工程目录，直接指向它：

SKILL_DIR="/path/to/skills/thu-thesis"
DOCX="/path/to/foo.docx"

python3 "$SKILL_DIR/scripts/convert.py" build \
  output/raw_foo.json \
  output/struct_foo.json \
  "$(dirname "$DOCX")/foo-latex"

自动完成：

• build_parsed.py：raw + struct → parsed JSON（含表格、图片正确插入）
• render.py：parsed JSON → LaTeX 项目
• xelatex + bibtex：编译 PDF（3~4 次，保证目录稳定）

Step 6：AI Rubric 评测 + 自动修复

编译完成后，我（AI）逐项检查转换质量，详见下方「Rubric 评测细则」。可自动修复的问题直接修复并重新编译，最多 3 轮；不可修复的问题在报告中标注。最终输出 evaluation_report.md 到 LaTeX 工程目录。

文件说明

Rubric 评测细则（AI 执行）

评测由 AI 直接完成，不使用 Python 脚本。 AI 阅读生成产物（parsed JSON、.tex 文件、refs.bib、thesis.log、thesis.pdf），按下方 Rubric 逐项打分，可修复问题直接修改后重新编译（最多 3 轮），最终输出 evaluation_report.md。

评测流程

1. 读取产物：parsed_xxx.json、data/*.tex、ref/refs.bib、thesis.log、thesis.pdf（检查是否存在及大小）
2. 逐项评分：按下方 38 项 Rubric 逐一检查，给出 PASS / WARN / FAIL + 原因
3. 自动修复：对可修复的 FAIL/WARN 项直接修改 .tex 文件，然后重新 xelatex + bibtex 编译（最多 3 轮）
4. 输出报告：生成 evaluation_report.md，含总分、维度得分、所有扣分项明细

评分制度

评级标准：总分/满分 → 优秀≥90% / 良好≥75% / 合格≥60% / 不合格<60%

可自动修复 vs 不可修复

Rubric 明细（38项，满分 90 分）

A. 元信息（11项）

B. 正文（5项）

C. 参考文献（7项）

D. 图片（4项）

E. 表格（4项）

F. 缩略语（2项）

G. 附件（2项）

H. 编译（3项）

报告格式

评测报告 evaluation_report.md 须包含：

1. 总分：XX / 90 分（XX%）— 评级
2. 维度得分表：每个维度（A~H）的得分/满分/得分率
3. 扣分明细：所有 FAIL / WARN 项列出 ID、检查项、扣分原因（不截断）
4. C6 抽检样本：随机抽取的 cite 关联性样本（文献信息 + 上下文），供人工核查
5. 完整明细表：38 项逐一列出 ID、类型、满分、得分、说明

参考文献处理

• Word 原文参考文献列表 → ref/refs.bib（自动解析为 BibTeX）
• 正文 [10] → \cite{key}，支持 [1,2,3] 和 [1-3]
• Author-year 行文引用自动补 \cite：
  • 曹玉（2025）分析了... → 曹玉（2025）\cite{cao2025aigc}分析了...
  • 支持中文全角 （年）、英文半角 (年)
  • 匹配失败时保留原文，rubric C7 会警告
• 未被引用文献：关键词匹配补 \cite；无匹配用 \nocite 兜底

图片和表格处理全链路

图表丢失是最常见的转换问题。 根本原因几乎总是 Step 2（AI 生成 struct.json）时 content_range 设定不准，导致图表所在段落被排除在章节范围之外。

完整流程

Step 1  extract_raw.py
  ├── 图片：扫描段落 XML 的 a:blip（普通图）/ c:chart（图表对象）
  │         记录 {filename, para_idx}，文件存入 output/figures/
  └── 表格：扫描 body 元素顺序，记录 {rows, before_para}
            before_para = 表格紧跟在哪个段落之后的 idx

Step 2  AI 生成 struct.json
  └── ⚠️ 关键：content_range 必须覆盖图表所在的 para_idx！

Step 3  build_parsed.py
  ├── 图片分配：figures_by_para[para_idx] → 章节的 content_range 内 → 插入
  │   caption 检测：图片 para_idx 后 0-2 段内匹配 ^图\s*\d
  ├── 表格分配：before_para 落在 content_range 内 → 插入
  │   before_para < first_chap_start → 跳过（封面/目录页表格）
  │   before_para 不在任何章节范围 → 分配给最近章节末尾（extra_tables）
  │   caption 检测：before_para 后 0-2 段内匹配 ^表\s*\d
  └── figures/ 目录拷贝至 output_dir/figures/

Step 4  render.py
  ├── 图片：type=figure → \begin{figure}...\includegraphics{figures/xxx}\caption{}\end{figure}
  │   SVG 跳过并警告；\caption 自动去掉"图X-X "前缀（thuthesis 自动编号）
  ├── 表格：type=table → render_table() 生成三线表 raw_latex 块
  │   列宽：内容≤12字符宽 → l；>12字符 → X；至少一列为 X
  │   \caption 自动去掉"表X-X "前缀；\caption 在表格上方
  └── 扫描生成的 .tex：有 \begin{figure} → 加 \listoffigures；有 \begin{table} → 加 \listoftables

⚠️ 图表丢失的常见原因及修复

原因 1（最常见）：struct.json 的 content_range 设定偏窄，图表 para_idx 在范围外

排查方法：检查 raw_xxx.json 中图片/表格的 para_idx / before_para，与 struct.json 的 content_range 对比：

import json
raw = json.load(open('output/raw_xxx.json'))
print("图片 para_idx:", [(f['filename'], f['para_idx']) for f in raw['figures']])
print("表格 before_para:", [(t['idx'], t['before_para']) for t in raw['tables']])

修复：重新生成 struct.json，确保每章 content_range[1]（结束 idx）足够大，覆盖该章所有图表段落，然后重跑 build 命令。

原因 2：图片/表格出现在章节之间的"间隙"段落

两章 content_range 之间可能有空隙（如过渡段落 idx 130-135 不在任何章节范围内）。build_parsed.py 会把这些表格用 extra_tables 附到最近章节末尾，但图片无此兜底，直接丢失。

修复：struct.json 相邻章节的 content_range 不能有间隙，确保：

第1章 content_range[1] + 1 ≥ 第2章 content_range[0]

原因 3：图片的 para_idx 为 0 或 None

Word 中图片有时嵌在空段落、文本框或表格单元格中，导致 extract_raw.py 无法找到对应段落。此时 para_idx=0，图片会被分配到第 0 段落，不在任何章节 content_range 内，丢失。

排查：raw_xxx.json 中 figures 里 para_idx=0 且文档实际有图的，属于此类。

修复：在 struct.json 中找到该图片实际所在的段落（根据骨架文本目视定位），手动在对应章节的 content_range 里调整，或在 parsed_xxx.json 中手动插入 figure 块后重跑 render。

原因 4：caption 未被识别（图/表无编号）

caption 检测依赖 ^图\s*\d / ^表\s*\d 正则：

• Word 中 caption 写法是 图1-1 标题 → 可识别
• 写法是 图一 标题（中文数字）、Figure 1 或 caption 与图片不在相邻段落 → 识别失败，caption 为空

caption 为空不影响图表出现在 PDF，但插图清单/附表清单会不完整（D4/E4 WARN）。

AI 在 Step 2 生成 struct.json 的图表注意事项

生成 struct.json 时必须执行以下检查，否则极可能导致图表丢失：

1. 对照 raw_xxx.json 的图片 para_idx 列表，确认每张图的 para_idx 都落在某章的 content_range 内
2. 对照表格的 before_para 列表，确认每个 before_para 都 ≥ first_chap_start（第一章 content_range[0]）且落在某章范围内
3. 相邻章节的 content_range 不能有间隙，末尾章节的 content_range[1] 要覆盖到参考文献段之前

表格格式（三线表）

\begin{table}[htbp]
  \caption{表题}
  \begin{tabularx}{\linewidth}{l X}
    \toprule
    短列头 & 长文本列头 \\
    \midrule
    内容1 & 内容2 \\
    \bottomrule
  \end{tabularx}
\end{table}

• 无竖线，三线（\toprule / \midrule / \bottomrule）
• 短列（≤12字符宽）用 l，长文本列用 X；至少一列为 X
• \caption 在 \begin{tabularx} 上方（thuthesis 规范：表题在上）
• render.py 自动去掉 caption 里的"表X-X "前缀，由 thuthesis 自动编号

图片格式

\begin{figure}[htbp]
  \centering
  \includegraphics[width=0.9\linewidth]{figures/image1.png}
  \caption{图题}
  \label{fig:xxx}
\end{figure}

• 图片文件放在 LaTeX 工程的 figures/ 目录
• render.py 自动去掉 caption 里的"图X-X "前缀，由 thuthesis 自动编号
• SVG 跳过，需手动转 PNG/PDF 后补入
• chart 对象（Excel 图表）由 matplotlib 重绘为 PNG，自动纳入流程

已知限制

• SVG 图片跳过（需手动转为 PNG/PDF 后补入）
• committee.tex / comments.tex / resolution.tex 为占位，需手工填写（答辩后）

⚠️ .doc 格式必须用 Word 转换，不能用 textutil

唯一可靠方法：用 Microsoft Word 打开 .doc 文件，另存为 .docx。

macOS textutil、Python docx2txt 等工具会把表格压平为普通段落，导致：

• extract 步骤报告"0 表格"
• 表格数据变成一行行普通文字进入正文
• 图片和封面元信息也可能丢失

判断转换是否正确的方法：运行 extract 后，看终端输出的"📊 表格 X 张"行：

如果没有 Word，可在 macOS 用 LibreOffice（需安装）：

soffice --headless --convert-to docx /path/to/论文.doc --outdir /path/to/

LibreOffice 保留表格结构，textutil 不保留。

thuthesis 配置（MBA 专业硕士）

\thusetup{
  degree = {master},
  degree-type = {professional},
  degree-category = {工商管理硕士},
  degree-category* = {Master of Business Administration},
  department = {经济管理学院},
}