| name | latex-visual-diff |
| description | 改動 LaTeX source 後做視覺 diff，知道改動影響哪幾頁 — 用 compile_diff(git_ref) 自動 checkout + compile + compare，或用 compare_pdfs 比兩個既存 PDF。當用戶說「視覺 diff」「比較改動前後」「我改了 X 影響哪幾頁」「跟上一版比」「visual regression」時使用。也適用於 batch 修完想驗證、release 前 ripple 檢查。 |
LaTeX Visual Diff
「改完不知道影響哪幾頁」是 LaTeX batch 修最大的 friction。這個 skill 把「改動 → 視覺 attribution」壓縮成單一 tool call。
Trigger
用戶說：
- 「視覺 diff」「visual diff」「跟上版比」
- 「我改了 X 影響哪幾頁」「ripple 檢查」
- 「比較 PDF」「compare pdfs」
- 直接
/latex-visual-diff
或 implicit 場景：
- 用戶剛 batch Edit 多處 .tex
- 用戶說「不確定改動範圍」
- commit / push 前驗證沒 collateral damage
兩種模式
模式 A：git ref 對照（最常用）
用戶想看「跟某個 commit 比改了什麼」。
compile_diff(
project_path,
main_file?, # 預設 main
engine?, # 預設 xelatex
git_ref, # HEAD~1（預設）/ HEAD~3 / branch-name / commit-sha
page_range?,
output_dir? # 預設 /tmp/latex_diff
)
工具會：
git worktree add 把 ref checkout 到暫存目錄- 在那邊跑 latexmk 編出 baseline PDF
- 跟當前 PDF 做 pixel-level diff（紅色高亮變動區）
- 回傳影響 page list + 每頁 diff PNG path
- 自動清掉 worktree
前置條件：當前 PDF 必須已編譯（current branch 的 main.pdf 存在）。如果還沒，先跑 compile_latex 再 call 這個。
模式 B：兩個既存 PDF 直接比（手動 baseline）
用戶手動保存 baseline PDF，或要比兩個 release 版本。
compare_pdfs(
before_pdf, # baseline PDF path
after_pdf, # current PDF path
page_range?,
output_dir?,
save_diff_images? # 預設 true
)
Workflow
Step 1: 判斷模式
問用戶或從 context 推斷：
- 有 git ref → 模式 A
- 有兩個 PDF path → 模式 B
- 都沒有 → 預設模式 A，git_ref = HEAD~1
Step 2: 跑 diff
call 對應的 tool。等 30 秒 - 2 分鐘（baseline 編譯需要時間）。
Step 3: 結果整理
工具回傳的是「哪幾頁變了 + diff PNG path」。不要直接 dump 整 list 給用戶，而是：
- 分群：把連續頁面 group（p.78-82 是同一段改動的 ripple；p.187 是另一處）
- attribute：根據改動的 .tex source（從 git diff 推），猜每群對應哪個改動
- flag 意外：如果 user 只改了 ch04 但 ch07 也有頁面變了，highlight 為「意外 ripple」要 user 注意
範例輸出：
## 視覺 diff: HEAD~1 → 當前
改動的 .tex 檔案（從 git diff）：
- 02_暑期班/part1_心理測驗/ch04_信度/ch04.tex
- 02_暑期班/00_common/commands.tex
### 影響頁面（共 6 頁）
**Group 1 — ch04 信度（4 頁，預期內）**
- p.66, 67, 69, 71: 2-15% 像素改變
- 對應改動：ch04 Cohen κ vocabbox + ICC vocabbox
- diff PNG: /tmp/latex_diff/diff_p66.png ⋯⋯
**Group 2 — ch10（2 頁，⚠️ 意外 ripple）**
- p.185, 186: 0.5% 像素改變
- 對應改動：commands.tex examitem env 改了 → 影響所有 examitem 渲染
- diff PNG: /tmp/latex_diff/diff_p185.png
- 建議：抽一頁 visual check 確認 examitem 改動 OK
注意事項
compile_diff 需要 git repo：如果 project 不在 git 內，會 error，改用 compare_pdfs + 手動 baseline- git_ref 必須能編譯：如果該 ref 的 source 本身有編譯錯誤，baseline 跑不出來。換 ref 或先修 source
- 巨大 ripple 警訊：如果 100+ 頁都改了，通常是改了 commands.tex / preamble.tex 這類底層檔案，視覺改變是 expected 但量大要花時間 review
- diff PNG 不要全載入 context：選 2-3 個代表性頁面 Read PNG，其他列 path 不載入
