ZUFE Thesis Typesetter
总览
使用此 Skill 将 Word 论文转换为 ZUFE-Thesis LaTeX/PDF 交付物。严格按三个流程推进：
- 流程 A：严格门禁与智能预准备。
- 流程 B：DOCX 正式抽取、内容清点账本、语义确认与模板写入。
- 流程 C：编译、诊断、质检与交付说明。
面向非技术用户的主要反馈必须在对话中给出。脚本负责稳定检查、抽取、文件写入、编译和生成机器可读证据。
核心契约
必须从 ZUFE-Thesis 模板根目录运行。修改任何文件前，先确认模板签名、身份版本和渲染器依赖接口满足兼容性门禁。
如果用户尚未准备模板项目，先说明本 Skill 依赖原始 ZUFE-Thesis LaTeX 模板，并按下面顺序处理：
- 默认引导用户使用原始模板 GitHub 仓库：
https://github.com/sqsssq/ZUFE-Thesis。 - 如果 GitHub 因网络环境不可用，可在用户确认后改用国内备用链接：
https://gitee.com/cwf818/ZUFE-Thesis。 - 如果 GitHub 和 Gitee 都不可用，停止转换，要求用户提供模板压缩包、已解压的完整模板目录，或其他可信获取方式。
Agent 可以在用户确认后协助下载、解压或切换到模板根目录，但不得静默跳过模板准备，也不得在空目录、本 Skill 仓库或缺失模板签名的目录中继续转换。
标准输入：
workspace/input/thesis.docx
workspace/input/metadata.yaml
标准中间产物：
workspace/intermediate/thesis.json
workspace/intermediate/extracted.md
标准输出：
main.pdf
workspace/output/report.md
workspace/output/qa_report.md
流程顺序
按顺序运行流程，不要因为后续脚本可能补救而跳过门禁。
- 流程 A：检查模板、workspace、DOCX、metadata、旧输出、Python DOCX 环境、LaTeX/Biber 环境。
- 流程 B：把 Word 每个可见或可抽取内容块写入
thesis.json；Agent 负责分配语义槽位并向用户确认低置信度内容；脚本只渲染已确认映射。 - 流程 C：再次确认流程 B 门禁和输入指纹，归档旧编译产物，运行
xelatex -> biber -> xelatex -> xelatex，诊断失败，做有限机械修复，并质检新 PDF。
详细参考（references/）
- 做流程 A 前，读取
references/flow-a-gatekeeping.md。 - 做环境判断或修复时，先读取
references/environment-sop.md。 - 只有需要平台命令、安装细节、PATH 修复或 TeX 包补装时，才读取
references/environment-setup-and-repair.md。 - 做流程 B 抽取或渲染前，读取
references/flow-b-conversion.md。 - 做流程 C 编译或 QA 前，读取
references/flow-c-export-and-qa.md。 - 手动编辑
thesis.json前，读取references/thesis-json-schema.md。
脚本使用（scripts/）
所有可执行脚本接受 --root，并输出 JSON 或写入 JSON 报告。先以当前已加载的 SKILL.md 所在目录作为 Skill 根目录，从该目录解析 scripts/，再把完整的 ZUFE-Thesis 模板根目录传给 --root；不要假定 Skill 文件夹位于模板工作区内。高数据量命令的 stdout 只给有界摘要和完整报告路径；Agent 先读摘要，只在需要具体证据时分页查询或读取报告。正常执行优先使用已文档化的 CLI，只有调试或维护脚本时才读取源码。
scripts/check_template.py：检查 ZUFE-Thesis 模板文件、身份版本和渲染器依赖接口；只有用户明确确认后，才可用--confirm-compatible-template接受接口完整但未列入验证范围的版本。scripts/prepare_workspace.py：创建workspace/，把 DOCX 放到标准路径，并可在用户批准后归档旧输出。scripts/check_env.py：按--stage检查 Python、python-docx、xelatex、biber、模板关键 TeX 包和 QA 工具；从--root识别依赖管理方式，模板属于其他依赖工作区时显式加--project-root。先选目标项目的现有解释器，不为诊断同步或重建环境；缺 pip 本身不阻塞。它不替代模板签名或 DOCX 可读性检查。scripts/prescan_docx.py：流程 A 的 DOCX 轻量预扫描和 metadata 候选提取。不得生成正式thesis.json。scripts/import_docx.py：流程 B 正式抽取，按原文顺序记录普通 run、可转换的超链接、脚注和原生 OMML 公式，并生成thesis.json和extracted.md。scripts/ledger.py：只读汇总、分页查询源块并生成带前后文的标题候选大纲；不得用它绕过 Agent 的语义判断。scripts/export_assets.py：核对源 DOCX 指纹后，抽取媒体到Images/word_media/并记录证据。scripts/render_basicinfo.py：把 metadata、摘要和关键词写入chapters/basicinfo.tex。scripts/render_chapters.py：在拒绝重复章节目标、无效图片资源和未决内联语义后，把已确认章节映射写入chapters/*.tex和chapters/mainbody.tex。scripts/render_bib.py：只有所有参考文献项均已确认时才原子写入Reference.bib，不得编造或部分覆盖参考文献。scripts/check_flow_b_gate.py：若仍有未处理、未确认或未渲染源块，则阻止流程 B 完成。scripts/build.py：强制重跑流程 B 门禁，通过后才归档旧main.pdf、清理临时文件并运行固定编译链。scripts/diagnose_build.py：把构建失败分类为可行动问题。scripts/qa.py：核对构建所用账本与当前输入，再检查固定编译链、PDF 新鲜度、文本、关键信号、引用、模板残留和占位符；通过后仍须人工视觉检查。
Agent 职责
Agent 负责语义判断，脚本不得替代：
- 判断段落属于章节标题、正文、摘要、参考文献、致谢、附录、图表标题或可丢弃噪声。
- 归并低置信度问题，并向用户确认。
- 在对话中解释卡住的位置、原因和下一步。
- 不静默丢弃内容，不静默错放内容。
- 不从文件名猜测学院、专业、日期、导师或报告类型；metadata 只能来自 Word 证据或用户确认。
- 不把 run 级样式问题当成普通文本问题忽略；上标、下标、表格字号异常都必须在流程 B/C 暴露。
- 流程 C 不修正文档语义；内容归属错误必须退回流程 B。
- 排版默认采用 preserve-first：先以原文样式、顺序和上下级关系表达的结构意图为基线，再通读全文形成完整候选大纲；不能仅凭段落样式、编号外观或局部上下文逐段猜测标题及其层级。
- 若要把正文升格为标题、把标题降格为正文、改变标题层级所表达的章节从属，或将内容移入不同章节，必须在
confirmation.note记录原始证据、调整理由和用户确认；没有充分证据时保留原结构并说明歧义。 - 对每个标题判断它是否属于真正的文章结构，并检查上下级关系、同级并列关系和出现顺序是否连贯；脚本候选、Word 样式和原文编号只能提供线索，不能替代语义判断。
- 区分标题正文与原文手写编号。确认
第一章、1.1、一、等内容只是人工编号后，从最终标题文字中去除，只保留标题正文，再由 LaTeX 按已经确认的层级自动编号；不得让原文编号与 LaTeX 编号同时出现。去除已确认的手写编号属于排版规范化，不等同于擅自改写文章结构；编号性质仍有歧义时必须确认。
转换质量硬约束
- DOCX 段落不得只保留纯文本；必须保留 run 级
bold、italic、superscript、subscript和字号证据。上标数字必须渲染为\textsuperscript{...}，不得压平成正文普通数字。 - Word 中疑似参考标号的上标数字不得静默改写成普通文本。若要转为正式
\cite/\supercite，必须先确认参考文献映射；否则至少保留视觉上标。 - Word 正文中的手写图表编号，例如
图2.1、图 2.1、表1.2，不得原样带入最终章节源码。Agent 必须确认它对应的图表块，给图表写入稳定label，并把正文改写为图~\ref{...}或表~\ref{...}；无法确认时阻塞流程 B。 - 普通正文中的 ASCII 双引号必须转换为 LaTeX 左右引号 ``...''；中文智能引号默认保留。不得对 raw LaTeX、图片路径、引用命令和公式套用正文引号转换。
- 缺失英文摘要或英文关键词时，必须让用户选择：确认留空、手动提供或允许生成；不得默认留空或自动根据中文补写。若用户允许生成，必须先说明这是内容性补写，并在 metadata 中记录授权。
- 生成
chapters/basicinfo.tex时必须写入全局\hypersetup{hidelinks,pdfborder={0 0 0},pdfborderstyle={/S/U/W 0}}，避免图表引用和 URL 在 PDF 中显示彩色链接边框。 - 映射到
chapters/basicinfo.tex的源块必须声明metadata_fields，且脚本必须核对整个源块都有去向；不能被宏承接的文字须改映射，或用metadata_excluded_text和metadata_exclusion_reason显式记录。 - 表格默认使用模板风格字号
\zihao{5}。不得无条件使用\resizebox{\textwidth}{!}{...}，因为它会把较窄表格放大并破坏字号。 - 只有表格自然宽度确实超过版心且没有更稳妥的列宽方案时，才允许缩小表格；禁止为了“填满版心”放大表格。
- Word 中目标明确的
http/https/mailto外部超链接、仅含可承接内联内容的普通脚注，以及公式编辑器生成且当前转换器能够完整识别的原生 OMML 公式，必须按原文顺序保留并渲染；不能完整转换时必须进入unsupported_features，不得只保留可见文本或静默忽略。 - 尾注、内部书签跳转、表格单元格脚注、未知 OMML 结构、图片/墨迹公式、MathType/OLE 对象，以及批注、修订痕迹、文本框、内容控件、外部导入内容、链接图片、Word 域/自动编号、图表/SmartArt 和页眉页脚等仍属于显式边界。Agent 必须核对公式语义和最终 PDF，自动转换成功不等于已经证明复杂公式与源 Word 视觉一致。
踩坑清单
- 标题编号重复与层级误判：这是全文语义理解问题，不能交给正则或其他机械规则裁决。Agent 必须先结合全文内容、标题候选及其前后文重新整理文章结构，统一确认哪些内容是真正的标题以及各自层级，再识别并去除标题中已有的手写编号。写入 LaTeX 后，还要复核最终大纲和编号是否连续、是否与文章逻辑一致；仍有歧义时向用户确认。
- 图片题注误填：图片媒体路径和源块摘要不得自动充当图题；
caption只能来自 Word 证据或 Agent/用户确认。 - 引用类型误判：
reference_rewrites必须显式写入target_kind或prefix；类型缺失时不得默认按图片引用生成图~\ref{...}。
人机协作
非技术用户不需要先打开报告。先在对话中给出：
- 门禁卡在哪里。
- 为什么继续会不安全。
- Agent 可以自动修什么。
- 哪些操作需要用户批准或提供文件。
技术用户需要细节时，再补充报告路径。
