SeraphinaGlacia/ZUFE-Thesis-Skill

ZUFE Thesis Typesetter

總覽

使用此 skill 將 Word 論文轉換為 ZUFE-Thesis LaTeX/PDF 交付物。嚴格按三個流程推進：

• 流程 A：嚴格門禁與智慧預準備。
• 流程 B：DOCX 正式抽取、內容清點帳本、語義確認與模板寫入。
• 流程 C：編譯、診斷、品檢與交付說明。

面向非技術使用者的主要反饋必須在對話中給出。腳本負責穩定檢查、抽取、檔案寫入、編譯和生成機器可讀證據。

核心契約

必須從 ZUFE-Thesis 模板根目錄執行。修改任何檔案前，先確 templates 簽名完整。

如果使用者尚未準備模板專案，先說明本 Skill 依賴原始 ZUFE-Thesis LaTeX 模板，並按下面順序處理：

1. 預設引導使用者使用原始模板 GitHub 儲存庫：https://github.com/sqsssq/ZUFE-Thesis。
2. 如果 GitHub 因網路環境不可用，可在使用者確認後改用國內備用連結：https://gitee.com/cwf818/ZUFE-Thesis。
3. 如果 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

流程順序

按順序執行流程，不要因為後續腳本可能補救而跳過門禁。

1. 流程 A：檢查模板、workspace、DOCX、metadata、舊輸出、Python DOCX 環境、LaTeX/Biber 環境。
2. 流程 B：把 Word 每個可見或可抽取內容區塊寫入 thesis.json；Agent 負責分配語義槽位並向使用者確認低置信度內容；腳本只渲染已確認映射。
3. 流程 C：歸檔舊編譯產物，執行 xelatex -> biber -> xelatex -> xelatex，診斷失敗，做有限機械修復，並品檢新 PDF。

腳本使用

所有腳本接受 --root，並輸出 JSON 或寫入 JSON 報告。Agent 使用 JSON 做判斷，再把結果翻譯成一般使用者能理解的簡短清單。

• scripts/check_template.py：檢查 ZUFE-Thesis 模板簽名。
• scripts/prepare_workspace.py：建立 workspace/，把 DOCX 放到標準路徑，並可在使用者核准後歸檔舊輸出。
• scripts/check_env.py：檢查 Python、python-docx、xelatex、biber 和模板關鍵 TeX 套件。
• scripts/prescan_docx.py：流程 A 的 DOCX 輕量預掃描和 metadata 候選提取。不得產生正式 thesis.json。
• scripts/import_docx.py：流程 B 正式抽取，產生 thesis.json 和 extracted.md。
• 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：把已確認 BibTeX 寫入 Reference.bib，不得編造參考文獻。
• scripts/check_flow_b_gate.py：若仍有未處理、未確認或未渲染源區塊，則阻止流程 B 完成。
• scripts/build.py：歸檔舊 main.pdf，清理臨時編譯檔案，執行固定編譯鏈。
• scripts/diagnose_build.py：把構建失敗分類為可行動問題。
• scripts/qa.py：檢查 PDF 新鮮度、文字、關鍵訊號、未解析引用、BibTeX/引用閉環、模板殘留和佔位符。

Agent 職責

Agent 負責語義判斷，腳本不得替代：

• 判斷段落屬於章節標題、正文、摘要、參考文獻、致謝、附錄、圖表標題或可丟棄雜訊。
• 歸併低置信度問題，並向使用者確認。
• 在對話中解釋卡住的位置、原因和下一步。
• 不靜默丟棄內容，不靜默錯放內容。
• 不從檔案名稱猜測學院、專業、日期、指導教授或報告類型；metadata 只能來自 Word 證據或使用者確認。
• 不把 run 級樣式問題當成一般文字問題忽略；上標、下標、表格字號異常都必須在流程 B/C 暴露。
• 流程 C 不修正文件語義；內容歸屬錯誤必須退回流程 B。

轉換品質硬約束

• 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 中顯示彩色連結邊框。
• 表格預設使用模板風格字號 \zihao{5}。不得無條件使用 \resizebox{\textwidth}{!}{...}，因為它會把較窄表格放大並破壞字號。
• 只有表格自然寬度確實超過版心且沒有更穩妥的列寬方案時，才允許縮小表格；禁止為了「填滿版心」放大表格。
• 腳註、尾註、公式、超連結、批註、修訂痕跡、文字方塊、頁首頁尾等暫不自動轉換內容必須進入 unsupported_features，不得靜默忽略。

詳細參考

• 做流程 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。

使用者反饋

非技術使用者不需要先開啟報告。先在對話中給出：

• 門禁卡在哪裡。
• 為什麼繼續會不安全。
• Agent 可以自動修什麼。
• 哪些操作需要使用者核准或提供檔案。

技術使用者需要細節時，再補充報告路徑。