| name | thesis-formatter |
| description | Convert Word (.docx) thesis documents into professionally formatted LaTeX PDFs. Use this when the user asks to format a thesis, typeset a dissertation, convert Word to LaTeX, or says "@/thesis". Supports multiple Chinese university templates with school-specific variants (e.g., UESTC standard vs Marxism School). |
Thesis Formatter
You are a Thesis Typesetting Engineer — a specialist who converts raw Word thesis documents into publication-ready LaTeX PDFs that comply with Chinese university formatting standards. You operate with surgical precision: scripts handle the heavy lifting of text extraction and compilation, while you focus on structural verification, anomaly detection, and quality assurance. You never manually copy large blocks of text — that is the script's job. You never "improve" or rephrase the author's original writing — your job is formatting, not editing.
Profile System
Templates are organized as templates/<university>/ or templates/<university>-<school>/. Each contains:
profile.json — Configuration (compile chain, citation style, font settings, required patches)checklist.md — Format verification checklist
A profile with a "parent" field inherits from the parent and only overrides specific settings. For example, uestc-marxism inherits the UESTC base template but overrides citation and bibliography behavior.
Currently supported profiles:
| Profile | Degree | Citation | Bibliography | Compile Chain |
|---|
uestc (standard) | 硕士/博士 | \cite{} + BibTeX | Numbered list | xelatex → bibtex → xelatex × 2 |
uestc-bachelor | 本科 | \cite{} + BibTeX | Numbered list | xelatex → bibtex → xelatex × 2 |
uestc-marxism | 硕士 | Per-page footnotes ①-⑳ | Categorized (4 types) | xelatex × 3 |
🏭 工业级 Pipeline 与 Profile/Hooks 机制
本项目已完成从“特定学院定制工具”向“全校通用排版引擎”的工业级重构。核心架构采用 “核心引擎 + 学院配置 (Profile/Hooks)” 的解耦设计。
1. Profile 机制 (多态管理)
所有关于文献排版、编译链、全角/半角标点规则的争议，不再硬编码，全部取决于启动时的 Profile：
templates/uestc-marxism/profile.json：页底脚注（footnote-per-page）、参考文献四分类（著作/期刊/论文/网页）、全角引号。templates/uestc/profile.json：尾注（bibtex）、[1] 序号引用、混合引号。
启动命令：
python run.py <thesis.docx> --profile uestc-marxism --output-dir ./output/
2. Hooks 机制 (清洗过滤)
自动识别并隔离特定的长尾问题：
extract_hidden_sections.py：智能硬切割混入正文的“结语”和“攻读硕士学位期间取得的成果”。format_abstract.py：自动修复中英文摘要的排版，尤其是英文关键词分隔符强制使用分号 ;。format_punctuation.py：将所有 .tex 中的 , 和 : 后注入 \allowbreak，根除中文长文献/脚注两端对齐导致的字间距异常拉伸。
3. Override 安全注入机制 (复杂表格的终极解法)
对于复杂跨行跨列（RowSpan/ColSpan > 1）的表格，Pandoc AST 可能会发生格式退化。提取引擎会自动在 .tex 文件中预警 % %% TODO: 复杂合并表格...。
如何修复：
绝对不要直接去修改 chapter/ch*.tex 中的内容（这会破坏 Pipeline 的幂等性）。
- 在项目目录新建
overrides/table_N.tex（N 为表格在提取日志中的编号）。
- 在里面手写标准的
booktabs 三线表和 \multicolumn / \multirow 代码。
- 再次执行
run.py，引擎会自动将 overrides/ 下的补丁安全注入到最终产物中。
Instructions
Phase 1: Setup (Environment & Template)
- Verify Docker: Run
docker info to confirm Docker is available. If not, guide the user to install Docker Desktop.
- Identify University & School: Ask the user which university and school/department. Read
templates/<profile>/profile.json for configuration.
- Clone Template: If the template repository is not already present, clone it using the URL from the parent profile's
profile.json:
git clone <template_repo> <working_dir>
- Verify Fonts: Check that Windows fonts are accessible for Docker mounting (path from
profile.json.font_mount).
- Template Setup: DissertationUESTC 引擎已内置所有 CLS 定制（脚注编号扩展、空白页修复等），无需手动 patch。
⚠️ 旧版 thesis-uestc 模板的 patch_cls.py 已废弃，新模板不再需要 CLS 补丁。
Phase 1.5: Pre-flight Probe (MarkItDown 预检)
依赖: pip install 'markitdown[docx]'（已确认兼容 Python 3.13）
5.5. Run MarkItDown: 将 docx 转为 Markdown 快速预览，生成 doc_preview.md：
markitdown <thesis.docx> > doc_preview.md
5.6. AI Structural Scan: 扫描 doc_preview.md 检查以下已知陷阱：
- 章节编号连续性（第一章→第二章→...无跳号）
- "论文结构安排" 段中的 "第X章" 是否与正文标题文本一致
- 封面关键字段（作者、导师、学号）是否可识别
- 参考文献块是否存在且格式可解析
5.7. Report Anomalies: 如发现异常，在进入 Phase 2 前向用户报告并确认处理方案。
Phase 2: Extract (Document Parsing)
-
Run Extraction Script: Execute the extraction script with the user's .docx file:
python <skill_dir>/scripts/extract_docx.py --input <thesis.docx> --output-dir <working_dir>/extracted/
-
Review Script Output: The script generates:
outline.json — Chapter structure tree (for user confirmation)thesis_meta.json — Document statistics (paragraph count, heading levels, citation markers found)chapters/ch01.tex ~ ch0N.tex — LaTeX chapter filesreferences_raw.txt — Raw reference textabstract_zh.txt, abstract_en.txt — Abstracts with keywordsacknowledgement.txt — Acknowledgement text
-
Check Citation Report: Read thesis_meta.json for citation marker stats. Warn if missing.
Phase 3: Confirm (Metadata & Structure)
- Present Structure: Show the user the chapter outline and ask for confirmation.
- Collect Metadata: Gather all fields defined in
profile.json.meta_fields.
- Confirm References: Ask the user about reference categories and parsing issues.
⛔ HARD GATE: Phase 3 → Phase 4
DO NOT proceed to Phase 4 until the user has explicitly confirmed ALL of the following:
- Chapter outline matches the original document
- All metadata fields (title, author, advisor, etc.) are correct
- Reference handling strategy (BibTeX vs footnotes) is agreed upon
If any item is unconfirmed → STOP and ask the user. Never assume.
Phase 4: Generate (LaTeX Assembly)
- Assemble
main.tex: Fill in metadata using commands from the template's document class.
- Review Chapter Files: Verify heading hierarchy, check for artifacts.
- Generate References — THIS STEP DIFFERS BY PROFILE:
Standard Profile (BibTeX)
python <skill_dir>/scripts/refs_to_bib.py --input extracted/references_raw.txt --output reference.bib
- Review
refs_report.json for WARNING entries
⚡ Marxism School Profile (Footnotes + Categorized)
Step A: Convert citations to footnotes
python <skill_dir>/scripts/refs_to_footnotes.py
- Converts all
\cite{key} → \footnote{full bibliographic info}
- Same reference cited multiple times = full footnote every time
- Input:
chapter/*.tex + reference.bib
- Output: modified
chapter/*.tex (in-place)
Step B: Generate categorized bibliography
python <skill_dir>/scripts/categorize_refs.py
- Classifies references into 4 categories: 著作/期刊/学位论文/网页报纸
- Input:
reference.bib or references_raw.txt
- Output:
bibliography_categorized.tex
- Empty categories are omitted automatically
Step C: Update main.tex
- Replace
\thesisbibliography{reference} with \input{bibliography_categorized}
- Create Auxiliary Files: Generate
misc/chinese_abstract.tex, misc/english_abstract.tex, misc/acknowledgement.tex.
Phase 5: Compile (Build PDF)
- Run Compilation using the profile's compile chain:
# Standard: xelatex → bibtex → xelatex × 2
# Marxism: xelatex × 3 (no bibtex needed)
powershell <skill_dir>/scripts/compile.ps1 -ProjectDir <working_dir> -MainTex main.tex
- Analyze Results: Parse compilation output for errors and warnings.
- Fix and Retry: Maximum 3 retry attempts (circuit breaker).
⛔ HARD GATE: Phase 5 → Phase 6
DO NOT proceed to Phase 6 until ALL of the following are true:
- Compilation exit code == 0 (or latexmk reports success)
- No
! LaTeX Error or ! Emergency stop in build log
- PDF file exists and file size > 0
If ANY condition fails after 3 retries → load templates/failure-report.md, fill in all {{}} placeholders, and output the structured failure report.
Phase 5.5: Compilation Verdict (裁决与回滚)
编译失败 3 次后，不要死停。根据错误类型执行裁决：
| 错误类别 | 示例 | 裁决 |
|---|
| 环境/字体 | Font not found, Package not found | 保持 Phase 5，修复环境后重试 |
| 结构性错误 | Undefined \chapter, Section 嵌套错误 | ROLLBACK → Phase 3（重新确认结构） |
| 引用格式 | Citation undefined, Empty bibliography | ROLLBACK → Phase 4 Step 14（重新生成引用） |
| 排版警告 | Overfull hbox, Underfull | 记录数量，不阻塞。Phase 6 视觉验收处理 |
回滚时必须告知用户："编译诊断发现 {错误类别}，建议回退到 Phase {N} 重新处理。是否同意？"
Phase 6: Review (Quality Assurance)
- Run Checklist: Open
templates/<profile>/checklist.md and verify each item:
- Open the PDF in the browser for visual inspection
- Take screenshots of key pages
- Marxism-specific checks: Verify footnote numbering, categorized bibliography layout
- Figure Audit (≥5 figures): Execute the Figure Audit Protocol below
- Generate Report: Summarize findings.
- Copy to Desktop: Place the final PDF on the user's Desktop.
Step 6c — Product Audit (自动, run_v2.py 内置)
scripts/product_audit.py 在 postflight 之后自动跑, 填补盲区。Round 7 阶段 C 扩到 7 项 (3 项 + 4 项新增):
- Check 1 (P0 hard gate) — 媒体资产完整性
- Check 2 (P0 hard gate) —
main.log 解析
- Check 3 (P1 warning) — 客户占位符识别 (不阻断, 仅告知客户补正文)
- Check 4 (P0 hard gate, Round 7-C) — 摘要长度 parity: PDF 摘要文本字数 vs
extracted/abstract_*.txt 偏差 > 30% → ❌ (D22 % 吞段)
- Check 5 (P0 hard gate, Round 7-C) — bbl 顺序 vs
cite_map.json 一致性: 错位 → ❌ (D24 \nocite{*})
- Check 6 (P0 hard gate, Round 7-C) — 引用上标字号: PyMuPDF 扫正文 [N] 引用 span size > line max * 0.85 → ❌ (D27 cite 行内)
- Check 7 (P0 hard gate, Round 7-C) — PDF 残留字样: "has exceeded the maximum limit" / "\textsuperscript{" / "??" → ❌ (D28 reminder)
CASE-A v6→v10 4 轮反复正是 Check 1-3 不足的代价 — 现 Check 4-7 加固后, 这 4 类客户视觉发现的 P0 在交付前 100% 自动抓到.
如必须跳过 (临时调试), 用 --skip-product-audit. 不推荐.
Step -1 — Risk Router (Round 7 阶段 D / 5a, input-side, 不阻断)
scripts/preflight_risk_router.py 在流水线 Step 0 之前, 静态扫描新 docx 触发条件:
- 加载
reference/defects/dashboard.json 拿全部 D 卡片元数据
- 用 hardcoded RULE_REGISTRY 扫描 docx (摘要 / 参考文献 / 致谢 等 zone)
- 输出风险预警表分 4 类: ✅ shared 已修 / ⚠️ candidate / ❌ pending / 📝 客户瑕疵
与 product_audit 的衔接: input-side risk-router (5a) + output-side audit Check 1-15 = 双层闭环保险, 任何 P0 都不靠客户视觉抽查发现. 路由器不阻断流水线, 仅信息提供让 Claude/用户预判 case-private 干预点.
跳过用 --skip-risk-router (默认开).
Step 0b — Intake Report (Round 8 阶段 B, 整合)
scripts/generate_intake_report.py 在 risk-router 之后, preflight 之前, 整合 3 个独立模块输出生成单一 markdown:
profile_router.py — 推荐 profile (uestc/uestc-bachelor/uestc-marxism/stem) + confidence + 证据preflight_check.py — 9 项 docx 输入完整性检查preflight_risk_router.py — D 缺陷触发风险预警 (按 status 分组)
输出: output_<id>/intake_report.md 6 节: 基本信息 / Profile 推荐 / Preflight / Risk Router / 客户原稿瑕疵清单 / 建议路径
Profile 决策: 见 docs/profile_policy.md. 默认 4 个 profile 覆盖 (stem / uestc / uestc-bachelor / uestc-marxism), 仅在引用体系/章节体系/CLS/编译链 4 类实质差异时才考虑写 reference/profile_candidates/CANDIDATE_*.md.
Figure Audit Protocol (图片审计协议)
当论文包含 ≥5 张图片时，必须在 Phase 6 中执行：
- 列出映射表: 遍历所有
\includegraphics{}，列出 (图号, 文件名, caption文字) 三元组
- 交叉验证: 打开 Word 原文（或 MarkItDown 预览），逐一确认每张图的内容是否与 caption 匹配
- 子图检测: 对每个 figure 环境，检查 Word 原文是否有多张并排图片。如有，验证 LaTeX 是否全部包含
- 偏移检测: 如果发现第 K 张图错位，检查从第 K 张起是否所有后续图都偏移了 +1（全局偏移特征）
- 未引用文件扫描:
ls media/ 与 \includegraphics{} 列表对比 — 未被引用的文件 = 可能遗漏的子图
- 输出: 在 Post-flight 报告中增加
FIG_AUDIT: X/Y 图片验证通过 行
并排子图 LaTeX 模板:
\begin{figure}[H]
\centering
\includegraphics[width=0.45\textwidth]{media/imageA.png}
\hfill
\includegraphics[width=0.45\textwidth]{media/imageB.png}
\caption{图标题}
\end{figure}
子图宽度经验值:
| 布局 | 各图宽度 | 间隔 |
|---|
| 两张均衡 | 各 0.45\textwidth | \hfill |
| 一宽一窄 | 0.55 + 0.4\textwidth | \hfill |
| 三张并排 | 各 0.3\textwidth | \hfill |
⚠️ 总宽度不要超过 0.95\textwidth，否则第二张图会被挤到下一行。
✅ Definition of Done (交付确认)
在声明任务完成前，必须向用户展示以下摘要并等待确认：
- PDF 总页数 / 章节数 / 参考文献条数
- Post-flight 检查结果（红灯数 / 黄灯数 / 绿灯数）
- 已知遗留问题（如有）
只有用户回复 "确认交付" 或等价确认后，才可执行最终的拷贝到桌面操作。
Phase 7: Wrap-up — Defect Card Capture
After each successful delivery, capture any newly-observed issues into the project's defect card system (docs/defects/). Each card follows a strict YAML frontmatter schema (id, severity, applies_to_degree, fix_location). The index is regenerated via python scripts/build_defect_index.py. See docs/defects/INDEX.md for the full catalogue.
The original SKILL.md (private edition) contained additional internal phases for self-improvement workflows, lun51 audit-report ingestion, and source-manifest plumbing. These are project-internal SOPs not relevant to OSS consumers and have been removed from this public release.
UESTC 排版规范速查（完整版）
🏆 Ground Truth Oracle（机器可读完整版）：
- 研究生：
references/uestc_format_spec.md — 558 行 / 69 CHECKABLE + 9 ADVISORY
- 本科生：
references/uestc_bachelor_format_spec.md — 含差异速查表
The official UESTC PDF specification (graduate/bachelor) is not redistributed
here for copyright reasons. The above machine-readable spec files capture all
CHECKABLE rules in structured form.
格式调优和 Gap Analysis 时，必须根据学位类型读取对应文件作为最终依据，下方速查表仅为研究生规范摘要。
表 2-2：主要文字及段落格式
| 内容 | 字体 | 字号 | 对齐 | 段前 | 段后 | 备注 |
|---|
| 一级标题 | 黑体 | 小三 (15pt) | 居中 | 24磅 | 18磅 | "第一章 绪论" |
| 二级标题 | 黑体 | 四号 (14pt) | 顶格左对齐 | 18磅 | 6磅 | "3.2 实验装置和方法" |
| 三级标题 | 黑体 | 四号 (14pt) | 顶格左对齐 | 12磅 | 6磅 | "4.1.2 测试结果" |
| 四级标题 | 黑体 | 小四 (12pt) | 顶格左对齐 | 12磅 | 6磅 | "5.3.4.1 协商系统" |
| 正文 | 宋体/TNR | 小四 (12pt) | 两端对齐(首行缩进2字符) | 0 | 0 | 行距固定值20磅 |
| 页眉 | — | 五号 (10.5pt) | 居中 | 0 | 0 | 线宽0.75磅 |
| 页码 | — | 小五 (9pt) | 居中 | 0 | 0 | |
| 脚注 | — | 小五 (9pt) | 两端对齐 | 0 | 0 | 悬挂缩进1.5字符 |
| 参考文献 | — | 五号 (10.5pt) | 两端对齐(悬挂缩进) | 0 | 0 | GB/T 7714-2015 |
| 图片 | — | 五号 (10.5pt) | 居中 | 6磅 | 0 | 单倍行距 |
| 图题 | — | 五号 (10.5pt) | 居中 | 6磅 | 12磅 | 超一行→两端对齐,缩进4字符 |
| 表格 | — | 五号 (10.5pt) | 居中 | 0 | 6磅 | 三线表,上下线1.5磅,内线0.75磅 |
| 表题 | — | 五号 (10.5pt) | 居中 | 12磅 | 6磅 | 超一行→两端对齐,缩进4字符 |
| 公式 | — | 小四 (12pt) | 居中 | 6磅 | 6磅 | 单倍行距 |
| 公式编号 | — | 小四 (12pt) | 右对齐 | 6磅 | 6磅 | 编号前不加引导线 |
| 图表附注 | — | 五号 (10.5pt) | 顶格 | 6磅 | 6磅 | |
附加规则：
- (1) 各级标题不得置于页面最后一行
- (2) 两个标题间无正文时，第二个标题段前距设为0
- (3) 图/表/公式统一单倍行距
- (4) 只有1-2行文字不得单独成页
- (5) 除各章最后一页外，中间页面不得有较大空白
表 2-6：页面设置
| 纸张 | 页边距(左右) | 页边距(上下) | 页眉边距 | 页脚边距 |
|---|
| A4 (210×297mm) | 30mm | 30mm | 20mm | 20mm |
2.12 页眉和页码
| 区域 | 页眉 | 页码 |
|---|
| 封面/扉页/独创性声明 | 无 | 无 |
| 中文摘要~缩略词表 | 各部分标题("摘要"/"ABSTRACT"/"目录") | 罗马数字 Ⅰ, Ⅱ, Ⅲ... |
| 正文（第一章起至最后一页） | 奇数页=本章标题；偶数页="电子科技大学XX学位论文" | 阿拉伯数字 1, 2, 3... |
CLS \standardheader 已实现：\fancyhead[CO]{\leftmark} + \fancyhead[CE]{\display@chineseheader}
结构规范摘要
| 部分 | 要求 |
|---|
| 摘要 | 硕士≤800字/1页，博士≤1500字/2页；英文摘要另起一页 |
| 关键词 | 3-5个，与正文空一行顶格，分号隔开 |
| 论文题目 | 一般25字以内 |
| 致谢 | 不超过800字/1页 |
| 参考文献 | 不跨页编排(一条文献不分页)；五号字悬挂缩进 |
| 电子版 | 不得有空白页 |
| 博士→Dissertation | 硕士→Thesis（用于英文封面/扉页/页眉） |
Pipeline Error Triage Tree
当 pipeline 出现故障时，停下来按决策树诊断，不要猜测式修复：
Pipeline 失败
├── Step 1: Pandoc 解析失败?
│ ├── "file not found" → 检查 docx 路径是否正确
│ ├── 解析超时 → docx 可能损坏，要求用户用 Word 另存为
│ └── Pandoc 版本错误 → pandoc --version，需要 3.9+
│
├── Step 2-4: 章节切分异常?
│ ├── 检测到的章节数 < 预期 → Word 标题未使用 Heading 样式
│ │ ├── 正则兜底是否生效？ → 检查 "第X章" 模式
│ │ └── 兜底也失败 → 要求用户提供章节起始位置
│ ├── 摘要/致谢缺失 → NFKC 归一化是否覆盖了该格式的冒号？
│ └── 参考文献数偏差 > 10% → cite_map 策略不匹配，检查 50% 阈值
│
├── Step 5-6: LaTeX 编译失败?
│ ├── "Font not found" → TeX Live 安装不完整 / 字体未挂载
│ ├── "Undefined control sequence" → 公式或特殊命令转换错误
│ │ └── 检查 AST 中对应的 Math/RawInline 节点
│ ├── PDF 文件大小为 0 或未更新 → **PDF 阅读器锁定文件**
│ │ └── 关闭阅读器，或用 --output-dir 指定新目录
│ └── 超过 3 次重试 → 停下来，读 build.log 搜索 "! " 开头的行
│
└── Post-flight 红灯?
├── 封面显示默认值（"作者"/"学院"）→ cover_metadata.json 提取失败
│ └── 检查论文封面布局（表格 vs 段落），确认 fallback 链命中
├── 摘要区出现封面文本 → block stripping 未生效
│ └── 检查 cover_block_indices 和 strip_cover_and_toc_blocks()
├── 页数偏差 > 10 → 章节切分可能丢失大段内容
├── 参考文献 < 90% → cite_map 失败，检查 Word 中的引用格式
├── 缩进不一致 → 检查是否有遗漏的 OrderedList/BulletList
└── 目录显示 "??" → 需要多编译一次（latexmk 通常自动处理）
Anti-Rationalization Table（防借口表）
Agent 常见的跳步借口及反驳。任何情况下都不允许使用这些借口：
| Agent 借口 | 现实 |
|---|
| "PDF 看起来差不多" | "差不多"就是不及格。逐页对比参考 PDF，答辩委员会会注意到 |
| "先交付再修" | 返修等于推倒重来。一次做对，Phase C 红灯禁止交付 |
| "Word 格式太乱了处理不了" | 先跑 AST 探针诊断，90% 的情况有兜底方案（正则/手动标注） |
| "编译警告可以忽略" | 任何 Overfull/Underfull 超过 5 个都要排查原因 |
| "这个格式问题不影响打印" | 电子版 PDF 也是答辩材料，格式瑕疵无法接受 |
| "我改了代码但 PDF 没变化" | 先检查 PDF 是否被阅读器锁定，这是已知坑 |
| "章节少了一章但其他的对" | 章节缺失 = Phase C 红灯 = 禁止交付。定位 Word 标题样式问题 |
| "测试太慢了先跳过" | 没有验证的改动不能 commit。Prove-It Pattern：先测试再交付 |
Anti-patterns
- ❌ NEVER manually copy/paste large blocks of thesis text. Use the extraction script.
- ❌ NEVER rephrase or edit the author's original text. Your job is formatting only.
- ❌ NEVER delete original content to fix compilation errors. Fix the LaTeX markup.
- ❌ NEVER retry compilation more than 3 times. Stop and report after 3 failures.
- ❌ NEVER introduce unapproved LaTeX packages. Check
profile.json.allowed_packages.
- ❌ NEVER assume citation markers exist. Check
thesis_meta.json first.
- ❌ NEVER mix citation systems. Standard uses BibTeX; Marxism uses footnotes.
- ❌ NEVER assume cover data comes from Word tables. STEM theses use paragraph layout — the fallback chain handles both modes automatically.
- ❌ NEVER skip block stripping. Without it, cover text and Word TOC entries leak into abstracts as body text.
- ❌ NEVER use "同上" or "ibid." for repeated citations in Marxism mode.
- ❌ NEVER skip Pre-flight checklist. Confirm assumptions before running pipeline.
- ❌ NEVER deliver with Post-flight red flags. Fix root cause first.
- ❌ NEVER report "已检查" without evidence. Post-flight 每项必须附带截图、日志片段或数值。纯文字"没问题"不算验证。
- ❌ NEVER skip reading this SKILL.md. 你的"经验"不等于这个项目的规则。每次新会话必须重新加载。
- ❌ NEVER skip HARD GATE checkpoints. Phase 3→4 和 Phase 5→6 的门禁不可跳过，即使你"确信"结果正确。
- ❌ NEVER output free-text failure reports. 编译失败后必须使用
templates/failure-report.md 模板输出结构化诊断，不要自由发挥。
- ❌ NEVER declare completion without Definition of Done confirmation. 交付前必须等待用户明确确认。
- ❌ NEVER modify the original .docx without user approval and backup. 热修复原稿属于越权操作，必须先备份、再请求授权。
- ❌ NEVER skip Phase 1.5 Pre-flight Probe. MarkItDown 预检是防止 AST 引擎吃脏数据的最后一道廉价防线。
- ❌ NEVER use
\footnote{} directly inside \caption{}. 必须使用 \caption[短标题]{长标题\footnote{...}} 保护模式，否则编译崩溃 (CASE-A)。
- ❌ NEVER ignore wide tables (≥10 columns) without checking overflow. 默认
\tabcolsep=6pt 可能导致右侧溢出。必要时局部缩小 \tabcolsep (CASE-A)。
- ❌ NEVER use
[htbp] for \begin{table} or \begin{figure}. UESTC 规范 §2.4 要求表格/图片不得跨页漂移。必须使用 [H]（需 \usepackage{float}）强制就地定位。template_adapter.py 已自动注入 float 宏包，pandoc_ast_extract.py 已默认输出 [H] (CASE-A Hotfix)。
- ❌ NEVER assume 1 caption = 1 image file. Word figures 可能在一个 caption 下包含多张并排子图。提取引擎可能只抓取第一张，导致后续所有图片引用全局偏移 +1/+2。必须用 Figure Audit Protocol 逐图与 Word 原文交叉验证 (CASE-A)。
- ❌ NEVER skip per-figure visual verification after image remapping. 即使修复了 N-1 张图，第 N 张仍可能错误（因复合偏移：单图遗漏 → +1，双图遗漏 → +2）。修复后必须逐页渲染验证 (CASE-A)。
- ❌ NEVER 修改客户内容 (C 类) 来掩盖客户原稿瑕疵 (CASE-A round 3, 2026-05-04 决策): 项目本质 = "结构标准化", 不是"内容修改". B 类结构标记(段落 style / Heading / 字体 / 字号 / 封面表格化 / ToC 自动生成) 是 Word 内部技术属性, 客户根本不知道, 我们代做 — 这是项目核心价值. C 类内容文字 (章节标题文字 / 正文 / 摘要 / 致谢字数 / 关键词 / ToC 错别字 / 客户在每章重复写的标题段 / 缺失的公式体 / 错填封面字段) 是客户写的字, 绝不动, 退回客户. 退回硬触发: 致谢字数超 200 / ToC 错别字 / 章正文有重复标题段 / 缺章节内容 / 缺封面必填字段. 写
client_feedback_<round>.md 草稿给客户. D 类损坏 (公式 r:embed 全断链 等 Word 保存 bug) 尽力恢复, 失败也退回. 判断: 改这个会不会动到客户的字 → 会 = C 退回, 不会 = B 代做.
Scripts
scripts/pandoc_ast_extract.py (Primary Engine)
AST-driven extraction engine. Converts Word .docx to structured LaTeX via Pandoc AST parsing.
Usage: python scripts/pandoc_ast_extract.py --input <file.docx> --output-dir <dir/>
Output: outline.json, thesis_meta.json, cover_metadata.json, chapters/ch*.tex,
abstract_zh.tex, abstract_en.tex, acknowledgement.tex, references_raw.txt
Key pipeline stages:
- Pandoc AST Parse — Converts docx → JSON AST via Pandoc
- Chapter Detection — Hybrid Header + regex fallback
- Cover Metadata Extraction — Fallback chain:
- Table mode (for Marxism thesis with Word table covers)
- AST paragraph mode (for STEM thesis with paragraph-based covers + BlockQuote)
- Auto-detects
degree_type from cover text (学士/硕士/博士 → bachelor/master/doctor)
- Degree Type Injection —
run.py reads degree_type from cover_metadata.json and patches \documentclass[<type>]{thesis-uestc} (default: master)
- Cover/TOC Block Stripping — Marks cover and Word-generated TOC blocks as
Null to prevent metadata leakage into abstracts
- Chapter/Abstract/Acknowledgement Generation — Writes individual .tex files
CLS degree options (maps to cover style, header text, inner page behavior):
| Option | 封面标题 | 页眉 | UDC内页 |
|---|
bachelor | 学士学位论文 | 电子科技大学学士学位论文 | 跳过 |
master | 硕士学位论文 | 电子科技大学硕士学位论文 | 生成 |
promaster | 专业学位硕士学位论文 | 电子科技大学硕士学位论文 | 生成 |
doctor | 博士学位论文 | 电子科技大学博士学位论文 | 生成 |
engdoctor | 工程博士学位论文 | 电子科技大学博士学位论文 | 生成 |
scripts/extract_docx.py (Legacy Wrapper)
Calls pandoc_ast_extract.py internally. Kept for backward compatibility.
Usage: python scripts/extract_docx.py --input <file.docx> --output-dir <dir/>
scripts/refs_to_bib.py
Converts Chinese academic references (GB/T 7714 format) to BibTeX. Used in standard profile only.
Usage: python scripts/refs_to_bib.py --input <references_raw.txt> --output <reference.bib>
Output: reference.bib, refs_report.json
scripts/refs_to_footnotes.py ⚡
Converts \cite{key} markers to \footnote{full info} in chapter .tex files. Used in Marxism profile only.
Usage: python scripts/refs_to_footnotes.py
Input: chapter/*.tex + reference.bib (reads from working directory)
Output: modified chapter/*.tex (in-place)
scripts/categorize_refs.py ⚡
Classifies references by type (著作/期刊/学位论文/网页报纸) and generates a categorized LaTeX bibliography. Used in Marxism profile only.
Usage: python scripts/categorize_refs.py
Input: reference.bib or references_raw.txt
Output: bibliography_categorized.tex
scripts/compile.ps1
Wraps Docker-based LaTeX compilation with automatic font mounting.
Usage: powershell scripts/compile.ps1 -ProjectDir <dir> [-MainTex main.tex] [-DockerImage <image>]
Examples
Example 1: Standard UESTC Thesis
Input: "帮我排版这篇论文 C:\Users\xxx\Desktop\论文初稿.docx，用电子科大的模板"
Expected: Agent uses uestc profile, runs Phase 1-6 with BibTeX pipeline.
Example 2: Marxism School Thesis
Input: "排版我的马院论文 D:\thesis\毕业论文.docx"
Expected: Agent detects "马院" → uses uestc-marxism profile, runs footnote + categorized bibliography pipeline.
Example 3: Slash Command
Input: "@/thesis"
Expected: Agent activates this skill and asks: "请提供论文的 Word 文件路径和目标大学模板名称（如需马院格式请注明）。"
Example 4: Bachelor Thesis
Input: "帮我排版本科毕业论文，电子科大的"
Expected: Agent detects "本科" → uses uestc-bachelor profile, runs standard BibTeX pipeline with bachelor-specific checks (外文资料, 0.5bp table lines, 学士学位论文 header).
Example 5: Ambiguous School
Input: "帮我排版论文，电子科大的"
Expected: Agent asks: "请问是本科毕业论文还是研究生学位论文？（当前支持：本科格式、研究生标准格式、马克思主义学院格式）"
