SeraphinaGlacia/ZUFE-Thesis-Skill

ZUFE Thesis Typesetter

Overview

Use this skill to convert a Word thesis into a ZUFE-Thesis LaTeX/PDF deliverable. Proceed strictly through three flows:

• Flow A: Strict gatekeeping and intelligent preparation.
• Flow B: Formal DOCX extraction, content ledger, semantic confirmation, and template writing.
• Flow C: Compilation, diagnosis, quality check, and delivery notes.

Primary feedback for non-technical users must be given in the conversation. Scripts handle stable checking, extraction, file writing, compilation, and generating machine-readable evidence.

Core Contract

Must run from the ZUFE-Thesis template root directory. Before modifying any file, first verify the template signature is intact.

If the user has not yet prepared the template project, explain that this Skill depends on the original ZUFE-Thesis LaTeX template, and proceed in the following order:

1. Default: guide the user to use the original template GitHub repository: https://github.com/sqsssq/ZUFE-Thesis.
2. If GitHub is unavailable due to network conditions, and after user confirmation, switch to the domestic backup link: https://gitee.com/cwf818/ZUFE-Thesis.
3. If both GitHub and Gitee are unavailable, stop the conversion and ask the user to provide a template archive, a fully extracted template directory, or another trusted means of acquisition.

The Agent may assist with downloading, extracting, or navigating to the template root directory after user confirmation, but must not silently skip template preparation, nor continue conversion in an empty directory, the Skill repository directory, or a directory missing the template signature.

Standard Input:

workspace/input/thesis.docx
workspace/input/metadata.yaml

Standard Intermediate Artifacts:

workspace/intermediate/thesis.json
workspace/intermediate/extracted.md

Standard Output:

main.pdf
workspace/output/report.md
workspace/output/qa_report.md

Flow Sequence

Run flows in order; do not skip gatekeeping because a later script might compensate.

1. Flow A: Check template, workspace, DOCX, metadata, old output, Python DOCX environment, LaTeX/Biber environment.
2. Flow B: Write each visible or extractable content block from Word into thesis.json; Agent is responsible for assigning semantic slots and confirming low-confidence content with the user; scripts only render confirmed mappings.
3. Flow C: Archive old compilation artifacts, run xelatex -> biber -> xelatex -> xelatex, diagnose failures, perform limited mechanical fixes, and QA the new PDF.

Script Usage

All scripts accept --root and output JSON or write JSON reports. The Agent uses JSON for decisions, then translates results into a short list understandable to regular users.

• scripts/check_template.py: Check ZUFE-Thesis template signature.
• scripts/prepare_workspace.py: Create workspace/, place the DOCX in the standard path, and optionally archive old output after user approval.
• scripts/check_env.py: Check Python, python-docx, xelatex, biber, and key template TeX packages.
• scripts/prescan_docx.py: Lightweight pre-scan of DOCX and metadata candidate extraction for Flow A. Must not generate a formal thesis.json.
• scripts/import_docx.py: Formal extraction for Flow B, generating thesis.json and extracted.md.
• scripts/export_assets.py: Extract DOCX media to Images/word_media/ and record evidence.
• scripts/render_basicinfo.py: Write metadata, abstract, and keywords into chapters/basicinfo.tex.
• scripts/render_chapters.py: Write confirmed chapter mappings into chapters/*.tex and chapters/mainbody.tex.
• scripts/render_bib.py: Write confirmed BibTeX into Reference.bib; do not fabricate references.
• scripts/check_flow_b_gate.py: Prevent Flow B from completing if there are unprocessed, unconfirmed, or unrendered source blocks.
• scripts/build.py: Archive old main.pdf, clean temporary compilation files, and run the fixed compilation chain.
• scripts/diagnose_build.py: Classify build failures as actionable issues.
• scripts/qa.py: Check PDF freshness, text, key signals, unresolved references, BibTeX/reference closure, template remnants, and placeholders.

Agent Responsibilities

The Agent is responsible for semantic judgments; scripts must not substitute:

• Judge whether a paragraph is a section heading, body text, abstract, reference, acknowledgment, appendix, figure/table caption, or discardable noise.
• Consolidate low-confidence issues and confirm with the user.
• Explain in the conversation what is stuck, why, and what to do next.
• Do not silently discard content or misplace content.
• Do not guess college, major, date, advisor, or report type from file names; metadata can only come from Word evidence or user confirmation.
• Do not ignore run-level style issues as ordinary text issues; superscript, subscript, or abnormal table font sizes must be exposed in Flow B/C.
• Flow C must not fix document semantics; content attribution errors must be returned to Flow B.

Conversion Quality Hard Constraints

• DOCX paragraphs must not retain only plain text; run-level bold, italic, superscript, subscript, and font size evidence must be preserved. Superscript numbers must be rendered as \textsuperscript{...}, not flattened into normal text numbers.
• Superscript numbers in Word that appear to be reference markers must not be silently rewritten as plain text. To convert them into formal \cite/\supercite, the reference mapping must first be confirmed; otherwise, at least keep the visual superscript.
• Handwritten figure/table numbers in Word body text, such as 图2.1, 图 2.1, 表1.2, must not be carried verbatim into final chapter source code. The Agent must confirm the corresponding figure/table block, write a stable label for the figure/table, and rewrite the body text as 图~\ref{...} or 表~\ref{...}; if confirmation is not possible, block Flow B.
• ASCII double quotes in ordinary body text must be converted to LaTeX left/right quotes ``...''; Chinese smart quotes are retained by default. Do not apply body text quote conversion to raw LaTeX, image paths, citation commands, or formulas.
• If English abstract or English keywords are missing, the user must choose: confirm to leave blank, provide manually, or allow generation; must not default to blank or automatically fill based on Chinese. If the user allows generation, first explain this is a content-level supplement, and record the authorization in metadata.
• When generating chapters/basicinfo.tex, the global \hypersetup{hidelinks,pdfborder={0 0 0},pdfborderstyle={/S/U/W 0}} must be written to avoid displaying colored link borders for figure/table references and URLs in the PDF.
• Tables default to the template style font size \zihao{5}. Must not unconditionally use \resizebox{\textwidth}{!}{...}, as it will enlarge narrow tables and break font size.
• Shrinking tables is only allowed when the table's natural width indeed exceeds the text width and there is no more stable column width solution; enlarging tables to "fill the text width" is prohibited.
• Content not automatically converted (footnotes, endnotes, formulas, hyperlinks, comments, revision marks, text boxes, headers/footers) must be entered into unsupported_features and not silently ignored.

Detailed References

• Before doing Flow A, read references/flow-a-gatekeeping.md.
• Before doing environment checks or fixes, read references/environment-sop.md.
• Only when platform commands, installation details, PATH fixes, or TeX package additions are needed, read references/environment-setup-and-repair.md.
• Before doing Flow B extraction or rendering, read references/flow-b-conversion.md.
• Before doing Flow C compilation or QA, read references/flow-c-export-and-qa.md.
• Before manually editing thesis.json, read references/thesis-json-schema.md.

User Feedback

Non-technical users do not need to open reports first. Give feedback in the conversation:

• What is blocking the gatekeeping.
• Why continuing would be unsafe.
• What the Agent can fix automatically.
• Which actions require user approval or file provision.

When technical users need details, supplement with the report path.