latex-validate

name	latex-validate
description	編譯 LaTeX 專案後跑完整 layout 驗證流程 — detect_layout_issues + find_overlaps + fonts_check + box_warnings。當用戶說「驗證 LaTeX」「檢查排版」「掃 layout 問題」「LaTeX 編完看看有沒有 bug」「latex audit」或在 LaTeX 專案目錄編譯後想自動 audit 時使用。也適用於 commit 前驗證、release 前 audit、暑校稿 batch 修完想知道剩餘 issue。

LaTeX Validate

編譯後完整 layout 驗證流程：把 6 個 detector tool 串成一條 audit pipeline，產生整理過的 issue 報告。

Trigger

用戶說：

• 「驗證 LaTeX」「LaTeX audit」「掃排版問題」
• 「編完看看有沒有 bug」「commit 前檢查」
• 「跑完整檢查」
• 直接 /latex-validate

或 implicit 場景：

• 剛跑完 compile_latex / latexmk make
• batch 修了多處 .tex 後（多輪 Edit）
• release / publish 前

Workflow

依序執行（用 mcp__plugin_che-latex-mcp_che-latex-mcp__<tool> 命名空間）：

Step 1: 確認 PDF 存在

如果用戶沒指定 project_path + main_file，問清楚或從 cwd 推斷。確認 PDF 已編譯出來，沒有的話先 compile_latex 一次。

Step 2: source-level 預檢查

fonts_check(project_path, main_file)     # .log 字型缺字
box_warnings(project_path, main_file)    # overfull/underfull box

這兩個從 .log 抓，速度極快（< 100ms），先跑。

Step 3: PDF-level 視覺檢查

detect_layout_issues(pdf_path, page_range?)
# → widow heading / empty page / bottom gap / overlap 一次抓完

這是主力 detector。報告會分四類列出問題 page 跟原因。

Step 4: 重疊細查（如果 detect 報告 overlap）

find_overlaps(pdf_path, problematic_pages, threshold=4.0)
# → 對問題頁面逐 block 列出重疊位置 + 文字 excerpt

只對 Step 3 報的 overlap pages 跑，不必整本。

Step 5: 整理 + 提出修法建議

收到 4 個 tool report 後，不要直接 dump 給用戶。整理成：

## LaTeX 排版 audit 報告（main.pdf，N 頁）

### ⚠️ Critical（必須修）
- p.X: widow heading「⋯⋯」← 加 \needspace 或 \clearpage
- p.Y: block overlap 12.4 pt² ← tikz layout 衝突或字型 ghost

### ⚠️ Warning（建議修）
- p.Z: 留白 65% ← 可能過度 \clearpage，檢查 line N
- 字型缺字 ⋯ 3 個（U+22EF / Times New Roman）← 改 \dots

### ✅ Pass
- 標點符號（如果跑了 punct_check）
- overfull box（如果 box_warnings 通過）

對每個 issue 給 具體 修法建議（哪個 LaTeX 指令 / 哪行加 needspace），不要泛泛說「請調整」。

注意事項

• 不要對 reading section / appendix 過度報警：那些 section 通常排版較鬆，留白比例高是正常。可以在報告中標明「（reading section）」加註。
• widow heading 誤報：tikz 流程圖、章標題前後常有短 block 但不是真的 widow heading。看 Step 4 找 block 文字確認。
• threshold 調整：find_overlaps 預設 threshold=4 pt²，數學環境會有偽陽性。如果偽陽性多，調 threshold=50 只看明顯重疊。